updeep

Easily update nested frozen objects and arrays in a declarative and immutable manner.

About

updeep makes updating deeply nested objects/arrays painless by allowing you to declare the updates you would like to make and it will take care of the rest. 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).

Because of this, everything returned by updeep is frozen. Not only that, but updeep assumes that every object passed in to update is immutable, so it may freeze objects passed in as well. Note that the freezing only happens in development.

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

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

API and Examples

Full example

var u = require('updeep');

var person = {
  name: { first: 'Bill', last: 'Sagat' },
  children: [
    { name: 'Mary-Kate', age: 7 },
    { name: 'Ashley', age: 7 }
  ],
  todo: [
    'Be funny',
    'Manage household'
  ],
  email: 'bill@example.com',
  version: 1
};

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

var newPerson = u({
  // Change first name
  name: { first: 'Bob' },
  // Increment all children's ages
  children: u.map({ age: inc }),
  // Update email
  email: 'bob@example.com',
  // Remove todo
  todo: u.reject(eq('Be funny')),
  // Increment version
  version: inc
}, person);
// => {
//  name: { first: 'Bob', last: 'Sagat' },
//  children: [
//    { name: 'Mary-Kate', age: 8 },
//    { name: 'Ashley', age: 8 }
//  ],
//  todo: [
//    'Manage household'
//  ],
//  email: 'bob@example.com',
//  version: 2
//}

NOTE: All functions are curried, so if you see f(x(, y)), it can be called with either f(x, y) or f(x)(y).

Install

$ npm install --save updeep

Configuration

If NODE_ENV is "production", updeep will not attempt to freeze objects. This may yield a slight performance gain.

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.

If you're manipulating massive amounts of data frequently, you may want to benchmark, as Immutable.js should be more efficient in that case.

Contributing

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

Releasing New Version

Login to npm, if you don't have access to the package, ask for it.
```
$ npm login
```
Make sure the build passes (best to let it pass on travis, but you can run it locally):
```
$ gulp
```
Bump the version:
```
$ npm version major|minor|patch
```
Update the CHANGELOG.md.
Add the new version and corresponding notes.
Add a link to the new version.
Update the unreleased link compare to be based off of the new version.

Publish and push:

$ npm publish
$ git push origin master --follow-tags