Skip to content

ArrayService

katanakit-js / ArrayService

Defined in: core/services/array.service.ts:29

ArrayService — singleton facade for collection helpers.

const arrays = ArrayService.getInstance();
arrays.useFilter(products, (product) => product.inStock);
useEvery<T>(array, predicate): boolean;

Defined in: core/services/array.service.ts:139

Returns true when every item satisfies predicate. Nullish input is false, because “every item passed” must not be vacuously true for a collection that does not exist.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

boolean

Whether all items match.


useEveryAsync<T>(array, predicate): Promise<boolean>;

Defined in: core/services/array.service.ts:411

Returns true when every async predicate resolves truthy. Short circuits on the first failure.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index) => Promise<boolean> Async test per item.

Promise<boolean>

A promise of whether all items match.


useFilter<T>(array, predicate): T[];

Defined in: core/services/array.service.ts:58

Keeps the items that satisfy predicate. Returns [] for nullish input.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

T[]

A new array of matching items.

useFilter(products, (product) => product.inStock);
useFilter(undefined, () => true); // []

useFilterAsync<T>(array, predicate): Promise<T[]>;

Defined in: core/services/array.service.ts:338

Keeps the items whose async predicate resolves truthy. Every predicate runs in parallel and the input order is preserved.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index) => Promise<boolean> Async test per item.

Promise<T[]>

A promise of the matching items.


useFind<T>(array, predicate): T | undefined;

Defined in: core/services/array.service.ts:72

Returns the first item satisfying predicate, or undefined.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

T | undefined

The first match, or undefined.


useFindAsync<T>(array, predicate): Promise<T | undefined>;

Defined in: core/services/array.service.ts:373

Returns the first item whose async predicate resolves truthy. Short circuits: later predicates are never invoked.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index) => Promise<boolean> Async test per item.

Promise<T | undefined>

A promise of the first match, or undefined.


useFindIndex<T>(array, predicate): number;

Defined in: core/services/array.service.ts:108

Returns the index of the first match, or -1.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

number

The index of the first match, or -1.


useFindLast<T>(array, predicate): T | undefined;

Defined in: core/services/array.service.ts:90

Returns the last item satisfying predicate, or undefined.

Implemented with an explicit reverse scan rather than Array.prototype.findLast, so it typechecks under the project’s ES2022 lib and keeps working on any runtime.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

T | undefined

The last match, or undefined.


useFlatMap<T, U>(array, transform): U[];

Defined in: core/services/array.service.ts:207

Maps each item to a collection and flattens one level. Returns [] for nullish input.

Type Parameter Description
T Source element type.
U Flattened element type.
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
transform (item, index, array) => readonly U[] Returns an iterable of U per item.

U[]

A new flattened array.


useFromEntries<K, V>(entries): Record<K, V>;

Defined in: core/services/array.service.ts:320

Typed Object.fromEntries. Returns {} for nullish input.

Type Parameter Description
K extends PropertyKey Key type.
V Value type.
Parameter Type Description
entries readonly (readonly [K, V])[] | null | undefined Entry pairs, possibly nullish.

Record<K, V>

A new record.

useFromEntries(products.map((p) => [p.id, p.name] as const));

useKeys<T>(object): (keyof T)[];

Defined in: core/services/array.service.ts:292

Typed Object.keys. The native call returns string[], losing the key union of the object it was given.

Type Parameter Description
T extends object Object type.
Parameter Type Description
object T | null | undefined Source object, possibly nullish.

(keyof T)[]

The object keys as a keyof array.

useKeys(user); // ("id" | "name" | "email")[]

useMap<T, U>(array, transform): U[];

Defined in: core/services/array.service.ts:190

Projects every item through transform. Returns [] for nullish input.

Type Parameter Description
T Source element type.
U Projected element type.
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
transform (item, index, array) => U Receives the item, its index and the source array.

U[]

A new array of projected values.


useMapAsync<T, U>(array, transform): Promise<U[]>;

Defined in: core/services/array.service.ts:357

Projects every item through an async transform, in parallel, preserving input order.

Type Parameter Description
T Source element type.
U Projected element type.
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
transform (item, index) => Promise<U> Async projection per item.

Promise<U[]>

A promise of the projected values.


usePartition<T>(array, predicate): [T[], T[]];

Defined in: core/services/array.service.ts:159

Splits the collection into [matching, rest]. Nullish input yields [[], []].

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

[T[], T[]]

A tuple of the matching items and the rest.

const [inStock, soldOut] = usePartition(products, (p) => p.inStock);

useReduce<T, U>(
array,
reducer,
initial
): U;

Defined in: core/services/array.service.ts:225

Folds the collection into a single value. initial is required, so the return type is unambiguous even for an empty or nullish collection.

Type Parameter Description
T Source element type.
U Accumulator type.
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
reducer (accumulator, item, index) => U Receives the accumulator, the item and its index.
initial U Seed value.

U

The accumulated value.


useReduceAsync<T, U>(
array,
reducer,
initial
): Promise<U>;

Defined in: core/services/array.service.ts:433

Folds the collection with an async reducer, sequentially — a reduce that ran in parallel could not be ordered.

Type Parameter Description
T Source element type.
U Accumulator type.
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
reducer (accumulator, item, index) => Promise<U> Async step receiving the accumulator, the item and its index.
initial U Seed value.

Promise<U>

A promise of the accumulated value.


useReverse<T>(array): T[];

Defined in: core/services/array.service.ts:271

Returns a reversed copy. The native reverse mutates in place.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.

T[]

A new reversed array.


useSome<T>(array, predicate): boolean;

Defined in: core/services/array.service.ts:123

Returns true when at least one item satisfies predicate. Nullish input is false, never true.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index, array) => boolean Receives the item, its index and the source array.

boolean

Whether any item matches.


useSomeAsync<T>(array, predicate): Promise<boolean>;

Defined in: core/services/array.service.ts:392

Returns true when at least one async predicate resolves truthy. Short circuits on the first match.

Type Parameter
T
Parameter Type Description
array NullableArray<T> Source collection, possibly nullish.
predicate (item, index) => Promise<boolean> Async test per item.

Promise<boolean>

A promise of whether any item matches.


useSortBy<T>(
array,
selector,
direction?
): T[];

Defined in: core/services/array.service.ts:249

Sorts a copy of the collection by a derived key. Array.prototype.sort mutates in place, which would corrupt a shared array coming from a store or a cache; this never does.

Type Parameter Description
T Source element type.
Parameter Type Default value Description
array NullableArray<T> undefined Source collection, possibly nullish.
selector (item) => string | number | bigint | boolean | Date undefined Derives the comparable value from an item.
direction? "desc" | "asc" "asc" "asc" (default) or "desc".

T[]

A new sorted array.

useSortBy(products, (product) => product.price, "desc");

useValues<T>(object): T[keyof T][];

Defined in: core/services/array.service.ts:303

Typed Object.values. The native call returns unknown[].

Type Parameter Description
T extends object Object type.
Parameter Type Description
object T | null | undefined Source object, possibly nullish.

T[keyof T][]

The object values.


static getInstance(): ArrayService;

Defined in: core/services/array.service.ts:34

ArrayService