This package includes a set of useful array methods that facilitates working with arrays, specifically the arrays that contain objects or arrays even falsy values (such as: 0, null, false, NaN...). This package is es5 supported.
const array = require("array-power");
var list= [1, {foo: "loo"}, 3, 1, [1,2], 1, 2, [1, 2], false, 2, 2, 4, 3, 5, "1", 8, {"foo": "loo"} ];
// noDup(array):Remove duplicates from an array.
array.noDup(list);
// Output: [ 1, { foo: 'loo' }, 3, [ 1, 2 ], 2, false, 4, 5, '1', 8 ]
// getDup(array): Get duplicated items in array (return an array of items with no duplicates).
array.getDup(list);
// Output: [ 1, { foo: 'loo' }, 3, [ 1, 2 ], 2 ]
// getUniq(array): Get unique items in array.
array.getUniq(list);
// Output: [ false, 4, 5, '1', 8 ]
// chunk(array, length): Chunks an array into arrays with length elements. The last chunk may contain less than length elements.
array.chunk(list, 3);
// Output: [
// [ 1, { foo: 'loo' }, 3 ],
// [ 1, [ 1, 2 ], 1 ],
// [ 2, [ 1, 2 ], false ],
// [ 2, 2, 4 ],
// [ 3, 5, '1' ],
// [ 8, { foo: 'loo' } ]
// ]
// occur(array, items): Get the occurrences of an array item(s) (if provided) as well as all occurrences of array elements. Items can be an array of values or seperate values (example: array(list, 3, "1", 2)).
array.occur(list)
// Output: [
// { item: 1, occurrence: 3 },
// { item: { foo: 'loo' }, occurrence: 2 },
// { item: 3, occurrence: 2 },
// { item: [ 1, 2 ], occurrence: 2 },
// { item: 2, occurrence: 3 },
// { item: false, occurrence: 1 },
// { item: 4, occurrence: 1 },
// { item: 5, occurrence: 1 },
// { item: '1', occurrence: 1 },
// { item: 8, occurrence: 1 }
// ]
array.occur(list, 3);
// Output: [{ item: 3, occurrence: 2 }]
array.occur(list, 3, 1);
// Output: [ { item: 3, occurrence: 2 }, { item: 1, occurrence: 3 } ]
array.occur(list, [3, 1]);
// Output: [ { item: 3, occurrence: 2 }, { item: 1, occurrence: 3 } ]
array.occur(list, [1, 2]);
// Output: [ { item: 1, occurrence: 3 }, { item: 2, occurrence: 3 } ]
array.occur(list, [[1, 2]]);
// Output: [ { item: [ 1, 2 ], occurrence: 2 } ]
// arrDiff(baseArray, array of arrays or seperate arrays): Compare array to another arrays to extract its unique items (without duplicates).
array.arrDiff(list, [1, 3, 5,{"foo": "loo"}, 6, 7]);
// Output: [ [ 1, 2 ], 2, false, 4, '1', 8 ]
array.arrDiff(list, [0, 3], [4, 5]);
// Output: [ 1, { foo: 'loo' }, [ 1, 2 ], 2, false, '1', 8 ]
array.arrDiff(list, [[0, 3], [4, 5]]);
// Output: [ 1, { foo: 'loo' }, [ 1, 2 ], 2, false, '1', 8 ]
// diffs(arrays of arrays or seperate arrays): Get unique items in two arrays or more (without duplicates).
array.diffs(list, [3, 9, 5, 1, 2, false, "home"]);
// Output: [ { foo: 'loo' }, [ 1, 2 ], 4, '1', 8, 9, 'home' ]
array.diffs(diffs(list, [1, 4,{foo: "loo"}, 5], [2, "Dog", 5]));
// Output: [ 3, [ 1, 2 ], false, '1', 8, 'Dog' ]
// cmn(array of arrays or seperate arrays): Get common items in two arrays or more.
array.cmn(list, [1, 4,{foo: "loo"}, 5], [2, "Dog", 5]);
// Output: [ 5 ]
array.cmn([[1, 3, "white"], [3, "red", 1], ["black", 6, 4]]);
// Output: []
// Check if array is an array of arrays.
array.isArrayOfArrays([[1, 2, 3], [], [23, "star", 12]]);
// Output: true
array.isArrayOfArrays([11, [1, 3, 5 ], ["keyboard", "flower", "football"]]);
// Output: false
// Check if array is an array of strings.
array.isArrayOfStrings(["BWM", "FORD", "Testla", "Google", "Facebook"]);
// Output: true
array.isArrayOfStrings(["BWM", "FORD", "Testla", 25, "Google", "Facebook"]);
// Output: false
// check if array is an array of numbers.
array.isArrayOfNumbers(["2", 3, 4, "1", 9]);
// Output: false
array.isArrayOfNumbers([2, 3, 4, 1, 9]);
// Output: true
// Check if array is an array of objects (arrays and null values are excluded).
array.isArrayOfObjects([{"firstName": "Elyes", "age":"28"}, {"firstName": "John", "age":"25"}, {"firstName": "Sarah", "age":"21"}]);
// Output: true
array.isArrayOfObjects([{"firstName": "Elyes", "age":"28"}, [2, 3, 5], {"foo": "loo"}]);
// Output: false
// itemIn(item: any value, oneArray: Boolean, array of arrays or seperate arrays): if oneArray is true, check if item exists in one array at least, else check that exists in all arrays.
array.itemIn(1, false, ["3", 1, 2], [1, 4, 25, 6], [2, 4, 8, 9, 1]);
// Output: true; 1 is included in all of the arrays;
array.itemIn(1, false, ["3", 1, 2], [2, 4], [1, 4, 25, 6], [2, 4, 8, 9, 1]);
// Output: false;
array.itemIn(1, true, ["3", 1, 2], [2, 4], [1, 4, 25, 6], [2, 4, 8, 9, 1]);
// Output: true; 1 is included in one array at least;
array.itemIn(7, true, ["3", 1, 2], [2, 4], [1, 4, 25, 6], [2, 4, 8, 9, 1]);
// Output: false;
// allIn(items: array of values, oneArray: Boolean, array of arrays or seperate arrays): if oneArray is true, check if all the items exist in one array at least, else check that exist in all arrays.
array.allIn([1, 2], false, [[4, 3, 5, 2, 1], [23, 99, 2, 12, 1, 3], [8, 1, 5, 2]]);
// Output: true; 1 and 2 are included in all of the arrays.
array.allIn([1, 2], false, [[3, 2, 5], [1, 2, 3, 4, 5], [1, 2, 9, 12]);
// Output: false
array.allIn([1, 2], true, [[3, 2, 5], [1, 2, 3, 4, 5], [1, 2, 9, 12]);
// Output: true; 1 and 2 are included in one array at least.
array.allIn([1, 2], true, [3, 5, 6], [2, 3, 6], [1, 4, 4]);
// Output: false
// oneIn(items: array of values, oneArray: Boolean, array of arrays or seperate arrays): if oneArray is true, check if on item at least from the list exists in one array at least, else check that one item exist in all arrays.
array.oneIn(["white", "blue", "red"], false, ["yellow", "green", "red"], ["white", "red", "black"], ["red", "blue", "purple"]);
// Output: true; at least one item is included in all arrays, which is in this case the "red".
array.oneIn(["white", "blue", "red"], true, ["yellow", "green"], ["orange", "black"], ["pink", "purple"]);
// Output: false; no item is included in one array at least.
array.oneIn(["white", "blue", "red"], true, ["yellow", "white", "green"], ["orange", "black"], ["pink", "purple"]);
// Output: true; at least one item is included in one array, which is in this case the "white".
// splitTo(array, n): Split an array into n parts of non-empty arrays. Return an array of arrays. Maximum number of generated arrays is equal to the length of the initial array even n is superior to the array's length.
array.splitTo([1, 3, 5, 7, 9, 11, 13, 15], 3);
// Output: [[1, 3, 5], [7, 9, 11], [13, 15]]
// shuffle(array): Shuffle an array (randomize).
array.shuffle([3, 4, 5, 6, 7, 8]);
// Output: [5, 3, 8, 7, 4, 6]
// filling(array, n, shuffled): Fill an array with multiple items, each of them repeated n times, with ability to shuffle it.
array.filling([1, 2, 3], 3, false);
// Output: [1, 1, 1, 2, 2, 2, 3, 3, 3]
array.filling([1, 2, 3], 3, true);
// Output: [3, 1, 1, 2, 3, 2, 1, 3, 2]
// arrange(array): Arrange array by same items (keeping same order of the unque items inside array).
array.arrange([1, 5, 3, 5, 2, 1, 1, 4, 5, 3, 3, 3, 6]);
// Output: [1, 1, 1, 5, 5, 5, 3, 3, 3, 3, 2, 4, 6]
// numRange(start, end, skip): Create array from a range of numbers with ability to skip.
array.numRange(5, 12);
// Output: [5, 6, 7, 8, 9, 10, 11, 12];
array.numRange(5, 12, 2);
// Output: [5, 7, 9, 11]
// findAll(array, item, start, end).
/**
* Look for item indexes in array from start to end position.
*
* @param {Array} array
* @param {Any} item Item to look for in the array.
* @param {Number} start The position from which to start searching for item in the array.
* @param {Number} end The position at which the search for item in the array stops.
* @return {Array} Return array of indexes.
*/
array.findAll([2, 3, 1, 7, 4, 9, 1, 4], 1);
// Output: [2, 6]
array.findAll([2, 3, 1, 7, 4, 9, 1, 4], 1, 3 , 5);
// Output: [] there is no item = 1 between the index 3 and the index 5.
let exampleArray = [4, 2, 3, 1, 7];
// pop(array).
/**
* Remove (pops) the last item of an array without changing the original array.
*
* @param {Array} array
* @return {Array} Return new array without the removed item (the last one).
*/
array.pop(exampleArray);
// Output: [4, 2, 3 ,1]
// shift(array).
/**
* Shift (remove) the first item of the array without changing the original array.
*
* @param {Array} array
* @return {Array} Return new array without the removed item (the first one).
*/
array.shift(exampleArray);
// Output: [2, 3, 1, 7];
// unshift(array, ...items).
/**
* Add new items to the beginning of an array without changing the original array.
*
* @param {Array} array
* @param {Any} items The item(s) to add to the array. Minimum one item is required.
* @return {Array} Return new array with the new items added to the beginning of the original array.
*/
array.unshift(exampleArray, 5);
// Output: [5, 4, 2, 3, 1, 7];
// push(array, ...items).
/**
* Add new items to the end of an array without changing the original array.
*
* @param {Array} array
* @param {Any} items The item(s) to add to the array. Minimum one item is required.
* @return {Array} Return new array with the new items added to the end of the original array.
*/
array.push(exampleArray, 5);
// Output: [4, 2, 3, 1, 7, 5];
// splice(array, start, deleteCount = 0, ...items).
/**
* Add and/or remove array items without changing the original array.
*
* @param {Array} array
* @param {Number} start The position to add/remove items. Negative value defines the position from the end of the array.
* @param {Number} deleteCount Number of items to be removed.
* @param {Any} items New elements(s) to be added.
* @return {Array} new array with added or/and without the removed elements from the original array.
*/
array.splice(exampleArray, 2, 0, 5, 6);
// Output: [4, 2, 5, 6, 3, 1, 7]
// sort(array, compareFunc).
/**
* Sort the array items as strings in alphabetical and ascending order without changing the original array.
*
* @param {Array} array
* @param {Function} compareFunc A function that defines a sort order. The function should return a negative, zero, or positive value, depending on the arguments.
* @return {Array} new array with the items sorted.
*/
array.sort(exampleArray);
// Output: [1, 2, 3, 4, 7];
// reverse(array).
/**
* Reverse the order of the items in an array without changing the original array.
*
* @param {Array} array
* @return {Array} return new array with the order of the elements in the original array is reversed.
*/
array.reverse(exampleArray);
// Output: [7, 1, 3, 2, 4];
// reverseSort(array, compareFunc).
/**
* Sort the array items as strings in alphabetical and ascending order, then reverse the order of the items without changing the original array.
*
* @param {Array} array.
* @param {Function} compareFunc A function that defines a sort order. The function should return a negative, zero, or positive value, depending on the arguments.
* @return {Array} new array with the items sorted with reversed order.
*/
array.reverseSort(exampleArray);
// Output: [7, 4, 3, 2, 1]
// isDense(array).
/**
* Check whether array is dense or sparse.
*
* @param {Array} array
* @return {Boolean} if true, array is dense, else is sparse.
*/
array.isDense(exampleArray);
//Output: true
exampleArray[100] = 8;
array.isDense(exampleArray);
//Output: false array is sparse.
// longStr(arr, order);
/**
* get the longest sting(s) in array
*
* @param {Array} arr
* @param {Number} order define the value to be returned, 0 = array of longests string in array; 1 = return the first longest string if there are multiple strings with same length; -1 = return the last longest string if there are multiple strings with same length.
* @return {Array | String} the longest string(s) in array.
*/
const randomList = ["John Doe", 1, "My name is Elyes", 25, "How are you?", "25d", "Hello world", "foo", "My name is Sarra", "str"]
array.longStr(randomList, 0) // Output: [ 'My name is Elyes', 'My name is Sarra' ];
array.longStr(randomList, 1) // Output: 'My name is Elyes'
array.longStr(randomList, -1) // Output: 'My name is Sarra'