fix: heap corruption in remove(), clone() capacity, and stability index bugs (v1.0.3)

- Fix remove() in PriorityQueue, TypedPriorityQueue, and StableTypedPriorityQueue:
  up/down heap restoration directions were swapped, causing silent heap corruption
  when removing internal elements in queues with >4 elements.

- Fix clone() in TypedPriorityQueue and StableTypedPriorityQueue: used _defaultSize
  instead of actual backing array length, causing RangeError after array growth.

- Fix StablePriorityQueue copy constructor: _index (FIFO stability counter) was not
  copied, breaking insertion order stability in cloned queues.

- Fix StableTypedPriorityQueue.heap getter: missing sindex property on returned nodes.

- Remove duplicate _indices.set() call in StableTypedPriorityQueue.from().

- Fix incorrect JSDoc on peek() in IPriorityQueueLike (said 'Removes all elements').

- Add regression tests for all fixes.

- Add package-lock.json to .gitignore (project uses bun.lockb).

- Bump version to 1.0.3.

Author: iwatakeshi

.gitignore

@@ -42,6 +42,9 @@ build/Release
 node_modules/
 jspm_packages/
 
+# Lock files (project uses bun.lockb)
+package-lock.json
+
 # Snowpack dependency directory (https://snowpack.dev/)
 web_modules/
 

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pq-ts",
-	"version": "1.0.2",
+	"version": "1.0.3",
 	"description": "A priority queue written in TypeScript.",
 	"main": "dist/main.js",
 	"module": "dist/main.mjs",

src/pq.test.ts

@@ -241,4 +241,56 @@ describe("PriorityQueue", () => {
     const priorities = dequeuedItems.map((_, index) => pq2.priorityAt(index, true));
     expect(priorities).toEqual([3, 4, 5]);
   });
-});
+
+  // Regression: remove() with many elements should preserve heap order
+  // (Bug: up/down directions were swapped in remove(), causing heap corruption
+  // when the last element needed to bubble in the opposite direction)
+  it("should maintain heap order after removing an internal element (regression)", () => {
+    const pq = new PriorityQueue<number>();
+    // This specific priority pattern triggers the bug: after removing value 0
+    // (pri=50), the last node (pri=25) must bubble UP past its new parent (pri=30),
+    // but the buggy code called _down instead, leaving it in the wrong position.
+    const priorities = [50, 10, 90, 20, 80, 30, 70, 40, 60, 5, 95, 15, 85, 25];
+    for (let i = 0; i < priorities.length; i++) {
+      pq.enqueue(i, priorities[i]);
+    }
+
+    expect(pq.remove(0)).toBe(true);
+
+    // Verify the heap invariant: parent priority <= child priority
+    const heap = pq.heap;
+    const size = pq.count;
+    for (let i = 1; i < size; i++) {
+      const parentIdx = (i - 1) >> 2;
+      expect(heap[i].priority).toBeGreaterThanOrEqual(heap[parentIdx].priority);
+    }
+
+    // Also verify dequeue order
+    let prev = pq.pop()!;
+    while (!pq.isEmpty()) {
+      const curr = pq.pop()!;
+      expect(curr.priority).toBeGreaterThanOrEqual(prev.priority);
+      prev = curr;
+    }
+  });
+
+  // Regression: remove() should preserve heap for all removals (stress test)
+  it("should maintain heap order after removing any element (regression)", () => {
+    const priorities = [50, 10, 90, 20, 80, 30, 70, 40, 60, 5, 95, 15, 85, 25];
+    for (let removeIdx = 0; removeIdx < priorities.length; removeIdx++) {
+      const pq = new PriorityQueue<number>();
+      for (let i = 0; i < priorities.length; i++) {
+        pq.enqueue(i, priorities[i]);
+      }
+
+      pq.remove(removeIdx);
+
+      let prev = pq.pop()!;
+      while (!pq.isEmpty()) {
+        const curr = pq.pop()!;
+        expect(curr.priority).toBeGreaterThanOrEqual(prev.priority);
+        prev = curr;
+      }
+    }
+  });
+});

src/pq.ts

