From 7c4ca87e00f0780d454f3148628be2ba88a0fe5d Mon Sep 17 00:00:00 2001 From: Aaron Jensen Date: Sat, 1 Aug 2015 10:09:25 -0700 Subject: [PATCH] Update readme --- README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 78 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6ec1686..5113157 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,61 @@ # 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 @@ -8,24 +63,29 @@ $ npm install --save updeep ``` +Requires [lodash] as a peer dependency, so make sure you have it installed as +well. -## Usage +## Motivation -```js -var u = require('updeep'); +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]. -u({ foo: 3 }, { foo: 1, bar: 2 }); -// => { foo: 3, bar: 2 } +## Contributing -Or with a function: -u({ foo: x => (x + 1) }, { foo: 2 }); -// => { foo: 3 } -``` +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 © [Aaron Jensen](https://twitter.com/aaronjensen) - +MIT ©2015 [Aaron Jensen](https://twitter.com/aaronjensen) [npm-image]: https://badge.fury.io/js/updeep.svg [npm-url]: https://npmjs.org/package/updeep @@ -33,3 +93,10 @@ MIT © [Aaron Jensen](https://twitter.com/aaronjensen) [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