atomic-fns 0.3.1 → 0.3.3-beta

package/core/collections/LRUCache.ts

@@ -0,0 +1,486 @@
+import { Iteratee, NotImplementedError, ValueError } from '../globals/index.js'
+import { IterableIterator } from '../itertools/index.js'
+import { Mapping } from './abc.js'
+import { getPointerArray } from './typedArrays.js'
+
+/**
+ * Base append-only Cache collection that supports adding and accessing keys in O(1).
+ * The collection has a fixed given size (default 1024) and when full, it evicts keys using LRU approach. This operation is also O(1).
+ * @template K, V
+ */
+export class Cache<K, V = any> extends Mapping<K, V> {
+  capacity: number
+  head: number = 0
+  tail: number = 0
+  count: number = 0
+  protected items = new Map<K, number>()
+  protected forward: Uint8Array | Uint16Array | Uint32Array
+  protected backward: Uint8Array | Uint16Array | Uint32Array
+  protected K: K[]
+  protected V: V[]
+
+  /**
+   * Create a new cache object of fixed size.
+   * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+   * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+   * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+   */
+  constructor(capacity = 1024, Keys = Array, Values = Array) {
+    super()
+    this.capacity = capacity
+
+    if (typeof this.capacity !== 'number' || this.capacity <= 0)
+      throw new ValueError('LRUCache capacity should be a positive integer.')
+    else if (!isFinite(this.capacity) || Math.floor(this.capacity) !== this.capacity)
+      throw new ValueError('LRUCache capacity should be a finite positive integer.')
+
+    const PointerArray = getPointerArray(capacity)
+    this.forward = new PointerArray(capacity)
+    this.backward = new PointerArray(capacity)
+    this.K = new Keys(capacity)
+    this.V = new Values(capacity)
+  }
+
+  /**
+   * This is just an alias of {@link Cache.set}.
+   * @param {K} key The key to add (note value will be `undefined`).
+   */
+  add(key: K) {
+    return this.set(key, undefined)
+  }
+
+  /**
+   * Method used to check whether the key exists in the cache.
+   *
+   * @param  {any} key   - Key.
+   * @return {boolean}
+   */
+  contains(key) {
+    return this.items.has(key)
+  }
+
+  /**
+   * Method used to clear the structure.
+   */
+  clear() {
+    this.count = 0
+    this.head = 0
+    this.tail = 0
+    this.items = new Map()
+  }
+
+  /**
+   * Returns the number of keys in the cache.
+   */
+  get size() {
+    return this.count
+  }
+
+  /**
+   * Method used to splay a value on top.
+   *
+   * @param  {number}   pointer - Pointer of the value to splay on top.
+   * @return {Cache}
+   */
+  protected splayOnTop(pointer) {
+    const oldHead = this.head
+
+    if (this.head === pointer) return this
+
+    const previous = this.backward[pointer]
+    const next = this.forward[pointer]
+
+    if (this.tail === pointer) {
+      this.tail = previous
+    } else {
+      this.backward[next] = previous
+    }
+
+    this.forward[previous] = next
+
+    this.backward[oldHead] = pointer
+    this.head = pointer
+    this.forward[pointer] = oldHead
+
+    return this
+  }
+
+  /**
+   * Method used to get the value attached to the given key. Will move the
+   * related key to the front of the underlying linked list.
+   *
+   * @param  {any} key   - Key.
+   * @return {any}
+   */
+  get(key) {
+    const pointer = this.items.get(key)
+
+    if (typeof pointer === 'undefined') return
+
+    this.splayOnTop(pointer)
+
+    return this.V[pointer]
+  }
+
+  /**
+   * Method used to set the value for the given key in the cache.
+   *
+   * @param  {any} key   - Key.
+   * @param  {any} value - Value.
+   * @return {undefined}
+   */
+  set(key, value) {
+    let pointer = this.items.get(key)
+
+    // The key already exists, we just need to update the value and splay on top
+    if (typeof pointer !== 'undefined') {
+      this.splayOnTop(pointer)
+      this.V[pointer] = value
+
+      return
+    }
+
+    // The cache is not yet full
+    if (this.count < this.capacity) {
+      pointer = this.count++
+    }
+
+    // Cache is full, we need to drop the last value
+    else {
+      pointer = this.tail
+      this.tail = this.backward[pointer]
+      this.items.delete(this.K[pointer])
+    }
+
+    // Storing key & value
+    this.items.set(key, pointer)
+    this.K[pointer] = key
+    this.V[pointer] = value
+
+    // Moving the item at the front of the list
+    this.forward[pointer] = this.head
+    this.backward[this.head] = pointer
+    this.head = pointer
+  }
+
+  /**
+   * Method used to get the value attached to the given key. Does not modify
+   * the ordering of the underlying linked list.
+   *
+   * @param  {any} key   - Key.
+   * @return {any}
+   */
+  peek(key) {
+    const pointer = this.items.get(key)
+
+    if (typeof pointer === 'undefined') return
+
+    return this.V[pointer]
+  }
+
+  /**
+   * Method used to iterate over the cache's entries using a callback.
+   *
+   * @param  {Iteratee<V>}  iteratee - Function to call for each item.
+   */
+  forEach(iteratee: Iteratee<V>) {
+    let i = 0
+    const l = this.count
+
+    let pointer = this.head
+    const keys = this.K
+    const values = this.V
+    const forward = this.forward
+
+    while (i < l) {
+      iteratee(values[pointer], keys[pointer], this)
+      pointer = forward[pointer]
+      i++
+    }
+  }
+
+  /**
+   * Method used to create an iterator over the cache's keys from most
+   * recently used to least recently used.
+   *
+   * @return {Iterator<K>}
+   */
+  keys() {
+    let i = 0
+    const l = this.count
+
+    let pointer = this.head
+    const keys = this.K
+    const forward = this.forward
+
+    return IterableIterator(() => {
+      if (i >= l) return { done: true }
+
+      const key = keys[pointer]
+
+      i++
+
+      if (i < l) pointer = forward[pointer]
+
+      return {
+        done: false,
+        value: key
+      }
+    })
+  }
+
+  /**
+   * Method used to create an iterator over the cache's values from most
+   * recently used to least recently used.
+   *
+   * @return {Iterator<V>}
+   */
+  values() {
+    let i = 0
+    const l = this.count
+
+    let pointer = this.head
+    const values = this.V
+    const forward = this.forward
+
+    return IterableIterator(() => {
+      if (i >= l) return { done: true }
+
+      const value = values[pointer]
+
+      i++
+
+      if (i < l) pointer = forward[pointer]
+
+      return {
+        done: false,
+        value
+      }
+    })
+  }
+
+  /**
+   * Method used to create an iterator over the cache's entries from most
+   * recently used to least recently used.
+   *
+   * @return {Iterator<[K, V]>}
+   */
+  entries() {
+    let i = 0
+    const l = this.count
+
+    let pointer = this.head
+    const keys = this.K
+    const values = this.V
+    const forward = this.forward
+
+    return IterableIterator<[K, V]>(() => {
+      if (i >= l) return { done: true }
+
+      const key = keys[pointer]
+      const value = values[pointer]
+
+      i++
+
+      if (i < l) pointer = forward[pointer]
+
+      return { value: [key, value] }
+    })
+  }
+
+  /**
+   * NotImplemented -- throws an exception.
+   * @param key
+   * @returns
+   */
+  remove(key: any) {
+    throw new NotImplementedError(`Base Cache class does not implement remove().`)
+  }
+
+  [Symbol.iterator]() {
+    return this.entries()
+  }
+
+  /**
+   * Convenience known methods.
+   */
+  inspect() {
+    const proxy = new Map()
+
+    const iterator = this.entries()
+    let step
+
+    while (((step = iterator.next()), !step.done)) proxy.set(step.value[0], step.value[1])
+
+    // Trick so that node displays the name of the constructor
+    Object.defineProperty(proxy, 'constructor', {
+      value: Cache,
+      enumerable: false
+    })
+
+    return proxy
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return this.inspect()
+  }
+}
+
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ */
+export class LRUCache<K, V> extends Cache<K, V> {
+  deletedSize = 0
+  deleted: Uint8Array | Uint16Array | Uint32Array
+
+  /**
+   * Create a new LRU cache object of fixed size.
+   * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+   * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+   * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+   */
+  constructor(capacity = 1024, Keys = Array, Values = Array) {
+    super(capacity, Keys, Values)
+    const PointerArray = getPointerArray(capacity)
+    this.deleted = new PointerArray(capacity)
+  }
+
+  /** Remove all elements in the cache. */
+  clear() {
+    super.clear()
+    this.deletedSize = 0
+  }
+
+  /**
+   * Method used to set the value for the given key in the cache.
+   *
+   * @param  {any} key   - Key.
+   * @param  {any} value - Value.
+   * @return {undefined}
+   */
+  set(key, value) {
+    let pointer = this.items.get(key)
+
+    // The key already exists, we just need to update the value and splay on top
+    if (typeof pointer !== 'undefined') {
+      this.splayOnTop(pointer)
+      this.V[pointer] = value
+
+      return
+    }
+
+    // The cache is not yet full
+    if (this.count < this.capacity) {
+      if (this.deletedSize > 0) {
+        // If there is a "hole" in the pointer list, reuse it
+        pointer = this.deleted[--this.deletedSize]
+      } else {
+        // otherwise append to the pointer list
+        pointer = this.count
+      }
+      this.count++
+    }
+
+    // Cache is full, we need to drop the last value
+    else {
+      pointer = this.tail
+      this.tail = this.backward[pointer]
+      this.items.delete(this.K[pointer])
+    }
+
+    // Storing key & value
+    this.items.set(key, pointer)
+    this.K[pointer] = key
+    this.V[pointer] = value
+
+    // Moving the item at the front of the list
+    this.forward[pointer] = this.head
+    this.backward[this.head] = pointer
+    this.head = pointer
+  }
+
+  /**
+   * Method used to delete the entry for the given key in the cache.
+   *
+   * @param  {any} key   - Key.
+   * @return {boolean}   - true if the item was present
+   */
+  delete(key) {
+    const pointer = this.items.get(key)
+
+    if (typeof pointer === 'undefined') {
+      return false
+    }
+
+    this.items.delete(key)
+
+    if (this.count === 1) {
+      this.count = 0
+      this.head = 0
+      this.tail = 0
+      this.deletedSize = 0
+      return true
+    }
+
+    const previous = this.backward[pointer]
+    const next = this.forward[pointer]
+
+    if (this.head === pointer) {
+      this.head = next
+    }
+    if (this.tail === pointer) {
+      this.tail = previous
+    }
+
+    this.forward[previous] = next
+    this.backward[next] = previous
+
+    this.count--
+    this.deleted[this.deletedSize++] = pointer
+
+    return true
+  }
+
+  /**
+   * Method used to remove and return the value for the given key in the cache.
+   *
+   * @param  {any} key                 - Key.
+   * @return {any} The value, if present; the missing indicator if absent
+   */
+  remove(key) {
+    const pointer = this.items.get(key)
+
+    if (typeof pointer === 'undefined') {
+      return
+    }
+
+    const dead = this.V[pointer]
+    this.items.delete(key)
+
+    if (this.count === 1) {
+      this.count = 0
+      this.head = 0
+      this.tail = 0
+      this.deletedSize = 0
+      return dead
+    }
+
+    const previous = this.backward[pointer]
+    const next = this.forward[pointer]
+
+    if (this.head === pointer) {
+      this.head = next
+    }
+    if (this.tail === pointer) {
+      this.tail = previous
+    }
+
+    this.forward[previous] = next
+    this.backward[next] = previous
+
+    this.count--
+    this.deleted[this.deletedSize++] = pointer
+
+    return dead
+  }
+}