@@ -257,9 +257,9 @@ export class PriorityQueue<
     if (index < newSize) {
       const lastNode = this._elements[newSize];
       if (this.compare(lastNode, removedElement) < 0) {
-        this._down(lastNode, index);
-      } else {
         this._up(lastNode, index);
+      } else {
+        this._down(lastNode, index);
       }
     }
 

src/stable.pq.test.ts

@@ -286,4 +286,37 @@ describe("StablePriorityQueue", () => {
     const elements = dequeuedItems.map((item) => item?.value);
     expect(elements).toEqual([2, 4, 3, 1]);
   });
-});
+
+  // Regression: clone should copy _index so new inserts into the clone
+  // preserve FIFO stability relative to existing items
+  it("should preserve stability after cloning and enqueueing (regression)", () => {
+    const pq = new StablePriorityQueue<string>();
+    pq.enqueue("a", 1);
+    pq.enqueue("b", 1);
+    pq.enqueue("c", 1);
+
+    const clone = pq.clone();
+    // After clone, inserting "d" with same priority should come after a, b, c
+    clone.enqueue("d", 1);
+
+    expect(clone.toArray()).toEqual(["a", "b", "c", "d"]);
+  });
+
+  // Regression: remove() with many elements should preserve heap + stability
+  it("should maintain heap order after removing internal element (regression)", () => {
+    const pq = new StablePriorityQueue<number>();
+    for (let i = 0; i < 15; i++) {
+      pq.enqueue(i, i % 5); // Groups of 3 items at each priority 0..4
+    }
+
+    // Remove an element from the middle
+    expect(pq.remove(7)).toBe(true);
+
+    let prev = pq.pop()!;
+    while (!pq.isEmpty()) {
+      const curr = pq.pop()!;
+      expect(curr.priority).toBeGreaterThanOrEqual(prev.priority);
+      prev = curr;
+    }
+  });
+});

src/stable.pq.ts

@@ -41,6 +41,7 @@ export class StablePriorityQueue<
       this._elements = [...elements._elements];
       this._size = elements._size;
       this.compare = elements.compare;
+      this._index = elements._index;
     } else if (Array.isArray(elements)) {
       this._elements = new Array(elements.length);
       this.compare = comparer ?? min as Comparer;

src/stable.typed.pq.test.ts

@@ -282,4 +282,45 @@ describe("StableTypedPriorityQueue", () => {
     const elements = dequeuedItems.map((item) => item?.value);
     expect(elements).toEqual([2, 4, 3, 1]);
   });
-});
+
+  // Regression: remove() with many elements should preserve heap + stability
+  it("should maintain heap order after removing an internal element (regression)", () => {
+    const pq = new StableTypedPriorityQueue(Uint32Array, 4);
+    for (let i = 1; i <= 20; i++) {
+      pq.enqueue(i * 10, i);
+    }
+
+    expect(pq.remove(150)).toBe(true);
+    expect(pq.count).toBe(19);
+
+    let prev = pq.pop()!;
+    while (!pq.isEmpty()) {
+      const curr = pq.pop()!;
+      expect(curr.priority).toBeGreaterThanOrEqual(prev.priority);
+      prev = curr;
+    }
+  });
+
+  // Regression: clone() should work after internal array growth
+  it("should clone correctly after the queue has grown beyond initial size (regression)", () => {
+    const pq = new StableTypedPriorityQueue(Uint32Array, 2);
+    for (let i = 0; i < 10; i++) {
+      pq.enqueue(i, i);
+    }
+
+    const clone = pq.clone();
+    expect(clone.count).toBe(10);
+    expect(clone.toArray()).toEqual(pq.toArray());
+  });
+
+  // Regression: heap getter should include sindex for stable nodes
+  it("should include sindex in heap nodes (regression)", () => {
+    const pq = new StableTypedPriorityQueue(Uint32Array, 10);
+    pq.enqueue(1, 5);
+    pq.enqueue(2, 3);
+
+    const nodes = pq.heap;
+    expect(nodes[0]).toHaveProperty("sindex");
+    expect(nodes[1]).toHaveProperty("sindex");
+  });
+});

src/stable.typed.pq.ts

@@ -49,7 +49,7 @@ export class StableTypedPriorityQueue<
     return Array
       .from(this._elements)
       .map((value, index) => ({
-        value, priority: this._priorities[index], nindex: index
+        value, priority: this._priorities[index], nindex: index, sindex: this._indices[index]
       }) as Node);
   }
 
