array-tools

array-tools

Lightweight tool-kit for working with arrays.

> var a = require("array-tools");
> a.exists([ 1, 2, 3 ], 1)
true

You can also chain together operations. Any method from array-tools or Array.prototype which returns an array can be chained. Methods which do not return an arrary (e.g. exists or Array.prototype.join) can not be chained. If the final operation in your chain is one of the chainable methods then you must terminate it with .val() to obtain the value. For example:

> var a = require("array-tools");
> a([ 1, 2, 2, 3 ]).exists(1)
true
> a([ 1, 2, 2, 3 ]).without(1).exists(1)
false
> a([ 1, 2, 2, 3 ]).without(1).unique().val()
[ 2, 3 ]

• array-tools
  • any value in
    • .arrayify(any) ⇒ Array
  • multiple arrays in
    • .union(array1, array2, idKey) ⇒ Array
    • .commonSequence(a, b) ⇒ Array
  • record set in
    • .pluck(arrayOfObjects, ...property) ⇒ Array
    • .pick(arrayOfObjects, ...property) ⇒ Array.<object>
    • .where(arrayOfObjects, query) ⇒ Array
    • .findWhere(arrayOfObjects, query) ⇒ object
    • .sortBy(arrayOfObjects, columns, customOrder) ⇒ Array
  • single array in
    • .exists(array, value) ⇒ boolean
    • .without(array, toRemove) ⇒ Array
    • .unique(array) ⇒ Array
    • .spliceWhile(array, index, test, ...elementN) ⇒ Array
    • .extract(array, query) ⇒ Array
    • .flatten(array) ⇒ Array
    • .last(arr) ⇒ *
    • .remove(arr, toRemove) ⇒ *
    • .contains(arr, value) ⇒

a.arrayify(any) ⇒ Array

Takes input and guarantees an array back. Result can be one of three things:

• puts a single scalar in an array
• converts array-like object (e.g. arguments) to a real array
• converts null or undefined to an empty array

Kind: static method of array-tools
Category: any value in

Param	Type	Description
any	*	the input value to convert to an array

Example

> a.arrayify(null)
[]
> a.arrayify(0)
[ 0 ]
> a.arrayify([ 1, 2 ])
[ 1, 2 ]
> function f(){ return a.arrayify(arguments); }
> f(1,2,3)
[ 1, 2, 3 ]

a.union(array1, array2, idKey) ⇒ Array

merge two arrays into a single array of unique values

Kind: static method of array-tools
Category: multiple arrays in

Param	Type	Description
array1	Array	First array
array2	Array	Second array
idKey	string	the unique ID property name

Example

> var array1 = [ 1, 2 ], array2 = [ 2, 3 ];
> a.union(array1, array2)
[ 1, 2, 3 ]
> var array1 = [ { id: 1 }, { id: 2 } ], array2 = [ { id: 2 }, { id: 3 } ];
> a.union(array1, array2)
[ { id: 1 }, { id: 2 }, { id: 3 } ]
> var array2 = [ { id: 2, blah: true }, { id: 3 } ]
> a.union(array1, array2)
[ { id: 1 },
  { id: 2 },
  { id: 2, blah: true },
  { id: 3 } ]
> a.union(array1, array2, "id")
[ { id: 1 }, { id: 2 }, { id: 3 } ]

a.commonSequence(a, b) ⇒ Array

Returns the initial elements which both input arrays have in common

Kind: static method of array-tools
Category: multiple arrays in

Param	Type	Description
a	Array	first array to compare
b	Array	second array to compare

Example

> a.commonSequence([1,2,3], [1,2,4])
[ 1, 2 ]

a.pluck(arrayOfObjects, ...property) ⇒ Array

Plucks the value of the specified property from each object in the input array

Kind: static method of array-tools
Category: record set in

Param	Type	Description
arrayOfObjects	Array.<object>	the input array of objects
...property	string	the property(s) to pluck

Example

> var data = [
    {one: 1, two: 2},
    {two: "two"},
    {one: "one", two: "zwei"},
];
> a.pluck(data, "one");
[ 1, 'one' ]
> a.pluck(data, "two");
[ 2, 'two', 'zwei' ]
> a.pluck(data, "one", "two");
[ 1, 'two', 'one' ]

a.pick(arrayOfObjects, ...property) ⇒ Array.<object>

return a copy of the input arrayOfObjects containing objects having only the cherry-picked properties

Kind: static method of array-tools
Category: record set in

Param	Type	Description
arrayOfObjects	Array.<object>	the input
...property	string	the properties to include in the result

Example

> data = [
    { one: "un", two: "deux", three: "trois" },
    { two: "two", one: "one" },
    { four: "quattro" },
    { two: "zwei" }
]
> a.pick(data, "two")
[ { two: 'deux' },
  { two: 'two' },
  { two: 'zwei' } ]

a.where(arrayOfObjects, query) ⇒ Array

