array-tools

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

There are four ways to use it.

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
▂▅▃▅▅▁▁▃▄▃▆▂▂▁▁▂▄▃▃▁▁▂█▆▆▄▁▃▅▃

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

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

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

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'

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>
  - .unique(array) ⇒ Array
  - .spliceWhile(array, index, test, [...elementN]) ⇒ Array
  - .extract(array, query) ⇒ Array
  - .flatten(array) ⇒ Array
  - .sortBy() ⇒ Array
- not chainable
  - .exists(array, query) ⇒ boolean
  - .findWhere(recordset, query) ⇒ *
  - .remove(arr, toRemove) ⇒ *
  - .last(arr) ⇒ *
  - .contains(array, value) ⇒ boolean

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

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

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

Param	Type	Description
array	`Array.<object>`	the array to query
query	`any` \| `Array.<any>`	one or more queries

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

Param	Type	Description
array	`Array`	the input array
toRemove	`any` \| `Array.<any>`	one, or more queries

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 each value plucked from the specified property of each object in the input array.

Kind: static method of array-tools
Category: chainable

Param	Type	Description
recordset	`Array.<object>`	The input recordset
property	`string` \| `Array.<string>`	Property name, or an array of property names. If an array is supplied, the first existing property will be returned.

Example
with this data..

> var data = [
    { name: "Pavel", nick: "Pasha" },
    { name: "Richard", nick: "Dick" },
    { name: "Trevor" },
]

pluck all the nicknames

> a.pluck(data, "nick")
[ 'Pasha', 'Dick' ]

in the case no nickname exists, take the name instead:

> a.pluck(data, [ "nick", "name" ])
[ 'Pasha', 'Dick', 'Trevor' ]

the values being plucked can be at any depth:

> var data = [
    { leeds: { leeds: { leeds: "we" } } },
    { leeds: { leeds: { leeds: "are" } } },
    { leeds: { leeds: { leeds: "Leeds" } } }
]

> a.pluck(data, "leeds.leeds.leeds")
[ 'we', 'are', 'Leeds' ]

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

Param	Type	Description
recordset	`Array.<object>`	the input
property	`string` \| `Array.<string>`	the properties to include in the result

Example
with this data..

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

return only the "name" field..

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

return both the "name" and "age" fields

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

cherry-picks fields at any depth:

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

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

> a.pick(data, "person.age")
[ { age: 30 }, { age: 20 }, { age: 10 } ]

a.unique(array) ⇒ `Array`

Returns an array containing the unique values from the input array.

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array	`Array`	input array

Example

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

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

Splice items from the input array until the matching test fails. Returns an array containing the items removed.

Kind: static method of array-tools
Category: chainable

Param	Type	Description
array	`Array`	the input array
index	`number`	the position to begin splicing from
test	`any`	the sequence of items passing this test will be removed
[...elementN]	`*`	elements to add to the array in place

Example

> function under10(n){ return n < 10; }
> numbers = [ 1, 2, 4, 6, 12 ]

> a.spliceWhile(numbers, 0, under10)
[ 1, 2, 4, 6 ]
> numbers
[ 12 ]

> countries = [ "Egypt", "Ethiopia", "France", "Argentina" ]

> a.spliceWhile(countries, 0, /^e/i)
[ 'Egypt', 'Ethiopia' ]
> countries
[ 'France', 'Argentina' ]

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

Param	Type	Description
array	`Array`	the input array, modified directly
query	`any`	if an item in the input array passes this test it is removed

Example

> DJs = [
    { name: "Trevor", sacked: true },
    { name: "Mike", sacked: true },
    { name: "Chris", sacked: false },
    { name: "Alan", sacked: false }
]

> a.extract(DJs, { sacked: true })
[ { name: 'Trevor', sacked: true },
  { name: 'Mike', sacked: true } ]

> DJs
[ { name: 'Chris', sacked: false },
  { name: 'Alan', sacked: false } ]

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

Param	Type	Description
array	`Array`	the input array

Example

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

a.sortBy() ⇒ `Array`

Sort an array of objects by one or more fields

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

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

Example
with this data