package/core/collections/SortedMap.d.ts

@@ -0,0 +1,92 @@
+import { Mapping } from './abc.js';
+/**
+ * A `SortedMap` 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 Operators.compare}
+ * @see {@link Operators.lt}
+ * @template K, V
+ */
+export declare class SortedMap<K, V> extends Mapping<K, V> {
+    private readonly store;
+    /**
+     * Creates a new `SortedMap` object.
+     * @param {Iterable<[K, V]>} [iterable] Initialize the map with entries.
+     * @param {Comparer} [compareFn] The `compare` function to sort keys.
+     */
+    constructor(iterable?: Iterable<[K, V]>, compareFn?: any);
+    /**
+     * Adds a new `key` with a `null` value, if the `key` doesn't exist.
+     * @param {K} key
+     * @returns {this} Returns the Map object.
+     */
+    add(key: K): this;
+    /**
+     * Returns the value associated with the `key` or `undefined`.
+     * @param {K} key
+     * @returns {?V} The key value or `undefined`.
+     */
+    get(key: K): any;
+    /**
+     * 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;
+    /**
+     * Returns the smallest key in the tree.
+     * @returns {?K}
+     */
+    min(): K | undefined;
+    /**
+     * Returns the largest key in the tree.
+     * @returns {?K}
+     */
+    max(): K | undefined;
+    /**
+     * Returns `true` if the `key` existed in the map and was removed.
+     * @param {K} key
+     * @returns {boolean} `true` if key was removed, otherwise `false`.
+     */
+    delete(item: K): boolean;
+    /**
+     * Removes all key/value pairs in the tree.
+     */
+    clear(): void;
+    /**
+     * Returns the total key/value pairs in the tree.
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Check if there are no key/value pairs in the tree.
+     * @returns {boolean} `true` if is empty.
+     */
+    empty(): boolean;
+    /**
+     * Returns `true` if the `key` exists in the map.
+     * @param {K} key
+     * @returns {boolean} `true` if key is found, otherwise `false`.
+     */
+    contains(key: K): boolean;
+    /**
+     * Returns `true` if the `key` exists in the map.
+     * @param {K} key
+     * @returns {boolean} `true` if key is found, otherwise `false`.
+     */
+    has(key: K): boolean;
+    /**
+     * Returns a new iterator of all **ordered** keys in the map.
+     * @returns {Iterable<K>}
+     */
+    keys(): Iterable<K>;
+    /**
+     * Returns a new iterator of all values **ordered** by their keys.
+     * @returns {Iterable<V>}
+     */
+    values(): Iterable<V>;
+    /**
+     * Returns a new iterator of all key value pairs **ordered** by their keys.
+     * @returns {Iterable<[K, V]>}
+     */
+    entries(): Iterable<[K, V]>;
+}

