lodash-deep

Lodash mixins for (deep) object accessing / manipulation.

lodash-deep

Lodash mixins for (deep) object accessing / manipulation.

lodash-deep is currently compatible with:

  • Node.js
  • All ES5 compatible browsers (IE9+, Chrome, Firefox, Safari etc)
  1. bower install lodash-deep
  2. Reference lodash-deep.min.js after lodash.min.js
  1. npm install lodash
  2. npm install lodash-deep
  3.  
    var _ = require("lodash");
    _.mixin(require("lodash-deep"));

The following mixins are included in lodash-deep:

Nearly all methods of this library have the propertyPath parameter. This parameter defines the location of the nested value(s) and can be either a single string or an array.

When an array is specified, each value should be a property name or array index and there is no need to escape special characters.

var obj = { level1: { 'lev\\el2': { 'lev.el3': { 'level4]': [ 'value' ] }}}};
var path2Value = ['level1', 'lev\\el2', 'lev.el3', 'level4]', '0'];

When a string is specified, it is split on unescaped ., [ and ] characters to create an array of property names. If a property name contains one of these characters, it must be escaped with a \ (which must be typed as \\ in a string literal). The helper method _.deepEscapePropertyName is provided to assist with this.

// basic property names 
var obj = { level1: { level2: [ 'value' ] }};
var path2Value = 'level1.level2[0]';
// complex property names 
var obj = { 'lev.el1': { 'lev\\el2': { `lev[e]l3`: [ 'value' ] }}};
 
// using a manually escaped string 
var path2Value = 'lev\\.el1.lev\\\\el2.lev\\[e\\]l3[0]';
 
// using a programatically escaped string 
var path2Value =
    _.deepEscapePropertyName('lev.el1') + '.' +
    _.deepEscapePropertyName('lev\\el2') + '.' +
    _.deepEscapePropertyName('lev[e]l3') + '[' + 0 + ']';

Sets a value of a property in an object tree. Any missing objects/arrays will be created.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: *

The value to set.

Type: Object

var object = {};
_.deepSet(object, 'level1.level2.level3.value', 'value 3');
// -> { level1: { level2: { level3: { value: 'value 3' }}}} 
_.deepSet(object, 'level1.level2.level3.value', 'foo');
// -> { level1: { level2: { level3: { value: 'foo' }}}} 

Retrieves the value of a property in an object tree.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: *|undefined

The value, or undefined if it doesn't exists.

var object = {
    level1: {
        value: 'value 1',
        level2: Object.create({
            level3: {
                value: 'value 3'
            }
        })
    }
};
_.deepGet(object, 'level1.value');
// -> 'value 1' 
_.deepGet(object, 'level1.level2.level3.value');
// -> 'value 3' 
_.deepGet(object, 'foo.bar.baz');
// -> undefined 

Retrieves the value of a own property in an object tree.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: *|undefined

The value, or undefined if it doesn't exists.

var object = {
    level1: {
        value: 'value 1',
        level2: Object.create({
            level3: {
                value: 'value 3'
            }
        })
    }
};
_.deepOwn(object, 'level1.value');
// -> 'value 1' 
_.deepOwn(object, 'level1.level2.level3.value');
// -> undefined 
_.deepOwn(object, 'foo.bar.baz');
// -> undefined 

Executes a deep pluck on an collection of object trees.

Type: Object|Array

The collection of object trees.

Type: string|Array

The propertyPath.

Type: Array

var collection = [
    { level1: { level2: { level3: { value: 1 }}}},
    { level1: { level2: { level3: { value: 2 }}}},
    { level1: { level2: { level3: { value: 3 }}}},
    { level1: { level2: { level3: { value: 4 }}}},
    { level1: { level2: {} }},
    {}
];
_.deepPluck(collection, 'level1.level2.level3.value');
// -> [ 1, 2, 3, 4, undefined, undefined ] 

Executes a deep check for the existence of a property in an object tree.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: boolean

var object = {
    level1: {
        level2: Object.create({
            level3: {
                value: 'value 3'
            }
        })
    }
};
_.deepIn(object, 'level1');
// -> true 
_.deepIn(object, 'level1.level2');
// -> true 
_.deepIn(object, 'level1.level2.level3');
// -> true 
_.deepIn(object, 'level1.level2.level3.value');
// -> true 

