atomic-fns 1.1.7 → 2.0.0

package/dist/array/list.js

@@ -0,0 +1,133 @@
+/**
+ * Array building blocks: `chunk`, `zip`, `range`, `remove`, `dropWhile`, `takeWhile`.
+ */
+import { assertNotHugeSparse, walkArray } from '../internal/sparse.js';
+/** The longest array the platform can build. */
+const MAX_LENGTH = 2 ** 32 - 1;
+/**
+ * `array` split into consecutive pieces of `size` elements; the last piece holds the rest.
+ * @param array The array to split.
+ * @param size The length of each piece, a positive integer.
+ * @returns A new array of new arrays.
+ * @throws {RangeError} when `size` is not a positive integer, or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ * ```
+ */
+export function chunk(array, size) {
+    if (!Number.isInteger(size) || size < 1) {
+        throw new RangeError(`chunk size must be a positive integer, got ${String(size)}`);
+    }
+    assertNotHugeSparse(array);
+    const out = [];
+    for (let i = 0; i < array.length; i += size)
+        out.push(array.slice(i, i + size));
+    return out;
+}
+/**
+ * Rows built from the elements at each index of `arrays`: `zip(a, b)[i]` is `[a[i], b[i]]`. The
+ * result is as long as the longest input, and shorter inputs give `undefined`, as lodash does, so
+ * `zip(...zip(a, b))` restores `a` and `b` padded to one length.
+ * @param arrays The arrays to combine.
+ * @returns A new array of rows.
+ * @throws {RangeError} when an input is a huge sparse array.
+ * @example
+ * ```ts
+ * zip(['a', 'b'], [1, 2]) // [['a', 1], ['b', 2]]
+ * zip(...[['a', 1], ['b', 2]]) // [['a', 'b'], [1, 2]]
+ * ```
+ */
+export function zip(...arrays) {
+    let length = 0;
+    for (const arr of arrays) {
+        assertNotHugeSparse(arr);
+        length = Math.max(length, arr.length);
+    }
+    return Array.from({ length }, (_, i) => arrays.map((arr) => arr[i]));
+}
+export function range(first, last, by) {
+    const [start, stop, step] = last === undefined ? [0, first, 1] : [first, last, by ?? 1];
+    for (const n of [start, stop, step]) {
+        if (typeof n !== 'number')
+            throw new TypeError(`range bounds must be numbers, got ${typeof n}`);
+        if (!Number.isFinite(n))
+            throw new RangeError('range bounds and step must be finite');
+    }
+    if (step === 0)
+        throw new RangeError('range step must not be zero');
+    const count = Math.max(0, Math.ceil((stop - start) / step));
+    if (count > MAX_LENGTH)
+        throw new RangeError(`range of ${String(count)} numbers is too long`);
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        const value = start + i * step;
+        if (step > 0 ? !(value < stop) : !(value > stop))
+            break;
+        out.push(value);
+    }
+    return out;
+}
+export function remove(array, predicate) {
+    const removed = [];
+    const kept = [];
+    walkArray(array, (event) => {
+        if (event.kind !== 'value')
+            return;
+        const value = event.value;
+        if (predicate(value, event.index, array))
+            removed.push(value);
+        else
+            kept.push([event.index - removed.length, value]);
+    });
+    if (removed.length === 0)
+        return [];
+    const length = array.length - removed.length;
+    array.length = 0;
+    for (const [index, value] of kept)
+        array[index] = value;
+    array.length = length;
+    return removed;
+}
+function splitWhile(array, predicate, take) {
+    const out = [];
+    const length = array.length;
+    let boundary = length;
+    let matching = true;
+    walkArray(array, (event) => {
+        if (event.kind !== 'value')
+            return;
+        const value = event.value;
+        if (matching) {
+            if (predicate(value, event.index, array)) {
+                if (take)
+                    out[event.index] = value;
+                return;
+            }
+            matching = false;
+            boundary = event.index;
+        }
+        if (take)
+            return false;
+        out[event.index - boundary] = value;
+    });
+    out.length = take ? boundary : length - boundary;
+    return out;
+}
+/**
+ * `array` without its leading elements for which `predicate` is truthy. Holes are skipped, as
+ * {@link remove} skips them, and keep their place in the result.
+ * @param array The array to read.
+ * @param predicate Tests one element present; gets `(value, index, array)`.
+ * @returns A new array from the first element that fails.
+ * @example
+ * ```ts
+ * dropWhile([1, 2, 3, 1], (n) => n < 3) // [3, 1]
+ * ```
+ */
+export function dropWhile(array, predicate) {
+    return splitWhile(array, predicate, false);
+}
+export function takeWhile(array, predicate) {
+    return splitWhile(array, predicate, true);
+}

