README
jeezy
JavaScript. Easy.
jeezy is a JavaScript library for manipulating data. It provides lots of useful functions and has no dependencies, so it won't add a lot of code to your project.
Installation
npm
npm install jeezy --save
var jz = require("jeezy");
Web browser
In vanilla, a jz global is exported. You can use the CDN from unpkg.
<script src="https://unpkg.com/jeezy@1.13.1/lib/jeezy.js"></script>
<script src="https://unpkg.com/jeezy@1.13.1/lib/jeezy.min.js"></script>
If you'd rather host it yourself, download jeezy.js or jeezy.min.js from the lib directory.
<script src="path/to/jeezy.js"></script>
<script src="path/to/jeezy.min.js"></script>
Usage
Arrays
Javascript has many built-in methods for manipulating arrays. These functions are meant to supplement those.
Numbers
Javascript has many built-in methods for manipulating numbers. These functions are meant to supplement those.
Strings
Javascript has many built-in methods for manipulating strings. These functions are meant to supplement those.
Arrays: Math
Functions for doing math with arrays of numbers.
# jz.arr.average(array)
Returns the average of an array of numbers.
# jz.arr.correlationMatrix(data, columns)
Given a data set (an array of objects) and a list of columns (an array with a list of numeric columns), calculate the Pearson correlation coeffient for each pair of columns and return a correlation matrix, which is an array of objects where each object takes the form {column_x: String, column_y: String, correlation: Number}. Demo
# jz.arr.extent(array)
Returns the minimum and maximum values of an array of numbers as the array [min, max].
# jz.arr.max(array)
Returns the maximum value of an array of numbers.
# jz.arr.median(array)
Returns the median of an array of numbers.
# jz.arr.min(array)
Returns the minimum value of an array of numbers.
# jz.arr.sum(array)
Returns the sum of an array of numbers.
Arrays: Queries
Functions for testing arrays for certain properties. Return booleans.
# jz.arr.is(array)
Tests whether an element is an array. Returns true or false.
Arrays: Transformations
Functions for transforming arrays.
# jz.arr.columnsToValues(array)
Expands a two-dimensional array of objects in which the column names contain values.
var data = [{year: 2015, Bob: 6, Steve: 10}, {year: 2016, Bob: 7, Steve: 12}, {year: 2017, Bob: 4, Steve: 16}];
data = jz.arr.columnsToValues(data);
/*
[ { year: 2015, column: "Bob", value: 6 },
{ year: 2016, column: "Bob", value: 7 },
{ year: 2017, column: "Bob", value: 4 },
{ year: 2015, column: "Steve", value: 10 },
{ year: 2016, column: "Steve", value: 12 },
{ year: 2017, column: "Steve", value: 16 } ]
*/
jz.arr.renameProperty(data, {in: "column", out: "first_name"});
# jz.arr.flatten(array)
Flattens an array of arrays into a single array.
var arrays = [[1],[2],[3]];
jz.arr.flatten(arrays); // [1, 2, 3]
# jz.arr.merge(array1, array2, property)
Merges two arrays of objects on a specified property. Keeps each object of the first array, and adds the matching properties of the first matched object in the second array.
# jz.arr.pivot(array, string)
Pivots an array of objects around the unique values of an attribute. Returns the unique values and the count of how many times each appears in the original array.
var json = [ { value: 1 }, { value: 2 }, { value: 3 }, { value: 1 }, { value: 2 } ];
jz.arr.pivot(json, "value"); // [ { value: 1, count: 2 }, { value: 2, count: 2 }, { value: 3, count: 1 } ]
# jz.arr.pluck(array, string)
Returns all the values of a specified attribute or mapping function from an array of objects.
var json = [ { value: 1 }, { value: 2 }, { value: 3 }, { value: 1 }, { value: 2 } ];
jz.arr.pluck(json, "value"); // [1, 2, 3, 1, 2]
jz.arr.pluck(json, function(d){ return d.value + 1; }); // [2, 3, 4, 2, 3]
# jz.arr.propertyToNumber(data, string OR array of strings [, coerce function])
Coerces the type of a property to a number in every object in an array of objects. The second argument can be a string with a single property name, or an array of strings with one or more property names.
By default, non-numeric values will be converted to NaN. But you can pass an optional third argument – a coerce function to decide how to deal with non-numeric values. However, if the function you pass returns a non-numeric value, that value will itself be coerced to NaN.
Examples of coerce functions are:
function(d){ return jz.str.keepNumber(d); }
function(d){ return 0; }
# jz.arr.removeItem(array, item)
Removes an item from an array, and returns the array.
# jz.arr.removeProperty(array, property string OR array of property strings)
Removes a property or properties from every object in an array of objects. The second argument can be a string or, if you want to remove multiple properties, an array of strings.
var json = [ { value: 1, name: "Bob", age: 30 }, { value: 2, name: "Steve", age: 23 }, { value: 3, name: "John", age: 40 }, { value: 1, name: "Tim", age: 6 }, { value: 2, name: "Jake", age: 92 } ];
jz.arr.removeProperty(json, "age"); // [ { value: 1, name: "Bob" }, { value: 2, name: "Steve" }, { value: 3, name: "John" }, { value: 1, name: "Tim" }, { value: 2, name: "Jake" } ]
jz.arr.removeProperty(json, ["value", "age"]); // [ { name: "Bob" }, { name: "Steve" }, { name: "John" }, { name: "Tim" }, { name: "Jake" } ]
# jz.arr.renameProperty(array, renamer)
Renames a property or properties in every object of an array of objects. You must pass a "renamer" as the second argument. If you are only renaming one property, the renamer can be an object with the properties "in", the value of which is a string with the input property name, and "out", the value of which is a string with the output property name. If you are renaming multiple properties, the renamer can be an array of objects, where each object has the "in" and "out" properties of the single renamer.
var json = [ { value: 1, name: "Bob", age: 30 }, { value: 2, name: "Steve", age: 23 } ];
jz.arr.renameProperty(json, {in: "value", out: "number"}) // [ { number: 1, name: "Bob", age: 30 }, { number: 2, name: "Steve", age: 23 } ];
jz.arr.renameProperty(json, [{in: "value", out: "number"}, {in: "age", out: "shoes"}]); // [ { number: 1, name: "Bob", shoes: 30 }, { number: 2, name: "Steve", shoes: 23 } ];
# jz.arr.shuffle(array)
Shuffles an array.
# jz.arr.sortBy(array[, order])
Sorts an array of objects by the values of an attribute. The attribute can be either a string representing a property in each object, or an accessor modifying each object. You can specify the order of the sort as descending or ascending by using "desc" or "asc" as the optional third argument. If there is no third argument, the sort order defaults to ascending.
var json = [ { value: "a", count: 2 }, { value: "b", count: 2 }, { value: "c", count: 1 } ]
jz.arr.sortBy(json, "count"); // [ { value: "c", count: 1 }, { value: "a", count: 2 }, { value: "b", count: 2 } ]
jz.arr.sortBy(json, "count", "asc"); // [ { value: "c", count: 1 }, { value: "a", count: 2 }, { value: "b", count: 2 } ]
jz.arr.sortBy(json, "count", "desc"); // [ { value: "b", count: 2 }, { value: "a", count: 2 }, { value: "c", count: 1 } ]
# jz.arr.sortNumbers(array[, order])
Sorts an array of numbers in ascending order by default. For descending order, pass "desc" as order.
# jz.arr.unique(array)
Returns unique values of an array.
# jz.arr.uniqueBy(array, string)
Returns an array of unique values of an object property or mapping function in an array of objects.
var json = [ { value: 1, name: "Bob", age: 6}, { value: 2, name: "Steve", age: 6}, { value: 3, name: "John", age: 6}, { value: 1, name: "Tim", age: 23}, { value: 2, name: "Jake", age: 30}, { value: 3, name: "John", age: 40}, { value: 1, name: "Tim", age: 92} ];
jz.arr.uniqueBy(json, "age"); // [ 6, 23, 30, 40, 92 ]
jz.arr.uniqueBy(json, "name"); // [ "Bob", "Steve", "John", "Tim", "Jake" ]
jz.arr.uniqueBy(json, "value"); // [ 1, 2, 3 ]
jz.arr.uniqueBy(json, function(d){ return d.value + 1; }); // [2, 3, 4]
Arrays: Other
Miscellaneous array functions.
# jz.arr.deepCopy(array)
Returns a deep copy of an array.
# jz.arr.random(array)
Returns a random item from an array.
# jz.arr.shallowCopy(array)
Returns a shallow copy of an array.
Numbers: Queries
Functions for testing numbers for certain properties.
# jz.num.isEven(integer)
Tests whether an integer is even.
Numbers: Other
Miscellaneous number functions.
# jz.num.randBetween(min, max)
Returns a random integer between two specified integers. If the second integer is less than the first, returns the first.
Strings: Cases
Functions for changing the case of words and characters.
# jz.str.toCamelCase(string)
Transforms a string into camel case.
jz.str.toCamelCase("Hello world!"); // "helloWorld"
# jz.str.toSentenceCase(string[, boolean])
Capitalizes the first letter of the first word in a string. Defaults to ignoring capital letters after the first letter. Set the second argument to true to include them.
var string = "new rules grant F.B.I., DEA & CIA access to 'raw' NSA surveillance data";
jz.str.toSentenceCase(string); // "New rules grant F.B.I., DEA & CIA access to 'raw' NSA surveillance data"
jz.str.toSentenceCase(string, true); // "New rules grant f.b.i., dea & cia access to 'raw' nsa surveillance data"
# jz.str.toSlugCase(string)
Transforms a string into a slug.
jz.str.toSlugCase("Hello world!"); // "hello-world"
# jz.str.toSnakeCase(string)
Transforms a string into snake case.
jz.str.toSnakeCase("Hello world!"); // "hello_world"
# jz.str.toStartCase(string)
Capitalizes the first letter of every word in a string. Defaults to ignoring capital letters after the first letter. Set the second argument to true to include them.
jz.str.toStartCase("Hello world!"); // "Hello World!";
var string = "new rules grant F.B.I., DEA & CIA access to 'raw' NSA surveillance data";
jz.str.toStartCase(string); // "New Rules Grant F.B.I., DEA & CIA Access To 'Raw' NSA Surveillance Data"
jz.str.toStartCase(string, true); // "New Rules Grant F.b.i., Dea & Cia Access To 'Raw' Nsa Surveillance Data"
# jz.str.toTitleCase(string[, array, boolean])
Transforms a string into title case, where the first letter of every word is capitalized except for certain prepositions, articles and conjunctions.
jz.str.toTitleCase("the quick brown fox jumps over the lazy dog"); // "The Quick Brown Fox Jumps over the Lazy Dog"
jz.str.toTitleCase("javascript: a beginner's guide to the language of the web"); // Javascript: A Beginner's Guide to the Language of the Web
jz.str.toTitleCase("james comey to remain on as FBI director"); // "James Comey to Remain on as FBI Director"
jz.str.toTitleCase("new rules grant FBI, DEA & CIA access to raw NSA surveillance data"); // New Rules Grant FBI, DEA & CIA Access to Raw NSA Surveillance Data
Strings: Numbers
Functions for manipulating numbers as strings.
# jz.str.numberCommas(string)
Adds commas to a number string for thousands, millions, billions, and so on.
# jz.str.numberDecimals(string, number)
Rounds a number string, both float and integer, to the nearest specified decimal place.
jz.str.numberDecimals("1", 2); // "1.00"
jz.str.numberDecimals("1.235", 2); // "1.24"
# jz.str.numberLakhs(string)
Adds commas to a number string for thousands, lakhs, crores, and so on. This is according to the Indian numbering system.
# jz.str.numberOrdinal(string)
Returns an ordinal number (1st, 2nd, 3rd, 4th, ...).
# jz.str.numberPrepend(string, number, prepend_character)
Adds a prepend_character before a string so that the length of the string equals a given number of characters. Does nothing to the string if it is already the same length or longer than the number of characters.
If you do not specify a prepend_character, it defaults to "0". If you specify a prepend_character of length greater than one, it uses just the first character.
jz.str.numberPrepend("1234", 6); // "001234"
Strings: Queries
Functions for testing strings for certain properties.
# jz.str.count(string, substring)
Counts the number of times a substring occurs in a string.
# jz.str.endsWith(string, substring[, boolean])
Tests whether a string ends with a substring. Defaults to case sensitive, but you can set the third argument to true for case insensitive.
jz.str.endsWith("Hello world", "LD"); // false
jz.str.endsWith("Hello world", "LD", true); // true
jz.str.endsWith("Hello world", "LD", false); // false
# jz.str.firstLetter(string)
Returns the first letter of a string. If there are no letters in the string, returns null.
jz.str.firstLetter("Hello world!"); // "H"
jz.str.firstLetter("!!Hello world!"); // "H"
jz.str.firstLetter("!"); // null
# jz.str.hasDigit(string)
Tests whether a string contains any digits.
# jz.str.includes(string, string[, boolean])
Tests whether a string includes a substring. Defaults to case sensitive, but you can set the third argument to true for case insensitive.
jz.str.includes("Hello world", "WO"); // false
jz.str.includes("Hello world", "WO", true); // true
jz.str.includes("Hello world", "WO", false); // false
# jz.str.isAllCaps(string)
Tests whether a string contains only capital letters. Ignores symbols and numbers.
jz.str.isAllCaps("JEEZY"); // true
jz.str.isAllCaps("JEE-ZY"); // true
jz.str.isAllCaps("JEEZy"); // false
# jz.str.isAllDigits(string)
Tests whether a string contains only digits.
# jz.str.isAllLower(string)
Tests whether a string contains only lowercase letters. Ignores symbols and numbers.
jz.str.isAllLower("jeezy"); // true
jz.str.isAllLower("jee-zy"); // true
jz.str.isAllLower("Jeezy"); // false
# jz.str.isUpperCase(character)
Tests whether a character is upper case.
# jz.str.startsWith(string, substring[, boolean])
Tests whether a string starts with a substring. Defaults to case sensitive, but you can set the third argument to true for case insensitive.
jz.str.startsWith("Hello world", "he"); // false
jz.str.startsWith("Hello world", "he", true); // true
jz.str.startsWith("Hello world", "he", false); // false
Strings: Transformations
Functions for applying various transformations to strings.
# jz.str.acronym(string)
Turns a string into an acronym.
# jz.str.keepAll(string, substring)
Keeps all instances of a substring in a string. Removes everything else. Returns a blank string if the substring does not appear in the original string.
# jz.str.keepEnd(string, number)
Keeps a certain number of characters at the end of a string and removes the rest.
# jz.str.keepNumber(string)
Keeps only digits and periods in a string.
+jz.str.keepNumber("254.62px"); // 254.62
# jz.str.keepOne(string, string)
Keeps one instance of a substring in a string, even if the substring appears multiple times. Removes everything else. Returns a blank string if the substring does not appear in the original string.
# jz.str.keepStart(string, number)
Keeps a certain number of characters at the start of a string and removes the rest.
# jz.str.removeAll(string, substring)
Removes all instances of a substring from a string.
# jz.str.removeDigits(string)
Removes all digits from a string.
jz.str.removeDigits("H1e2l3lo w45orld!6"); // Hello world!
# jz.str.removeFirst(string, substring)
Removes the first instance of a substring from a string.
# jz.str.removeLast(string, substring)
Removes the last instance of a substring from a string.
# jz.str.removeSymbols(string)
Removes anything that is not a letter or a space from a string.
# jz.str.removeTags(string[, array])
Removes HTML tags from a string. You can pass an optional array with the tags you want to keep.
jz.str.removeTags("<span><i>Hello</i> <b>world</b>!</span>"); // Hello world!
jz.str.removeTags("<span><i>Hello</i> <b>world</b>!</span>", ["i", "span"]); // <span><i>Hello</i> world!</span>
# jz.str.replaceAll(string, substringA, substringB)
Replaces all instances of substring A in a string with substring B.
jz.str.replaceAll("Hello world!", "l", "z"); // Hezzo worzd!
# jz.str.replaceAt(string, index, replacement)
Replaces the characters of a string with another string beginning at a specific index.
jz.str.replaceAt("Hello world!", 6, "Jonny"); // Hello Jonny!
# jz.str.replaceFirst(string, substringA, substringB)
Replaces the first instance of substring A in a string with substring B. Uses the same functionality as the native Javascript String.replace() method.
jz.str.replaceFirst("Hello world!", "l", "z"); // Hezlo world!
jz.str.replaceFirst("Hello world!", "ll", "zz"); // Hezzo world!
# jz.str.replaceLast(string, substringA, substringB)
Replaces the last instance substring A in a string with substring B.
jz.str.replaceLast("Hello world!", "l", "z"); // Hello worzd!
# jz.str.reverseCharacters(string)
Reverses the order of a string's characters.
# jz.str.reverseWords(string)
Reverses the order of a string's words.
# jz.str.shuffleCharacters(string)
Randomly shuffles a string's characters. Uses the Fischer-Yates shuffle.
# jz.str.shuffleCharactersInWords(string)
Randomly shuffles the characters of each word, but keeps the words in order. Uses the Fischer-Yates shuffle.
# jz.str.shuffleWords(string)
Randomly shuffles a string's words. Uses the Fischer-Yates shuffle.
Strings: Other
# jz.str.randomString(n)
Creates a string of randomized characters of n length. If n is not specified, the string will be 5 characters long.
# jz.str.splitAfterFirst(string, char)
Split a string at the first instance of a character or a sequence of characters (char). Returns an array with two items. The first item is everything that came before char, while the second item is everything that came after. char itself is removed.
jz.str.splitAfterFirst("Hello world", "o"); // ["Hell", " world"]
jz.str.splitAfterFirst("Good morning world", "or"); // ["Good m", "ning world"]
jz.str.splitAfterFirst("Hello world", "x"); // ["Hello world", ""]
# jz.str.splitAfterLast(string, char)
Split a string at the last instance of a character or a sequence of characters (char). Returns an array with two items. The first item is everything that came before char, while the second item is everything that came after. char itself is removed.
jz.str.splitAfterLast("Hello world", "o"); // ["Hello w", "rld"]
jz.str.splitAfterLast("Good morning world", "or"); // ["Good morning w", "ld"]
jz.str.splitAfterLast("Hello world", "x"); // ["Hello world", ""]
# jz.str.splitAtIndex(string, number OR array of numbers)
Split a string at a numerical index or at each index in an array of numerical indices.
jz.str.splitAtIndex("Hello world", "Hello world".length - 1); // ["Hello worl", "d"]
jz.str.splitAtIndex("Hello world", [1, "Hello world".length - 1]); // ["H", "ello worl", "d"]
Tests
npm test # Test
npm run cover # Test and run a coverage report
Contributing
jeezy uses rollup to bundle several small modules, usually containing just one function, into a library. To add a function, create a file in the appropriate subdirectory within the src directory, and then export it from arrays.js, numbers.js, or strings.js.
To bundle the library:
npm run rollup # Bundle
npm run build # Bundle and minify
In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.