d-ary-heap 2.2.0 → 2.5.0

package/README.md

@@ -1,10 +1,12 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)
 ![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)
 
-# d-Heap Priority Queue (TypeScript) v2.2.0
+# d-Heap Priority Queue (TypeScript) v2.5.0
 
 A high-performance, generic d-ary heap priority queue with O(1) item lookup, supporting both min-heap and max-heap behavior.
 
+**[Live Demo](https://pcfvw.github.io/d-Heap-priority-queue/)** — Interactive visualization with Dijkstra's algorithm
+
 ## Strengths
 
 - **Flexible behavior**: min-heap or max-heap via comparator functions, and configurable arity `d` at construction time.
@@ -13,7 +15,7 @@ A high-performance, generic d-ary heap priority queue with O(1) item lookup, sup
   - O(log_d n): `insert()` and upward reheapification.
   - O(d · log_d n): delete-top (`pop()`), with up to d children examined per level.
 - **O(1) item lookup**: internal Map tracks positions by item key, enabling efficient priority updates.
-- **Practical API**: `insert`, `front`, `peek`, `pop`, `increasePriority`, `decreasePriority`, `isEmpty`, `len`, `contains`.
+- **Practical API**: `insert`, `front`, `peek`, `pop`, `increasePriority`, `decreasePriority`, `updatePriority`, `isEmpty`, `len`, `contains`.
 - **Unified API**: Cross-language standardized methods matching C++, Rust, and Zig implementations.
 - **TypeScript-native**: Full type safety, generics, and IDE support.
 - **Zero dependencies**: No runtime dependencies.
@@ -107,8 +109,12 @@ Options:
 | `increase_priority(item)` | Alias for `increasePriority()` (cross-language compatibility) | O(log_d n) |
 | `increasePriorityByIndex(i)` | Update by index (primary method) | O(log_d n) |
 | `increase_priority_by_index(i)` | Alias for `increasePriorityByIndex()` (cross-language compatibility) | O(log_d n) |
+| `decreasePriorityByIndex(i)` | Update by index (primary method) | O(d · log_d n) |
+| `decrease_priority_by_index(i)` | Alias for `decreasePriorityByIndex()` (cross-language compatibility) | O(d · log_d n) |
 | `decreasePriority(item)` | Update item to lower priority (primary method) | O(d · log_d n) |
 | `decrease_priority(item)` | Alias for `decreasePriority()` (cross-language compatibility) | O(d · log_d n) |
+| `updatePriority(item)` | Update item when direction unknown (primary method) | O((d+1) · log_d n) |
+| `update_priority(item)` | Alias for `updatePriority()` (cross-language compatibility) | O((d+1) · log_d n) |
 | `clear(newD?)` | Remove all items, optionally change arity | O(1) |
 
 ### Utility Methods
@@ -124,8 +130,8 @@ Options:
 
 This TypeScript implementation follows **camelCase** as the primary naming convention (TypeScript/JavaScript standard), with **snake_case aliases** provided for cross-language compatibility:
 
-- **Primary methods**: `isEmpty()`, `increasePriority()`, `decreasePriority()`, `toString()`
-- **Compatibility aliases**: `is_empty()`, `increase_priority()`, `decrease_priority()`, `to_string()`
+- **Primary methods**: `isEmpty()`, `increasePriority()`, `increasePriorityByIndex()`, `decreasePriority()`, `decreasePriorityByIndex()`, `updatePriority()`, `toString()`
+- **Compatibility aliases**: `is_empty()`, `increase_priority()`, `increase_priority_by_index()`, `decrease_priority()`, `decrease_priority_by_index()`, `update_priority()`, `to_string()`
 
 Use the primary camelCase methods for TypeScript/JavaScript projects, and the snake_case aliases when porting code from C++/Rust implementations.
 
@@ -154,12 +160,100 @@ const byPriorityThenTime = chain(
 );
 ```
 
+## Instrumentation (v2.4.0+)
+
+The library provides opt-in instrumentation for counting comparisons during heap operations. This is useful for:
+
+- **Educational purposes**: Understanding theoretical vs actual comparison costs
+- **Benchmarking**: Measuring real comparison counts across different arities
+- **Visualization**: Powering interactive demos that show heap behavior
+
+### Zero-Cost When Disabled
+
+Instrumentation follows a zero-overhead design:
+- No performance impact when not using instrumentation
+- Existing code works unchanged
+- Per-operation tracking distinguishes insert/pop/increasePriority/decreasePriority/updatePriority comparisons
+
+### Usage
+
+```typescript
+import {
+  PriorityQueue,
+  minBy,
+  instrumentComparator,
+  theoreticalInsertComparisons,
+  theoreticalPopComparisons
+} 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.insert({ id: 'C', distance: 3 });
+pq.pop();
+
+// 4. Access statistics
+console.log(comparator.stats);
+// { insert: 3, pop: 2, decreasePriority: 0, increasePriority: 0, updatePriority: 0, total: 5 }
+
+// 5. Compare with theoretical bounds
+const n = 3;
+const d = 4;
+console.log('Theoretical insert (worst):', theoreticalInsertComparisons(n, d));
+console.log('Theoretical pop (worst):', theoreticalPopComparisons(n, d));
+
+// 6. Reset for next measurement
+comparator.stats.reset();
+```
+
+### Theoretical Complexity
+
+For a d-ary heap with n elements:
+
+| Operation        | Comparisons (worst case)       |
+|------------------|--------------------------------|
+| insert           | floor(log_d(n))                |
+| pop              | d × floor(log_d(n))            |
+| increasePriority | floor(log_d(n)) (moveUp only)  |
+| decreasePriority | d × floor(log_d(n)) (moveDown only) |
+| updatePriority   | (d+1) × floor(log_d(n)) (both) |
+
+### 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 |
+
 ## Priority Update Semantics
 
-The `increasePriority()` and `decreasePriority()` methods have an intentionally **asymmetric design**:
+This library uses **importance-based** semantics:
 
 - **`increasePriority()`**: Make an item **more important** (moves toward heap root). Only moves up for O(log_d n) performance.
-- **`decreasePriority()`**: Make an item **less important** (moves toward leaves). Checks both directions for robustness.
+- **`decreasePriority()`**: Make an item **less important** (moves toward leaves). Only moves down for O(d · log_d n) performance.
+- **`updatePriority()`**: Update when direction is **unknown**. Checks both directions for O((d+1) · log_d n) performance.
+
+**When to use each:**
+- Use `increasePriority()` when you know the item became more important
+- Use `decreasePriority()` when you know the item became less important
+- Use `updatePriority()` when you don't know which direction the priority changed
 
 **Heap Context:**
 - **Min-heap**: Lower priority values = higher importance

package/dist/index.cjs

@@ -12,6 +12,10 @@ var PriorityQueue = class _PriorityQueue {
   comparator;
   /** Key extractor for identity-based lookup */
   keyExtractor;
+  /** Optional hook called before operations (for instrumentation) */
+  onBeforeOperation;
+  /** Optional hook called after operations (for instrumentation) */
+  onAfterOperation;
   /**
    * Create a new d-ary heap priority queue.
    *
@@ -36,6 +40,8 @@ var PriorityQueue = class _PriorityQueue {
     this.depth = d;
     this.comparator = options.comparator;
     this.keyExtractor = options.keyExtractor;
+    this.onBeforeOperation = options.onBeforeOperation;
+    this.onAfterOperation = options.onAfterOperation;
     const capacity = options.initialCapacity ?? 0;
     this.container = capacity > 0 ? new Array(capacity) : [];
     if (capacity > 0) this.container.length = 0;
@@ -163,14 +169,17 @@ var PriorityQueue = class _PriorityQueue {
    * to update existing items.
    */
   insert(item) {
+    this.onBeforeOperation?.("insert");
     const index = this.container.length;
     this.container.push(item);
     if (index === 0) {
       this.positions.set(this.keyExtractor(item), 0);
+      this.onAfterOperation?.();
       return;
     }
     this.positions.set(this.keyExtractor(item), index);
     this.moveUp(index);
+    this.onAfterOperation?.();
   }
   /**
    * Insert multiple items into the heap.
@@ -229,13 +238,16 @@ var PriorityQueue = class _PriorityQueue {
    * This method only moves items upward for performance.
    */
   increasePriority(updatedItem) {
+    this.onBeforeOperation?.("increasePriority");
     const key = this.keyExtractor(updatedItem);
     const index = this.positions.get(key);
     if (index === void 0) {
+      this.onAfterOperation?.();
       throw new Error("Item not found in priority queue");
     }
     this.container[index] = updatedItem;
     this.moveUp(index);
+    this.onAfterOperation?.();
   }
   /** Alias for increasePriority() - snake_case for cross-language consistency */
   increase_priority(updatedItem) {
@@ -261,6 +273,28 @@ var PriorityQueue = class _PriorityQueue {
   increase_priority_by_index(index) {
     this.increasePriorityByIndex(index);
   }
+  /**
+   * 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) {
+    if (index < 0 || index >= this.container.length) {
+      throw new Error("Index out of bounds");
+    }
+    this.moveDown(index);
+  }
+  /** Alias for decreasePriorityByIndex() - snake_case for cross-language consistency */
+  decrease_priority_by_index(index) {
+    this.decreasePriorityByIndex(index);
+  }
   /**
    * Decrease the priority of an existing item (move toward leaves).
    * Time complexity: O(d · log_d n)
@@ -271,22 +305,53 @@ var PriorityQueue = class _PriorityQueue {
    * @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) {
+    this.onBeforeOperation?.("decreasePriority");
     const key = this.keyExtractor(updatedItem);
     const index = this.positions.get(key);
     if (index === void 0) {
+      this.onAfterOperation?.();
       throw new Error("Item not found in priority queue");
     }
     this.container[index] = updatedItem;
-    this.moveUp(index);
     this.moveDown(index);
+    this.onAfterOperation?.();
   }
   /** Alias for decreasePriority() - snake_case for cross-language consistency */
   decrease_priority(updatedItem) {
     this.decreasePriority(updatedItem);
   }
+  /**
+   * 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) {
+    this.onBeforeOperation?.("updatePriority");
+    const key = this.keyExtractor(updatedItem);
+    const index = this.positions.get(key);
+    if (index === void 0) {
+      this.onAfterOperation?.();
+      throw new Error("Item not found in priority queue");
+    }
+    this.container[index] = updatedItem;
+    this.moveUp(index);
+    this.moveDown(index);
+    this.onAfterOperation?.();
+  }
+  /** Alias for updatePriority() - snake_case for cross-language consistency */
+  update_priority(updatedItem) {
+    this.updatePriority(updatedItem);
+  }
   /**
    * Remove and return the highest-priority item.
    * Time complexity: O(d · log_d n)
@@ -294,9 +359,11 @@ var PriorityQueue = class _PriorityQueue {
    * @returns The removed item, or undefined if empty
    */
   pop() {
+    this.onBeforeOperation?.("pop");
     const container = this.container;
     const n = container.length;
     if (n === 0) {
+      this.onAfterOperation?.();
       return void 0;
     }
     const keyExtractor = this.keyExtractor;
@@ -304,6 +371,7 @@ var PriorityQueue = class _PriorityQueue {
     this.positions.delete(keyExtractor(top));
     if (n === 1) {
       container.length = 0;
+      this.onAfterOperation?.();
       return top;
     }
     const lastItem = container[n - 1];
@@ -311,6 +379,7 @@ var PriorityQueue = class _PriorityQueue {
     this.positions.set(keyExtractor(lastItem), 0);
     container.length = n - 1;
     this.moveDown(0);
+    this.onAfterOperation?.();
     return top;
   }
   /**
@@ -472,6 +541,73 @@ function chain(...comparators) {
     return false;
   };
 }
+
+// src/instrumentation.ts
+function createComparisonStats() {
+  const stats = {
+    insert: 0,
+    pop: 0,
+    decreasePriority: 0,
+    increasePriority: 0,
+    updatePriority: 0,
+    get total() {
+      return this.insert + this.pop + this.decreasePriority + this.increasePriority + this.updatePriority;
+    },
+    reset() {
+      this.insert = 0;
+      this.pop = 0;
+      this.decreasePriority = 0;
+      this.increasePriority = 0;
+      this.updatePriority = 0;
+    }
+  };
+  return stats;
+}
+function instrumentComparator(comparator) {
+  const stats = createComparisonStats();
+  let currentOperation = null;
+  const instrumented = ((a, b) => {
+    if (currentOperation !== null) {
+      stats[currentOperation]++;
+    }
+    return comparator(a, b);
+  });
+  Object.defineProperty(instrumented, "stats", {
+    value: stats,
+    writable: false,
+    enumerable: true
+  });
+  instrumented.startOperation = (type) => {
+    currentOperation = type;
+  };
+  instrumented.endOperation = () => {
+    currentOperation = null;
+  };
+  return instrumented;
+}
+function theoreticalInsertComparisons(n, d) {
+  if (n <= 1) return 0;
+  return Math.floor(Math.log(n) / Math.log(d));
+}
+function theoreticalPopComparisons(n, d) {
+  if (n <= 1) return 0;
+  const height = Math.floor(Math.log(n) / Math.log(d));
+  return d * height;
+}
+function theoreticalIncreasePriorityComparisons(n, d) {
+  if (n <= 1) return 0;
+  return Math.floor(Math.log(n) / Math.log(d));
+}
+function theoreticalDecreasePriorityComparisons(n, d) {
+  if (n <= 1) return 0;
+  const height = Math.floor(Math.log(n) / Math.log(d));
+  return d * height;
+}
+function theoreticalUpdatePriorityComparisons(n, d) {
+  if (n <= 1) return 0;
+  const height = Math.floor(Math.log(n) / Math.log(d));
+  return (d + 1) * height;
+}
 /**
  * d-ary Heap Priority Queue - TypeScript Implementation
  *
@@ -480,10 +616,12 @@ function chain(...comparators) {
  * - 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
  */
@@ -491,7 +629,86 @@ function chain(...comparators) {
  * Pre-built comparator factories for common use cases.
  *
  * @module comparators
- * @version 2.2.0
+ * @version 2.4.0
+ * @license Apache-2.0
+ */
+/**
+ * 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
  */
 /**
@@ -501,13 +718,15 @@ function chain(...comparators) {
  *
  * @packageDocumentation
  * @module d-ary-heap
- * @version 2.2.0
+ * @version 2.4.0
  * @license Apache-2.0
  * @copyright 2023-2025 Eric Jacopin
  */
 
 exports.PriorityQueue = PriorityQueue;
 exports.chain = chain;
+exports.createComparisonStats = createComparisonStats;
+exports.instrumentComparator = instrumentComparator;
 exports.maxBy = maxBy;
 exports.maxNumber = maxNumber;
 exports.maxString = maxString;
@@ -515,5 +734,10 @@ exports.minBy = minBy;
 exports.minNumber = minNumber;
 exports.minString = minString;
 exports.reverse = reverse;
+exports.theoreticalDecreasePriorityComparisons = theoreticalDecreasePriorityComparisons;
+exports.theoreticalIncreasePriorityComparisons = theoreticalIncreasePriorityComparisons;
+exports.theoreticalInsertComparisons = theoreticalInsertComparisons;
+exports.theoreticalPopComparisons = theoreticalPopComparisons;
+exports.theoreticalUpdatePriorityComparisons = theoreticalUpdatePriorityComparisons;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map