🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more →
Socket
Book a DemoInstallSign in
Socket
Book a DemoInstallSign in

array-tools

Package Overview
Dependencies
Maintainers
1
Versions
53
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

array-tools - npm Package Compare versions

Comparing version

1.8.5
to
1.8.6

249

lib/array-tools.js
"use strict";
/* set module.exports above the requires: avoids circular reference issues with object-tools */
/* set module.exports above the requires: necessary to avoid circular reference issues with object-tools */
module.exports = ArrayTools;

@@ -77,20 +77,115 @@

/**
Takes any input and guarantees an array back.
- converts array-like objects (e.g. `arguments`) to a real array
- converts `null` or `undefined` to an empty array
- converts any another other, singular value into an array containing that value
- ignores input which is already an array
@param {*} - the input value to convert to an array
@returns {Array}
@category chainable
@static
@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 ]
*/
function arrayify(any){
if (any === null || any === undefined){
return [];
} else if (t.isArrayLike(any)){
return Array.prototype.slice.call(any);
} else {
return Array.isArray(any) ? any : [ any ];
}
}
/**
Query a recordset, at any depth..
@param {object[]} - the recordset to query
@param {query} - the query definition
@returns {Array}
@category chainable
@static
@example
> data = [
{ name: "Dana", age: 30 },
{ name: "Yana", age: 20 },
{ name: "Zhana", age: 10 }
]
> // match on an exact value
> a.where(data, { age: 10 })
[ { name: 'Zhana', age: 10 } ]
> // match records which satisfy the function testing the value of the `age` field
> a.where(data, { age: function(ageValue){ return ageValue > 10; } })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]
> // match if NOT the value
> a.where(data, { "!age": 10 })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]
> // match on regular expression
> a.where(data, { name: /ana/ })
[ { name: 'Dana', age: 30 },
{ name: 'Yana', age: 20 },
{ name: 'Zhana', age: 10 } ]
> // you can perform deep queries
> deepData = [
{ name: "Dana", favourite: { colour: "light red" } },
{ name: "Yana", favourite: { colour: "dark red" } },
{ name: "Zhana", favourite: { colour: [ "white", "red" ] } }
]
> // match values of `person.favourite.colour` which match the regex `/red/`
> a.where(deepData, { favourite: { colour: /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
{ name: 'Yana', favourite: { colour: 'dark red' } } ]
> // if there are one or more values for colour (i.e. the field may contain a singular
> // or array of values) then search inside arrays too
> a.where(deepData, { favourite: { "+colour": /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
{ name: 'Yana', favourite: { colour: 'dark red' } },
{ name: 'Zhana', favourite: { colour: [ "white", "red" ] } } ]
*/
function where(arrayOfObjects, query){
return arrayify(arrayOfObjects).filter(function(item){
return o.exists(item, query);
});
}
/**
Plucks the value of the specified property from each object in the input array
@param arrayOfObjects {object[]} - the input array of objects
@param property {...string} - the property(s) to pluck
@param arrayOfObjects {object[]} - The input recordset
@param property {...string} - Up to three property names - the first one found will be returned.
@returns {Array}
@category record set in
@category chainable
@static
@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' ]
@alias module:array-tools.pluck
{ a: "Lionel", b: "Roger" },
{ a: "Luis", b: "Craig" },
{ b: "Peter" },
]
> a.pluck(data, "a")
[ 'Lionel', 'Luis' ]
> a.pluck(data, "a", "b")
[ 'Lionel', 'Luis', 'Peter' ]
*/

@@ -120,14 +215,17 @@ function pluck(arrayOfObjects, property, property2, property3){

@return {object[]}
@category record set in
@category chainable
@example
> data = [
{ one: "un", two: "deux", three: "trois" },
{ two: "two", one: "one" },
{ four: "quattro" },
{ two: "zwei" }
{ name: "Dana", age: 30 },
{ name: "Yana", age: 20 },
{ name: "Zhana", age: 10 }
]
> a.pick(data, "two")
[ { two: 'deux' },
{ two: 'two' },
{ two: 'zwei' } ]
> 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 } ]
@alias module:array-tools.pick

@@ -160,34 +258,2 @@ */

