atomic-fns 0.3.1 → 0.3.2

package/core/collections/Heap.d.ts

@@ -0,0 +1,69 @@
+import type { Comparer } from '../operators/index.js';
+import { compare } from '../operators/index.js';
+import { Collection } from './abc.js';
+export declare class Heap<T> extends Collection {
+    private readonly heap;
+    private readonly compare;
+    private count;
+    /**
+     * Initializes a new Heap instance.
+     *
+     * **Note:** When constructing the heap from an array, it will operate directly on this array. For other iterables, it will create a new array.
+     *
+     * @param {Iterable<T>} [container=[]] The initial values.
+     * @param {Comparer} [cmp=compare] Compare function. Defaults to smaller values first.
+     */
+    constructor(container?: Iterable<T>, cmp?: Comparer);
+    at(n: number): T | undefined;
+    get size(): number;
+    clear(): void;
+    /**
+     * Push element into a container in order.
+     * @param item The element to push.
+     */
+    add(item: T): void;
+    /**
+     * Removes the top element.
+     */
+    pop(): T | undefined;
+    /**
+     * Accesses the top element.
+     */
+    top(): T | undefined;
+    /**
+     * Check if element is in heap.
+     * @param item The item want to find.
+     * @return `true` if element exists.
+     */
+    contains(item: T): boolean;
+    /**
+     * Remove specified item from heap.
+     * @param item The item want to remove.
+     * @return `true` if the item was removed.
+     */
+    remove(item: T): boolean;
+    /**
+     * Returns an iterable with all the values in the heap.
+     * @returns {Iterable<T>} The values in the heap.
+     */
+    values(): IterableIterator<T>;
+}
+/**
+ * Transform any array into a heap, in-place, in linear time.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export declare function heapify(heap: any, compareFn?: typeof compare): void;
+/**
+ * Push the value `item` onto the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {*} item
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export declare function heappush<T>(heap: T[], item: T, compareFn?: typeof compare): void;
+/**
+ * Pop and return the smallest item from the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export declare function heappop<T>(heap: T[], compareFn?: typeof compare): T;

package/core/collections/Heap.js

@@ -0,0 +1,181 @@
+import { compare } from '../operators/index.js';
+import { Collection } from './abc.js';
+export class Heap extends Collection {
+    heap;
+    compare;
+    count = 0;
+    /**
+     * Initializes a new Heap instance.
+     *
+     * **Note:** When constructing the heap from an array, it will operate directly on this array. For other iterables, it will create a new array.
+     *
+     * @param {Iterable<T>} [container=[]] The initial values.
+     * @param {Comparer} [cmp=compare] Compare function. Defaults to smaller values first.
+     */
+    constructor(container = [], cmp = compare) {
+        super();
+        this.compare = cmp;
+        if (Array.isArray(container)) {
+            // use the provided array to avoid copying.
+            this.heap = container;
+        }
+        else {
+            this.heap = Array.from(container);
+        }
+        this.count = this.heap.length;
+        const halfLength = this.count >> 1;
+        // Heapify the items
+        for (let parent = (this.count - 1) >> 1; parent >= 0; --parent) {
+            heapifyDown(this.heap, parent, halfLength, this.compare);
+        }
+    }
+    at(n) {
+        return this.heap.at(n);
+    }
+    get size() {
+        return this.count;
+    }
+    clear() {
+        this.count = 0;
+        this.heap.length = 0;
+    }
+    /**
+     * Push element into a container in order.
+     * @param item The element to push.
+     */
+    add(item) {
+        this.heap.push(item);
+        heapifyUp(this.heap, this.count, this.compare);
+        this.count += 1;
+    }
+    /**
+     * Removes the top element.
+     */
+    pop() {
+        if (!this.count)
+            return;
+        const value = this.heap[0];
+        const last = this.heap.pop();
+        this.count -= 1;
+        if (this.count) {
+            this.heap[0] = last;
+            heapifyDown(this.heap, 0, this.count >> 1, this.compare);
+        }
+        return value;
+    }
+    /**
+     * Accesses the top element.
+     */
+    top() {
+        if (!this.count)
+            return;
+        return this.heap[0];
+    }
+    /**
+     * Check if element is in heap.
+     * @param item The item want to find.
+     * @return `true` if element exists.
+     */
+    contains(item) {
+        if (!this.count)
+            return false;
+        return this.heap.includes(item);
+    }
+    /**
+     * Remove specified item from heap.
+     * @param item The item want to remove.
+     * @return `true` if the item was removed.
+     */
+    remove(item) {
+        const index = this.heap.indexOf(item);
+        if (index < 0)
+            return false;
+        if (index === 0) {
+            this.pop();
+        }
+        else if (index === this.count - 1) {
+            this.heap.pop();
+            this.count -= 1;
+        }
+        else {
+            this.heap.splice(index, 1, this.heap.pop());
+            this.count -= 1;
+            heapifyUp(this.heap, index, this.compare);
+            heapifyDown(this.heap, index, this.count >> 1, this.compare);
+        }
+        return true;
+    }
+    /**
+     * Returns an iterable with all the values in the heap.
+     * @returns {Iterable<T>} The values in the heap.
+     */
+    values() {
+        return this.heap[Symbol.iterator]();
+    }
+}
+function heapifyDown(heap, i, halfLength, compareFn = compare) {
+    const item = heap[i];
+    while (i < halfLength) {
+        let left = (i << 1) | 1;
+        const right = left + 1;
+        let minItem = heap[left];
+        if (right < heap.length && compareFn(minItem, heap[right]) > 0) {
+            left = right;
+            minItem = heap[right];
+        }
+        if (compareFn(minItem, item) >= 0)
+            break;
+        heap[i] = minItem;
+        i = left;
+    }
+    heap[i] = item;
+}
+function heapifyUp(heap, i, compareFn) {
+    const item = heap[i];
+    while (i > 0) {
+        const parent = (i - 1) >> 1;
+        const parentItem = heap[parent];
+        if (compareFn(parentItem, item) <= 0)
+            break;
+        heap[i] = parentItem;
+        i = parent;
+    }
+    heap[i] = item;
+}
+/**
+ * Transform any array into a heap, in-place, in linear time.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heapify(heap, compareFn = compare) {
+    const size = heap.length;
+    const halfLength = size >> 1;
+    for (let parent = (size - 1) >> 1; parent >= 0; --parent) {
+        heapifyDown(heap, parent, halfLength, compareFn);
+    }
+}
+/**
+ * Push the value `item` onto the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {*} item
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heappush(heap, item, compareFn = compare) {
+    heap.push(item);
+    heapifyUp(heap, heap.length - 1, compareFn);
+}
+/**
+ * Pop and return the smallest item from the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heappop(heap, compareFn = compare) {
+    const last = heap.pop();
+    if (heap.length) {
+        const item = heap[0];
+        heap[0] = last;
+        heapifyDown(heap, 0, heap.length >> 1, compareFn);
+        return item;
+    }
+    return last;
+}

package/core/collections/Heap.ts

@@ -0,0 +1,189 @@
+import type { Comparer } from '../operators/index.js'
+import { compare } from '../operators/index.js'
+import { Collection } from './abc.js'
+
+export class Heap<T> extends Collection {
+  private readonly heap: T[]
+  private readonly compare: Comparer
+  private count: number = 0
+
+  /**
+   * Initializes a new Heap instance.
+   *
+   * **Note:** When constructing the heap from an array, it will operate directly on this array. For other iterables, it will create a new array.
+   *
+   * @param {Iterable<T>} [container=[]] The initial values.
+   * @param {Comparer} [cmp=compare] Compare function. Defaults to smaller values first.
+   */
+  constructor(container: Iterable<T> = [], cmp: Comparer = compare) {
+    super()
+    this.compare = cmp
+    if (Array.isArray(container)) {
+      // use the provided array to avoid copying.
+      this.heap = container
+    } else {
+      this.heap = Array.from(container)
+    }
+    this.count = this.heap.length
+    const halfLength = this.count >> 1
+    // Heapify the items
+    for (let parent = (this.count - 1) >> 1; parent >= 0; --parent) {
+      heapifyDown(this.heap, parent, halfLength, this.compare)
+    }
+  }
+
+  at(n: number) {
+    return this.heap.at(n)
+  }
+
+  get size() {
+    return this.count
+  }
+
+  clear() {
+    this.count = 0
+    this.heap.length = 0
+  }
+
+  /**
+   * Push element into a container in order.
+   * @param item The element to push.
+   */
+  add(item: T) {
+    this.heap.push(item)
+    heapifyUp(this.heap, this.count, this.compare)
+    this.count += 1
+  }
+
+  /**
+   * Removes the top element.
+   */
+  pop() {
+    if (!this.count) return
+    const value = this.heap[0]
+    const last = this.heap.pop() as T
+    this.count -= 1
+    if (this.count) {
+      this.heap[0] = last
+      heapifyDown(this.heap, 0, this.count >> 1, this.compare)
+    }
+    return value
+  }
+
+  /**
+   * Accesses the top element.
+   */
+  top() {
+    if (!this.count) return
+    return this.heap[0] as T | undefined
+  }
+
+  /**
+   * Check if element is in heap.
+   * @param item The item want to find.
+   * @return `true` if element exists.
+   */
+  contains(item: T) {
+    if (!this.count) return false
+    return this.heap.includes(item)
+  }
+
+  /**
+   * Remove specified item from heap.
+   * @param item The item want to remove.
+   * @return `true` if the item was removed.
+   */
+  remove(item: T) {
+    const index = this.heap.indexOf(item)
+    if (index < 0) return false
+    if (index === 0) {
+      this.pop()
+    } else if (index === this.count - 1) {
+      this.heap.pop()
+      this.count -= 1
+    } else {
+      this.heap.splice(index, 1, this.heap.pop() as T)
+      this.count -= 1
+      heapifyUp(this.heap, index, this.compare)
+      heapifyDown(this.heap, index, this.count >> 1, this.compare)
+    }
+    return true
+  }
+
+  /**
+   * Returns an iterable with all the values in the heap.
+   * @returns {Iterable<T>} The values in the heap.
+   */
+  values() {
+    return this.heap[Symbol.iterator]()
+  }
+}
+
+function heapifyDown(heap, i: number, halfLength: number, compareFn = compare) {
+  const item = heap[i]
+  while (i < halfLength) {
+    let left = (i << 1) | 1
+    const right = left + 1
+    let minItem = heap[left]
+    if (right < heap.length && compareFn(minItem, heap[right]) > 0) {
+      left = right
+      minItem = heap[right]
+    }
+    if (compareFn(minItem, item) >= 0) break
+    heap[i] = minItem
+    i = left
+  }
+  heap[i] = item
+}
+
+function heapifyUp(heap, i: number, compareFn) {
+  const item = heap[i]
+  while (i > 0) {
+    const parent = (i - 1) >> 1
+    const parentItem = heap[parent]
+    if (compareFn(parentItem, item) <= 0) break
+    heap[i] = parentItem
+    i = parent
+  }
+  heap[i] = item
+}
+
+/**
+ * Transform any array into a heap, in-place, in linear time.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heapify(heap, compareFn = compare) {
+  const size = heap.length
+  const halfLength = size >> 1
+  for (let parent = (size - 1) >> 1; parent >= 0; --parent) {
+    heapifyDown(heap, parent, halfLength, compareFn)
+  }
+}
+
+/**
+ * Push the value `item` onto the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {*} item
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heappush<T>(heap: T[], item: T, compareFn = compare) {
+  heap.push(item)
+  heapifyUp(heap, heap.length - 1, compareFn)
+}
+
+/**
+ * Pop and return the smallest item from the `heap`, maintaining the heap invariant.
+ * @param {Array} heap
+ * @param {Comparer} [compareFn=compare] Custom compare function
+ */
+export function heappop<T>(heap: T[], compareFn = compare) {
+  const last = heap.pop() as T
+  if (heap.length) {
+    const item = heap[0]
+    heap[0] = last
+    heapifyDown(heap, 0, heap.length >> 1, compareFn)
+    return item
+  }
+  return last
+}

