atomic-fns 1.2.0 → 2.0.0

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>;

package/dist/async/sleep.js

@@ -0,0 +1,76 @@
+import { timerWait } from '../internal/timer.js';
+/**
+ * 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 function sleep(ms, options) {
+    return new Promise((resolve, reject) => {
+        const delay = timerWait(ms, 'ms');
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, delay);
+    });
+}
+/**
+ * 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 function timeout(promise, ms, options) {
+    return new Promise((resolve, reject) => {
+        const signal = options?.signal;
+        let timer;
+        const settle = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const onAbort = () => {
+            settle();
+            reject(signal?.reason);
+        };
+        // Subscribe before any early exit so a later rejection of `promise` is always handled.
+        Promise.resolve(promise).finally(settle).then(resolve, reject);
+        const delay = timerWait(ms, 'ms');
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => {
+            settle();
+            reject(new DOMException('The operation timed out.', 'TimeoutError'));
+        }, delay);
+    });
+}

package/dist/collections/bisect.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The leftmost index at which `value` can be inserted into the sorted `array` and keep it sorted:
+ * before any elements equal to it, as Python's `bisect_left`.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to locate.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order (numbers,
+ * bigints and strings).
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * bisectLeft([1, 2, 2, 3], 2) // 1
+ * ```
+ */
+export declare function bisectLeft<T>(array: ArrayLike<T>, value: T, compareFn?: (a: T, b: T) => number, lo?: number, hi?: number): number;
+/**
+ * The rightmost index at which `value` can be inserted into the sorted `array` and keep it sorted:
+ * after any elements equal to it, as Python's `bisect_right`. Also exported as `bisect`, Python's
+ * short name.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to locate.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order (numbers,
+ * bigints and strings).
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * bisectRight([1, 2, 2, 3], 2) // 3
+ * bisect(['a', 'c'], 'b') // 1
+ * ```
+ */
+export declare function bisectRight<T>(array: ArrayLike<T>, value: T, compareFn?: (a: T, b: T) => number, lo?: number, hi?: number): number;
+export { bisectRight as bisect };
+/**
+ * Insert `value` into the sorted `array` after any equal elements, keeping it sorted, and return
+ * the array.
+ *
+ * @param array A sorted array; changed in place.
+ * @param value The value to insert.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo` or `hi` is not an integer (`hi` may also be ±Infinity).
+ * @throws {RangeError} when `lo` is negative or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * insort([1, 3], 2) // [1, 2, 3]
+ * ```
+ */
+export declare function insort<T>(array: T[], value: T, compareFn?: (a: T, b: T) => number, lo?: number, hi?: number): T[];
+/**
+ * Insert `value` into the sorted `array` before any equal elements, keeping it sorted, and return
+ * the array.
+ *
+ * @param array A sorted array; changed in place.
+ * @param value The value to insert.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo` or `hi` is not an integer (`hi` may also be ±Infinity).
+ * @throws {RangeError} when `lo` is negative or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * insortLeft([1, 3], 2) // [1, 2, 3]
+ * ```
+ */
+export declare function insortLeft<T>(array: T[], value: T, compareFn?: (a: T, b: T) => number, lo?: number, hi?: number): T[];
+/**
+ * The index of `value` in the sorted `array`, or `-(insertion index) - 1` when it is absent, so a
+ * negative result `r` means `value` belongs at `-r - 1`.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to find.
+ * @param compareFn Comparator the array is sorted by; 0 means found. Defaults to the primitive
+ * order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * binarySearch([1, 3, 5], 3) // 1
+ * binarySearch([1, 3, 5], 4) // -3
+ * ```
+ */
+export declare function binarySearch<T>(array: ArrayLike<T>, value: T, compareFn?: (a: T, b: T) => number, lo?: number, hi?: number): number;

package/dist/collections/bisect.js

@@ -0,0 +1,157 @@
+import { defaultCompare } from '../internal/compare.js';
+import { assertNotHugeSparse } from './internal/arrayKeys.js';
+/**
+ * Check the search bounds and return the exclusive end of the search: `hi` clamped to the length
+ * of `array`, or the length when `hi` is omitted. `lo` is checked first, as Python does.
+ */
+function searchBounds(array, lo, hi) {
+    if (!Number.isInteger(lo))
+        throw new TypeError('lo must be an integer');
+    if (lo < 0)
+        throw new RangeError('lo must be non-negative');
+    const length = array.length;
+    if (!Number.isInteger(length))
+        throw new TypeError('array length must be an integer');
+    if (length < 0 || length > Number.MAX_SAFE_INTEGER) {
+        throw new RangeError('array length must be a non-negative safe integer');
+    }
+    if (hi === undefined)
+        return length;
+    if (!Number.isInteger(hi) && hi !== Infinity && hi !== -Infinity) {
+        throw new TypeError('hi must be an integer');
+    }
+    return Math.min(hi, length);
+}
+/** Binary search over `[lo, end)`, with bounds already checked by {@link searchBounds}. */
+function search(array, value, compareFn, lo, end, right) {
+    while (lo < end) {
+        const mid = lo + Math.floor((end - lo) / 2);
+        const goRight = right ? compareFn(value, array[mid]) >= 0 : compareFn(array[mid], value) < 0;
+        if (goRight)
+            lo = mid + 1;
+        else
+            end = mid;
+    }
+    return lo;
+}
+/**
+ * The leftmost index at which `value` can be inserted into the sorted `array` and keep it sorted:
+ * before any elements equal to it, as Python's `bisect_left`.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to locate.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order (numbers,
+ * bigints and strings).
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * bisectLeft([1, 2, 2, 3], 2) // 1
+ * ```
+ */
+export function bisectLeft(array, value, compareFn = defaultCompare, lo = 0, hi) {
+    return search(array, value, compareFn, lo, searchBounds(array, lo, hi), false);
+}
+/**
+ * The rightmost index at which `value` can be inserted into the sorted `array` and keep it sorted:
+ * after any elements equal to it, as Python's `bisect_right`. Also exported as `bisect`, Python's
+ * short name.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to locate.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order (numbers,
+ * bigints and strings).
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * bisectRight([1, 2, 2, 3], 2) // 3
+ * bisect(['a', 'c'], 'b') // 1
+ * ```
+ */
+export function bisectRight(array, value, compareFn = defaultCompare, lo = 0, hi) {
+    return search(array, value, compareFn, lo, searchBounds(array, lo, hi), true);
+}
+export { bisectRight as bisect };
+/**
+ * Insert `value` into the sorted `array` after any equal elements, keeping it sorted, and return
+ * the array.
+ *
+ * @param array A sorted array; changed in place.
+ * @param value The value to insert.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo` or `hi` is not an integer (`hi` may also be ±Infinity).
+ * @throws {RangeError} when `lo` is negative or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * insort([1, 3], 2) // [1, 2, 3]
+ * ```
+ */
+export function insort(array, value, compareFn = defaultCompare, lo = 0, hi) {
+    const end = searchBounds(array, lo, hi);
+    assertNotHugeSparse(array);
+    array.splice(search(array, value, compareFn, lo, end, true), 0, value);
+    return array;
+}
+/**
+ * Insert `value` into the sorted `array` before any equal elements, keeping it sorted, and return
+ * the array.
+ *
+ * @param array A sorted array; changed in place.
+ * @param value The value to insert.
+ * @param compareFn Comparator the array is sorted by. Defaults to the primitive order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo` or `hi` is not an integer (`hi` may also be ±Infinity).
+ * @throws {RangeError} when `lo` is negative or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * insortLeft([1, 3], 2) // [1, 2, 3]
+ * ```
+ */
+export function insortLeft(array, value, compareFn = defaultCompare, lo = 0, hi) {
+    const end = searchBounds(array, lo, hi);
+    assertNotHugeSparse(array);
+    array.splice(search(array, value, compareFn, lo, end, false), 0, value);
+    return array;
+}
+/**
+ * The index of `value` in the sorted `array`, or `-(insertion index) - 1` when it is absent, so a
+ * negative result `r` means `value` belongs at `-r - 1`.
+ *
+ * @param array A sorted array or array-like.
+ * @param value The value to find.
+ * @param compareFn Comparator the array is sorted by; 0 means found. Defaults to the primitive
+ * order.
+ * @param lo First index to search, a non-negative integer. Defaults to 0.
+ * @param hi End of the search (exclusive): an integer or ±Infinity, clamped to the length.
+ * Defaults to the length.
+ * @throws {TypeError} when `lo`, `hi` or the length of `array` is not an integer (`hi` may also be
+ * ±Infinity).
+ * @throws {RangeError} when `lo` is negative or the length of `array` is not a non-negative safe
+ * integer.
+ * @example
+ * ```ts
+ * binarySearch([1, 3, 5], 3) // 1
+ * binarySearch([1, 3, 5], 4) // -3
+ * ```
+ */
+export function binarySearch(array, value, compareFn = defaultCompare, lo = 0, hi) {
+    const end = searchBounds(array, lo, hi);
+    const i = search(array, value, compareFn, lo, end, false);
+    return i < end && compareFn(array[i], value) === 0 ? i : -i - 1;
+}

