0
# List Operations
1

2
Comprehensive array manipulation functions with functional programming patterns. The List module provides 69 functions covering iteration, transformation, folding, sorting, searching, and mathematical operations on arrays.
3

4
## Capabilities
5

6
### Iteration and Transformation
7

8
Core functions for iterating over and transforming arrays.
9

10
```javascript { .api }
11
/**
12
 * Applies function to each element, returns original array
13
 * @param {Function} fn - Function to apply to each element
14
 * @param {Array} array - Array to iterate over
15
 * @returns {Array} Original array (for chaining)
16
 */
17
function each(fn, array);
18

19
/**
20
 * Transforms each element using provided function
21
 * @param {Function} fn - Transformation function
22
 * @param {Array} array - Array to transform
23
 * @returns {Array} New array with transformed elements
24
 */
25
function map(fn, array);
26

27
/**
28
 * Removes falsy values from array
29
 * @param {Array} array - Array to compact
30
 * @returns {Array} Array without falsy values
31
 */
32
function compact(array);
33

34
/**
35
 * Keeps elements that match predicate
36
 * @param {Function} predicate - Function returning boolean
37
 * @param {Array} array - Array to filter
38
 * @returns {Array} Filtered array
39
 */
40
function filter(predicate, array);
41

42
/**
43
 * Removes elements that match predicate
44
 * @param {Function} predicate - Function returning boolean
45
 * @param {Array} array - Array to filter
46
 * @returns {Array} Array with rejected elements removed
47
 */
48
function reject(predicate, array);
49

50
/**
51
 * Removes first occurrence of element
52
 * @param {*} element - Element to remove
53
 * @param {Array} array - Array to modify
54
 * @returns {Array} Array with element removed
55
 */
56
function remove(element, array);
57

58
/**
59
 * Splits array into [passed, failed] based on predicate
60
 * @param {Function} predicate - Function returning boolean
61
 * @param {Array} array - Array to partition
62
 * @returns {Array} [passed, failed] arrays
63
 */
64
function partition(predicate, array);
65

66
/**
67
 * Finds first element matching predicate
68
 * @param {Function} predicate - Function returning boolean
69
 * @param {Array} array - Array to search
70
 * @returns {*} First matching element or undefined
71
 */
72
function find(predicate, array);
73
```
74

75
### Array Access and Structure
76

77
Functions for accessing and manipulating array structure.
78

79
```javascript { .api }
80
/**
81
 * Gets first element of array
82
 * @param {Array} array - Array to access
83
 * @returns {*} First element or undefined
84
 */
85
function head(array);
86

87
/**
88
 * Alias for head - gets first element
89
 * @param {Array} array - Array to access
90
 * @returns {*} First element or undefined
91
 */
92
function first(array);
93

94
/**
95
 * Gets all elements except first
96
 * @param {Array} array - Array to access
97
 * @returns {Array} Array without first element
98
 */
99
function tail(array);
100

101
/**
102
 * Gets last element of array
103
 * @param {Array} array - Array to access
104
 * @returns {*} Last element or undefined
105
 */
106
function last(array);
107

108
/**
109
 * Gets all elements except last
110
 * @param {Array} array - Array to access
111
 * @returns {Array} Array without last element
112
 */
113
function initial(array);
114

115
/**
116
 * Checks if array is empty
117
 * @param {Array} array - Array to check
118
 * @returns {boolean} True if array has no elements
119
 */
120
function empty(array);
121

122
/**
123
 * Reverses array (returns new array)
124
 * @param {Array} array - Array to reverse
125
 * @returns {Array} Reversed array
126
 */
127
function reverse(array);
128
```
129

130
### Set Operations
131

132
Functions for set-like operations on arrays.
133