package/dist/array/sets.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Set operations on arrays: values in order of first appearance, duplicates removed, compared
+ * with SameValueZero (as `Set` and `includes` do) unless a key or equality function is given.
+ */
+/**
+ * `array` with the later elements that give the same key as an earlier one removed.
+ * `[...new Set(array)]` is the plain `uniq`.
+ * @param array The array to read.
+ * @param keyOf Returns the key of one element, compared with SameValueZero.
+ * @returns A new array of the first element for each key.
+ * @example
+ * ```ts
+ * uniqBy([2.1, 1.2, 2.3], Math.floor) // [2.1, 1.2]
+ * ```
+ */
+export declare function uniqBy<T>(array: Iterable<T>, keyOf: (value: T) => unknown): T[];
+/**
+ * `array` with the later elements that `equals` matches to an earlier one removed. It costs one
+ * comparison per pair of kept elements.
+ * @param array The array to read.
+ * @param equals Returns truthy when two elements count as the same; it gets the element under test
+ *   first and the kept element second.
+ * @returns A new array of the first element of each group.
+ * @example
+ * ```ts
+ * uniqWith([{ x: 1 }, { x: 1 }], (a, b) => a.x === b.x) // [{ x: 1 }]
+ * ```
+ */
+export declare function uniqWith<T>(array: Iterable<T>, equals: (a: T, b: T) => unknown): T[];
+/**
+ * The distinct values of `array` that none of `others` holds.
+ * @param array The array to keep values from.
+ * @param others The arrays whose values to leave out.
+ * @returns A new array, in the order of `array`.
+ * @example
+ * ```ts
+ * difference([2, 1, 2, 3], [2]) // [1, 3]
+ * ```
+ */
+export declare function difference<T>(array: Iterable<T>, ...others: Iterable<T>[]): T[];
+/**
+ * {@link difference} by the key `keyOf` gives each value; the key function comes last.
+ * @param array The array to keep values from.
+ * @param rest The arrays to leave out, then the key function.
+ * @returns A new array, in the order of `array`.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * differenceBy([2.1, 1.2], [2.3], Math.floor) // [1.2]
+ * ```
+ */
+export declare function differenceBy<T>(array: Iterable<T>, ...rest: [...others: Iterable<T>[], keyOf: (value: T) => unknown]): T[];
+/**
+ * {@link difference} with `equals` deciding which values match; the function comes last.
+ * @param array The array to keep values from.
+ * @param rest The arrays to leave out, then the equality function, which gets the element under
+ *   test first and the kept or excluded element second.
+ * @returns A new array, in the order of `array`.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * differenceWith([{ x: 1 }, { x: 2 }], [{ x: 1 }], (a, b) => a.x === b.x) // [{ x: 2 }]
+ * ```
+ */
+export declare function differenceWith<T>(array: Iterable<T>, ...rest: [...others: Iterable<T>[], equals: (a: T, b: T) => unknown]): T[];
+/**
+ * The distinct values of the first array that every other array holds.
+ * @param arrays The arrays to intersect.
+ * @returns A new array, in the order of the first array; `[]` with no arrays.
+ * @example
+ * ```ts
+ * intersection([2, 1, 2], [2, 3], [4, 2]) // [2]
+ * ```
+ */
+export declare function intersection<T>(...arrays: Iterable<T>[]): T[];
+/**
+ * {@link intersection} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to intersect, then the key function.
+ * @returns A new array, in the order of the first array.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * intersectionBy([2.1, 1.2], [2.3], Math.floor) // [2.1]
+ * ```
+ */
+export declare function intersectionBy<T>(...rest: [...arrays: Iterable<T>[], keyOf: (value: T) => unknown]): T[];
+/**
+ * The distinct values of all `arrays`, in order of first appearance.
+ * @param arrays The arrays to join.
+ * @returns A new array.
+ * @example
+ * ```ts
+ * union([2], [1, 2], [3]) // [2, 1, 3]
+ * ```
+ */
+export declare function union<T>(...arrays: Iterable<T>[]): T[];
+/**
+ * {@link union} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to join, then the key function.
+ * @returns A new array of the first value for each key.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * unionBy([2.1], [1.2, 2.3], Math.floor) // [2.1, 1.2]
+ * ```
+ */
+export declare function unionBy<T>(...rest: [...arrays: Iterable<T>[], keyOf: (value: T) => unknown]): T[];
+/**
+ * The distinct values that exactly one of `arrays` holds (for two arrays, the symmetric
+ * difference), in order of first appearance.
+ * @param arrays The arrays to compare.
+ * @returns A new array.
+ * @example
+ * ```ts
+ * xor([2, 1], [2, 3]) // [1, 3]
+ * xor([1], [1], [1]) // []
+ * ```
+ */
+export declare function xor<T>(...arrays: Iterable<T>[]): T[];
+/**
+ * {@link xor} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to compare, then the key function.
+ * @returns A new array of the first value for each key only one array holds.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * xorBy([2.1, 1.2], [2.3], Math.floor) // [1.2]
+ * ```
+ */
+export declare function xorBy<T>(...rest: [...arrays: Iterable<T>[], keyOf: (value: T) => unknown]): T[];

