# collection — Array Utilities

> `import { batch, uniq, sortBy, seed, headTail, levelUp, flatten, flattenUniq } from 'puffy-core/collection'`
> CJS: `const { collection: { batch, uniq, sortBy, seed, headTail, levelUp, flatten, flattenUniq } } = require('puffy-core')`
> Also available in snake_case: `head_tail`, `level_up`, `sort_by`, `flatten_uniq`

---

## batch

Splits an array into chunks of a specified size.

### Signature

```
batch(array: Array, batchSize: number = 1) → Array<Array>
```

### Examples

```js
batch([1,2,3,4,5,6,7,8,9,10], 3)
// [[1,2,3], [4,5,6], [7,8,9], [10]]
// Last batch may be smaller than batchSize

batch([1,2,3], 1)
// [[1], [2], [3]]

batch([1,2,3], 5)
// [[1,2,3]]
// Single batch when batchSize > array length
```

---

## uniq

Removes duplicate items from an array.

### Signature

```
uniq(array: Array, identityFn?: (item) => any) → Array
```

Parameters:
- `array`: Input array
- `identityFn` (optional): Function that returns a key for comparison. Without it, items are compared by value (using Set).

### Examples

```js
// Primitives — direct comparison
uniq([1,1,1,1,2,2])  // [1, 2]
uniq(['a','b','a'])   // ['a', 'b']

// Objects — use identity function to compare by a property
uniq(
	[{ name:'Ben' }, { name:'Ben' }, { name:'Jerry' }],
	x => x.name
)
// [{ name:'Ben' }, { name:'Jerry' }]
```

GOTCHA: Without an identity function, deduplication uses Set, which compares by reference for objects. Two objects with identical properties are NOT considered equal:

```js
uniq([{ a:1 }, { a:1 }])          // [{ a:1 }, { a:1 }] — NOT deduped
uniq([{ a:1 }, { a:1 }], x => x.a)  // [{ a:1 }] — deduped by identity fn
```

---

## sortBy

Sorts arrays (or objects) with optional mapper and direction.

### Signature

```
sortBy(collection: Array|Object, mapperOrDirection?, direction?: 'asc'|'desc') → Array|Object
```

Call patterns:
- `sortBy(arr)` — sort ascending by value
- `sortBy(arr, 'desc')` — sort descending by value
- `sortBy(arr, fn)` — sort ascending by mapped value
- `sortBy(arr, fn, 'desc')` — sort descending by mapped value

### Examples

```js
// Simple sort
sortBy([2,1,4,3])           // [1,2,3,4]
sortBy([2,1,4,3], 'desc')   // [4,3,2,1]

// Sort objects by a property
const people = [
	{ name:'Nic', age:40 },
	{ name:'Paul', age:50 },
	{ name:'Lin', age:30 }
]
sortBy(people, x => x.age)
// [{ name:'Lin', age:30 }, { name:'Nic', age:40 }, { name:'Paul', age:50 }]

sortBy(people, x => x.age, 'desc')
// [{ name:'Paul', age:50 }, { name:'Nic', age:40 }, { name:'Lin', age:30 }]
```

---

## seed

Creates an array of a specified length filled with `undefined`.

### Signature

```
seed(size: number = 0) → Array<undefined>
```

### Example

```js
seed(3)  // [undefined, undefined, undefined]
seed(0)  // []
```

---

## headTail

Splits an array into a head (first N items) and tail (remaining items).

### Signature

```
headTail(array: Array, headSize: number = 1) → [Array, Array]
```

Returns: A 2-element array `[head, tail]`.

### Examples

```js
headTail([1,2,3,4,5,6,7,8], 3)
// [[1,2,3], [4,5,6,7,8]]

headTail([1,2,3], 1)
// [[1], [2,3]]

headTail([1,2,3], 10)
// [[1,2,3], []]
```

---

## levelUp

Pads all input arrays to the length of the longest one using `undefined`.

### Signature

```
levelUp(...arrays: Array[]) → Array<Array>
```

### Example

```js
levelUp([1], [2,2], [3,3,3])
// [[1,undefined,undefined], [2,2,undefined], [3,3,3]]
```

---

## flatten

Recursively flattens nested arrays into a single flat array.

### Signature

```
flatten(...args: any[]) → Array
```

### Example

```js
flatten(1, [1,2,3], [4,5,[6,7]], 8, 9, [6])
// [1, 1, 2, 3, 4, 5, 6, 7, 8, 9, 6]
// Note: duplicates are preserved
```

---

## flattenUniq

Recursively flattens and removes duplicates.

### Signature

```
flattenUniq(...args: any[]) → Array
```

### Example

```js
flattenUniq(1, [1,2,3], [4,5,[6,7]], 8, 9, [6])
// [1, 2, 3, 4, 5, 6, 7, 8, 9]
```

GOTCHA: Deduplication uses Set, so it only works reliably for primitives (numbers, strings, booleans). Object references are compared by identity, not by value:

```js
flattenUniq([{ a:1 }], [{ a:1 }])
// [{ a:1 }, { a:1 }] — NOT deduped (different object references)
```

Use `uniq()` with an identity function if you need value-based deduplication for objects.