tinkit 0.0.0-stage → 1.0.0

package/dist/async/index.d.ts

@@ -0,0 +1,729 @@
+import { type MemoizeCache, type Result } from '../functions/index.js';
+import type { AbortSignalLike, AnyFunction, RandomGenerator } from '../utils/index.js';
+export type { Result } from '../functions/index.js';
+/**
+ * Error used to reject operations cancelled through an abort signal that carries no `reason`.
+ * @example
+ * const controller = new AbortController();
+ * controller.abort(new AbortError('cancelled by the user'));
+ * await sleep(1000, { signal: controller.signal }); // throws AbortError
+ * new AbortError().message; // => 'The operation was aborted.'
+ */
+export declare class AbortError extends Error {
+    name: string;
+    /**
+     * @param {string} [message='The operation was aborted.'] - The error message
+     */
+    constructor(message?: string);
+}
+/**
+ * Error used by {@link withTimeout} when the wrapped promise does not settle in time.
+ * @example
+ * try {
+ *   await withTimeout(new Promise(function () {}), 10);
+ * } catch (error) {
+ *   error instanceof TimeoutError; // => true
+ * }
+ */
+export declare class TimeoutError extends Error {
+    name: string;
+    /**
+     * @param {string} [message='The operation timed out.'] - The error message
+     */
+    constructor(message?: string);
+}
+/**
+ * A promise together with the functions that settle it.
+ * @template T - The resolved value type
+ */
+export interface Deferred<T> {
+    /** The pending promise. */
+    readonly promise: Promise<T>;
+    /** Resolves `promise` (no-op once settled). */
+    resolve(value: T | PromiseLike<T>): void;
+    /** Rejects `promise` (no-op once settled). */
+    reject(reason?: unknown): void;
+}
+/**
+ * Options accepted by {@link sleep}.
+ */
+export interface SleepOptions {
+    /** Aborts the sleep, rejecting with the signal's `reason` (or an {@link AbortError}). */
+    signal?: AbortSignalLike;
+}
+/**
+ * Options accepted by {@link retry}.
+ */
+export interface RetryOptions {
+    /** Number of retries after the first attempt (`Infinity` allowed). Defaults to `3`. */
+    retries?: number;
+    /** Delay in ms before the first retry. Defaults to `0`. */
+    delay?: number;
+    /** Multiplier applied to the delay after each retry. Defaults to `2`. */
+    factor?: number;
+    /** Upper bound for a single delay in ms. Defaults to `Infinity`. */
+    maxDelay?: number;
+    /** When `true`, each delay is drawn uniformly from `[0, delay]` ("full jitter"). Defaults to `false`. */
+    jitter?: boolean;
+    /** Decides whether the error thrown by attempt number `attempt` (1-based) should be retried. Defaults to always. */
+    shouldRetry?(error: unknown, attempt: number): boolean;
+    /** Called before waiting for the next retry, with the error of attempt number `attempt` (1-based). */
+    onRetry?(error: unknown, attempt: number): void;
+    /** Aborts the retry loop between attempts (and during delays), rejecting with the signal's reason. */
+    signal?: AbortSignalLike;
+}
+/**
+ * Creates a promise that can be resolved or rejected from the outside.
+ * @template T - The resolved value type
+ * @returns {Deferred<T>} The promise and its `resolve`/`reject` functions
+ * @example
+ * const ready = createDeferred<string>();
+ * setTimeout(function () { ready.resolve('open'); }, 10);
+ * await ready.promise; // => 'open'
+ */
+export declare function createDeferred<T>(): Deferred<T>;
+/**
+ * Resolves after `ms` milliseconds. If `options.signal` is aborted (before or during the wait), the timer is cleared and the promise
+ * rejects with the signal's `reason` (or an {@link AbortError} if it has none).
+ * @param {number} ms - Delay in milliseconds (`0` to `2^31 - 1`)
+ * @param {SleepOptions} [options] - Optional abort `signal`
+ * @returns {Promise<void>} A promise resolving after the delay
+ * @throws {TypeError} (as a rejection) when `ms` is not a number
+ * @throws {RangeError} (as a rejection) when `ms` is negative, `NaN` or larger than `2^31 - 1`
+ * @example
+ * await sleep(10); // resolves after ~10 ms
+ * const controller = new AbortController();
+ * const nap = sleep(10_000, { signal: controller.signal });
+ * controller.abort(); // clears the timer
+ * await nap; // throws AbortError
+ */
+export declare function sleep(ms: number, options?: SleepOptions): Promise<void>;
+/**
+ * Races `promise` against a timer: resolves/rejects like `promise` if it settles within `ms` milliseconds, otherwise rejects with a
+ * {@link TimeoutError}. The timer is always cleared. Note that the underlying operation is not cancelled.
+ * @template T - The resolved value type
+ * @param {PromiseLike<T> | T} promise - The promise (or value) to wait for
+ * @param {number} ms - The time limit in milliseconds (`0` to `2^31 - 1`)
+ * @param {string} [message] - Message of the `TimeoutError` (defaults to `Operation timed out after <ms> ms`)
+ * @returns {Promise<T>} A promise settling like `promise`, or rejecting on timeout
+ * @throws {TimeoutError} (as a rejection) when `promise` does not settle within `ms` milliseconds
+ * @throws {TypeError} (as a rejection) when `ms` is not a number
+ * @throws {RangeError} (as a rejection) when `ms` is negative, `NaN` or larger than `2^31 - 1`
+ * @example
+ * await withTimeout(Promise.resolve('data'), 5000); // => 'data'
+ * await withTimeout(new Promise(function () {}), 10, 'took too long'); // throws TimeoutError
+ */
+export declare function withTimeout<T>(promise: PromiseLike<T> | T, ms: number, message?: string): Promise<T>;
+/**
+ * Calls `fn` until it succeeds, retrying up to `options.retries` times with exponential backoff:
+ * the delay before retry `k` (1-based) is `min(delay * factor^(k - 1), maxDelay)`, optionally randomised with full jitter.
+ * Resolves with the first successful result; rejects with the last error once retries are exhausted or `shouldRetry` returns `false`.
+ * Every retry waits for at least one timer tick (`setTimeout(0)` for a zero delay), so even `retries: Infinity` with a synchronously
+ * throwing `fn` never blocks the thread and stays abortable through `signal`.
+ * @template T - The resolved value type
+ * @param {(attempt: number) => Promise<T> | T} fn - The operation; receives the 1-based attempt number
+ * @param {RetryOptions} [options] - `retries` (3), `delay` (0), `factor` (2), `maxDelay` (Infinity), `jitter` (false), `shouldRetry`, `onRetry`, `signal`
+ * @param {RandomGenerator} [random=Math.random] - Random source used for jitter
+ * @returns {Promise<T>} The first successful result
+ * @throws {TypeError} (as a rejection) when `fn`, `shouldRetry`, `onRetry` or (with `jitter`) `random` is not a function, or a numeric option is not a number
+ * @throws {RangeError} (as a rejection) when `retries` is not a non-negative integer or `Infinity`, `delay` is not a finite number >= 0,
+ * `factor` is not a finite number > 0, `maxDelay` is negative or `NaN`, or `random()` returns a value outside [0, 1)
+ * @throws {unknown} (as a rejection) the last error of `fn`, or the abort reason of `signal`
+ * @example
+ * let calls = 0;
+ * function flaky(): Promise<string> { calls++; return calls < 3 ? Promise.reject(new Error('busy')) : Promise.resolve('ok'); }
+ * await retry(flaky, { retries: 5, delay: 10, maxDelay: 2000, jitter: true }); // => 'ok'
+ * calls; // => 3
+ */
+export declare function retry<T>(fn: (attempt: number) => Promise<T> | T, options?: RetryOptions, random?: RandomGenerator): Promise<T>;
+/**
+ * Options accepted by {@link mapWithConcurrency}, {@link mapSettledWithConcurrency} and {@link filterWithConcurrency}.
+ */
+export interface ConcurrencyOptions {
+    /** Maximum number of callbacks in flight (an integer >= 1, or `Infinity`). Defaults to `Infinity`. */
+    concurrency?: number;
+    /**
+     * Aborting it stops starting new items and rejects straight away with the signal's `reason` (or an {@link AbortError}); callbacks
+     * already running are not interrupted (their outcome is ignored), but they receive the signal as their third argument.
+     */
+    signal?: AbortSignalLike | null;
+    /**
+     * `true` (the default): reject with the first error and start no further items. `false`: process every item, then reject with an
+     * `AggregateError` holding every error (in the order they occurred) if any callback failed.
+     */
+    stopOnError?: boolean;
+}
+/**
+ * A callback run by the `*WithConcurrency` helpers: receives the item, its index and the caller's abort signal.
+ * @template T - The item type
+ * @template R - The result type
+ */
+export type ConcurrentCallback<T, R> = (item: T, index: number, signal: AbortSignalLike | undefined) => PromiseLike<R> | R;
+/**
+ * Maps `items` with an async `mapper`, running at most `concurrency` mappers at the same time, and resolves with the results in input
+ * order. The third argument is either the concurrency or a {@link ConcurrencyOptions} object:
+ * - `stopOnError` (default `true`) rejects with the first error and starts no further items (mappers already running are not
+ *   cancelled; their outcome is ignored and their rejections are handled). With `false`, every item is processed and the promise then
+ *   rejects with an `AggregateError` of all the errors if any mapper failed.
+ * - `signal` stops starting new items and rejects at once with the signal's `reason`; it is also passed to every mapper as its third
+ *   argument, so mappers can cancel their own work (e.g. `fetch(url, { signal })`). The abort listener is removed on settle.
+ * @template T - The item type
+ * @template R - The mapped value type
+ * @param {Iterable<T>} items - The items to map (consumed eagerly)
+ * @param {ConcurrentCallback<T, R>} mapper - The (possibly async) mapping function, called with `(item, index, signal)`
+ * @param {number | ConcurrencyOptions} [options=Infinity] - The maximum number of mappers in flight, or `{ concurrency, signal, stopOnError }`
+ * @returns {Promise<R[]>} The mapped values, in input order
+ * @throws {TypeError} (as a rejection) when `mapper` is not a function, `concurrency` is not a number, or `signal` is not a signal
+ * @throws {RangeError} (as a rejection) when `concurrency` is not an integer >= 1 or `Infinity`
+ * @throws {AggregateError} (as a rejection) with `stopOnError: false`, when at least one mapper failed
+ * @throws {unknown} (as a rejection) the first error thrown or rejected by `mapper`, or the abort reason of `signal`
+ * @example
+ * async function size(name: string): Promise<number> { await sleep(5); return name.length; }
+ * await mapWithConcurrency(['a', 'bb', 'ccc'], size, 2); // => [1, 2, 3] // in input order, at most 2 running at once
+ * @example
+ * const controller = new AbortController();
+ * async function load(id: number, index: number, signal?: AbortSignalLike): Promise<number> { await sleep(20, { signal }); return id; }
+ * const pages = mapWithConcurrency([1, 2, 3], load, { concurrency: 2, signal: controller.signal });
+ * controller.abort(new AbortError('navigated away'));
+ * await pages; // throws AbortError
+ */
+export declare function mapWithConcurrency<T, R>(items: Iterable<T>, mapper: ConcurrentCallback<T, R>, options?: number | ConcurrencyOptions): Promise<R[]>;
+/**
+ * Like {@link mapWithConcurrency}, but never rejects because of a mapper: resolves with a `PromiseSettledResult` per item, in input
+ * order (like `Promise.allSettled`). It still rejects for invalid arguments, and with the signal's `reason` when `signal` aborts
+ * (no new items start; `stopOnError` has no effect).
+ * @template T - The item type
+ * @template R - The mapped value type
+ * @param {Iterable<T>} items - The items to map (consumed eagerly)
+ * @param {ConcurrentCallback<T, R>} mapper - The (possibly async) mapping function, called with `(item, index, signal)`
+ * @param {number | ConcurrencyOptions} [options=Infinity] - The maximum number of mappers in flight, or `{ concurrency, signal }`
+ * @returns {Promise<Array<PromiseSettledResult<Awaited<R>>>>} The outcome of every item, in input order
+ * @throws {TypeError} (as a rejection) when `mapper` is not a function, `concurrency` is not a number, or `signal` is not a signal
+ * @throws {RangeError} (as a rejection) when `concurrency` is not an integer >= 1 or `Infinity`
+ * @throws {unknown} (as a rejection) the abort reason of `signal`
+ * @example
+ * async function parse(text: string): Promise<number> { const n = Number(text); if (Number.isNaN(n)) throw new Error(`bad: ${text}`); return n; }
+ * const results = await mapSettledWithConcurrency(['1', 'x'], parse, 2);
+ * results[0]; // => { status: 'fulfilled', value: 1 }
+ * results[1]; // => { status: 'rejected', reason: new Error('bad: x') }
+ */
+export declare function mapSettledWithConcurrency<T, R>(items: Iterable<T>, mapper: ConcurrentCallback<T, R>, options?: number | ConcurrencyOptions): Promise<Array<PromiseSettledResult<Awaited<R>>>>;
+/**
+ * Filters `items` with an async `predicate`, running at most `concurrency` predicates at the same time, and resolves with the items
+ * whose predicate returned (or resolved to) a truthy value, in input order. Accepts the same options as {@link mapWithConcurrency}
+ * (`concurrency`, `signal`, `stopOnError`), with the same error and abort semantics.
+ * @template T - The item type
+ * @param {Iterable<T>} items - The items to filter (consumed eagerly)
+ * @param {ConcurrentCallback<T, unknown>} predicate - The (possibly async) predicate, called with `(item, index, signal)`
+ * @param {number | ConcurrencyOptions} [options=Infinity] - The maximum number of predicates in flight, or `{ concurrency, signal, stopOnError }`
+ * @returns {Promise<T[]>} The kept items, in input order
+ * @throws {TypeError} (as a rejection) when `predicate` is not a function, `concurrency` is not a number, or `signal` is not a signal
+ * @throws {RangeError} (as a rejection) when `concurrency` is not an integer >= 1 or `Infinity`
+ * @throws {AggregateError} (as a rejection) with `stopOnError: false`, when at least one predicate failed
+ * @throws {unknown} (as a rejection) the first error thrown or rejected by `predicate`, or the abort reason of `signal`
+ * @example
+ * async function isOnline(host: string): Promise<boolean> { await sleep(5); return host !== 'down.example'; }
+ * await filterWithConcurrency(['a.example', 'down.example', 'b.example'], isOnline, { concurrency: 2 }); // => ['a.example', 'b.example']
+ */
+export declare function filterWithConcurrency<T, S extends T>(items: Iterable<T>, predicate: (item: T, index: number, signal: AbortSignalLike | undefined) => item is S, options?: number | ConcurrencyOptions): Promise<S[]>;
+/**
+ * Filters `items` with an async `predicate`, with bounded concurrency (see the first overload).
+ * @template T - The item type
+ * @param {Iterable<T>} items - The items to filter (consumed eagerly)
+ * @param {ConcurrentCallback<T, unknown>} predicate - The (possibly async) predicate, called with `(item, index, signal)`
+ * @param {number | ConcurrencyOptions} [options=Infinity] - The maximum number of predicates in flight, or `{ concurrency, signal, stopOnError }`
+ * @returns {Promise<T[]>} The kept items, in input order
+ * @example
+ * await filterWithConcurrency([1, 2, 3, 4], async function (n) { return n % 2 === 0; }); // => [2, 4]
+ */
+export declare function filterWithConcurrency<T>(items: Iterable<T>, predicate: ConcurrentCallback<T, unknown>, options?: number | ConcurrencyOptions): Promise<T[]>;
+/**
+ * Awaits a promise (or calls a possibly async function and awaits its result) and captures the outcome as a {@link Result} tuple.
+ * The returned promise never rejects: synchronous throws and rejections both become `[error, undefined]`.
+ * @template T - The resolved value type
+ * @param {PromiseLike<T> | (() => PromiseLike<T> | T)} fnOrPromise - A promise, or a function to call (with no arguments)
+ * @returns {Promise<Result<T>>} `[undefined, value]` on success, `[error, undefined]` on failure
+ * @example
+ * await attemptAsync(Promise.resolve(42)); // => [undefined, 42]
+ * const [error, value] = await attemptAsync(function () { return JSON.parse('{'); });
+ * error instanceof SyntaxError; // => true
+ * value; // => undefined
+ */
+export declare function attemptAsync<T>(fnOrPromise: PromiseLike<T> | (() => PromiseLike<T> | T)): Promise<Result<T>>;
+/**
+ * Options accepted by {@link createLimiter}.
+ */
+export interface LimiterOptions {
+    /** When `true`, {@link Limiter.clearQueue} rejects the promises of the discarded tasks with an {@link AbortError}. Defaults to `false` (they never settle). */
+    rejectOnClear?: boolean;
+    /**
+     * Largest number of tasks allowed to wait for a slot (an integer >= 0, or `Infinity`). Once that many wait, further calls reject
+     * with a `RangeError` straight away, without queueing or running their task. Set it whenever tasks are created from untrusted or
+     * unbounded input (e.g. one per incoming request): an unbounded queue grows until the process runs out of memory.
+     * @default Infinity
+     */
+    maxPending?: number;
+}
+/**
+ * A concurrency limiter as returned by {@link createLimiter}.
+ */
+export interface Limiter {
+    /**
+     * Runs `fn(...args)` as soon as fewer than `concurrency` tasks are active (immediately and synchronously when a slot is free),
+     * and settles like its result. Synchronous throws become rejections.
+     * @throws {TypeError} (as a rejection) when `fn` is not a function
+     * @throws {RangeError} (as a rejection) when no slot is free and `maxPending` tasks are already waiting
+     */
+    <A extends unknown[], T>(fn: (...args: A) => PromiseLike<T> | T, ...args: A): Promise<T>;
+    /** Number of tasks currently running. */
+    readonly activeCount: number;
+    /** Number of tasks waiting for a free slot. */
+    readonly pendingCount: number;
+    /** Discards the waiting tasks (running tasks are not affected). */
+    clearQueue(): void;
+}
+/**
+ * Creates a limiter that runs at most `concurrency` tasks at the same time, starting waiting tasks in FIFO order (like `p-limit`).
+ * The queue of waiting tasks is unbounded by default: pass `maxPending` to bound it (calls beyond it reject with a `RangeError`)
+ * whenever the number of calls is not under your control.
+ * @param {number} concurrency - Maximum number of tasks running at once (an integer >= 1, or `Infinity`)
+ * @param {LimiterOptions} [options] - `rejectOnClear` (default `false`) and `maxPending` (default `Infinity`)
+ * @returns {Limiter} The `limit(fn, ...args)` function, with `activeCount`, `pendingCount` and `clearQueue()`
+ * @throws {TypeError} when `concurrency` or `maxPending` is not a number
+ * @throws {RangeError} when `concurrency` is not an integer >= 1 or `Infinity`, or `maxPending` is not an integer >= 0 or `Infinity`
+ * @example
+ * const limit = createLimiter(2);
+ * async function double(n: number): Promise<number> { await sleep(5); return n * 2; }
+ * const results = Promise.all([1, 2, 3].map(function (n) { return limit(double, n); }));
+ * limit.activeCount; // => 2
+ * limit.pendingCount; // => 1
+ * await results; // => [2, 4, 6]
+ * @example
+ * const limit = createLimiter(1, { maxPending: 1 });
+ * const running = limit(sleep, 5);
+ * const queued = limit(sleep, 5);
+ * await limit(sleep, 5); // throws RangeError // the queue is full
+ * await Promise.all([running, queued]);
+ */
+export declare function createLimiter(concurrency: number, options?: LimiterOptions): Limiter;
+/**
+ * Options accepted by {@link createQueue}.
+ */
+export interface QueueOptions {
+    /** Maximum number of tasks running at once (an integer >= 1, or `Infinity`). Defaults to `Infinity`. */
+    concurrency?: number;
+    /**
+     * Aborting it removes every waiting task and rejects its promise with the signal's `reason` (or an {@link AbortError}), and so does
+     * every later `add`. Running tasks are not interrupted: they receive the signal and settle on their own.
+     */
+    signal?: AbortSignalLike | null;
+}
+/**
+ * Options accepted by {@link Queue.add}.
+ */
+export interface QueueAddOptions {
+    /** Tasks with a higher priority start first; tasks of equal priority start in the order they were added. Defaults to `0`. */
+    priority?: number;
+    /**
+     * Aborting it before the task starts removes the task from the queue (it never runs) and rejects its promise with the signal's
+     * `reason`. Once started, the task receives it (combined with the queue's signal, when both are set).
+     */
+    signal?: AbortSignalLike | null;
+}
+/**
+ * A priority task queue as returned by {@link createQueue}.
+ */
+export interface Queue {
+    /**
+     * Adds a task and returns a promise that settles like it. The task is called with an abort signal (see {@link QueueAddOptions.signal})
+     * when it starts: immediately and synchronously if a slot is free, nothing is waiting and the queue is not paused. Synchronous throws
+     * become rejections.
+     * @throws {TypeError} (as a rejection) when `task` is not a function, `priority` is not a number, or `signal` is not a signal
+     * @throws {RangeError} (as a rejection) when `priority` is `NaN`
+     */
+    add<T>(task: (signal: AbortSignalLike | undefined) => PromiseLike<T> | T, options?: QueueAddOptions): Promise<T>;
+    /** Number of tasks waiting to start. */
+    readonly size: number;
+    /** Number of tasks running. */
+    readonly pending: number;
+    /** Whether the queue is paused. */
+    readonly isPaused: boolean;
+    /** Stops starting tasks (running tasks continue) until `resume()` is called. */
+    pause(): void;
+    /** Starts waiting tasks again, up to the concurrency. */
+    resume(): void;
+    /** Removes every waiting task, rejecting its promise with an {@link AbortError} (running tasks are not affected). */
+    clear(): void;
+    /** Resolves as soon as no task is waiting (immediately if none is). Each call returns a new promise, so it can be awaited again later. */
+    onEmpty(): Promise<void>;
+    /** Resolves as soon as no task is waiting or running (immediately if none is). Each call returns a new promise. */
+    onIdle(): Promise<void>;
+}
+/**
+ * Creates a task queue that runs at most `concurrency` tasks at the same time, starting the waiting task with the highest `priority`
+ * first and tasks of equal priority in FIFO order (a stable binary heap, so `add` and every start are O(log n)). It has no timers.
+ *
+ * Cancellation is precise: a task whose own `signal` aborts while it waits is removed from the queue (it never runs) and its promise
+ * rejects with the signal's `reason`; aborting the queue's `signal` does the same for every waiting task and rejects every later `add`.
+ * Running tasks are never interrupted, but they receive the signal(s) to cancel their own work. Listeners are removed as soon as a task
+ * starts or leaves the queue.
+ * @param {QueueOptions} [options] - `concurrency` (default `Infinity`) and `signal`
+ * @returns {Queue} The queue
+ * @throws {TypeError} when `concurrency` is not a number or `signal` is not a signal
+ * @throws {RangeError} when `concurrency` is not an integer >= 1 or `Infinity`
+ * @example
+ * const queue = createQueue({ concurrency: 1 });
+ * const order: string[] = [];
+ * async function job(name: string): Promise<string> { await sleep(5); order.push(name); return name; }
+ * queue.add(function () { return job('first'); }); // starts at once
+ * queue.add(function () { return job('low'); });
+ * queue.add(function () { return job('urgent'); }, { priority: 10 });
+ * queue.size; // => 2
+ * queue.pending; // => 1
+ * await queue.onIdle();
+ * order; // => ['first', 'urgent', 'low']
+ * @example
+ * const queue = createQueue({ concurrency: 1 });
+ * const controller = new AbortController();
+ * queue.add(function () { return sleep(10); });
+ * const waiting = queue.add(function () { return 'never runs'; }, { signal: controller.signal });
+ * controller.abort(new AbortError('not needed any more'));
+ * await waiting; // throws AbortError
+ * queue.size; // => 0
+ */
+export declare function createQueue(options?: QueueOptions): Queue;
+/**
+ * Options accepted by {@link createRateLimiter}.
+ */
+export interface RateLimiterOptions {
+    /** Maximum number of calls that may start within any window of `interval` milliseconds (an integer >= 1). */
+    limit: number;
+    /** Length of the sliding window in milliseconds (`0` to `2^31 - 1`). */
+    interval: number;
+    /**
+     * Aborting it rejects every waiting call (and every later one) with the signal's `reason` (or an {@link AbortError}) and clears the
+     * timer. Calls already started are not affected.
+     */
+    signal?: AbortSignalLike | null;
+}
+/**
+ * A rate limiter as returned by {@link createRateLimiter}.
+ */
+export interface RateLimiter {
+    /**
+     * Calls `fn(...args)` as soon as the rate limit allows it (immediately and synchronously when it does and no call is waiting), and
+     * settles like its result. Calls start in FIFO order and are never dropped. Synchronous throws become rejections.
+     * @throws {TypeError} (as a rejection) when `fn` is not a function
+     */
+    schedule<A extends unknown[], T>(fn: (...args: A) => PromiseLike<T> | T, ...args: A): Promise<T>;
+    /**
+     * Returns a rate-limited version of `fn`: every call goes through {@link RateLimiter.schedule} (with `this` forwarded) and returns a promise.
+     * @throws {TypeError} when `fn` is not a function
+     */
+    wrap<A extends unknown[], T, This = unknown>(fn: (this: This, ...args: A) => PromiseLike<T> | T): (this: This, ...args: A) => Promise<Awaited<T>>;
+    /** Number of calls waiting for the rate limit. */
+    readonly pendingCount: number;
+    /** Removes every waiting call, rejecting its promise with an {@link AbortError}, and clears the timer. */
+    clearQueue(): void;
+}
+/**
+ * Creates a rate limiter that starts at most `limit` calls within any window of `interval` milliseconds. Calls beyond the limit are
+ * queued (never dropped, unlike `throttle`) and start in FIFO order as soon as the window allows.
+ *
+ * The window slides (it is "strict"): a call may start only once the call `limit` starts before it started at least `interval` ms ago.
+ * Fixed windows, the default of several libraries, let `2 × limit` calls through around a window boundary. Only the start times of the
+ * last `limit` calls are kept, and at most one timer exists, only while calls are waiting: an idle limiter holds no timer, so it never
+ * keeps a process alive. `limit` caps how often calls start, not how many run at once (combine with {@link createLimiter} for that).
+ * @param {RateLimiterOptions} options - `limit`, `interval` and an optional `signal`
+ * @returns {RateLimiter} The limiter, with `schedule`, `wrap`, `pendingCount` and `clearQueue`
+ * @throws {TypeError} when `options` is not an object, `limit` or `interval` is not a number, or `signal` is not a signal
+ * @throws {RangeError} when `limit` is not an integer >= 1, or `interval` is not between `0` and `2^31 - 1`
+ * @example
+ * const limiter = createRateLimiter({ limit: 2, interval: 50 });
+ * const started: number[] = [];
+ * const begin = Date.now();
+ * function call(id: number): number { started.push(Date.now() - begin); return id; }
+ * await Promise.all([1, 2, 3].map(function (id) { return limiter.schedule(call, id); })); // => [1, 2, 3]
+ * started[1] < 50; // => true // the first two start at once
+ * started[2] >= 49; // => true // the third waits for the window to slide
+ * @example
+ * // doctest: skip
+ * const search = createRateLimiter({ limit: 5, interval: 1000 }).wrap(function (query: string) { return fetch(`/api?q=${query}`); });
+ */
+export declare function createRateLimiter(options: RateLimiterOptions): RateLimiter;
+/**
+ * Values considered falsy by JavaScript, removed from a type by {@link Truthy}.
+ */
+type Falsy = false | 0 | 0n | '' | null | undefined;
+/**
+ * `T` without its falsy members (`false`, `0`, `0n`, `''`, `null`, `undefined`).
+ * @template T - The type to narrow
+ * @example
+ * type T = Truthy<string | null>; // string
+ */
+export type Truthy<T> = Exclude<T, Falsy>;
+/**
+ * Options accepted by {@link pollUntil}.
+ */
+export interface PollOptions {
+    /** Delay in ms between the end of one check and the start of the next. Defaults to `100`. */
+    interval?: number;
+    /** Overall time limit in ms, after which the promise rejects with a {@link TimeoutError}. Defaults to `Infinity`. */
+    timeout?: number;
+    /** Stops polling, rejecting with the signal's `reason` (or an {@link AbortError}). */
+    signal?: AbortSignalLike;
+}
+/**
+ * Calls `check` immediately and then every `interval` ms (waiting for async checks to settle in between, so checks never overlap)
+ * until it returns (or resolves to) a truthy value, and resolves with that value. All timers and listeners are cleaned up on settle.
+ * @template T - The value produced by `check`
+ * @param {() => T | PromiseLike<T>} check - The condition to poll
+ * @param {PollOptions} [options] - `interval` (100), `timeout` (Infinity) and `signal`
+ * @returns {Promise<Truthy<Awaited<T>>>} The first truthy value
+ * @throws {TimeoutError} (as a rejection) when no truthy value was produced within `timeout` ms
+ * @throws {RangeError} (as a rejection) when `interval` is not a number between `0` and `2^31 - 1`, or `timeout` is neither such a number nor `Infinity`
+ * @throws {TypeError} (as a rejection) when `check` is not a function, or `interval` or `timeout` is not a number
+ * @throws {unknown} (as a rejection) the error thrown or rejected by `check`, or the abort reason of `signal`
+ * @example
+ * let status = 'loading';
+ * setTimeout(function () { status = 'ready'; }, 30);
+ * await pollUntil(function () { return status === 'ready' && status; }, { interval: 10, timeout: 5000 }); // => 'ready'
+ * await pollUntil(function () { return false; }, { interval: 10, timeout: 50 }); // throws TimeoutError
+ */
+export declare function pollUntil<T>(check: () => T | PromiseLike<T>, options?: PollOptions): Promise<Truthy<Awaited<T>>>;
+/**
+ * Like `Promise.all`, but for an object of promises (or values): resolves with an object with the same keys and the awaited values.
+ * Rejects with the first rejection. Own enumerable string and symbol keys are used; the input is not mutated.
+ * @template T - The input object type
+ * @param {T} obj - An object whose values are promises or plain values
+ * @returns {Promise<{ [K in keyof T]: Awaited<T[K]> }>} The awaited values, keyed like `obj`
+ * @throws {TypeError} (as a rejection) when `obj` is not a non-array object
+ * @example
+ * await promiseAllObject({ user: Promise.resolve('Ada'), posts: sleep(5).then(function () { return [1, 2]; }) }); // => { user: 'Ada', posts: [1, 2] }
+ */
+export declare function promiseAllObject<T extends object>(obj: T): Promise<{
+    -readonly [K in keyof T]: Awaited<T[K]>;
+}>;
+/**
+ * Like `Promise.allSettled`, but for an object of promises (or values): resolves with an object with the same keys and a
+ * `PromiseSettledResult` for each value. Never rejects (except for invalid input). Own enumerable string and symbol keys are used.
+ * @template T - The input object type
+ * @param {T} obj - An object whose values are promises or plain values
+ * @returns {Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<T[K]>> }>} The settled results, keyed like `obj`
+ * @throws {TypeError} (as a rejection) when `obj` is not a non-array object
+ * @example
+ * const results = await promiseAllSettledObject({ a: Promise.resolve(1), b: Promise.reject(new Error('x')) });
+ * results.a; // => { status: 'fulfilled', value: 1 }
+ * results.b; // => { status: 'rejected', reason: Error('x') }
+ */
+export declare function promiseAllSettledObject<T extends object>(obj: T): Promise<{
+    -readonly [K in keyof T]: PromiseSettledResult<Awaited<T[K]>>;
+}>;
+/**
+ * A debounced async function as returned by {@link debounceAsync}.
+ * @template F - The original function type
+ */
+export interface DebouncedAsync<F extends (...args: never[]) => unknown> {
+    (this: ThisParameterType<F>, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>>;
+    /** Cancels the pending invocation; the promises of the current burst reject with an {@link AbortError}. */
+    cancel(): void;
+    /** Performs the pending invocation now and returns its shared promise (`undefined` when nothing is pending). */
+    flush(): Promise<Awaited<ReturnType<F>>> | undefined;
+}
+/**
+ * Creates a debounced version of a (possibly async) function: `fn` is invoked `wait` ms after the last call of a burst, with the latest
+ * `this` and arguments, and every call of the burst returns a promise that settles with the result of that single invocation.
+ * Calls made while an invocation is running start a new burst.
+ * @template F - The type of the function to debounce
+ * @param {F} fn - The function to debounce
+ * @param {number} wait - The quiet period in milliseconds (`0` to `2^31 - 1`)
+ * @returns {DebouncedAsync<F>} The debounced function, with `.cancel()` and `.flush()`
+ * @throws {TypeError} when `fn` is not a function, or `wait` is not a number
+ * @throws {RangeError} when `wait` is negative, `NaN` or larger than `2^31 - 1`
+ * @example
+ * const queries: string[] = [];
+ * const search = debounceAsync(async function (query: string) { queries.push(query); return `results for ${query}`; }, 20);
+ * const first = search('a');
+ * const second = search('ab');
+ * await Promise.all([first, second]); // => ['results for ab', 'results for ab']
+ * queries; // => ['ab'] // one call for the whole burst
+ */
+export declare function debounceAsync<F extends (...args: never[]) => unknown>(fn: F, wait: number): DebouncedAsync<F>;
+/**
+ * Options accepted by {@link memoizeAsync}.
+ * @template F - The memoized function type
+ */
+export interface MemoizeAsyncOptions<F extends AnyFunction> {
+    /** Computes the cache key from the call arguments (`this` is forwarded). Defaults to `defaultMemoizeKey` (from the functions module). */
+    resolver?: (this: ThisParameterType<F>, ...args: Parameters<F>) => unknown;
+    /**
+     * Where resolved values are stored. Defaults to a new `Map`, or, with `ttl`, to an unbounded `createLRUCache` (from the cache module).
+     * Pass `createLRUCache({ max })` to bound it. With `ttl`, the cache's `set` is called with `{ ttl }` as its third argument.
+     */
+    cache?: MemoizeCache<unknown, Awaited<ReturnType<F>>>;
+    /** Time-to-live of every resolved value in milliseconds (`> 0`, or `Infinity`). Defaults to no expiry. */
+    ttl?: number;
+}
+/**
+ * An async function memoized with {@link memoizeAsync}.
+ * @template F - The original function type
+ */
+export interface MemoizedAsync<F extends AnyFunction> {
+    (this: ThisParameterType<F>, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>>;
+    /** The cache of resolved values, keyed by the resolver's result. */
+    readonly cache: MemoizeCache<unknown, Awaited<ReturnType<F>>>;
+    /** Forgets every resolved value and every call in flight (a call in flight still settles its callers, but its value is not cached). */
+    clear(): void;
+    /** Forgets the resolved value and the call in flight for these arguments; returns whether there was one. */
+    delete(...args: Parameters<F>): boolean;
+    /**
+     * Calls the memoized function (with `this` undefined) but stops waiting when `signal` aborts: this caller's promise rejects with the
+     * signal's `reason`, while the shared call keeps running for the other callers and still fills the cache. An already-aborted signal
+     * rejects without calling anything.
+     */
+    withSignal(signal: AbortSignalLike | null | undefined, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>>;
+}
+/**
+ * Memoizes an async (or promise-returning) function, correctly:
+ * - Single flight: concurrent calls with the same key share one in-flight call instead of starting one each.
+ * - Only resolved values are cached. A rejection (or a synchronous throw) is passed to the callers of that call and then forgotten, so
+ *   the next call retries; `memoize` or `once` on an async function would cache the rejected promise forever.
+ * - `ttl` expires resolved values; `cache` can be any `Map`-like store, such as `createLRUCache` to bound memory.
+ * - `withSignal(signal, ...args)` lets one caller stop waiting without cancelling the work shared with the others.
+ * - `clear()` / `delete(...args)` invalidate: a call in flight at that moment does not write its (possibly stale) value to the cache.
+ * @template F - The type of the function to memoize
+ * @param {F} fn - The function to memoize
+ * @param {MemoizeAsyncOptions<F>} [options] - `resolver` (key function), `cache` and `ttl`
+ * @returns {MemoizedAsync<F>} The memoized function, with `cache`, `clear()`, `delete(...args)` and `withSignal(signal, ...args)`
+ * @throws {TypeError} when `fn` or `resolver` is not a function, or `ttl` is not a number
+ * @throws {RangeError} when `ttl` is not a number > 0
+ * @example
+ * let requests = 0;
+ * async function fetchUser(id: number): Promise<{ id: number }> { requests++; await sleep(5); return { id }; }
+ * const getUser = memoizeAsync(fetchUser, { ttl: 60_000 });
+ * const [a, b] = await Promise.all([getUser(1), getUser(1)]);
+ * a === b; // => true
+ * await getUser(1); // => { id: 1 } // cached
+ * requests; // => 1
+ * @example
+ * let attempts = 0;
+ * const flaky = memoizeAsync(async function (): Promise<string> { attempts++; if (attempts === 1) throw new Error('offline'); return 'ok'; });
+ * await flaky(); // throws Error
+ * await flaky(); // => 'ok' // the rejection was not cached
+ */
+export declare function memoizeAsync<F extends AnyFunction>(fn: F, options?: MemoizeAsyncOptions<F>): MemoizedAsync<F>;
+/**
+ * Runs (possibly async) tasks one at a time, in iteration order, and resolves with their results in the same order. Each task is
+ * only pulled from the iterable (and started) after the previous one has settled, so lazy iterables and generators are supported.
+ * Rejects with the first error, without starting the remaining tasks.
+ * @template T - The task result type
+ * @param {Iterable<() => PromiseLike<T> | T>} tasks - The tasks to run
+ * @returns {Promise<T[]>} The results, in order
+ * @throws {TypeError} (as a rejection) when a task is not a function
+ * @throws {unknown} (as a rejection) the first error thrown or rejected by a task
+ * @example
+ * const log: string[] = [];
+ * async function migrate(version: number): Promise<number> { await sleep(10 - version); log.push(`v${version}`); return version; }
+ * await sequence([function () { return migrate(1); }, function () { return migrate(2); }]); // => [1, 2]
+ * log; // => ['v1', 'v2'] // each task starts after the previous one settled
+ */
+export declare function sequence<T>(tasks: Iterable<() => PromiseLike<T> | T>): Promise<T[]>;
+/**
+ * The platform's `AbortSignal` type when the consumer's TypeScript environment declares one (DOM or Node typings), and
+ * {@link AbortSignalLike} otherwise. {@link timeoutSignal} and {@link anySignal} return real `AbortSignal`s created by the platform's
+ * `AbortController`, so their results can be passed straight to `fetch`, `addEventListener` and other platform APIs.
+ */
+export type PlatformAbortSignal = typeof globalThis extends {
+    AbortSignal: {
+        prototype: infer S;
+    };
+} ? S : AbortSignalLike;
+/**
+ * Creates an `AbortSignal` that aborts with a {@link TimeoutError} after `ms` milliseconds — like the platform's `AbortSignal.timeout`,
+ * but with this library's `TimeoutError` as the reason (so `error instanceof TimeoutError` works across the async helpers).
+ *
+ * The timer cannot be cancelled and is not `unref`'d (browsers have no such concept): in Node it keeps the process alive until it
+ * fires, so prefer short timeouts or an `AbortController` you abort yourself for long-lived work. `Infinity` gives a signal that never
+ * aborts (and starts no timer), which is handy for optional timeouts.
+ * @param {number} ms - Delay in milliseconds (`0` to `2^31 - 1`, or `Infinity`)
+ * @returns {PlatformAbortSignal} A new signal that aborts after `ms` milliseconds
+ * @throws {TypeError} when `ms` is not a number
+ * @throws {RangeError} when `ms` is negative, `NaN` or larger than `2^31 - 1` (and not `Infinity`)
+ * @throws {Error} when the environment has no `AbortController`
+ * @example
+ * const signal = timeoutSignal(10);
+ * signal.aborted; // => false
+ * await sleep(30);
+ * signal.aborted; // => true
+ * signal.reason instanceof TimeoutError; // => true
+ * signal.reason.message; // => 'timeoutSignal: timed out after 10 ms'
+ * @example
+ * // doctest: skip
+ * const response = await fetch(url, { signal: timeoutSignal(5000) });
+ */
+export declare function timeoutSignal(ms: number): PlatformAbortSignal;
+/**
+ * Combines abort signals: returns a new `AbortSignal` that aborts as soon as any of the inputs aborts, with that input's `reason`
+ * (or an {@link AbortError} when it has none) — like the platform's `AbortSignal.any`, but accepting any {@link AbortSignalLike}.
+ * `null` and `undefined` entries are ignored, so optional signals can be passed directly; with no signals the result never aborts.
+ *
+ * If an input is already aborted, the result is returned already aborted (with the reason of the first such input) and no listener
+ * is attached. Otherwise one `abort` listener is added to each input, and all of them are removed as soon as the result aborts.
+ * Note that if no input ever aborts, those listeners stay attached for as long as the inputs live (unlike the native implementation,
+ * which holds them weakly), so avoid creating unbounded numbers of combined signals from one long-lived signal.
+ * @param {Iterable<AbortSignalLike | null | undefined>} signals - The signals to combine (consumed eagerly)
+ * @returns {PlatformAbortSignal} A new signal
+ * @throws {TypeError} when `signals` is not iterable, or one of its entries is not a signal, `null` or `undefined`
+ * @throws {Error} when the environment has no `AbortController`
+ * @example
+ * const user = new AbortController();
+ * const shutdown = new AbortController();
+ * const signal = anySignal([user.signal, shutdown.signal, undefined]);
+ * signal.aborted; // => false
+ * shutdown.abort('shutting down');
+ * signal.aborted; // => true
+ * signal.reason; // => 'shutting down'
+ * @example
+ * // doctest: skip
+ * await fetch(url, { signal: anySignal([options.signal, timeoutSignal(5000)]) });
+ */
+export declare function anySignal(signals: Iterable<AbortSignalLike | null | undefined>): PlatformAbortSignal;
+/**
+ * Settles like `promise`, unless `signal` aborts first, in which case it rejects with the signal's `reason` (or an
+ * {@link AbortError} when it has none). An already-aborted signal rejects immediately. The abort listener is removed as soon as
+ * `promise` settles. `signal` may be `null` or `undefined`, in which case this simply settles like `promise`.
+ *
+ * This only stops *waiting*: the underlying operation is not cancelled and keeps running (pass the signal to the operation itself,
+ * e.g. to `fetch`, when it supports cancellation). A later rejection of `promise` is handled, so it does not surface as an
+ * unhandled rejection.
+ * @template T - The resolved value type
+ * @param {PromiseLike<T> | T} promise - The promise (or value) to wait for
+ * @param {AbortSignalLike | null | undefined} signal - The signal that stops the wait
+ * @returns {Promise<T>} A promise settling like `promise`, or rejecting when `signal` aborts first
+ * @throws {TypeError} (as a rejection) when `signal` is not a signal, `null` or `undefined`
+ * @throws {unknown} (as a rejection) the abort reason of `signal`, or the rejection of `promise`
+ * @example
+ * const controller = new AbortController();
+ * await abortable(Promise.resolve(42), controller.signal); // => 42
+ * const pending = abortable(new Promise(function () {}), controller.signal);
+ * controller.abort(new AbortError('stopped waiting'));
+ * await pending; // throws AbortError
+ * await abortable(Promise.resolve(42), controller.signal); // throws AbortError
+ * await abortable(Promise.resolve(42), undefined); // => 42
+ */
+export declare function abortable<T>(promise: PromiseLike<T> | T, signal: AbortSignalLike | null | undefined): Promise<T>;
+/**
+ * Throws the signal's `reason` (or an {@link AbortError} when it has none) if `signal` is aborted; does nothing otherwise. Works with
+ * any {@link AbortSignalLike} (unlike the platform's `signal.throwIfAborted()`), and accepts `null` / `undefined` for optional signals.
+ * @param {AbortSignalLike | null | undefined} signal - The signal to check
+ * @returns {void}
+ * @throws {unknown} the abort reason of `signal`, when it is aborted
+ * @throws {TypeError} when `signal` is not a signal, `null` or `undefined`
+ * @example
+ * const controller = new AbortController();
+ * throwIfAborted(controller.signal); // => undefined
+ * throwIfAborted(undefined); // => undefined
+ * controller.abort(new TimeoutError());
+ * throwIfAborted(controller.signal); // throws TimeoutError
+ */
+export declare function throwIfAborted(signal: AbortSignalLike | null | undefined): void;