atomic-fns 1.1.6 → 1.2.0

package/dist/collections/LRUCache.d.ts

@@ -6,6 +6,7 @@ import { Mapping } from './abc.js';
 export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
     protected items: Map<K, V>;
     protected maxSize: number;
+    private eviction;
     /**
      * Creates a new instance of fixed size.
      * @param {number} capacity
@@ -18,6 +19,8 @@ export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
      * @returns {this}
      */
     set(key: K, value: V): this;
+    /** An idle Map iterator pins every hash table the Map has outgrown, so it cannot live forever. */
+    private wrote;
     /**
      * This is just an alias of {@link LRUCache.set}.
      * @param {K} key The key to add (note value will be `undefined`)
@@ -35,7 +38,7 @@ export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
      * @param {K} key
      * @returns {?V} The associated value or `undefined`
      */
-    get(key: K): V;
+    get(key: K): V | undefined;
     /**
      * Removes all keys and values from the cache.
      * @returns {this}
@@ -52,7 +55,7 @@ export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
      * @param {K} key
      * @returns {?V} The value if it was removed or `undefined`.
      */
-    remove(key: K): V;
+    remove(key: K): V | undefined;
     /**
      * Returns the total number of elements in the cache.
      */
@@ -62,17 +65,17 @@ export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
      */
     get capacity(): number;
     /**
-     * Returns an iterable of all the keys in the cache, in insertion order.
+     * Returns an iterable of all the keys in the cache, from least to most recently used.
      * @returns {IterableIterator<K>}
      */
     keys(): IterableIterator<K>;
     /**
-     * Returns an iterable of all the values in the cache, in insertion order.
+     * Returns an iterable of all the values in the cache, from least to most recently used.
      * @returns {IterableIterator<V>}
      */
     values(): IterableIterator<V>;
     /**
-     * Returns an iterable of all the [key, value] pairs in the cache, in insertion order.
+     * Returns an iterable of all the [key, value] pairs in the cache, from least to most recently used.
      * @returns {IterableIterator<[K, V]>}
      */
     entries(): IterableIterator<[K, V]>;

package/dist/collections/LRUCache.js