Executes a deep check for the existence of a own property in an object tree.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: boolean

var object = {
    level1: {
        level2: Object.create({
            level3: {
                value: 'value 3'
            }
        })
    }
};
_.deepHas(object, 'level1');
// -> true 
_.deepHas(object, 'level1.level2');
// -> true 
_.deepHas(object, 'level1.level2.level3');
// -> false 
_.deepHas(object, 'level1.level2.level3.value');
// -> false 

Calls a function located at the specified property path, if it exists.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: Object

The 'this' argument the function should be executed with.

Type: *

One of the arguments the function should be executed with. Can occur 0..n times.

Type: *

The result of executing the function if it exists, or undefined if the function doesn't exist.

_.deepCall(myObject, 'level1.level2.myFunc', myObject, 'arg1', 'arg2');
// if it exists -> result of myObject.level1.level2.myFunc('arg1', 'arg2') 
// if it does not exist -> undefined 

Calls a function located at the specified property path, if it exists.

Type: Object|Array

The root object/array of the object tree.

Type: string|Array

The propertyPath.

Type: Object

The 'this' argument the function should be executed with.

Type: Array

The arguments the function should be executed with.

Type: *

The result of executing the function if it exists, or undefined if the function doesn't exist.

var args = ['arg1', 'arg2'];
_.deepApply(myObject, 'level1.level2.myFunc', myObject, args);
// if it exists -> result of myObject.level1.level2.myFunc('arg1', 'arg2') 
// if it does not exist -> undefined 

Maps all values in an object tree and returns a new object with the same structure as the original.

Type: Object

The root object of the object tree.

Type: Function

The function to be called per iteration on any non-object value in the tree.

Callback is invoked with 2 arguments: (value, propertyPath).

value the value of the current property.

propertyPath the propertyPath of the current property, in array format.

Type: Object

var object = {
    level1: {
        value: 'value 1'
        level2: {
            value: 'value 2'
            level3: {
                value: 'value 3'
            }
        }
    }
};
 
_.deepMapValues(object, function(valuepropertyPath){
    return (propertyPath.join('.') + ' is ' + value)
});
 
/** ->
 *    {
 *        level1: {
 *            value: 'level1.value is value 1'
 *            level2: {
 *                value: 'level1.level2.value is value 2'
 *                level3: {
 *                    value: 'level1.level2.level3.value is value 3'
 *                }
 *            }
 *        }
 *    };
 */

Collection of shorthand functions for executing a non-deep Lodash function with a "_.deepPluck" style callback:

  • _.deepFindIndex
  • _.deepFindLastIndex
  • _.deepFirst
  • _.deepFlatten
  • _.deepInitial
  • _.deepLast
  • _.deepLastIndexOf
  • _.deepRemove
  • _.deepRest
  • _.deepSortedIndex
  • _.deepUniq
  • _.deepCountBy
  • _.deepEvery
  • _.deepFilter
  • _.deepFind
  • _.deepGroupBy
  • _.deepIndexBy
  • _.deepMax
  • _.deepMin
  • _.deepReject
  • _.deepSome
  • _.deepSortBy
  • _.deepFindKey
  • _.deepFindLastKey

Type: Object|Array

The collection of object trees.

Type: string|Array

The propertyPath.

Type: *

The result of calling the original Lodash function with a "_.deepPluck" style callback.

var collection = [
    { level1: { level2: { level3: { value: 1 }}}},
    { level1: { level2: { level3: { value: 2 }}}},
    { level1: { level2: { level3: { value: 3 }}}},
    { level1: { level2: { level3: { value: 4 }}}},
    { level1: { level2: {} }},
    {}
];
_.deepMax(collection, 'level1.level2.level3.value');
// -> { level1: { level2: { level3: { value: 4 }}}} 
// === shorthand for 
_.max(collection, function(item){
    return _.deepGet(item, 'level1.level2.level3.value');
});

In version 1.2.0 function names were simplified. Backward compatibility with the old names remains in place.

Please use the canary branch when creating a pull request.