0
# Immutable Arrays
1

2
Non-mutating array manipulation functions that return new arrays without modifying the original data structures. These functions are ideal for use with Solid.js signals where immutability is crucial for proper reactivity.
3

4
## Capabilities
5

6
### Basic Array Operations
7

8
Core array operations that return new arrays without modifying the original.
9

10
```typescript { .api }
11
/**
12
 * Non-mutating Array.prototype.push()
13
 * @param list - Original array
14
 * @param items - Items to add
15
 * @returns New array with added items
16
 */
17
function push<T>(list: readonly T[], ...items: T[]): T[];
18

19
/**
20
 * Non-mutating function that drops n items from the array start
21
 * @param list - Original array
22
 * @param n - Number of items to drop (default: 1)
23
 * @returns New array with items dropped from start
24
 */
25
function drop<T>(list: T[], n?: number): T[];
26

27
/**
28
 * Non-mutating function that drops n items from the array end
29
 * @param list - Original array
30
 * @param n - Number of items to drop (default: 1)
31
 * @returns New array with items dropped from end
32
 */
33
function dropRight<T>(list: T[], n?: number): T[];
34

35
/**
36
 * Standalone Array.prototype.slice() function
37
 * @param list - Original array
38
 * @param start - Start index
39
 * @param end - End index
40
 * @returns New sliced array
41
 */
42
function slice<T>(list: readonly T[], start?: number, end?: number): T[];
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import { createSignal } from "solid-js";
49
import { push, drop, dropRight, slice } from "@solid-primitives/utils/immutable";
50

51
const [items, setItems] = createSignal([1, 2, 3]);
52

53
// Add items
54
setItems(current => push(current, 4, 5)); // [1, 2, 3, 4, 5]
55

56
// Drop from start
57
setItems(current => drop(current, 2)); // [3, 4, 5]
58

59
// Drop from end  
60
setItems(current => dropRight(current, 1)); // [3, 4]
61

62
// Slice
63
const subset = slice(items(), 1, 3); // [4] (from current state)
64
```
65

66
### Filtering and Searching
67

68
Functions for filtering arrays and finding specific elements.
69

70
```typescript { .api }
71
/**
72
 * Standalone Array.prototype.filter()
73
 * @param list - Original array
74
 * @param predicate - Filter predicate function
75
 * @returns New filtered array with removed count property
76
 */
77
function filter<T>(list: readonly T[], predicate: Predicate<T>): T[] & { removed: number };
78

79
/**
80
 * Standalone Array.prototype.filter() that filters out passed item
81
 * @param list - Original array
82
 * @param item - Item to filter out
83
 * @returns New filtered array with removed count property
84
 */
85
function filterOut<T>(list: readonly T[], item: T): T[] & { removed: number };
86

87
/**
88
 * Returns a subset of items that are instances of provided Classes
89
 * @param list - Original array
90
 * @param classes - Classes to filter by
91
 * @returns New array with only instances of specified classes
92
 */
93
function filterInstance<T, I extends AnyClass[]>(
94
  list: readonly T[],
95
  ...classes: I
96
): Extract<T, InstanceType<ItemsOf<I>>>[];
97

98
/**
99
 * Returns a subset of items that aren't instances of provided Classes
100
 * @param list - Original array
101
 * @param classes - Classes to filter out
102
 * @returns New array excluding instances of specified classes
103
 */
104
function filterOutInstance<T, I extends AnyClass[]>(
105
  list: readonly T[],
106
  ...classes: I
107
): Exclude<T, InstanceType<ItemsOf<I>>>[];
108

109
type Predicate<T> = (item: T, index: number, array: readonly T[]) => boolean;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { filter, filterOut, filterInstance } from "@solid-primitives/utils/immutable";
116

117
const numbers = [1, 2, 3, 4, 5];
118
const result = filter(numbers, x => x > 3);
119
console.log(result); // [4, 5]
120
console.log(result.removed); // 3
121

122
const withoutTwo = filterOut(numbers, 2); // [1, 3, 4, 5]
123

124
// Class filtering
125
class Dog {}
126
class Cat {}
127
const animals = [new Dog(), new Cat(), new Dog()];
128
const dogs = filterInstance(animals, Dog); // [Dog, Dog]
129
```
130

131
### Transformation and Mapping
132

133
Functions for transforming array elements and structure.
134

135
```typescript { .api }
136
/**
137
 * Standalone Array.prototype.map() function
138
 * @param list - Original array
139
 * @param mapFn - Mapping function
140
 * @returns New mapped array
141
 */
142
function map<T, V>(list: readonly T[], mapFn: MappingFn<T, V>): V[];
143

144
/**
145
 * Flattens a nested array into a one-level array
146
 * @param arr - Nested array to flatten
147
 * @returns Flattened array
148
 */
149
function flatten<T extends any[]>(arr: T): FlattenArray<T>[];
150

151
/**
152
 * Creates a new array concatenating array with any additional arrays and/or values
153
 * @param a - Arrays or values to concatenate
154
 * @returns New concatenated array
155
 */
156
function concat<A extends any[], V extends ItemsOf<A>>(
157
  ...a: A
158
): Array<V extends any[] ? ItemsOf<V> : V>;
159

160
type MappingFn<T, V> = (item: T, index: number, array: readonly T[]) => V;
161
type FlattenArray<T> = T extends any[] ? FlattenArray<ItemsOf<T>> : T;
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { map, flatten, concat } from "@solid-primitives/utils/immutable";
168

169
// Mapping
170
const doubled = map([1, 2, 3], x => x * 2); // [2, 4, 6]
171

172
// Flattening
173
const nested = [[1, 2], [3, [4, 5]]];
174
const flat = flatten(nested); // [1, 2, 3, 4, 5]
175

176
// Concatenation
177
const combined = concat([1, 2], [3, 4], 5); // [1, 2, 3, 4, 5]
178
```
179

