nc.async

nc.async.sleep()

sleep(duration: string | number, options?: { signal?: AbortSignal; } | undefined): Promise<void>

Waits for a while. Same as nc.wait().

Returns Promise<void>

Example

await async.sleep("250ms");

nc.async.map()

map<T, R>(items: Iterable<T> | AsyncIterable<T>, fn: (item: T, index: number) => R | PromiseLike<R>, options?: MapOptions): Promise<Awaited<R>[]>

Maps items through an async function, with at most concurrency calls at once. Results stay in order.

Returns Promise<Array<Awaited<R>>>

Throws The first error, an AggregateError with stopOnError: false, or an AbortError.

Example

const users = await async.map(ids, (id) => api.getUser(id), { concurrency: 10 });

nc.async.forEach()

forEach<T>(items: Iterable<T> | AsyncIterable<T>, fn: (item: T, index: number) => unknown, options?: MapOptions): Promise<void>

Runs an async function for every item, with a concurrency limit.

Returns Promise<void>

Example

await async.forEach(images, (image) => optimize(image), { concurrency: 4 });

nc.async.filter()

filter<T>(items: Iterable<T> | AsyncIterable<T>, predicate: (item: T, index: number) => unknown, options?: MapOptions): Promise<T[]>

Keeps the items that pass an async test, with a concurrency limit. Order is preserved.

Returns Promise<T[]>

Example

const alive = await async.filter(hosts, (host) => ping(host), { concurrency: 20 });

nc.async.series()

series<T>(tasks: Iterable<() => T | PromiseLike<T>>): Promise<Awaited<T>[]>

Runs async functions one after the other and returns their results.

Returns Promise<Array<Awaited<T>>>

Example

await async.series([() => migrateUsers(), () => migrateOrders()]);

nc.async.limit()

limit(concurrency: number): Limiter

A limiter: wrap calls with it, and at most concurrency run at once while the rest wait their turn. Like p-limit.

Returns Limiter

Example

const limit = async.limit(3);
const results = await Promise.all(urls.map((url) => limit(() => fetch(url))));

nc.async.queue()

queue(options?: QueueOptions): Queue

A task queue with a concurrency limit, priorities, pause and per-task timeouts.

Returns Queue

Example

const jobs = async.queue({ concurrency: 2, timeout: "30s" });
jobs.add(() => sendEmail(a));
jobs.add(() => sendEmail(vip), { priority: 10 }); // jumps the line
await jobs.onIdle();

nc.async.mutex()

mutex(): Mutex

A mutex: tasks given to run() never overlap. Put it around read-modify-write steps, like updating a file or refreshing a token.

Returns Mutex

Example

const lock = async.mutex();
await lock.run(async () => {
  const data = nc.readJSON("./counter.json", { n: 0 });
  nc.writeJSON("./counter.json", { n: data.n + 1 });
});

nc.async.deferred()

deferred<T = void>(): Deferred<T>

A promise along with its resolve and reject. Handy to connect callbacks or events to await.

Returns Deferred<T>

Example

const ready = async.deferred();
socket.once("open", () => ready.resolve());
await ready.promise;

nc.async.settle()

settle<T>(promises: Iterable<T | PromiseLike<T>>): Promise<Settled<Awaited<T>>>

Waits for every promise and sorts successes from failures.

Returns Promise<Settled<Awaited<T>>>

Example

const { fulfilled, rejected } = await async.settle(emails.map(send));
nc.info(`${fulfilled.length} sent, ${rejected.length} failed`);

nc.async.props()

props<T extends Record<string, unknown>>(object: T): Promise<{ [K in keyof T]: Awaited<T[K]>; }>

Like Promise.all, for an object of promises.

Returns Promise<{ [K in keyof T]: Awaited<T[K]> }>

Example

const { user, orders } = await async.props({ user: getUser(id), orders: getOrders(id) });

nc.async.poll()

poll<T>(fn: () => T | PromiseLike<T>, options?: PollOptions): Promise<NonNullable<Awaited<T>>>

Calls fn until it returns something truthy, and resolves with it. Errors count as "not yet".

Returns Promise<NonNullable<Awaited<T>>>

Throws TimeoutError; AbortError

Example

await async.poll(() => fetch(healthUrl).then((res) => res.ok), { interval: "500ms", timeout: "30s" });

nc.async.retry()

retry<T>(fn: (attempt: number) => T | PromiseLike<T>, options?: RetryOptions): Promise<Awaited<T>>

Calls fn until it succeeds, waiting between attempts. If every attempt fails, the last error is thrown.

Returns Promise<Awaited<T>>

Throws The last error, or an AbortError if the signal fires.

Example

const data = await func.retry(() => fetchJSON(url), {
  attempts: 5,
  delay: 200,
  backoff: 2, // 200, 400, 800, 1600 ms
  shouldRetry: (error) => !(error instanceof nc.errors.HttpError && error.status < 500),
});

nc.async.timeout()

timeout<T>(promise: PromiseLike<T> | (() => T | PromiseLike<T>), ms: number, message?: string): Promise<Awaited<T>>

Rejects with a TimeoutError if the promise takes longer than ms.

Returns Promise<Awaited<T>>

Throws TimeoutError

Example

const res = await func.timeout(fetch(url), 5000);
const rows = await func.timeout(() => slowQuery(), 2000, "Database too slow");