@@ -72,7 +72,8 @@ export class StableTypedPriorityQueue<
   }
 
   clone(): this {
-    const clone = new StableTypedPriorityQueue<Node, Comparer>(this._backend, this._defaultSize, this.compare);
+    const size = Math.max(this._elements.length, this._defaultSize);
+    const clone = new StableTypedPriorityQueue<Node, Comparer>(this._backend, size, this.compare);
     clone._elements.set(this._elements);
     clone._priorities.set(this._priorities);
     clone._indices.set(this._indices);
@@ -102,12 +103,12 @@ export class StableTypedPriorityQueue<
         sindex: this._indices[newSize]
       } as const as Node;
 
-      // If the last element should be "bubbled up" (preserve heap property)
+      // If lastNode has higher or equal priority than removed, it may need to bubble up;
+      // otherwise it has lower priority and must bubble down.
       if (this.compare(removedNode, lastNode) < 0) {
-        this._up(lastNode, index);
-      } else {
-        // Otherwise, it should "bubble down"
         this._down(lastNode, index);
+      } else {
+        this._up(lastNode, index);
       }
     }
 
@@ -301,7 +302,6 @@ export class StableTypedPriorityQueue<
       newQueue._indices.set(queue._indices);
       newQueue._size = queue._size;
       newQueue._sindex = queue._sindex;
-      newQueue._indices.set(queue._indices);
       return newQueue;
     };
 

src/typed.pq.test.ts

@@ -257,4 +257,37 @@ describe("TypedPriorityQueue", () => {
     const priorities = dequeuedItems.map((_, index) => pq2.priorityAt(index, true));
     expect(priorities).toEqual([3, 4, 5]);
   });
-});
+
+  // Regression: remove() with many elements should preserve heap order
+  // (Bug: up/down directions were swapped in remove())
+  it("should maintain heap order after removing an internal element (regression)", () => {
+    const pq = new TypedPriorityQueue(Uint32Array, 4);
+    for (let i = 1; i <= 20; i++) {
+      pq.enqueue(i * 10, i);
+    }
+
+    // Remove an element with high priority value so lastNode must bubble up
+    expect(pq.remove(150)).toBe(true);
+    expect(pq.count).toBe(19);
+
+    let prev = pq.pop()!;
+    while (!pq.isEmpty()) {
+      const curr = pq.pop()!;
+      expect(curr.priority).toBeGreaterThanOrEqual(prev.priority);
+      prev = curr;
+    }
+  });
+
+  // Regression: clone() should work even after internal array growth
+  // (Bug: clone used _defaultSize which is too small after growth)
+  it("should clone correctly after the queue has grown beyond initial size (regression)", () => {
+    const pq = new TypedPriorityQueue(Uint32Array, 2); // tiny initial size
+    for (let i = 0; i < 10; i++) {
+      pq.enqueue(i, i);
+    }
+
+    const clone = pq.clone();
+    expect(clone.count).toBe(10);
+    expect(clone.toArray()).toEqual(pq.toArray());
+  });
+});

src/typed.pq.ts

@@ -77,7 +77,8 @@ export class TypedPriorityQueue<
   }
 
   clone(): this {
-    const clone = new TypedPriorityQueue<Node, Comparer>(this._backend, this._defaultSize, this.compare);
+    const size = Math.max(this._elements.length, this._defaultSize);
+    const clone = new TypedPriorityQueue<Node, Comparer>(this._backend, size, this.compare);
     clone._elements.set(this._elements);
     clone._priorities.set(this._priorities);
     clone._size = this._size;
@@ -103,12 +104,12 @@ export class TypedPriorityQueue<
         nindex: newSize
       } as const as Node;
 
-      // If the last element should be "bubbled up" (preserve heap property)
+      // If lastNode has higher or equal priority than removed, it may need to bubble up;
+      // otherwise it has lower priority and must bubble down.
       if (this.compare(removedNode, lastNode) < 0) {
-        this._up(lastNode, index);
-      } else {
-        // Otherwise, it should "bubble down"
         this._down(lastNode, index);
+      } else {
+        this._up(lastNode, index);
       }
     }