Add PromiseQueue utility with comprehensive tests

Implements a promise queue with configurable concurrency limits based
on patterns from coana-package-manager. Features include:
- Configurable max concurrency
- Optional queue size limits to prevent memory buildup
- Progress tracking (activeCount, pendingCount)
- Idle detection with onIdle()
- Proper error propagation

Includes 7 comprehensive unit tests covering all functionality.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jdalton

src/utils/promise-queue.mts

@@ -0,0 +1,109 @@
+/**
+ * A promise queue that limits concurrent execution of async tasks.
+ * Based on patterns from coana-package-manager for resource-aware async operations.
+ */
+
+type QueuedTask<T> = {
+  fn: () => Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+}
+
+export class PromiseQueue {
+  private queue: Array<QueuedTask<unknown>> = []
+  private running = 0
+
+  private readonly maxConcurrency: number
+  private readonly maxQueueLength?: number
+
+  /**
+   * 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)
+   */
+  constructor(maxConcurrency: number, maxQueueLength?: number) {
+    this.maxConcurrency = maxConcurrency
+    this.maxQueueLength = maxQueueLength
+    if (maxConcurrency < 1) {
+      throw new Error('maxConcurrency must be at least 1')
+    }
+  }
+
+  /**
+   * Add a task to the queue
+   * @param fn - Async function to execute
+   * @returns Promise that resolves with the function's result
+   */
+  async add<T>(fn: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const task: QueuedTask<T> = { fn, resolve, reject }
+
+      if (this.maxQueueLength && this.queue.length >= this.maxQueueLength) {
+        // Drop oldest task to prevent memory buildup
+        this.queue.shift()
+      }
+
+      this.queue.push(task as QueuedTask<unknown>)
+      this.runNext()
+    })
+  }
+
+  private runNext(): void {
+    if (this.running >= this.maxConcurrency || this.queue.length === 0) {
+      return
+    }
+
+    const task = this.queue.shift()
+    if (!task) {
+      return
+    }
+
+    this.running++
+
+    task
+      .fn()
+      .then(task.resolve)
+      .catch(task.reject)
+      .finally(() => {
+        this.running--
+        this.runNext()
+      })
+  }
+
+  /**
+   * Wait for all queued and running tasks to complete
+   */
+  async onIdle(): Promise<void> {
+    return new Promise<void>(resolve => {
+      const check = () => {
+        if (this.running === 0 && this.queue.length === 0) {
+          resolve()
+        } else {
+          setImmediate(check)
+        }
+      }
+      check()
+    })
+  }
+
+  /**
+   * Get the number of tasks currently running
+   */
+  get activeCount(): number {
+    return this.running
+  }
+
+  /**
+   * Get the number of tasks waiting in the queue
+   */
+  get pendingCount(): number {
+    return this.queue.length
+  }
+
+  /**
+   * Clear all pending tasks from the queue (does not affect running tasks)
+   */
+  clear(): void {
+    this.queue = []
+  }
+}

src/utils/promise-queue.test.mts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest'
+
+import { PromiseQueue } from './promise-queue.mts'
+
+describe('PromiseQueue', () => {
+  it('should execute tasks with limited concurrency', async () => {
+    const queue = new PromiseQueue(2)
+    const executed: number[] = []
+    const tasks = Array.from({ length: 5 }, (_, i) => {
+      return () =>
+        new Promise<number>(resolve => {
+          executed.push(i)
+          setTimeout(() => resolve(i), 10)
+        })
+    })
+
+    const results = await Promise.all(tasks.map(task => queue.add(task)))
+
+    expect(results).toEqual([0, 1, 2, 3, 4])
+  })
+
+  it('should track active and pending counts', async () => {
+    const queue = new PromiseQueue(1)
+    const task = () => new Promise(resolve => setTimeout(resolve, 50))
+
+    const p1 = queue.add(task)
+    const p2 = queue.add(task)
+
+    expect(queue.activeCount).toBe(1)
+    expect(queue.pendingCount).toBe(1)
+
+    await Promise.all([p1, p2])
+
+    expect(queue.activeCount).toBe(0)
+    expect(queue.pendingCount).toBe(0)
+  })
+
+  it('should limit queue size when maxQueueLength is set', () => {
+    const queue = new PromiseQueue(1, 2)
+
+    // Add one running task
+    queue.add(() => new Promise(resolve => setTimeout(resolve, 100)))
+
+    // Queue should be empty initially
+    expect(queue.pendingCount).toBe(0)
+
+    // Add 3 tasks to queue (max 2, so oldest will be dropped)
+    queue.add(() => Promise.resolve())
+    expect(queue.pendingCount).toBe(1)
+
+    queue.add(() => Promise.resolve())
+    expect(queue.pendingCount).toBe(2)
+
+    queue.add(() => Promise.resolve())
+    // Should still be 2 because oldest was dropped
+    expect(queue.pendingCount).toBe(2)
+  })
+
+  it('should wait for all tasks to complete with onIdle', async () => {
+    const queue = new PromiseQueue(2)
+    const results: number[] = []
+
+    for (let i = 0; i < 5; i++) {
+      queue.add(async () => {
+        await new Promise(resolve => setTimeout(resolve, 10))
+        results.push(i)
+      })
+    }
+
+    await queue.onIdle()
+
+    expect(results).toHaveLength(5)
+  })
+
+  it('should clear pending tasks', async () => {
+    const queue = new PromiseQueue(1)
+    const results: string[] = []
+
+    const task = (id: string) => () =>
+      new Promise<void>(resolve => {
+        results.push(id)
+        setTimeout(resolve, 50)
+      })
+
+    queue.add(task('a'))
+    queue.add(task('b'))
+    queue.add(task('c'))
+
+    queue.clear()
+
+    await queue.onIdle()
+
+    // Only the first task should have run
+    expect(results).toEqual(['a'])
+  })
+
+  it('should handle task errors', async () => {
+    const queue = new PromiseQueue(1)
+
+    const goodTask = () => Promise.resolve('success')
+    const badTask = () => Promise.reject(new Error('failure'))
+
+    const result1 = await queue.add(goodTask)
+    await expect(queue.add(badTask)).rejects.toThrow('failure')
+    const result2 = await queue.add(goodTask)
+
+    expect(result1).toBe('success')
+    expect(result2).toBe('success')
+  })
+
+  it('should throw error for invalid concurrency', () => {
+    expect(() => new PromiseQueue(0)).toThrow(
+      'maxConcurrency must be at least 1',
+    )
+    expect(() => new PromiseQueue(-1)).toThrow(
+      'maxConcurrency must be at least 1',
+    )
+  })
+})