updeep-remeda/README.md
2015-08-01 10:09:25 -07:00

103 lines
3.3 KiB
Markdown

# updeep [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url]
> 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
```js
var u = require('updeep');
// 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
```sh
$ 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][immutablejs] such as debugging and
destructuring. I wanted something more powerful than [icepick] and more
composable than [React.addons.update].
## Contributing
1. Fork it.
1. Create your feature branch (`git checkout -b my-new-feature`).
1. Run `gulp` to run tests and lint.
1. Commit your changes (`git commit -am 'Added some feature'`).
1. Push to the branch (`git push origin my-new-feature`).
1. Create new Pull Request.
## License
MIT ©2015 [Aaron Jensen](https://twitter.com/aaronjensen)
[npm-image]: https://badge.fury.io/js/updeep.svg
[npm-url]: https://npmjs.org/package/updeep
[travis-image]: https://travis-ci.org/aaronjensen/updeep.svg?branch=master
[travis-url]: https://travis-ci.org/aaronjensen/updeep
[daviddm-image]: https://david-dm.org/aaronjensen/updeep.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/aaronjensen/updeep
[lodash]: http://lodash.com
[PureRenderMixin]: https://facebook.github.io/react/docs/pure-render-mixin.html
[redux]: https://github.com/gaearon/redux
[immutablejs]: https://github.com/facebook/immutable-js
[icepick]: https://github.com/aearly/icepick
[React.addons.update]: https://facebook.github.io/react/docs/update.html
[tests]: https://github.com/aaronjensen/updeep/blob/master/test/index.js