Object methods

Object methods read, write, and reshape plain objects and paths: property access (get, set, has), merging and cloning, and key or value transforms. Methods named with a With suffix (mergeWith, assignWith) accept a customizer function for full control over how values combine.

_.assign(object, [sources])

Available since v0.10.0.

Assigns own enumerable string keyed properties of source objects to the destination object. Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.

Note: This method mutates object and is loosely based on Object.assign.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
}

function Bar() {
  this.c = 3;
}

Foo.prototype.b = 2;
Bar.prototype.d = 4;

_.assign({ 'a': 0 }, new Foo, new Bar);
// => { 'a': 1, 'c': 3 }

_.assignIn(object, [sources])

Available since v4.0.0. Alias: _.extend.

This method is like _.assign except that it iterates over own and inherited source properties.

Note: This method mutates object.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
}

function Bar() {
  this.c = 3;
}

Foo.prototype.b = 2;
Bar.prototype.d = 4;

_.assignIn({ 'a': 0 }, new Foo, new Bar);
// => { 'a': 1, 'b': 2, 'c': 3, 'd': 4 }

_.assignInWith(object, sources, [customizer])

Available since v4.0.0. Alias: _.extendWith.

This method is like _.assignIn except that it accepts customizer which is invoked to produce the assigned values. If customizer returns undefined, assignment is handled by the method instead. The customizer is invoked with five arguments: (objValue, srcValue, key, object, source).

Note: This method mutates object.

Returns Object — Returns object.

function customizer(objValue, srcValue) {
  return _.isUndefined(objValue) ? srcValue : objValue;
}

var defaults = _.partialRight(_.assignInWith, customizer);

defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 });
// => { 'a': 1, 'b': 2 }

_.assignWith(object, sources, [customizer])

Available since v4.0.0.

This method is like _.assign except that it accepts customizer which is invoked to produce the assigned values. If customizer returns undefined, assignment is handled by the method instead. The customizer is invoked with five arguments: (objValue, srcValue, key, object, source).

Note: This method mutates object.

Returns Object — Returns object.

function customizer(objValue, srcValue) {
  return _.isUndefined(objValue) ? srcValue : objValue;
}

var defaults = _.partialRight(_.assignWith, customizer);

defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 });
// => { 'a': 1, 'b': 2 }

_.at(object, [paths])

Available since v1.0.0.

Creates an array of values corresponding to paths of object.

Returns Array — Returns the picked values.

var object = { 'a': [{ 'b': { 'c': 3 } }, 4] };

_.at(object, ['a[0].b.c', 'a[1]']);
// => [3, 4]

_.create(prototype, [properties])

Available since v2.3.0.

Creates an object that inherits from the prototype object. If a properties object is given, its own enumerable string keyed properties are assigned to the created object.

Returns Object — Returns the new object.

function Shape() {
  this.x = 0;
  this.y = 0;
}

function Circle() {
  Shape.call(this);
}

Circle.prototype = _.create(Shape.prototype, {
  'constructor': Circle
});

var circle = new Circle;
circle instanceof Circle;
// => true

circle instanceof Shape;
// => true

_.defaults(object, [sources])

Available since v0.1.0.

Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to undefined. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.

Note: This method mutates object.

Returns Object — Returns object.

_.defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 });
// => { 'a': 1, 'b': 2 }

_.defaultsDeep(object, [sources])

Available since v3.10.0.

This method is like _.defaults except that it recursively assigns default properties.

Note: This method mutates object.

Returns Object — Returns object.

_.defaultsDeep({ 'a': { 'b': 2 } }, { 'a': { 'b': 1, 'c': 3 } });
// => { 'a': { 'b': 2, 'c': 3 } }

_.findKey(object, [predicate=identity])

Available since v1.1.0.

This method is like _.find except that it returns the key of the first element predicate returns truthy for instead of the element itself.

Returns any — Returns the key of the matched element, else undefined.

var users = {
  'barney':  { 'age': 36, 'active': true },
  'fred':    { 'age': 40, 'active': false },
  'pebbles': { 'age': 1,  'active': true }
};

