0
# Array Operations
1

2
Core operations for modifying arrays including adding items to the beginning or end, and performing splice operations. All operations create new arrays without mutating the original.
3

4
## Capabilities
5

6
### Push Operation
7

8
Appends items to the end of an array.
9

10
```typescript { .api }
11
/**
12
 * Push items to the end of an array
13
 * @param value - Array of items to append
14
 * @returns New array with items appended
15
 */
16
{ $push: ReadonlyArray<T> }
17
```
18

19
**Usage Examples:**
20

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

24
// Basic push
25
const arr = [1, 2, 3];
26
const result = update(arr, { $push: [4, 5] });
27
// Result: [1, 2, 3, 4, 5]
28

29
// Push to nested array
30
const data = { items: ['a', 'b'] };
31
const updated = update(data, { items: { $push: ['c', 'd'] } });
32
// Result: { items: ['a', 'b', 'c', 'd'] }
33

34
// Empty push preserves reference
35
const original = [1, 2, 3];
36
const unchanged = update(original, { $push: [] });
37
console.log(unchanged === original); // true
38
```
39

40
### Unshift Operation
41

42
Prepends items to the beginning of an array.
43

44
```typescript { .api }
45
/**
46
 * Add items to the beginning of an array
47
 * @param value - Array of items to prepend
48
 * @returns New array with items prepended
49
 */
50
{ $unshift: ReadonlyArray<T> }
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import update from "immutability-helper";
57

58
// Basic unshift
59
const arr = [3, 4, 5];
60
const result = update(arr, { $unshift: [1, 2] });
61
// Result: [1, 2, 3, 4, 5]
62

63
// Unshift to nested array
64
const data = { queue: ['task2', 'task3'] };
65
const updated = update(data, { queue: { $unshift: ['task1'] } });
66
// Result: { queue: ['task1', 'task2', 'task3'] }
67
```
68

69
### Splice Operation
70

71
Performs multiple splice operations on an array. Each splice operation is specified as an array of arguments that would be passed to Array.prototype.splice().
72

73
```typescript { .api }
74
/**
75
 * Perform splice operations on an array
76
 * @param value - Array of splice operation arguments
77
 * Each splice operation: [start, deleteCount?, ...itemsToInsert]
78
 * @returns New array with splice operations applied sequentially
79
 */
80
{ $splice: ReadonlyArray<[number, number?] | [number, number, ...T[]]> }
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import update from "immutability-helper";
87

88
// Remove items
89
const arr = [1, 2, 3, 4, 5];
90
const removed = update(arr, { $splice: [[1, 2]] }); // Remove 2 items starting at index 1
91
// Result: [1, 4, 5]
92

93
// Replace items
94
const replaced = update(arr, { $splice: [[1, 1, 'a', 'b']] }); // Replace 1 item at index 1 with 'a', 'b'
95
// Result: [1, 'a', 'b', 3, 4, 5]
96

97
// Multiple splice operations (applied sequentially)
98
const multi = update([0, 1, 2, 3, 4], { 
99
  $splice: [
100
    [1, 1],        // Remove 1 item at index 1
101
    [2, 0, 'x']    // Insert 'x' at index 2 (after first operation)
102
  ] 
103
});
104
// Result: [0, 2, 'x', 3, 4]
105

106
// Insert without removing
107
const inserted = update(arr, { $splice: [[2, 0, 'new']] });
108
// Result: [1, 2, 'new', 3, 4, 5]
109

110
// Delete element at specific index (common pattern)
111
const items = ['a', 'b', 'c', 'd'];
112
const index = 2;
113
const withDeleted = update(items, { $splice: [[index, 1]] });
114
// Result: ['a', 'b', 'd'] (removed 'c' at index 2)
115

116
// Nested array splice
117
const data = { list: [10, 20, 30, 40] };
118
const updated = update(data, { 
119
  list: { $splice: [[1, 1, 25]] } 
120
});
121
// Result: { list: [10, 25, 30, 40] }
122

123
// Computed property names (ES2015 feature)
124
const collection = { children: ['zero', 'one', 'two'] };
125
const index = 1;
126
const updated = update(collection, { 
127
  children: { [index]: { $set: 'updated' } } 
128
});
129
// Result: { children: ['zero', 'updated', 'two'] }
130
```
131

132
## Error Handling
133

134
Array operations validate their inputs and throw descriptive errors:
135

136
- `$push` and `$unshift` require the target to be an array
137
- `$push` and `$unshift` require the spec value to be an array
138
- `$splice` requires the target to be an array
139
- `$splice` requires the spec value to be an array of arrays
140
- Each splice operation must be an array of valid splice arguments
141

142
```typescript
143
// These will throw errors:
144
update(123, { $push: [1] }); // Target must be array
145
update([1], { $push: 123 }); // Spec must be array
146
update([1], { $splice: 123 }); // Spec must be array of arrays
147
update([1], { $splice: [123] }); // Each splice must be array
148
```
149

150
## Performance Notes
151

152
- Operations preserve reference equality when no changes occur (e.g., empty push/unshift)
153
- Only creates new arrays when modifications are actually made
154
- Splice operations are applied sequentially, so order matters for indices
155
- Uses shallow copying for optimal performance