deep

0.0.2 • Public • Published

deep

This library contains utilities for manipulating deeply-nested data structures. These functions only perform recursive traversal of arrays and "plain" objects, that is, those objects that were created using object literals ({}) or new Object.

Installation

npm install deep

Function reference

isPlainObject(object)

deep.isPlainObject({}); // true
deep.isPlainObject(new Object); // true
deep.isPlainObject([]); // false
deep.isPlainObject(new function(){}); // false

This function works by checking to see if the argument's constructor's name is Object.


clone(object)

= {
  a: 1,
  b: [ 2, 3, function(arg) { return arg; } ]
};
 
= deep.clone(x) // -> deep-copies x, preserving references to nested functions

This will preserve references to all non-array, non-plain objects, including functions.


equals(a, b)

= b = [1, 2, 3]
deep.equals(a, b) // true
 
= [1, 2, 3]
= [1, 2, 3]
deep.equals(a, b) // true
 
= [1, 2, 3]
= [1, 2, 4]
deep.equals(a, b) // false
 
= b = {x: 1, y: 2}
deep.equals(a, b) // true
 
= {x: 1, y: 2}
= {x: 1, y: 2}
deep.equals(a, b) // true
 
= b = new Buffer
deep.equals(a, b) // true
 
= new Buffer
= new Buffer
deep.equals(a, b) // false
 
= [1, 2, {x: 3, y: 4}]
= [1, 2, {x: 3, y: 4}]
deep.equals(a, b) //true
 
= {x: 1, y: [2, 3], z: {a: 4, b: 5}}
= {z: {a: 4, b: 5}, y: [2, 3], x: 1}
deep.equals(a, b) // true

Recursively compares nested arrays and plain objects, and returns true if the objects are structurally identical. Comparison is made with the strict identity operator (===). Variables containing references to non-plain objects are only considered equal is the references themselves are the same, regardless of the internal structure of the objects.

Since JavaScript objects do not have a defined order for their keys, plain objects whose keys were defined in different order but are otherwise identical are considered equal.


extend(destination, source, ...)

= { a: { b: { c: 1 } }, d: 2, e: 3 }
= { a: { b: { c: 4, f: 5 }, d: 6, g: 7 } }
= { a: { b: { c: 8 } }, h: 9 }
 
deep.extend(x, y, z)
 
// x -> { a: { b: { c: 8, f: 5 }, d: 6, e: 3, g: 7 }, h: 9 }

Recursively merges each source object into destination, preserving any nested structure common among the sources. Precedence is given to the rightmost sources.


select(root, filter)

= {
  a: 1,
  b: [ 2, 3, 'hello' ]
};
 
deep.select(x, function(obj) { return typeof obj == 'number' } );
 
// -> [
//      { value: 1, path: [ 'a' ] },
//      { value: 2, path: [ 'b', '0' ] },
//      { value: 3, path: [ 'c', '1' ] }
//    ]

Recursively traverses arrays and plain objects for any values that satisfy the test defined by the filter function. The path of references to each value is returned.


set(root, path, value)

= { a: { b: [ { c: 5 } ] } }
deep.set(x, ['a', 'b', 0, 'c'], 'hello');
 
// x -> { a: { b: [ { c: 'hello' } ] } }

Inserts value into the root object by traversing a sequence of references defined by path.


transform(object, filter, transform)

= {
  a: 1,
  b: [ 2, 3, 'hello' ]
};
 
deep.transform(
  x,
  function(obj) { return typeof obj == 'string' },
  function(obj) { return obj.length }
);
 
// -> {
//      a: 1,
//      b: [ 2, 3, 5 ]
//    }

Returns a deep copy of object, using the transform function to modify any elements that satisfy the filter function.

Readme

Keywords

none

Package Sidebar

Install

npm i deep

Weekly Downloads

228

Version

0.0.2

License

none

Last publish

Collaborators

  • jeffomatic