180
### Sorting
181

182
Functions for sorting arrays without mutation.
183

184
```typescript { .api }
185
/**
186
 * Non-mutating Array.prototype.sort() as a standalone function
187
 * @param list - Original array
188
 * @param compareFn - Optional comparison function
189
 * @returns New sorted array
190
 */
191
function sort<T>(list: T[], compareFn?: (a: T, b: T) => number): T[];
192

193
/**
194
 * Sort an array by object key, or multiple keys
195
 * @param arr - Array to sort
196
 * @param paths - Property paths or functions to sort by
197
 * @returns New sorted array
198
 */
199
function sortBy<T>(
200
  arr: T[],
201
  ...paths: T extends object ? (Many<keyof T> | Many<(item: T) => any>)[] : Many<(item: T) => any>[]
202
): T[];
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
import { sort, sortBy } from "@solid-primitives/utils/immutable";
209

210
// Basic sorting
211
const sorted = sort([3, 1, 4, 1, 5]); // [1, 1, 3, 4, 5]
212
const descending = sort([3, 1, 4], (a, b) => b - a); // [4, 3, 1]
213

214
// Object sorting
215
const users = [
216
  { name: "Alice", age: 30 },
217
  { name: "Bob", age: 25 },
218
  { name: "Carol", age: 35 }
219
];
220
const byAge = sortBy(users, "age"); // Sorted by age ascending
221
const byName = sortBy(users, user => user.name.toLowerCase());
222
```
223

224
### Modification Operations
225

226
Functions for modifying arrays through splicing and element manipulation.
227

228
```typescript { .api }
229
/**
230
 * Non-mutating Array.prototype.splice() as a standalone function
231
 * @param list - Original array
232
 * @param start - Start index
233
 * @param deleteCount - Number of items to delete (default: 0)
234
 * @param items - Items to insert
235
 * @returns New array with modifications
236
 */
237
function splice<T>(
238
  list: readonly T[],
239
  start: number,
240
  deleteCount?: number,
241
  ...items: T[]
242
): T[];
243

244
/**
245
 * Non-mutating Array.prototype.fill() as a standalone function
246
 * @param list - Original array
247
 * @param value - Value to fill with
248
 * @param start - Start index
249
 * @param end - End index
250
 * @returns New filled array
251
 */
252
function fill<T>(list: readonly T[], value: T, start?: number, end?: number): T[];
253

254
/**
255
 * Remove item from array
256
 * @param list - Original array
257
 * @param item - Item to remove
258
 * @param insertItems - Items to insert in place of removed item
259
 * @returns New array with item removed/replaced
260
 */
261
function remove<T>(list: readonly T[], item: T, ...insertItems: T[]): T[];
262

263
/**
264
 * Remove multiple items from an array
265
 * @param list - Original array
266
 * @param items - Items to remove
267
 * @returns New array with items removed
268
 */
269
function removeItems<T>(list: readonly T[], ...items: T[]): T[];
270
```
271

272
**Usage Examples:**
273

274
```typescript
275
import { splice, fill, remove, removeItems } from "@solid-primitives/utils/immutable";
276

277
const numbers = [1, 2, 3, 4, 5];
278

279
// Splice operations
280
const spliced = splice(numbers, 2, 1, 99); // [1, 2, 99, 4, 5] (removed 3, added 99)
281
const inserted = splice(numbers, 2, 0, 88, 89); // [1, 2, 88, 89, 3, 4, 5]
282

283
// Fill operations
284
const filled = fill([1, 2, 3, 4, 5], 0, 1, 4); // [1, 0, 0, 0, 5]
285

286
// Remove operations
287
const withoutThree = remove(numbers, 3); // [1, 2, 4, 5]
288
const replaced = remove(numbers, 3, 33); // [1, 2, 33, 4, 5]
289
const withoutMultiple = removeItems(numbers, 2, 4); // [1, 3, 5]
290
```
291

292
## Types
293

294
```typescript { .api }
295
type Predicate<T> = (item: T, index: number, array: readonly T[]) => boolean;
296
type MappingFn<T, V> = (item: T, index: number, array: readonly T[]) => V;
297
type FlattenArray<T> = T extends any[] ? FlattenArray<ItemsOf<T>> : T;
298
type Many<T> = T | T[];
299
type ItemsOf<T> = T extends (infer E)[] ? E : never;
300
type AnyClass = abstract new (...args: any) => any;
301
```