0
# Sugar Array Module
1

2
Comprehensive array manipulation methods providing functional programming patterns, statistical operations, and advanced data processing capabilities for JavaScript arrays.
3

4
## Core Imports
5

6
```typescript
7
import Sugar from "sugar";
8
```
9

10
For CommonJS:
11

12
```javascript
13
const Sugar = require("sugar");
14
```
15

16
## Basic Usage
17

18
```typescript
19
import Sugar from "sugar";
20

21
// Array construction
22
const numbers = Sugar.Array.range(1, 10);
23
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
24

25
// Array modification
26
const fruits = ['apple', 'banana', 'cherry'];
27
Sugar.Array.add(fruits, 'date', 1);
28
// ['apple', 'date', 'banana', 'cherry']
29

30
// Statistical operations
31
const scores = [85, 92, 78, 96, 88];
32
const average = Sugar.Array.average(scores);
33
// 87.8
34

35
// Functional operations
36
const users = [
37
  { name: 'Alice', age: 30 },
38
  { name: 'Bob', age: 25 },
39
  { name: 'Charlie', age: 35 }
40
];
41
const grouped = Sugar.Array.groupBy(users, 'age');
42
// { 25: [{ name: 'Bob', age: 25 }], 30: [...], 35: [...] }
43
```
44

45
## Capabilities
46

47
### Array Construction & Creation
48

49
Methods for creating and initializing arrays with various patterns.
50

51
```typescript { .api }
52
/**
53
 * Creates array with mapping function applied to each index
54
 * @param n - Number of elements to create
55
 * @param indexMapFn - Optional function to map each index to a value
56
 * @returns New array with mapped values
57
 */
58
function construct<T>(n: number, indexMapFn?: mapFn<number, T>): T[];
59

60
/**
61
 * Creates array from object, number, or other input
62
 * @param obj - Input to convert to array
63
 * @param clone - Whether to clone the input
64
 * @returns New array created from input
65
 */
66
function create<T>(obj: any, clone?: boolean): T[];
67

68
/**
69
 * Creates array containing range of numbers
70
 * @param start - Starting number (default: 0)
71
 * @param end - Ending number (exclusive)
72
 * @returns Array of numbers in range
73
 */
74
function range(start?: number, end?: number): number[];
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
// Create array with index mapping
81
const squares = Sugar.Array.construct(5, (i) => i * i);
82
// [0, 1, 4, 9, 16]
83

84
// Create array from various inputs
85
const fromString = Sugar.Array.create('hello');
86
// ['h', 'e', 'l', 'l', 'o']
87

88
// Create number ranges
89
const oneToTen = Sugar.Array.range(1, 11);
90
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
91

92
const zeroToFive = Sugar.Array.range(6);
93
// [0, 1, 2, 3, 4, 5]
94
```
95

96
### Array Modification
97

98
Methods for adding, removing, and modifying array contents.
99

