Arrays

Lightweight, tree-shakable array helpers. Every function imports from the package root — import { unique } from "@mongez/reinforcements". For richer collection operations (partition, keyBy, sortBy, intersection, …) reach for @mongez/collection.

chunk()

Split an array (or string) into groups of size. The final group holds whatever is left over.

chunk<T>(array: T[] | string, size: number): T[][]

chunk([1, 2, 3, 4, 5], 2);  // [[1, 2], [3, 4], [5]]
chunk("abcdef", 2);         // [["a", "b"], ["c", "d"], ["e", "f"]]

range()

Build an inclusive array of numbers from min to max.

range(min: number, max: number): number[]

range(1, 5);   // [1, 2, 3, 4, 5]
range(0, 0);   // [0]

unique()

Remove duplicate values. Pass a key to dedupe an array of objects by a property — the result is the plucked unique values for that key.

unique<T>(array: T[], key?: string): T[]

unique([1, 1, 2, 3, 3]);                          // [1, 2, 3]
unique([{ id: 1 }, { id: 1 }, { id: 2 }], "id");  // [1, 2]

pluck()

Project a single property (or a subset of properties) out of an array of objects. Dot-notation paths work for nested values.

pluck(array: any[], key?: string | string[]): any[]

pluck([{ name: "Ada" }, { name: "Bob" }], "name"); // ["Ada", "Bob"]
pluck([{ a: 1, b: 2 }, { a: 3, b: 4 }], ["a"]);    // [{ a: 1 }, { a: 3 }]
pluck(users, "address.city");                       // nested path

groupBy()

Group an array of objects by one or more keys. Each group is an object with the key value(s) plus a data array of its members — rename data via the third argument.

groupBy(array: object[], key: string | string[], listAs?: string): object[]

groupBy(students, "class");             // [{ class: "A", data: [...] }, ...]
groupBy(students, ["class", "grade"]);  // multi-key grouping
groupBy(students, "class", "items");    // rename "data" → "items"

countBy()

Tally how many items fall under each value of key. Returns a value → count map.

countBy(array: any[], key: string): Record<string, number>

countBy([{ type: "a" }, { type: "b" }, { type: "a" }], "type");
// { a: 2, b: 1 }

count()

Count items matching a condition — either items with a defined value at a dot-notation path, or items passing a predicate.

count(array: any[], key: string | ((item) => boolean)): number

count(items, "name");               // items that have a defined "name"
count(items, item => item.active);  // items passing the predicate

sum()

Add up the numbers in an array. Pass a dot-notation key to sum a property across an array of objects.

sum(array: any[], key?: string): number

sum([1, 2, 3]);             // 6
sum(orders, "total.price"); // sum of total.price across orders

average() / avg()

Arithmetic mean of the values (or of a keyed property). avg is a shorthand alias.

average(array: any[], key?: string): number   // alias: avg

average([2, 4, 6]); // 4
avg(users, "age");  // mean age

Average of an empty array is NaN — guard before displaying.

median()

The middle value once sorted (mean of the two middle values for even-length arrays).

median(array: any[], key?: string): number

median([1, 2, 3, 4]); // 2.5
median([3, 1, 2]);    // 2

min() / max()

Smallest / largest value, optionally by a dot-notation key.

min(array: any[], key?: string): number
max(array: any[], key?: string): number

min([5, 2, 9]);   // 2
max(users, "age"); // largest age

min / max of an empty array return 0.

even() / odd()

Filter to elements whose value is even / odd. With a key, tests that property instead.

even(array: any[], key?: string): any[]
odd(array: any[], key?: string): any[]

even([1, 2, 3, 4]);  // [2, 4]
odd([1, 2, 3, 4]);   // [1, 3]
even(items, "age");  // items whose age is even

evenIndexes() / oddIndexes()

Filter by position rather than value — elements sitting at even / odd indices.

evenIndexes<T>(array: T[]): T[]   // indices 0, 2, 4, …
oddIndexes<T>(array: T[]): T[]    // indices 1, 3, 5, …

evenIndexes(["a", "b", "c", "d"]); // ["a", "c"]
oddIndexes(["a", "b", "c", "d"]);  // ["b", "d"]

pushUnique() / unshiftUnique()

Append / prepend items only when they aren’t already present.

pushUnique<T>(array: T[], ...items: T[]): T[]
unshiftUnique<T>(array: T[], ...items: T[]): T[]

const arr = [1, 2];
pushUnique(arr, 2, 3);    // [1, 2, 3]    — 2 was skipped
unshiftUnique(arr, 0, 1); // [0, 1, 2, 3] — 1 was skipped

These mutate the input array (and return the same reference). Reach for them when you have a stable array you want to grow without duplicates. For a non-mutating dedupe, use unique().