min-heap-typed 1.51.9 → 1.52.0

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

@@ -16,30 +16,27 @@ import { IterableElementBase } from '../base';
  * 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.
+ * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
  */
-export declare class Heap<E = any> extends IterableElementBase<E> {
+export declare class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>> {
     /**
      * The constructor initializes a heap data structure with optional elements and options.
      * @param elements - The `elements` parameter is an iterable object that contains the initial
-     * elements to be added to the heap. It is an optional parameter and if not provided, the heap will
+     * elements to be added to the heap.
+     * It is an optional parameter, and if not provided, the heap will
      * be initialized as empty.
      * @param [options] - The `options` parameter is an optional object that can contain additional
-     * configuration options for the heap. In this case, it is used to specify a custom comparator
-     * function for comparing elements in the heap. The comparator function is used to determine the
+     * configuration options for the heap.
+     * In this case, it is used to specify a custom comparator
+     * function for comparing elements in the heap.
+     * The comparator function is used to determine the
      * order of elements in the heap.
      */
-    constructor(elements?: Iterable<E>, options?: HeapOptions<E>);
-    protected _comparator: (a: E, b: E) => number;
-    /**
-     * The function returns the value of the _comparator property.
-     * @returns The `_comparator` property is being returned.
-     */
-    get comparator(): (a: E, b: E) => number;
+    constructor(elements?: Iterable<E> | Iterable<R>, options?: HeapOptions<E, R>);
     protected _elements: E[];
     /**
      * The function returns an array of elements.
-     * @returns The elements array is being returned.
+     * @returns The element array is being returned.
      */
     get elements(): E[];
     /**
@@ -57,12 +54,7 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @param elements
      * @param options
      */
-    static heapify<E>(elements: Iterable<E>, options: HeapOptions<E>): Heap<E>;
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     * where n is the number of elements in the heap.
-     */
+    static heapify<E = any, R = any>(elements: Iterable<E>, options: HeapOptions<E, R>): Heap<E>;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -71,23 +63,14 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @param element - The element to be inserted.
      */
     add(element: E): boolean;
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     * where n is the number of elements in the heap.
-     */
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * Remove and return the top element (smallest or largest element) from the heap.
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @returns The top element or undefined if the heap is empty.
      */
     poll(): E | undefined;
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -105,10 +88,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * Reset the elements of the heap. Make the elements empty.
      */
     clear(): void;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -117,10 +96,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @param elements
      */
     refill(elements: E[]): boolean[];
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -131,12 +106,7 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      */
     has(element: E): boolean;
     /**
-     * Time Complexity:  O(n)
-     * Space Complexity: O(1)
-     * The worst-case  O(n) This is because, in the worst case, the element to be deleted is located at the end of the heap (not the root), and after deletion, we may need to reorganize the elements by performing a sinkDown operation.
-     */
-    /**
-     * Time Complexity:  O(n)
+     * Time Complexity: O(n)
      * Space Complexity: O(1)
      *
      * The `delete` function removes an element from an array-like data structure, maintaining the order
@@ -147,11 +117,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * successfully deleted from the array, and `false` if the element was not found in the array.
      */
     delete(element: E): boolean;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(log n)
-     * where log n is the height of the heap.
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -161,10 +126,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @returns An array containing elements traversed in the specified order.
      */
     dfs(order?: DFSOrderPattern): E[];
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -173,10 +134,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @returns An array containing the elements of the heap.
      */
     toArray(): E[];
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -184,11 +141,7 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * Clone the heap, creating a new heap with the same elements.
      * @returns A new Heap instance containing the same elements.
      */
-    clone(): Heap<E>;
-    /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
-     */
+    clone(): Heap<E, R>;
     /**
      * Time Complexity: O(n log n)
      * Space Complexity: O(n)
@@ -197,10 +150,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @returns An array containing the elements sorted in ascending order.
      */
     sort(): E[];
-    /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n log n)
      * Space Complexity: O(n)
@@ -208,10 +157,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * Fix the entire heap to maintain heap properties.
      */
     fix(): boolean[];
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -228,40 +173,40 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @returns The `filter` method is returning a new `Heap` object that contains the elements that pass
      * the filter condition specified by the `callback` function.
      */
-    filter(callback: ElementCallback<E, boolean>, thisArg?: any): Heap<E>;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     */
+    filter(callback: ElementCallback<E, R, boolean, Heap<E, R>>, thisArg?: any): Heap<E, R>;
     /**
-     * Time Complexity: O(n)
+     * Time Complexity: O(n log n)
      * Space Complexity: O(n)
      *
      * The `map` function creates a new heap by applying a callback function to each element of the
      * original heap.
-     * @param callback - The callback parameter is a function that will be called for each element in the
-     * original heap. It takes three arguments: the current element, the index of the current element,
-     * and the original heap itself. The callback function should return a value of type T, which will be
-     * added to the mapped heap.
-     * @param comparator - The `comparator` parameter is a function that is used to compare elements in
-     * the heap. It takes two arguments, `a` and `b`, and returns a negative number if `a` is less than
-     * `b`, a positive number if `a` is greater than `b`, or
+     * @param callback - The `callback` parameter is a function that will be called for each element in
+     * the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
+     * element), and `this` (the heap itself). The callback function should return a value of
+     * @param comparator - The `comparator` parameter is a function that defines the order of the
+     * elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
+     * if `a` should be placed before `b`, a positive number if `a` should be placed after
+     * @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
+     * element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
+     * returns a value of type `T`. This function is used to transform the elements of the original
      * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-     * specify the value of `this` within the callback function. It is used when you want to bind a
-     * specific object as the context for the callback function. If `thisArg` is not provided,
-     * `undefined` is used as
-     * @returns a new instance of the Heap class, which is created using the mapped elements from the
-     * original Heap.
+     * specify the value of `this` within the callback function. It is used to set the context or scope
+     * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
+     * value of
+     * @returns a new instance of the `Heap` class with the mapped elements.
      */
-    map<T>(callback: ElementCallback<E, T>, comparator: Comparator<T>, thisArg?: any): Heap<T>;
+    map<EM, RM>(callback: ElementCallback<E, R, EM, Heap<E, R>>, comparator: Comparator<EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): Heap<EM, RM>;
+    protected _DEFAULT_COMPARATOR: (a: E, b: E) => number;
+    protected _comparator: Comparator<E>;
     /**
-     * The function `_getIterator` returns an iterable iterator for the elements in the class.
+     * The function returns the value of the _comparator property.
+     * @returns The `_comparator` property is being returned.
      */
-    protected _getIterator(): IterableIterator<E>;
+    get comparator(): Comparator<E>;
     /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
+     * The function `_getIterator` returns an iterable iterator for the elements in the class.
      */
+    protected _getIterator(): IterableIterator<E>;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -270,10 +215,6 @@ export declare class Heap<E = any> extends IterableElementBase<E> {
      * @param index - The index of the newly added element.
      */
     protected _bubbleUp(index: number): boolean;
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -343,10 +284,6 @@ export declare class FibonacciHeap<E> {
      * @returns {number} The size of the heap.  Returns 0 if the heap is empty. Returns -1 if the heap is invalid.
      */
     clear(): void;
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -356,10 +293,6 @@ export declare class FibonacciHeap<E> {
      * @returns {FibonacciHeap<E>} FibonacciHeap<E> - The heap itself.
      */
     add(element: E): FibonacciHeap<E>;
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -369,10 +302,6 @@ export declare class FibonacciHeap<E> {
      * @returns {FibonacciHeap<E>} FibonacciHeap<E> - The heap itself.
      */
     push(element: E): FibonacciHeap<E>;
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -412,7 +341,7 @@ export declare class FibonacciHeap<E> {
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * Remove and return the top element (smallest or largest element) from the heap.
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @returns The top element or undefined if the heap is empty.
      */
     poll(): E | undefined;
@@ -424,7 +353,7 @@ export declare class FibonacciHeap<E> {
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * Remove and return the top element (smallest or largest element) from the heap.
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @returns The top element or undefined if the heap is empty.
      */
     pop(): E | undefined;
@@ -472,8 +401,8 @@ export declare class FibonacciHeap<E> {
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
-     *.
-     * Remove and return the top element (smallest or largest element) from the heap.
+     *
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @param node - The node to be removed.
      * @protected
      */
@@ -486,7 +415,7 @@ export declare class FibonacciHeap<E> {
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * Remove and return the top element (smallest or largest element) from the heap.
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @param y
      * @param x
      * @protected
@@ -500,7 +429,7 @@ export declare class FibonacciHeap<E> {
      * Time Complexity: O(n log n)
      * Space Complexity: O(n)
      *
-     * Remove and return the top element (smallest or largest element) from the heap.
+     * Remove and return the top element (the smallest or largest element) from the heap.
      * @protected
      */
     protected _consolidate(): void;