[Docs] Update addons.update
Fixes #1815. Add the new `$apply` command, plus a few examples. @petehunt
Cheng Lou committed
Jul 11, 2014 at 19:25 UTC
8ebadf15919331297a2652b4c3a924c212cc411c
1 file changed
+47
-9
docs/docs/09.6-update.md
+47
-9
@@ -14,14 +14,15 @@ Dealing with immutable data in JavaScript is more difficult than in languages de
14
15
If you mutate data like this:
16
17
-```javascript
17
+```js
18
myData.x.y.z = 7;
19
+// or...
20
myData.a.b.push(9);
21
```
22
22
-you have no way of determining which data has changed since the previous copy is destroyed. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
23
+you have no way of determining which data has changed since the previous copy is overriden. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
24
24
-```javascript
25
+```js
26
var newData = deepCopy(myData);
27
newData.x.y.z = 7;
28
newData.a.b.push(9);
@@ -29,7 +30,7 @@ newData.a.b.push(9);
30
31
Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
32
32
-```javascript
33
+```js
34
var newData = extend(myData, {
35
x: extend(myData.x, {
36
y: extend(myData.x.y, {z: 7}),
@@ -42,7 +43,7 @@ While this is fairly performant (since it only shallow copies `log n` objects an
43
44
`update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
45
45
-```javascript
46
+```js
47
var newData = React.addons.update(myData, {
48
x: {y: {z: {$set: 7}}},
49
a: {b: {$push: [9]}}
@@ -55,8 +56,45 @@ The `$`-prefixed keys are called *commands*. The data structure they are "mutati
56
57
## Available commands
58
58
- * `{$push: array}` `push()` all the items in `array` on the target
59
- * `{$unshift: array}` `unshift()` all the items in `array` on the target
59
+ * `{$push: array}` `push()` all the items in `array` on the target.
60
+ * `{$unshift: array}` `unshift()` all the items in `array` on the target.
61
* `{$splice: array of arrays}` for each item in `array()` call `splice()` on the target with the parameters provided by the item.
61
- * `{$set: any}` replace the target entirely
62
- * `{$merge: object}` merge the keys of `object` with the target
62
+ * `{$set: any}` replace the target entirely.
63
+ * `{$merge: object}` merge the keys of `object` with the target.
64
+ * `{$apply: function}` passes in the current value to the function and updates it with the new returned value.
65
+
66
+## Examples
67
+
68
+### Simple push
69
+
70
+```js
71
+var initialArray = [1, 2, 3];
72
+var newArray = update(initialArray, {$push: [4]}); // => [1, 2, 3, 4]
73
+```
74
+`initialArray` is still `[1, 2, 3]`.
75
+
76
+### Nested collections
77
+
78
+```js
79
+var collection = [1, 2, {a: [12, 17, 15]}];
80
+var newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
81
+// => [1, 2, {a: [12, 13, 14, 15]}]
82
+```
83
+This accesses `collection`'s index `2`, key `a`, and does a splice of one item starting from index `1` (to remove `17`) while inserting `13` and `14`.
84
+
85
+### Updating a value based on its current one
86
+
87
+```js
88
+var obj = {a: 5, b: 3};
89
+var newObj = update(obj, {b: {$apply: function(x) {return x * 2;}}});
90
+// => {a: 5, b: 6}
91
+// This is equivalent, but gets verbose for deeply nested collections:
92
+var newObj2 = update(obj, {b: {$set: obj.b * 2}});
93
+```
94
+
95
+### (Shallow) merge
96
+
97
+```js
98
+var obj = {a: 5, b: 3};
99
+var newObj = update(obj, {$merge: {b: 6, c: 7}}); // => {a: 5, b: 6, c: 7}
100
+```