134
```javascript { .api }
135
/**
136
 * Elements in first array not in others (variadic)
137
 * @param {...Array} arrays - Arrays to compare
138
 * @returns {Array} Elements unique to first array
139
 */
140
function difference(...arrays);
141

142
/**
143
 * Elements common to all arrays (variadic)
144
 * @param {...Array} arrays - Arrays to intersect
145
 * @returns {Array} Common elements
146
 */
147
function intersection(...arrays);
148

149
/**
150
 * All unique elements from all arrays (variadic)
151
 * @param {...Array} arrays - Arrays to unite
152
 * @returns {Array} Union of all arrays
153
 */
154
function union(...arrays);
155

156
/**
157
 * Removes duplicate elements
158
 * @param {Array} array - Array to process
159
 * @returns {Array} Array with unique elements
160
 */
161
function unique(array);
162

163
/**
164
 * Removes duplicates based on function result
165
 * @param {Function} fn - Function to determine uniqueness
166
 * @param {Array} array - Array to process
167
 * @returns {Array} Array with unique elements by function
168
 */
169
function uniqueBy(fn, array);
170
```
171

172
### Folding and Reduction
173

174
Functions for reducing arrays to single values.
175

176
```javascript { .api }
177
/**
178
 * Left fold with initial value (alias: foldl)
179
 * @param {Function} fn - Reducer function (acc, val) => newAcc
180
 * @param {*} initial - Initial accumulator value
181
 * @param {Array} array - Array to fold
182
 * @returns {*} Final accumulated value
183
 */
184
function fold(fn, initial, array);
185

186
/**
187
 * Alias for fold - left fold with initial value
188
 * @param {Function} fn - Reducer function
189
 * @param {*} initial - Initial accumulator value
190
 * @param {Array} array - Array to fold
191
 * @returns {*} Final accumulated value
192
 */
193
function foldl(fn, initial, array);
194

195
/**
196
 * Left fold using first element as initial (alias: foldl1)
197
 * @param {Function} fn - Reducer function
198
 * @param {Array} array - Non-empty array to fold
199
 * @returns {*} Final accumulated value
200
 */
201
function fold1(fn, array);
202

203
/**
204
 * Alias for fold1 - left fold using first element
205
 * @param {Function} fn - Reducer function
206
 * @param {Array} array - Non-empty array to fold
207
 * @returns {*} Final accumulated value
208
 */
209
function foldl1(fn, array);
210

211
/**
212
 * Right fold with initial value
213
 * @param {Function} fn - Reducer function (val, acc) => newAcc
214
 * @param {*} initial - Initial accumulator value
215
 * @param {Array} array - Array to fold
216
 * @returns {*} Final accumulated value
217
 */
218
function foldr(fn, initial, array);
219

220
/**
221
 * Right fold using last element as initial
222
 * @param {Function} fn - Reducer function
223
 * @param {Array} array - Non-empty array to fold
224
 * @returns {*} Final accumulated value
225
 */
226
function foldr1(fn, array);
227

228
/**
229
 * Unfolds array from seed value using function
230
 * @param {Function} fn - Function returning [value, newSeed] or null
231
 * @param {*} seed - Initial seed value
232
 * @returns {Array} Unfolded array
233
 */
234
function unfoldr(fn, seed);
235
```
236

237
### Logical Operations
238

239
Functions for logical operations on arrays.
240

241
```javascript { .api }
242
/**
243
 * Logical AND of all elements
244
 * @param {Array} array - Array of values
245
 * @returns {boolean} True if all elements are truthy
246
 */
247
function andList(array);
248

249
/**
250
 * Logical OR of all elements
251
 * @param {Array} array - Array of values
252
 * @returns {boolean} True if any element is truthy
253
 */
254
function orList(array);
255

256
/**
257
 * Tests if any element matches predicate
258
 * @param {Function} predicate - Function returning boolean
259
 * @param {Array} array - Array to test
260
 * @returns {boolean} True if any element matches
261
 */
262
function any(predicate, array);
263

264
/**
265
 * Tests if all elements match predicate
266
 * @param {Function} predicate - Function returning boolean
267
 * @param {Array} array - Array to test
268
 * @returns {boolean} True if all elements match
269
 */
270
function all(predicate, array);
271
```
272

273
### Sorting and Ordering
274