100
```typescript { .api }
101
/**
102
 * Adds item to array at specified index
103
 * @param instance - Array to modify
104
 * @param item - Item to add
105
 * @param index - Position to insert (default: end)
106
 * @returns Modified array
107
 */
108
function add<T>(instance: T[], item: T, index?: number): T[];
109

110
/**
111
 * Appends item to array
112
 * @param instance - Array to modify
113
 * @param item - Item to append
114
 * @param index - Position to insert (default: end)
115
 * @returns Modified array
116
 */
117
function append<T>(instance: T[], item: T, index?: number): T[];
118

119
/**
120
 * Inserts item at specific index
121
 * @param instance - Array to modify
122
 * @param item - Item to insert
123
 * @param index - Position to insert (default: 0)
124
 * @returns Modified array
125
 */
126
function insert<T>(instance: T[], item: T, index?: number): T[];
127

128
/**
129
 * Removes all matching elements from array
130
 * @param instance - Array to modify
131
 * @param search - Item or function to match for removal
132
 * @returns Modified array
133
 */
134
function remove<T>(instance: T[], search: any): T[];
135

136
/**
137
 * Removes elements at specified indices
138
 * @param instance - Array to modify
139
 * @param start - Starting index
140
 * @param end - Ending index (optional)
141
 * @returns Modified array
142
 */
143
function removeAt<T>(instance: T[], start: number, end?: number): T[];
144

145
/**
146
 * Excludes matching elements from array
147
 * @param instance - Array to modify
148
 * @param search - Item or function to match for exclusion
149
 * @returns Modified array
150
 */
151
function exclude<T>(instance: T[], search: any): T[];
152

153
/**
154
 * Removes null, undefined, and optionally falsy values
155
 * @param instance - Array to compact
156
 * @param all - If true, removes all falsy values
157
 * @returns Array with null/undefined removed
158
 */
159
function compact<T>(instance: T[], all?: boolean): T[];
160

161
/**
162
 * Flattens nested arrays up to specified depth
163
 * @param instance - Array to flatten
164
 * @param limit - Maximum depth to flatten (default: 1)
165
 * @returns Flattened array
166
 */
167
function flatten<T>(instance: T[], limit?: number): T[];
168

169
/**
170
 * Removes duplicate elements from array
171
 * @param instance - Array to process
172
 * @param map - Optional function to determine uniqueness
173
 * @returns Array with duplicates removed
174
 */
175
function unique<T, U>(instance: T[], map?: mapFn<T, U>): T[];
176

177
/**
178
 * Randomizes array element order
179
 * @param instance - Array to shuffle
180
 * @returns Array with randomized order
181
 */
182
function shuffle<T>(instance: T[]): T[];
183
```
184

185
**Usage Examples:**
186

187
```typescript
188
// Adding and inserting elements
189
const numbers = [1, 2, 3];
190
Sugar.Array.add(numbers, 4); // [1, 2, 3, 4]
191
Sugar.Array.insert(numbers, 0, 0); // [0, 1, 2, 3, 4]
192

193
// Removing elements
194
const colors = ['red', 'blue', 'green', 'blue'];
195
Sugar.Array.remove(colors, 'blue'); // ['red', 'green']
196

197
// Compacting arrays
198
const mixed = [1, null, 2, undefined, 3, '', 4, false];
199
Sugar.Array.compact(mixed); // [1, 2, 3, '', 4, false]
200
Sugar.Array.compact(mixed, true); // [1, 2, 3, 4]
201

202
// Flattening nested arrays
203
const nested = [[1, 2], [3, [4, 5]], 6];
204
Sugar.Array.flatten(nested); // [1, 2, 3, [4, 5], 6]
205
Sugar.Array.flatten(nested, 2); // [1, 2, 3, 4, 5, 6]
206

207
// Removing duplicates
208
const duplicates = [1, 2, 2, 3, 3, 3];
209
Sugar.Array.unique(duplicates); // [1, 2, 3]
210

211
// Unique by property
212
const users = [
213
  { id: 1, name: 'Alice' },
214
  { id: 2, name: 'Bob' },
215
  { id: 1, name: 'Alice Clone' }
216
];
217
Sugar.Array.unique(users, (u) => u.id); // [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
218
```
219

220
### Array Access
221

222
Methods for accessing array elements with advanced indexing and sampling.
223

224
```typescript { .api }
225
/**
226
 * Gets element at index with optional looping
227
 * @param instance - Array to access
228
 * @param index - Index to retrieve (supports negative indices)
229
 * @param loop - Whether to loop around array bounds
230
 * @returns Element at index
231
 */
232
function at<T>(instance: T[], index: number, loop?: boolean): T;
233

234
/**
235
 * Gets first n elements from array
236
 * @param instance - Array to access
237
 * @param num - Number of elements to get (default: 1)
238
 * @returns First n elements
239
 */
240
function first<T>(instance: T[], num?: number): T | T[];
241

242
/**
243
 * Gets last n elements from array
244
 * @param instance - Array to access
245
 * @param num - Number of elements to get (default: 1)
246
 * @returns Last n elements
247
 */
248
function last<T>(instance: T[], num?: number): T | T[];
249

250
/**
251
 * Gets slice from specified index to end
252
 * @param instance - Array to slice
253
 * @param index - Starting index
254
 * @returns Slice from index to end
255
 */
256
function from<T>(instance: T[], index: number): T[];
257

258
/**
259
 * Gets slice from beginning to specified index
260
 * @param instance - Array to slice
261
 * @param index - Ending index (exclusive)
262
 * @returns Slice from beginning to index
263
 */
264
function to<T>(instance: T[], index: number): T[];
265

266
/**
267
 * Gets random sample of elements from array
268
 * @param instance - Array to sample from
269
 * @param num - Number of elements to sample (default: 1)
270
 * @param remove - Whether to remove sampled elements
271
 * @returns Random sample of elements
272
 */
273
function sample<T>(instance: T[], num?: number, remove?: boolean): T | T[];
274
```
275

