underscore.nested

Nested and Delegating Accessors for Underscore

underscore.nested

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.)

<tbody>
    <tr>
        <td>
            <strong>ensure</strong>
        </td>
        <td>
            <code>Boolean</code>
        </td>
        <td>
            <code>false</code>
        </td>
        <td>
            If true, intermediate keys that are <code>null</code> or <code>undefined</code> will be filled in with a new empty object <code>{}</code>, ensuring the get will return valid metadata.
        </td>
    </tr>

    <tr>
        <td>
            <strong>getter</strong>
        </td>
        <td>
            <code>String</code>
        </td>
        <td>
            <code>"get"</code>
        </td>
        <td>
            Name of the sub-object getter method use if it exists.
        </td>
    </tr>

    <tr>
        <td>
            <strong>setter</strong>
        </td>
        <td>
            <code>String</code>
        </td>
        <td>
            <code>"set"</code>
        </td>
        <td>
            Name of the sub-object setter method use if it exists.
        </td>
    </tr>

    <tr>
        <td>
            <strong>deleter</strong>
        </td>
        <td>
            <code>String</code>
        </td>
        <td>
            <code>"unset"</code>
        </td>
        <td>
            Name of the sub-object deleter method use if it exists.
        </td>
    </tr>
</tbody>
name type default description

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

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.

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

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

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.

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

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

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

[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.

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

Returns whether value is a plain object or not.

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

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 dsc@less.ly.

--

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