returns an array containing items from arrayOfObjects where key/value pairs from query are matched identically

Kind: static method of array-tools
Category: record set in

Param	Type	Description
arrayOfObjects	Array.<object>	the array to search
query	query	an object containing the key/value pairs you want to match

Example

> dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]
[ { name: 'Jim', age: 8 },
  { name: 'Clive', age: 8 },
  { name: 'Hater', age: 9 } ]
> a.where(dudes, { age: 8})
[ { name: 'Jim', age: 8 },
  { name: 'Clive', age: 8 } ]

a.findWhere(arrayOfObjects, query) ⇒ object

returns the first item from arrayOfObjects where key/value pairs from query are matched identically

Kind: static method of array-tools
Category: record set in

Param	Type	Description
arrayOfObjects	Array.<object>	the array to search
query	object	an object containing the key/value pairs you want to match

Example

> dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]
[ { name: 'Jim', age: 8 },
  { name: 'Clive', age: 8 },
  { name: 'Hater', age: 9 } ]
> a.findWhere(dudes, { age: 8})
{ name: 'Jim', age: 8 }

a.sortBy(arrayOfObjects, columns, customOrder) ⇒ Array

Sort an array of objects by one or more fields

Kind: static method of array-tools
Category: record set in
Since: 1.5.0

Param	Type	Description
arrayOfObjects	Array.<object>	input array
columns	string | Array.<string>	column name(s) to sort by
customOrder	object	specific sort orders, per columns

Example

>  var fixture = [
    { a: 4, b: 1, c: 1},
    { a: 4, b: 3, c: 1},
    { a: 2, b: 2, c: 3},
    { a: 2, b: 2, c: 2},
    { a: 1, b: 3, c: 4},
    { a: 1, b: 1, c: 4},
    { a: 1, b: 2, c: 4},
    { a: 3, b: 3, c: 3},
    { a: 4, b: 3, c: 1}
];
> a.sortBy(fixture, ["a", "b", "c"])
[ { a: 1, b: 1, c: 4 },
  { a: 1, b: 2, c: 4 },
  { a: 1, b: 3, c: 4 },
  { a: 2, b: 2, c: 2 },
  { a: 2, b: 2, c: 3 },
  { a: 3, b: 3, c: 3 },
  { a: 4, b: 1, c: 1 },
  { a: 4, b: 3, c: 1 },
  { a: 4, b: 3, c: 1 } ]

a.exists(array, value) ⇒ boolean

returns true if a value, or nested object value exists in an array

Kind: static method of array-tools
Category: single array in

Param	Type	Description
array	Array	the array to search
value	*	the value to search for

Example

> a.exists([ 1, 2, 3 ], 2)
true
> a.exists([ { result: false }, { result: false } ], { result: true })
false
> a.exists([ { result: true }, { result: false } ], { result: true })
true
> a.exists([ { result: true }, { result: true } ], { result: true })
true

a.without(array, toRemove) ⇒ Array

Returns the input minus the specified values.

Kind: static method of array-tools
Category: single array in

Param	Type	Description
array	Array	the input array
toRemove	*	a single, or array of values to omit

Example

> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]

a.unique(array) ⇒ Array

returns an array of unique values

Kind: static method of array-tools
Category: single array in

Param	Type	Description
array	Array	input array

Example

> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]
> a.unique(n)
[ 1, 6, 7 ]

a.spliceWhile(array, index, test, ...elementN) ⇒ Array

splice from index until test fails

Kind: static method of array-tools
Category: single array in

Param	Type	Description
array	Array	the input array
index	number	the position to begin splicing from
test	RegExp	the test to continue splicing while true
...elementN	*	the elements to add to the array

Example

> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]
> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]
> letters
[ 'x', 'b' ]

a.extract(array, query) ⇒ Array

Removes items from array which satisfy the query. Modifies the input array, returns the extracted.

Kind: static method of array-tools
Returns: Array - the extracted items.
Category: single array in

Param	Type	Description
array	Array	the input array, modified directly
query	function | object	Per item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted

a.flatten(array) ⇒ Array

flatten an array of arrays into a single array

Kind: static method of array-tools
Category: single array in
Since: 1.4.0

Param	Type	Description
array	Array	the input array

Example

> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]

a.last(arr) ⇒ *

Return the last item in an array.

Kind: static method of array-tools
Category: single array in
Since: 1.7.0

Param	Type	Description
arr	Array	the input array

a.remove(arr, toRemove) ⇒ *

Kind: static method of array-tools
Category: single array in
Since: 1.8.0

Param	Type	Description
arr	Array	the input array
toRemove	*	the item to remove

a.contains(arr, value) ⇒

Kind: static method of array-tools
Returns: boolean
Category: single array in
Since: 1.8.0

Param	Type	Description
arr	Array	the input array
value	*	the value to look for

---

© 2015 Lloyd Brookes [e-mail]. Documented by jsdoc-to-markdown.