package/core/collections/LRUCache.d.ts

@@ -0,0 +1,131 @@
+import { Iteratee } from '../globals/index.js';
+import { Mapping } from './abc.js';
+/**
+ * Base append-only Cache collection.
+ */
+export declare class Cache<K, V = any> extends Mapping<K, V> {
+    capacity: number;
+    head: number;
+    tail: number;
+    count: number;
+    protected items: Map<K, number>;
+    protected forward: Uint8Array | Uint16Array | Uint32Array;
+    protected backward: Uint8Array | Uint16Array | Uint32Array;
+    protected K: K[];
+    protected V: V[];
+    constructor(capacity?: number, Keys?: ArrayConstructor, Values?: ArrayConstructor);
+    /**
+     * This is just an alias of {@link Cache.set}.
+     * @param {K} key The key to add (note value will be `undefined`).
+     */
+    add(key: K): void;
+    /**
+     * Method used to check whether the key exists in the cache.
+     *
+     * @param  {any} key   - Key.
+     * @return {boolean}
+     */
+    contains(key: any): boolean;
+    /**
+     * Method used to clear the structure.
+     */
+    clear(): void;
+    get size(): number;
+    /**
+     * Method used to splay a value on top.
+     *
+     * @param  {number}   pointer - Pointer of the value to splay on top.
+     * @return {Cache}
+     */
+    protected splayOnTop(pointer: any): 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: any): V | undefined;
+    /**
+     * 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: any, value: any): void;
+    /**
+     * 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: any): V | undefined;
+    /**
+     * 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>): void;
+    /**
+     * Method used to create an iterator over the cache's keys from most
+     * recently used to least recently used.
+     *
+     * @return {Iterator<K>}
+     */
+    keys(): Iterator<any, any, undefined> & Iterable<any>;
+    /**
+     * Method used to create an iterator over the cache's values from most
+     * recently used to least recently used.
+     *
+     * @return {Iterator<V>}
+     */
+    values(): Iterator<any, any, undefined> & Iterable<any>;
+    /**
+     * Method used to create an iterator over the cache's entries from most
+     * recently used to least recently used.
+     *
+     * @return {Iterator<[K, V]>}
+     */
+    entries(): Iterator<[K, V], any, undefined> & Iterable<[K, V]>;
+    /**
+     * NotImplemented -- throws an exception.
+     * @param key
+     * @returns
+     */
+    remove(key: any): void;
+    [Symbol.iterator](): Iterator<[K, V], any, undefined> & Iterable<[K, V]>;
+    /**
+     * Convenience known methods.
+     */
+    inspect(): Map<any, any>;
+}
+export declare class LRUCache<K, V> extends Cache<K, V> {
+    deletedSize: number;
+    deleted: Uint8Array | Uint16Array | Uint32Array;
+    constructor(capacity?: number, Keys?: ArrayConstructor, Values?: ArrayConstructor);
+    clear(): void;
+    /**
+     * 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: any, value: any): void;
+    /**
+     * 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: any): boolean;
+    /**
+     * 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: any): V | undefined;
+}