-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.hbs
201 lines (152 loc) · 6.31 KB
/
README.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
[](https://circleci.com/gh/andres-kovalev/immutable-object-update)
[](https://codecov.io/gh/andres-kovalev/immutable-object-update)
[](https://www.npmjs.com/package/immutable-object-update)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/immutable-object-update)
[](https://github.com/andres-kovalev/immutable-object-update/blob/master/LICENSE)
[](https://www.npmjs.com/package/immutable-object-update)
[](https://conventionalcommits.org)
# immutable-object-update
Simple and fast immutable update utility.
* full documentation can be found on [https://andres-kovalev.github.io/immutable-object-update/](https://andres-kovalev.github.io/immutable-object-update/)
* playground with couple examples can be found [here](https://repl.it/@andreskovalev/immutable-object-update-playground)
# 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:
```bash
npm i -S immutable-object-update
```
# API
There are several operations provided by this package:
{{#each operations}}
* [{{fn}}](src/operations/{{name}}/README.md)
{{/each}}
Most of operations consumes at least 2 arguments:
- `object` to be updated
- `path` to updated element
The 2nd argument might be an array of items or dot-separated string.
```js
import { set } from 'immutable-object-update';
const state = {
a: {
a1: 1,
a2: 2
},
b: {
b1: 3,
b2: 4
}
};
const updated = set(state, [ 'b', 'b1' ], 5);
// or
const updated = set(state, 'b.b1', 5);
```
As a result we will receive new object with structure below:
```js
{
a: {
a1: 1,
a2: 2
},
b: {
b1: 3,
b2: 5
}
}
```
New object will keep the same refs when necessary:
```js
state === updated // false
state.a === updated.a // true (structure of a hasn't changed)
state.a.a1 === updated.a.a1 // true
state.a.a2 === updated.a.a2 // true
state.b === updated.b // false
state.b.b1 === updated.b.b1 // true
state.b.b2 === updated.b.b2 // 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:
```js
const updated = set({
'a.b': 1,
a: {
b: 2
}
}, 'a.b', 3);
/*
{
'a.b': 1,
a: {
b: 3
}
}
*/
```
If you need to update such keys, use array type path instead:
```js
const updated = set({
'a.b': 1,
a: {
b: 2
}
}, [ 'a.b' ], 3);
/*
{
'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:
```js
const updated = set({}, 'a.b', 10);
/*
{
a: {
b: 10
}
}
*/
```
It can even create new objects when no source object provided:
```js
const updated = set(undefined, 'a.b', 10);
/*
{
a: {
b: 10
}
}
*/
```
It tries to predict type of created object. For instance, when path contains number, array will be created:
```js
const updated = set({}, 'a.0', 1);
/*
{
a: [ 1 ]
}
*/
```
To prevent further accidental mutation all operations returns frozen updated object.
```js
const updated = set(source, 'b.b1', 6);
updated.b.b1 = 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:
```js
const setB1to6 = set('b.b1', 6);
const updated = setB1to6(state); // equal to set(state, 'b.b1', 6);
```
When partial application is used, updated object should be passed last:
```js
const setB1 = set('b.b1');
const setB1to6 = setB1(6); // equal to set('b.b1', 6);
```
There are several helpful functions provided to make work with partially applied operations easier:
{{#each functionals}}
* [{{fn}}](./src/functional/{{name}}/README.md)
{{/each}}