@zerotal/queue 1.6.3 → 1.7.2

package/CHANGELOG.md

@@ -8,6 +8,24 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+### Fixed
+
+- **`queue:work` listened on one hardcoded queue, so queued notifications were never sent.**
+  The `--queue` flag defaulted to the literal string `"default"` and the command never read
+  `queue.queues` — the key `QueueProvider`'s in-process pool has always used. A job may pin its
+  own queue, and `SendNotificationJob` sets `"notifications"`, so following both documented
+  steps — `Notify.queue(user, notification)`, then `bun zt queue:work` — put the mail on a queue
+  nobody was reading. Nothing errored. The job sat as pending forever and the worker reported
+  "Queue is empty."
+
+  With no `--queue`, the worker now drains every queue in `queue.queues`, falling back to
+  `["default"]`. The flag still overrides it and now accepts a comma-separated list
+  (`--queue=emails,reports`) in priority order, so one worker can take a subset without a second
+  process. `--once` stops at the first queue with a claimable job rather than taking one job per
+  queue, and the idle sleep is only taken when *no* queue had anything — sleeping after the first
+  empty one would leave a busy second queue waiting out the poll interval.
+
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/api-surface.md

@@ -0,0 +1,421 @@
+# @zerotal/queue — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class Batch = {
+  new (_r: BatchRecord): Batch
+  createdAt: string
+  failed: () => boolean
+  failedJobIds: number[]
+  failedJobs: number
+  finished: () => boolean
+  finishedAt: string | undefined
+  id: string
+  name: string
+  options: BatchOptions
+  pendingJobs: number
+  progress: () => number
+  totalJobs: number
+}
+
+class Bus = {
+  new (): Bus
+  static batch: (jobs: Job[]) => PendingBatch
+  static chain: (jobs: Job[]) => {    dispatch(): Promise<void>;}
+  static reset: () => void
+  static setManager: (manager: QueueManager) => void
+}
+
+class Job = {
+  new (): Job
+  _chain: SerializedJob[] | undefined
+  batchId: string | undefined
+  className: string
+  debounceKey: () => string
+  handle: () => Promise<void>
+  payload: () => Record<string, unknown>
+  readonly debounce?: number
+  readonly maxAttempts: number
+  readonly queue: string
+  readonly retryDelay: number
+}
+
+class JobRan = {
+  new (className: string, queue: string, status: 'dispatched' | 'completed' | 'failed' | 'retried', durationMs: number, error?: string | undefined): JobRan
+  readonly className: string
+  readonly durationMs: number
+  readonly error?: string | undefined
+  readonly queue: string
+  readonly status: 'dispatched' | 'completed' | 'failed' | 'retried'
+}
+
+class PendingBatch = {
+  new (_jobs: Job[], _dispatcher: BatchDispatcher): PendingBatch
+  batchName: string
+  catch: (job: Job | Job[]) => PendingBatch
+  dispatch: () => Promise<Batch>
+  finally: (job: Job | Job[]) => PendingBatch
+  jobs: Job[]
+  name: (n: string) => PendingBatch
+  options: BatchOptions
+  then: (job: Job | Job[]) => PendingBatch
+}
+
+class QueueBatchingUnsupportedError = {
+  new (): QueueBatchingUnsupportedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueDebounceUnsupportedError = {
+  new (className: string, driver: string): QueueDebounceUnsupportedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): QueueError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueFake = {
+  new (app: Application, original: Binding): QueueFake
+  static install: () => QueueFake
+  assertDispatched: <T extends Job>(JobClass: new (...args: never[]) => T, callback?: (job: T) => boolean) => void
+  assertDispatchedCount: (count: number) => void
+  assertNotDispatched: <T extends Job>(JobClass: new (...args: never[]) => T) => void
+  assertNothingDispatched: () => void
+  dispatch: (job: Job) => Promise<void>
+  dispatched: () => Job[]
+  drain: () => Promise<void>
+  flush: () => Promise<void>
+  isShuttingDown: boolean
+  processNext: () => Promise<boolean>
+  restore: () => void
+  size: () => Promise<number>
+}
+
+class QueueManager = {
+  new (driver: QueueDriver): QueueManager
+  activeJobCount: number
+  clearFailed: (queue?: string) => Promise<void>
+  dispatch: (job: Job) => Promise<void>
+  dispatchBatch: (pending: PendingBatch) => Promise<Batch>
+  drain: () => Promise<void>
+  failed: (queue?: string) => Promise<FailedRecord[]>
+  flush: () => Promise<void>
+  forgetFailed: (id: number) => Promise<void>
+  isShuttingDown: boolean
+  pending: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  processNext: (queue?: string) => Promise<boolean>
+  queues: () => Promise<{    queue: string;    pending: number;}[]>
+  retryFailed: (id: number) => Promise<boolean>
+  setWorkerPool: (pool: JobExecutor) => void
+  size: (queue?: string) => Promise<number>
+  stats: () => QueueStats
+}
+
+class QueueNotInitializedError = {
+  new (): QueueNotInitializedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class QueueProvider = {
+  new (app: Application): QueueProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['queue']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class QueueShuttingDownError = {
+  new (className: string): QueueShuttingDownError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class RedisDriver = {
+  new (prefix?: string, options?: { visibilityTimeout?: number; client?: RedisClientLike; }): RedisDriver
+  clearFailed: (queue?: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number, queue?: string) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+class SqliteDriver = {
+  new (sql: SQLInstance, options?: { visibilityTimeout?: number; }): SqliteDriver
+  clearFailed: (queue?: string) => Promise<void>
+  createBatch: (id: string, name: string, totalJobs: number, optionsJson: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  getBatch: (batchId: string) => Promise<BatchRecord | null>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  listPending: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  queues: () => Promise<{    queue: string;    pending: number;}[]>
+  recordBatchJobComplete: (batchId: string) => Promise<BatchStatus>
+  recordBatchJobFailed: (batchId: string, jobId: number) => Promise<BatchStatus>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+class SyncDriver = {
+  new (): SyncDriver
+  static _pendingJob: Job | undefined
+  clearFailed: (queue?: string) => Promise<void>
+  delete: (_record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  failedJobs: FailedEntry[]
+  flush: () => Promise<void>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  pop: () => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  retry: (record: JobRecord) => Promise<void>
+  size: () => Promise<number>
+}
+
+class WorkerPool = {
+  new (opts: WorkerPoolOptions): WorkerPool
+  run: (record: JobRecord) => Promise<WorkerResult>
+  start: () => Promise<void>
+  terminate: () => Promise<void>
+}
+
+const JobRegistry = {    _map: Map<string, JobClass>;    register(JobClass: JobClass): void;    resolve(className: string): JobClass | undefined;    all(): ReadonlyMap<string, JobClass>;}
+
+const Queue = QueueManager
+
+function QueueConfig = (options?: Partial<QueueConfigShape>) => QueueConfigShape
+
+function queueStats = () => QueueStats
+
+interface BatchOptions = {
+  catchJobs?: SerializedJob[] | undefined
+  finallyJobs?: SerializedJob[] | undefined
+  thenJobs?: SerializedJob[] | undefined
+}
+
+interface BatchRecord = {
+  createdAt: string
+  failedJobIds: number[]
+  failedJobs: number
+  finishedAt: string | undefined
+  id: string
+  name: string
+  options: BatchOptions
+  pendingJobs: number
+  totalJobs: number
+}
+
+interface JobRecord = {
+  attempts: number
+  availableAt: number
+  batchId?: string | undefined
+  className: string
+  createdAt: string
+  debounceKey?: string | undefined
+  id: number
+  maxAttempts: number
+  payload: string
+  queue: string
+  retryDelay: number
+}
+
+interface QueueConfigShape = {
+  driver: 'sqlite' | 'redis' | 'sync'
+  pollInterval: number
+  queues: string[]
+  workerBootstrap?: string
+  workers: number
+}
+
+interface QueueDriver = {
+  clearFailed: (queue?: string) => Promise<void>
+  createBatch?: (id: string, name: string, totalJobs: number, optionsJson: string) => Promise<void>
+  delete: (record: JobRecord) => Promise<void>
+  deleteFailedRecord: (id: number) => Promise<void>
+  fail: (record: JobRecord, error: string) => Promise<void>
+  flush: () => Promise<void>
+  getBatch?: (batchId: string) => Promise<BatchRecord | null>
+  listFailed: (queue?: string) => Promise<FailedRecord[]>
+  listPending?: (queue?: string, limit?: number, offset?: number) => Promise<JobRecord[]>
+  pop: (queue?: string) => Promise<JobRecord | null>
+  push: (record: Omit<JobRecord, 'id' | 'createdAt'>) => Promise<void>
+  pushDebounced?: (record: Omit<JobRecord, 'id' | 'createdAt'>, key: string) => Promise<void>
+  queues?: () => Promise<{    queue: string;    pending: number;}[]>
+  recordBatchJobComplete?: (batchId: string) => Promise<BatchStatus>
+  recordBatchJobFailed?: (batchId: string, jobId: number) => Promise<BatchStatus>
+  retry: (record: JobRecord) => Promise<void>
+  size: (queue?: string) => Promise<number>
+}
+
+interface QueueStats = {
+  failedLast5m: number
+  failedTotal: number
+  processedLast5m: number
+  processedTotal: number
+}
+
+interface WorkerPoolOptions = {
+  bootstrapPath?: string | undefined
+  maxPending?: number | undefined
+  maxRespawns?: number | undefined
+  size: number
+}
+
+type BatchStatus = 'failed' | 'pending' | 'complete'
+
+type JobStatus = 'dispatched' | 'completed' | 'failed' | 'retried'
+
+type SerializedJob = {    className: string;    payload: Record<string, unknown>;}
+
+type WorkerResult = {    success: true;} | {    success: false;    error: string;}
+
+## ./commands  `(./src/commands/index.ts)`
+
+class QueueFailedCommand = {
+  new (): QueueFailedCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    short: string;    type: 'string';    description: string;    default: string;}[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueFlushCommand = {
+  new (): QueueFlushCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    short: string;    type: 'string';    description: string;    default: string;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;    short?: never;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueRetryCommand = {
+  new (): QueueRetryCommand
+  static args: {    name: string;    required: boolean;    description: string;}[]
+  static commandName: string
+  static description: string
+  static flags: FlagDef[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class QueueWorkCommand = {
+  new (): QueueWorkCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    short: string;    type: 'string';    description: string;    default: string;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;    short?: never;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/queue",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -13,6 +13,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -30,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3",
-    "@zerotal/orm": "1.6.3"
+    "@zerotal/core": "1.7.2",
+    "@zerotal/orm": "1.7.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/QueueWorkCommand.ts

@@ -1,5 +1,6 @@
 import type { Application } from "@zerotal/core";
 import { Command } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
 import type { QueueManager } from "../QueueManager.ts";
 
 export class QueueWorkCommand extends Command {
@@ -12,8 +13,8 @@ export class QueueWorkCommand extends Command {
       name: "queue",
       short: "q",
       type: "string" as const,
-      description: "Queue name to process",
-      default: "default",
+      description: "Queue name(s) to process, comma-separated. Defaults to config queue.queues",
+      default: "",
     },
     {
       name: "once",
@@ -23,8 +24,35 @@ export class QueueWorkCommand extends Command {
     },
   ];
 
+  /**
+   * The queues to drain: the flag if given, else the app's own `queue.queues`.
+   *
+   * Defaulting to the literal string `"default"` was a silent delivery failure.
+   * A job may pin its own queue — `SendNotificationJob` sets `"notifications"` —
+   * and `config/queue.ts` lists exactly that queue so the in-process pool drains
+   * it (`QueueProvider` reads this same key and loops over every entry). But this
+   * command ignored the config and listened on `"default"` alone, so following
+   * both documented steps — `Notify.queue(...)`, then `zt queue:work` — queued
+   * the mail and then never sent it. Nothing errors: the job sits in a queue
+   * nobody is reading, forever.
+   *
+   * Comma-separated, so one worker can take a subset without a second process.
+   * Order is priority order, matching the provider's loop.
+   */
+  private targetQueues(app: Application): string[] {
+    const flag = ((this.flags["queue"] as string) ?? "").trim();
+    if (flag) {
+      const named = flag
+        .split(",")
+        .map((q) => q.trim())
+        .filter(Boolean);
+      if (named.length) return named;
+    }
+    const config = app.container.makeSync("config") as ConfigManager;
+    return config.get<string[]>("queue.queues", ["default"]);
+  }
+
   async run(): Promise<void> {
-    const queueName = this.flags["queue"] as string;
     const once = this.flags["once"] as boolean;
     const app = this.app as Application | undefined;
     if (!app) {
@@ -33,22 +61,36 @@ export class QueueWorkCommand extends Command {
     }
 
     const manager = app.container.makeSync("queue") as QueueManager;
+    const queues = this.targetQueues(app);
 
     if (once) {
-      const processed = await manager.processNext(queueName);
-      this.info(processed ? "Processed 1 job." : "Queue is empty.");
+      // The first queue with anything claimable wins, so `--once` drains one job
+      // rather than one job *per queue*.
+      for (const q of queues) {
+        if (await manager.processNext(q)) {
+          this.info("Processed 1 job.");
+          return;
+        }
+      }
+      this.info("Queue is empty.");
       return;
     }
 
-    this.info(`Processing queue "${queueName}" — Ctrl+C to stop.`);
+    this.info(`Processing queue(s) [${queues.join(", ")}] — Ctrl+C to stop.`);
     while (!manager.isShuttingDown) {
       // Sleep whenever nothing was *claimable* this tick — not merely when the
       // queue is empty. size() counts not-yet-due delayed jobs and jobs reserved
       // by other workers, so keying the sleep off size() busy-spins at 100% CPU
       // whenever a delayed/reserved job exists but nothing is ready.
-      const processed = await manager
-        .processNext(queueName)
-        .catch((err) => (console.error(err), false));
+      //
+      // "Nothing claimable" means across every queue: sleeping after the first
+      // empty one would leave a busy second queue waiting out the poll interval.
+      let processed = false;
+      for (const q of queues) {
+        if (manager.isShuttingDown) break;
+        const did = await manager.processNext(q).catch((err) => (console.error(err), false));
+        processed = processed || did;
+      }
       if (!processed) {
         await new Promise<void>((r) => setTimeout(r, 500));
       }