0
# Immutability Helper
1
2
Immutability Helper provides a MongoDB-inspired syntax for creating modified copies of JavaScript data structures without mutating the original data. It serves as a drop-in replacement for React's deprecated `react-addons-update`, offering powerful immutable update operations with shallow copying for performance.
3
4
## Package Information
5
6
- **Package Name**: immutability-helper
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install immutability-helper`
10
11
## Core Imports
12
13
```typescript
14
import update from "immutability-helper";
15
import { Context, extend, isEquals, invariant } from "immutability-helper";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const update = require("immutability-helper");
22
const { Context, extend, isEquals, invariant } = require("immutability-helper");
23
```
24
25
## Basic Usage
26
27
```typescript
28
import update from "immutability-helper";
29
30
// Update arrays
31
const initialArray = [1, 2, 3];
32
const newArray = update(initialArray, { $push: [4] }); // [1, 2, 3, 4]
33
34
// Update objects
35
const obj = { a: 5, b: 3 };
36
const newObj = update(obj, { b: { $set: 6 } }); // { a: 5, b: 6 }
37
38
// Nested updates
39
const collection = [1, 2, { a: [12, 17, 15] }];
40
const newCollection = update(collection, {
41
2: { a: { $splice: [[1, 1, 13, 14]] } }
42
}); // [1, 2, { a: [12, 13, 14, 15] }]
43
44
// Function-based updates
45
const updated = update(obj, { b: { $apply: x => x * 2 } });
46
```
47
48
## Architecture
49
50
Immutability Helper is built around several core concepts:
51
52
- **Update Function**: The main `update(object, spec)` function that applies specifications to data
53
- **Command System**: MongoDB-inspired `$`-prefixed commands for different operation types
54
- **Context System**: `Context` class for isolated environments with custom commands
55
- **Type Safety**: Full TypeScript support with generic type preservation
56
- **Shallow Copying**: Efficient copying strategy that only copies changed branches
57
- **Reference Equality**: Preserves object references when no changes occur for performance
58
59
## Capabilities
60
61
### Array Operations
62
63
Core operations for modifying arrays including push, unshift, and splice operations.
64
65
```typescript { .api }
66
// Push items to end of array
67
{ $push: ReadonlyArray<T> }
68
69
// Add items to beginning of array
70
{ $unshift: ReadonlyArray<T> }
71
72
// Perform splice operations
73
{ $splice: ReadonlyArray<[number, number?] | [number, number, ...T[]]> }
74
```
75
76
[Array Operations](./array-operations.md)
77
78
### Object Operations
79
80
Operations for modifying object properties including set, merge, toggle, and unset.
81
82
```typescript { .api }
83
// Replace target entirely
84
{ $set: T }
85
86
// Shallow merge properties
87
{ $merge: Partial<T> }
88
89
// Toggle boolean fields
90
{ $toggle: ReadonlyArray<keyof T> }
91
92
// Remove properties
93
{ $unset: ReadonlyArray<keyof T> }
94
```
95
96
[Object Operations](./object-operations.md)
97
98
### Map and Set Operations
99
100
Specialized operations for ES6 Map and Set data structures.
101
102
```typescript { .api }
103
// Add entries to Map or Set
104
{ $add: ReadonlyArray<[K, V]> | ReadonlyArray<T> }
105
106
// Remove entries from Map or Set
107
{ $remove: ReadonlyArray<K> }
108
```
109
110
[Map and Set Operations](./map-set-operations.md)
111
112
### Function Operations
113
114
Function-based operations for complex transformations and custom logic.
115
116
```typescript { .api }
117
// Apply function to current value
118
{ $apply: (v: T) => T }
119
120
// Shorthand: pass function directly
121
(v: T) => T
122
```
123
124
[Function Operations](./function-operations.md)
125
126
### Context and Extension System
127
128
Advanced features for creating isolated contexts and adding custom commands.
129
130
```typescript { .api }
131
class Context {
132
constructor();
133
extend<T>(directive: string, fn: (param: any, old: T) => T): void;
134
update<T, C extends CustomCommands<object> = never>(object: T, $spec: Spec<T, C>): T;
135
get isEquals(): (x: any, y: any) => boolean;
136
set isEquals(value: (x: any, y: any) => boolean);
137
}
138
139
function extend<T>(directive: string, fn: (param: any, old: T) => T): void;
140
```
141
142
[Extension System](./extension-system.md)
143
144
## Limitations
145
146
**Important:** The `update` function only works for _data properties_, not for _accessor properties_ defined with `Object.defineProperty`. It does not see accessor properties and may create shadowing data properties which could break application logic depending on setter side effects. Therefore `update` should only be used on plain data objects that contain only _data properties_ as descendants.
147
148
## Core Types
149
150
```typescript { .api }
151
// Main update function type
152
function update<T, C extends CustomCommands<object> = never>(
153
object: T,
154
$spec: Spec<T, C>
155
): T;
156
157
// Specification type for updates
158
type Spec<T, C extends CustomCommands<object> = never> =
159
| (T extends (Array<infer U> | ReadonlyArray<infer U>) ? ArraySpec<U, C> :
160
T extends (Map<infer K, infer V> | ReadonlyMap<infer K, infer V>) ? MapSpec<K, V, C> :
161
T extends (Set<infer X> | ReadonlySet<infer X>) ? SetSpec<X> :
162
T extends object ? ObjectSpec<T, C> :
163
never)
164
| { $set: T }
165
| { $apply: (v: T) => T }
166
| ((v: T) => T)
167
| (C extends CustomCommands<infer O> ? O : never);
168
169
// Custom commands type brand
170
type CustomCommands<T> = T & { __noInferenceCustomCommandsBrand: any };
171
172
// Specialized spec types
173
type ArraySpec<T, C extends CustomCommands<object>> =
174
| { $push: ReadonlyArray<T> }
175
| { $unshift: ReadonlyArray<T> }
176
| { $splice: ReadonlyArray<[number, number?] | [number, number, ...T[]]> }
177
| { [index: string]: Spec<T, C> };
178
179
type MapSpec<K, V, C extends CustomCommands<object>> =
180
| { $add: ReadonlyArray<[K, V]> }
181
| { $remove: ReadonlyArray<K> }
182
| { [key: string]: Spec<V, C> };
183
184
type SetSpec<T> =
185
| { $add: ReadonlyArray<T> }
186
| { $remove: ReadonlyArray<T> };
187
188
type ObjectSpec<T, C extends CustomCommands<object>> =
189
| { $toggle: ReadonlyArray<keyof T> }
190
| { $unset: ReadonlyArray<keyof T> }
191
| { $merge: Partial<T> }
192
| { [K in keyof T]?: Spec<T[K], C> };
193
194
// Utility functions
195
/**
196
* Throws an error if condition is false
197
* @param condition - Boolean condition to check
198
* @param message - Function that returns error message
199
*/
200
function invariant(condition: boolean, message: () => string): void;
201
202
/**
203
* Default equality function used for change detection
204
* Can be overridden via Context.isEquals
205
*/
206
const isEquals: (x: any, y: any) => boolean;
207
```