Find file
Fetching contributors…
Cannot retrieve contributors at this time
214 lines (144 sloc) 5.73 KB


Nested and delegating object-graph extensions for Underscore.js.


For usage in node.js, install it via npm: npm install underscore.nested.

Once Then mix it into Underscore:

var _ = require('underscore');
_.mixin require('underscore.nested');



Many accessor functions take an options object with common fields. The sub-object delegation options (getter, setter, and deleter) are used to specify where to look for the specific accessor method on a custom sub-object when performing that operation. (Functions that do not use that operation will ignore these options, so you're welcome to specify them everywhere just to be safe.)

name type default description
ensure Boolean false If true, intermediate keys that are null or undefined will be filled in with a new empty object {}, ensuring the get will return valid metadata.
getter String "get" Name of the sub-object getter method use if it exists.
setter String "set" Name of the sub-object setter method use if it exists.
deleter String "unset" Name of the sub-object deleter method use if it exists.

Delegating Accessors

_.get(target, key, def, opts) -> value

Gets the value at key from the object if present, returning def otherwise.

_.set(target, key, value, opts) -> target

Puts a given value to key on the given target object. If an object is supplied as key instead of a String, each key-value pair on that object will be put to the target object. In this case, omit value. Returns the target object.

_.unset(target, key, opts) -> oldValue

Deletes key from the target object, returning whatever value was present prior to being removed.

_.isMember(object, ...values) -> Boolean

Tests whether all values are contained in the given collection (accepting Object or Array).

Nested Delegating Accessors

These methods perform nested accessor operations, delegating like their non-nested counterparts to the target object when an instance method is found matching the operation.

_.getNested(target, chain, def, opts) -> value

Searches a hierarchical object for a given subkey specified in dotted-property syntax, returning the value if found, and def otherwise.

_.setNested(target, chain, value, opts) -> oldValue

Searches a hierarchical object for a given subkey specified in dotted-property syntax, setting it with the provided value if found.

_.unsetNested(target, chain, opts) -> target

Searches a hierarchical object for a potentially-nested key and removes it, returning whatever value was present there prior to being removed.

_.getNestedMeta(object, chain, opts) -> Object

[Private] Searches a hierarchical object for a given subkey (specified in dotted-property syntax), respecting sub-object accessor-methods (e.g., 'get', 'set') if they exist. If found, returns an object of the form { key: Qualified key name, obj: Parent object of key, val: Value at obj[key], opts: Options }, and otherwise undefined.

Collection Utilities

_.merge(target={}, ...donors) -> target

Recursively merges together any number of donor objects into the target object. (Modified from jQuery.extend().)

_.isPlainObject(object) -> Boolean

Returns whether value is a plain object or not.

_.remove(object, value) -> Object

In-place removal of a value from an Array or Object. Returns the object.

_.items(object) -> Array

Converts the collection to a list of its items:

  • Objects become a list of [key, value] pairs.
  • Strings become a list of characters.
  • Arguments objects become an array.
  • Arrays are copied.


Find a bug or want to contribute? Open a ticket (or fork the source!) on github. You're also welcome to send me email at

underscore.nested was written by David Schoonover; it is open-source software and freely available under the MIT License.