atomic-fns 0.3.5 → 0.4.3

package/README.md

@@ -23,7 +23,7 @@ You may prefer this because it's:
 
 This library is available as an [npm package](https://www.npmjs.com/package/atomic-fns).
 
-To install the package you need to have [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (or [yarn](https://yarnpkg.com/getting-started/install)) and then run:
+To install the package you need to have [npm](https://www.npmjs.com/get-npm) (or [yarn](https://yarnpkg.com/getting-started/install)) installed and then run:
 
 ```bash
 npm install atomic-fns
@@ -47,17 +47,6 @@ uniqueId('user_')
 ...
 ```
 
-You could also import any individual module directly from an html page like this:
-
-```html
-<script type="module">
-  import {
-    namedtuple, FrozenSet, SortedSet, SortedMap
-  } from 'https://unpkg.com/atomic-fns/core/collections';
-  // your code goes here...
-</script>
-```
-
 See the full list of [modules](https://atomic-fns.dev/modules.html).
 
 ## Data model

package/{core → dist}/collections/BTree.d.ts

@@ -81,7 +81,7 @@ export declare class BTree<K = any, V = any> extends Mapping<K, V> {
      *  @param firstKey: Minimum key to include in the output. */
     keys(firstKey?: K): IterableIterator<K>;
     /** Gets the lowest key in the tree. Complexity: O(log size) */
-    minKey(): K | undefined;
+    minKey(): K;
     /** Gets the highest key in the tree. Complexity: O(1) */
     maxKey(): K;
     /** Returns a new iterator for iterating the values of each pair in order by key.
@@ -166,11 +166,11 @@ export declare class BTree<K = any, V = any> extends Mapping<K, V> {
      * @param includeHigh If the `high` key is present, `onFound` is called for
      *        that final pair if and only if this parameter is true.
      * @param onFound A function that is called for each key-value pair. This
-     *        function can return {break:R} to stop early with result R.
+     *        function can return {done:R} to stop early with result R.
      * @param initialCounter Initial third argument of onFound. This value
      *        increases by one each time `onFound` is called. Default: 0
      * @returns The number of values found, or R if the callback returned
-     *        `{break:R}` to stop early.
+     *        `{done:R}` to stop early.
      * @description Computational complexity: O(number of items scanned + log size)
      */
     rangeForEach<R = number>(low: K, high: K, includeHigh: boolean, onFound?: Iteratee<K, V>, initialCounter?: number): R | number;
@@ -190,13 +190,13 @@ export declare class BTree<K = any, V = any> extends Mapping<K, V> {
      * @param onFound A function that is called for each key-value pair. This
      *        function can return `{value:v}` to change the value associated
      *        with the current key, `{delete:true}` to delete the current pair,
-     *        `{break:R}` to stop early with result R, or it can return nothing
+     *        `{done:R}` to stop early with result R, or it can return nothing
      *        (undefined or {}) to cause no effect and continue iterating.
-     *        `{break:R}` can be combined with one of the other two commands.
+     *        `{done:R}` can be combined with one of the other two commands.
      *        The third argument `counter` is the number of items iterated
      *        previously; it equals 0 when `onFound` is called the first time.
      * @returns The number of values scanned, or R if the callback returned
-     *        `{break:R}` to stop early.
+     *        `{done:R}` to stop early.
      * @description
      *   Computational complexity: O(number of items scanned + log size)
      *   Note: if the tree has been cloned with clone(), any shared

package/{core → dist}/collections/BTree.js

@@ -3,7 +3,7 @@ import { compare } from '../operators/index.js';
 import { Mapping } from './abc.js';
 const Delete = { delete: true };
 const DeleteRange = () => Delete;
-const Break = { break: true };
+const Break = { done: true };
 const EmptyArray = [];
 const ReusedArray = []; // assumed thread-local
 // Optimization: this array of `undefined`s is used instead of a normal
@@ -164,7 +164,7 @@ class BNode {
         }
         else {
             // Key already exists
-            if (overwrite !== false) {
+            if (overwrite) {
                 if (value !== undefined)
                     this.reifyValues();
                 // usually this is a no-op, but some users may wish to edit the key
@@ -252,7 +252,7 @@ class BNode {
             iHigh = this.indexOf(high, -1, cmp);
             if (iHigh < 0)
                 iHigh = ~iHigh;
-            else if (includeHigh === true)
+            else if (includeHigh)
                 iHigh++;
         }
         const keys = this.keys;
@@ -263,7 +263,7 @@ class BNode {
                 const result = onFound(key, values[i], count++);
                 if (result !== undefined) {
                     if (editMode) {
-                        if (key !== keys[i] || this.isShared === true)
+                        if (key !== keys[i] || this.isShared)
                             throw new Error('BTree illegally changed or cloned in editRange');
                         if (result.delete) {
                             this.keys.splice(i, 1);
@@ -277,7 +277,7 @@ class BNode {
                             values[i] = result.value;
                         }
                     }
-                    if (result.break !== undefined)
+                    if (result.done !== undefined)
                         return result;
                 }
             }
@@ -344,23 +344,23 @@ export class BTree extends Mapping {
     //  *  the callback is backwards: value first, then key. Call forEachPair
     //  *  instead to receive the key as the first argument.
     //  * @returns the number of values that were sent to the callback,
-    //  *        or the R value if the callback returned {break:R}. */
+    //  *        or the R value if the callback returned {done:R}. */
     // forEach<R = number>(iteratee: Iteratee<V, K>): R | number {
     //   return this.forEachPair((k, v) => iteratee(v as V, k, this))
     // }
     // /** Runs a function for each key-value pair, in order from smallest to
-    //  *  largest key. The callback can return {break:R} (where R is any value
+    //  *  largest key. The callback can return {done:R} (where R is any value
     //  *  except undefined) to stop immediately and return R from forEachPair.
     //  * @param onFound A function that is called for each key-value pair. This
-    //  *        function can return {break:R} to stop early with result R.
-    //  *        The reason that you must return {break:R} instead of simply R
+    //  *        function can return {done:R} to stop early with result R.
+    //  *        The reason that you must return {done:R} instead of simply R
     //  *        itself is for consistency with editRange(), which allows
     //  *        multiple actions, not just breaking.
     //  * @param initialCounter This is the value of the third argument of
     //  *        `onFound` the first time it is called. The counter increases
     //  *        by one each time `onFound` is called. Default value: 0
     //  * @returns the number of pairs sent to the callback (plus initialCounter,
-    //  *        if you provided one). If the callback returned {break:R} then
+    //  *        if you provided one). If the callback returned {done:R} then
     //  *        the R value is returned instead. */
     // private forEachPair<R = number>(callback: Iteratee<K, V>, initialCounter?: number): R | number {
     //   const low = this.minKey()
@@ -758,16 +758,16 @@ export class BTree extends Mapping {
      * @param includeHigh If the `high` key is present, `onFound` is called for
      *        that final pair if and only if this parameter is true.
      * @param onFound A function that is called for each key-value pair. This
-     *        function can return {break:R} to stop early with result R.
+     *        function can return {done:R} to stop early with result R.
      * @param initialCounter Initial third argument of onFound. This value
      *        increases by one each time `onFound` is called. Default: 0
      * @returns The number of values found, or R if the callback returned
-     *        `{break:R}` to stop early.
+     *        `{done:R}` to stop early.
      * @description Computational complexity: O(number of items scanned + log size)
      */
     rangeForEach(low, high, includeHigh, onFound, initialCounter) {
         const r = this.root.forRange(low, high, includeHigh, false, this, initialCounter || 0, onFound);
-        return typeof r === 'number' ? r : r.break;
+        return typeof r === 'number' ? r : r.done;
     }
     /**
      * Scans and potentially modifies values for a subsequence of keys.
@@ -785,13 +785,13 @@ export class BTree extends Mapping {
      * @param onFound A function that is called for each key-value pair. This
      *        function can return `{value:v}` to change the value associated
      *        with the current key, `{delete:true}` to delete the current pair,
-     *        `{break:R}` to stop early with result R, or it can return nothing
+     *        `{done:R}` to stop early with result R, or it can return nothing
      *        (undefined or {}) to cause no effect and continue iterating.
-     *        `{break:R}` can be combined with one of the other two commands.
+     *        `{done:R}` can be combined with one of the other two commands.
      *        The third argument `counter` is the number of items iterated
      *        previously; it equals 0 when `onFound` is called the first time.
      * @returns The number of values scanned, or R if the callback returned
-     *        `{break:R}` to stop early.
+     *        `{done:R}` to stop early.
      * @description
      *   Computational complexity: O(number of items scanned + log size)
      *   Note: if the tree has been cloned with clone(), any shared
@@ -804,7 +804,7 @@ export class BTree extends Mapping {
             this.root = root = root.clone();
         try {
             const r = root.forRange(low, high, includeHigh, true, this, initialCounter || 0, onFound);
-            return typeof r === 'number' ? r : r.break;
+            return typeof r === 'number' ? r : r.done;
         }
         finally {
             let isShared;

package/{core → dist}/collections/Heap.d.ts

@@ -14,7 +14,7 @@ export declare class Heap<T> extends Collection {
      * @param {Comparer} [cmp=compare] Compare function. Defaults to smaller values first.
      */
     constructor(container?: Iterable<T>, cmp?: Comparer);
-    at(n: number): T | undefined;
+    at(n: number): T;
     get size(): number;
     clear(): void;
     /**
@@ -25,11 +25,11 @@ export declare class Heap<T> extends Collection {
     /**
      * Removes the top element.
      */
-    pop(): T | undefined;
+    pop(): T;
     /**
      * Accesses the top element.
      */
-    top(): T | undefined;
+    top(): T;
     /**
      * Check if element is in heap.
      * @param item The item want to find.

package/dist/collections/LRUCache.d.ts

@@ -0,0 +1,80 @@
+import { Mapping } from './abc.js';
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ * @template K, V
+ */
+export declare class LRUCache<K = any, V = any> extends Mapping<K, V> {
+    protected items: Map<K, V>;
+    protected maxSize: number;
+    /**
+     * Creates a new instance of fixed size.
+     * @param {number} capacity
+     */
+    constructor(capacity?: number);
+    /**
+     * 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.
+     * @param {K} key
+     * @param {V} value
+     * @returns {this}
+     */
+    set(key: K, value: V): this;
+    /**
+     * This is just an alias of {@link LRUCache.set}.
+     * @param {K} key The key to add (note value will be `undefined`)
+     * @returns {this}
+     */
+    add(key: K): this;
+    /**
+     * Returns `true` if the specified `key` is found on the cache.
+     * @param {K} key
+     * @returns {boolean}
+     */
+    contains(key: K): boolean;
+    /**
+     * Get the value associated with the specified `key`, or `undefined` it not found.
+     * @param {K} key
+     * @returns {?V} The associated value or `undefined`
+     */
+    get(key: K): V;
+    /**
+     * Removes all keys and values from the cache.
+     * @returns {this}
+     */
+    clear(): this;
+    /**
+     * Removes a key from the cache and returns `true` if the key existed or `false` otherwise.
+     * @param {K} key
+     * @returns {boolean} `true` if the key existed and was removed
+     */
+    delete(key: K): boolean;
+    /**
+     * Removes the value associated with the specified `key` from the cache and returns the removed value if the key existed.
+     * @param {K} key
+     * @returns {?V} The value if it was removed or `undefined`.
+     */
+    remove(key: K): V;
+    /**
+     * Returns the total number of elements in the cache.
+     */
+    get size(): number;
+    /**
+     * Returns the total capacity of the cache.
+     */
+    get capacity(): number;
+    /**
+     * Returns an iterable of all the keys in the cache, in insertion order.
+     * @returns {IterableIterator<K>}
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Returns an iterable of all the values in the cache, in insertion order.
+     * @returns {IterableIterator<V>}
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Returns an iterable of all the [key, value] pairs in the cache, in insertion order.
+     * @returns {IterableIterator<[K, V]>}
+     */
+    entries(): IterableIterator<[K, V]>;
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}

package/dist/collections/LRUCache.js

@@ -0,0 +1,126 @@
+import { Mapping } from './abc.js';
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ * @template K, V
+ */
+export class LRUCache extends Mapping {
+    items = new Map();
+    maxSize;
+    /**
+     * Creates a new instance of fixed size.
+     * @param {number} capacity
+     */
+    constructor(capacity = 1024) {
+        super();
+        this.maxSize = capacity;
+    }
+    /**
+     * 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.
+     * @param {K} key
+     * @param {V} value
+     * @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);
+        return this;
+    }
+    /**
+     * This is just an alias of {@link LRUCache.set}.
+     * @param {K} key The key to add (note value will be `undefined`)
+     * @returns {this}
+     */
+    add(key) {
+        return this.set(key, undefined);
+    }
+    /**
+     * Returns `true` if the specified `key` is found on the cache.
+     * @param {K} key
+     * @returns {boolean}
+     */
+    contains(key) {
+        return this.items.has(key);
+    }
+    /**
+     * Get the value associated with the specified `key`, or `undefined` it not found.
+     * @param {K} key
+     * @returns {?V} The associated value or `undefined`
+     */
+    get(key) {
+        if (this.items.has(key)) {
+            const value = this.items.get(key);
+            // Delete the previous key to update the new insertion order
+            this.items.delete(key);
+            this.items.set(key, value);
+            return value;
+        }
+    }
+    /**
+     * Removes all keys and values from the cache.
+     * @returns {this}
+     */
+    clear() {
+        this.items.clear();
+        return this;
+    }
+    /**
+     * Removes a key from the cache and returns `true` if the key existed or `false` otherwise.
+     * @param {K} key
+     * @returns {boolean} `true` if the key existed and was removed
+     */
+    delete(key) {
+        return this.items.delete(key);
+    }
+    /**
+     * Removes the value associated with the specified `key` from the cache and returns the removed value if the key existed.
+     * @param {K} key
+     * @returns {?V} The value if it was removed or `undefined`.
+     */
+    remove(key) {
+        const value = this.items.get(key);
+        this.items.delete(key);
+        return value;
+    }
+    /**
+     * Returns the total number of elements in the cache.
+     */
+    get size() {
+        return this.items.size;
+    }
+    /**
+     * Returns the total capacity of the cache.
+     */
+    get capacity() {
+        return this.maxSize;
+    }
+    /**
+     * Returns an iterable of all the keys in the cache, in insertion order.
+     * @returns {IterableIterator<K>}
+     */
+    keys() {
+        return this.items.keys();
+    }
+    /**
+     * Returns an iterable of all the values in the cache, in insertion order.
+     * @returns {IterableIterator<V>}
+     */
+    values() {
+        return this.items.values();
+    }
+    /**
+     * Returns an iterable of all the [key, value] pairs in the cache, in insertion order.
+     * @returns {IterableIterator<[K, V]>}
+     */
+    entries() {
+        return this.items.entries();
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}

package/{core → dist}/collections/SortedMap.d.ts

@@ -36,12 +36,12 @@ export declare class SortedMap<K, V> extends Mapping<K, V> {
      * Returns the smallest key in the tree.
      * @returns {?K}
      */
-    min(): K | undefined;
+    min(): K;
     /**
      * Returns the largest key in the tree.
      * @returns {?K}
      */
-    max(): K | undefined;
+    max(): K;
     /**
      * Returns `true` if the `key` existed in the map and was removed.
      * @param {K} key

package/{core → dist}/collections/SortedSet.d.ts

@@ -1,7 +1,7 @@
 import { Collection } from './abc.js';
 /**
  * A `SortedSet` is a set that holds values in order. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as values.
- * @see {@link Compare}
+ * @see {@link Comparable}
  * @see {@link Ordered}
  * @template K, V
  */
@@ -23,12 +23,12 @@ export declare class SortedSet<T> extends Collection {
      * Returns the smallest value in the set.
      * @returns {?T}
      */
-    min(): T | undefined;
+    min(): T;
     /**
      * Returns the largest value in the set.
      * @returns {?T}
      */
-    max(): T | undefined;
+    max(): T;
     /**
      * Removes the value from the set and returns `true` if the value was found and removed.
      * @param {T} value

package/{core → dist}/collections/SortedSet.js

@@ -2,7 +2,7 @@ import { Collection } from './abc.js';
 import { SplayTree } from './SplayTree.js';
 /**
  * A `SortedSet` is a set that holds values in order. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as values.
- * @see {@link Compare}
+ * @see {@link Comparable}
  * @see {@link Ordered}
  * @template K, V
  */

package/{core → dist}/collections/SortedTree.d.ts

@@ -2,7 +2,7 @@ import { 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.
- * @see {@link Compare}
+ * @see {@link Comparable}
  * @see {@link Ordered}
  * @template K, V
  */
@@ -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 | undefined;
+    get(key: K): V;
     /**
      * Sets the value for the given `key`.
      * @param {K} key
@@ -37,7 +37,7 @@ export declare class SortedTree<K, V> extends Mapping<K, V> {
      * Returns the smallest key in the tree.
      * @returns {?K}
      */
-    min(): K | undefined;
+    min(): K;
     /**
      * Returns the largest key in the tree.
      * @returns {?K}

package/{core → dist}/collections/SortedTree.js

@@ -2,7 +2,7 @@ import { Mapping } from './abc.js';
 import { BTree } from './BTree.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.
- * @see {@link Compare}
+ * @see {@link Comparable}
  * @see {@link Ordered}
  * @template K, V
  */

package/{core → dist}/collections/SplayTree.d.ts

@@ -31,7 +31,7 @@ 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 | undefined;
+    top(): K;
     get size(): number;
     empty(): boolean;
     get height(): any;
@@ -53,23 +53,23 @@ export declare class SplayTree<K, V = any> extends Mapping<K, V> {
      * @param {K} key The key to remove.
      * @returns {V} The removed value associated with `key`.
      */
-    remove(key: K): V | undefined;
+    remove(key: K): V;
     /**
      * Returns the minimum key in the tree or subtree.
      * @returns The minimum key.
      */
-    min(root?: Node<K, V> | undefined): K | undefined;
+    min(root?: Node<K, V>): K;
     /**
      * Returns the maximum key in the tree or subtree.
      * @returns The maximum key.
      */
-    max(root?: Node<K, V> | undefined): K | undefined;
+    max(root?: Node<K, V>): K;
     /**
      * Returns the largest key that is less than a given key.
      * @param key The given key
      * @returns The largest key found or `undefined`.
      */
-    lowerBound(key: any): K | Node<K, V> | undefined;
+    lowerBound(key: any): K | Node<K, V>;
     /**
      * 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

package/{core → dist}/collections/deque.d.ts

@@ -44,28 +44,28 @@ export declare class Deque<T = any> extends Sequence<T> {
      * Removes and returns the element at the end of the deque.
      * @returns {?T} Returns the popped item.
      */
-    pop(): T | undefined;
+    pop(): T;
     /**
      * Alias of {@link Deque.pop}
      * @returns {?T} Returns the popped item.
      */
-    remove(): T | undefined;
+    remove(): T;
     /**
      * Removes and returns the element at the beginning of the deque.
      * @returns {?T} Returns the removed deque element.
      */
-    popleft(): T | undefined;
+    popleft(): T;
     /**
      * Returns the element at the beginning of the deque.
      * @returns {?T} The element if exists
      */
-    first(): T | undefined;
+    first(): T;
     /**
      * 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;
+    get(index: any): T;
     /**
      * Update the element at a given `index`.
      * @param {number} index The given index
@@ -82,7 +82,7 @@ export declare class Deque<T = any> extends Sequence<T> {
      * @param {Iteratee<T>} iteratee A function that will be invoked per element
      * @returns {?T} The element if exists
      */
-    find(iteratee: Iteratee<T>): T | undefined;
+    find(iteratee: Iteratee<T>): T;
     /**
      * Calls `iteratee` function for every element in the deque.
      * @param {Iteratee<T>} iteratee A function that will be invoked per element
@@ -111,7 +111,7 @@ export declare class Deque<T = any> extends Sequence<T> {
      * Creates an iterator of `[index, value]` pairs for all elements in the deque.
      * @returns {Iterator}
      */
-    entries(): Iterator<[number, T], any, undefined> & Iterable<[number, T]>;
+    entries(): Iterable<[number, T]> & Iterator<[number, T], any, undefined>;
     [Symbol.iterator](): Iterable<T>;
     inspect(): any;
 }

package/{core → dist}/collections/deque.js

@@ -228,17 +228,15 @@ export class Deque extends Sequence {
         return IterableIterator(() => {
             if (j >= l)
                 return {
-                    done: true
+                    done: true,
+                    value: undefined
                 };
             const value = items[i];
             i++;
             j++;
             if (i === c)
                 i = 0;
-            return {
-                value,
-                done: false
-            };
+            return { value };
         });
     }
     /**
@@ -260,15 +258,15 @@ export class Deque extends Sequence {
         return IterableIterator(() => {
             if (j >= l)
                 return {
-                    done: true
+                    done: true,
+                    value: undefined
                 };
             const value = items[i];
             i++;
             if (i === c)
                 i = 0;
             return {
-                value: [j++, value],
-                done: false
+                value: [j++, value]
             };
         });
     }

package/{core → dist}/collections/frozenset.js

@@ -13,18 +13,15 @@ export class FrozenSet extends Set {
     }
     /** @private */
     add() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return this; // eslint-disable-line
+        return this;
     }
     /** @private */
     delete() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return false; // eslint-disable-line
+        return false;
     }
     /** @private */
     clear() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return this; // eslint-disable-line
+        return this;
     }
     /** @private */
     freeze() {