package/dist/array/sets.js

@@ -0,0 +1,213 @@
+/**
+ * Set operations on arrays: values in order of first appearance, duplicates removed, compared
+ * with SameValueZero (as `Set` and `includes` do) unless a key or equality function is given.
+ */
+const same = (value) => value;
+function splitLast(rest, what) {
+    const fn = rest[rest.length - 1];
+    if (typeof fn !== 'function') {
+        throw new TypeError(`the last argument must be ${what}, got ${typeof fn}`);
+    }
+    // TypeScript cannot split a tuple whose rest element comes first, so the halves are cast.
+    return [rest.slice(0, -1), fn];
+}
+function uniqueBy(lists, keyOf, keep) {
+    const seen = new Set();
+    const out = [];
+    for (const list of lists) {
+        for (const value of list) {
+            const key = keyOf(value);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (keep(key))
+                out.push(value);
+        }
+    }
+    return out;
+}
+function keySet(list, keyOf) {
+    const keys = new Set();
+    for (const value of list)
+        keys.add(keyOf(value));
+    return keys;
+}
+function uniqueWith(lists, equals, keep) {
+    const out = [];
+    for (const list of lists) {
+        for (const value of list) {
+            if (out.some((kept) => equals(value, kept)) || !keep(value))
+                continue;
+            out.push(value);
+        }
+    }
+    return out;
+}
+/**
+ * `array` with the later elements that give the same key as an earlier one removed.
+ * `[...new Set(array)]` is the plain `uniq`.
+ * @param array The array to read.
+ * @param keyOf Returns the key of one element, compared with SameValueZero.
+ * @returns A new array of the first element for each key.
+ * @example
+ * ```ts
+ * uniqBy([2.1, 1.2, 2.3], Math.floor) // [2.1, 1.2]
+ * ```
+ */
+export function uniqBy(array, keyOf) {
+    return uniqueBy([array], keyOf, () => true);
+}
+/**
+ * `array` with the later elements that `equals` matches to an earlier one removed. It costs one
+ * comparison per pair of kept elements.
+ * @param array The array to read.
+ * @param equals Returns truthy when two elements count as the same; it gets the element under test
+ *   first and the kept element second.
+ * @returns A new array of the first element of each group.
+ * @example
+ * ```ts
+ * uniqWith([{ x: 1 }, { x: 1 }], (a, b) => a.x === b.x) // [{ x: 1 }]
+ * ```
+ */
+export function uniqWith(array, equals) {
+    return uniqueWith([array], equals, () => true);
+}
+/**
+ * The distinct values of `array` that none of `others` holds.
+ * @param array The array to keep values from.
+ * @param others The arrays whose values to leave out.
+ * @returns A new array, in the order of `array`.
+ * @example
+ * ```ts
+ * difference([2, 1, 2, 3], [2]) // [1, 3]
+ * ```
+ */
+export function difference(array, ...others) {
+    return differenceBy(array, ...others, same);
+}
+/**
+ * {@link difference} by the key `keyOf` gives each value; the key function comes last.
+ * @param array The array to keep values from.
+ * @param rest The arrays to leave out, then the key function.
+ * @returns A new array, in the order of `array`.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * differenceBy([2.1, 1.2], [2.3], Math.floor) // [1.2]
+ * ```
+ */
+export function differenceBy(array, ...rest) {
+    const [others, keyOf] = splitLast(rest, 'a key function');
+    const excluded = new Set();
+    for (const other of others)
+        for (const value of other)
+            excluded.add(keyOf(value));
+    return uniqueBy([array], keyOf, (key) => !excluded.has(key));
+}
+/**
+ * {@link difference} with `equals` deciding which values match; the function comes last.
+ * @param array The array to keep values from.
+ * @param rest The arrays to leave out, then the equality function, which gets the element under
+ *   test first and the kept or excluded element second.
+ * @returns A new array, in the order of `array`.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * differenceWith([{ x: 1 }, { x: 2 }], [{ x: 1 }], (a, b) => a.x === b.x) // [{ x: 2 }]
+ * ```
+ */
+export function differenceWith(array, ...rest) {
+    const [others, equals] = splitLast(rest, 'an equality function');
+    const excluded = others.flatMap((other) => [...other]);
+    return uniqueWith([array], equals, (value) => !excluded.some((other) => equals(value, other)));
+}
+/**
+ * The distinct values of the first array that every other array holds.
+ * @param arrays The arrays to intersect.
+ * @returns A new array, in the order of the first array; `[]` with no arrays.
+ * @example
+ * ```ts
+ * intersection([2, 1, 2], [2, 3], [4, 2]) // [2]
+ * ```
+ */
+export function intersection(...arrays) {
+    return intersectionBy(...arrays, same);
+}
+/**
+ * {@link intersection} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to intersect, then the key function.
+ * @returns A new array, in the order of the first array.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * intersectionBy([2.1, 1.2], [2.3], Math.floor) // [2.1]
+ * ```
+ */
+export function intersectionBy(...rest) {
+    const [arrays, keyOf] = splitLast(rest, 'a key function');
+    if (arrays.length === 0)
+        return [];
+    const others = arrays.slice(1).map((other) => keySet(other, keyOf));
+    return uniqueBy([arrays[0]], keyOf, (key) => others.every((keys) => keys.has(key)));
+}
+/**
+ * The distinct values of all `arrays`, in order of first appearance.
+ * @param arrays The arrays to join.
+ * @returns A new array.
+ * @example
+ * ```ts
+ * union([2], [1, 2], [3]) // [2, 1, 3]
+ * ```
+ */
+export function union(...arrays) {
+    return uniqueBy(arrays, same, () => true);
+}
+/**
+ * {@link union} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to join, then the key function.
+ * @returns A new array of the first value for each key.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * unionBy([2.1], [1.2, 2.3], Math.floor) // [2.1, 1.2]
+ * ```
+ */
+export function unionBy(...rest) {
+    const [arrays, keyOf] = splitLast(rest, 'a key function');
+    return uniqueBy(arrays, keyOf, () => true);
+}
+/**
+ * The distinct values that exactly one of `arrays` holds (for two arrays, the symmetric
+ * difference), in order of first appearance.
+ * @param arrays The arrays to compare.
+ * @returns A new array.
+ * @example
+ * ```ts
+ * xor([2, 1], [2, 3]) // [1, 3]
+ * xor([1], [1], [1]) // []
+ * ```
+ */
+export function xor(...arrays) {
+    return xorBy(...arrays, same);
+}
+/**
+ * {@link xor} by the key `keyOf` gives each value; the key function comes last.
+ * @param rest The arrays to compare, then the key function.
+ * @returns A new array of the first value for each key only one array holds.
+ * @throws {TypeError} when the last argument is not a function.
+ * @example
+ * ```ts
+ * xorBy([2.1, 1.2], [2.3], Math.floor) // [1.2]
+ * ```
+ */
+export function xorBy(...rest) {
+    const [arrays, keyOf] = splitLast(rest, 'a key function');
+    const lists = arrays.map((array) => Array.from(array, (value) => [value, keyOf(value)]));
+    const keyOfPair = ([, key]) => key;
+    const holders = new Map();
+    for (const list of lists) {
+        for (const key of keySet(list, keyOfPair))
+            holders.set(key, (holders.get(key) ?? 0) + 1);
+    }
+    return uniqueBy(lists, keyOfPair, (key) => holders.get(key) === 1).map(([value]) => value);
+}

