ProArray

Extends Arrays (safely) with useful methods of unparalleled performance

Installation

npm install pro-array --save

Usage

require('pro-array');

Requires browserify to work in the browser.

API Reference

Array

The native Array object.

See: MDN JavaScript Array Reference

• Array
  • .bsearch(value, [compareFunction]) ⇒ number
  • .chunk([size]) ⇒ Array
  • .clear() ⇒ Array
  • .clone() ⇒ Array
  • .compact() ⇒ Array
  • .diff()
  • .difference(...arrays) ⇒ Array
  • .each(callback, [safeIteration]) ⇒ Array
    • ~eachCallback : function
  • .equals(array) ⇒ boolean
  • .flatten() ⇒ Array
  • .flattenDeep([noCallStack]) ⇒ Array
  • .get(index) ⇒ *
  • .intersect(...arrays) ⇒ Array
  • .natsort([caseInsensitive]) ⇒ Array
  • .numsort() ⇒ Array
  • .pull()
  • .remove(...items) ⇒ Array
  • .rnatsort([caseInsensitive]) ⇒ Array
  • .rnumsort() ⇒ Array
  • .union(...arrays) ⇒ Array
  • .uniq()
  • .unique([isSorted]) ⇒ Array
  • .without(...items) ⇒ Array
  • .xor(...arrays) ⇒ Array

array.bsearch(value, [compareFunction]) ⇒ number

Finds the index of a value in a sorted array using a binary search algorithm.

If no compareFunction is supplied, the > and < relational operators are used to compare values, which provides optimal performance for arrays of numbers and simple strings.

| Param | Type | Description | | --- | --- | --- | | value | * | The value to search for. | | [compareFunction] | function | The same type of comparing function you would pass to .sort(). |

Returns: number - The index of the value if it is in the array, or -1 if it cannot be found. If the search value can be found at multiple indexes in the array, it is unknown which of those indexes will be returned.

Example

['a', 'b', 'c', 'd'].bsearch('c');
// -> 2

[1, 1, 2, 2].bsearch(2);
// -> 2 or 3

[1, 2, 3, 4].bsearch(10);
// -> -1

// Search an array of people sorted by age
var finn = {name: 'Finn', age: 12};
var jake = {name: 'Jake', age: 28};
[finn, jake].bsearch(finn, function(a, b) {
  return a.age - b.age;
});
// -> 0

['img1', 'img2', 'img10', 'img13'].bsearch('img2', naturalCompare);
// -> 1
// `naturalCompare` is provided by the string-natural-compare npm module:
// https://www.npmjs.com/package/string-natural-compare

array.chunk([size]) ⇒ Array

Creates an array of elements split into groups the length of size. If the array can't be split evenly, the final chunk will be the remaining elements.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [size] | number | 1 | The length of each chunk. |

Returns: Array - An array containing the chunks.
Throws:

• RangeError Throws when size is a negative number.

Example

[1, 2, 3, 4].chunk(2);
// -> [[1, 2], [3, 4]]

[1, 2, 3, 4].chunk(3);
// -> [[1, 2, 3], [4]]

array.clear() ⇒ Array

Removes all elements from the array.

Returns: Array - The array this method was called on.

Example

var array = [1, 2, 3];
array.clear();
console.log(array);
// -> []

array.clone() ⇒ Array

Creates a shallow copy of the array.

Returns: Array - A clone of the array.

Example

var a = [1, 2, 3];
var b = a.clone();
console.log(b, b === a);
// -> [1, 2, 3] false

array.compact() ⇒ Array

Returns a new array with all falsey values removed. Falsey values are false, 0, "", null, undefined, and NaN.

Returns: Array - The new array containing only the truthy values from the original array.

Example

[0, 1, false, 2, '', 3].compact();
// -> [1, 2, 3]

array.diff()

Alias of difference.

See: difference

array.difference(...arrays) ⇒ Array

Returns a new array with all of the values of the array that are not in any of the input arrays (performs a set difference).

| Param | Type | Description | | --- | --- | --- | | arrays | ...Array | A variable number of arrays. |

Returns: Array - The new array of filtered values.

Example

[1, 2, 3, 4, 5].difference([5, 2, 10]);
// -> [1, 3, 4]