package/core/collections/SortedMap.js

@@ -0,0 +1,130 @@
+import { Mapping } from './abc.js';
+import { SplayTree } from './SplayTree.js';
+/**
+ * A `SortedMap` 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 Operators.compare}
+ * @see {@link Operators.lt}
+ * @template K, V
+ */
+export class SortedMap extends Mapping {
+    store;
+    /**
+     * Creates a new `SortedMap` object.
+     * @param {Iterable<[K, V]>} [iterable] Initialize the map with entries.
+     * @param {Comparer} [compareFn] The `compare` function to sort keys.
+     */
+    constructor(iterable, compareFn) {
+        super();
+        this.store = new SplayTree(compareFn);
+        if (iterable) {
+            for (const pair of iterable) {
+                this.store.set(pair[0], pair[1] ?? null);
+            }
+        }
+    }
+    /**
+     * Adds a new `key` with a `null` value, if the `key` doesn't exist.
+     * @param {K} key
+     * @returns {this} Returns the Map object.
+     */
+    add(key) {
+        this.store.set(key, null);
+        return this;
+    }
+    /**
+     * Returns the value associated with the `key` or `undefined`.
+     * @param {K} key
+     * @returns {?V} The key value or `undefined`.
+     */
+    get(key) {
+        return this.store.get(key);
+    }
+    /**
+     * Sets the value for the given `key`.
+     * @param {K} key
+     * @param {V} value
+     * @returns {this} Returns the Map object.
+     */
+    set(key, value) {
+        return this.store.set(key, value);
+    }
+    /**
+     * Returns the smallest key in the tree.
+     * @returns {?K}
+     */
+    min() {
+        return this.store.min();
+    }
+    /**
+     * Returns the largest key in the tree.
+     * @returns {?K}
+     */
+    max() {
+        return this.store.max();
+    }
+    /**
+     * Returns `true` if the `key` existed in the map and was removed.
+     * @param {K} key
+     * @returns {boolean} `true` if key was removed, otherwise `false`.
+     */
+    delete(item) {
+        return this.store.remove(item) !== undefined;
+    }
+    /**
+     * Removes all key/value pairs in the tree.
+     */
+    clear() {
+        return this.store.clear();
+    }
+    /**
+     * Returns the total key/value pairs in the tree.
+     * @returns {number}
+     */
+    get size() {
+        return this.store.size;
+    }
+    /**
+     * Check if there are no key/value pairs in the tree.
+     * @returns {boolean} `true` if is empty.
+     */
+    empty() {
+        return this.store.empty();
+    }
+    /**
+     * Returns `true` if the `key` exists in the map.
+     * @param {K} key
+     * @returns {boolean} `true` if key is found, otherwise `false`.
+     */
+    contains(key) {
+        return this.store.contains(key);
+    }
+    /**
+     * Returns `true` if the `key` exists in the map.
+     * @param {K} key
+     * @returns {boolean} `true` if key is found, otherwise `false`.
+     */
+    has(key) {
+        return this.store.contains(key);
+    }
+    /**
+     * Returns a new iterator of all **ordered** keys in the map.
+     * @returns {Iterable<K>}
+     */
+    keys() {
+        return this.store.keys();
+    }
+    /**
+     * Returns a new iterator of all values **ordered** by their keys.
+     * @returns {Iterable<V>}
+     */
+    values() {
+        return this.store.values();
+    }
+    /**
+     * Returns a new iterator of all key value pairs **ordered** by their keys.
+     * @returns {Iterable<[K, V]>}
+     */
+    entries() {
+        return this.store.entries();
+    }
+}