d-ary-heap 2.2.0 → 2.5.0

package/dist/index.d.ts

@@ -1,3 +1,254 @@
+/**
+ * Instrumentation utilities for d-ary heap performance analysis.
+ *
+ * This module provides opt-in instrumentation to count comparisons performed
+ * during heap operations. It is designed for:
+ *
+ * - **Educational purposes**: Understanding the theoretical vs actual cost of heap operations
+ * - **Benchmarking**: Measuring real comparison counts across different arities
+ * - **Visualization**: Powering interactive demos that show heap behavior
+ *
+ * ## Design Philosophy: Zero-Cost When Disabled
+ *
+ * Instrumentation follows these principles:
+ *
+ * 1. **Opt-in only**: No overhead when not using instrumentation
+ * 2. **Non-breaking**: Existing code continues to work unchanged
+ * 3. **Per-operation tracking**: Distinguish insert/pop/decreasePriority comparisons
+ *
+ * ## Cross-Language Consistency
+ *
+ * Currently, instrumentation is implemented in TypeScript only. The table below
+ * shows the idiomatic zero-cost approach for each language, planned for v2.5.0:
+ *
+ * | Language   | Mechanism                        | Overhead When Disabled | Status |
+ * |------------|----------------------------------|------------------------|--------|
+ * | TypeScript | Optional hooks + instrumented comparator | Zero (JIT optimization) | ✅ Implemented |
+ * | Go         | Nil stats pointer                | ~1 cycle (nil check)   | Planned v2.5.0 |
+ * | Rust       | Generic over StatsCollector trait | Zero (monomorphization) | Planned v2.5.0 |
+ * | C++        | Template policy class            | Zero (inlining)        | Planned v2.5.0 |
+ * | Zig        | Comptime bool parameter          | Zero (branch elimination) | Planned v2.5.0 |
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * import { PriorityQueue, minBy, instrumentComparator } from 'd-ary-heap';
+ *
+ * // 1. Wrap your comparator with instrumentation
+ * const comparator = instrumentComparator(minBy((v: Vertex) => v.distance));
+ *
+ * // 2. Create priority queue with operation hooks
+ * const pq = new PriorityQueue({
+ *   d: 4,
+ *   comparator,
+ *   keyExtractor: (v) => v.id,
+ *   onBeforeOperation: (op) => comparator.startOperation(op),
+ *   onAfterOperation: () => comparator.endOperation(),
+ * });
+ *
+ * // 3. Use normally - comparisons are tracked automatically
+ * pq.insert({ id: 'A', distance: 0 });
+ * pq.insert({ id: 'B', distance: 5 });
+ * pq.pop();
+ *
+ * // 4. Access statistics
+ * console.log(comparator.stats);
+ * // { insert: 1, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 3 }
+ *
+ * // 5. Reset for next measurement
+ * comparator.stats.reset();
+ * ```
+ *
+ * ## Theoretical Complexity Reference
+ *
+ * For a d-ary heap with n elements:
+ *
+ * | Operation        | Comparisons (worst case)      |
+ * |------------------|-------------------------------|
+ * | insert           | ⌊log_d(n)⌋                    |
+ * | pop              | d × ⌊log_d(n)⌋                |
+ * | increasePriority | ⌊log_d(n)⌋ (moveUp only)      |
+ * | decreasePriority | d × ⌊log_d(n)⌋ (moveDown only)|
+ * | updatePriority   | (d+1) × ⌊log_d(n)⌋ (both)     |
+ *
+ * The demo visualization compares actual counts against these theoretical bounds.
+ *
+ * @module instrumentation
+ * @version 2.4.0
+ * @license Apache-2.0
+ */
+
+/**
+ * Operation types that can be tracked.
+ *
+ * Note: `updatePriority` is tracked separately for when the caller doesn't know
+ * whether priority increased or decreased (checks both directions).
+ */
+type OperationType = 'insert' | 'pop' | 'decreasePriority' | 'increasePriority' | 'updatePriority';
+/**
+ * Statistics tracking comparison counts per operation type.
+ *
+ * All counts start at zero and accumulate until `reset()` is called.
+ */
+interface ComparisonStats {
+    /** Comparisons during insert operations (moveUp) */
+    insert: number;
+    /** Comparisons during pop operations (moveDown + bestChildPosition) */
+    pop: number;
+    /** Comparisons during decreasePriority operations (moveDown only) */
+    decreasePriority: number;
+    /** Comparisons during increasePriority operations (moveUp only) */
+    increasePriority: number;
+    /** Comparisons during updatePriority operations (moveUp + moveDown) */
+    updatePriority: number;
+    /** Total comparisons across all operation types */
+    readonly total: number;
+    /** Reset all counters to zero */
+    reset(): void;
+}
+/**
+ * An instrumented comparator that tracks comparison counts.
+ *
+ * This extends a regular comparator with:
+ * - `stats`: Current comparison counts
+ * - `startOperation(type)`: Begin tracking for an operation
+ * - `endOperation()`: Stop tracking current operation
+ *
+ * The comparator itself remains a valid `Comparator<T>` and can be used
+ * anywhere a regular comparator is expected.
+ */
+interface InstrumentedComparator<T> extends Comparator<T> {
+    /** Current comparison statistics */
+    readonly stats: ComparisonStats;
+    /**
+     * Signal the start of a heap operation.
+     * Comparisons will be attributed to this operation type until `endOperation()`.
+     *
+     * @param type - The operation type being started
+     */
+    startOperation(type: OperationType): void;
+    /**
+     * Signal the end of the current heap operation.
+     * Subsequent comparisons will not be counted until the next `startOperation()`.
+     */
+    endOperation(): void;
+}
+/**
+ * Create comparison statistics tracker.
+ *
+ * @returns Fresh stats object with all counts at zero
+ *
+ * @example
+ * ```typescript
+ * const stats = createComparisonStats();
+ * stats.insert = 5;
+ * stats.pop = 10;
+ * console.log(stats.total); // 15
+ * stats.reset();
+ * console.log(stats.total); // 0
+ * ```
+ */
+declare function createComparisonStats(): ComparisonStats;
+/**
+ * Wrap a comparator with instrumentation to track comparison counts.
+ *
+ * The returned comparator:
+ * - Behaves identically to the original for comparison purposes
+ * - Tracks how many times it's called, attributed to operation types
+ * - Has zero overhead when `startOperation()` hasn't been called
+ *
+ * ## How It Works
+ *
+ * 1. Call `startOperation('insert')` before `pq.insert()`
+ * 2. The comparator increments `stats.insert` for each comparison
+ * 3. Call `endOperation()` after the operation completes
+ * 4. Repeat for other operations
+ *
+ * The `PriorityQueue` class supports `onBeforeOperation` and `onAfterOperation`
+ * hooks to automate this.
+ *
+ * ## Performance Note
+ *
+ * When `currentOperation` is null (between operations), the instrumented
+ * comparator performs only a single null check before calling the original.
+ * Modern JavaScript engines optimize this extremely well.
+ *
+ * @param comparator - The original comparator to instrument
+ * @returns An instrumented comparator with stats tracking
+ *
+ * @example
+ * ```typescript
+ * import { minBy, instrumentComparator } from 'd-ary-heap';
+ *
+ * const cmp = instrumentComparator(minBy<number, number>(x => x));
+ *
+ * // Manual usage (without hooks)
+ * cmp.startOperation('insert');
+ * console.log(cmp(5, 3)); // false, and stats.insert++
+ * console.log(cmp(3, 5)); // true, and stats.insert++
+ * cmp.endOperation();
+ *
+ * console.log(cmp.stats.insert); // 2
+ * ```
+ */
+declare function instrumentComparator<T>(comparator: Comparator<T>): InstrumentedComparator<T>;
+/**
+ * Calculate theoretical comparison count for an insert operation.
+ *
+ * Insert performs at most ⌊log_d(n)⌋ comparisons (one per level during moveUp).
+ *
+ * @param n - Number of elements in heap AFTER insert
+ * @param d - Heap arity
+ * @returns Theoretical worst-case comparison count
+ */
+declare function theoreticalInsertComparisons(n: number, d: number): number;
+/**
+ * Calculate theoretical comparison count for a pop operation.
+ *
+ * Pop performs at most d × ⌊log_d(n)⌋ comparisons:
+ * - At each level, find best among d children (d-1 comparisons)
+ * - Compare best child with current (1 comparison)
+ * - Total: d comparisons per level × ⌊log_d(n)⌋ levels
+ *
+ * @param n - Number of elements in heap BEFORE pop
+ * @param d - Heap arity
+ * @returns Theoretical worst-case comparison count
+ */
+declare function theoreticalPopComparisons(n: number, d: number): number;
+/**
+ * Calculate theoretical comparison count for an increasePriority operation.
+ *
+ * IncreasePriority performs only moveUp (item became more important).
+ * Worst case: ⌊log_d(n)⌋ comparisons (one per level).
+ *
+ * @param n - Number of elements in heap
+ * @param d - Heap arity
+ * @returns Theoretical worst-case comparison count
+ */
+declare function theoreticalIncreasePriorityComparisons(n: number, d: number): number;
+/**
+ * Calculate theoretical comparison count for a decreasePriority operation.
+ *
+ * DecreasePriority performs only moveDown (item became less important).
+ * Worst case: d × ⌊log_d(n)⌋ comparisons.
+ *
+ * @param n - Number of elements in heap
+ * @param d - Heap arity
+ * @returns Theoretical worst-case comparison count
+ */
+declare function theoreticalDecreasePriorityComparisons(n: number, d: number): number;
+/**
+ * Calculate theoretical comparison count for an updatePriority operation.
+ *
+ * UpdatePriority performs both moveUp and moveDown (direction unknown).
+ * Worst case: (d + 1) × ⌊log_d(n)⌋ comparisons.
+ *
+ * @param n - Number of elements in heap
+ * @param d - Heap arity
+ * @returns Theoretical worst-case comparison count
+ */
+declare function theoreticalUpdatePriorityComparisons(n: number, d: number): number;
+
 /**
  * d-ary Heap Priority Queue - TypeScript Implementation
  *
@@ -6,13 +257,16 @@
  * - 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
+ * - O(log_d n) insert and increasePriority operations
+ * - O(d · log_d n) pop and decreasePriority operations
+ * - O((d+1) · log_d n) updatePriority (bidirectional)
+ * - Optional instrumentation hooks for performance analysis
  *
- * @version 2.2.0
+ * @version 2.4.0
  * @license Apache-2.0
  * @copyright 2023-2025 Eric Jacopin
  */
