Tweaks

Author: sindresorhus

package.json

@@ -47,13 +47,13 @@
 		"bluebird"
 	],
 	"dependencies": {
-		"eventemitter3": "^5.0.1",
+		"eventemitter3": "^5.0.4",
 		"p-timeout": "^7.0.0"
 	},
 	"devDependencies": {
 		"@sindresorhus/tsconfig": "^8.0.1",
 		"@types/benchmark": "^2.1.5",
-		"@types/node": "^24.5.1",
+		"@types/node": "^25.6.0",
 		"benchmark": "^2.1.4",
 		"del-cli": "^6.0.0",
 		"delay": "^6.0.0",

source/priority-queue.ts

@@ -11,7 +11,7 @@ export type PriorityQueueOptions = {
 export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOptions> {
 	readonly #queue: Array<PriorityQueueOptions & {run: RunFunction}> = [];
 
-	// Index of the next item to dequeue. Old items are compacted lazily so dequeue stays O(1).
+	// The queue is stored as a sorted array, but dequeued items are left before `#head` until compaction. Only items from `#head` onward are live, which keeps repeated dequeues amortized O(1).
 	#head = 0;
 
 	enqueue(run: RunFunction, options?: Partial<PriorityQueueOptions>): void {
@@ -28,23 +28,27 @@ export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOp
 		};
 
 		if (size === 0) {
+			// When the queue is logically empty, discard any consumed prefix before accepting new work.
 			this.#queue.length = 0;
 			this.#head = 0;
 			this.#queue.push(element);
 			return;
 		}
 
 		if (this.#queue.at(-1)!.priority! >= priority) {
+			// Same-priority and lower-priority items belong after the current tail. Appending preserves FIFO order for equal priorities.
 			this.#queue.push(element);
 			return;
 		}
 
+		// Binary insertion must run on the live sorted range only.
 		this.#compact();
 		const index = lowerBound(this.#queue, element, (a: Readonly<PriorityQueueOptions>, b: Readonly<PriorityQueueOptions>) => b.priority! - a.priority!);
 		this.#queue.splice(index, 0, element);
 	}
 
 	setPriority(id: string, priority: number) {
+		// A dequeued item with the same id is no longer part of the queue.
 		const index = this.#queue.findIndex((element: Readonly<PriorityQueueOptions>, index) => index >= this.#head && element.id === id);
 		if (index === -1) {
 			throw new ReferenceError(`No promise function with the id "${id}" exists in the queue.`);
@@ -58,6 +62,7 @@ export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOp
 	remove(run: RunFunction): void;
 	remove(idOrRun: string | RunFunction): void {
 		const index = this.#queue.findIndex((element: Readonly<PriorityQueueOptions & {run: RunFunction}>, index) => {
+			// The consumed prefix may still contain references that should not be removable.
 			if (index < this.#head) {
 				return false;
 			}
@@ -83,9 +88,11 @@ export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOp
 		this.#head++;
 
 		if (this.#head === this.#queue.length) {
+			// Fully drained queues are reset immediately so the next enqueue starts from a clean array.
 			this.#queue.length = 0;
 			this.#head = 0;
 		} else if (this.#head > compactionThreshold && this.#head > this.#queue.length / 2) {
+			// Keep repeated dequeues cheap, but stop the consumed prefix from growing without bound.
 			this.#compact();
 		}
 
@@ -110,6 +117,7 @@ export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOp
 	}
 
 	#compact(): void {
+		// Compaction restores the invariant that the whole array is the live sorted range.
 		if (this.#head === 0) {
 			return;
 		}

test/priority-queue.ts

@@ -47,6 +47,28 @@ test('PriorityQueue inserts high-priority items correctly after partial dequeue'
 	assert.equal(queue.dequeue(), undefined);
 });
 
+test('PriorityQueue appends same-priority and lower-priority items correctly after partial dequeue', () => {
+	const queue = new PriorityQueue();
+	const first = createRun('first');
+	const second = createRun('second');
+	const samePriority = createRun('samePriority');
+	const lowerPriority = createRun('lowerPriority');
+
+	queue.enqueue(first, {priority: 0});
+	queue.enqueue(second, {priority: 0});
+
+	assert.equal(queue.dequeue(), first);
+
+	queue.enqueue(samePriority, {priority: 0});
+	queue.enqueue(lowerPriority, {priority: -1});
+
+	assert.equal(queue.size, 3);
+	assert.equal(queue.dequeue(), second);
+	assert.equal(queue.dequeue(), samePriority);
+	assert.equal(queue.dequeue(), lowerPriority);
+	assert.equal(queue.dequeue(), undefined);
+});
+
 test('PriorityQueue removes the live duplicate id after partial dequeue', () => {
 	const queue = new PriorityQueue();
 	const first = createRun('first');
@@ -85,30 +107,57 @@ test('PriorityQueue removes by run after partial dequeue', () => {
 	assert.equal(queue.dequeue(), undefined);
 });
 
+test('PriorityQueue ignores consumed items with no live match', () => {
+	const queue = new PriorityQueue();
+	const first = createRun('first');
+	const second = createRun('second');
+
+	queue.enqueue(first, {id: 'first'});
+	queue.enqueue(second, {id: 'second'});
+
+	assert.equal(queue.dequeue(), first);
+
+	assert.throws(
+		() => {
+			queue.setPriority('first', 1);
+		},
+		{
+			name: 'ReferenceError',
+			message: 'No promise function with the id "first" exists in the queue.',
+		},
+	);
+
+	queue.remove(first);
+
+	assert.equal(queue.size, 1);
+	assert.equal(queue.dequeue(), second);
+	assert.equal(queue.dequeue(), undefined);
+});
+
 test('PriorityQueue stays ordered after cursor compaction', () => {
 	const queue = new PriorityQueue();
 	const urgent = createRun('urgent');
+	const tasks = Array.from({length: 150}, (_element, index) => createRun(`task-${index}`));
 
-	for (let index = 0; index < 150; index++) {
-		queue.enqueue(createRun(`task-${index}`));
+	for (const task of tasks) {
+		queue.enqueue(task);
 	}
 
 	// Cross the compaction threshold while leaving queued items behind.
 	for (let index = 0; index < 120; index++) {
-		assert.notEqual(queue.dequeue(), undefined);
+		assert.equal(queue.dequeue(), tasks[index]);
 	}
 
 	queue.enqueue(urgent, {priority: 1});
 
 	assert.equal(queue.size, 31);
 	assert.equal(queue.dequeue(), urgent);
 
-	let remaining = 0;
-	while (queue.dequeue() !== undefined) {
-		remaining++;
+	for (let index = 120; index < tasks.length; index++) {
+		assert.equal(queue.dequeue(), tasks[index]);
 	}
 
-	assert.equal(remaining, 30);
+	assert.equal(queue.dequeue(), undefined);
 	assert.equal(queue.size, 0);
 });