package/dist/async/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Async helpers: `sleep`, `timeout` and `retry`.
+ * @module async
+ */
+export { type RetryOptions, retry } from './retry.js';
+export { type SleepOptions, sleep, type TimeoutOptions, timeout } from './sleep.js';

package/dist/async/index.js

@@ -0,0 +1,6 @@
+/**
+ * Async helpers: `sleep`, `timeout` and `retry`.
+ * @module async
+ */
+export { retry } from './retry.js';
+export { sleep, timeout } from './sleep.js';

package/dist/async/retry.d.ts

@@ -0,0 +1,38 @@
+/** Options for {@link retry}. */
+export interface RetryOptions {
+    /** Retries after the first attempt (default 3); `Infinity` retries until success or abort. */
+    retries?: number;
+    /** Delay before the first retry, in milliseconds (default 100). */
+    minDelay?: number;
+    /** Longest delay between attempts, in milliseconds (default 10000, or `minDelay` when larger). */
+    maxDelay?: number;
+    /** Growth of the delay per retry (default 2). */
+    factor?: number;
+    /** Scale each delay by a random factor in [0.5, 1) so callers spread out (default `true`). */
+    jitter?: boolean;
+    /**
+     * Stops retrying and rejects with the signal's `reason` when it aborts. A running attempt is
+     * not interrupted, so pass the same signal to the work in `fn` to stop it too.
+     */
+    signal?: AbortSignal;
+    /** Decides whether an error is worth another attempt (default: every error is). */
+    shouldRetry?: (error: unknown, attempt: number) => boolean | PromiseLike<boolean>;
+}
+/**
+ * Calls `fn` until it succeeds, waiting between attempts with exponential backoff:
+ * `min(maxDelay, minDelay * factor ** (retry - 1))`, scaled into [0.5, 1) of that when `jitter`
+ * is on. `fn` receives the attempt number, from 1. After the last retry, or when `shouldRetry`
+ * returns `false`, the promise rejects with the error `fn` threw. An aborted `signal` rejects with
+ * its `reason` once the running attempt settles, before `shouldRetry` and the next attempt, or
+ * during a wait. Delays are checked as in {@link sleep}: negative ones clamp to 0.
+ * @param fn The work to try; may return a value or a promise.
+ * @param options Backoff, `signal` and `shouldRetry`.
+ * @returns A promise for the first successful result.
+ * @throws {TypeError} when `fn` is not a function, or a delay is not a number.
+ * @throws {RangeError} when an option is out of range, or `maxDelay` is below `minDelay`.
+ * @example
+ * ```ts
+ * const data = await retry(() => fetch('/api').then((r) => r.json()), { retries: 5 })
+ * ```
+ */
+export declare function retry<T>(fn: (attempt: number) => T | PromiseLike<T>, options?: RetryOptions): Promise<T>;