array.each(callback, [safeIteration]) ⇒ Array

Invokes a callback function on each element in the array.

A generic iterator method similar to .forEach() but with the following differences:

1. this always refers to the current element in the iteration (the value argument to the callback).
2. Returning false in the callback will cancel the iteration (similar to a break statement).
3. The array is returned to allow for function chaining.
4. The callback is invoked for indexes that have been deleted or elided unless safeIteration is true.

| Param | Type | Default | Description | | --- | --- | --- | --- | | callback | eachCallback | | A function to be executed on each element in the array. | | [safeIteration] | boolean | false | When true, the callback will not be invoked for indexes that have been deleted or elided (are undefined). |

Returns: Array - The array this method was called on.

Example

['a', 'b', 'c'].each(console.log.bind(console));
// -> 'a' 0 ['a', 'b', 'c']
// -> 'b' 1 ['a', 'b', 'c']
// -> 'c' 2 ['a', 'b', 'c']
// -> ['a', 'b', 'c']

['a', 'b', 'c'].each(function(value, index) {
  console.log(value);
  if (index === 1) return false;
});
// -> 'a'
// -> 'b'
// -> ['a', 'b', 'c']

[[1, 2], [3, 4, 5]].each(Array.prototype.pop);
// -> [[1], [3, 4]]

new Array(1).each(console.log.bind(console));
// -> undefined 0 [undefined]
// -> [undefined]

new Array(1).each(console.log.bind(console), true);
// -> [undefined]

each~eachCallback : function

| Param | Type | Description | | --- | --- | --- | | value | * | The current element being processed. | | index | number | The index of the current element being processed. | | array | Array | The array .each() was called on. |

array.equals(array) ⇒ boolean

Determines if the arrays are equal by doing a shallow comparison of their elements using strict equality.

Note: The order of elements in the arrays does matter. The elements must be found in the same order for the arrays to be considered equal.

| Param | Type | Description | | --- | --- | --- | | array | Array | An array to compare for equality. |

Returns: boolean - true if the arrays are equal, false otherwise.

Example

var array = [1, 2, 3];

array.equals(array);
// -> true

array.equals([1, 2, 3]);
// -> true

array.equals([3, 2, 1]);
// -> false

array.flatten() ⇒ Array

Flattens a nested array a single level.

Returns: Array - The new flattened array.

Example

[1, [2, 3, [4]], 5].flatten();
// -> [1, 2, 3, [4], 5]

array.flattenDeep([noCallStack]) ⇒ Array

Recursively flattens a nested array.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [noCallStack] | boolean | false | Specifies if an algorithm that is not susceptible to call stack limits should be used, allowing very deeply nested arrays (i.e. > 9000 levels) to be flattened. |

Returns: Array - The new flattened array.

Example

[1, [2, 3, [4]], 5].flattenDeep();
// -> [1, 2, 3, 4, 5]

array.get(index) ⇒ *

Retrieve an element in the array.

| Param | Type | Description | | --- | --- | --- | | index | number | A zero-based integer indicating which element to retrieve. |

Returns: * - The element at the specified index.

Example

var array = [1, 2, 3];

array.get(0);
// -> 1

array.get(1);
// -> 2

array.get(-1);
// -> 3

array.get(-2);
// -> 2

array.get(5);
// -> undefined

array.intersect(...arrays) ⇒ Array

Returns an new array that is the set intersection of the array and the input array(s).

| Param | Type | Description | | --- | --- | --- | | arrays | ...Array | A variable number of arrays. |

Returns: Array - The new array of unique values shared by all of the arrays.

Example

[1, 2, 3].intersect([2, 3, 4]);
// -> [2, 3]

[1, 2, 3].intersect([101, 2, 50, 1], [2, 1]);
// -> [1, 2]

array.natsort([caseInsensitive]) ⇒ Array

Sorts an array in place using a natural order string comparison algorithm.

For more ways to perform a natural ordering sort, including configuring a custom alphabet, see the string-natural-compare documentation.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [caseInsensitive] | boolean | false | Set this to true to ignore letter casing when sorting. |

Returns: Array - The array this method was called on.

Example

var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.natsort();
console.log(files);
// -> ['a.txt', 'a1.txt', 'a2.txt', 'a10.txt']

