fix(promise-queue): reject newest submissions when queue is full

`maxQueueLength` overflow dropped the HEAD of the queue — the task that
had been waiting longest — and rejected that caller's promise. FIFO
queues conventionally reject at the tail (drop-newest) so patient
submitters aren't punished by a burst of late arrivals. `p-queue` and
bottleneck both default to drop-newest; the old drop-oldest behavior
was surprising and silently starved early callers under pressure.

Also documents that overflow rejections arrive via the returned promise
and must be handled or they become unhandled rejections.

Author: jdalton

src/promise-queue.ts

@@ -1,8 +1,9 @@
 /**
  * @fileoverview Bounded concurrency promise queue.
  * Exports the `PromiseQueue` class, which limits how many async tasks run
- * simultaneously, supports an optional max queue length (dropping the oldest
- * pending task when exceeded), and exposes an idle-wait helper.
+ * simultaneously, supports an optional max queue length (new tasks beyond
+ * the cap are rejected with "Task dropped: queue length exceeded"), and
+ * exposes an idle-wait helper.
  */
 
 type QueuedTask<T> = {
@@ -22,7 +23,10 @@ export class PromiseQueue {
   /**
    * Creates a new PromiseQueue
    * @param maxConcurrency - Maximum number of promises that can run concurrently
-   * @param maxQueueLength - Maximum queue size (older tasks are dropped if exceeded)
+   * @param maxQueueLength - Maximum queue size; submissions past the cap
+   * reject with "Task dropped: queue length exceeded" instead of evicting
+   * a caller that has been waiting patiently. Callers must handle this
+   * rejection or they'll see an unhandled rejection.
    */
   constructor(maxConcurrency: number, maxQueueLength?: number | undefined) {
     this.maxConcurrency = maxConcurrency
@@ -35,23 +39,25 @@ export class PromiseQueue {
   /**
    * Add a task to the queue
    * @param fn - Async function to execute
-   * @returns Promise that resolves with the function's result
+   * @returns Promise that resolves with the function's result, or rejects
+   * with "Task dropped: queue length exceeded" if the queue is full.
    */
   async add<T>(fn: () => Promise<T>): Promise<T> {
     return await new Promise<T>((resolve, reject) => {
-      const task: QueuedTask<T> = { fn, resolve, reject }
-
+      // Reject the newcomer rather than evicting an earlier-submitted task.
+      // FIFO fairness: the caller who waited longest gets served, not the
+      // caller who arrived last. Previously this dropped the queue head,
+      // which punished patient callers and violated typical
+      // bounded-queue semantics.
       if (
         this.maxQueueLength !== undefined &&
         this.queue.length >= this.maxQueueLength
       ) {
-        // Drop oldest task to prevent memory buildup
-        const droppedTask = this.queue.shift()
-        if (droppedTask) {
-          droppedTask.reject(new Error('Task dropped: queue length exceeded'))
-        }
+        reject(new Error('Task dropped: queue length exceeded'))
+        return
       }
 
+      const task: QueuedTask<T> = { fn, resolve, reject }
       this.queue.push(task as QueuedTask<unknown>)
       this.runNext()
     })

test/unit/promise-queue.test.mts

@@ -141,40 +141,44 @@ describe('PromiseQueue', () => {
   })
 
   describe('maxQueueLength', () => {
-    it('should drop oldest task when queue exceeds max length', async () => {
+    it('should reject the newest submission when queue is full (drop-newest, FIFO-fair)', async () => {
       const queue = new PromiseQueue(1, 2)
       const results: string[] = []
       const errors: Error[] = []
 
-      // Add 4 tasks - first one runs immediately, next 2 queue, 4th drops oldest queued
+      // Concurrency 1, queue cap 2. task1 runs immediately, task2+task3
+      // fill the queue, task4 arrives over the cap and should be rejected —
+      // earlier submitters (task2, task3) keep their slots.
       const tasks = [
         queue.add(async () => {
           await delay(50)
           results.push('task1')
           return 'task1'
         }),
-        queue
-          .add(async () => {
-            results.push('task2')
-            return 'task2'
-          })
-          .catch((e: Error) => errors.push(e)),
         queue.add(async () => {
-          results.push('task3')
-          return 'task3'
+          results.push('task2')
+          return 'task2'
         }),
         queue.add(async () => {
-          results.push('task4')
-          return 'task4'
+          results.push('task3')
+          return 'task3'
         }),
+        queue
+          .add(async () => {
+            results.push('task4')
+            return 'task4'
+          })
+          .catch((e: Error) => errors.push(e)),
       ]
 
       await Promise.all(tasks.map(t => t.catch(() => {})))
 
       expect(errors.length).toBe(1)
       expect(errors[0]?.message).toBe('Task dropped: queue length exceeded')
       expect(results).toContain('task1')
-      expect(results).not.toContain('task2') // Dropped
+      expect(results).toContain('task2')
+      expect(results).toContain('task3')
+      expect(results).not.toContain('task4')
     })
 
     it('should work without dropping tasks when under limit', async () => {