6.6 KiB
updeep
Easily update nested frozen objects and arrays in a declarative and immutable manner.
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. 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.
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 (as lodash-fp do).
Note that the parameters may be backwards from what you are used to. updeep
supports partial application, so the parameter order is:
updeep(updates, obj)
.
API and Examples
Full example
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
// }
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)
.
u(updates(, object))
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
function inc(i) { return i + 1; }
u({ x: { b: inc } }, { x: { a: 0, b: 0 } });
// => { x: { a: 0, b: 1 } }
Partial application
var setBTo3 = u({ b: 3 });
setBTo3({ a: 0, b: 0 });
// => { a: 0, b: 3 })
ES6 computed properties
var key = 'b';
u({ x: { [key]: 3 } }, { x: { a: 0, b: 0 } });
// => { x: { a: 0, b: 3 } }
u.in(path(, value)(, object))
Update a single value with a simple string or array path.
u.in('a.b', 3, { a: { b: 0 } });
// => { a: { b: 3 } };
function inc(i) { return i + 1; }
u.in('a.b', inc, { a: { b: 0 } });
// => { a: { b: 1 } };
u({
x: u.in(['a', 'b'], 3)
}, { x: { a: { b: 0 } } });
// => { x: { a: { b: 3 } } };
u.omit(predicate(, object))
Remove properties. See _.omit
.
u({ x: u.omit('b') }, { x: { a: 0, b: 0, c: 0 } });
// => { x: { a: 0, c: 0 } }
u({ x: u.omit(['b', 'c']) }, { x: { a: 0, b: 0, c: 0 } });
// => { x: { a: 0 } }
u.reject(predicate(, object))
Reject items from an array. See _.reject
.
function even(i) { return i % 2 === 0 };
u({ x: u.reject(even) }, { x: [1, 2, 3, 4] });
// => { x: [1, 3] }
u.withDefault(default(, updates)(, object))
Like u()
, but start with the default value if the original value is undefined.
u({ x: withDefault([], { 0: 3 }) }, {});
// => { x: [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.
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 master --follow-tags
License
MIT ©2015 Aaron Jensen