@rtorcato/js-common / arrays
arrays
Array Utilities
first()
first<
T>(arr):T|undefined
Defined in: arrays/index.ts:15
Returns the first element of an array, or undefined if the array is empty.
Type Parameters
T
T
Parameters
arr
T[]
The array to get the first element from
Returns
T | undefined
The first element or undefined if array is empty
Example
first([1, 2, 3]) // 1
first([]) // undefined
first(['a', 'b']) // 'a'
last()
last<
T>(arr):T|undefined
Defined in: arrays/index.ts:33
Returns the last element of an array, or undefined if the array is empty.
Type Parameters
T
T
Parameters
arr
T[]
The array to get the last element from
Returns
T | undefined
The last element or undefined if array is empty
Example
last([1, 2, 3]) // 3
last([]) // undefined
last(['a', 'b']) // 'b'
unique()
unique<
T>(arr):T[]
Defined in: arrays/index.ts:52
Removes duplicate values from an array while preserving order. Uses Set for O(n) performance with primitive values.
Type Parameters
T
T
Parameters
arr
T[]
The array to remove duplicates from
Returns
T[]
A new array with unique values
Example
unique([1, 2, 2, 3, 1]) // [1, 2, 3]
unique(['a', 'b', 'a']) // ['a', 'b']
unique([{id: 1}, {id: 2}, {id: 1}]) // [{id: 1}, {id: 2}, {id: 1}] (objects by reference)
flatten()
flatten<
T>(arr):T[]
Defined in: arrays/index.ts:70
Flattens an array one level deep.
Type Parameters
T
T
Parameters
arr
readonly (T | T[])[]
The array to flatten
Returns
T[]
A new flattened array
Example
flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
flatten([1, [2, 3], 4]) // [1, 2, 3, 4]
flatten([[1, [2]], [3]]) // [1, [2], 3] (only one level deep)
chunk()
chunk<
T>(arr,size):T[][]
Defined in: arrays/index.ts:91
Chunks an array into smaller arrays of a specified size. The last chunk may be smaller if the array length is not evenly divisible.
Type Parameters
T
T
Parameters
arr
T[]
The array to chunk
size
number
The size of each chunk (must be positive)
Returns
T[][]
An array of chunks
Example
chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
chunk(['a', 'b', 'c'], 2) // [['a', 'b'], ['c']]
chunk([1, 2, 3], 5) // [[1, 2, 3]]
Throws
When size is less than 1
compact()
compact<
T>(arr):T[]
Defined in: arrays/index.ts:115
Removes all falsy values from an array. Falsy values: false, 0, -0, 0n, "", null, undefined, NaN
Type Parameters
T
T
Parameters
arr
T[]
The array to filter
Returns
T[]
A new array with only truthy values
Example
compact([0, 1, false, 2, '', 3, null, undefined, NaN]) // [1, 2, 3]
compact(['', 'hello', 0, 'world']) // ['hello', 'world']
compact([true, false, 1, 0]) // [true, 1]
shuffle()
shuffle<
T>(arr):T[]
Defined in: arrays/index.ts:138
Shuffles an array using the Fisher-Yates algorithm. Returns a new array without modifying the original.
Type Parameters
T
T
Parameters
arr
T[]
The array to shuffle
Returns
T[]
A new shuffled array
Example
shuffle([1, 2, 3, 4, 5]) // [3, 1, 5, 2, 4] (random order)
shuffle(['a', 'b', 'c']) // ['c', 'a', 'b'] (random order)
// Original array is unchanged
const original = [1, 2, 3]
const shuffled = shuffle(original)
console.log(original) // [1, 2, 3]
groupBy()
groupBy<
T>(arr,fn):Record<string|number,T[]>
Defined in: arrays/index.ts:164
Groups array elements by a key derived from each element.
Type Parameters
T
T
Parameters
arr
T[]
The array to group
fn
(item) => string | number
Function that returns the group key for each element
Returns
Record<string | number, T[]>
An object mapping keys to arrays of elements
Example
groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
// { odd: [1, 3], even: [2, 4] }
groupBy([{ type: 'a' }, { type: 'b' }, { type: 'a' }], x => x.type)
// { a: [{ type: 'a' }, { type: 'a' }], b: [{ type: 'b' }] }