0
# Object Operations
1

2
Operations for modifying object properties including complete replacement, merging properties, toggling boolean fields, and removing properties. All operations create new objects without mutating the original.
3

4
## Capabilities
5

6
### Set Operation
7

8
Replaces the target entirely with a new value.
9

10
```typescript { .api }
11
/**
12
 * Replace the target entirely with a new value
13
 * @param value - New value to replace the target
14
 * @returns The new value
15
 */
16
{ $set: T }
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import update from "immutability-helper";
23

24
// Replace primitive value
25
const obj = { count: 5 };
26
const updated = update(obj, { count: { $set: 10 } });
27
// Result: { count: 10 }
28

29
// Replace object property
30
const data = { user: { name: 'Alice', age: 25 } };
31
const replaced = update(data, { 
32
  user: { $set: { name: 'Bob', age: 30, role: 'admin' } } 
33
});
34
// Result: { user: { name: 'Bob', age: 30, role: 'admin' } }
35

36
// Replace array
37
const state = { items: [1, 2, 3] };
38
const newState = update(state, { items: { $set: ['a', 'b'] } });
39
// Result: { items: ['a', 'b'] }
40

41
// Replace entire object
42
const result = update({ a: 1, b: 2 }, { $set: { c: 3 } });
43
// Result: { c: 3 }
44
```
45

46
### Merge Operation
47

48
Performs a shallow merge of properties from the spec into the target object.
49

50
```typescript { .api }
51
/**
52
 * Shallow merge properties into the target object
53
 * @param value - Object containing properties to merge
54
 * @returns New object with merged properties
55
 */
56
{ $merge: Partial<T> }
57
```
58

59
**Usage Examples:**
60

61
```typescript
62
import update from "immutability-helper";
63

64
// Basic merge
65
const user = { name: 'Alice', age: 25, role: 'user' };
66
const updated = update(user, { 
67
  $merge: { age: 26, role: 'admin' } 
68
});
69
// Result: { name: 'Alice', age: 26, role: 'admin' }
70

71
// Add new properties
72
const obj = { a: 1 };
73
const merged = update(obj, { $merge: { b: 2, c: 3 } });
74
// Result: { a: 1, b: 2, c: 3 }
75

76
// Nested merge
77
const data = { 
78
  config: { theme: 'dark', lang: 'en' },
79
  user: { name: 'Alice' }
80
};
81
const result = update(data, { 
82
  config: { $merge: { theme: 'light', debug: true } } 
83
});
84
// Result: { 
85
//   config: { theme: 'light', lang: 'en', debug: true },
86
//   user: { name: 'Alice' }
87
// }
88
```
89

90
### Toggle Operation
91

92
Toggles boolean fields in the target object.
93

94
```typescript { .api }
95
/**
96
 * Toggle boolean fields in the target object
97
 * @param targets - Array of property keys to toggle
98
 * @returns New object with toggled boolean properties
99
 */
100
{ $toggle: ReadonlyArray<keyof T> }
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import update from "immutability-helper";
107

108
// Toggle single field
109
const settings = { darkMode: false, notifications: true };
110
const toggled = update(settings, { $toggle: ['darkMode'] });
111
// Result: { darkMode: true, notifications: true }
112

113
// Toggle multiple fields
114
const flags = { 
115
  isActive: true, 
116
  isVisible: false, 
117
  isEditable: true 
118
};
119
const updated = update(flags, { 
120
  $toggle: ['isActive', 'isVisible'] 
121
});
122
// Result: { isActive: false, isVisible: true, isEditable: true }
123

124
// Nested toggle
125
const data = { 
126
  user: { isOnline: false, hasNotifications: true },
127
  system: { maintenanceMode: false }
128
};
129
const result = update(data, { 
130
  user: { $toggle: ['isOnline', 'hasNotifications'] } 
131
});
132
// Result: { 
133
//   user: { isOnline: true, hasNotifications: false },
134
//   system: { maintenanceMode: false }
135
// }
136
```
137

138
### Unset Operation
139

140
Removes specified properties from the target object.
141

142
```typescript { .api }
143
/**
144
 * Remove properties from the target object
145
 * @param keys - Array of property keys to remove
146
 * @returns New object with specified properties removed
147
 */
148
{ $unset: ReadonlyArray<keyof T> }
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import update from "immutability-helper";
155

156
// Remove single property
157
const user = { name: 'Alice', age: 25, temp: 'remove me' };
158
const cleaned = update(user, { $unset: ['temp'] });
159
// Result: { name: 'Alice', age: 25 }
160

161
// Remove multiple properties
162
const obj = { a: 1, b: 2, c: 3, d: 4 };
163
const filtered = update(obj, { $unset: ['b', 'd'] });
164
// Result: { a: 1, c: 3 }
165

166
// Nested unset
167
const data = { 
168
  config: { theme: 'dark', debug: true, tempFlag: 'delete' },
169
  user: { name: 'Alice' }
170
};
171
const result = update(data, { 
172
  config: { $unset: ['debug', 'tempFlag'] } 
173
});
174
// Result: { 
175
//   config: { theme: 'dark' },
176
//   user: { name: 'Alice' }
177
// }
178

179
// Attempting to remove non-existent property (no effect)
180
const safe = update({ a: 1 }, { $unset: ['nonexistent'] });
181
// Result: { a: 1 } (unchanged)
182
```
183

184
## Error Handling
185

186
Object operations validate their inputs and throw descriptive errors:
187

188
- `$set` cannot be combined with other commands in the same specification object
189
- `$merge` requires both the target and spec value to be objects
190
- `$toggle` requires the spec value to be an array
191
- `$unset` requires the spec value to be an array
192

193
```typescript
194
// These will throw errors:
195
update({}, { $set: 1, $merge: {} }); // Cannot combine $set with other commands
196
update('string', { $merge: {} }); // Target must be object for $merge
197
update({}, { $merge: 'string' }); // Spec must be object for $merge
198
update({}, { $toggle: 'field' }); // Spec must be array for $toggle
199
update({}, { $unset: 'field' }); // Spec must be array for $unset
200
```
201

202
## Performance Notes
203

204
- Operations preserve reference equality when no changes occur
205
- `$unset` only creates a new object if properties actually exist and are removed
206
- `$toggle` only creates a new object if there are fields to toggle
207
- `$merge` only creates a new object if there are actual changes to merge
208
- Uses shallow copying for optimal performance