276
**Usage Examples:**
277

278
```typescript
279
const letters = ['a', 'b', 'c', 'd', 'e'];
280

281
// Accessing with indices
282
Sugar.Array.at(letters, 0); // 'a'
283
Sugar.Array.at(letters, -1); // 'e'
284
Sugar.Array.at(letters, 10, true); // 'a' (loops around)
285

286
// Getting first/last elements
287
Sugar.Array.first(letters); // 'a'
288
Sugar.Array.first(letters, 3); // ['a', 'b', 'c']
289
Sugar.Array.last(letters, 2); // ['d', 'e']
290

291
// Slicing operations
292
Sugar.Array.from(letters, 2); // ['c', 'd', 'e']
293
Sugar.Array.to(letters, 3); // ['a', 'b', 'c']
294

295
// Random sampling
296
Sugar.Array.sample(letters); // Random single letter
297
Sugar.Array.sample(letters, 3); // Array of 3 random letters
298
```
299

300
### Array Search & Filter
301

302
Methods for finding and filtering array elements.
303

304
```typescript { .api }
305
/**
306
 * Finds first element matching search criteria
307
 * @param instance - Array to search
308
 * @param search - Search criteria (value, function, or object)
309
 * @param context - Optional context for function execution
310
 * @returns First matching element or undefined
311
 */
312
function find<T>(instance: T[], search: any, context?: any): T | undefined;
313

314
/**
315
 * Finds index of first element matching search criteria
316
 * @param instance - Array to search
317
 * @param search - Search criteria (value, function, or object)
318
 * @param context - Optional context for function execution
319
 * @returns Index of first match or -1 if not found
320
 */
321
function findIndex<T>(instance: T[], search: any, context?: any): number;
322

323
/**
324
 * Filters elements matching search criteria
325
 * @param instance - Array to filter
326
 * @param search - Filter criteria (value, function, or object)
327
 * @param context - Optional context for function execution
328
 * @returns Array of matching elements
329
 */
330
function filter<T>(instance: T[], search: any, context?: any): T[];
331

332
/**
333
 * Counts elements matching search criteria
334
 * @param instance - Array to count in
335
 * @param search - Count criteria (value, function, or object)
336
 * @param context - Optional context for function execution
337
 * @returns Number of matching elements
338
 */
339
function count<T>(instance: T[], search: any, context?: any): number;
340
```
341

342
**Usage Examples:**
343

344
```typescript
345
const products = [
346
  { name: 'Laptop', price: 999, category: 'electronics' },
347
  { name: 'Book', price: 29, category: 'books' },
348
  { name: 'Phone', price: 699, category: 'electronics' }
349
];
350

351
// Finding elements
352
const laptop = Sugar.Array.find(products, { name: 'Laptop' });
353
const expensiveIndex = Sugar.Array.findIndex(products, (p) => p.price > 500);
354

355
// Filtering elements
356
const electronics = Sugar.Array.filter(products, { category: 'electronics' });
357
const affordable = Sugar.Array.filter(products, (p) => p.price < 100);
358

359
// Counting matches
360
const electronicsCount = Sugar.Array.count(products, { category: 'electronics' }); // 2
361
const expensiveCount = Sugar.Array.count(products, (p) => p.price > 500); // 2
362
```
363

364
### Array Test
365

366
Methods for testing array contents and conditions.
367

