this documentation is for the pre-release version

array-tools

Lightweight, use-anywhere toolkit for working with array data.

There are four ways to use it.

1. As a command-line tool. E.g. array-tools downloads last month:

$ curl -s https://api.npmjs.org/downloads/range/last-month/array-tools \
| object-tools get downloads \
| array-tools pluck downloads \
| array-tools join "," \
| spark
▂▅▃▅▅▁▁▃▄▃▆▂▂▁▁▂▄▃▃▁▁▂█▆▆▄▁▃▅▃

2. As a standard library, passing the input array on each method invocation:

> var a = require("array-tools");

> var remainder = a.without([ 1, 2, 3, 4, 5 ], 1)
> a.exists(remainder, 1)
false

3. As a chainable method, passing the input array once then chaining from there:

> a([ 1, 2, 3, 4, 5 ]).without(1).exists(1);
false

4. As a base class.

var util = require("util");
var ArrayTools = require("array-tools");

// this class will inherit all array-tools methods
function CarCollection(cars){
  ArrayTools.call(this, cars);
}
util.inherits(CarCollection, ArrayTools);

var cars = new CarCollection([ 
  { owner: "Me", model: "Citreon Xsara" }, 
  { owner: "Floyd", model: "Bugatti Veyron" } 
]);

cars.findWhere({ owner: "Floyd" });
// returns { owner: "Floyd", model: "Bugatti Veyron" }

More on chaining

• Each method returning an Array (e.g. where, without) can be chained.
• Methods not returning an array (exists, contains) cannot be chained.
• All methods from Array.prototype (e.g. .join, .forEach etc.) are also available in the chain. The same rules, regarding what can and cannot be chained, apply as above.
• If the final operation in your chain is "chainable" (returns an array), append .val() to terminate the chain and retrieve the output.

> 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 ]
> a([ 1, 2, 2, 3 ]).without(1).unique().join("-")
'2-3'

Compatibility

This library is tested in node versions 0.10, 0.11, 0.12, iojs and the following browsers:

Install

As a library:

$ npm install array-tools --save

As a command-line tool:

$ npm install -g array-tools

Using bower:

$ bower install array-tools --save

API Reference

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

a.arrayify(any) ⇒ Array

Takes any input and guarantees an array back.

• converts array-like objects (e.g. arguments) to a real array
• converts undefined to an empty array
• converts any another other, singular value (including null) into an array containing that value
• ignores input which is already an array

Kind: static method of array-tools
Category: chainable

Example

> a.arrayify(undefined)
[]

> a.arrayify(null)
[ 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.where(array, query) ⇒ Array

Deep query an array.

Kind: static method of array-tools
Category: chainable

Example
Say you have a recordset:

> data = [
    { name: "Dana", age: 30 },
    { name: "Yana", age: 20 },
    { name: "Zhana", age: 10 }
]

You can return records with properties matching an exact value:

> a.where(data, { age: 10 })
[ { name: 'Zhana', age: 10 } ]

or where NOT the value (prefix the property name with !)

> a.where(data, { "!age": 10 })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]

match using a function:

> function over10(age){ return age > 10; }
> a.where(data, { age: over10 })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]

match using a regular expression

> a.where(data, { name: /ana/ })
[ { name: 'Dana', age: 30 },
  { name: 'Yana', age: 20 },
  { name: 'Zhana', age: 10 } ]

You can query to any arbitrary depth. So with deeper data, like this:

> deepData = [
    { name: "Dana", favourite: { colour: "light red" } },
    { name: "Yana", favourite: { colour: "dark red" } },
    { name: "Zhana", favourite: { colour: [ "white", "red" ] } }
]

get records with favourite.colour values matching /red/

> a.where(deepData, { favourite: { colour: /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
  { name: 'Yana', favourite: { colour: 'dark red' } } ]

if the value you're looking for maybe part of an array, prefix the property name with +. Now Zhana is included:

> a.where(deepData, { favourite: { "+colour": /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
  { name: 'Yana', favourite: { colour: 'dark red' } },
  { name: 'Zhana', favourite: { colour: [ "white", "red" ] } } ]

you can combine any of the above by supplying an array of queries. Records will be returned if any of the queries match:

> var nameBeginsWithY = { name: /^Y/ };
> var faveColourIncludesWhite = { favourite: { "+colour": "white" } };

> a.where(deepData, [ nameBeginsWithY, faveColourIncludesWhite ])
[ { name: 'Yana', favourite: { colour: 'dark red' } },
  { name: 'Zhana', favourite: { colour: [ "white", "red" ] } } ]

a.without(array, toRemove) ⇒ Array

Returns a new array with the same content as the input minus the specified values. It accepts the same query syntax as where.

Kind: static method of array-tools
Category: chainable

Example

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

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

> data = [
    { name: "Dana", age: 30 },
    { name: "Yana", age: 20 },
    { name: "Zhana", age: 10 }
]
> a.without(data, { name: /ana/ })
[]

a.pluck(recordset, property) ⇒ Array

Returns an array containing the value of each specified property, if it exists.

Kind: static method of array-tools
Category: chainable

Example

> var data = [
    { a: "Lionel", b: "Roger" },
    { a: "Luis", b: "Craig" },
    { b: "Peter" },
]

> a.pluck(data, "a")
[ 'Lionel', 'Luis' ]

> a.pluck(data, "a", "b")
[ 'Lionel', 'Luis', 'Peter' ]

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

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

Kind: static method of array-tools
Category: chainable

Example

> data = [
    { name: "Dana", age: 30 },
    { name: "Yana", age: 20 },
    { name: "Zhana", age: 10 }
]

> a.pick(data, "name")
[ { name: 'Dana' }, { name: 'Yana' }, { name: 'Zhana' } ]

> a.pick(data, "name", "age")
[ { name: 'Dana', age: 30 },
  { name: 'Yana', age: 20 },
  { name: 'Zhana', age: 10 } ]

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

merge two arrays into a single array of unique values

Kind: static method of array-tools
Category: chainable

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: chainable

Example

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

a.unique(array) ⇒ Array

returns an array of unique values

Kind: static method of array-tools
Category: chainable

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: chainable

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: chainable

a.flatten(array) ⇒ Array

flatten an array of arrays into a single array

Kind: static method of array-tools
Category: chainable
Since: 1.4.0

Example

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

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

Sort an array of objects by one or more fields

Kind: static method of array-tools
Category: chainable
Since: 1.5.0

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, query) ⇒ boolean

returns true if a value, or nested object value exists in an array.. If value is a plain object, it is considered to be a query. If value is a plain object and you want to search for it by reference, use .contains.

Kind: static method of array-tools
Category: not chainable

Example

> a.exists([ 1, 2, 3 ], 2)
true

> a.exists([ 1, 2, 3 ], [ 2, 3 ])
true

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

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

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

a.findWhere(recordset, query) ⇒ object

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

Kind: static method of array-tools
Category: not chainable

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.last(arr) ⇒ *

Return the last item in an array.

Kind: static method of array-tools
Category: not chainable
Since: 1.7.0

a.remove(arr, toRemove) ⇒ *

Kind: static method of array-tools
Category: not chainable
Since: 1.8.0

a.contains(array, value) ⇒

Searches the array for the exact value supplied (strict equality). To query for value existance using an expression or function, use exists. If you pass an array of values, contains will return true if they all exist. (note: exists returns true if some of them exist).

Kind: static method of array-tools
Returns: boolean
Category: not chainable
Since: 1.8.0

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