/**
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
@param {*} - the input value to convert to an array
@returns {Array}
@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 ]
@alias module:array-tools.arrayify
*/
function arrayify(any){
if (any === null || any === undefined){
return [];
} else if (t.isArrayLike(any)){
return Array.prototype.slice.call(any);
} else {
return Array.isArray(any) ? any : [ any ];
}
}
/**
returns true if a value, or nested object value exists in an array

@@ -197,20 +263,23 @@ @param {Array} - the array to search

@returns {boolean}
@category single array in
@category not chainable
@static
@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
@alias module:array-tools.exists
*/
function exists(array, value){
if (t.isPlainObject(value)){
var query = value,
found = false,
index = 0,
item;
var query = value;
var found = false;
var index = 0;
var item;

@@ -227,25 +296,2 @@ while(!found && (item = array[index++])){

/**
returns an array containing items from `arrayOfObjects` where key/value pairs
from `query` are matched identically
@param {object[]} - the array to search
@param {query} - an object containing the key/value pairs you want to match
@returns {Array}
@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 } ]
@alias module:array-tools.where
*/
function where(arrayOfObjects, query){
return arrayify(arrayOfObjects).filter(function(item){
return o.exists(item, query);
});
}
/**
returns the first item from `arrayOfObjects` where key/value pairs

@@ -256,3 +302,3 @@ from `query` are matched identically

@returns {object}
@category record set in
@category not chainable
@example

@@ -263,2 +309,3 @@ > dudes = [{ name: "Jim", age: 8}, { name: "Clive", age: 8}, { name: "Hater", age: 9}]

{ name: 'Hater', age: 9 } ]
> a.findWhere(dudes, { age: 8})

@@ -279,6 +326,7 @@ { name: 'Jim', age: 8 }

@returns {Array}
@category single array in
@category chainable
@example
> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])

@@ -301,3 +349,3 @@ [ 1 ]

@returns {Array}
@category multiple arrays in
@category chainable
@example

@@ -307,5 +355,7 @@ > var array1 = [ 1, 2 ], array2 = [ 2, 3 ];

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

@@ -342,3 +392,3 @@ > a.union(array1, array2)

@returns {Array}
@category multiple arrays in
@category chainable
@example

@@ -365,6 +415,7 @@ > a.commonSequence([1,2,3], [1,2,4])

@returns {Array}
@category single array in
@category chainable
@example
> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]
> a.unique(n)

@@ -388,8 +439,10 @@ [ 1, 6, 7 ]

@returns {Array}
@category single array in
@category chainable
@example
> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]
> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]
> letters

@@ -413,3 +466,3 @@ [ 'x', 'b' ]

@returns {Array} the extracted items.
@category single array in
@category chainable
@alias module:array-tools.extract

@@ -445,3 +498,3 @@ */

@returns {Array}
@category single array in
@category chainable
@example

@@ -465,3 +518,3 @@ > numbers = [ 1, 2, [ 3, 4 ], 5 ]

@returns {Array}
@category record set in
@category chainable
@since 1.5.0

@@ -534,3 +587,3 @@ @example

@param {Array} - the input array
@category single array in
@category not chainable
@return {*}

@@ -547,3 +600,3 @@ @static

@param {*} - the item to remove
@category single array in
@category not chainable
@return {*}

@@ -558,5 +611,7 @@ @static

/**
Searches the array for the exact value supplied (strict equality). To query for value existance using an expression or function, use {@link module:array-tools.exists}.
@param {Array} - the input array
@param {*} - the value to look for
@category single array in
@category not chainable
@return boolean

@@ -563,0 +618,0 @@ @static

6

package.json
{
"name": "array-tools",
"author": "Lloyd Brookes <75pound@gmail.com>",
"version": "1.8.5",
"version": "1.8.6",
"description": "Lightweight tool-kit for working with arrays",

@@ -28,8 +28,8 @@ "repository": "https://github.com/75lb/array-tools.git",

"test": "tape test/*.js",
"test-travis": "zuul -- test/*.js",
"lint": "jshint lib/*.js test/*.js; echo",
"docs": "jsdoc2md -t jsdoc2md/README.hbs lib/*.js > README.md; echo",
"watch": "baldrick --do 'npm run docs' --when lib/*.js --change"
"cover": "istanbul cover ./node_modules/.bin/tape test/*.js && cat coverage/lcov.info | ./node_modules/.bin/coveralls && rm -rf coverage; echo"
},
"devDependencies": {
"coveralls": "^2.11.2",
"jsdoc-to-markdown": "^1.0.3",

@@ -36,0 +36,0 @@ "tape": "^4"

435

README.md

@@ -5,14 +5,15 @@ [![view on npm](http://img.shields.io/npm/v/array-tools.svg)](https://www.npmjs.org/package/array-tools)

[![Dependency Status](https://david-dm.org/75lb/array-tools.svg)](https://david-dm.org/75lb/array-tools)
[![Coverage Status](https://coveralls.io/repos/75lb/array-tools/badge.svg?branch=master)](https://coveralls.io/r/75lb/array-tools?branch=master)
# array-tools
Lightweight tool-kit for working with arrays.
Lightweight tool-kit for working with array data. 1.5k, compressed.
```js
> 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:
There are four ways to use it.
1) As a standard library, passing the input array on each method invocation:
```js

@@ -24,3 +25,3 @@ > var remainder = a.without([ 1, 2, 3, 4, 5 ], 1)

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

@@ -32,3 +33,3 @@ ```js

As a base class.
3) As a base class.
```js

@@ -45,14 +46,30 @@ var util = require("util");

{ owner: "Me", model: "Citreon Xsara" },
{ owner: "Floyd", model: "Bugatti Veron" }
{ owner: "Floyd", model: "Bugatti Veyron" }
]);
cars.findWhere({ owner: "Floyd" });
// returns { owner: "Floyd", model: "Bugatti Veron" }
// returns { owner: "Floyd", model: "Bugatti Veyron" }
```
4) As a command-line tool.
```sh
$ curl -s "https://api.github.com/users/75lb/repos?page=1&per_page=100" | array-tools pick full_name description
[
{
"full_name": "75lb/ansi-escape-sequences",
"description": "A simple library containing all known terminal ansi escape codes and sequences."
},
{
"full_name": "75lb/baldrick",
"description": "Your own private dogsbody. Does the shitty work you can't be arsed to do."
},
etc,
etc
]
```
#### 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.
Each method returning an `Array` (e.g. `where`, `without`) can be chained. Methods not returning an array (`exists`, `contains`) cannot be chained. If the final operation in your chain is chainable (returns an array), append `.val()` to terminate the chain and retrieve the output.
```js
> var a = require("array-tools");
> a([ 1, 2, 2, 3 ]).exists(1)

@@ -66,19 +83,30 @@ true

## Compatibility
This library is tested in node versions 0.10, 0.11, 0.12, iojs and the following browsers:
[![Sauce Test Status](https://saucelabs.com/browser-matrix/arr-tools.svg)](https://saucelabs.com/u/arr-tools)
## Install
As a library:
```
$ npm install array-tools --save
```
As a command-line tool:
```
$ npm install -g array-tools
```
## API Reference
* [array-tools](#module_array-tools)
* _any value in_
* _chainable_
* [.arrayify(any)](#module_array-tools.arrayify) ⇒ <code>Array</code>
* _multiple arrays in_
* [.union(array1, array2, idKey)](#module_array-tools.union) ⇒ <code>Array</code>
* [.commonSequence(a, b)](#module_array-tools.commonSequence) ⇒ <code>Array</code>
* _record set in_
* [.where(arrayOfObjects, query)](#module_array-tools.where) ⇒ <code>Array</code>
* [.pluck(arrayOfObjects, ...property)](#module_array-tools.pluck) ⇒ <code>Array</code>
* [.pick(arrayOfObjects, ...property)](#module_array-tools.pick) ⇒ <code>Array.&lt;object&gt;</code>
* [.where(arrayOfObjects, query)](#module_array-tools.where) ⇒ <code>Array</code>
* [.findWhere(arrayOfObjects, query)](#module_array-tools.findWhere) ⇒ <code>object</code>
* [.sortBy(arrayOfObjects, columns, customOrder)](#module_array-tools.sortBy) ⇒ <code>Array</code>
* _single array in_
* [.exists(array, value)](#module_array-tools.exists) ⇒ <code>boolean</code>
* [.without(array, toRemove)](#module_array-tools.without) ⇒ <code>Array</code>
* [.union(array1, array2, idKey)](#module_array-tools.union) ⇒ <code>Array</code>
* [.commonSequence(a, b)](#module_array-tools.commonSequence) ⇒ <code>Array</code>
* [.unique(array)](#module_array-tools.unique) ⇒ <code>Array</code>

@@ -88,2 +116,6 @@ * [.spliceWhile(array, index, test, ...elementN)](#module_array-tools.spliceWhile) ⇒ <code>Array</code>

* [.flatten(array)](#module_array-tools.flatten) ⇒ <code>Array</code>
* [.sortBy(arrayOfObjects, columns, customOrder)](#module_array-tools.sortBy) ⇒ <code>Array</code>
* _not chainable_
* [.exists(array, value)](#module_array-tools.exists) ⇒ <code>boolean</code>
* [.findWhere(arrayOfObjects, query)](#module_array-tools.findWhere) ⇒ <code>object</code>
* [.last(arr)](#module_array-tools.last) ⇒ <code>\*</code>

@@ -95,10 +127,11 @@ * [.remove(arr, toRemove)](#module_array-tools.remove) ⇒ <code>\*</code>

### a.arrayify(any) ⇒ <code>Array</code>
Takes input and guarantees an array back. Result can be one of three things:
Takes any input and guarantees an array back.
- puts a single scalar in an array
- converts array-like object (e.g. `arguments`) to a real array
- converts array-like objects (e.g. `arguments`) to a real array
- converts `null` or `undefined` to an empty array
- converts any another other, singular value into an array containing that value
- ignores input which is already an array
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: any value in
**Category**: chainable

@@ -113,6 +146,9 @@ | Param | Type | Description |

[]
> a.arrayify(0)
[ 0 ]
> a.arrayify([ 1, 2 ])
[ 1, 2 ]
> function f(){ return a.arrayify(arguments); }

@@ -122,2 +158,133 @@ > f(1,2,3)

```
<a name="module_array-tools.where"></a>
### a.where(arrayOfObjects, query) ⇒ <code>Array</code>
Query a recordset, at any depth..
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the recordset to query |
| query | <code>query</code> | the query definition |
**Example**
```js
> data = [
{ name: "Dana", age: 30 },
{ name: "Yana", age: 20 },
{ name: "Zhana", age: 10 }
]
> // match on an exact value
> a.where(data, { age: 10 })
[ { name: 'Zhana', age: 10 } ]
> // match records which satisfy the function testing the value of the `age` field
> a.where(data, { age: function(ageValue){ return ageValue > 10; } })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]
> // match if NOT the value
> a.where(data, { "!age": 10 })
[ { name: 'Dana', age: 30 }, { name: 'Yana', age: 20 } ]
> // match on regular expression
> a.where(data, { name: /ana/ })
[ { name: 'Dana', age: 30 },
{ name: 'Yana', age: 20 },
{ name: 'Zhana', age: 10 } ]
> // you can perform deep queries
> deepData = [
{ name: "Dana", favourite: { colour: "light red" } },
{ name: "Yana", favourite: { colour: "dark red" } },
{ name: "Zhana", favourite: { colour: [ "white", "red" ] } }
]
> // match values of `person.favourite.colour` which match the regex `/red/`
> a.where(deepData, { favourite: { colour: /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
{ name: 'Yana', favourite: { colour: 'dark red' } } ]
> // if there are one or more values for colour (i.e. the field may contain a singular
> // or array of values) then search inside arrays too
> a.where(deepData, { favourite: { "+colour": /red/ } })
[ { name: 'Dana', favourite: { colour: 'light red' } },
{ name: 'Yana', favourite: { colour: 'dark red' } },
{ name: 'Zhana', favourite: { colour: [ "white", "red" ] } } ]
```
<a name="module_array-tools.pluck"></a>
### a.pluck(arrayOfObjects, ...property) ⇒ <code>Array</code>
Plucks the value of the specified property from each object in the input array
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | The input recordset |
| ...property | <code>string</code> | Up to three property names - the first one found will be returned. |
**Example**
```js
> 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 name="module_array-tools.pick"></a>
### a.pick(arrayOfObjects, ...property) ⇒ <code>Array.&lt;object&gt;</code>
return a copy of the input `arrayOfObjects` containing objects having only the cherry-picked properties
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the input |
| ...property | <code>string</code> | the properties to include in the result |
**Example**
```js
> 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 name="module_array-tools.without"></a>
### a.without(array, toRemove) ⇒ <code>Array</code>
Returns the input minus the specified values.
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | the input array |
| toRemove | <code>\*</code> | a single, or array of values to omit |
**Example**
```js
> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]
```
<a name="module_array-tools.union"></a>

@@ -128,3 +295,3 @@ ### a.union(array1, array2, idKey) ⇒ <code>Array</code>

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: multiple arrays in
**Category**: chainable

@@ -142,5 +309,7 @@ | Param | Type | Description |

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

@@ -160,3 +329,3 @@ > a.union(array1, array2)

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: multiple arrays in
**Category**: chainable

@@ -173,97 +342,76 @@ | Param | Type | Description |

```
<a name="module_array-tools.pluck"></a>
### a.pluck(arrayOfObjects, ...property) ⇒ <code>Array</code>
Plucks the value of the specified property from each object in the input array
<a name="module_array-tools.unique"></a>
### a.unique(array) ⇒ <code>Array</code>
returns an array of unique values
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: record set in
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the input array of objects |
| ...property | <code>string</code> | the property(s) to pluck |
| array | <code>Array</code> | input array |
**Example**
```js
> 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' ]
> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]
> a.unique(n)
[ 1, 6, 7 ]
```
<a name="module_array-tools.pick"></a>
### a.pick(arrayOfObjects, ...property) ⇒ <code>Array.&lt;object&gt;</code>
return a copy of the input `arrayOfObjects` containing objects having only the cherry-picked properties
<a name="module_array-tools.spliceWhile"></a>
### a.spliceWhile(array, index, test, ...elementN) ⇒ <code>Array</code>
splice from `index` until `test` fails
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: record set in
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the input |
| ...property | <code>string</code> | the properties to include in the result |
| array | <code>Array</code> | the input array |
| index | <code>number</code> | the position to begin splicing from |
| test | <code>RegExp</code> | the test to continue splicing while true |
| ...elementN | <code>\*</code> | the elements to add to the array |
**Example**
```js
> 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' } ]
> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]
> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]
> letters
[ 'x', 'b' ]
```
<a name="module_array-tools.where"></a>
### a.where(arrayOfObjects, query) ⇒ <code>Array</code>
returns an array containing items from `arrayOfObjects` where key/value pairs
from `query` are matched identically
<a name="module_array-tools.extract"></a>
### a.extract(array, query) ⇒ <code>Array</code>
Removes items from `array` which satisfy the query. Modifies the input array, returns the extracted.
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: record set in
**Returns**: <code>Array</code> - the extracted items.
**Category**: chainable
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the array to search |
| query | <code>query</code> | an object containing the key/value pairs you want to match |
| array | <code>Array</code> | the input array, modified directly |
| query | <code>function</code> &#124; <code>object</code> | Per item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted |
**Example**
```js
> 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 name="module_array-tools.findWhere"></a>
### a.findWhere(arrayOfObjects, query) ⇒ <code>object</code>
returns the first item from `arrayOfObjects` where key/value pairs
from `query` are matched identically
<a name="module_array-tools.flatten"></a>
### a.flatten(array) ⇒ <code>Array</code>
flatten an array of arrays into a single array
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: record set in
**Category**: chainable
**Since**: 1.4.0
| Param | Type | Description |
| --- | --- | --- |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the array to search |
| query | <code>object</code> | an object containing the key/value pairs you want to match |
| array | <code>Array</code> | the input array |
**Example**
```js
> 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 }
> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]
```

@@ -275,3 +423,3 @@ <a name="module_array-tools.sortBy"></a>

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: record set in
**Category**: chainable
**Since**: 1.5.0

@@ -314,3 +462,3 @@

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
**Category**: not chainable

@@ -326,100 +474,35 @@ | Param | Type | Description |

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 name="module_array-tools.without"></a>
### a.without(array, toRemove) ⇒ <code>Array</code>
Returns the input minus the specified values.
<a name="module_array-tools.findWhere"></a>
### a.findWhere(arrayOfObjects, query) ⇒ <code>object</code>
returns the first item from `arrayOfObjects` where key/value pairs
from `query` are matched identically
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
**Category**: not chainable
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | the input array |
| toRemove | <code>\*</code> | a single, or array of values to omit |
| arrayOfObjects | <code>Array.&lt;object&gt;</code> | the array to search |
| query | <code>object</code> | an object containing the key/value pairs you want to match |
**Example**
```js
> a.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> a.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]
```
<a name="module_array-tools.unique"></a>
### a.unique(array) ⇒ <code>Array</code>
returns an array of unique values
> 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 } ]
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | input array |
**Example**
```js
> n = [1,6,6,7,1]
[ 1, 6, 6, 7, 1 ]
> a.unique(n)
[ 1, 6, 7 ]
> a.findWhere(dudes, { age: 8})
{ name: 'Jim', age: 8 }
```
<a name="module_array-tools.spliceWhile"></a>
### a.spliceWhile(array, index, test, ...elementN) ⇒ <code>Array</code>
splice from `index` until `test` fails
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | the input array |
| index | <code>number</code> | the position to begin splicing from |
| test | <code>RegExp</code> | the test to continue splicing while true |
| ...elementN | <code>\*</code> | the elements to add to the array |
**Example**
```js
> letters = ["a", "a", "b"]
[ 'a', 'a', 'b' ]
> a.spliceWhile(letters, 0, /a/, "x")
[ 'a', 'a' ]
> letters
[ 'x', 'b' ]
```
<a name="module_array-tools.extract"></a>
### a.extract(array, query) ⇒ <code>Array</code>
Removes items from `array` which satisfy the query. Modifies the input array, returns the extracted.
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Returns**: <code>Array</code> - the extracted items.
**Category**: single array in
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | the input array, modified directly |
| query | <code>function</code> &#124; <code>object</code> | Per item in the array, if either the function returns truthy or the exists query is satisfied, the item is extracted |
<a name="module_array-tools.flatten"></a>
### a.flatten(array) ⇒ <code>Array</code>
flatten an array of arrays into a single array
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
**Since**: 1.4.0
| Param | Type | Description |
| --- | --- | --- |
| array | <code>Array</code> | the input array |
**Example**
```js
> numbers = [ 1, 2, [ 3, 4 ], 5 ]
> a.flatten(numbers)
[ 1, 2, 3, 4, 5 ]
```
<a name="module_array-tools.last"></a>

@@ -430,3 +513,3 @@ ### a.last(arr) ⇒ <code>\*</code>

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
**Category**: not chainable
**Since**: 1.7.0

@@ -441,3 +524,3 @@

**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Category**: single array in
**Category**: not chainable
**Since**: 1.8.0

@@ -452,5 +535,7 @@

### a.contains(arr, value) ⇒
Searches the array for the exact value supplied (strict equality). To query for value existance using an expression or function, use [exists](#module_array-tools.exists).
**Kind**: static method of <code>[array-tools](#module_array-tools)</code>
**Returns**: boolean
**Category**: single array in
**Category**: not chainable
**Since**: 1.8.0

@@ -457,0 +542,0 @@

15

test/exists.js

@@ -1,5 +0,5 @@

var test = require("tape"),
a = require("../");
var test = require("tape");
var a = require("../");
test("exists: search for object value", function(t){
test("exists: query a recordset", function(t){
var arr = [

@@ -24,1 +24,10 @@ { result: false, number: 1 },

});
test.skip("exists: search an object", function(t){
var obj1 = {};
var obj2 = {};
var arr = [ obj1, {} ];
t.equal(a.exists(arr, obj1), true);
t.equal(a.exists(arr, obj2), false);
t.end();
});
.npmignore

Sorry, the diff of this file is not supported yet

.zuul.yml

Sorry, the diff of this file is not supported yet

jsdoc2md/README.hbs

Sorry, the diff of this file is not supported yet