275
Functions for sorting arrays.
276

277
```javascript { .api }
278
/**
279
 * Sorts array using default comparison
280
 * @param {Array} array - Array to sort
281
 * @returns {Array} Sorted array
282
 */
283
function sort(array);
284

285
/**
286
 * Sorts using custom comparison function
287
 * @param {Function} compareFn - Comparison function (a, b) => number
288
 * @param {Array} array - Array to sort
289
 * @returns {Array} Sorted array
290
 */
291
function sortWith(compareFn, array);
292

293
/**
294
 * Sorts by result of function applied to elements
295
 * @param {Function} fn - Function to extract sort key
296
 * @param {Array} array - Array to sort
297
 * @returns {Array} Sorted array
298
 */
299
function sortBy(fn, array);
300
```
301

302
### Mathematical Operations
303

304
Functions for mathematical operations on arrays of numbers.
305

306
```javascript { .api }
307
/**
308
 * Sum of all numbers in array
309
 * @param {Array<number>} array - Array of numbers
310
 * @returns {number} Sum of all numbers
311
 */
312
function sum(array);
313

314
/**
315
 * Product of all numbers in array
316
 * @param {Array<number>} array - Array of numbers
317
 * @returns {number} Product of all numbers
318
 */
319
function product(array);
320

321
/**
322
 * Arithmetic mean of numbers (alias: average)
323
 * @param {Array<number>} array - Array of numbers
324
 * @returns {number} Arithmetic mean
325
 */
326
function mean(array);
327

328
/**
329
 * Alias for mean - arithmetic mean of numbers
330
 * @param {Array<number>} array - Array of numbers
331
 * @returns {number} Arithmetic mean
332
 */
333
function average(array);
334

335
/**
336
 * Largest element in array
337
 * @param {Array} array - Array to search
338
 * @returns {*} Maximum element
339
 */
340
function maximum(array);
341

342
/**
343
 * Smallest element in array
344
 * @param {Array} array - Array to search
345
 * @returns {*} Minimum element
346
 */
347
function minimum(array);
348

349
/**
350
 * Largest element by function result
351
 * @param {Function} fn - Function to extract comparison value
352
 * @param {Array} array - Array to search
353
 * @returns {*} Element with maximum function result
354
 */
355
function maximumBy(fn, array);
356

357
/**
358
 * Smallest element by function result
359
 * @param {Function} fn - Function to extract comparison value
360
 * @param {Array} array - Array to search
361
 * @returns {*} Element with minimum function result
362
 */
363
function minimumBy(fn, array);
364
```
365

366
### Array Manipulation
367

368
Functions for combining and manipulating arrays.
369

370
```javascript { .api }
371
/**
372
 * Concatenates array of arrays
373
 * @param {Array<Array>} arrays - Array containing arrays to concatenate
374
 * @returns {Array} Flattened array
375
 */
376
function concat(arrays);
377

378
/**
379
 * Maps function then concatenates results
380
 * @param {Function} fn - Function returning array
381
 * @param {Array} array - Array to map over
382
 * @returns {Array} Concatenated results
383
 */
384
function concatMap(fn, array);
385

386
/**
387
 * Recursively flattens nested arrays
388
 * @param {Array} array - Nested array structure
389
 * @returns {Array} Completely flattened array
390
 */
391
function flatten(array);
392
```
393

394
### Scanning
395

396
Functions for intermediate results during folding.
397

