hoops

Nested property access and manipulation library for node and the browser. Available as a standalone module, and integrates with underscore and lodash. Tested in all modern browsers, and IE6+. Inspired by igorw/get-in.

• Overview
• Installation
• Usage
• API
  • hoops.getIn(object, keys, [defaultValue])
  • hoops.isIn(object, keys)
  • hoops.invokeIn(object, keys, [...args])
  • hoops.updateIn(object, keys, value)
  • hoops.setIn(object, keys, value)

Overview

hoops is a library for traversing and manipulating deeply nested properties in JavaScript. It's a set of convenience functions to help reduce some of the repetition faced in these scenarios. For example, to retrieve a deeply nested configuration value from an object, you may have:

var namespace;
if (app.environment && app.environment.redis && app.environment.redis.namespace) {
  namespace = app.environment.redis.namespace;
}

All this to avoid a TypeError resulting from trying to access a property of an undefined value: TypeError: Cannot read property 'redis' of undefined. How can hoops help? You can achieve the same as the previous example using:

var namespace = hoops.getIn(app, 'environment.redis.namespace');

Keys may be accessed via a dot-delimited string as seen above, or by providing an array of strings. The library also integrates nicely with both underscore and lodash, allowing you to do:

_(object).getIn('some.nested.property').pick('id', 'name');

It may not offer the convenience of monads, but it certainly helps reduce friction in dealing with these objects. Some may also wonder how this compares to underscore-contrib or lodash-contrib:

• The contrib repos only offer getPath and hasPath (getIn, isIn)
• The libs cannot be used standalone, as they require underscore/lodash

Installation

The library can be installed via npm:

npm install hoops

Or using bower:

bower install hoops

NodeJS

// Standalone
var hoops = require('hoops');
 
// With underscore
var _     = require('underscore');
var hoops = require('hoops');
_.mixin(hoops);
 
// With lodash
var _     = require('lodash').runInContext();
var hoops = require('hoops');
_.mixin(hoops);

Browser

Simply load hoops.min.js. For automatic integration with underscore or lodash, the file should be loaded after either script. It can also be loaded via CommonJS and AMD.

Usage

Standalone

Chaining is not available when using hoops on its own.

hoops.getIn(object, 'foo.bar.baz');

Underscore

Underscore chaining requires chain() and value() calls.

_.getIn(object, 'foo.bar.baz');
_(object).chain().getIn('foo.bar.baz').value();

Lodash

Lodash chaining only requires a value call.

_.getIn(object, 'foo.bar.baz');
_(object).getIn('foo.bar.baz').value();

API

hoops.getIn(object, keys, [defaultValue])

Returns the value at the nested property, if it exists. Keys may either be an array, or a dot-delimited string of properties. If the value does not exist, the function returns undefined, or the defaultValue if supplied.

var object = {foo: {bar: {baz: 'example'}}};
hoops.getIn(object, 'foo.bar.baz'); // => 'example'
hoops.getIn(object, ['foo', 'bar', 'baz']); // => 'example'

hoops.isIn(object, keys)

Returns whether or not the nested property is defined. Keys may be an array, or a dot-delimited string of properties.

var object = {foo: {bar: {baz: 'example'}}};
hoops.isIn(object, 'foo.bar.baz'); // => true
hoops.isIn(object, ['foo', 'bar', 'baz']); // => true

hoops.invokeIn(object, keys, [...args])

Invokes the function nested at the provided path of keys, if it exists, and returns the object. The given keys may be an array, or a dot-delimited string of properties. invokeIn accepts a variable number of arguments to be passed. If a function at the key does not exist, the object is simply returned.

var y, object;
object = {foo: {bar: function(x, z) {
  y = x + z;
}}};
 
hoops.invokeIn(object, 'foo.bar', 10, 5); // => object
console.log(y); // 15

hoops.updateIn(object, keys, value)

Updates the nested key with the given value, if it exists, and returns the object. Keys may either be an array, or a dot-delimited string of properties. If a key does not exist, the object is simply returned.

var object = {foo: {bar: { baz: 'test'}}};
hoops.updateIn(object, 'foo.bar.baz.invalid', 'updatedValue'); // => object

hoops.setIn(object, keys, value)

Sets the nested key to the provided value, creating objects for any non-existent properties, and returns the supplied object. Keys may be supplied an array, or a dot-delimited string of properties.

var object = {foo: {}};
hoops.setIn(object, 'foo.bar.baz', 'example');
// {foo: {bar: {baz: 'example'}}}