Immutable set
This tools aims to facilitate the modification of nested property while preserving immutable principles. Lets say you have the given object:
const state = {
a: {
foo: 'bar',
},
b: {
value: 3,
},
};
If we want to increment b.value
, immutability says that we should generate a new object where
newState === state // false
newState.b === state.b // false
newState.a === state.a // true
That's exactly what our set
function does.
Setup
Add the dependency to your project:
yarn add immutable-set
Parameters
name | description | type | requiered |
---|---|---|---|
base | object to modify | object | |
path | list of keys to access the value to modify | array or string | |
value | value to set | any | |
options | options… | object |
Options
name | description | type | default |
---|---|---|---|
withArray | if set to true number will be interpreted has array indexes |
boolean | false |
equality | if provided, the function will be used to determine if the value at the path is equal to the value provided | function | === |
safe | verify if the value does not already exist | boolean | false |
sameValue | use same value for each nested property in case of multi set | boolean | false |
Usage
Import the set
function
import set from 'immutable-set';
Then set the property you want in your object
const newState = set(state, ['a', 'b'], 42);
// or
const newState = set(state, 'a.b', 42);
/*
newState => {
a: {
b: 42,
},
…
}
*/
The function mutates the object only if the value is not already present in the object.
Advanced usage
with arrays
The option withArrays
allow to dynamically create arrays when the current level is empty and the current path key is a number.
let base = set({}, ['a', 0], 12, { withArrays: true });
// will return { a: [12] }
safe
The option safe
will verify if the value is not already in the object.
const base = { a: 2 };
set(base, 'a', 2, { safe: true })
// will return the base unmodified
equality
The option equality
allows using another equality function instead of ===
. It has to be used with the safe
option.
const base = { a: { id: 1, v: 0 } };
const equality = (a, b) => a.id === b.id && a.v === b.v };
set(base, 'a', { id: 1, v: 0 }, { safe: true, equality);
// will return the base unmodified
set(base, 'a', { id: 1, v: 1 }, { safe: true, equality);
// will return { a: { id: 1, v: 1 } }
multiple set
It is possible to set multiple elements at once, providing multiple keys in the path and an array (or an object) in value.
set({}, ['a', ['b', 'c']], [12, 13]);
// or
set({}, ['a', ['b', 'c']], { b: 12, c: 13 });
// will return { a: { b: 12, c: 13 } }
set({}, ['a', [0, 1 ]], [12, 13], { withArrays: true });
// will return { a: [12, 13] }
It's also possible to set multiple elements at once with the same value by setting sameValue: true
in options.
set({}, ['a', ['b', 'c']], { foo: 'bar' }, { sameValue: true });
// will return { a: { b: { foo: 'bar' }, c: { foo: 'bar' } } }
set({}, ['a', [0, 1 ]], 'foo', { withArrays: true, sameValue: true });
// will return { a: ['foo', 'foo'] }
-
⚠️ If the array of keys is not the last element of the path, the rest of the path will be used for each sub tree. -
⚠️ It's not possible to set objects in array with object sub values, this will throw an error. -
⚠️ For now safe mode does not work with multiple set.