deque-typed 2.1.0 → 2.1.2

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

@@ -1,503 +0,0 @@
-/**
- * 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;
-}