+
 /** Type alias for position indices (cross-language consistency) */
 type Position = number;
 /**
@@ -37,6 +291,35 @@ interface PriorityQueueOptions<T, K> {
     keyExtractor: KeyExtractor<T, K>;
     /** Initial capacity hint for pre-allocation */
     initialCapacity?: number;
+    /**
+     * Optional hook called before each heap operation.
+     *
+     * This enables opt-in instrumentation for performance analysis without
+     * adding overhead when not used. Pair with an instrumented comparator
+     * to track comparison counts per operation type.
+     *
+     * @param type - The operation about to be performed
+     *
+     * @example
+     * ```typescript
+     * const cmp = instrumentComparator(minBy((v) => v.priority));
+     * const pq = new PriorityQueue({
+     *   comparator: cmp,
+     *   keyExtractor: (v) => v.id,
+     *   onBeforeOperation: (op) => cmp.startOperation(op),
+     *   onAfterOperation: () => cmp.endOperation(),
+     * });
+     * ```
+     *
+     * @see instrumentComparator from './instrumentation'
+     */
+    onBeforeOperation?: (type: OperationType) => void;
+    /**
+     * Optional hook called after each heap operation completes.
+     *
+     * @see onBeforeOperation for usage example
+     */
+    onAfterOperation?: () => void;
 }
 /**
  * Generic d-ary heap priority queue with O(1) lookup.
@@ -56,6 +339,7 @@ interface PriorityQueueOptions<T, K> {
  * - pop(): O(d · log_d n)
  * - increasePriority(): O(log_d n)
  * - decreasePriority(): O(d · log_d n)
+ * - updatePriority(): O((d+1) · log_d n)
  * - contains(): O(1)
  * - len(), isEmpty(), d(): O(1)
  *
@@ -73,6 +357,10 @@ declare class PriorityQueue<T, K = string | number> {
     private readonly comparator;
     /** Key extractor for identity-based lookup */
     private readonly keyExtractor;
+    /** Optional hook called before operations (for instrumentation) */
+    private readonly onBeforeOperation;
+    /** Optional hook called after operations (for instrumentation) */
+    private readonly onAfterOperation;
     /**
      * Create a new d-ary heap priority queue.
      *
@@ -222,6 +510,21 @@ declare class PriorityQueue<T, K = string | number> {
     increasePriorityByIndex(index: number): void;
     /** Alias for increasePriorityByIndex() - snake_case for cross-language consistency */
     increase_priority_by_index(index: number): void;
+    /**
+     * Decrease the priority of the item at the given index.
+     * Time complexity: O(d · 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 decreasePriority() with the item itself.
+     * The item at the given index should already have its priority value updated
+     * in the container before calling this method.
+     */
+    decreasePriorityByIndex(index: number): void;
+    /** Alias for decreasePriorityByIndex() - snake_case for cross-language consistency */
+    decrease_priority_by_index(index: number): void;
     /**
      * Decrease the priority of an existing item (move toward leaves).
      * Time complexity: O(d · log_d n)
@@ -232,11 +535,26 @@ declare class PriorityQueue<T, K = string | number> {
      * @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.
+     * This method only moves items downward. Use updatePriority() if direction is unknown.
      */
     decreasePriority(updatedItem: T): void;
     /** Alias for decreasePriority() - snake_case for cross-language consistency */
     decrease_priority(updatedItem: T): void;