368
```typescript { .api }
369
/**
370
 * Tests if all elements match criteria
371
 * @param instance - Array to test
372
 * @param search - Test criteria (value, function, or object)
373
 * @param context - Optional context for function execution
374
 * @returns True if all elements match
375
 */
376
function every<T>(instance: T[], search: any, context?: any): boolean;
377

378
/**
379
 * Tests if some elements match criteria
380
 * @param instance - Array to test
381
 * @param search - Test criteria (value, function, or object)
382
 * @param context - Optional context for function execution
383
 * @returns True if at least one element matches
384
 */
385
function some<T>(instance: T[], search: any, context?: any): boolean;
386

387
/**
388
 * Tests if no elements match criteria
389
 * @param instance - Array to test
390
 * @param search - Test criteria (value, function, or object)
391
 * @param context - Optional context for function execution
392
 * @returns True if no elements match
393
 */
394
function none<T>(instance: T[], search: any, context?: any): boolean;
395

396
/**
397
 * Tests if array is empty
398
 * @param instance - Array to test
399
 * @returns True if array has no elements
400
 */
401
function isEmpty<T>(instance: T[]): boolean;
402

403
/**
404
 * Tests equality with another array
405
 * @param instance - First array
406
 * @param arr - Second array to compare
407
 * @returns True if arrays are deeply equal
408
 */
409
function isEqual<T>(instance: T[], arr: T[]): boolean;
410
```
411

412
**Usage Examples:**
413

414
```typescript
415
const numbers = [2, 4, 6, 8, 10];
416
const mixed = [1, 2, 3, 4, 5];
417

418
// Testing all elements
419
Sugar.Array.every(numbers, (n) => n % 2 === 0); // true (all even)
420
Sugar.Array.every(mixed, (n) => n > 0); // true (all positive)
421

422
// Testing some elements
423
Sugar.Array.some(mixed, (n) => n > 4); // true (5 is > 4)
424
Sugar.Array.some(numbers, (n) => n > 10); // false
425

426
// Testing no elements
427
Sugar.Array.none(numbers, (n) => n % 2 === 1); // true (no odd numbers)
428
Sugar.Array.none(mixed, (n) => n < 0); // true (no negatives)
429

430
// Testing emptiness and equality
431
Sugar.Array.isEmpty([]); // true
432
Sugar.Array.isEmpty([1]); // false
433
Sugar.Array.isEqual([1, 2, 3], [1, 2, 3]); // true
434
Sugar.Array.isEqual([1, 2, 3], [1, 2, 4]); // false
435
```
436

437
### Array Set Operations
438

439
Methods for performing mathematical set operations on arrays.
440

441
```typescript { .api }
442
/**
443
 * Returns intersection of two arrays
444
 * @param instance - First array
445
 * @param arr - Second array
446
 * @returns Array containing elements present in both arrays
447
 */
448
function intersect<T>(instance: T[], arr: T[]): T[];
449

450
/**
451
 * Removes items from array
452
 * @param instance - Array to subtract from
453
 * @param item - Item or array of items to remove
454
 * @returns Array with specified items removed
455
 */
456
function subtract<T>(instance: T[], item: T | T[]): T[];
457

458
/**
459
 * Returns union of two arrays
460
 * @param instance - First array
461
 * @param arr - Second array
462
 * @returns Array containing all unique elements from both arrays
463
 */
464
function union<T>(instance: T[], arr: T[]): T[];
465
```
466

467
**Usage Examples:**
468

469
```typescript
470
const set1 = [1, 2, 3, 4, 5];
471
const set2 = [3, 4, 5, 6, 7];
472

473
// Intersection (common elements)
474
const common = Sugar.Array.intersect(set1, set2); // [3, 4, 5]
475

476
// Subtraction (remove elements)
477
const remaining = Sugar.Array.subtract(set1, [2, 4]); // [1, 3, 5]
478

479
// Union (all unique elements)
480
const combined = Sugar.Array.union(set1, set2); // [1, 2, 3, 4, 5, 6, 7]
481

482
// String arrays
483
const fruits1 = ['apple', 'banana', 'cherry'];
484
const fruits2 = ['banana', 'cherry', 'date'];
485
Sugar.Array.intersect(fruits1, fruits2); // ['banana', 'cherry']
486
```
487

488
### Array Grouping & Organization
489

490
Methods for grouping, sorting, and organizing array elements.
491