398
```javascript { .api }
399
/**
400
 * Left scan - returns intermediate fold results (alias: scanl)
401
 * @param {Function} fn - Reducer function
402
 * @param {*} initial - Initial value
403
 * @param {Array} array - Array to scan
404
 * @returns {Array} Array of intermediate results
405
 */
406
function scan(fn, initial, array);
407

408
/**
409
 * Alias for scan - left scan with initial value
410
 * @param {Function} fn - Reducer function
411
 * @param {*} initial - Initial value
412
 * @param {Array} array - Array to scan
413
 * @returns {Array} Array of intermediate results
414
 */
415
function scanl(fn, initial, array);
416

417
/**
418
 * Left scan using first element as initial (alias: scanl1)
419
 * @param {Function} fn - Reducer function
420
 * @param {Array} array - Non-empty array to scan
421
 * @returns {Array} Array of intermediate results
422
 */
423
function scan1(fn, array);
424

425
/**
426
 * Alias for scan1 - left scan using first element
427
 * @param {Function} fn - Reducer function
428
 * @param {Array} array - Non-empty array to scan
429
 * @returns {Array} Array of intermediate results
430
 */
431
function scanl1(fn, array);
432

433
/**
434
 * Right scan with initial value
435
 * @param {Function} fn - Reducer function
436
 * @param {*} initial - Initial value
437
 * @param {Array} array - Array to scan
438
 * @returns {Array} Array of intermediate results
439
 */
440
function scanr(fn, initial, array);
441

442
/**
443
 * Right scan using last element as initial
444
 * @param {Function} fn - Reducer function
445
 * @param {Array} array - Non-empty array to scan
446
 * @returns {Array} Array of intermediate results
447
 */
448
function scanr1(fn, array);
449
```
450

451
### Slicing and Taking
452

453
Functions for extracting portions of arrays.
454

455
```javascript { .api }
456
/**
457
 * Extracts section of array
458
 * @param {number} start - Start index (inclusive)
459
 * @param {number} end - End index (exclusive)
460
 * @param {Array} array - Array to slice
461
 * @returns {Array} Sliced portion
462
 */
463
function slice(start, end, array);
464

465
/**
466
 * Takes first n elements
467
 * @param {number} n - Number of elements to take
468
 * @param {Array} array - Array to take from
469
 * @returns {Array} First n elements
470
 */
471
function take(n, array);
472

473
/**
474
 * Drops first n elements
475
 * @param {number} n - Number of elements to drop
476
 * @param {Array} array - Array to drop from
477
 * @returns {Array} Array without first n elements
478
 */
479
function drop(n, array);
480

481
/**
482
 * Splits array at index into two arrays
483
 * @param {number} index - Index to split at
484
 * @param {Array} array - Array to split
485
 * @returns {Array} [firstPart, secondPart]
486
 */
487
function splitAt(index, array);
488

489
/**
490
 * Takes elements while predicate is true
491
 * @param {Function} predicate - Function returning boolean
492
 * @param {Array} array - Array to take from
493
 * @returns {Array} Elements taken while predicate true
494
 */
495
function takeWhile(predicate, array);
496

497
/**
498
 * Drops elements while predicate is true
499
 * @param {Function} predicate - Function returning boolean
500
 * @param {Array} array - Array to drop from
501
 * @returns {Array} Remaining elements after dropping
502
 */
503
function dropWhile(predicate, array);
504

505
/**
506
 * Splits into [takeWhile, dropWhile] results
507
 * @param {Function} predicate - Function returning boolean
508
 * @param {Array} array - Array to split
509
 * @returns {Array} [taken, remaining]
510
 */
511
function span(predicate, array);
512

513
/**
514
 * Splits where predicate first becomes true
515
 * @param {Function} predicate - Function returning boolean
516
 * @param {Array} array - Array to break
517
 * @returns {Array} [before, after] break point
518
 */
519
function breakList(predicate, array);
520
```
521

522
### Grouping and Counting
523

524
Functions for grouping and counting elements.
525

526
```javascript { .api }
527
/**
528
 * Counts elements by function result
529
 * @param {Function} fn - Function to group by
530
 * @param {Array} array - Array to count
531
 * @returns {Object} Object mapping keys to counts
532
 */
533
function countBy(fn, array);
534

535
/**
536
 * Groups elements by function result
537
 * @param {Function} fn - Function to group by
538
 * @param {Array} array - Array to group
539
 * @returns {Object} Object mapping keys to arrays of elements
540
 */
541
function groupBy(fn, array);
542
```
543

544
### Zipping
545

546
Functions for combining multiple arrays.
547