@@ -13,6 +13,8 @@ export class LRUCache extends Mapping {
     constructor(capacity = 1024) {
         super();
         this.maxSize = capacity;
+        // Not enumerable, so two caches compare by their items
+        Object.defineProperty(this, 'eviction', { value: { keys: this.items.keys(), writes: 0 } });
     }
     /**
      * Adds a new element with a specified `key` and `value` to the cache. If an element with the same key already exists, the element will be updated.
@@ -21,16 +23,25 @@ export class LRUCache extends Mapping {
      * @returns {this}
      */
     set(key, value) {
-        if (this.items.size === this.maxSize) {
-            // Because ES6 maps remember insertion order, we can evict the first key
-            const lastKey = this.items.keys().next().value;
-            this.items.delete(lastKey);
-        }
         // Delete the previous key to update the new insertion order
         this.items.delete(key);
         this.items.set(key, value);
+        this.wrote();
+        if (this.items.size > this.maxSize) {
+            // Because ES6 maps remember insertion order, we can evict the first key
+            const lastKey = this.eviction.keys.next().value;
+            this.items.delete(lastKey);
+        }
         return this;
     }
+    /** An idle Map iterator pins every hash table the Map has outgrown, so it cannot live forever. */
+    wrote() {
+        const { eviction } = this;
+        if (++eviction.writes >= this.items.size) {
+            eviction.writes = 0;
+            eviction.keys = this.items.keys();
+        }
+    }
     /**
      * This is just an alias of {@link LRUCache.set}.
      * @param {K} key The key to add (note value will be `undefined`)
@@ -58,6 +69,7 @@ export class LRUCache extends Mapping {
             // Delete the previous key to update the new insertion order
             this.items.delete(key);
             this.items.set(key, value);
+            this.wrote();
             return value;
         }
     }
@@ -100,25 +112,26 @@ export class LRUCache extends Mapping {
         return this.maxSize;
     }
     /**
-     * Returns an iterable of all the keys in the cache, in insertion order.
+     * Returns an iterable of all the keys in the cache, from least to most recently used.
      * @returns {IterableIterator<K>}
      */
     keys() {
-        return this.items.keys();
+        // A snapshot: get and set re-insert keys, so a live Map iterator would never reach the end
+        return [...this.items.keys()].values();
     }
     /**
-     * Returns an iterable of all the values in the cache, in insertion order.
+     * Returns an iterable of all the values in the cache, from least to most recently used.
      * @returns {IterableIterator<V>}
      */
     values() {
-        return this.items.values();
+        return [...this.items.values()].values();
     }
     /**
-     * Returns an iterable of all the [key, value] pairs in the cache, in insertion order.
+     * Returns an iterable of all the [key, value] pairs in the cache, from least to most recently used.
      * @returns {IterableIterator<[K, V]>}
      */
     entries() {
-        return this.items.entries();
+        return [...this.items.entries()].values();
     }
     [Symbol.iterator]() {
         return this.entries();

package/dist/collections/SortedMap.d.ts

@@ -24,24 +24,24 @@ export declare class SortedMap<K, V> extends Mapping<K, V> {
      * @param {K} key
      * @returns {?V} The key value or `undefined`.
      */
-    get(key: K): any;
+    get(key: K): V | undefined;
     /**
      * Sets the value for the given `key`.
      * @param {K} key
      * @param {V} value
      * @returns {this} Returns the Map object.
      */
-    set(key: K, value: V): void;
+    set(key: K, value: V): this;
     /**
      * Returns the smallest key in the tree.
      * @returns {?K}
      */
-    min(): K;
+    min(): K | undefined;
     /**
      * Returns the largest key in the tree.
      * @returns {?K}
      */
-    max(): K;
+    max(): K | undefined;
     /**
      * Returns `true` if the `key` existed in the map and was removed.
      * @param {K} key

package/dist/collections/SortedMap.js

@@ -28,7 +28,7 @@ export class SortedMap extends Mapping {
      * @returns {this} Returns the Map object.
      */
     add(key) {
-        this.store.set(key, null);
+        this.store.add(key);
         return this;
     }
     /**
@@ -46,7 +46,8 @@ export class SortedMap extends Mapping {
      * @returns {this} Returns the Map object.
      */
     set(key, value) {
-        return this.store.set(key, value);
+        this.store.set(key, value);
+        return this;
     }
     /**
      * Returns the smallest key in the tree.
@@ -68,7 +69,7 @@ export class SortedMap extends Mapping {
      * @returns {boolean} `true` if key was removed, otherwise `false`.
      */
     delete(item) {
-        return this.store.remove(item) !== undefined;
+        return this.store.delete(item);
     }
     /**
      * Removes all key/value pairs in the tree.

package/dist/collections/SortedSet.d.ts

@@ -23,12 +23,12 @@ export declare class SortedSet<T> extends Collection {
      * Returns the smallest value in the set.
      * @returns {?T}
      */
-    min(): T;
+    min(): T | undefined;
     /**
      * Returns the largest value in the set.
      * @returns {?T}
      */
-    max(): T;
+    max(): T | undefined;
     /**
      * Removes the value from the set and returns `true` if the value was found and removed.
      * @param {T} value

package/dist/collections/SortedTree.d.ts

@@ -1,4 +1,4 @@
-import { Comparer } from '../operators/index.js';
+import type { Comparer } from '../operators/index.js';
 import { Mapping } from './abc.js';
 /**
  * A `SortedTree` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
@@ -15,7 +15,7 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
      */
     constructor(iterable?: Iterable<[K, V]>, compareFn?: Comparer);
     /**
-     * Adds a new `key` with a `null` value.
+     * Adds a new `key` with a `null` value, if the `key` doesn't exist.
      * @param {K} key
      * @returns {this} Returns the Tree object.
      */
@@ -25,7 +25,7 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
      * @param {K} key
      * @returns {?V} The key value or `undefined`.
      */
-    get(key: K): V;
+    get(key: K): V | undefined;
     /**
      * Sets the value for the given `key`.
      * @param {K} key
@@ -37,12 +37,12 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
      * Returns the smallest key in the tree.
      * @returns {?K}
      */
-    min(): K;
+    min(): K | undefined;
     /**
      * Returns the largest key in the tree.
      * @returns {?K}
      */
-    max(): K;
+    max(): K | undefined;
     /**
      * Returns `true` if the `key` existed in the tree and was removed.
      * @param {K} key
@@ -60,7 +60,7 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
     freeze(): this;
     /**
      * Returns a new iterator of `[K, V]` pairs in reverse order of keys.
-     * @returns {Iterable<[K, V]>}
+     * @returns {IterableIterator<[K, V]>}
      */
     reversed(): IterableIterator<[K, V]>;
     /**
@@ -87,17 +87,17 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
     has(key: K): boolean;
     /**
      * Returns a new iterator of all **ordered** keys in the tree.
-     * @returns {Iterable<K>}
+     * @returns {IterableIterator<K>}
      */
     keys(): IterableIterator<K>;
     /**
      * Returns a new iterator of all values **ordered** by their keys.
-     * @returns {Iterable<V>}
+     * @returns {IterableIterator<V>}
      */
     values(): IterableIterator<V>;
     /**
      * Returns a new iterator of all key value pairs **ordered** by their keys.
-     * @returns {Iterable<[K, V]>}
+     * @returns {IterableIterator<[K, V]>}
      */
     entries(): IterableIterator<[K, V]>;
 }

package/dist/collections/SortedTree.js

@@ -18,12 +18,13 @@ export class SortedTree extends Mapping {
         this.store = new BTree(iterable, compareFn);
     }
     /**
-     * Adds a new `key` with a `null` value.
+     * Adds a new `key` with a `null` value, if the `key` doesn't exist.
      * @param {K} key
      * @returns {this} Returns the Tree object.
      */
     add(key) {
-        this.store.set(key, null);
+        if (!this.store.contains(key))
+            this.store.set(key, null);
         return this;
     }
     /**
@@ -82,7 +83,7 @@ export class SortedTree extends Mapping {
     }
     /**
      * Returns a new iterator of `[K, V]` pairs in reverse order of keys.
-     * @returns {Iterable<[K, V]>}
+     * @returns {IterableIterator<[K, V]>}
      */
     reversed() {
         return this.store.reversed();
@@ -119,21 +120,21 @@ export class SortedTree extends Mapping {
     }
     /**
      * Returns a new iterator of all **ordered** keys in the tree.
-     * @returns {Iterable<K>}
+     * @returns {IterableIterator<K>}
      */
     keys() {
         return this.store.keys();
     }
     /**
      * Returns a new iterator of all values **ordered** by their keys.
-     * @returns {Iterable<V>}
+     * @returns {IterableIterator<V>}
      */
     values() {
         return this.store.values();
     }
     /**
      * Returns a new iterator of all key value pairs **ordered** by their keys.
-     * @returns {Iterable<[K, V]>}
+     * @returns {IterableIterator<[K, V]>}
      */
     entries() {
         return this.store.entries();

package/dist/collections/SplayTree.d.ts

@@ -1,4 +1,4 @@
-import { Comparer } from '../operators/index.js';
+import { type Comparer } from '../operators/index.js';
 import { Mapping } from './abc.js';
 /**
  * Base SplayTree node class.
@@ -10,7 +10,7 @@ declare class Node<K = any, V = any> {
     left?: Node<K, V>;
     right?: Node<K, V>;
     constructor(key: K, value: V);
-    get height(): any;
+    get height(): number;
 }
 /**
  * A splay tree is a *self-balancing binary* search tree with the additional property that recently accessed elements are quick to access again.
@@ -31,45 +31,47 @@ export declare class SplayTree<K, V = any> extends Mapping<K, V> {
      * @param p When an element is accessed, with probability `p` splay the tree. With probability `1 - p`, leave the tree as it is.
      */
     constructor(compareFn?: any, p?: number);
-    top(): K;
+    top(): K | undefined;
     get size(): number;
     empty(): boolean;
-    get height(): any;
+    get height(): number;
     /**
      *  Returns the value for `key` or `undefined` if the key is not found.
      * @param key The key to find.
      * @returns {?V} The value for the key or `undefined`.
      */
-    get(key: K): any;
+    get(key: K): V | undefined;
+    private findNode;
     /**
-     * Inserts the `key` and `value` in the tree if the `key` does not exist.
+     * Inserts the `key` and `value` in the tree, or updates the value if the `key` exists.
      * @param {K} key A key which can be any comparable value
      * @param {V} value A value associated with the key
      * @returns
      */
     set(key: K, value: V): void;
+    private insert;
     /**
      * Removes a specified key if it exists in the tree. The removed value is returned or `undefined` if not found.
      * @param {K} key The key to remove.
-     * @returns {V} The removed value associated with `key`.
+     * @returns {?V} The removed value associated with `key`.
      */
-    remove(key: K): V;
+    remove(key: K): V | undefined;
     /**
      * Returns the minimum key in the tree or subtree.
      * @returns The minimum key.
      */
-    min(root?: Node<K, V>): K;
+    min(root?: Node<K, V>): K | undefined;
     /**
      * Returns the maximum key in the tree or subtree.
      * @returns The maximum key.
      */
-    max(root?: Node<K, V>): K;
+    max(root?: Node<K, V>): K | undefined;
     /**
      * Returns the largest key that is less than a given key.
      * @param key The given key
-     * @returns The largest key found or `undefined`.
+     * @returns {?K} The largest key found or `undefined`.
      */
-    lowerBound(key: any): K | Node<K, V>;
+    lowerBound(key: any): K | undefined;
     /**
      * This is the simplified top-down splaying method proposed by Sleator and Tarjan in {@link https://doi.org/10.1145%2F3828.3835 Self-Adjusting Binary Search Trees}.
      * @param key
@@ -83,7 +85,7 @@ export declare class SplayTree<K, V = any> extends Mapping<K, V> {
      * @returns `true` if found.
      */
     contains(key: K): boolean;
-    /** Alias of remove but just returns `true` instead of the deleted value. */
+    /** Alias of remove but returns `true` if the key was found instead of the deleted value. */
     delete(key: K): boolean;
     clear(): void;
     /**
@@ -97,8 +99,8 @@ export declare class SplayTree<K, V = any> extends Mapping<K, V> {
      */
     entries(): Iterable<[K, V]>;
     /**
-     * Returns an ordered iterable of all the keys and values in the tree.
-     * @returns {Iterable<V>} A iterable of `[key, value]` pairs sorted by key.
+     * Returns an ordered iterable of all the values in the tree.
+     * @returns {Iterable<V>} An iterable of values sorted by key.
      */
     values(): Iterable<V>;
 }

package/dist/collections/SplayTree.js

@@ -1,4 +1,4 @@
-import { compare, eq } from '../operators/index.js';
+import { compare } from '../operators/index.js';
 import { Mapping } from './abc.js';
 /**
  * Base SplayTree node class.
@@ -14,22 +14,29 @@ class Node {
         this.value = value;
     }
     get height() {
-        if (this.left && this.right)
-            return 1 + Math.max(this.right.height, this.left.height);
-        if (this.right)
-            return 1 + this.right.height;
-        if (this.left)
-            return 1 + this.left.height;
-        return 0;
+        let height = -1;
+        let level = [this];
+        while (level.length) {
+            height += 1;
+            level = level.flatMap((node) => [node.left, node.right].filter(Boolean));
+        }
+        return height;
     }
 }
-// In-order traversal of a tree
-function* traverse(node) {
-    while (node) {
-        yield* traverse(node.left);
-        yield node;
+// In-order snapshot of a tree: reads splay it, so a live walk would lose its place
+function traverse(node) {
+    const nodes = [];
+    const stack = [];
+    while (node || stack.length) {
+        while (node) {
+            stack.push(node);
+            node = node.left;
+        }
+        node = stack.pop();
+        nodes.push(node);
         node = node.right;
     }
+    return nodes;
 }
 /**
  * A splay tree is a *self-balancing binary* search tree with the additional property that recently accessed elements are quick to access again.
@@ -75,6 +82,9 @@ export class SplayTree extends Mapping {
      * @returns {?V} The value for the key or `undefined`.
      */
     get(key) {
+        return this.findNode(key)?.value;
+    }
+    findNode(key) {
         if (!this.root)
             return;
         // Note: deterministic splaying (always moves key to front):
@@ -86,7 +96,7 @@ export class SplayTree extends Mapping {
         if (Math.random() <= this.randSplay) {
             this.splay(key);
             if (this.cmp(key, this.root.key) === 0)
-                return this.root.value;
+                return this.root;
             else
                 return undefined;
         }
@@ -95,7 +105,7 @@ export class SplayTree extends Mapping {
         while (current) {
             const rank = this.cmp(key, current.key);
             if (rank === 0)
-                return current.value;
+                return current;
             if (rank < 0)
                 current = current.left;
             else
@@ -103,12 +113,15 @@ export class SplayTree extends Mapping {
         }
     }
     /**
-     * Inserts the `key` and `value` in the tree if the `key` does not exist.
+     * Inserts the `key` and `value` in the tree, or updates the value if the `key` exists.
      * @param {K} key A key which can be any comparable value
      * @param {V} value A value associated with the key
      * @returns
      */
     set(key, value) {
+        this.insert(key, value, true);
+    }
+    insert(key, value, overwrite) {
         if (!this.root) {
             this.root = new Node(key, value);
             this.count += 1;
@@ -120,7 +133,8 @@ export class SplayTree extends Mapping {
         const rank = this.cmp(key, this.root.key);
         if (rank === 0) {
             // Update the value
-            this.root.value = value;
+            if (overwrite)
+                this.root.value = value;
             return;
         }
         const node = new Node(key, value);
@@ -140,14 +154,14 @@ export class SplayTree extends Mapping {
     /**
      * Removes a specified key if it exists in the tree. The removed value is returned or `undefined` if not found.
      * @param {K} key The key to remove.
-     * @returns {V} The removed value associated with `key`.
+     * @returns {?V} The removed value associated with `key`.
      */
     remove(key) {
         if (!this.root) {
             return;
         }
         this.splay(key);
-        if (!eq(key, this.root.key)) {
+        if (this.cmp(key, this.root.key) !== 0) {
             return;
         }
         const removed = this.root;
@@ -203,7 +217,7 @@ export class SplayTree extends Mapping {
     /**
      * Returns the largest key that is less than a given key.
      * @param key The given key
-     * @returns The largest key found or `undefined`.
+     * @returns {?K} The largest key found or `undefined`.
      */
     lowerBound(key) {
         if (!this.root)
@@ -214,7 +228,7 @@ export class SplayTree extends Mapping {
         // Now the result is either the root node or the greatest node in
         // the left subtree.
         if (this.cmp(this.root.key, key) < 0) {
-            return this.root;
+            return this.root.key;
         }
         else if (this.root.left) {
             return this.max(this.root.left);
@@ -229,7 +243,6 @@ export class SplayTree extends Mapping {
         if (!this.root)
             return;
         let stub, left, right;
-        // eslint-disable-next-line
         stub = left = right = new Node(null, null);
         let root = this.root;
         while (true) {
@@ -284,7 +297,7 @@ export class SplayTree extends Mapping {
         this.root = root;
     }
     add(key) {
-        return this.set(key, null);
+        this.insert(key, null, false);
     }
     /**
      * Returns `true` if the given key is in the tree.
@@ -292,13 +305,13 @@ export class SplayTree extends Mapping {
      * @returns `true` if found.
      */
     contains(key) {
-        return this.get(key) !== undefined;
+        return this.findNode(key) !== undefined;
     }
-    /** Alias of remove but just returns `true` instead of the deleted value. */
+    /** Alias of remove but returns `true` if the key was found instead of the deleted value. */
     delete(key) {
-        // since remove throws, this will throw too
+        const size = this.count;
         this.remove(key);
-        return true;
+        return this.count < size;
     }
     clear() {
         if (!this.root)
@@ -327,8 +340,8 @@ export class SplayTree extends Mapping {
         }
     }
     /**
-     * Returns an ordered iterable of all the keys and values in the tree.
-     * @returns {Iterable<V>} A iterable of `[key, value]` pairs sorted by key.
+     * Returns an ordered iterable of all the values in the tree.
+     * @returns {Iterable<V>} An iterable of values sorted by key.
      */
     *values() {
         for (const node of traverse(this.root)) {

package/dist/collections/Trie.d.ts

@@ -23,9 +23,9 @@ export declare class Trie extends Collection {
     /**
      * Generates all results that start with the given string.
      * @param word A prefix string
-     * @param {number} [limit=20] The number of results to return.
+     * @param {number} [limit] The number of results to return. Defaults to every result.
      */
-    matches: (word: string, limit?: number) => Generator<any, void, any>;
+    matches: (word: string, limit?: number) => Generator<string>;
     /**
      * Returns `true` if the given string is found in the tree.
      * @param {string} word