immutable-object-update
Simple and fast immutable update utility.
- full documentation can be found on https://andres-kovalev.github.io/immutable-object-update/
Description
immutable-object-update
provides simple utilities for immutable object update (pretty helpful for reducers).
Installation
As any other npm package immutable-object-update
can be added to your project by following command:
npm i -S immutable-object-update
API
There are several operations provided by this package:
- filter(object, path, predicate)
- get(object, path)
- insert(object, path, value)
- insertAll(object, path, values)
- map(object, path, transform)
- pop(object, path)
- popN(object, path, n)
- push(object, path, value)
- pushAll(object, path, values)
- reduce(object, path, reducer)
- remove(object, path)
- removeN(object, path, n)
- set(object, path, value)
- shift(object, path)
- shiftN(object, path, n)
- unshift(object, path, value)
- unshiftAll(object, path, values)
- update(object, path, update)
Most of operations consumes at least 2 arguments:
object
to be updatedpath
to updated element
The 2nd argument might be an array of items or dot-separated string.
; const state = a: a1: 1 a2: 2 b: b1: 3 b2: 4 ; const updated = ; // or const updated = ;
As a result we will receive new object with structure below:
a: a1: 1 a2: 2 b: b1: 3 b2: 5
New object will keep the same refs when necessary:
state === updated // falsestatea === updateda // true (structure of a hasn't changed)stateaa1 === updatedaa1 // truestateaa2 === updatedaa2 // truestateb === updatedb // falsestatebb1 === updatedbb1 // truestatebb2 === updatedbb2 // false
When using string as 2nd argument - dot will be considered as a delimiter (e.g. a.b
means field b
of field a
). So, it's not possible to update keys which contains dots with string type path:
const updated = ; /*{ 'a.b': 1, a: { b: 3 }}*/
If you need to update such keys, use array type path instead:
const updated = ; /*{ 'a.b': 3, a: { b: 2 }}*/
Utility also ignores empty path (e.g. a..b
equal to a.b
) and will create intermediate fields by itself when needed:
const updated = ; /*{ a: { b: 10 }}*/
It can even create new objects when no source object provided:
const updated = ; /*{ a: { b: 10 }}*/
It tries to predict type of created object. For instance, when path contains number, array will be created:
const updated = ; /*{ a: [ 1 ]}*/
To prevent further accidental mutation all operations returns frozen updated object.
const updated = ; updatedbb1 = 10; // updated.b.b1 still has value of 6
Partial application
All operations supports partial application - when object arguments is not provided, operation returns update function:
const setB1to6 = ; const updated = ; // equal to set(state, 'b.b1', 6);
When partial application is used, updated object should be passed last:
const setB1 = ;const setB1to6 = ; // equal to set('b.b1', 6);
There are several helpful functions provided to make work with partially applied operations easier: