atomic-fns 1.1.7 → 2.0.0

package/dist/collections/lru-cache.js

@@ -0,0 +1,164 @@
+function refresh(state, entry) {
+    if (entry === state.newest)
+        return;
+    unlink(state, entry);
+    append(state, entry);
+}
+function unlink(state, entry) {
+    const { older, newer } = entry;
+    if (older === undefined)
+        state.oldest = newer;
+    else
+        older.newer = newer;
+    if (newer === undefined)
+        state.newest = older;
+    else
+        newer.older = older;
+    entry.older = undefined;
+    entry.newer = undefined;
+}
+function append(state, entry) {
+    entry.older = state.newest;
+    if (state.newest === undefined)
+        state.oldest = entry;
+    else
+        state.newest.newer = entry;
+    state.newest = entry;
+}
+function snapshot(state) {
+    const entries = [];
+    for (let entry = state.oldest; entry !== undefined; entry = entry.newer)
+        entries.push(entry);
+    return entries;
+}
+/**
+ * A fixed-capacity least-recently-used cache with `Map`'s method names. `get` refreshes recency;
+ * `has` does not. Keys compare with SameValueZero, as in `Map`. Iterators and `forEach` walk a
+ * snapshot taken when they start, so `get` and `set` inside a loop are safe.
+ *
+ * @example
+ * ```ts
+ * const cache = new LRUCache<string, number>(2)
+ * cache.set('a', 1).set('b', 2)
+ * cache.get('a') // 1, so 'b' is now the least recent
+ * cache.set('c', 3)
+ * cache.has('b') // false
+ * ```
+ */
+export class LRUCache {
+    /**
+     * Create an empty cache.
+     * @param capacity Maximum number of entries; must be an integer >= 1. Defaults to 1024.
+     * @throws {TypeError} when capacity is not a number.
+     * @throws {RangeError} when capacity is not an integer >= 1.
+     */
+    constructor(capacity = 1024) {
+        if (typeof capacity !== 'number')
+            throw new TypeError('capacity must be a number');
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError('capacity must be an integer >= 1');
+        }
+        const state = {
+            items: new Map(),
+            capacity,
+            oldest: undefined,
+            newest: undefined
+        };
+        Object.defineProperty(this, 'state', { value: state });
+    }
+    /**
+     * Set `key` to `value`. Setting an existing key updates its value and makes it the most recent,
+     * without evicting. Inserting a new key at capacity evicts the least recently used entry.
+     */
+    set(key, value) {
+        const { state } = this;
+        const entry = state.items.get(key);
+        if (entry !== undefined) {
+            entry.value = value;
+            refresh(state, entry);
+            return this;
+        }
+        const oldest = state.oldest;
+        if (oldest !== undefined && state.items.size >= state.capacity) {
+            unlink(state, oldest);
+            state.items.delete(oldest.key);
+        }
+        const added = { key, value, older: undefined, newer: undefined };
+        state.items.set(key, added);
+        append(state, added);
+        return this;
+    }
+    /** Whether `key` is cached. Does not refresh its recency. */
+    has(key) {
+        return this.state.items.has(key);
+    }
+    /**
+     * Return the value for `key`, refreshing its recency. Missing keys return `undefined`.
+     */
+    get(key) {
+        const { state } = this;
+        const entry = state.items.get(key);
+        if (entry === undefined)
+            return undefined;
+        refresh(state, entry);
+        return entry.value;
+    }
+    /** Remove every entry. */
+    clear() {
+        const { state } = this;
+        state.items.clear();
+        state.oldest = undefined;
+        state.newest = undefined;
+    }
+    /**
+     * Remove `key`.
+     * @returns Whether it was present.
+     */
+    delete(key) {
+        const { state } = this;
+        const entry = state.items.get(key);
+        if (entry === undefined)
+            return false;
+        unlink(state, entry);
+        return state.items.delete(key);
+    }
+    /** The number of entries. */
+    get size() {
+        return this.state.items.size;
+    }
+    /** Maximum number of entries. */
+    get capacity() {
+        return this.state.capacity;
+    }
+    /** `'LRUCache'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag]() {
+        return 'LRUCache';
+    }
+    /** The keys, least to most recently used. */
+    keys() {
+        return snapshot(this.state)
+            .map((entry) => entry.key)
+            .values();
+    }
+    /** The values, least to most recently used. */
+    values() {
+        return snapshot(this.state)
+            .map((entry) => entry.value)
+            .values();
+    }
+    /** `[key, value]` pairs, least to most recently used. */
+    entries() {
+        return snapshot(this.state)
+            .map((entry) => [entry.key, entry.value])
+            .values();
+    }
+    /** Call `callback(value, key, cache)` for each entry, least to most recently used. */
+    forEach(callback, thisArg) {
+        for (const [k, v] of this.entries())
+            Reflect.apply(callback, thisArg, [v, k, this]);
+    }
+    /** `[key, value]` pairs, least to most recently used. */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}

package/dist/collections/order.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The default key order of the key helpers.
+ */
+/** The two families of keys the default order compares: numbers with bigints, and strings. */
+export type KeyKind = 'number' | 'string';
+/**
+ * The family of a non-nil key.
+ * @throws {RangeError} for `NaN`.
+ * @throws {TypeError} for anything but a number, a bigint or a string.
+ */
+export declare function keyKind(x: unknown): KeyKind;
+/**
+ * Order two keys in `direction` (`1` ascending, `-1` descending): numbers and bigints by value
+ * (`<` is exact across the two), strings by UTF-16 code units as `<` does, and `null` /
+ * `undefined` after everything else in either direction.
+ * @throws {RangeError} for `NaN`.
+ * @throws {TypeError} for any other type, or a number against a string.
+ */
+export declare function compareKeys(a: unknown, b: unknown, direction?: 1 | -1): number;

package/dist/collections/order.js

@@ -0,0 +1,38 @@
+/**
+ * The default key order of the key helpers.
+ */
+import { isNil } from '../is/isNil.js';
+/**
+ * The family of a non-nil key.
+ * @throws {RangeError} for `NaN`.
+ * @throws {TypeError} for anything but a number, a bigint or a string.
+ */
+export function keyKind(x) {
+    if (typeof x === 'number') {
+        if (Number.isNaN(x))
+            throw new RangeError('NaN has no order; return another key');
+        return 'number';
+    }
+    if (typeof x === 'bigint')
+        return 'number';
+    if (typeof x === 'string')
+        return 'string';
+    throw new TypeError(`cannot order a ${typeof x} key; return a number, bigint or string`);
+}
+/**
+ * Order two keys in `direction` (`1` ascending, `-1` descending): numbers and bigints by value
+ * (`<` is exact across the two), strings by UTF-16 code units as `<` does, and `null` /
+ * `undefined` after everything else in either direction.
+ * @throws {RangeError} for `NaN`.
+ * @throws {TypeError} for any other type, or a number against a string.
+ */
+export function compareKeys(a, b, direction = 1) {
+    const aNil = isNil(a);
+    const bNil = isNil(b);
+    if (aNil || bNil)
+        return aNil === bNil ? 0 : aNil ? 1 : -1;
+    if (keyKind(a) !== keyKind(b))
+        throw new TypeError('cannot order a string key against a number key');
+    const ascending = a < b ? -1 : a > b ? 1 : 0;
+    return ascending * direction;
+}

package/dist/collections/shape.d.ts

@@ -0,0 +1,32 @@
+/** Any value the collection helpers accept: an object, a string, or `null` / `undefined` as empty. */
+export type Collection = object | string | null | undefined;
+/**
+ * The key a collection helper passes for `C`: an index for arrays, typed arrays, strings and other
+ * iterables, the map key for a `Map`, the value for a `Set`, and an own string key otherwise.
+ */
+export type CollectionKey<C> = C extends string ? number : C extends ReadonlyMap<infer K, unknown> ? K : C extends ReadonlySet<infer V> ? V : C extends Iterable<unknown> ? number : C extends object ? string : never;
+/**
+ * The value a collection helper passes for `C`: an element, a code point, a map value, a set
+ * member, or an own property value.
+ */
+export type CollectionValue<C> = C extends string ? string : C extends ReadonlyMap<unknown, infer V> ? V : C extends Iterable<infer V> ? V : C extends object ? [keyof C] extends [never] ? unknown : C[keyof C] : never;
+/** `(value, key, collection)`, as `Map.prototype.forEach` passes them. */
+export type CollectionCallback<C, R> = (value: CollectionValue<C>, key: CollectionKey<C>, collection: C) => R;
+/** A visitor of `(value, key)`; returning `true` stops the walk. */
+export type Visit = (value: unknown, key: unknown) => boolean | undefined | void;
+/**
+ * Visit the present elements of `arr` in index order until `visit` returns `true`; the cost
+ * follows the elements, not `length`. Returns whether it stopped early.
+ */
+export declare function eachIndex(arr: readonly unknown[], visit: Visit): boolean;
+/**
+ * Visit the entries of `collection` as `(value, key)`, by the shape rules of `fns/collection`,
+ * until `visit` returns `true`. Returns whether it stopped early. A number, boolean, bigint or
+ * symbol has no entries, as `Object.keys(5)` has none.
+ */
+export declare function eachEntry(collection: unknown, visit: Visit): boolean;
+/**
+ * Every `[key, value]` of `collection` in order, as `entries` lists them, for the helpers that
+ * walk from the end.
+ */
+export declare function entryList(collection: unknown): [key: unknown, value: unknown][];

package/dist/collections/shape.js

@@ -0,0 +1,86 @@
+import { isMap, isSet, typedArrayLength } from '../internal/kind.js';
+import { walkArray } from '../internal/sparse.js';
+const mapEntries = Map.prototype.entries;
+const setValues = Set.prototype.values;
+function isIterable(x) {
+    return typeof x[Symbol.iterator] === 'function';
+}
+/**
+ * Visit the present elements of `arr` in index order until `visit` returns `true`; the cost
+ * follows the elements, not `length`. Returns whether it stopped early.
+ */
+export function eachIndex(arr, visit) {
+    let stopped = false;
+    walkArray(arr, (event) => {
+        if (event.kind === 'value' && visit(event.value, event.index) === true) {
+            stopped = true;
+            return false;
+        }
+    });
+    return stopped;
+}
+/**
+ * Visit the entries of `collection` as `(value, key)`, by the shape rules of `fns/collection`,
+ * until `visit` returns `true`. Returns whether it stopped early. A number, boolean, bigint or
+ * symbol has no entries, as `Object.keys(5)` has none.
+ */
+export function eachEntry(collection, visit) {
+    if (collection === null || collection === undefined)
+        return false;
+    if (typeof collection === 'string') {
+        let i = 0;
+        for (const ch of collection)
+            if (visit(ch, i++) === true)
+                return true;
+        return false;
+    }
+    if (typeof collection !== 'object' && typeof collection !== 'function')
+        return false;
+    if (Array.isArray(collection))
+        return eachIndex(collection, visit);
+    const length = typedArrayLength(collection);
+    if (length !== undefined) {
+        const view = collection;
+        for (let i = 0; i < length; i++)
+            if (visit(view[i], i) === true)
+                return true;
+        return false;
+    }
+    if (isMap(collection)) {
+        for (const [key, value] of mapEntries.call(collection)) {
+            if (visit(value, key) === true)
+                return true;
+        }
+        return false;
+    }
+    if (isSet(collection)) {
+        for (const value of setValues.call(collection)) {
+            if (visit(value, value) === true)
+                return true;
+        }
+        return false;
+    }
+    if (isIterable(collection)) {
+        let i = 0;
+        for (const value of collection)
+            if (visit(value, i++) === true)
+                return true;
+        return false;
+    }
+    const record = collection;
+    for (const key of Object.keys(record))
+        if (visit(record[key], key) === true)
+            return true;
+    return false;
+}
+/**
+ * Every `[key, value]` of `collection` in order, as `entries` lists them, for the helpers that
+ * walk from the end.
+ */
+export function entryList(collection) {
+    const out = [];
+    eachEntry(collection, (value, key) => {
+        out.push([key, value]);
+    });
+    return out;
+}

package/dist/collections/sorted-map.d.ts

@@ -0,0 +1,171 @@
+import { type Comparator } from '../internal/compare.js';
+export declare let createSetMap: <T>(values?: Iterable<T> | null, compareFn?: Comparator<T> | null) => SortedMap<T, true>;
+export declare let insertIfAbsent: <K, V>(map: SortedMap<K, V>, key: K, value: V) => boolean;
+/**
+ * A map whose keys stay sorted, on a copy-on-write B+ tree with subtree counts. It has `Map`'s
+ * method names and iterates in key order, adds order queries (`firstKey`, `lastKey`, `lower`,
+ * `higher`, `floor`, `ceiling`), position queries (`at`, `rank`) and range operations
+ * (`entriesBetween`, `updateRange`, `removeRange`), and clones in O(1): a clone shares nodes with
+ * its source until either one writes. Keys the comparator calls equal are the
+ * same key, and a `-0` key is stored as `+0`, as `Map` does. With the default comparator, keys are
+ * numbers, bigints or strings: `NaN` throws `RangeError`, and `null`, `undefined` and other values
+ * throw `TypeError`; pass a comparator to order them.
+ *
+ * The comparator must be pure, return a finite number for every pair, and return 0 for a key
+ * compared with itself; every new key is checked, and a comparator that breaks these rules throws
+ * `TypeError` and leaves the map unchanged. Subtracting numbers fails for `Infinity` and `NaN`
+ * keys (`Infinity - x` is not finite); the default comparator handles every number but `NaN`.
+ *
+ * Under a strict total order, changing the map while iterating it never repeats a key: after a
+ * structural change the cursor re-seeks to the key after the last one it yielded. The walk ends
+ * unless the loop keeps inserting keys ahead of the cursor, as with `Map`.
+ *
+ * @example
+ * ```ts
+ * const scores = new SortedMap([
+ *   ['carol', 7],
+ *   ['alice', 9]
+ * ])
+ * scores.set('bob', 8)
+ * ;[...scores.keys()] // ['alice', 'bob', 'carol']
+ * scores.at(-1) // ['carol', 7]
+ * scores.rank('bob') // 1
+ * ```
+ */
+export declare class SortedMap<K = unknown, V = unknown> {
+    #private;
+    /**
+     * Create a map holding `entries`. Sorted input loads in linear time; when keys repeat, the last
+     * entry wins, as for `Map`.
+     * @param entries Initial `[key, value]` pairs. `null` means none, as for `Map`.
+     * @param compareFn Key comparator. Defaults to the primitive order (numbers, bigints and strings).
+     * @throws {TypeError} when `entries` is not iterable or holds something that is not an entry,
+     * or the comparator cannot order a key.
+     */
+    constructor(entries?: Iterable<readonly [K, V]> | null, compareFn?: ((a: K, b: K) => number) | null);
+    /** The number of entries. */
+    get size(): number;
+    /** `'SortedMap'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag](): string;
+    /** Remove every entry. */
+    clear(): void;
+    /** The value for `key`, or `undefined` when it is absent. O(log n). */
+    get(key: K): V | undefined;
+    /**
+     * Insert or replace `key`. Replacing also stores the new key object. O(log n).
+     * @returns `this`
+     * @throws {TypeError} when the comparator cannot order `key`; the map is unchanged.
+     */
+    set(key: K, value: V): this;
+    /** Whether `key` is present. O(log n). */
+    has(key: K): boolean;
+    /**
+     * Remove `key`. O(log n).
+     * @returns Whether it was present.
+     */
+    delete(key: K): boolean;
+    /**
+     * The entry at `index` in key order, with `Array.prototype.at` rules (negative counts from the
+     * end), or `undefined` out of range. O(log n), with no comparator calls.
+     */
+    at(index: number): [K, V] | undefined;
+    /**
+     * `[key, value]` pairs in ascending key order.
+     * @param lowestKey Start at the first key not below it. Omitted (or `undefined`) means the first
+     * key.
+     */
+    entries(lowestKey?: K): IteratorObject<[K, V]>;
+    /**
+     * `[key, value]` pairs in descending key order.
+     * @param highestKey Start at the last key not above it. Omitted (or `undefined`) means the last
+     * key.
+     */
+    entriesDescending(highestKey?: K): IteratorObject<[K, V]>;
+    /** The keys, in order. */
+    keys(): IteratorObject<K>;
+    /** The values, in key order. */
+    values(): IteratorObject<V>;
+    /** Call `callback(value, key, map)` for each entry, in key order. */
+    forEach(callback: (value: V, key: K, map: this) => void, thisArg?: unknown): void;
+    /** `[key, value]` pairs, in key order. */
+    [Symbol.iterator](): IteratorObject<[K, V]>;
+    /**
+     * How many keys sort before `key`: its index when present, else where it would go. O(log n).
+     * @throws {TypeError} when the comparator cannot order `key`.
+     */
+    rank(key: K): number;
+    /** The smallest key, or `undefined` when empty. */
+    firstKey(): K | undefined;
+    /** The largest key, or `undefined` when empty. */
+    lastKey(): K | undefined;
+    /** The entry with the least key above `key`, or `undefined`. */
+    higher(key: K): [K, V] | undefined;
+    /** The entry with the greatest key below `key`, or `undefined`. */
+    lower(key: K): [K, V] | undefined;
+    /** The entry with the least key at or above `key`, or `undefined`. */
+    ceiling(key: K): [K, V] | undefined;
+    /** The entry with the greatest key at or below `key`, or `undefined`. */
+    floor(key: K): [K, V] | undefined;
+    /**
+     * The entries whose keys lie in `[from, to)`, or `[from, to]` with `inclusiveEnd`, in key order.
+     * @param options `inclusiveEnd` includes `to` (default false); `limit` caps how many entries are
+     * collected (a non-negative integer or `Infinity`, the default).
+     * @throws {TypeError} when `limit` is not a number.
+     * @throws {RangeError} when `limit` is negative or not an integer.
+     * @example
+     * ```ts
+     * new SortedMap([[1, 'a'], [2, 'b'], [3, 'c']]).entriesBetween(1, 3) // [[1, 'a'], [2, 'b']]
+     * ```
+     */
+    entriesBetween(from: K, to: K, options?: {
+        inclusiveEnd?: boolean;
+        limit?: number;
+    }): [K, V][];
+    /**
+     * Visit the entries whose keys lie in `[from, to)`, or `[from, to]` with `inclusiveEnd`, in key
+     * order, and change them in one atomic step: if `update` or the comparator throws, the map is
+     * left as it was. `update(value, key, map)` returns `{ replace: value }`, `{ remove: true }`,
+     * either with `stop: true` to end after this entry, `{ stop: true }`, or `null`/`undefined` to
+     * leave the entry alone.
+     * @returns The number of entries visited.
+     * @throws {TypeError} when `update` returns a primitive, an object with none of `replace`,
+     * `remove` and `stop`, or both `replace` and a truthy `remove`.
+     * @example
+     * ```ts
+     * const stock = new SortedMap([['apple', 3], ['pear', 0]])
+     * stock.updateRange('a', 'z', (n) => (n === 0 ? { remove: true } : { replace: n - 1 }))
+     * ;[...stock] // [['apple', 2]]
+     * ```
+     */
+    updateRange(from: K, to: K, update: (value: V, key: K, map: this) => {
+        replace: V;
+        stop?: true;
+    } | {
+        remove: true;
+        stop?: true;
+    } | {
+        stop: true;
+    } | null | undefined, options?: {
+        inclusiveEnd?: boolean;
+    }): number;
+    /**
+     * Remove the entries whose keys lie in `[from, to)`, or `[from, to]` with `inclusiveEnd`, in one
+     * atomic step: a comparator that throws leaves the map unchanged.
+     * @returns The number of entries removed.
+     * @example
+     * ```ts
+     * const log = new SortedMap([[1, 'a'], [5, 'b'], [9, 'c']])
+     * log.removeRange(0, 5, { inclusiveEnd: true }) // 2
+     * ```
+     */
+    removeRange(from: K, to: K, options?: {
+        inclusiveEnd?: boolean;
+    }): number;
+    /**
+     * A copy in O(1): the two maps share nodes until either one writes, which copies only the path
+     * it changes. The copy keeps the class and comparator.
+     * @throws {TypeError} when a subclass constructor does not pass `(entries, compareFn)`
+     * on to `SortedMap`.
+     */
+    clone(): this;
+}