Skip to content

Array API ​

chunk Chunk ​

Splits a readonly array into fixed-size chunks.

Signature ​

ts
export function chunk<Item>(items: readonly Item[], size: number): Item[][];

Example ​

ts
import { chunk } from "@fast-china/utils";

const result = chunk([1, 2, 3], 2);
console.log(result); // [[1, 2], [3]]

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
sizenumberRequiredMaximum items per chunk; must be a positive safe integer.

Returns ​

ValueTypeDescription
resultItem[][]New two-dimensional array; the final chunk may contain fewer than size items.

removeNullishValues Compact ​

Removes null and undefined, preserving false, 0, and empty strings.

Signature ​

ts
export function removeNullishValues<Item>(items: readonly (Item | null | undefined)[]): Item[];

Example ​

ts
import { removeNullishValues } from "@fast-china/utils";

const result = removeNullishValues([1, null, 2, undefined, 3]);
console.log(result); // [1, 2, 3]

Input ​

InputTypeRequired / defaultDescription
itemsreadonly (Item | null | undefined)[]RequiredReadonly array that may contain nullish values.

Returns ​

ValueTypeDescription
resultItem[]New array preserving the original order.

unique Unique ​

Deduplicates with JavaScript Set SameValueZero semantics.

Signature ​

ts
export function unique<Item>(items: readonly Item[]): Item[];

Example ​

ts
import { unique } from "@fast-china/utils";

const result = unique([1, 2, 2, 3]);
console.log(result); // [1, 2, 3]

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.

Returns ​

ValueTypeDescription
resultItem[]New array preserving first occurrence order; sparse holes are skipped.

uniqueBy Unique ​

Deduplicates by selector keys.

Signature ​

ts
export function uniqueBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Item[];

Example ​

ts
import { uniqueBy } from "@fast-china/utils";

const result = uniqueBy([1, 2, 3], (item) => item);

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
selectKeyKeySelector<Item, Key>RequiredFunction receiving an item and index and returning a deduplication key.

Returns ​

ValueTypeDescription
resultItem[]New array retaining the first item for each key; sparse holes are skipped.

groupBy Group ​

Groups items by selector results.

Signature ​

ts
export function groupBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Map<Key, Item[]>;

Example ​

ts
import { groupBy } from "@fast-china/utils";

const result = groupBy([1, 2, 3], (item) => item);

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
selectKeyKeySelector<Item, Key>RequiredFunction returning any valid Map key.

Returns ​

ValueTypeDescription
resultMap<Key, Item[]>A Map ordered by first key occurrence; groups preserve input order and skip sparse holes.

partition Partition ​

Partitions an array into matching and nonmatching items.

Signature ​

ts
export function partition<Item>(items: readonly Item[], predicate: (item: Item, index: number) => boolean): [matched: Item[], unmatched: Item[]];

Example ​

ts
import { partition } from "@fast-china/utils";

const result = partition([1, 2, 3], (item) => item > 1);

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
predicate(item: Item, index: number) => booleanRequiredPredicate receiving an item and index.

Returns ​

ValueTypeDescription
result[matched: Item[], unmatched: Item[]]Tuple of matching and nonmatching arrays; both preserve input order and skip sparse holes.

difference Difference ​

Returns distinct values found only in the left array.

Signature ​

ts
export function difference<Item>(left: readonly Item[], right: readonly Item[]): Item[];

Example ​

ts
import { difference } from "@fast-china/utils";

const result = difference([1, 2, 3], [2, 4]);

Input ​

InputTypeRequired / defaultDescription
leftreadonly Item[]RequiredPrimary input array.
rightreadonly Item[]RequiredValues to exclude.

Returns ​

ValueTypeDescription
resultItem[]Deduplicated result preserving first occurrence order in the left array; holes on both sides are skipped.

intersection Intersection ​

Returns distinct values shared by both arrays.

Signature ​

ts
export function intersection<Item>(left: readonly Item[], right: readonly Item[]): Item[];

Example ​

ts
import { intersection } from "@fast-china/utils";

const result = intersection([1, 2, 3], [2, 4]);

Input ​

InputTypeRequired / defaultDescription
leftreadonly Item[]RequiredArray determining result order.
rightreadonly Item[]RequiredArray used for membership checks.

Returns ​

ValueTypeDescription
resultItem[]Deduplicated result preserving first occurrence order in the left array; holes on both sides are skipped.

symmetricDifference Difference ​

Returns distinct values present in exactly one array.

Signature ​

ts
export function symmetricDifference<Item>(left: readonly Item[], right: readonly Item[]): Item[];

Example ​

ts
import { symmetricDifference } from "@fast-china/utils";

const result = symmetricDifference([1, 2, 3], [2, 4]);

Input ​

InputTypeRequired / defaultDescription
leftreadonly Item[]RequiredArray determining the left-side result order.
rightreadonly Item[]RequiredArray determining the right-side result order.

Returns ​

ValueTypeDescription
resultItem[]Symmetric difference ordered by first occurrence on the left, then the right; uses SameValueZero and skips sparse holes.

hasDuplicatesBy Duplicates ​

Checks for duplicate selector keys.

Signature ​

ts
export function hasDuplicatesBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;

Example ​

ts
import { hasDuplicatesBy } from "@fast-china/utils";

const result = hasDuplicatesBy([1, 2, 3], (item) => item);

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
selectKeyKeySelector<Item, Key>RequiredKey selector; keys are compared using SameValueZero.

Returns ​

ValueTypeDescription
resultbooleantrue if at least one duplicate key exists.

allEqualBy Equality ​

Checks whether every item produces the same selector key.

Signature ​

ts
export function allEqualBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;

Example ​

ts
import { allEqualBy } from "@fast-china/utils";

const result = allEqualBy([1, 2, 3], (item) => item);

Input ​

InputTypeRequired / defaultDescription
itemsreadonly Item[]RequiredReadonly input array; not mutated.
selectKeyKeySelector<Item, Key>RequiredComparison-key selector.

Returns ​

ValueTypeDescription
resultbooleantrue if all keys are equal under SameValueZero.