insides v0.0.2

Insides

Small JavaScript utility library for working with nested objects.

Installation

npm install insides --save

Quick Examples

  var buildObject = require("insides").buildObject;
  var reduceKV    = require("insides").reduceKV;
  var getIn       = require("insides").getIn;
  var setIn       = require("insides").setIn;

  var object = buildObject([
    [ [ "a", "b", "c" ], 1 ],
    [ [ "a", "b", "d" ], 2 ],
    [ [ "e" ], 3 ]
  ]);

  console.log(JSON.stringify(object, null, 2));
  // {
  //   "a": {
  //     "b": {
  //       "c": 1,
  //       "d": 2
  //     }
  //   },
  //   "e": 3
  // }

  var depth = 3;
  var sum = reduceKV(object, depth, function(memo, key, value) {
    return memo + value;
  }, 0);

  console.log("sum: " + sum);
  // sum: 3

  var abcValue = getIn(object, [ "a", "b", "c" ]);

  console.log("abc value: " + abcValue);
  // abc value: 1

  var abgValue = getIn(object, [ "a", "b", "g" ], "not found");

  console.log("abg value: " + abgValue);
  // abg value: not found

  var newObject = setIn(object, [ "a", "b", "g" ], 10);
  var newAbgValue = getIn(newObject, [ "a", "b", "g" ], "not found");

  console.log("new abg value: " + newAbgValue);
  // new abg value: 10

Functions

buildObject(objectMap)

Creates object from nestedArray:

var object = buildObject([ [ "a", 2 ] ]); // => { a: 2 }

var object = buildObject([ [ [ "a", "b" ], 2 ] ]); // => { a: { b: 2 } }

var object = buildObject([
  [ [ "a", "b" ], 2 ],
  [ [ "a", "c" ], 3 ]
]); // => { a: { b: 2, c: 3 } }

Argument is array of two-element arrays, first element is key map for the value, and second argument is the value;

getIn(object, keys, notFound)

Returns value from nested object.

Arguments

• object - object from which to return value
• keys - keys array, could be a string or a array of keys: "a", [ "a", "b" ] or "a.b"
• notFound - optional not found value, defaults to undefined

Differences from object.a.b.c:

If object.a does not exists this will thor a TypeError, getIn(object, [ "a", "b", "c" ]) returns undefined.

setIn(object, keys, value/callback);

Sets value in object for provided keys array. Overwrites everything that was in this key and returns new object (initial one is left unchanged).

Arguments

• object - object to update value
• keys - keys array, could be a string or a array of keys: "a", [ "a", "b" ] or "a.b"
• value/callback - value or a callback to update the object:
  • value - overwrites object at given keys to provided value
  • callback - calls callback(key, value) and replaces object at given key path to return value of the callback

updateIn(object, keys, value/callback);

The same as setIn but updates the values instead of replacing them:

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

var setObject = setIn(object, [ "a" ], { b: 5 });
// => { "a": { "b": 5 } }

var updateObject = setIn(object, [ "a" ], { b: 5 });
// => { "a": { "b": 5, "c": 2 } }

eachKV(object, depth, callback)

Iterates over object calling callback on each matching value.

Arguments

• object - object to iterate on
• [depth] - optional depth argument, positive integer, defaults to 0
• callback - callback to be run on every matching node: callback(key, value, object)

mapKV(object, depth, callback)

Same as eachKV but returns new object instead of updating existing one, returns new object (initial one is left unchanged).

reduceKV(object, depth, callback, initialValue)

Reduces nested object using provided callback.

Arguments

• object - object to reduce
• [depth] - optional depth argument, positive integer, defaults to 0
• callback - callback to be run on every matching node: callback(memo, key, value, object)
• [initialValue] - optional initial value for first memo in callback