492
```typescript { .api }
493
/**
494
 * Groups elements by specified criteria
495
 * @param instance - Array to group
496
 * @param map - Grouping function or property name
497
 * @param groupFn - Optional function for processing groups
498
 * @returns Object with grouped elements
499
 */
500
function groupBy<T, U>(instance: T[], map?: mapFn<T, U>, groupFn?: Function): { [key: string]: T[] };
501

502
/**
503
 * Splits array into specified number of groups
504
 * @param instance - Array to split
505
 * @param num - Number of groups to create
506
 * @param padding - Value to pad incomplete groups
507
 * @returns Array of group arrays
508
 */
509
function inGroups<T>(instance: T[], num: number, padding?: T): T[][];
510

511
/**
512
 * Groups array into chunks of specified size
513
 * @param instance - Array to chunk
514
 * @param num - Size of each chunk
515
 * @param padding - Value to pad incomplete chunks
516
 * @returns Array of chunk arrays
517
 */
518
function inGroupsOf<T>(instance: T[], num: number, padding?: T): T[][];
519

520
/**
521
 * Sorts array by specified criteria
522
 * @param instance - Array to sort
523
 * @param map - Sorting function or property name
524
 * @param desc - Whether to sort in descending order
525
 * @returns Sorted array
526
 */
527
function sortBy<T, U>(instance: T[], map?: mapFn<T, U>, desc?: boolean): T[];
528

529
/**
530
 * Zips array with other arrays
531
 * @param instance - First array
532
 * @param args - Additional arrays to zip with
533
 * @returns Array of tuples containing elements from each position
534
 */
535
function zip<T>(instance: T[], ...args: T[][]): T[][];
536
```
537

538
**Usage Examples:**
539

540
```typescript
541
const students = [
542
  { name: 'Alice', grade: 'A', class: 'Math' },
543
  { name: 'Bob', grade: 'B', class: 'Math' },
544
  { name: 'Charlie', grade: 'A', class: 'Science' },
545
  { name: 'David', grade: 'C', class: 'Science' }
546
];
547

548
// Grouping by property
549
const byGrade = Sugar.Array.groupBy(students, 'grade');
550
// { A: [Alice, Charlie], B: [Bob], C: [David] }
551

552
const byClass = Sugar.Array.groupBy(students, (s) => s.class);
553
// { Math: [Alice, Bob], Science: [Charlie, David] }
554

555
// Splitting into groups
556
const numbers = [1, 2, 3, 4, 5, 6, 7, 8];
557
const groups = Sugar.Array.inGroups(numbers, 3);
558
// [[1, 2, 3], [4, 5, 6], [7, 8]]
559

560
const chunks = Sugar.Array.inGroupsOf(numbers, 3);
561
// [[1, 2, 3], [4, 5, 6], [7, 8]]
562

563
// Sorting
564
const sorted = Sugar.Array.sortBy(students, 'name');
565
// Sorted alphabetically by name
566

567
const gradeSort = Sugar.Array.sortBy(students, 'grade', true);
568
// Sorted by grade descending (C, B, A)
569

570
// Zipping arrays
571
const names = ['Alice', 'Bob', 'Charlie'];
572
const ages = [25, 30, 35];
573
const cities = ['NYC', 'LA', 'Chicago'];
574
const zipped = Sugar.Array.zip(names, ages, cities);
575
// [['Alice', 25, 'NYC'], ['Bob', 30, 'LA'], ['Charlie', 35, 'Chicago']]
576
```
577

578
### Array Statistical
579

580
Methods for calculating statistical values from array elements.
581

