updeep

Easily update immutable objects (frozen or not) in a declarative way.

About

Updating deeply nested objects/arrays is a bit of a pain. updeep makes it painless by allowing you to declare the updates you would like to make and it will take care of the rest. You can use it on frozen objects, as updeep never mutates. It will recursively return the same instance if no changes have been made, making it ideal for using reference equality checks to detect changes (like PureRenderMixin).

updeep requires lodash, but works very well with lodash-fp. As a matter of fact, many of the helpers functions are curried lodash functions with their parameters reversed.

Note that the parameters may be backwards from what you are used to. updeep supports currying, so the parameter order is: updeep(updates, obj).

Examples

var u = require('updeep');

var person = {
  name: {
    first: 'Bill',
    last: 'Sagat',
  },
  children: ['Marty', 'Ashley'],
  email: 'bill@example.com',
  version: 1
};

var inc = function(i) { return i + 1; }

var newPerson = u({
  name: {
    first: 'Bob',
  },
  children: { 0: 'Mary-Kate' },
  email: 'bob@example.com',
  version: inc
}, person);

// => {
//      name: {
//        first: 'Bob',
//        last: 'Sagat',
//      },
//      children: ['Mary-Kate', 'Ashley'],
//      email: 'bob@example.com',
//      version: 2
//    }


// Simple update
u({ x: { b: 3 } }, { x: { a: 0, b: 0 } });
// => { x: { a: 0, b: 3 } }


// Multiple updates, including an array
u({ x: { b: 3 }, y: { 1: 4 } }, { x: { a: 0, b: 0 }, y: [0, 0] });
// => { x: { a: 0, b: 3 }, y: [0, 4] }


// Use a function
var inc = function(i) { return i + 1; }
u({ x: { b: inc } }, { x: { a: 0, b: 0 } });
// => { x: { a: 0, b: 1 } }


// Curry
var setBTo3 = u({ b: 3 });
setBTo3({ a: 0, b: 0 });
// => { a: 0, b: 3 })


// Remove a property
u({ x: u.omit('b') }, { x: { a: 0, b: 0 } });
// => { x: { a: 0 } }


// With a default
u({ x: withDefault([], { 0: 3 }) }, {});
// => { x: [3] }


// ES6 computed properties
var key = 'b';
u({ x: { [key]: 3 } }, { x: { a: 0, b: 0 } });
// => { x: { a: 0, b: 3 } }

See the tests for more examples.

Install

$ npm install --save updeep

Requires lodash as a peer dependency, so make sure you have it installed as well.

Motivation

While creating reducers for use with redux, I wanted something that made it easy to work with frozen objects. Native javascript objects have some nice advantages over things like Immutable.js such as debugging and destructuring. I wanted something more powerful than icepick and more composable than React.addons.update.

Contributing

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Run gulp to run tests and lint.
4. Commit your changes (git commit -am 'Added some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create new Pull Request.

License

MIT ©2015 Aaron Jensen