suaveplan/packages/foundation/flow/queue/README.md

@suaveplan/queue - Enterprise-grade queue management: memory/priority/delayed queues, concurrent workers with retry and dead-letter, job state machines, OTel instrumentation

Summary

Enterprise-grade queue management: memory/priority/delayed queues, concurrent workers with retry and dead-letter forwarding, job state machines, and OTel instrumentation.

Documentation tree

• errors — (no submodules)
  • queue-error — (no submodules)
• job — (no submodules)
  • job — (no submodules)
• delayed-queue — DelayedQueue<T> is an explicit alias for a delay-aware FIFO queue. It extends MemoryQueue<T> to make the delay inte…
• memory-queue — MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and…
• priority-queue — PriorityQueue<T> extends MemoryQueue<T> to provide priority-ordered job scheduling. Jobs with higher priority val…
• types — (no submodules)
  • queue-types — (no submodules)
• worker — (no submodules)
  • queue-worker — (no submodules)

- [queue-error](./src/errors/queue-error.md) — _(no submodules)_- [job](./src/job/job.md) — _(no submodules)_- [job](./src/job/job.md) — _(no submodules)_- [delayed-queue](./src/queue/delayed-queue.md) — `DelayedQueue` is an explicit alias for a delay-aware FIFO queue. It extends `MemoryQueue` to make the delay inte…

• memory-queue — MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and…
• priority-queue — PriorityQueue<T> extends MemoryQueue<T> to provide priority-ordered job scheduling. Jobs with higher priority val…
• types — (no submodules)- queue-types — (no submodules)- worker — (no submodules)- queue-worker — (no submodules)- queue-error — (no submodules)- job — (no submodules)- job — (no submodules)- delayed-queue — DelayedQueue<T> is an explicit alias for a delay-aware FIFO queue. It extends MemoryQueue<T> to make the delay inte…
• memory-queue — MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and…
• priority-queue — PriorityQueue<T> extends MemoryQueue<T> to provide priority-ordered job scheduling. Jobs with higher priority val…
• types — (no submodules)- queue-types — (no submodules)- worker — (no submodules)- queue-worker — (no submodules)- queue-error — (no submodules)- job — (no submodules)- job — (no submodules)- delayed-queue — DelayedQueue<T> is an explicit alias for a delay-aware FIFO queue. It extends MemoryQueue<T> to make the delay inte…
• memory-queue — MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and…
• priority-queue — PriorityQueue<T> extends MemoryQueue<T> to provide priority-ordered job scheduling. Jobs with higher priority val…
• types — (no submodules)- queue-types — (no submodules)- worker — (no submodules)- queue-worker — (no submodules)- queue-error — (no submodules)- job — (no submodules) - job — (no submodules)- delayed-queue — DelayedQueue<T> is an explicit alias for a delay-aware FIFO queue. It extends MemoryQueue<T> to make the delay inte…
• memory-queue — MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and…
• priority-queue — PriorityQueue<T> extends MemoryQueue<T> to provide priority-ordered job scheduling. Jobs with higher priority val…
• types — (no submodules) - queue-types — (no submodules)- worker — (no submodules) - queue-worker — (no submodules)

Packages

Module	Description
errors/queue-error	Error hierarchy with stable codes
job/job	Job state machine
queue/memory-queue	FIFO in-memory queue
queue/priority-queue	Priority-ordered queue
queue/delayed-queue	Delay-aware queue
worker/queue-worker	Concurrent job worker with retry
types/queue-types	Shared types and Zod schemas

Quick Start

import { createMemoryQueue } from "@suaveplan/queue/queue/memory-queue";
import { runWorker } from "@suaveplan/queue/worker/queue-worker";

const queue = createMemoryQueue<{ userId: string }>();
await queue.enqueue({ userId: "user_1" });
await queue.enqueue({ userId: "user_2" });

const stats = await runWorker(queue, async (job) => {
  console.log("Processing user:", job.payload.userId);
}, {
  concurrency: 2,
  retryPolicy: { maxAttempts: 3, backoffMs: 1000, backoffMultiplier: 2 },
});
console.log(stats); // { processed: 2, succeeded: 2, failed: 0, dead: 0, retried: 0 }