object-tools


object-tools

Useful functions for working with objects

Example
``js
var o = require('object-tools')
`

* object-tools
* .extend(...object) ⇒ object
* .clone(input) ⇒ object | array
* .every(object, iterator) ⇒ boolean
* .each(object, callback)
* .exists(object, query) ⇒ boolean
* .without(object, toRemove) ⇒ object
* .where(object, query) ⇒ object
* .extract(object, query) ⇒ object
* .select(object, fields) ⇒ object
.get(object, expression) ⇒ \




$3

Merge a list of objects, left to right, into one - to a maximum depth of 10.

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| ...object | object | a sequence of object instances to be extended |

Example
`js
> o.extend({ one: 1, three: 3 }, { one: 'one', two: 2 }, { four: 4 })
{ one: 'one',
three: 3,
two: 2,
four: 4 }
`



$3

Clones an object or array

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| input | object | array | the input to clone |

Example
`js
> date = new Date()
Fri May 09 2014 13:54:34 GMT+0200 (CEST)
> o.clone(date)
{} // a Date instance doesn't own any properties
> date.clive = 'hater'
'hater'
> o.clone(date)
{ clive: 'hater' }
> array = [1,2,3]
[ 1, 2, 3 ]
> newArray = o.clone(array)
[ 1, 2, 3 ]
> array === newArray
false
`



$3

Returns true if the supplied iterator function returns true for every property in the object

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| object | object | the object to inspect |
| iterator | function | the iterator function to run against each key/value pair, the args are (value, key). |

Example
`js
> function aboveTen(input){ return input > 10; }
> o.every({ eggs: 12, carrots: 30, peas: 100 }, aboveTen)
true
> o.every({ eggs: 6, carrots: 30, peas: 100 }, aboveTen)
false
`



$3

Runs the iterator function against every key/value pair in the input object

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| object | object | the object to iterate |
| callback | function | the iterator function to run against each key/value pair, the args are (value, key). |

Example
`js
> var total = 0
> function addToTotal(n){ total += n; }
> o.each({ eggs: 3, celery: 2, carrots: 1 }, addToTotal)
> total
6
`



$3


returns true if the key/value pairs in query also exist identically in object.
Also supports RegExp values in query. If the query property begins with ! then test is negated.

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| object | object | the object to examine |
| query | object | the key/value pairs to look for |

Example
`js
> o.exists({ a: 1, b: 2}, {a: 0})
false
> o.exists({ a: 1, b: 2}, {a: 1})
true
> o.exists({ a: 1, b: 2}, {'!a': 1})
false
> o.exists({ name: 'clive hater' }, { name: /clive/ })
true
> o.exists({ name: 'clive hater' }, { '!name': /ian/ })
true
> o.exists({ a: 1}, { a: function(n){ return n > 0; } })
true
> o.exists({ a: 1}, { a: function(n){ return n > 1; } })
false
`



$3

Returns a clone of the object minus the specified properties. See also select.

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| object | object | the input object |
| toRemove | string | Array.<string> | a single property, or array of properties to omit |

Example
`js
> o.without({ a: 1, b: 2, c: 3}, 'b')
{ a: 1, c: 3 }
> o.without({ a: 1, b: 2, c: 3}, ['b', 'a'])
{ c: 3 }
`



$3

Returns a new object containing the key/value pairs which satisfy the query

Kind: static method of object-tools
Since: 1.2.0

| Param | Type | Description |
| --- | --- | --- |
| object | object | The input object |
| query | Array.<string> | function | Either an array of property names, or a function. The function is called with (value, key) and must return true to be included in the output. |

Example
`js
> object = { a: 1, b: 0, c: 2 }
{ a: 1, b: 0, c: 2 }
> o.where(object, function(value, key){
return value > 0
})
{ a: 1, c: 2 }
> o.where(object, [ 'b' ])
{ b: 0 }
> object
{ a: 1, b: 0, c: 2 }
`



$3


identical to o.where(object, query) with one exception - the found properties are removed from the input object

Kind: static method of object-tools
Since: 1.2.0

| Param | Type | Description |
| --- | --- | --- |
| object | object | The input object |
| query | Array.<string> | function | Either an array of property names, or a function. The function is called with (value, key) and must return true to be included in the output. |

Example
`js
> object = { a: 1, b: 0, c: 2 }
{ a: 1, b: 0, c: 2 }
> o.where(object, function(value, key){
return value > 0
})
{ a: 1, c: 2 }
> object
{ b: 0 }
``

$3

Returns a new object containing only the selected fields. See also without.

Kind: static method of object-tools

| Param | Type | Description |
| --- | --- | --- |
| object | object | the input object |
| fields | string | array | a list of fields to return |

$3

Returns the value at the given property.

Kind: static method of object-tools
Since: 1.4.0

| Param | Type | Description |
| --- | --- | --- |
| object | object | the input object |
| expression | string | the property accessor expression |

*

© 2014-16 Lloyd Brookes \<75pound@gmail.com\>. Documented by jsdoc-to-markdown.