_.findKey(users, function(o) { return o.age < 40; });
// => 'barney' (iteration order is not guaranteed)

// The `_.matches` iteratee shorthand.
_.findKey(users, { 'age': 1, 'active': true });
// => 'pebbles'

// The `_.matchesProperty` iteratee shorthand.
_.findKey(users, ['active', false]);
// => 'fred'

// The `_.property` iteratee shorthand.
_.findKey(users, 'active');
// => 'barney'

_.findLastKey(object, [predicate=identity])

Available since v2.0.0.

This method is like _.findKey except that it iterates over elements of a collection in the opposite order.

Returns any — Returns the key of the matched element, else undefined.

var users = {
  'barney':  { 'age': 36, 'active': true },
  'fred':    { 'age': 40, 'active': false },
  'pebbles': { 'age': 1,  'active': true }
};

_.findLastKey(users, function(o) { return o.age < 40; });
// => returns 'pebbles' assuming `_.findKey` returns 'barney'

// The `_.matches` iteratee shorthand.
_.findLastKey(users, { 'age': 36, 'active': true });
// => 'barney'

// The `_.matchesProperty` iteratee shorthand.
_.findLastKey(users, ['active', false]);
// => 'fred'

// The `_.property` iteratee shorthand.
_.findLastKey(users, 'active');
// => 'pebbles'

_.forIn(object, [iteratee=identity])

Available since v0.3.0.

Iterates over own and inherited enumerable string keyed properties of an object and invokes iteratee for each property. The iteratee is invoked with three arguments: (value, key, object). Iteratee functions may exit iteration early by explicitly returning false.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.forIn(new Foo, function(value, key) {
  console.log(key);
});
// => Logs 'a', 'b', then 'c' (iteration order is not guaranteed).

_.forInRight(object, [iteratee=identity])

Available since v2.0.0.

This method is like _.forIn except that it iterates over properties of object in the opposite order.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.forInRight(new Foo, function(value, key) {
  console.log(key);
});
// => Logs 'c', 'b', then 'a' assuming `_.forIn` logs 'a', 'b', then 'c'.

_.forOwn(object, [iteratee=identity])

Available since v0.3.0.

Iterates over own enumerable string keyed properties of an object and invokes iteratee for each property. The iteratee is invoked with three arguments: (value, key, object). Iteratee functions may exit iteration early by explicitly returning false.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.forOwn(new Foo, function(value, key) {
  console.log(key);
});
// => Logs 'a' then 'b' (iteration order is not guaranteed).

_.forOwnRight(object, [iteratee=identity])

Available since v2.0.0.

This method is like _.forOwn except that it iterates over properties of object in the opposite order.

Returns Object — Returns object.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.forOwnRight(new Foo, function(value, key) {
  console.log(key);
});
// => Logs 'b' then 'a' assuming `_.forOwn` logs 'a' then 'b'.

_.functions(object)

Available since v0.1.0.

Creates an array of function property names from own enumerable properties of object.

Returns Array — Returns the function names.

function Foo() {
  this.a = _.constant('a');
  this.b = _.constant('b');
}

Foo.prototype.c = _.constant('c');

_.functions(new Foo);
// => ['a', 'b']

_.functionsIn(object)

Available since v4.0.0.

Creates an array of function property names from own and inherited enumerable properties of object.

Returns Array — Returns the function names.

function Foo() {
  this.a = _.constant('a');
  this.b = _.constant('b');
}

Foo.prototype.c = _.constant('c');

_.functionsIn(new Foo);
// => ['a', 'b', 'c']

_.get(object, path, [defaultValue])

Available since v3.7.0.

Gets the value at path of object. If the resolved value is undefined, the defaultValue is returned in its place.

Returns any — Returns the resolved value.

var object = { 'a': [{ 'b': { 'c': 3 } }] };

_.get(object, 'a[0].b.c');
// => 3

_.get(object, ['a', '0', 'b', 'c']);
// => 3

_.get(object, 'a.b.c', 'default');
// => 'default'

_.has(object, path)

Available since v0.1.0.

Checks if path is a direct property of object.

