Async API

sleep Delay

Waits for a duration with AbortSignal support.

Signature

export function sleep(milliseconds: number, options: AbortOptions = {}): Promise<void>;

Example

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

const result = await sleep(100, {});

Input

Input	Type	Required / default	Description
milliseconds	number	Required	Finite duration in milliseconds from 0 to 2,147,483,647.
options	AbortOptions	Optional; defaults to {}	Optional cancellation signal.

Returns

Value	Type	Description
result	Promise<void>	Promise fulfilled after the delay.

withTimeout Timeout

Adds a waiting deadline to a Promise.

Signature

export function withTimeout<Result>(promise: PromiseLike<Result>, timeoutMs: number, options: TimeoutOptions = {}): Promise<Result>;

Example

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

const result = await withTimeout(Promise.resolve("done"), 100, {});

Input

Input	Type	Required / default	Description
promise	PromiseLike<Result>	Required	Promise or PromiseLike to await.
timeoutMs	number	Required	Finite timeout from 0 to 2,147,483,647 milliseconds.
options	TimeoutOptions	Optional; defaults to {}	Cancellation signal and custom message.

Returns

Value	Type	Description
result	Promise<Result>	Result of the underlying Promise.

retry Retry

Retries an operation with capped exponential backoff.

Signature

export async function retry<Result>(
	operation: (context: RetryContext) => Result | PromiseLike<Result>,
	options: RetryOptions = {}
): Promise<Awaited<Result>>;

Example

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

const result = await retry(async ({ attempt }) => (attempt < 2 ? Promise.reject(new Error("retry")) : "done"), { attempts: 2 });

Input

Input	Type	Required / default	Description
operation	(context: RetryContext) => Result | PromiseLike<Result>	Required	Function called for every attempt; attempt starts at 1.
options	RetryOptions	Optional; defaults to {}	Attempt count, backoff, and cancellation policy.

Returns

Value	Type	Description
result	Promise<Awaited<Result>>	First successful result.

mapConcurrent Concurrency

Maps an array with bounded concurrency, preserving result order.

Signature

export async function mapConcurrent<Item, Result>(
	items: readonly Item[],
	concurrency: number,
	mapper: (item: Item, index: number, signal: AbortSignal | undefined) => Result | PromiseLike<Result>,
	options: ConcurrentMapOptions = {}
): Promise<Awaited<Result>[]>;

Example

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

const result = await mapConcurrent([1, 2, 3], 2, async (item) => item * 2);

Input

Input	Type	Required / default	Description
items	readonly Item[]	Required	Readonly input array; not mutated.
concurrency	number	Required	Maximum simultaneous tasks; a positive safe integer.
mapper	(item: Item, index: number, signal: AbortSignal | undefined) => Result | PromiseLike<Result>	Required	Mapper receiving the item, index, and cancellation signal.
options	ConcurrentMapOptions	Optional; defaults to {}	Optional cancellation signal.

Returns

Value	Type	Description
result	Promise<Awaited<Result>[]>	Result array matching input length and order; sparse holes remain holes without invoking the mapper.

debounce Debounce

Creates a Promise-aware debounced function.

Signature

export function debounce<Arguments extends unknown[], Result>(
	callback: AsyncCallback<Arguments, Result>,
	delayMs = 300
): DebouncedFunction<Arguments, Awaited<Result>>;

Example

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

const save = debounce((value: string) => value.length, 200);
const pending = save("Fast");
await save.flush();
const result = await pending;

Input

Input	Type	Required / default	Description
callback	AsyncCallback<Arguments, Result>	Required	Synchronous or asynchronous callback.
delayMs	unknown	Optional; defaults to 300	Finite delay from 0 to 2,147,483,647 milliseconds; defaults to 300.

Returns

Value	Type	Description
result	DebouncedFunction<Arguments, Awaited<Result>>	Debounced function with cancellation, flush, and status methods.

throttle Throttle

Creates a Promise-aware leading-edge throttled function.

Signature

export function throttle<Arguments extends unknown[], Result>(
	callback: AsyncCallback<Arguments, Result>,
	delayMs = 300
): ThrottledFunction<Arguments, Awaited<Result>>;

Example

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

const update = throttle((value: number) => value * 2, 200);
const result = await update(2);

Input

Input	Type	Required / default	Description
callback	AsyncCallback<Arguments, Result>	Required	Synchronous or asynchronous callback.
delayMs	unknown	Optional; defaults to 300	Finite cooldown from 0 to 2,147,483,647 milliseconds; defaults to 300.

Returns

Value	Type	Description
result	ThrottledFunction<Arguments, Awaited<Result>>	Leading-edge throttled function with cancellation and status methods.

DebouncedFunction.cancel Cancel

Cancels a pending debounce batch and rejects all its Promises.

Signature

cancel(reason?: unknown): void;

Example

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

const save = debounce(async () => "saved");
const pending = save();
save.cancel(new Error("cancelled"));
await pending.catch(() => undefined);

Input

Input	Type	Required / default	Description
reason	unknown	Optional	Rejection reason; an internal cancellation error is used when omitted.

Returns

Value	Type	Description
result	void	No return value.

DebouncedFunction.flush Flush

Immediately executes the pending debounce batch.

Signature

flush(): Promise<Result> | undefined;

Example

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

const save = debounce(async () => "saved");
save();
const result = await save.flush();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	Promise<Result> | undefined	Shared execution Promise, or undefined when no batch is pending.

DebouncedFunction.pending Pending

Checks whether a debounce batch is waiting to start.

Signature

pending(): boolean;

Example

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

const save = debounce(() => 1);
save();
const result = save.pending();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	boolean	true when a batch is pending.

ThrottledFunction.cancel Cancel

Ends the throttle cooldown early; does not cancel an operation already running.

Signature

cancel(): void;

Example

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

const update = throttle(() => 1);
update.cancel();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

ThrottledFunction.pending Pending

Checks whether the throttled callback is running or cooling down.

Signature

pending(): boolean;

Example

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

const update = throttle(() => 1);
update();
const result = update.pending();

Input

This method has no input parameters.

Returns

Value	Type	Description
result	boolean	true while running or cooling down.