data-structure-typed 2.0.5 → 2.1.1

package/dist/types/data-structures/heap/heap.d.ts

@@ -0,0 +1,503 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { Comparator, DFSOrderPattern, ElementCallback, HeapOptions } from '../../types';
+import { IterableElementBase } from '../base';
+/**
+ * Binary heap with pluggable comparator; supports fast insertion and removal of the top element.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @template R
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. Heap Properties: Each node in a heap follows a specific order property, which varies depending on the type of heap:
+ * Max Heap: The value of each parent node is greater than or equal to the value of its children.
+ * Min Heap: The value of each parent node is less than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
+ * @example
+ * // Use Heap to sort an array
+ *     function heapSort(arr: number[]): number[] {
+ *       const heap = new Heap<number>(arr, { comparator: (a, b) => a - b });
+ *       const sorted: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         sorted.push(heap.poll()!); // Poll minimum element
+ *       }
+ *       return sorted;
+ *     }
+ *
+ *     const array = [5, 3, 8, 4, 1, 2];
+ *     console.log(heapSort(array)); // [1, 2, 3, 4, 5, 8]
+ * @example
+ * // Use Heap to solve top k problems
+ *     function topKElements(arr: number[], k: number): number[] {
+ *       const heap = new Heap<number>([], { comparator: (a, b) => b - a }); // Max heap
+ *       arr.forEach(num => {
+ *         heap.add(num);
+ *         if (heap.size > k) heap.poll(); // Keep the heap size at K
+ *       });
+ *       return heap.toArray();
+ *     }
+ *
+ *     const numbers = [10, 30, 20, 5, 15, 25];
+ *     console.log(topKElements(numbers, 3)); // [15, 10, 5]
+ * @example
+ * // Use Heap to merge sorted sequences
+ *     function mergeSortedSequences(sequences: number[][]): number[] {
+ *       const heap = new Heap<{ value: number; seqIndex: number; itemIndex: number }>([], {
+ *         comparator: (a, b) => a.value - b.value // Min heap
+ *       });
+ *
+ *       // Initialize heap
+ *       sequences.forEach((seq, seqIndex) => {
+ *         if (seq.length) {
+ *           heap.add({ value: seq[0], seqIndex, itemIndex: 0 });
+ *         }
+ *       });
+ *
+ *       const merged: number[] = [];
+ *       while (!heap.isEmpty()) {
+ *         const { value, seqIndex, itemIndex } = heap.poll()!;
+ *         merged.push(value);
+ *
+ *         if (itemIndex + 1 < sequences[seqIndex].length) {
+ *           heap.add({
+ *             value: sequences[seqIndex][itemIndex + 1],
+ *             seqIndex,
+ *             itemIndex: itemIndex + 1
+ *           });
+ *         }
+ *       }
+ *
+ *       return merged;
+ *     }
+ *
+ *     const sequences = [
+ *       [1, 4, 7],
+ *       [2, 5, 8],
+ *       [3, 6, 9]
+ *     ];
+ *     console.log(mergeSortedSequences(sequences)); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * @example
+ * // Use Heap to dynamically maintain the median
+ *     class MedianFinder {
+ *       private low: MaxHeap<number>; // Max heap, stores the smaller half
+ *       private high: MinHeap<number>; // Min heap, stores the larger half
+ *
+ *       constructor() {
+ *         this.low = new MaxHeap<number>([]);
+ *         this.high = new MinHeap<number>([]);
+ *       }
+ *
+ *       addNum(num: number): void {
+ *         if (this.low.isEmpty() || num <= this.low.peek()!) this.low.add(num);
+ *         else this.high.add(num);
+ *
+ *         // Balance heaps
+ *         if (this.low.size > this.high.size + 1) this.high.add(this.low.poll()!);
+ *         else if (this.high.size > this.low.size) this.low.add(this.high.poll()!);
+ *       }
+ *
+ *       findMedian(): number {
+ *         if (this.low.size === this.high.size) return (this.low.peek()! + this.high.peek()!) / 2;
+ *         return this.low.peek()!;
+ *       }
+ *     }
+ *
+ *     const medianFinder = new MedianFinder();
+ *     medianFinder.addNum(10);
+ *     console.log(medianFinder.findMedian()); // 10
+ *     medianFinder.addNum(20);
+ *     console.log(medianFinder.findMedian()); // 15
+ *     medianFinder.addNum(30);
+ *     console.log(medianFinder.findMedian()); // 20
+ *     medianFinder.addNum(40);
+ *     console.log(medianFinder.findMedian()); // 25
+ *     medianFinder.addNum(50);
+ *     console.log(medianFinder.findMedian()); // 30
+ * @example
+ * // Use Heap for load balancing
+ *     function loadBalance(requests: number[], servers: number): number[] {
+ *       const serverHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // min heap
+ *       const serverLoads = new Array(servers).fill(0);
+ *
+ *       for (let i = 0; i < servers; i++) {
+ *         serverHeap.add({ id: i, load: 0 });
+ *       }
+ *
+ *       requests.forEach(req => {
+ *         const server = serverHeap.poll()!;
+ *         serverLoads[server.id] += req;
+ *         server.load += req;
+ *         serverHeap.add(server); // The server after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return serverLoads;
+ *     }
+ *
+ *     const requests = [5, 2, 8, 3, 7];
+ *     console.log(loadBalance(requests, 3)); // [12, 8, 5]
+ * @example
+ * // Use Heap to schedule tasks
+ *     type Task = [string, number];
+ *
+ *     function scheduleTasks(tasks: Task[], machines: number): Map<number, Task[]> {
+ *       const machineHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // Min heap
+ *       const allocation = new Map<number, Task[]>();
+ *
+ *       // Initialize the load on each machine
+ *       for (let i = 0; i < machines; i++) {
+ *         machineHeap.add({ id: i, load: 0 });
+ *         allocation.set(i, []);
+ *       }
+ *
+ *       // Assign tasks
+ *       tasks.forEach(([task, load]) => {
+ *         const machine = machineHeap.poll()!;
+ *         allocation.get(machine.id)!.push([task, load]);
+ *         machine.load += load;
+ *         machineHeap.add(machine); // The machine after updating the load is re-entered into the heap
+ *       });
+ *
+ *       return allocation;
+ *     }
+ *
+ *     const tasks: Task[] = [
+ *       ['Task1', 3],
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task4', 5],
+ *       ['Task5', 4]
+ *     ];
+ *     const expectedMap = new Map<number, Task[]>();
+ *     expectedMap.set(0, [
+ *       ['Task1', 3],
+ *       ['Task4', 5]
+ *     ]);
+ *     expectedMap.set(1, [
+ *       ['Task2', 1],
+ *       ['Task3', 2],
+ *       ['Task5', 4]
+ *     ]);
+ *     console.log(scheduleTasks(tasks, 2)); // expectedMap
+ */
+export declare class Heap<E = unknown, R = never> extends IterableElementBase<E, R> {
+    protected _equals: (a: E, b: E) => boolean;
+    /**
+     * Create a Heap and optionally bulk-insert elements.
+     * @remarks Time O(N), Space O(N)
+     * @param [elements] - Iterable of elements (or raw values if toElementFn is set).
+     * @param [options] - Options such as comparator and toElementFn.
+     * @returns New Heap instance.
+     */
+    constructor(elements?: Iterable<E | R>, options?: HeapOptions<E, R>);
+    protected _elements: E[];
+    /**
+     * Get the backing array of the heap.
+     * @remarks Time O(1), Space O(1)
+     * @returns Internal elements array.
+     */
+    get elements(): E[];
+    /**
+     * Get the number of elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Heap size.
+     */
+    get size(): number;
+    /**
+     * Get the last leaf element.
+     * @remarks Time O(1), Space O(1)
+     * @returns Last element or undefined.
+     */
+    get leaf(): E | undefined;
+    /**
+     * Create a heap of the same class from an iterable.
+     * @remarks Time O(N), Space O(N)
+     * @template T
+     * @template R
+     * @template S
+     * @param [elements] - Iterable of elements or raw records.
+     * @param [options] - Heap options including comparator.
+     * @returns A new heap instance of this class.
+     */
+    static from<T, R = never, S extends Heap<T, R> = Heap<T, R>>(this: new (elements?: Iterable<T | R>, options?: HeapOptions<T, R>) => S, elements?: Iterable<T | R>, options?: HeapOptions<T, R>): S;
+    /**
+     * Build a Heap from an iterable in linear time given a comparator.
+     * @remarks Time O(N), Space O(N)
+     * @template EE
+     * @template RR
+     * @param elements - Iterable of elements.
+     * @param options - Heap options including comparator.
+     * @returns A new Heap built from elements.
+     */
+    static heapify<EE = unknown, RR = never>(elements: Iterable<EE>, options: HeapOptions<EE, RR>): Heap<EE, RR>;
+    /**
+     * Insert an element.
+     * @remarks Time O(1) amortized, Space O(1)
+     * @param element - Element to insert.
+     * @returns True.
+     */
+    add(element: E): boolean;
+    /**
+     * Insert many elements from an iterable.
+     * @remarks Time O(N log N), Space O(1)
+     * @param elements - Iterable of elements or raw values.
+     * @returns Array of per-element success flags.
+     */
+    addMany(elements: Iterable<E | R>): boolean[];
+    /**
+     * Remove and return the top element.
+     * @remarks Time O(log N), Space O(1)
+     * @returns Top element or undefined.
+     */
+    poll(): E | undefined;
+    /**
+     * Get the current top element without removing it.
+     * @remarks Time O(1), Space O(1)
+     * @returns Top element or undefined.
+     */
+    peek(): E | undefined;
+    /**
+     * Check whether the heap is empty.
+     * @remarks Time O(1), Space O(1)
+     * @returns True if size is 0.
+     */
+    isEmpty(): boolean;
+    /**
+     * Remove all elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns void
+     */
+    clear(): void;
+    /**
+     * Replace the backing array and rebuild the heap.
+     * @remarks Time O(N), Space O(N)
+     * @param elements - Iterable used to refill the heap.
+     * @returns Array of per-node results from fixing steps.
+     */
+    refill(elements: Iterable<E>): boolean[];
+    /**
+     * Check if an equal element exists in the heap.
+     * @remarks Time O(N), Space O(1)
+     * @param element - Element to search for.
+     * @returns True if found.
+     */
+    has(element: E): boolean;
+    /**
+     * Delete one occurrence of an element.
+     * @remarks Time O(N), Space O(1)
+     * @param element - Element to delete.
+     * @returns True if an element was removed.
+     */
+    delete(element: E): boolean;
+    /**
+     * Delete the first element that matches a predicate.
+     * @remarks Time O(N), Space O(1)
+     * @param predicate - Function (element, index, heap) → boolean.
+     * @returns True if an element was removed.
+     */
+    deleteBy(predicate: (element: E, index: number, heap: this) => boolean): boolean;
+    /**
+     * Set the equality comparator used by has/delete operations.
+     * @remarks Time O(1), Space O(1)
+     * @param equals - Equality predicate (a, b) → boolean.
+     * @returns This heap.
+     */
+    setEquality(equals: (a: E, b: E) => boolean): this;
+    /**
+     * Traverse the binary heap as a complete binary tree and collect elements.
+     * @remarks Time O(N), Space O(H)
+     * @param [order] - Traversal order: 'PRE' | 'IN' | 'POST'.
+     * @returns Array of visited elements.
+     */
+    dfs(order?: DFSOrderPattern): E[];
+    /**
+     * Restore heap order bottom-up (heapify in-place).
+     * @remarks Time O(N), Space O(1)
+     * @returns Array of per-node results from fixing steps.
+     */
+    fix(): boolean[];
+    /**
+     * Return all elements in ascending order by repeatedly polling.
+     * @remarks Time O(N log N), Space O(N)
+     * @returns Sorted array of elements.
+     */
+    sort(): E[];
+    /**
+     * Deep clone this heap.
+     * @remarks Time O(N), Space O(N)
+     * @returns A new heap with the same elements.
+     */
+    clone(): this;
+    /**
+     * Filter elements into a new heap of the same class.
+     * @remarks Time O(N log N), Space O(N)
+     * @param callback - Predicate (element, index, heap) → boolean to keep element.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new heap with the kept elements.
+     */
+    filter(callback: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
+    /**
+     * Map elements into a new heap of possibly different element type.
+     * @remarks Time O(N log N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param callback - Mapping function (element, index, heap) → newElement.
+     * @param options - Options for the output heap, including comparator for EM.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new heap with mapped elements.
+     */
+    map<EM, RM>(callback: ElementCallback<E, R, EM>, options: HeapOptions<EM, RM> & {
+        comparator: Comparator<EM>;
+    }, thisArg?: unknown): Heap<EM, RM>;
+    /**
+     * Map elements into a new heap of the same element type.
+     * @remarks Time O(N log N), Space O(N)
+     * @param callback - Mapping function (element, index, heap) → element.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new heap with mapped elements.
+     */
+    mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;
+    protected _DEFAULT_COMPARATOR: (a: E, b: E) => number;
+    protected _comparator: Comparator<E>; /**
+     * Get the comparator used to order elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Comparator function.
+     */
+    /**
+     * Get the comparator used to order elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Comparator function.
+     */
+    get comparator(): Comparator<E>;
+    protected _getIterator(): IterableIterator<E>;
+    protected _bubbleUp(index: number): boolean;
+    protected _sinkDown(index: number, halfLength: number): boolean;
+    /**
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @param [options] - Options to override comparator or toElementFn.
+     * @returns A like-kind empty heap instance.
+     */
+    protected _createInstance(options?: HeapOptions<E, R>): this;
+    /**
+     * (Protected) Create a like-kind instance seeded by elements.
+     * @remarks Time O(N log N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param [elements] - Iterable of elements or raw values to seed.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A like-kind heap instance.
+     */
+    protected _createLike<EM, RM>(elements?: Iterable<EM> | Iterable<RM>, options?: HeapOptions<EM, RM>): Heap<EM, RM>;
+    /**
+     * (Protected) Spawn an empty like-kind heap instance.
+     * @remarks Time O(1), Space O(1)
+     * @template EM
+     * @template RM
+     * @param [options] - Options forwarded to the constructor.
+     * @returns An empty like-kind heap instance.
+     */
+    protected _spawnLike<EM, RM>(options?: HeapOptions<EM, RM>): Heap<EM, RM>;
+}
+/**
+ * Node container used by FibonacciHeap.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ */
+export declare class FibonacciHeapNode<E> {
+    element: E;
+    degree: number;
+    left?: FibonacciHeapNode<E>;
+    right?: FibonacciHeapNode<E>;
+    child?: FibonacciHeapNode<E>;
+    parent?: FibonacciHeapNode<E>;
+    marked: boolean;
+    constructor(element: E, degree?: number);
+}
+/**
+ * Fibonacci heap (min-heap) optimized for fast merges and amortized operations.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @example examples will be generated by unit test
+ */
+export declare class FibonacciHeap<E> {
+    /**
+     * Create a FibonacciHeap.
+     * @remarks Time O(1), Space O(1)
+     * @param [comparator] - Comparator to order elements (min-heap by default).
+     * @returns New FibonacciHeap instance.
+     */
+    constructor(comparator?: Comparator<E>);
+    protected _root?: FibonacciHeapNode<E>;
+    /**
+     * Get the circular root list head.
+     * @remarks Time O(1), Space O(1)
+     * @returns Root node or undefined.
+     */
+    get root(): FibonacciHeapNode<E> | undefined;
+    protected _size: number;
+    get size(): number;
+    protected _min?: FibonacciHeapNode<E>;
+    /**
+     * Get the current minimum node.
+     * @remarks Time O(1), Space O(1)
+     * @returns Min node or undefined.
+     */
+    get min(): FibonacciHeapNode<E> | undefined;
+    protected _comparator: Comparator<E>;
+    get comparator(): Comparator<E>;
+    clear(): void;
+    add(element: E): boolean;
+    /**
+     * Push an element into the root list.
+     * @remarks Time O(1) amortized, Space O(1)
+     * @param element - Element to insert.
+     * @returns This heap.
+     */
+    push(element: E): this;
+    peek(): E | undefined;
+    /**
+     * Collect nodes from a circular doubly linked list starting at head.
+     * @remarks Time O(K), Space O(K)
+     * @param [head] - Start node of the circular list.
+     * @returns Array of nodes from the list.
+     */
+    consumeLinkedList(head?: FibonacciHeapNode<E>): FibonacciHeapNode<E>[];
+    /**
+     * Insert a node into a parent's child list (circular).
+     * @remarks Time O(1), Space O(1)
+     * @param parent - Parent node.
+     * @param node - Child node to insert.
+     * @returns void
+     */
+    mergeWithChild(parent: FibonacciHeapNode<E>, node: FibonacciHeapNode<E>): void;
+    poll(): E | undefined;
+    /**
+     * Remove and return the minimum element, consolidating the root list.
+     * @remarks Time O(log N) amortized, Space O(1)
+     * @returns Minimum element or undefined.
+     */
+    pop(): E | undefined;
+    /**
+     * Meld another heap into this heap.
+     * @remarks Time O(1), Space O(1)
+     * @param heapToMerge - Another FibonacciHeap to meld into this one.
+     * @returns void
+     */
+    merge(heapToMerge: FibonacciHeap<E>): void;
+    _createNode(element: E): FibonacciHeapNode<E>;
+    isEmpty(): boolean;
+    protected _defaultComparator(a: E, b: E): number;
+    protected mergeWithRoot(node: FibonacciHeapNode<E>): void;
+    protected removeFromRoot(node: FibonacciHeapNode<E>): void;
+    protected _link(y: FibonacciHeapNode<E>, x: FibonacciHeapNode<E>): void;
+    protected _consolidate(): void;
+}

package/dist/types/data-structures/heap/max-heap.d.ts

@@ -0,0 +1,32 @@
+/**
+ * data-structure-typed
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
+ * @license MIT License
+ */
+import type { HeapOptions } from '../../types';
+import { Heap } from './heap';
+/**
+ * @template E
+ * @template R
+ * Max-oriented binary heap.
+ * Notes and typical use-cases are documented in {@link Heap}.
+ *
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. Heap Properties: The value of each parent node is greater than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum-spanning tree algorithm, which use heaps to improve performance.
+ * @example
+ */
+export declare class MaxHeap<E = any, R = any> extends Heap<E, R> {
+    /**
+     * Create a max-heap. For objects, supply a custom comparator.
+     * @param elements Optional initial elements.
+     * @param options Optional configuration.
+     */
+    constructor(elements?: Iterable<E> | Iterable<R>, options?: HeapOptions<E, R>);
+}

package/dist/types/data-structures/heap/min-heap.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @remarks Time O(n log n), Space O(n).
+ * data-structure-typed
+ * @author Kirk Qi
+ * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
+ * @license MIT License
+ */
+import type { HeapOptions } from '../../types';
+import { Heap } from './heap';
+/**
+ * @template E
+ * @template R
+ * Min-oriented binary heap.
+ * Notes and typical use-cases are documented in {@link Heap}.
+ *
+ * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
+ * 2. MinHeap Properties:  The value of each parent node is less than or equal to the value of its children.
+ * 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
+ * 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
+ * 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
+ * 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
+ * 7. Efficient Sorting Algorithms: For example, heap sort. MinHeap sort uses the properties of a heap to sort elements.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
+ * @example
+ */
+export declare class MinHeap<E = any, R = any> extends Heap<E, R> {
+    /**
+     * Create a min-heap.
+     * @param elements Optional initial elements.
+     * @param options Optional configuration.
+     */
+    constructor(elements?: Iterable<E> | Iterable<R>, options?: HeapOptions<E, R>);
+}