Returns boolean — Returns true if path exists, else false.

var object = { 'a': { 'b': 2 } };
var other = _.create({ 'a': _.create({ 'b': 2 }) });

_.has(object, 'a');
// => true

_.has(object, 'a.b');
// => true

_.has(object, ['a', 'b']);
// => true

_.has(other, 'a');
// => false

_.hasIn(object, path)

Available since v4.0.0.

Checks if path is a direct or inherited property of object.

Returns boolean — Returns true if path exists, else false.

var object = _.create({ 'a': _.create({ 'b': 2 }) });

_.hasIn(object, 'a');
// => true

_.hasIn(object, 'a.b');
// => true

_.hasIn(object, ['a', 'b']);
// => true

_.hasIn(object, 'b');
// => false

_.invert(object)

Available since v0.7.0.

Creates an object composed of the inverted keys and values of object. If object contains duplicate values, subsequent values overwrite property assignments of previous values.

Returns Object — Returns the new inverted object.

var object = { 'a': 1, 'b': 2, 'c': 1 };

_.invert(object);
// => { '1': 'c', '2': 'b' }

_.invertBy(object, [iteratee=identity])

Available since v4.1.0.

This method is like _.invert except that the inverted object is generated from the results of running each element of object thru iteratee. The corresponding inverted value of each inverted key is an array of keys responsible for generating the inverted value. The iteratee is invoked with one argument: (value).

Returns Object — Returns the new inverted object.

var object = { 'a': 1, 'b': 2, 'c': 1 };

_.invertBy(object);
// => { '1': ['a', 'c'], '2': ['b'] }

_.invertBy(object, function(value) {
  return 'group' + value;
});
// => { 'group1': ['a', 'c'], 'group2': ['b'] }

_.invoke(object, path, [args])

Available since v4.0.0.

Invokes the method at path of object.

Returns any — Returns the result of the invoked method.

var object = { 'a': [{ 'b': { 'c': [1, 2, 3, 4] } }] };

_.invoke(object, 'a[0].b.c.slice', 1, 3);
// => [2, 3]

_.keys(object)

Available since v0.1.0.

Creates an array of the own enumerable property names of object.

Note: Non-object values are coerced to objects. See the ES spec for more details.

Returns Array — Returns the array of property names.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.keys(new Foo);
// => ['a', 'b'] (iteration order is not guaranteed)

_.keys('hi');
// => ['0', '1']

_.keysIn(object)

Available since v3.0.0.

Creates an array of the own and inherited enumerable property names of object.

Note: Non-object values are coerced to objects.

Returns Array — Returns the array of property names.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.keysIn(new Foo);
// => ['a', 'b', 'c'] (iteration order is not guaranteed)

_.mapKeys(object, [iteratee=identity])

Available since v3.8.0.

The opposite of _.mapValues; this method creates an object with the same values as object and keys generated by running each own enumerable string keyed property of object thru iteratee. The iteratee is invoked with three arguments: (value, key, object).

Returns Object — Returns the new mapped object.

_.mapKeys({ 'a': 1, 'b': 2 }, function(value, key) {
  return key + value;
});
// => { 'a1': 1, 'b2': 2 }

_.mapValues(object, [iteratee=identity])

Available since v2.4.0.

Creates an object with the same keys as object and values generated by running each own enumerable string keyed property of object thru iteratee. The iteratee is invoked with three arguments: (value, key, object).

Returns Object — Returns the new mapped object.

var users = {
  'fred':    { 'user': 'fred',    'age': 40 },
  'pebbles': { 'user': 'pebbles', 'age': 1 }
};

_.mapValues(users, function(o) { return o.age; });
// => { 'fred': 40, 'pebbles': 1 } (iteration order is not guaranteed)

// The `_.property` iteratee shorthand.
_.mapValues(users, 'age');
// => { 'fred': 40, 'pebbles': 1 } (iteration order is not guaranteed)

_.merge(object, [sources])

Available since v0.5.0.

This method is like _.assign except that it recursively merges own and inherited enumerable string keyed properties of source objects into the destination object. Source properties that resolve to undefined are skipped if a destination value exists. Array and plain object properties are merged recursively. Other objects and value types are overridden by assignment. Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.