548
```javascript { .api }
549
/**
550
 * Zips two arrays into array of pairs
551
 * @param {Array} array1 - First array
552
 * @param {Array} array2 - Second array
553
 * @returns {Array} Array of [elem1, elem2] pairs
554
 */
555
function zip(array1, array2);
556

557
/**
558
 * Zips two arrays using function
559
 * @param {Function} fn - Function to combine elements
560
 * @param {Array} array1 - First array
561
 * @param {Array} array2 - Second array
562
 * @returns {Array} Array of combined elements
563
 */
564
function zipWith(fn, array1, array2);
565

566
/**
567
 * Zips multiple arrays (variadic)
568
 * @param {...Array} arrays - Arrays to zip
569
 * @returns {Array} Array of element arrays
570
 */
571
function zipAll(...arrays);
572

573
/**
574
 * Zips multiple arrays using function (variadic)
575
 * @param {Function} fn - Function to combine elements
576
 * @param {...Array} arrays - Arrays to zip
577
 * @returns {Array} Array of combined elements
578
 */
579
function zipAllWith(fn, ...arrays);
580
```
581

582
### Indexing and Search
583

584
Functions for finding elements and indices.
585

586
```javascript { .api }
587
/**
588
 * Gets element at index (supports negative indices)
589
 * @param {number} index - Index to access (negative for from end)
590
 * @param {Array} array - Array to access
591
 * @returns {*} Element at index or undefined
592
 */
593
function at(index, array);
594

595
/**
596
 * Finds index of element
597
 * @param {*} element - Element to find
598
 * @param {Array} array - Array to search
599
 * @returns {number} Index of element or -1
600
 */
601
function elemIndex(element, array);
602

603
/**
604
 * Finds all indices of element
605
 * @param {*} element - Element to find
606
 * @param {Array} array - Array to search
607
 * @returns {Array<number>} Array of indices
608
 */
609
function elemIndices(element, array);
610

611
/**
612
 * Finds index of first element matching predicate
613
 * @param {Function} predicate - Function returning boolean
614
 * @param {Array} array - Array to search
615
 * @returns {number} Index of first match or -1
616
 */
617
function findIndex(predicate, array);
618

619
/**
620
 * Finds all indices of elements matching predicate
621
 * @param {Function} predicate - Function returning boolean
622
 * @param {Array} array - Array to search
623
 * @returns {Array<number>} Array of matching indices
624
 */
625
function findIndices(predicate, array);
626
```
627

628
## Usage Examples
629

630
**Basic Array Processing:**
631

632
```javascript
633
const { map, filter, fold } = require('prelude-ls');
634

635
const numbers = [1, 2, 3, 4, 5];
636
const doubled = map(x => x * 2, numbers);        // [2, 4, 6, 8, 10]
637
const evens = filter(x => x % 2 === 0, doubled); // [2, 4, 6, 8, 10]
638
const sum = fold((a, b) => a + b, 0, evens);     // 30
639
```
640

641
**Curried Function Composition:**
642

643
```javascript
644
const { map, filter, fold } = require('prelude-ls');
645

646
// Create reusable functions
647
const double = map(x => x * 2);
648
const evens = filter(x => x % 2 === 0);
649
const sum = fold((a, b) => a + b, 0);
650

651
// Compose pipeline
652
const processNumbers = numbers => sum(evens(double(numbers)));
653
const result = processNumbers([1, 2, 3, 4, 5]); // 30
654
```
655

656
**Complex Data Processing:**
657

658
```javascript
659
const { groupBy, map, keys, sortBy } = require('prelude-ls');
660

661
const students = [
662
  { name: 'Alice', grade: 'A', subject: 'Math' },
663
  { name: 'Bob', grade: 'B', subject: 'Math' },
664
  { name: 'Charlie', grade: 'A', subject: 'Science' }
665
];
666

667
const byGrade = groupBy(student => student.grade, students);
668
const gradeStats = map(group => group.length, byGrade);
669
const sortedGrades = sortBy(grade => grade, keys(gradeStats));
670
```