lodash-deep

Lodash mixins for (deep) object accessing / manipulation.

Compatibility

lodash-deep is currently compatible with:

• Node.js
• All ES5 compatible browsers (IE9+, Chrome, Firefox, Safari etc)

Installation

Bower

1. bower install lodash-deep
2. Reference lodash-deep.min.js after lodash.min.js

Node.js

1. npm install lodash
2. npm install lodash-deep

3. var _ = require("lodash");
   _.mixin(require("lodash-deep"));

Docs

The following mixins are included in lodash-deep:

• _.deepSet
• _.deepGet
• _.deepOwn
• _.deepPluck
• _.deepIn
• _.deepHas
• _.deepCall
• _.deepApply
• _.deepMapValues
• _.deepFindIndex
• _.deepFindLastIndex
• _.deepFirst
• _.deepFlatten
• _.deepInitial
• _.deepLast
• _.deepLastIndexOf
• _.deepRemove
• _.deepRest
• _.deepSortedIndex
• _.deepUniq
• _.deepCountBy
• _.deepEvery
• _.deepFilter
• _.deepFind
• _.deepGroupBy
• _.deepIndexBy
• _.deepMax
• _.deepMin
• _.deepReject
• _.deepSome
• _.deepSortBy
• _.deepFindKey
• _.deepFindLastKey

propertyPath

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 + ']';

_.deepSet(collection, propertyPath, value)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

value

Type: *

The value to set.

returns

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' }}}}

_.deepGet(collection, propertyPath)

Retrieves the value of a property in an object tree.

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

returns

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

_.deepOwn(collection, propertyPath)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

returns

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

_.deepPluck(collection, propertyPath)

Executes a deep pluck on an collection of object trees.

collection

Type: Object|Array

The collection of object trees.

propertyPath

Type: string|Array

The propertyPath.

returns

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 ]

_.deepIn(collection, propertyPath)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

returns

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

_.deepHas(collection, propertyPath)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

returns

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

_.deepCall(collection, propertyPath, thisArg, arg)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

thisArg

Type: Object

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

arg1 ... argN

Type: *

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

returns

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

_.deepApply(collection, propertyPath, thisArg, args)

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

collection

Type: Object|Array

The root object/array of the object tree.

propertyPath

Type: string|Array

The propertyPath.

thisArg

Type: Object

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

args

Type: Array

The arguments the function should be executed with.

returns

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

_.deepMapValues(object, propertyPath)

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

object

Type: Object

The root object of the object tree.

callback

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.

returns

Type: Object

var object = {
    level1: {
        value: 'value 1'
        level2: {
            value: 'value 2'
            level3: {
                value: 'value 3'
            }
        }
    }
};

_.deepMapValues(object, function(value, propertyPath){
    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'
 *                }
 *            }
 *        }
 *    };
 */

_.deepPluckStyle(collection, propertyPath)

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

collection

Type: Object|Array

The collection of object trees.

propertyPath

Type: string|Array

The propertyPath.

returns

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');
});

Function name change

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

Contributing

Please use the canary branch when creating a pull request.

Contributors

• Mark Lagendijk
• Andrew Luetgers
• Nelson Pecora
• Mark Battersby
• Beau Gunderson
• Spencer