package/dist/async/retry.js

@@ -0,0 +1,56 @@
+import { assertFunction } from '../function/shared.js';
+import { timerWait } from '../internal/timer.js';
+import { sleep } from './sleep.js';
+/**
+ * Calls `fn` until it succeeds, waiting between attempts with exponential backoff:
+ * `min(maxDelay, minDelay * factor ** (retry - 1))`, scaled into [0.5, 1) of that when `jitter`
+ * is on. `fn` receives the attempt number, from 1. After the last retry, or when `shouldRetry`
+ * returns `false`, the promise rejects with the error `fn` threw. An aborted `signal` rejects with
+ * its `reason` once the running attempt settles, before `shouldRetry` and the next attempt, or
+ * during a wait. Delays are checked as in {@link sleep}: negative ones clamp to 0.
+ * @param fn The work to try; may return a value or a promise.
+ * @param options Backoff, `signal` and `shouldRetry`.
+ * @returns A promise for the first successful result.
+ * @throws {TypeError} when `fn` is not a function, or a delay is not a number.
+ * @throws {RangeError} when an option is out of range, or `maxDelay` is below `minDelay`.
+ * @example
+ * ```ts
+ * const data = await retry(() => fetch('/api').then((r) => r.json()), { retries: 5 })
+ * ```
+ */
+export function retry(fn, options = {}) {
+    assertFunction(fn, 'fn');
+    const retries = options.retries ?? 3;
+    if (!(Number.isInteger(retries) || retries === Number.POSITIVE_INFINITY) || retries < 0) {
+        throw new RangeError('retries must be a non-negative integer or Infinity');
+    }
+    const minDelay = timerWait(options.minDelay ?? 100, 'minDelay');
+    const maxDelay = options.maxDelay == null ? Math.max(10_000, minDelay) : timerWait(options.maxDelay, 'maxDelay');
+    if (maxDelay < minDelay)
+        throw new RangeError('maxDelay must be >= minDelay');
+    const factor = options.factor ?? 2;
+    if (typeof factor !== 'number' || !(factor >= 1 && Number.isFinite(factor))) {
+        throw new RangeError('factor must be a finite number >= 1');
+    }
+    const jitter = options.jitter ?? true;
+    const { signal, shouldRetry } = options;
+    return (async () => {
+        let backoff = minDelay;
+        for (let attempt = 1;; attempt++) {
+            signal?.throwIfAborted();
+            try {
+                return await fn(attempt);
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                if (attempt > retries)
+                    throw error;
+                if (shouldRetry && !(await shouldRetry(error, attempt)))
+                    throw error;
+                await sleep(jitter ? backoff * (0.5 + Math.random() / 2) : backoff, { signal });
+                // Grown one step at a time, so it stays capped instead of overflowing to Infinity or NaN.
+                backoff = Math.min(maxDelay, backoff * factor);
+            }
+        }
+    })();
+}

