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

• 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

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

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.