582
```typescript { .api }
583
/**
584
 * Calculates average of array elements
585
 * @param instance - Array to process
586
 * @param map - Optional function to extract numeric values
587
 * @returns Average value
588
 */
589
function average<T, U>(instance: T[], map?: mapFn<T, U>): number;
590

591
/**
592
 * Calculates sum of array elements
593
 * @param instance - Array to process
594
 * @param map - Optional function to extract numeric values
595
 * @returns Sum of values
596
 */
597
function sum<T, U>(instance: T[], map?: mapFn<T, U>): number;
598

599
/**
600
 * Finds minimum elements in array
601
 * @param instance - Array to process
602
 * @param all - Whether to return all minimum elements or just one
603
 * @param map - Optional function to extract comparable values
604
 * @returns Minimum element(s)
605
 */
606
function min<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
607

608
/**
609
 * Finds maximum elements in array
610
 * @param instance - Array to process
611
 * @param all - Whether to return all maximum elements or just one
612
 * @param map - Optional function to extract comparable values
613
 * @returns Maximum element(s)
614
 */
615
function max<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
616

617
/**
618
 * Finds minimum elements in array (alias for min)
619
 * @param instance - Array to process
620
 * @param all - Whether to return all minimum elements or just one
621
 * @param map - Optional function to extract comparable values
622
 * @returns Minimum element(s)
623
 */
624
function least<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
625

626
/**
627
 * Finds maximum elements in array (alias for max)
628
 * @param instance - Array to process
629
 * @param all - Whether to return all maximum elements or just one
630
 * @param map - Optional function to extract comparable values
631
 * @returns Maximum element(s)
632
 */
633
function most<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
634

635
/**
636
 * Calculates median of array elements
637
 * @param instance - Array to process
638
 * @param map - Optional function to extract numeric values
639
 * @returns Median value
640
 */
641
function median<T, U>(instance: T[], map?: mapFn<T, U>): number;
642
```
643

644
**Usage Examples:**
645

646
```typescript
647
// Basic statistical operations
648
const scores = [85, 92, 78, 96, 88, 90];
649

650
Sugar.Array.average(scores); // 88.17
651
Sugar.Array.sum(scores); // 529
652
Sugar.Array.min(scores); // 78
653
Sugar.Array.max(scores); // 96
654
Sugar.Array.median(scores); // 89
655

656
// With object arrays and mapping functions
657
const products = [
658
  { name: 'Laptop', price: 999 },
659
  { name: 'Book', price: 29 },
660
  { name: 'Phone', price: 699 },
661
  { name: 'Tablet', price: 299 }
662
];
663

664
Sugar.Array.average(products, (p) => p.price); // 506.5
665
Sugar.Array.sum(products, 'price'); // 2026
666
Sugar.Array.min(products, false, 'price'); // { name: 'Book', price: 29 }
667
Sugar.Array.max(products, false, (p) => p.price); // { name: 'Laptop', price: 999 }
668

669
// Finding all min/max elements
670
const grades = [85, 92, 85, 96, 92];
671
Sugar.Array.min(grades, true); // [85, 85] (all minimum values)
672
Sugar.Array.max(grades, true); // [96] (all maximum values)
673

674
// Complex mapping
675
const teams = [
676
  { name: 'Alpha', members: 5 },
677
  { name: 'Beta', members: 3 },
678
  { name: 'Gamma', members: 8 },
679
  { name: 'Delta', members: 3 }
680
];
681

682
Sugar.Array.least(teams, true, 'members'); 
683
// [{ name: 'Beta', members: 3 }, { name: 'Delta', members: 3 }]
684
```
685

686
### Array Transformation
687

688
Methods for transforming and cloning arrays.
689

690
```typescript { .api }
691
/**
692
 * Maps elements using transformation function
693
 * @param instance - Array to transform
694
 * @param map - Transformation function
695
 * @param context - Optional context for function execution
696
 * @returns New array with transformed elements
697
 */
698
function map<T, U>(instance: T[], map: mapFn<T, U>, context?: any): U[];
699

700
/**
701
 * Creates deep clone of array and its elements
702
 * @param instance - Array to clone
703
 * @returns Deep clone of array
704
 */
705
function clone<T>(instance: T[]): T[];
706
```
707

708
**Usage Examples:**
709

710
```typescript
711
// Basic mapping
712
const numbers = [1, 2, 3, 4, 5];
713
const doubled = Sugar.Array.map(numbers, (n) => n * 2);
714
// [2, 4, 6, 8, 10]
715

716
// Complex object mapping
717
const users = [
718
  { firstName: 'John', lastName: 'Doe', age: 30 },
719
  { firstName: 'Jane', lastName: 'Smith', age: 25 }
720
];
721

722
const fullNames = Sugar.Array.map(users, (user) => `${user.firstName} ${user.lastName}`);
723
// ['John Doe', 'Jane Smith']
724

725
const adults = Sugar.Array.map(users, (user) => ({
726
  name: `${user.firstName} ${user.lastName}`,
727
  isAdult: user.age >= 18
728
}));
729

730
// Deep cloning
731
const original = [
732
  { id: 1, tags: ['a', 'b'] },
733
  { id: 2, tags: ['c', 'd'] }
734
];
735

736
const cloned = Sugar.Array.clone(original);
737
cloned[0].tags.push('e'); // Doesn't affect original
738
```
739