+    /**
+     * Update the priority of an existing item when direction is unknown.
+     * Time complexity: O((d+1) · log_d n) - checks both directions
+     *
+     * @param updatedItem - Item with same identity but updated priority
+     * @throws Error if item not found
+     *
+     * @remarks
+     * Use this method when you don't know whether the priority increased or decreased.
+     * If you know the direction, prefer increasePriority() or decreasePriority() for
+     * better performance (log_d n vs (d+1) · log_d n comparisons).
+     */
+    updatePriority(updatedItem: T): void;
+    /** Alias for updatePriority() - snake_case for cross-language consistency */
+    update_priority(updatedItem: T): void;
     /**
      * Remove and return the highest-priority item.
      * Time complexity: O(d · log_d n)
@@ -305,7 +623,7 @@ declare class PriorityQueue<T, K = string | number> {
  * Pre-built comparator factories for common use cases.
  *
  * @module comparators
- * @version 2.2.0
+ * @version 2.4.0
  * @license Apache-2.0
  */
 
@@ -385,4 +703,4 @@ declare function reverse<T>(cmp: Comparator<T>): Comparator<T>;
  */
 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 };
+export { type Comparator, type ComparisonStats, type InstrumentedComparator, type KeyExtractor, type OperationType, type Position, PriorityQueue, type PriorityQueueOptions, chain, createComparisonStats, instrumentComparator, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse, theoreticalDecreasePriorityComparisons, theoreticalIncreasePriorityComparisons, theoreticalInsertComparisons, theoreticalPopComparisons, theoreticalUpdatePriorityComparisons };