addressable-binary-heaps
Version:
A versatile TypeScript library for addressable binary heaps, delivering optimized and scalable min-heap and max-heap implementations, seamlessly supporting both object-oriented and functional paradigms.
111 lines (108 loc) • 4.14 kB
TypeScript
import { IHeapNode } from '../types.js';
/**
* An abstract base class for implementing heap data structures.
*
* Provides a common interface for both min-heap and max-heap implementations.
*
* @template N - The type of nodes in the heap, must extend `IHeapNode`.
*/
declare abstract class AbstractHeap<N extends IHeapNode = IHeapNode> {
/**
* Returns the current number of elements in the heap.
*
* @returns The number of elements in the heap.
*/
abstract get size(): number;
/**
* Makes the `AbstractHeap` iterable.
*
* *Note*: The traversal follows the order of the underlying array, not the priority order.
*
* @param reversed - If `true`, the iterator will traverse the heap in reverse order.
* @returns An iterator yielding heap elements in the specified order.
*/
abstract [Symbol.iterator](reversed: boolean): Generator<N, void, void>;
/**
* Adds a new node to the heap while maintaining the heap property.
*
* @param node - The node to add to the heap.
*/
abstract add(node: N): void;
/**
* Removes all elements from the heap.
*/
abstract clear(): void;
/**
* Decreases the key value of a heap element by a specified amount.
*
* @param node - The element to modify.
* @param decreaseValue - Amount to decrease the key by.
* @returns `true` if element was found and modified, `false` otherwise.
*/
abstract decrease(node: N, decreaseValue: N['key']): boolean;
/**
* Returns an iterator for traversing all elements in the heap.
*
* *Note*: The traversal follows the order of the underlying array, not the priority order.
*
* @param [reversed=false] - If `true`, the iterator will traverse the heap in reverse order.
* @returns An iterator yielding heap elements in the specified order.
*/
abstract entries(reversed: boolean): Generator<N, void, void>;
/**
* Executes a callback function for each element in the heap.
*
* *Note*: The traversal follows the order of the underlying array, not the priority order.
*/
abstract forEach(
/**
* @param node - Element of each iteration.
* @param index - The index of the current element being processed in the heap.
* @param heapInstance - The heap instance being iterated.
*/
callback: (node: N, index: number, heapInstance: typeof this) => void,
/**
* @param [thisArg] - A value to use as `this` when executing `callback`.
*/
thisArg?: any): void;
/**
* Increases the key value of a heap element by a specified amount.
*
* @param node - The element to modify.
* @param increaseValue - Amount to increase the key by.
* @returns `true` if element was found and modified, `false` otherwise.
*/
abstract increase(node: N, increaseValue: N['key']): boolean;
/**
* Returns an iterator for traversing just the key values in the heap.
*
* *Note*: The traversal follows the order of the underlying array, not the priority order.
*
* @param reversed - If `true`, the iterator will traverse the heap in reverse order.
*/
abstract keys(reversed: boolean): Generator<N['key'], void, void>;
/**
* Returns the top element of the heap without removing it.
* - For min-heaps, returns the minimum element.
* - For max-heaps, returns the maximum element.
*
@returns The top element or `undefined` if heap is empty.
*/
abstract peek(): N | undefined;
/**
* Removes and returns the top element of the heap.
* - For min-heaps, removes the minimum element.
* - For max-heaps, removes the maximum element.
*
* @returns The removed top element or `undefined` if heap is empty.
*/
abstract pop(): N | undefined;
/**
* Removes a specific element from anywhere in the heap.
*
* @param node - The element to remove.
* @returns `true` if element was found and removed, `false` if not found.
*/
abstract remove(node: N): boolean;
}
export { AbstractHeap };