array.numsort() ⇒ Array

Sorts an array in place using a numerical comparison algorithm (sorts numbers from lowest to highest) and returns the array.

Returns: Array - The array this method was called on.

Example

var a = [10, 0, 2, 1];
a.numsort();
console.log(a);
// -> [0, 1, 2, 3]

array.pull()

Alias of remove.

See: remove

array.remove(...items) ⇒ Array

Removes all occurrences of the passed in items from the array and returns the array.

Note: Unlike .without(), this method mutates the array.

| Param | Type | Description | | --- | --- | --- | | items | ...* | Items to remove from the array. |

Returns: Array - The array this method was called on.

Example

var array = [1, 2, 3, 3, 4, 3, 5];

array.remove(1);
// -> [2, 3, 3, 4, 3, 5]

array.remove(3);
// -> [2, 4, 5]

array.remove(2, 5);
// -> [4]

array.rnatsort([caseInsensitive]) ⇒ Array

Sorts an array in place using a natural order string comparison algorithm.

The same as .natsort() except the strings are sorted in descending order.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [caseInsensitive] | boolean | false | Set this to true to ignore letter casing when sorting. |

Returns: Array - The array this method was called on.

Example

var files = ['a.txt', 'a10.txt', 'a2.txt', 'a1.txt'];
files.rnatsort();
console.log(files);
// -> ['a10.txt', 'a2.txt', 'a1.txt', 'a.txt']

array.rnumsort() ⇒ Array

Sorts an array in place using a reverse numerical comparison algorithm (sorts numbers from highest to lowest) and returns the array.

Returns: Array - The array this method was called on.

Example

var a = [10, 0, 2, 1];
a.rnumsort();
console.log(a);
// -> [3, 2, 1, 0]

array.union(...arrays) ⇒ Array

Returns an array that is the union of the array and the input array(s).

| Param | Type | Description | | --- | --- | --- | | arrays | ...Array | A variable number of arrays. |

Returns: Array - The new array containing every distinct element found in the arrays.

Example

[1, 2, 3].union([2, 3, 4, 5]);
// -> [1, 2, 3, 4, 5]

[1, 2].union([4, 2], [2, 1]);
// -> [1, 2, 4]

array.uniq()

Alias of unique.

See: unique

array.unique([isSorted]) ⇒ Array

Returns a duplicate-free clone of the array.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [isSorted] | boolean | false | If the array's contents are sorted and this is set to true, a faster algorithm will be used to create the unique array. |

Returns: Array - The new, duplicate-free array.

Example

// Unsorted
[4, 2, 3, 2, 1, 4].unique();
// -> [4, 2, 3, 1]

// Sorted
[1, 2, 2, 3, 4, 4].unique();
// -> [1, 2, 3, 4]

[1, 2, 2, 3, 4, 4].unique(true);
// -> [1, 2, 3, 4] (but faster than the previous example)

array.without(...items) ⇒ Array

Returns a copy of the array without any elements from the input parameters.

| Param | Type | Description | | --- | --- | --- | | items | ...* | Items to leave out of the returned array. |

Returns: Array - The new array of filtered values.

Example

[1, 2, 3, 4].without(2, 4);
// -> [1, 3]

[1, 1].without(1);
// -> []

array.xor(...arrays) ⇒ Array

Finds the symmetric difference of the array and the input array(s).

| Param | Type | Description | | --- | --- | --- | | arrays | ...Array | A variable number of arrays. |

Returns: Array - The new array of values.

Example

[1, 2].xor([4, 2]);
// -> [1, 4]

[1, 2, 5].xor([2, 3, 5], [3, 4, 5]);
// -> [1, 4, 5]
// Explanation:
// [1, 2, 5] ⊕ [2, 3, 5] ⊕ [3, 4, 5] = [1, 4, 5]

Extending Array.prototype

ProArray uses Object.defineProperties() to safely extend the native Array prototype such that the added properties are not enumerable. This keeps native arrays clean and prevents potential abnormalities when working with arrays.

Worried about naming collisions?

It is extremely unlikely that the name of any method that ProArray adds to the Array prototype will be used in a future ECMAScript standard, but if you're still worried and want to be extra safe, try using the alias methods (like .pull() and .uniq()).