array-tools

Lightweight tool-kit for working with arrays

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. The process:

  1. Pass your input array to array-tools as an argument.
  2. Chain together your operations. From array-tools, you may use pluck, pick, arrayify, where, findWhere, without, unique, spliceWhile, extract, flatten, exists and sortBy in the chain. From core Array methods you may use filter, reverse, sort, concat, slice, every, some and map.
  3. Finally, following all above methods except exists, call .val() to extract the result.
> 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 ]

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

ParamTypeDescription
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 ]

merge two arrays into a single array of unique values

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

ParamTypeDescription
array1ArrayFirst array
array2ArraySecond array
idKeystringthe 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 } ]

Returns the initial elements which both input arrays have in common

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

ParamTypeDescription
aArrayfirst array to compare
bArraysecond array to compare

Example

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

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

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

ParamTypeDescription
arrayOfObjectsArray.<object>the input array of objects
...propertystringthe 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' ]

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

ParamTypeDescription
arrayOfObjectsArray.<object>the input
...propertystringthe 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' } ]

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

ParamTypeDescription
arrayOfObjectsArray.<object>the array to search
queryqueryan 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 } ]

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

ParamTypeDescription
arrayOfObjectsArray.<object>the array to search
queryobjectan 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 }

Sort an array of objects by one or more fields

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

ParamTypeDescription
arrayOfObjectsArray.<object>input array
columnsstring | Array.<string>column name(s) to sort by
customOrderobjectspecific 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 } ]

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

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

ParamTypeDescription
arrayArraythe 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

Returns the input minus the specified values.

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

ParamTypeDescription
arrayArraythe 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 ]

returns an array of unique values

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

ParamTypeDescription
arrayArrayinput array

Example

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

splice from index until test fails

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

ParamTypeDescription
arrayArraythe input array
indexnumberthe position to begin splicing from
testRegExpthe 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' ]

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

ParamTypeDescription
arrayArraythe input array, modified directly
queryfunction | objectPer item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted

flatten an array of arrays into a single array

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

  • [ ] document

Example

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

© 2015 Lloyd Brookes 75pound@gmail.com. Documented by jsdoc-to-markdown.