> DJs = [
    { name: "Trevor", slot: "twilight" },
    { name: "Chris", slot: "twilight" },
    { name: "Mike", slot: "afternoon" },
    { name: "Rodney", slot: "morning" },
    { name: "Chris", slot: "morning" },
    { name: "Zane", slot: "evening" }
]

sort by slot using the default sort order

> a.sortBy(DJs, "slot")
[ { name: 'Mike', slot: 'afternoon' },
  { name: 'Zane', slot: 'evening' },
  { name: 'Chris', slot: 'morning' },
  { name: 'Rodney', slot: 'morning' },
  { name: 'Chris', slot: 'twilight' },
  { name: 'Trevor', slot: 'twilight' } ]

specify a custom sort order for slot

> a.sortBy(DJs, "slot", { slot: [ "morning", "afternoon", "evening", "twilight" ]})
[ { name: 'Rodney', slot: 'morning' },
  { name: 'Chris', slot: 'morning' },
  { name: 'Mike', slot: 'afternoon' },
  { name: 'Zane', slot: 'evening' },
  { name: 'Trevor', slot: 'twilight' },
  { name: 'Chris', slot: 'twilight' } ]

sort by slot then name

> a.sortBy(DJs, ["slot", "name"], { slot: [ "morning", "afternoon", "evening", "twilight" ]})
[ { name: 'Chris', slot: 'morning' },
  { name: 'Rodney', slot: 'morning' },
  { name: 'Mike', slot: 'afternoon' },
  { name: 'Zane', slot: 'evening' },
  { name: 'Chris', slot: 'twilight' },
  { name: 'Trevor', slot: 'twilight' } ]

a.exists(array, query) ⇒ `boolean`

Works in exactly the same way as where but returning a boolean indicating whether a matching record exists.

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

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

Example

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

> a.exists(data, { age: 10 })
true

a.findWhere(recordset, query) ⇒ `*`

Works in exactly the same way as where but returns only the first item found.

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

Param	Type	Description
recordset	`Array.<object>`	the array to search
query	`object`	the search query

Example

> dudes = [
    { name: 'Jim', age: 8 },
    { name: 'Clive', age: 8 },
    { name: 'Hater', age: 9 }
]

> a.findWhere(dudes, { age: 8 })
{ name: 'Jim', age: 8 }

a.remove(arr, toRemove) ⇒ `*`

Removes the specified value from the input array.

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

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

Example

> numbers = [ 1, 2, 3 ]
> a.remove(numbers, 1)
[ 1 ]

> numbers
[ 2, 3 ]

a.last(arr) ⇒ `*`

Return the last item in an array.

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

Param	Type	Description
arr	`Array`	the input array

a.contains(array, value) ⇒ `boolean`

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
Category: not chainable
Since: 1.8.0

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

Current Tags

2.0.9 ... latest (10 years ago)

array-tools

More on chaining

Install

API Reference

a.arrayify(any) ⇒ Array

a.where(array, query) ⇒ Array

a.without(array, toRemove) ⇒ Array

a.pluck(recordset, property) ⇒ Array

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

a.unique(array) ⇒ Array

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

a.extract(array, query) ⇒ Array

a.flatten(array) ⇒ Array

a.sortBy() ⇒ Array

a.exists(array, query) ⇒ boolean

a.findWhere(recordset, query) ⇒ *

a.remove(arr, toRemove) ⇒ *

a.last(arr) ⇒ *

a.contains(array, value) ⇒ boolean

Current Tags

53 Versions

a.arrayify(any) ⇒ `Array`

a.where(array, query) ⇒ `Array`

a.without(array, toRemove) ⇒ `Array`

a.pluck(recordset, property) ⇒ `Array`

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

a.unique(array) ⇒ `Array`

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

a.extract(array, query) ⇒ `Array`

a.flatten(array) ⇒ `Array`

a.sortBy() ⇒ `Array`

a.exists(array, query) ⇒ `boolean`

a.findWhere(recordset, query) ⇒ `*`

a.remove(arr, toRemove) ⇒ `*`

a.last(arr) ⇒ `*`

a.contains(array, value) ⇒ `boolean`