suaveplan/openspec/archive/2026-04-24-enterprise-queue/tasks.md

Tasks: enterprise-queue

• Change ID: enterprise-queue
• Package: @suaveplan/queue
• Date: 2026-04-24

Prerequisites (must be published to Verdaccio first)

• @suaveplan/error
• @suaveplan/types
• @suaveplan/events

Tasks

1. Scaffold package

• Create universal/streams/queue/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/queue, version 0.1.0, sideEffects: false, correct workspace deps)
• Write tsconfig.json extending @suaveplan/typescript-config/library.json
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config

2. Error codes (src/error-codes.ts)

• Define QueueErrorCode union type
• Call defineCodes to register all QUEUE.* codes
• Export registerQueueErrorCodes() and QueueError

3. Types (src/types/common.ts)

• Define and export Queue<T>, Job<T>, JobState, QueueWorker, QueueWorkerOptions, RetryPolicy, WorkerStats
• Write common.md

4. Queue implementations

• createMemoryQueue<T> in src/queues/memory-queue/ — FIFO with maxSize bound, injectable clock/idGenerator/bus
• createPriorityQueue<T> in src/queues/priority-queue/ — max-heap by job.priority
• createDelayedQueue<T> in src/queues/delayed-queue/ — delayed dequeue based on job.scheduledAt with injectable clock
• Each: .ts, .md, .types.ts, .test.ts, index.ts; Zod options schema; lifecycle events on bus

5. Retry policy helpers (src/utils/retry-policy.ts)

• Implement constant, linear, exponential backoff delay computation
• Write .md and .test.ts

6. QueueWorker (src/worker/queue-worker/)

• Implement createQueueWorker<T> with:
  • Configurable concurrency (semaphore-based)
  • AbortSignal propagation to handler
  • Retry loop per RetryPolicy on handler failure
  • Dead letter queue routing after maxRetries exhausted
  • WorkerStats accumulation
  • Job lifecycle event emission via @suaveplan/events bus
  • OTel spans, counters, histogram per proposal.md §3
• Write .md, .types.ts, .test.ts, index.ts

7. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — enqueue jobs, start worker, assert completion stats and events
• tests/property.test.ts — fast-check properties per proposal.md §4

8. Benchmarks (src/__benchmarks__/queue.bench.ts)

• Implement benchmark cases per proposal.md §5

9. Docs

• Every .ts implementation file has a sibling .md
• Root README.md

10. Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/queue green
• bunx turbo test:coverage --filter=@suaveplan/queue ≥ 100% on touched modules

11. Publish

• bun scripts/publish.ts --package @suaveplan/queue

12. Archive

• Fold spec delta into openspec/specs/streams/spec.md
• mv openspec/changes/enterprise-queue openspec/archive/2026-04-24-enterprise-queue