Skip to content

Commit fe84154

Browse files
committed
updated README
1 parent d63e208 commit fe84154

File tree

1 file changed

+58
-0
lines changed

1 file changed

+58
-0
lines changed

README.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ The `$`-prefixed keys are called *commands*. The data structure they are "mutati
8080
* `{$unshift: array}` `unshift()` all the items in `array` on the target.
8181
* `{$splice: array of arrays}` for each item in `arrays` call `splice()` on the target with the parameters provided by the item. ***Note:** The items in the array are applied sequentially, so the order matters. The indices of the target may change during the operation.*
8282
* `{$set: any}` replace the target entirely.
83+
* `{$unset: array of strings}` remove the list of keys in `array` from the target object.
8384
* `{$merge: object}` merge the keys of `object` with the target.
8485
* `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
8586

@@ -119,6 +120,63 @@ const obj = {a: 5, b: 3};
119120
const newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
120121
```
121122

123+
### [Autovivification](https://en.wikipedia.org/wiki/Autovivification)
124+
125+
Autovivification is the auto creation of new arrays and objects when needed. In the context
126+
of javascript that would mean something like this
127+
128+
```js
129+
const state = {}
130+
state.a.b.c = 1; // state would equal { a: { b: { c: 1 } } }
131+
```
132+
133+
Since javascript doesn't have this "feature", the same applies to `immutability-helper`. The reason
134+
why this is practically impossible in javascript and by extension `immutability-helper` is the following:
135+
136+
```js
137+
var state = {}
138+
state.thing[0] = 'foo' // What type should state.thing have? Should it be an object or array?
139+
state.thing2[1] = 'foo2' // What about thing2? This must be an object!
140+
state.thing3 = ['thing3'] // This is regular js, this works without autovivification
141+
state.thing3[1] = 'foo3' // Hmm, notice that state.thing2 is an object, yet this is an array
142+
state.thing2.slice // should be undefined
143+
state.thing2.slice // should be a function
144+
```
145+
146+
If you need to set something deeply nested and don't want to have to set each layer down the line,
147+
consider using this technique which is shown with a contrived example:
148+
149+
```js
150+
var state = {}
151+
var desiredState = {
152+
foo: [
153+
{
154+
bar: ['x', 'y', 'z']
155+
},
156+
],
157+
};
158+
159+
var state2 = update(state, {
160+
foo: {$apply: foo =>
161+
update(foo || [], {
162+
0: {$apply: fooZero =>
163+
update(fooZero || {}, {
164+
bar: {$apply: bar =>
165+
update(bar || [], {$push: ['x', 'y', 'z']})
166+
}
167+
})
168+
}
169+
})
170+
}
171+
})
172+
173+
console.log(JSON.stringify(state2) === JSON.stringify(desiredState)) // true
174+
// note that state could have been declared as any of the following and it would still output true:
175+
// var state = { foo: [] }
176+
// var state = { foo: [ {} ] }
177+
// var state = { foo: [ {bar: []} ] }
178+
```
179+
122180
---
123181

124182
## Adding your own commands

0 commit comments

Comments
 (0)