package/dist/async/sleep.d.ts

@@ -0,0 +1,42 @@
+/** Options for {@link sleep}. */
+export interface SleepOptions {
+    /** Rejects the wait with the signal's `reason` when it aborts. */
+    signal?: AbortSignal;
+}
+/** Options for {@link timeout}. */
+export interface TimeoutOptions {
+    /** Rejects with the signal's `reason` when it aborts before the promise settles. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves after `ms` milliseconds. An aborted `signal` rejects with its `reason`, at once when it
+ * is already aborted. Negative waits clamp to 0; NaN, infinite or past-2147483647 waits reject with
+ * `RangeError`.
+ * @param ms Milliseconds to wait.
+ * @param options `signal` to cancel the wait.
+ * @returns A promise that resolves to `undefined`.
+ * @example
+ * ```ts
+ * await sleep(100)
+ * const controller = new AbortController()
+ * const nap = sleep(1000, { signal: controller.signal })
+ * controller.abort()
+ * await nap.catch((reason) => console.log(reason)) // the abort reason
+ * ```
+ */
+export declare function sleep(ms: number, options?: SleepOptions): Promise<void>;
+/**
+ * Settles as `promise` does, or rejects with a `DOMException` named `TimeoutError` when `ms`
+ * milliseconds pass first, as `AbortSignal.timeout` does. An aborted `signal` rejects with its
+ * `reason`. The timer and the abort listener are removed once the result is known; `promise`
+ * itself keeps running, so pass the same `signal` to the work to stop it too.
+ * @param promise The promise to wait for.
+ * @param ms Milliseconds before it times out; checked as in {@link sleep}.
+ * @param options `signal` to cancel the wait.
+ * @returns A promise that settles with `promise`, or rejects on timeout or abort.
+ * @example
+ * ```ts
+ * const response = await timeout(fetch('/api'), 5000)
+ * ```
+ */
+export declare function timeout<T>(promise: PromiseLike<T> | T, ms: number, options?: TimeoutOptions): Promise<T>;