740
## Types
741

742
```typescript { .api }
743
/**
744
 * Mapping function type for transforming array elements
745
 */
746
type mapFn<T, U> = (item: T, index: number, array: T[]) => U;
747

748
/**
749
 * Sugar Array namespace containing all array methods
750
 */
751
declare namespace Array {
752
  // Construction & Creation
753
  function construct<T>(n: number, indexMapFn?: mapFn<number, T>): T[];
754
  function create<T>(obj: any, clone?: boolean): T[];
755
  function range(start?: number, end?: number): number[];
756

757
  // Modification
758
  function add<T>(instance: T[], item: T, index?: number): T[];
759
  function append<T>(instance: T[], item: T, index?: number): T[];
760
  function insert<T>(instance: T[], item: T, index?: number): T[];
761
  function remove<T>(instance: T[], search: any): T[];
762
  function removeAt<T>(instance: T[], start: number, end?: number): T[];
763
  function exclude<T>(instance: T[], search: any): T[];
764
  function compact<T>(instance: T[], all?: boolean): T[];
765
  function flatten<T>(instance: T[], limit?: number): T[];
766
  function unique<T, U>(instance: T[], map?: mapFn<T, U>): T[];
767
  function shuffle<T>(instance: T[]): T[];
768

769
  // Access
770
  function at<T>(instance: T[], index: number, loop?: boolean): T;
771
  function first<T>(instance: T[], num?: number): T | T[];
772
  function last<T>(instance: T[], num?: number): T | T[];
773
  function from<T>(instance: T[], index: number): T[];
774
  function to<T>(instance: T[], index: number): T[];
775
  function sample<T>(instance: T[], num?: number, remove?: boolean): T | T[];
776

777
  // Search & Filter
778
  function find<T>(instance: T[], search: any, context?: any): T | undefined;
779
  function findIndex<T>(instance: T[], search: any, context?: any): number;
780
  function filter<T>(instance: T[], search: any, context?: any): T[];
781
  function count<T>(instance: T[], search: any, context?: any): number;
782

783
  // Test
784
  function every<T>(instance: T[], search: any, context?: any): boolean;
785
  function some<T>(instance: T[], search: any, context?: any): boolean;
786
  function none<T>(instance: T[], search: any, context?: any): boolean;
787
  function isEmpty<T>(instance: T[]): boolean;
788
  function isEqual<T>(instance: T[], arr: T[]): boolean;
789

790
  // Set Operations
791
  function intersect<T>(instance: T[], arr: T[]): T[];
792
  function subtract<T>(instance: T[], item: T | T[]): T[];
793
  function union<T>(instance: T[], arr: T[]): T[];
794

795
  // Grouping & Organization
796
  function groupBy<T, U>(instance: T[], map?: mapFn<T, U>, groupFn?: Function): { [key: string]: T[] };
797
  function inGroups<T>(instance: T[], num: number, padding?: T): T[][];
798
  function inGroupsOf<T>(instance: T[], num: number, padding?: T): T[][];
799
  function sortBy<T, U>(instance: T[], map?: mapFn<T, U>, desc?: boolean): T[];
800
  function zip<T>(instance: T[], ...args: T[][]): T[][];
801

802
  // Statistical
803
  function average<T, U>(instance: T[], map?: mapFn<T, U>): number;
804
  function sum<T, U>(instance: T[], map?: mapFn<T, U>): number;
805
  function min<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
806
  function max<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
807
  function least<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
808
  function most<T, U>(instance: T[], all?: boolean, map?: mapFn<T, U>): T | T[];
809
  function median<T, U>(instance: T[], map?: mapFn<T, U>): number;
810

811
  // Transformation
812
  function map<T, U>(instance: T[], map: mapFn<T, U>, context?: any): U[];
813
  function clone<T>(instance: T[]): T[];
814
}
815
```