Note: This method mutates object.

Returns Object — Returns object.

var object = {
  'a': [{ 'b': 2 }, { 'd': 4 }]
};

var other = {
  'a': [{ 'c': 3 }, { 'e': 5 }]
};

_.merge(object, other);
// => { 'a': [{ 'b': 2, 'c': 3 }, { 'd': 4, 'e': 5 }] }

_.mergeWith(object, sources, customizer)

Available since v4.0.0.

This method is like _.merge except that it accepts customizer which is invoked to produce the merged values of the destination and source properties. If customizer returns undefined, merging is handled by the method instead. The customizer is invoked with six arguments: (objValue, srcValue, key, object, source, stack).

Note: This method mutates object.

Returns Object — Returns object.

function customizer(objValue, srcValue) {
  if (_.isArray(objValue)) {
    return objValue.concat(srcValue);
  }
}

var object = { 'a': [1], 'b': [2] };
var other = { 'a': [3], 'b': [4] };

_.mergeWith(object, other, customizer);
// => { 'a': [1, 3], 'b': [2, 4] }

_.omit(object, [paths])

Available since v0.1.0.

The opposite of _.pick; this method creates an object composed of the own and inherited enumerable property paths of object that are not omitted.

Note: This method is considerably slower than _.pick.

Returns Object — Returns the new object.

var object = { 'a': 1, 'b': '2', 'c': 3 };

_.omit(object, ['a', 'c']);
// => { 'b': '2' }

_.omitBy(object, [predicate=identity])

Available since v4.0.0.

The opposite of _.pickBy; this method creates an object composed of the own and inherited enumerable string keyed properties of object that predicate doesn't return truthy for. The predicate is invoked with two arguments: (value, key).

Returns Object — Returns the new object.

var object = { 'a': 1, 'b': '2', 'c': 3 };

_.omitBy(object, _.isNumber);
// => { 'b': '2' }

_.pick(object, [paths])

Available since v0.1.0.

Creates an object composed of the picked object properties.

Returns Object — Returns the new object.

var object = { 'a': 1, 'b': '2', 'c': 3 };

_.pick(object, ['a', 'c']);
// => { 'a': 1, 'c': 3 }

_.pickBy(object, [predicate=identity])

Available since v4.0.0.

Creates an object composed of the object properties predicate returns truthy for. The predicate is invoked with two arguments: (value, key).

Returns Object — Returns the new object.

var object = { 'a': 1, 'b': '2', 'c': 3 };

_.pickBy(object, _.isNumber);
// => { 'a': 1, 'c': 3 }

_.result(object, path, [defaultValue])

Available since v0.1.0.

This method is like _.get except that if the resolved value is a function it's invoked with the this binding of its parent object and its result is returned.

Returns any — Returns the resolved value.

var object = { 'a': [{ 'b': { 'c1': 3, 'c2': _.constant(4) } }] };

_.result(object, 'a[0].b.c1');
// => 3

_.result(object, 'a[0].b.c2');
// => 4

_.result(object, 'a[0].b.c3', 'default');
// => 'default'

_.result(object, 'a[0].b.c3', _.constant('default'));
// => 'default'

_.set(object, path, value)

Available since v3.7.0.

Sets the value at path of object. If a portion of path doesn't exist, it's created. Arrays are created for missing index properties while objects are created for all other missing properties. Use _.setWith to customize path creation.

Note: This method mutates object.

Returns Object — Returns object.

var object = { 'a': [{ 'b': { 'c': 3 } }] };

_.set(object, 'a[0].b.c', 4);
console.log(object.a[0].b.c);
// => 4

_.set(object, ['x', '0', 'y', 'z'], 5);
console.log(object.x[0].y.z);
// => 5

_.setWith(object, path, value, [customizer])

Available since v4.0.0.

This method is like _.set except that it accepts customizer which is invoked to produce the objects of path. If customizer returns undefined path creation is handled by the method instead. The customizer is invoked with three arguments: (nsValue, key, nsObject).

