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)

x = {
  a: 1,
  b: [ 2, 3, function(arg) { return arg; } ]
};

y = 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)

a = b = [1, 2, 3]
deep.equals(a, b) // true

a = [1, 2, 3]
b = [1, 2, 3]
deep.equals(a, b) // true

a = [1, 2, 3]
b = [1, 2, 4]
deep.equals(a, b) // false

a = b = {x: 1, y: 2}
deep.equals(a, b) // true

a = {x: 1, y: 2}
b = {x: 1, y: 2}
deep.equals(a, b) // true

a = b = new Buffer
deep.equals(a, b) // true

a = new Buffer
b = new Buffer
deep.equals(a, b) // false

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

a = {x: 1, y: [2, 3], z: {a: 4, b: 5}}
b = {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, ...)

x = { a: { b: { c: 1 } }, d: 2, e: 3 }
y = { a: { b: { c: 4, f: 5 }, d: 6, g: 7 } }
z = { 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)

x = {
  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)

x = { 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)

x = {
  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.