list-toolkit 2.2.5 → 2.3.0

package/src/heap/min-heap.d.ts

@@ -0,0 +1,270 @@
+import HeapBase, {HeapOptions} from './basics.js';
+
+/** Array-based binary min-heap. */
+export class MinHeap<T = unknown> extends HeapBase<T> {
+  /** The underlying array storing heap elements. */
+  array: T[];
+
+  /**
+   * @param options - Ordering functions.
+   * @param args - Initial arrays or heaps to merge.
+   */
+  constructor(options?: HeapOptions<T>, ...args: Array<MinHeap<T> | T[]>);
+
+  /** Number of elements in the heap. */
+  get length(): number;
+
+  /** Whether the heap has no elements. */
+  get isEmpty(): boolean;
+
+  /** The minimum element without removing it. */
+  get top(): T | undefined;
+
+  /** Alias for {@link top}. */
+  peek(): T | undefined;
+
+  /**
+   * Remove and return the minimum element.
+   * @returns The minimum element, or `undefined` if empty.
+   */
+  pop(): T | undefined;
+
+  /**
+   * Insert a value into the heap.
+   * @param value - Value to insert.
+   * @returns `this` for chaining.
+   */
+  push(value: T): this;
+
+  /**
+   * Push a value then immediately pop the minimum.
+   * @param value - Value to push.
+   * @returns The minimum element after the push.
+   */
+  pushPop(value: T): T;
+
+  /**
+   * Pop the minimum then push a new value.
+   * @param value - Value to push after popping.
+   * @returns The old minimum element.
+   */
+  replaceTop(value: T): T;
+
+  /**
+   * Check whether a value exists in the heap.
+   * @param value - Value to search for.
+   * @returns `true` if found.
+   */
+  has(value: T): boolean;
+
+  /**
+   * Find the index of a value in the underlying array.
+   * @param value - Value to search for.
+   * @returns The index, or `-1` if not found.
+   */
+  findIndex(value: T): number;
+
+  /**
+   * Remove a value from the heap.
+   * @param value - Value to remove.
+   * @returns `this` for chaining.
+   */
+  remove(value: T): this;
+
+  /**
+   * Remove an element by its array index.
+   * @param index - Index to remove.
+   * @returns `this` for chaining.
+   */
+  removeByIndex(index: number): this;
+
+  /**
+   * Replace a value with a new one.
+   * @param value - Value to find and replace.
+   * @param newValue - Replacement value.
+   * @returns `this` for chaining.
+   */
+  replace(value: T, newValue: T): this;
+
+  /**
+   * Replace an element at a given index.
+   * @param index - Index to replace.
+   * @param newValue - Replacement value.
+   * @returns `this` for chaining.
+   */
+  replaceByIndex(index: number, newValue: T): this;
+
+  /**
+   * Re-sift the top element downward after an in-place mutation.
+   * @returns `this` for chaining.
+   */
+  updateTop(): this;
+
+  /**
+   * Re-sift an element at a given index after an in-place mutation.
+   * @param index - Index of the mutated element.
+   * @param isDecreased - `true` if the key decreased (sift up), `false` to sift down.
+   * @returns `this` for chaining.
+   */
+  updateByIndex(index: number, isDecreased: boolean): this;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /**
+   * Sort the array in place and release it, leaving the heap empty.
+   * @returns The sorted array.
+   */
+  releaseSorted(): T[];
+
+  /**
+   * Merge other heaps or arrays into this heap.
+   * @param args - Heaps or arrays to merge.
+   * @returns `this` for chaining.
+   */
+  merge(...args: Array<MinHeap<T> | T[]>): this;
+
+  /**
+   * Create a deep copy of this heap.
+   * @returns A new MinHeap with the same elements.
+   */
+  clone(): MinHeap<T>;
+
+  /**
+   * Build a heap-ordered array in place.
+   * @param array - Array to heapify.
+   * @param less - Ordering function.
+   * @returns The heapified array.
+   */
+  static build<T = unknown>(array: T[], less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Pop the minimum from a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param less - Ordering function.
+   * @returns The minimum element, or `undefined` if empty.
+   */
+  static pop<T = unknown>(heapArray: T[], less?: (a: T, b: T) => boolean): T | undefined;
+
+  /**
+   * Push a value onto a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to push.
+   * @param less - Ordering function.
+   * @returns The array.
+   */
+  static push<T = unknown>(heapArray: T[], item: T, less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Push then pop in one operation on a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to push.
+   * @param less - Ordering function.
+   * @returns The minimum element.
+   */
+  static pushPop<T = unknown>(heapArray: T[], item: T, less?: (a: T, b: T) => boolean): T;
+
+  /**
+   * Replace the top of a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Replacement value.
+   * @param less - Ordering function.
+   * @returns The old top element.
+   */
+  static replaceTop<T = unknown>(heapArray: T[], item: T, less?: (a: T, b: T) => boolean): T;
+
+  /**
+   * Check whether a value exists in a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to search for.
+   * @param equal - Equality function.
+   * @returns `true` if found.
+   */
+  static has<T = unknown>(heapArray: T[], item: T, equal?: (a: T, b: T) => boolean): boolean;
+
+  /**
+   * Find the index of a value in a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to search for.
+   * @param equal - Equality function.
+   * @returns The index, or `-1` if not found.
+   */
+  static findIndex<T = unknown>(heapArray: T[], item: T, equal?: (a: T, b: T) => boolean): number;
+
+  /**
+   * Remove an element by index from a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param index - Index to remove.
+   * @param less - Ordering function.
+   * @returns The array.
+   */
+  static removeByIndex<T = unknown>(heapArray: T[], index: number, less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Remove a value from a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to remove.
+   * @param less - Ordering function.
+   * @param equal - Equality function.
+   * @returns The array.
+   */
+  static remove<T = unknown>(heapArray: T[], item: T, less?: (a: T, b: T) => boolean, equal?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Replace an element at a given index in a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param index - Index to replace.
+   * @param newItem - Replacement value.
+   * @param less - Ordering function.
+   * @returns The array.
+   */
+  static replaceByIndex<T = unknown>(heapArray: T[], index: number, newItem: T, less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Replace a value in a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param item - Value to find and replace.
+   * @param newItem - Replacement value.
+   * @param less - Ordering function.
+   * @param equal - Equality function.
+   * @returns The array.
+   */
+  static replace<T = unknown>(
+    heapArray: T[],
+    item: T,
+    newItem: T,
+    less?: (a: T, b: T) => boolean,
+    equal?: (a: T, b: T) => boolean
+  ): T[];
+
+  /**
+   * Re-sift an element at a given index in a heap array.
+   * @param heapArray - Heap-ordered array.
+   * @param index - Index of the mutated element.
+   * @param isDecreased - `true` if the key decreased.
+   * @param less - Ordering function.
+   * @returns The array.
+   */
+  static updateByIndex<T = unknown>(heapArray: T[], index: number, isDecreased: boolean, less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Heap-sort an array in place (ascending order).
+   * @param heapArray - Heap-ordered array.
+   * @param less - Ordering function.
+   * @returns The sorted array.
+   */
+  static sort<T = unknown>(heapArray: T[], less?: (a: T, b: T) => boolean): T[];
+
+  /**
+   * Build a MinHeap from an array.
+   * @param array - Array of values.
+   * @param options - Ordering functions.
+   * @returns A new MinHeap.
+   */
+  static from<T = unknown>(array: T[], options?: HeapOptions<T>): MinHeap<T>;
+}
+
+export default MinHeap;

package/src/heap/min-heap.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import HeapBase from './basics.js';
 
 // the following functions are inlined:
@@ -35,7 +33,12 @@ const down = (array, i, less = defaultLess, n = array.length) => {
   return array;
 };
 
+/** Array-based binary min-heap. */
 export class MinHeap extends HeapBase {
+  /**
+   * @param {object} [options] - Ordering options (`less`, `equal`, `compare`).
+   * @param {...Iterable} args - Initial arrays or heaps to merge.
+   */
   constructor(options, ...args) {
     super(options);
     if (typeof this.compare == 'function') {
@@ -46,22 +49,30 @@ export class MinHeap extends HeapBase {
     if (args.length) this.merge(...args);
   }
 
+  /** The number of elements. */
   get length() {
     return this.array.length;
   }
 
+  /** Whether the heap has no elements. */
   get isEmpty() {
     return !this.array.length;
   }
 
+  /** The minimum element without removing it. */
   get top() {
     return this.array[0];
   }
 
+  /** Alias for {@link MinHeap#top|top}. */
   peek() {
     return this.array[0];
   }
 
+  /**
+   * Remove and return the minimum element.
+   * @returns {*} The removed element, or `undefined` if empty.
+   */
   pop() {
     // return MinHeap.pop(this.array, this.less); // inlined
     switch (this.array.length) {
@@ -89,6 +100,11 @@ export class MinHeap extends HeapBase {
     return top;
   }
 
+  /**
+   * Add an element to the heap.
+   * @param {*} value - Element to add.
+   * @returns {MinHeap} `this` for chaining.
+   */
   push(value) {
     // MinHeap.push(this.array, value, this.less); // inlined
     let i = this.array.length;
@@ -104,6 +120,11 @@ export class MinHeap extends HeapBase {
     return this;
   }
 
+  /**
+   * Push then pop in one operation.
+   * @param {*} value - Element to push.
+   * @returns {*} The popped element.
+   */
   pushPop(value) {
     // return MinHeap.pushPop(this.array, value, this.less); // inlined
     if (!this.array.length || this.less(value, this.array[0])) return value;
@@ -126,6 +147,11 @@ export class MinHeap extends HeapBase {
     return top;
   }
 
+  /**
+   * Pop then push in one operation.
+   * @param {*} value - Element to push.
+   * @returns {*} The previously minimum element.
+   */
   replaceTop(value) {
     // return MinHeap.replaceTop(this.array, value, this.less); // inlined
     const top = this.array[0];
@@ -147,50 +173,100 @@ export class MinHeap extends HeapBase {
     return top;
   }
 
+  /**
+   * Check whether a value exists in the heap.
+   * @param {*} value - Value to search for.
+   * @returns {boolean} `true` if found.
+   */
   has(value) {
     // return MinHeap.has(this.array, value, this.equal); // inlined
     return this.array.findIndex(element => this.equal(element, value)) >= 0;
   }
 
+  /**
+   * Find the index of a value.
+   * @param {*} value - Value to search for.
+   * @returns {number} The index, or `-1` if not found.
+   */
   findIndex(value) {
     return this.array.findIndex(element => this.equal(element, value));
   }
 
+  /**
+   * Remove a value from the heap.
+   * @param {*} value - Value to remove.
+   * @returns {MinHeap} `this` for chaining.
+   */
   remove(value) {
     MinHeap.remove(this.array, value, this.less, this.equal);
     return this;
   }
 
+  /**
+   * Remove an element by its array index.
+   * @param {number} index - Index to remove.
+   * @returns {MinHeap} `this` for chaining.
+   */
   removeByIndex(index) {
     MinHeap.removeByIndex(this.array, index, this.less);
     return this;
   }
 
+  /**
+   * Replace a value with a new one.
+   * @param {*} value - Value to find.
+   * @param {*} newValue - Replacement value.
+   * @returns {MinHeap} `this` for chaining.
+   */
   replace(value, newValue) {
     MinHeap.replace(this.array, value, newValue, this.less, this.equal);
     return this;
   }
 
+  /**
+   * Replace an element at a given index.
+   * @param {number} index - Index to replace.
+   * @param {*} newValue - Replacement value.
+   * @returns {MinHeap} `this` for chaining.
+   */
   replaceByIndex(index, newValue) {
     MinHeap.replaceByIndex(this.array, index, newValue, this.less);
     return this;
   }
 
+  /**
+   * Re-heapify after the top element has been mutated.
+   * @returns {MinHeap} `this` for chaining.
+   */
   updateTop() {
     down(this.array, 0, this.less);
     return this;
   }
 
+  /**
+   * Re-heapify after an element at a given index has been mutated.
+   * @param {number} index - Index of the mutated element.
+   * @param {boolean} isDecreased - `true` if the key decreased.
+   * @returns {MinHeap} `this` for chaining.
+   */
   updateByIndex(index, isDecreased) {
     MinHeap.updateByIndex(this.array, index, isDecreased, this.less);
     return this;
   }
 
+  /**
+   * Remove all elements.
+   * @returns {MinHeap} `this` for chaining.
+   */
   clear() {
     this.array = [];
     return this;
   }
 
+  /**
+   * Sort the internal array in place and release it, clearing the heap.
+   * @returns {Array} The sorted array.
+   */
   releaseSorted() {
     MinHeap.sort(this.array, this.less);
     const array = this.array;
@@ -198,6 +274,11 @@ export class MinHeap extends HeapBase {
     return array;
   }
 
+  /**
+   * Merge one or more iterables or heaps into this heap.
+   * @param {...Iterable} args - Arrays or MinHeaps to merge.
+   * @returns {MinHeap} `this` for chaining.
+   */
   merge(...args) {
     if (!args.length) return this;
     this.array = MinHeap.build(
@@ -213,12 +294,22 @@ export class MinHeap extends HeapBase {
     return this;
   }
 
+  /**
+   * Create a shallow copy of this heap.
+   * @returns {MinHeap} A new MinHeap with the same elements.
+   */
   clone() {
     const heap = new MinHeap(this);
     heap.array = this.array.slice(0);
     return heap;
   }
 
+  /**
+   * Build a heap from an array in place.
+   * @param {Array} array - Array to heapify.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The heapified array.
+   */
   static build(array, less = MinHeap.defaults.less) {
     if (array.length <= 1) return array;
     for (let n = array.length, j = (n >> 1) - 1; j >= 0; --j) {
@@ -239,6 +330,12 @@ export class MinHeap extends HeapBase {
     return array;
   }
 
+  /**
+   * Pop the minimum from a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {Function} [less] - Ordering function.
+   * @returns {*} The removed element.
+   */
   static pop(heapArray, less = MinHeap.defaults.less) {
     switch (heapArray.length) {
       case 0:
@@ -252,17 +349,38 @@ export class MinHeap extends HeapBase {
     return top;
   }
 
+  /**
+   * Push an item onto a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Element to add.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The heap array.
+   */
   static push(heapArray, item, less = MinHeap.defaults.less) {
     const i = heapArray.length;
     heapArray.push(item);
     return up(heapArray, i, less);
   }
 
+  /**
+   * Push then pop on a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Element to push.
+   * @param {Function} [less] - Ordering function.
+   * @returns {*} The popped element.
+   */
   static pushPop(heapArray, item, less = MinHeap.defaults.less) {
     if (!heapArray.length || less(item, heapArray[0])) return item;
     return MinHeap.replaceTop(heapArray, item, less);
   }
 
+  /**
+   * Replace the top of a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Replacement element.
+   * @param {Function} [less] - Ordering function.
+   * @returns {*} The previous top.
+   */
   static replaceTop(heapArray, item, less = MinHeap.defaults.less) {
     const top = heapArray[0];
     heapArray[0] = item;
@@ -270,14 +388,35 @@ export class MinHeap extends HeapBase {
     return top;
   }
 
+  /**
+   * Check whether a value exists in a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Value to search for.
+   * @param {Function} [equal] - Equality function.
+   * @returns {boolean} `true` if found.
+   */
   static has(heapArray, item, equal = MinHeap.defaults.equal) {
     return heapArray.findIndex(element => equal(element, item)) >= 0;
   }
 
+  /**
+   * Find the index of a value in a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Value to search for.
+   * @param {Function} [equal] - Equality function.
+   * @returns {number} The index, or `-1` if not found.
+   */
   static findIndex(heapArray, item, equal = MinHeap.defaults.equal) {
     return heapArray.findIndex(element => equal(element, item));
   }
 
+  /**
+   * Remove an element by index from a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {number} index - Index to remove.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The heap array.
+   */
   static removeByIndex(heapArray, index, less = MinHeap.defaults.less) {
     if (index < 0 || index >= heapArray.length) return this;
     const last = heapArray.length - 1;
@@ -290,11 +429,27 @@ export class MinHeap extends HeapBase {
     return heapArray;
   }
 
+  /**
+   * Remove a value from a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Value to remove.
+   * @param {Function} [less] - Ordering function.
+   * @param {Function} [equal] - Equality function.
+   * @returns {Array} The heap array.
+   */
   static remove(heapArray, item, less = MinHeap.defaults.less, equal = MinHeap.defaults.equal) {
     const index = heapArray.findIndex(element => equal(element, item));
     return MinHeap.removeByIndex(heapArray, index, less);
   }
 
+  /**
+   * Replace an element at a given index in a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {number} index - Index to replace.
+   * @param {*} newItem - Replacement element.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The heap array.
+   */
   static replaceByIndex(heapArray, index, newItem, less = MinHeap.defaults.less) {
     if (index < 0 || index >= heapArray.length) return this;
     const item = heapArray[index];
@@ -302,16 +457,39 @@ export class MinHeap extends HeapBase {
     return MinHeap.updateByIndex(heapArray, index, less(newItem, item), less);
   }
 
+  /**
+   * Replace a value in a heap array.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {*} item - Value to find.
+   * @param {*} newItem - Replacement value.
+   * @param {Function} [less] - Ordering function.
+   * @param {Function} [equal] - Equality function.
+   * @returns {Array} The heap array.
+   */
   static replace(heapArray, item, newItem, less = MinHeap.defaults.less, equal = MinHeap.defaults.equal) {
     const index = heapArray.findIndex(element => equal(element, item));
     return MinHeap.replaceByIndex(heapArray, index, newItem, less);
   }
 
+  /**
+   * Re-heapify after an element at a given index has been mutated.
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {number} index - Index of the mutated element.
+   * @param {boolean} isDecreased - `true` if the key decreased.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The heap array.
+   */
   static updateByIndex(heapArray, index, isDecreased, less = MinHeap.defaults.less) {
     if (index < 0 || index >= heapArray.length) return this;
     return (isDecreased ? up : down)(heapArray, index, less);
   }
 
+  /**
+   * Sort a heap array in place (heap sort).
+   * @param {Array} heapArray - Heap-ordered array.
+   * @param {Function} [less] - Ordering function.
+   * @returns {Array} The sorted array.
+   */
   static sort(heapArray, less = MinHeap.defaults.less) {
     if (heapArray.length <= 1) return heapArray;
     for (let n = heapArray.length - 1; n; --n) {
@@ -321,6 +499,12 @@ export class MinHeap extends HeapBase {
     return heapArray;
   }
 
+  /**
+   * Build a MinHeap from an existing array.
+   * @param {Array} array - Array of elements.
+   * @param {object} [options] - Ordering options.
+   * @returns {MinHeap} A new MinHeap.
+   */
   static from(array, options = MinHeap.defaults) {
     const heap = new MinHeap(options);
     heap.array = MinHeap.build(array, heap.less);