d-ary-heap 2.1.1

package/dist/index.js

@@ -0,0 +1,509 @@
+// src/PriorityQueue.ts
+var PriorityQueue = class _PriorityQueue {
+  /** Array-based heap storage (complete tree representation) */
+  container;
+  /** Maps each item's key to its position in the container for O(1) lookup */
+  positions;
+  /** Number of children per node (arity of the heap) */
+  depth;
+  /** Comparator determining heap order (min vs max) */
+  comparator;
+  /** Key extractor for identity-based lookup */
+  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) {
+    const d = options.d ?? 2;
+    if (d < 1) {
+      throw new Error("Heap arity (d) must be >= 1");
+    }
+    this.depth = d;
+    this.comparator = options.comparator;
+    this.keyExtractor = options.keyExtractor;
+    const capacity = options.initialCapacity ?? 0;
+    this.container = capacity > 0 ? new Array(capacity) : [];
+    if (capacity > 0) this.container.length = 0;
+    this.positions = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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(options, firstItem) {
+    const pq = new _PriorityQueue(options);
+    pq.insert(firstItem);
+    return pq;
+  }
+  // ===========================================================================
+  // Public API - Query Operations
+  // ===========================================================================
+  /**
+   * Get the number of items in the heap.
+   * Time complexity: O(1)
+   */
+  len() {
+    return this.container.length;
+  }
+  /** Alias for len() - backward compatibility */
+  get size() {
+    return this.container.length;
+  }
+  /**
+   * Check if the heap is empty.
+   * Time complexity: O(1)
+   */
+  isEmpty() {
+    return this.container.length === 0;
+  }
+  /** Alias for isEmpty() - snake_case for cross-language consistency */
+  is_empty() {
+    return this.isEmpty();
+  }
+  /**
+   * Get the arity (number of children per node) of the heap.
+   * Time complexity: O(1)
+   */
+  d() {
+    return this.depth;
+  }
+  /**
+   * 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) {
+    return this.positions.has(this.keyExtractor(item));
+  }
+  /**
+   * Check if an item with the given key exists in the heap.
+   * Time complexity: O(1)
+   *
+   * @param key - Key to check directly
+   */
+  containsKey(key) {
+    return this.positions.has(key);
+  }
+  /**
+   * 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) {
+    return this.positions.get(this.keyExtractor(item));
+  }
+  /**
+   * 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) {
+    return this.positions.get(key);
+  }
+  /**
+   * Get the highest-priority item without removing it.
+   * Time complexity: O(1)
+   *
+   * @returns The highest-priority item
+   * @throws Error if heap is empty
+   */
+  front() {
+    const item = this.container[0];
+    if (item === void 0) {
+      throw new Error("front() called on empty priority queue");
+    }
+    return item;
+  }
+  /**
+   * 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() {
+    return this.container.length > 0 ? this.container[0] : void 0;
+  }
+  // ===========================================================================
+  // Public API - Modification Operations
+  // ===========================================================================
+  /**
+   * 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) {
+    const index = this.container.length;
+    this.container.push(item);
+    if (index === 0) {
+      this.positions.set(this.keyExtractor(item), 0);
+      return;
+    }
+    this.positions.set(this.keyExtractor(item), index);
+    this.moveUp(index);
+  }
+  /**
+   * 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) {
+    if (items.length === 0) return;
+    const keyExtractor = this.keyExtractor;
+    const container = this.container;
+    const positions = this.positions;
+    const startIndex = container.length;
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      container.push(item);
+      positions.set(keyExtractor(item), startIndex + i);
+    }
+    if (startIndex === 0 && items.length > 1) {
+      this.heapify();
+    } else {
+      for (let i = startIndex; i < container.length; i++) {
+        this.moveUp(i);
+      }
+    }
+  }
+  /**
+   * Build heap property from unordered array.
+   * Uses Floyd's algorithm - O(n) time complexity.
+   * Called internally by insertMany when starting from empty heap.
+   */
+  heapify() {
+    const n = this.container.length;
+    if (n <= 1) return;
+    const d = this.depth;
+    const lastNonLeaf = (n - 2) / d | 0;
+    for (let i = lastNonLeaf; i >= 0; i--) {
+      this.moveDown(i);
+    }
+  }
+  /**
+   * 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) {
+    const key = this.keyExtractor(updatedItem);
+    const index = this.positions.get(key);
+    if (index === void 0) {
+      throw new Error("Item not found in priority queue");
+    }
+    this.container[index] = updatedItem;
+    this.moveUp(index);
+  }
+  /** Alias for increasePriority() - snake_case for cross-language consistency */
+  increase_priority(updatedItem) {
+    this.increasePriority(updatedItem);
+  }
+  /**
+   * 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) {
+    if (index < 0 || index >= this.container.length) {
+      throw new Error("Index out of bounds");
+    }
+    this.moveUp(index);
+  }
+  /** Alias for increasePriorityByIndex() - snake_case for cross-language consistency */
+  increase_priority_by_index(index) {
+    this.increasePriorityByIndex(index);
+  }
+  /**
+   * 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) {
+    const key = this.keyExtractor(updatedItem);
+    const index = this.positions.get(key);
+    if (index === void 0) {
+      throw new Error("Item not found in priority queue");
+    }
+    this.container[index] = updatedItem;
+    this.moveUp(index);
+    this.moveDown(index);
+  }
+  /** Alias for decreasePriority() - snake_case for cross-language consistency */
+  decrease_priority(updatedItem) {
+    this.decreasePriority(updatedItem);
+  }
+  /**
+   * Remove and return the highest-priority item.
+   * Time complexity: O(d · log_d n)
+   *
+   * @returns The removed item, or undefined if empty
+   */
+  pop() {
+    const container = this.container;
+    const n = container.length;
+    if (n === 0) {
+      return void 0;
+    }
+    const keyExtractor = this.keyExtractor;
+    const top = container[0];
+    this.positions.delete(keyExtractor(top));
+    if (n === 1) {
+      container.length = 0;
+      return top;
+    }
+    const lastItem = container[n - 1];
+    container[0] = lastItem;
+    this.positions.set(keyExtractor(lastItem), 0);
+    container.length = n - 1;
+    this.moveDown(0);
+    return top;
+  }
+  /**
+   * 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) {
+    const result = [];
+    const actualCount = count < this.container.length ? count : this.container.length;
+    for (let i = 0; i < actualCount; i++) {
+      const item = this.pop();
+      if (item !== void 0) {
+        result.push(item);
+      }
+    }
+    return result;
+  }
+  /**
+   * 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) {
+    this.container.length = 0;
+    this.positions.clear();
+    if (newD !== void 0) {
+      if (newD < 1) {
+        throw new Error("Heap arity (d) must be >= 1");
+      }
+      this.depth = newD;
+    }
+  }
+  /**
+   * Get a string representation of the heap contents.
+   * Time complexity: O(n)
+   *
+   * @returns Formatted string showing all items in heap order
+   */
+  toString() {
+    return "{" + this.container.map(String).join(", ") + "}";
+  }
+  /** Alias for toString() - snake_case for cross-language consistency */
+  to_string() {
+    return this.toString();
+  }
+  /**
+   * Get all items in heap order (for debugging/iteration).
+   * Time complexity: O(n) - creates a copy
+   *
+   * @returns Copy of internal array
+   */
+  toArray() {
+    return [...this.container];
+  }
+  /**
+   * Iterate over items in heap order (not priority order).
+   */
+  *[Symbol.iterator]() {
+    for (const item of this.container) {
+      yield item;
+    }
+  }
+  // ===========================================================================
+  // Private Methods - Heap Operations
+  // ===========================================================================
+  /**
+   * Swap two items in the heap and update their position mappings.
+   * V8 optimizes simple swap patterns well.
+   */
+  swap(i, j) {
+    const container = this.container;
+    const temp = container[i];
+    container[i] = container[j];
+    container[j] = temp;
+    this.positions.set(this.keyExtractor(container[i]), i);
+    this.positions.set(this.keyExtractor(container[j]), j);
+  }
+  /**
+   * Find the child with highest priority among all children of node i.
+   */
+  bestChildPosition(i) {
+    const d = this.depth;
+    const container = this.container;
+    const n = container.length;
+    const left = i * d + 1;
+    if (left >= n) return left;
+    let best = left;
+    const right = Math.min((i + 1) * d, n - 1);
+    for (let j = left + 1; j <= right; j++) {
+      if (this.comparator(container[j], container[best])) {
+        best = j;
+      }
+    }
+    return best;
+  }
+  /**
+   * Move an item upward in the heap to restore heap property.
+   * Uses simple swap pattern which V8 optimizes well.
+   */
+  moveUp(i) {
+    const d = this.depth;
+    const container = this.container;
+    while (i > 0) {
+      const p = Math.floor((i - 1) / d);
+      if (this.comparator(container[i], container[p])) {
+        this.swap(i, p);
+        i = p;
+      } else {
+        break;
+      }
+    }
+  }
+  /**
+   * Move an item downward in the heap to restore heap property.
+   */
+  moveDown(i) {
+    const d = this.depth;
+    const container = this.container;
+    while (true) {
+      const firstChild = i * d + 1;
+      if (firstChild >= container.length) break;
+      const best = this.bestChildPosition(i);
+      if (this.comparator(container[best], container[i])) {
+        this.swap(i, best);
+        i = best;
+      } else {
+        break;
+      }
+    }
+  }
+};
+
+// src/comparators.ts
+function minBy(keyFn) {
+  return (a, b) => keyFn(a) < keyFn(b);
+}
+function maxBy(keyFn) {
+  return (a, b) => keyFn(a) > keyFn(b);
+}
+var minNumber = (a, b) => a < b;
+var maxNumber = (a, b) => a > b;
+var minString = (a, b) => a < b;
+var maxString = (a, b) => a > b;
+function reverse(cmp) {
+  return (a, b) => cmp(b, a);
+}
+function chain(...comparators) {
+  return (a, b) => {
+    for (const cmp of comparators) {
+      if (cmp(a, b)) return true;
+      if (cmp(b, a)) return false;
+    }
+    return false;
+  };
+}
+/**
+ * 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
+ */
+/**
+ * Pre-built comparator factories for common use cases.
+ *
+ * @module comparators
+ * @version 2.0.0
+ * @license Apache-2.0
+ */
+/**
+ * d-ary Heap Priority Queue - TypeScript Implementation
+ *
+ * A high-performance, generic d-ary heap priority queue with O(1) item lookup.
+ *
+ * @packageDocumentation
+ * @module d-ary-heap
+ * @version 2.0.0
+ * @license Apache-2.0
+ * @copyright 2023-2025 Eric Jacopin
+ */
+
+export { PriorityQueue, chain, maxBy, maxNumber, maxString, minBy, minNumber, minString, reverse };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,60 @@
+{
+  "type": "module",
+  "name": "d-ary-heap",
+  "version": "2.1.1",
+  "description": "High-performance d-ary heap priority queue with O(1) item lookup, configurable arity, and min/max heap support",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "priority-queue",
+    "heap",
+    "d-ary-heap",
+    "d-heap",
+    "min-heap",
+    "max-heap",
+    "data-structure",
+    "algorithm",
+    "dijkstra",
+    "typescript"
+  ],
+  "author": "Eric Jacopin",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PCfVW/d-Heap-priority-queue"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "eslint": "^9.39.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}