Note: This method mutates object.

Returns Object — Returns object.

var object = {};

_.setWith(object, '[0][1]', 'a', Object);
// => { '0': { '1': 'a' } }

_.toPairs(object)

Available since v4.0.0. Alias: _.entries.

Creates an array of own enumerable string keyed-value pairs for object which can be consumed by _.fromPairs. If object is a map or set, its entries are returned.

Returns Array — Returns the key-value pairs.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.toPairs(new Foo);
// => [['a', 1], ['b', 2]] (iteration order is not guaranteed)

_.toPairsIn(object)

Available since v4.0.0. Alias: _.entriesIn.

Creates an array of own and inherited enumerable string keyed-value pairs for object which can be consumed by _.fromPairs. If object is a map or set, its entries are returned.

Returns Array — Returns the key-value pairs.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.toPairsIn(new Foo);
// => [['a', 1], ['b', 2], ['c', 3]] (iteration order is not guaranteed)

_.transform(object, [iteratee=identity], [accumulator])

Available since v1.3.0.

An alternative to _.reduce; this method transforms object to a new accumulator object which is the result of running each of its own enumerable string keyed properties thru iteratee, with each invocation potentially mutating the accumulator object. If accumulator is not provided, a new object with the same [[Prototype]] will be used. The iteratee is invoked with four arguments: (accumulator, value, key, object). Iteratee functions may exit iteration early by explicitly returning false.

Returns any — Returns the accumulated value.

_.transform([2, 3, 4], function(result, n) {
  result.push(n *= n);
  return n % 2 == 0;
}, []);
// => [4, 9]

_.transform({ 'a': 1, 'b': 2, 'c': 1 }, function(result, value, key) {
  (result[value] || (result[value] = [])).push(key);
}, {});
// => { '1': ['a', 'c'], '2': ['b'] }

_.unset(object, path)

Available since v4.0.0.

Removes the property at path of object.

Note: This method mutates object.

Returns boolean — Returns true if the property is deleted, else false.

var object = { 'a': [{ 'b': { 'c': 7 } }] };
_.unset(object, 'a[0].b.c');
// => true

console.log(object);
// => { 'a': [{ 'b': {} }] };

_.unset(object, ['a', '0', 'b', 'c']);
// => true

console.log(object);
// => { 'a': [{ 'b': {} }] };

_.update(object, path, updater)

Available since v4.6.0.

This method is like _.set except that accepts updater to produce the value to set. Use updateWith to customize path creation. The updater is invoked with one argument: (value).

Note: This method mutates object.

Returns Object — Returns object.

var object = { 'a': [{ 'b': { 'c': 3 } }] };

_.update(object, 'a[0].b.c', function(n) { return n * n; });
console.log(object.a[0].b.c);
// => 9

_.update(object, 'x[0].y.z', function(n) { return n ? n + 1 : 0; });
console.log(object.x[0].y.z);
// => 0

_.updateWith(object, path, updater, [customizer])

Available since v4.6.0.

This method is like _.update except that it accepts customizer which is invoked to produce the objects of path. If customizer returns undefined path creation is handled by the method instead. The customizer is invoked with three arguments: (nsValue, key, nsObject).

Note: This method mutates object.

Returns Object — Returns object.

var object = {};

_.updateWith(object, '[0][1]', _.constant('a'), Object);
// => { '0': { '1': 'a' } }

_.values(object)

Available since v0.1.0.

Creates an array of the own enumerable string keyed property values of object.

Note: Non-object values are coerced to objects.

Returns Array — Returns the array of property values.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.values(new Foo);
// => [1, 2] (iteration order is not guaranteed)

_.values('hi');
// => ['h', 'i']

_.valuesIn(object)

Available since v3.0.0.

Creates an array of the own and inherited enumerable string keyed property values of object.

Note: Non-object values are coerced to objects.

Returns Array — Returns the array of property values.

function Foo() {
  this.a = 1;
  this.b = 2;
}

Foo.prototype.c = 3;

_.valuesIn(new Foo);
// => [1, 2, 3] (iteration order is not guaranteed)