array-tools

Lightweight tool-kit for working with arrays.

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

There are three ways to use it. As a standard library, passing the input array on each invocation:

> 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");

function CarCollection(cars){
  ArrayTools.call(this, cars);
}
util.inherits(CarCollection, ArrayTools);

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

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

More on chaining

Each methods returning an Array (e.g. where, without) can be chained. Each method returning a scalar (exists, contains) cannot be chained. If the final operation is chainable, append .val() to terminate the chain an retrieve the output data.

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

API Reference

• 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

a.remove(arr, toRemove) ⇒ *

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

a.contains(arr, value) ⇒

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

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