d-ary-heap 2.1.1

package/dist/index.d.cts

@@ -0,0 +1,388 @@
+/**
+ * d-ary Heap Priority Queue - TypeScript Implementation
+ *
+ * A generic d-ary heap (d-heap) priority queue with:
+ * - Configurable arity (d): number of children per node
+ * - Min-heap or max-heap behavior via comparator functions
+ * - O(1) item lookup using Map for efficient priority updates
+ * - O(1) access to highest-priority item
+ * - O(log_d n) insert and priority increase operations
+ * - O(d · log_d n) pop and priority decrease operations
+ *
+ * @version 2.0.0
+ * @license Apache-2.0
+ * @copyright 2023-2025 Eric Jacopin
+ */
+/** Type alias for position indices (cross-language consistency) */
+type Position = number;
+/**
+ * Comparator function type for priority comparison.
+ * Returns true if `a` has higher priority than `b`.
+ */
+type Comparator<T> = (a: T, b: T) => boolean;
+/**
+ * Key extractor function type for identity-based lookup.
+ * Must return a value that can be used as a Map key (string or number recommended).
+ */
+type KeyExtractor<T, K> = (item: T) => K;
+/**
+ * Configuration options for PriorityQueue construction.
+ */
+interface PriorityQueueOptions<T, K> {
+    /** Number of children per node (arity). Must be >= 1. Default: 2 */
+    d?: number;
+    /** Comparator function. Returns true if first arg has higher priority. */
+    comparator: Comparator<T>;
+    /** Key extractor for identity-based lookup. Required for decrease/increase priority. */
+    keyExtractor: KeyExtractor<T, K>;
+    /** Initial capacity hint for pre-allocation */
+    initialCapacity?: number;
+}
+/**
+ * Generic d-ary heap priority queue with O(1) lookup.
+ *
+ * A d-ary heap is a tree structure where:
+ * - Each node has at most d children
+ * - The root contains the highest-priority item
+ * - Each parent has higher priority than all its children
+ * - The tree is complete (filled left-to-right, level by level)
+ *
+ * This implementation uses an array-based representation with O(1) item lookup
+ * via a Map that tracks each item's position in the heap.
+ *
+ * ## Time Complexities
+ * - front(), peek(): O(1)
+ * - insert(): O(log_d n)
+ * - pop(): O(d · log_d n)
+ * - increasePriority(): O(log_d n)
+ * - decreasePriority(): O(d · log_d n)
+ * - contains(): O(1)
+ * - len(), isEmpty(), d(): O(1)
+ *
+ * @typeParam T - Item type stored in the queue
+ * @typeParam K - Key type for identity lookup (typically string or number)
+ */
+declare class PriorityQueue<T, K = string | number> {
+    /** Array-based heap storage (complete tree representation) */
+    private container;
+    /** Maps each item's key to its position in the container for O(1) lookup */
+    private positions;
+    /** Number of children per node (arity of the heap) */
+    private depth;
+    /** Comparator determining heap order (min vs max) */
+    private readonly comparator;
+    /** Key extractor for identity-based lookup */
+    private readonly keyExtractor;
+    /**
+     * Create a new d-ary heap priority queue.
+     *
+     * @param options - Configuration options
+     * @throws Error if d < 1
+     *
+     * @example
+     * ```typescript
+     * // Min-heap by cost
+     * const pq = new PriorityQueue<Item, number>({
+     *   d: 4,
+     *   comparator: (a, b) => a.cost < b.cost,
+     *   keyExtractor: (item) => item.id
+     * });
+     * ```
+     */
+    constructor(options: PriorityQueueOptions<T, K>);
+    /**
+     * Create a new priority queue with an initial item already inserted.
+     * Equivalent to Rust's `with_first()` constructor.
+     *
+     * @param options - Configuration options
+     * @param firstItem - First item to insert
+     * @returns New PriorityQueue with the item already inserted
+     */
+    static withFirst<T, K>(options: PriorityQueueOptions<T, K>, firstItem: T): PriorityQueue<T, K>;
+    /**
+     * Get the number of items in the heap.
+     * Time complexity: O(1)
+     */
+    len(): number;
+    /** Alias for len() - backward compatibility */
+    get size(): number;
+    /**
+     * Check if the heap is empty.
+     * Time complexity: O(1)
+     */
+    isEmpty(): boolean;
+    /** Alias for isEmpty() - snake_case for cross-language consistency */
+    is_empty(): boolean;
+    /**
+     * Get the arity (number of children per node) of the heap.
+     * Time complexity: O(1)
+     */
+    d(): number;
+    /**
+     * Check if an item with the given key exists in the heap.
+     * Time complexity: O(1)
+     *
+     * @param item - Item to check (uses keyExtractor for identity)
+     */
+    contains(item: T): boolean;
+    /**
+     * Check if an item with the given key exists in the heap.
+     * Time complexity: O(1)
+     *
+     * @param key - Key to check directly
+     */
+    containsKey(key: K): boolean;
+    /**
+     * Get the current position (index) of an item in the heap.
+     * Time complexity: O(1)
+     *
+     * @param item - Item to find (uses keyExtractor for identity)
+     * @returns Position index, or undefined if not found
+     */
+    getPosition(item: T): Position | undefined;
+    /**
+     * Get the current position (index) of an item by its key.
+     * Time complexity: O(1)
+     *
+     * @param key - Key to find
+     * @returns Position index, or undefined if not found
+     */
+    getPositionByKey(key: K): Position | undefined;
+    /**
+     * Get the highest-priority item without removing it.
+     * Time complexity: O(1)
+     *
+     * @returns The highest-priority item
+     * @throws Error if heap is empty
+     */
+    front(): T;
+    /**
+     * Get the highest-priority item without removing it.
+     * Safe alternative to front().
+     * Time complexity: O(1)
+     *
+     * @returns The highest-priority item, or undefined if empty
+     */
+    peek(): T | undefined;
+    /**
+     * Insert a new item into the heap.
+     * Time complexity: O(log_d n)
+     *
+     * @param item - Item to insert
+     *
+     * @remarks
+     * If an item with the same key already exists, behavior is undefined.
+     * Use contains() to check first, or use increasePriority()/decreasePriority()
+     * to update existing items.
+     */
+    insert(item: T): void;
+    /**
+     * Insert multiple items into the heap.
+     * Uses heapify algorithm which is O(n) for bulk insertion vs O(n log n) for individual inserts.
+     * Time complexity: O(n) where n is total items after insertion
+     *
+     * @param items - Array of items to insert
+     *
+     * @remarks
+     * More efficient than calling insert() repeatedly when adding many items at once.
+     * If any item has a key that already exists, behavior is undefined.
+     */
+    insertMany(items: T[]): void;
+    /**
+     * Build heap property from unordered array.
+     * Uses Floyd's algorithm - O(n) time complexity.
+     * Called internally by insertMany when starting from empty heap.
+     */
+    private heapify;
+    /**
+     * Increase the priority of an existing item (move toward root).
+     * Time complexity: O(log_d n)
+     *
+     * @param updatedItem - Item with same identity but updated priority
+     * @throws Error if item not found
+     *
+     * @remarks
+     * For min-heap: decreasing the priority value increases importance.
+     * For max-heap: increasing the priority value increases importance.
+     * This method only moves items upward for performance.
+     */
+    increasePriority(updatedItem: T): void;
+    /** Alias for increasePriority() - snake_case for cross-language consistency */
+    increase_priority(updatedItem: T): void;
+    /**
+     * Increase the priority of the item at the given index.
+     * Time complexity: O(log_d n)
+     *
+     * @param index - Index of the item in the heap array
+     * @throws Error if index is out of bounds
+     *
+     * @remarks
+     * This is a lower-level method. Prefer increasePriority() with the item itself.
+     */
+    increasePriorityByIndex(index: number): void;
+    /** Alias for increasePriorityByIndex() - snake_case for cross-language consistency */
+    increase_priority_by_index(index: number): void;
+    /**
+     * Decrease the priority of an existing item (move toward leaves).
+     * Time complexity: O(d · log_d n)
+     *
+     * @param updatedItem - Item with same identity but updated priority
+     * @throws Error if item not found
+     *
+     * @remarks
+     * For min-heap: increasing the priority value decreases importance.
+     * For max-heap: decreasing the priority value decreases importance.
+     * This method checks both directions for robustness.
+     */
+    decreasePriority(updatedItem: T): void;
+    /** Alias for decreasePriority() - snake_case for cross-language consistency */
+    decrease_priority(updatedItem: T): void;
+    /**
+     * Remove and return the highest-priority item.
+     * Time complexity: O(d · log_d n)
+     *
+     * @returns The removed item, or undefined if empty
+     */
+    pop(): T | undefined;
+    /**
+     * Remove and return multiple highest-priority items.
+     * More efficient than calling pop() repeatedly.
+     * Time complexity: O(count · d · log_d n)
+     *
+     * @param count - Number of items to remove
+     * @returns Array of removed items in priority order
+     */
+    popMany(count: number): T[];
+    /**
+     * Clear all items from the heap, optionally changing the arity.
+     * Time complexity: O(1) (references cleared, GC handles memory)
+     *
+     * @param newD - Optional new arity value (must be >= 1 if provided)
+     * @throws Error if newD < 1
+     */
+    clear(newD?: number): void;
+    /**
+     * Get a string representation of the heap contents.
+     * Time complexity: O(n)
+     *
+     * @returns Formatted string showing all items in heap order
+     */
+    toString(): string;
+    /** Alias for toString() - snake_case for cross-language consistency */
+    to_string(): string;
+    /**
+     * Get all items in heap order (for debugging/iteration).
+     * Time complexity: O(n) - creates a copy
+     *
+     * @returns Copy of internal array
+     */
+    toArray(): T[];
+    /**
+     * Iterate over items in heap order (not priority order).
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Swap two items in the heap and update their position mappings.
+     * V8 optimizes simple swap patterns well.
+     */
+    private swap;
+    /**
+     * Find the child with highest priority among all children of node i.
+     */
+    private bestChildPosition;
+    /**
+     * Move an item upward in the heap to restore heap property.
+     * Uses simple swap pattern which V8 optimizes well.
+     */
+    private moveUp;
+    /**
+     * Move an item downward in the heap to restore heap property.
+     */
+    private moveDown;
+}
+
+/**
+ * Pre-built comparator factories for common use cases.
+ *
+ * @module comparators
+ * @version 2.0.0
+ * @license Apache-2.0
+ */
+
+/**
+ * Create a min-heap comparator using a key extractor.
+ * Lower key values have higher priority (appear closer to root).
+ *
+ * @param keyFn - Function to extract the comparable key from an item
+ * @returns Comparator function for min-heap behavior
+ *
+ * @example
+ * ```typescript
+ * const minByCost = minBy<Item, number>(item => item.cost);
+ * ```
+ */
+declare function minBy<T, K>(keyFn: (item: T) => K): Comparator<T>;
+/**
+ * Create a max-heap comparator using a key extractor.
+ * Higher key values have higher priority (appear closer to root).
+ *
+ * @param keyFn - Function to extract the comparable key from an item
+ * @returns Comparator function for max-heap behavior
+ *
+ * @example
+ * ```typescript
+ * const maxByCost = maxBy<Item, number>(item => item.cost);
+ * ```
+ */
+declare function maxBy<T, K>(keyFn: (item: T) => K): Comparator<T>;
+/**
+ * Min-heap comparator for primitive number values.
+ * Lower numbers have higher priority.
+ */
+declare const minNumber: Comparator<number>;
+/**
+ * Max-heap comparator for primitive number values.
+ * Higher numbers have higher priority.
+ */
+declare const maxNumber: Comparator<number>;
+/**
+ * Min-heap comparator for primitive string values.
+ * Lexicographically smaller strings have higher priority.
+ */
+declare const minString: Comparator<string>;
+/**
+ * Max-heap comparator for primitive string values.
+ * Lexicographically larger strings have higher priority.
+ */
+declare const maxString: Comparator<string>;
+/**
+ * Create a comparator that reverses another comparator.
+ *
+ * @param cmp - Original comparator to reverse
+ * @returns Reversed comparator
+ *
+ * @example
+ * ```typescript
+ * const maxByCost = reverse(minBy<Item, number>(item => item.cost));
+ * ```
+ */
+declare function reverse<T>(cmp: Comparator<T>): Comparator<T>;
+/**
+ * Create a comparator that compares by multiple keys in order.
+ * Falls back to subsequent comparators when items are equal.
+ *
+ * @param comparators - Array of comparators to apply in order
+ * @returns Combined comparator
+ *
+ * @example
+ * ```typescript
+ * // Sort by priority first, then by timestamp
+ * const cmp = chain(
+ *   minBy<Task, number>(t => t.priority),
+ *   minBy<Task, number>(t => t.timestamp)
+ * );
+ * ```
+ */
+declare function chain<T>(...comparators: Comparator<T>[]): Comparator<T>;
+
+export { type Comparator, type KeyExtractor, type Position, PriorityQueue, type PriorityQueueOptions, chain, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse };