Array API

chunk Chunk

Splits a readonly array into fixed-size chunks.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
size	number	Required	Maximum items per chunk; must be a positive safe integer.

Returns

Value	Type	Description
result	Item[][]	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

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly (Item | null | undefined)[]	Required	Readonly array that may contain nullish values.

Returns

Value	Type	Description
result	Item[]	New array preserving the original order.

unique Unique

Deduplicates with JavaScript Set SameValueZero semantics.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.

Returns

Value	Type	Description
result	Item[]	New array preserving first occurrence order; sparse holes are skipped.

uniqueBy Unique

Deduplicates by selector keys.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
selectKey	KeySelector<Item, Key>	Required	Function receiving an item and index and returning a deduplication key.

Returns

Value	Type	Description
result	Item[]	New array retaining the first item for each key; sparse holes are skipped.

groupBy Group

Groups items by selector results.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
selectKey	KeySelector<Item, Key>	Required	Function returning any valid Map key.

Returns

Value	Type	Description
result	Map<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

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
predicate	(item: Item, index: number) => boolean	Required	Predicate receiving an item and index.

Returns

Value	Type	Description
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

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

Example

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

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

Input

Input	Type	Required / default	Description
left	readonly Item[]	Required	Primary input array.
right	readonly Item[]	Required	Values to exclude.

Returns

Value	Type	Description
result	Item[]	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

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

Example

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

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

Input

Input	Type	Required / default	Description
left	readonly Item[]	Required	Array determining result order.
right	readonly Item[]	Required	Array used for membership checks.

Returns

Value	Type	Description
result	Item[]	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

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

Example

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

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

Input

Input	Type	Required / default	Description
left	readonly Item[]	Required	Array determining the left-side result order.
right	readonly Item[]	Required	Array determining the right-side result order.

Returns

Value	Type	Description
result	Item[]	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

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
selectKey	KeySelector<Item, Key>	Required	Key selector; keys are compared using SameValueZero.

Returns

Value	Type	Description
result	boolean	true if at least one duplicate key exists.

allEqualBy Equality

Checks whether every item produces the same selector key.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
selectKey	KeySelector<Item, Key>	Required	Comparison-key selector.

Returns

Value	Type	Description
result	boolean	true if all keys are equal under SameValueZero.