package/dist/collections/deque.d.ts

@@ -1,117 +1,87 @@
-import type { Iteratee } from '../types.js';
-import { Sequence } from './abc.js';
 /**
- * Fixed capacity double-ended queue implemented as ring deque.
- * @template T
+ * A double-ended queue on a ring buffer, with Array's method names: `push` and `pop` at the end,
+ * `unshift` and `shift` at the front, `at` and `set` by index, all O(1) amortized. It grows by
+ * doubling when unbounded; with `maxlen` it evicts from the opposite end, as Python's `deque` does.
+ * `includes` uses SameValueZero.
+ *
+ * @example
+ * ```ts
+ * const recent = new Deque<number>([], { maxlen: 3 })
+ * recent.push(1, 2, 3, 4)
+ * ;[...recent] // [2, 3, 4]
+ * recent.shift() // 2
+ * ```
  */
-export declare class Deque<T = any> extends Sequence<T> {
-    items: T[];
-    start: number;
-    count: number;
-    capacity: number;
-    ArrayConstructor: any;
-    /**
-     * Creates a new `Deque` instance of a fixed size.
-     * @param {Array} [arrType = []] The initial elements or array type to use (accepts any kind of typed array).
-     * @param {number} [capacity=1024] The fixed size of the deque. Defaults to `1024`.
-     */
-    constructor(arrType?: T[], capacity?: number);
-    /** Returns the total number of elements in the deque. */
+export declare class Deque<T> {
+    #private;
+    /**
+     * Create a deque holding `items`, in order.
+     * @param items Initial elements, read one at a time. When longer than `maxlen`, only the last
+     * `maxlen` remain.
+     * @param options.maxlen Maximum size; overflow evicts from the opposite end. `0` makes push/unshift
+     * no-ops. `null`, `undefined` and `Infinity` mean unbounded.
+     * @param options.arrType Typed-array (or similar) constructor used for storage.
+     * @throws {TypeError} when `items` is not iterable, or `maxlen` is not a number, `null` or
+     * `undefined`.
+     * @throws {RangeError} when `maxlen` is negative, not an integer, or above
+     * `Number.MAX_SAFE_INTEGER`, or when `items` is a huge sparse array.
+     */
+    constructor(items?: Iterable<T> | null, options?: {
+        maxlen?: number | null;
+        arrType?: new (n: number) => {
+            [i: number]: T;
+            length: number;
+        };
+    });
+    /** The number of elements. */
     get size(): number;
     /**
-     * Method used to clear the structure.
+     * Maximum size when constructed with a finite `maxlen`, otherwise `undefined`.
      */
+    get maxlen(): number | undefined;
+    /** `'Deque'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag](): string;
+    /** Remove every element and give back the buffer a burst grew. */
     clear(): void;
     /**
-     * Alias of {@link Deque.append}
-     * @param {T} item Item to append.
-     * @returns {number} Returns the new size of the deque.
-     */
-    add(item: any): number;
-    /**
-     * Appends a new element to the end of the deque.
-     * @param {T} item Item to append.
-     * @returns {number} Returns the new size of the deque.
+     * Append one or more elements at the end.
+     * @returns The new size.
      */
-    append(item: any): number;
+    push(...xs: T[]): number;
     /**
-     * Appends a new element to the beginning of the deque.
-     * @param {T} item Item to prepend.
-     * @returns {number} Returns the new size of the deque.
+     * Insert one or more elements at the front, preserving argument order.
+     * @returns The new size.
      */
-    appendleft(item: any): number;
+    unshift(...xs: T[]): number;
     /**
-     * Removes and returns the element at the end of the deque.
-     * @returns {?T} Returns the popped item.
+     * Remove and return the last element, or `undefined` when empty.
      */
     pop(): T | undefined;
     /**
-     * Alias of {@link Deque.pop}
-     * @returns {?T} Returns the popped item.
-     */
-    remove(): T | undefined;
-    /**
-     * Removes and returns the element at the beginning of the deque.
-     * @returns {?T} Returns the removed deque element.
-     */
-    popleft(): T | undefined;
-    /**
-     * Returns the element at the beginning of the deque.
-     * @returns {?T} The element if exists
-     */
-    first(): T | undefined;
-    /**
-     * Returns the element at a specified index position in the deque.
-     * @param {number} index The given index
-     * @returns {?T} The element if exists
-     */
-    get(index: any): T | undefined;
-    /**
-     * Update the element at a given `index`.
-     * @param {number} index The given index
-     */
-    set(index: number, value: T): void;
-    /**
-     * Check if a given element is in the deque.
-     * @param {T} x The value to find
-     * @returns {boolean} `true` if the value is found
-     */
-    contains(x: any): boolean;
-    /**
-     * Returns the first element that matches the `iteratee` function.
-     * @param {Iteratee<T>} iteratee A function that will be invoked per element
-     * @returns {?T} The element if exists
-     */
-    find(iteratee: Iteratee<T>): T | undefined;
-    /**
-     * Calls `iteratee` function for every element in the deque.
-     * @param {Iteratee<T>} iteratee A function that will be invoked per element
-     */
-    forEach(iteratee: any): void;
-    /**
-     * Returns a new array with all the elements in reverse order.
-     * @returns {Array<T>} The elements reversed
-     */
-    reversed(): T[];
-    /**
-     * Returns a new array with all the elements in the order they were added to the deque.
-     * @returns {Array<T>} The elements array
-     */
-    toArray(): T[];
-    /**
-     * Returns an iterator over the deque's values.
-     * @returns {Iterator}
+     * Remove and return the first element, or `undefined` when empty.
      */
-    values(): Iterable<T>;
+    shift(): T | undefined;
     /**
-     * Alias of {@link Deque.values}. Returns iterator of values.
+     * Element at index `i` (negative from the end). Out of range or empty -> `undefined`.
+     * The index coerces as in `Array.prototype.at`; values that coerce to `NaN` mean `0`.
      */
-    keys(): Iterable<T>;
+    at(i: number): T | undefined;
     /**
-     * Creates an iterator of `[index, value]` pairs for all elements in the deque.
-     * @returns {Iterator}
+     * Replace the element at index `i` (negative from the end). The index coerces as in {@link at}.
+     * @returns `this`
+     * @throws {RangeError} when the index is out of range.
      */
-    entries(): Iterable<[number, T]>;
-    [Symbol.iterator](): Iterable<T>;
-    inspect(): T[];
+    set(i: number, v: T): this;
+    /** Whether `value` is present (SameValueZero). */
+    includes(value: T): boolean;
+    /** Call `callback(element, index, deque)` for each element, front to back. */
+    forEach(callback: (value: T, index: number, deque: this) => void, thisArg?: unknown): void;
+    /** The indices, front to back, as `Array.prototype.keys` gives them. */
+    keys(): Generator<number>;
+    /** The elements, front to back. */
+    values(): Generator<T>;
+    /** `[index, element]` pairs, front to back. */
+    entries(): Generator<[number, T]>;
+    /** The elements, front to back. */
+    [Symbol.iterator](): Generator<T>;
 }