@zerotal/queue 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/queue
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Added a typed error vocabulary (`QueueError` + `E_QUEUE_*` codes) for init/shutdown/batching failures.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @zerotal/queue
+
+> Background job queue with retries, batches, chaining, and a worker pool.
+
+Offload slow work to background jobs. Define `Job` classes, dispatch them singly, batched, or chained, choose a driver (SQLite, Redis, or sync), and process them with the worker loop or a `WorkerPool` of Bun threads.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/queue
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { QueueProvider } from "@zerotal/queue";
+```
+
+## Usage
+
+A job extends `Job`, serialises its state in `payload()`, restores it in a static `fromPayload()`, and does the work in `handle()`. Register it so the worker can rebuild it by class name:
+
+```ts
+import { Job, JobRegistry } from "@zerotal/queue";
+
+export class NotifyFollowersJob extends Job {
+  override readonly queue = "notifications";
+  override readonly maxAttempts = 3;
+  override readonly retryDelay = 5000;
+
+  constructor(public readonly postId: number) {
+    super();
+  }
+
+  payload(): Record<string, unknown> {
+    return { postId: this.postId };
+  }
+
+  static fromPayload(p: Record<string, unknown>): NotifyFollowersJob {
+    return new NotifyFollowersJob(p["postId"] as number);
+  }
+
+  async handle(): Promise<void> {
+    /* … */
+  }
+}
+
+JobRegistry.register(NotifyFollowersJob as never);
+```
+
+Dispatch via the `Queue` facade:
+
+```ts
+import { Queue } from "@zerotal/queue";
+
+await Queue.dispatch(new NotifyFollowersJob(post.id));
+```
+
+Batch jobs and react when they all finish, or chain them to run sequentially:
+
+```ts
+import { Bus } from "@zerotal/queue";
+
+await Bus.batch(rows.map((row) => new ImportCsvRowJob(row)))
+  .then(new SendImportSummaryJob(user)) // when ALL succeed
+  .catch(new NotifyAdminOfFailureJob(user)) // when ANY fail
+  .dispatch();
+
+await Bus.chain([new ValidateImportJob(id), new ProcessImportJob(id)]).dispatch();
+```
+
+In tests, swap the facade for a recorder:
+
+```ts
+import { QueueFake } from "@zerotal/queue";
+
+QueueFake.swap();
+expect(QueueFake.dispatched(NotifyFollowersJob)).toHaveLength(1);
+QueueFake.restore();
+```
+
+## Exports
+
+| Export                                                                                 | Description                                              |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `Queue`                                                                                | Facade over `QueueManager`.                              |
+| `Job`, `JobRegistry`                                                                   | Base job class and the class-name registry.              |
+| `QueueManager`, `queueStats`, `JobStatus`, `QueueStats`                                | Manager and stats helpers.                               |
+| `Bus`, `Batch`, `PendingBatch`, `BatchRecord`, `BatchOptions`, `SerializedJob`         | Batch and chain orchestration.                           |
+| `WorkerPool`, `WorkerPoolOptions`, `WorkerResult`                                      | Bun-thread worker pool for CPU-bound jobs.               |
+| `QueueFake`                                                                            | In-memory test double.                                   |
+| `QueueProvider`                                                                        | Service provider — register in `bootstrap/providers.ts`. |
+| `QueueConfig`, `QueueConfigShape`                                                      | Config factory and its type.                             |
+| `QueueDriver`, `JobRecord`, `BatchStatus`, `SqliteDriver`, `SyncDriver`, `RedisDriver` | Driver contract and built-in drivers.                    |
+| `errors`                                                                               | Typed error vocabulary (re-exported).                    |
+
+Subpath exports:
+
+- `@zerotal/queue` — the public API above.
+- `@zerotal/queue/commands` — `QueueWorkCommand`, `QueueFailedCommand`, `QueueRetryCommand`, `QueueFlushCommand`.
+
+## Documentation
+
+- [Queue](../../docs/queue.md)

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@zerotal/queue",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "stable",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./commands": "./src/commands/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0",
+    "@zerotal/orm": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Background job queue for Zerotal with SQLite and Redis drivers, delayed jobs, and retries.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "queue",
+    "jobs",
+    "background",
+    "redis"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/queue"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/queue#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/Batch.ts

@@ -0,0 +1,63 @@
+export type SerializedJob = { className: string; payload: Record<string, unknown> };
+
+export interface BatchOptions {
+  thenJobs?: SerializedJob[] | undefined;
+  catchJobs?: SerializedJob[] | undefined;
+  finallyJobs?: SerializedJob[] | undefined;
+}
+
+export interface BatchRecord {
+  id: string;
+  name: string;
+  totalJobs: number;
+  pendingJobs: number;
+  failedJobs: number;
+  failedJobIds: number[];
+  options: BatchOptions;
+  createdAt: string;
+  finishedAt: string | undefined;
+}
+
+export class Batch {
+  constructor(private readonly _r: BatchRecord) {}
+
+  get id(): string {
+    return this._r.id;
+  }
+  get name(): string {
+    return this._r.name;
+  }
+  get totalJobs(): number {
+    return this._r.totalJobs;
+  }
+  get pendingJobs(): number {
+    return this._r.pendingJobs;
+  }
+  get failedJobs(): number {
+    return this._r.failedJobs;
+  }
+  get failedJobIds(): number[] {
+    return this._r.failedJobIds;
+  }
+  get options(): BatchOptions {
+    return this._r.options;
+  }
+  get createdAt(): string {
+    return this._r.createdAt;
+  }
+  get finishedAt(): string | undefined {
+    return this._r.finishedAt;
+  }
+
+  finished(): boolean {
+    return this._r.finishedAt !== undefined;
+  }
+  failed(): boolean {
+    return this._r.failedJobs > 0;
+  }
+  progress(): number {
+    return this._r.totalJobs === 0
+      ? 1
+      : (this._r.totalJobs - this._r.pendingJobs) / this._r.totalJobs;
+  }
+}

package/src/Bus.ts

@@ -0,0 +1,49 @@
+import type { Job } from "./Job.ts";
+import { QueueNotInitializedError } from "./errors.ts";
+import type { Batch } from "./Batch.ts";
+import type { QueueManager } from "./QueueManager.ts";
+import { PendingBatch } from "./PendingBatch.ts";
+
+export class Bus {
+  private static _manager: QueueManager | undefined;
+
+  static setManager(manager: QueueManager): void {
+    Bus._manager = manager;
+  }
+
+  /** Dispatch a set of jobs as a batch. Returns a fluent builder to attach callbacks. */
+  static batch(jobs: Job[]): PendingBatch {
+    const manager = Bus._manager;
+    if (!manager) throw new QueueNotInitializedError();
+    return new PendingBatch(jobs, {
+      dispatchBatch: (pending) => manager.dispatchBatch(pending),
+    });
+  }
+
+  /**
+   * Chain jobs sequentially — each job runs only after the previous one succeeds.
+   * If any job fails the chain is stopped (no subsequent jobs are dispatched).
+   */
+  static chain(jobs: Job[]): { dispatch(): Promise<void> } {
+    const manager = Bus._manager;
+    if (!manager) throw new QueueNotInitializedError();
+    return {
+      async dispatch(): Promise<void> {
+        if (jobs.length === 0) return;
+        const [first, ...rest] = jobs;
+        if (!first) return;
+        if (rest.length > 0) {
+          first._chain = rest.map((j) => ({ className: j.className, payload: j.payload() }));
+        }
+        await manager.dispatch(first);
+      },
+    };
+  }
+
+  /** Reset the manager reference (for testing). */
+  static reset(): void {
+    Bus._manager = undefined;
+  }
+}
+
+export type { Batch };

package/src/Job.ts

@@ -0,0 +1,37 @@
+import type { SerializedJob } from "./Batch.ts";
+
+export abstract class Job {
+  /** Queue name — override in subclass to route to specific queues */
+  readonly queue: string = "default";
+
+  /** Max retry attempts before moving to failed queue */
+  readonly maxAttempts: number = 3;
+
+  /** Milliseconds to wait between retry attempts */
+  readonly retryDelay: number = 1000;
+
+  /** Set by Bus.batch() — tracks which batch this job belongs to. */
+  batchId: string | undefined = undefined;
+
+  /** Set by Bus.chain() — remaining jobs to dispatch after this one succeeds. */
+  _chain: SerializedJob[] | undefined = undefined;
+
+  /** The job's work — implement this in every subclass */
+  abstract handle(): Promise<void>;
+
+  /**
+   * Serialize job state to a plain object for storage.
+   * Override in subclasses that have constructor arguments.
+   */
+  payload(): Record<string, unknown> {
+    return {};
+  }
+
+  /**
+   * The class name used as the serialization key.
+   * Must match what JobRegistry.register() stores.
+   */
+  get className(): string {
+    return this.constructor.name;
+  }
+}

package/src/JobRegistry.ts

@@ -0,0 +1,24 @@
+import type { Job } from "./Job.ts";
+
+type JobClass = new (...args: never[]) => Job;
+
+/**
+ * Global registry mapping job class names to their constructors.
+ * Required for deserialization — when a job is popped from the queue,
+ * the worker looks up the class here to instantiate it.
+ */
+export const JobRegistry = {
+  _map: new Map<string, JobClass>(),
+
+  register(JobClass: JobClass): void {
+    JobRegistry._map.set(JobClass.name, JobClass);
+  },
+
+  resolve(className: string): JobClass | undefined {
+    return JobRegistry._map.get(className);
+  },
+
+  all(): ReadonlyMap<string, JobClass> {
+    return JobRegistry._map;
+  },
+};

package/src/PendingBatch.ts

@@ -0,0 +1,63 @@
+import type { Job } from "./Job.ts";
+import type { Batch, BatchOptions, SerializedJob } from "./Batch.ts";
+
+type BatchDispatcher = {
+  dispatchBatch(pending: PendingBatch): Promise<Batch>;
+};
+
+function toSerialized(job: Job | Job[]): SerializedJob[] {
+  return (Array.isArray(job) ? job : [job]).map((j) => ({
+    className: j.className,
+    payload: j.payload(),
+  }));
+}
+
+export class PendingBatch {
+  private _name = "";
+  private _thenJobs: SerializedJob[] = [];
+  private _catchJobs: SerializedJob[] = [];
+  private _finallyJobs: SerializedJob[] = [];
+
+  constructor(
+    private readonly _jobs: Job[],
+    private readonly _dispatcher: BatchDispatcher,
+  ) {}
+
+  name(n: string): this {
+    this._name = n;
+    return this;
+  }
+
+  then(job: Job | Job[]): this {
+    this._thenJobs.push(...toSerialized(job));
+    return this;
+  }
+  catch(job: Job | Job[]): this {
+    this._catchJobs.push(...toSerialized(job));
+    return this;
+  }
+  finally(job: Job | Job[]): this {
+    this._finallyJobs.push(...toSerialized(job));
+    return this;
+  }
+
+  async dispatch(): Promise<Batch> {
+    return this._dispatcher.dispatchBatch(this);
+  }
+
+  // ── Internal accessors (used by QueueManager) ──────────────────────────
+
+  get jobs(): Job[] {
+    return this._jobs;
+  }
+  get batchName(): string {
+    return this._name;
+  }
+  get options(): BatchOptions {
+    return {
+      thenJobs: this._thenJobs.length ? this._thenJobs : undefined,
+      catchJobs: this._catchJobs.length ? this._catchJobs : undefined,
+      finallyJobs: this._finallyJobs.length ? this._finallyJobs : undefined,
+    };
+  }
+}

package/src/QueueFake.ts

@@ -0,0 +1,126 @@
+import { Application, currentApp } from "@zerotal/core";
+import type { Job } from "./Job.ts";
+
+type Binding = unknown;
+
+/**
+ * Drop-in replacement for QueueManager that captures dispatched jobs instead
+ * of persisting or executing them. Install at the start of a test; restore after.
+ *
+ * @example
+ * const queue = QueueFake.install();
+ *
+ * await Queue.dispatch(new ProcessPaymentJob(order));
+ *
+ * queue.assertDispatched(ProcessPaymentJob);
+ * queue.assertDispatchedCount(1);
+ *
+ * queue.restore(); // call in afterEach
+ */
+export class QueueFake {
+  private readonly _dispatched: Job[] = [];
+  private readonly _app: Application;
+  private readonly _original: Binding;
+
+  private constructor(app: Application, original: Binding) {
+    this._app = app;
+    this._original = original;
+  }
+
+  /** Replace the 'queue' container binding with this fake. */
+  static install(): QueueFake {
+    const app = currentApp();
+    const original = app.container.registry.get("queue");
+    const fake = new QueueFake(app, original);
+    app.container.value("queue", fake);
+    return fake;
+  }
+
+  /** Restore the original 'queue' binding. Call in afterEach. */
+  restore(): void {
+    if (this._original !== undefined) {
+      this._app.container.registry.set("queue", this._original as never);
+    } else {
+      this._app.container.registry.delete("queue");
+    }
+  }
+
+  // ── Queue manager interface ──────────────────────────────────────────────
+
+  /** Capture the job — does NOT execute it. */
+  async dispatch(job: Job): Promise<void> {
+    this._dispatched.push(job);
+  }
+
+  get isShuttingDown(): boolean {
+    return false;
+  }
+
+  async processNext(): Promise<boolean> {
+    return false;
+  }
+  async drain(): Promise<void> {}
+  async size(): Promise<number> {
+    return this._dispatched.length;
+  }
+  async flush(): Promise<void> {
+    this._dispatched.length = 0;
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────────
+
+  /** All captured jobs. */
+  dispatched(): Job[] {
+    return [...this._dispatched];
+  }
+
+  /**
+   * Assert that a specific Job class was dispatched.
+   * Pass an optional filter callback to narrow the assertion.
+   *
+   * @example
+   * queue.assertDispatched(ProcessPaymentJob);
+   * queue.assertDispatched(ProcessPaymentJob, (j) => j.orderId === 42);
+   */
+  assertDispatched<T extends Job>(
+    JobClass: new (...args: never[]) => T,
+    callback?: (job: T) => boolean,
+  ): void {
+    const matching = this._dispatched.filter(
+      (j): j is T => j instanceof JobClass && (callback === undefined || callback(j)),
+    );
+    if (matching.length === 0) {
+      const hint = callback ? " matching the given filter" : "";
+      throw new Error(`Expected ${JobClass.name} to have been dispatched${hint}, but it was not.`);
+    }
+  }
+
+  /** Assert that a Job class was NOT dispatched. */
+  assertNotDispatched<T extends Job>(JobClass: new (...args: never[]) => T): void {
+    const matching = this._dispatched.filter((j): j is T => j instanceof JobClass);
+    if (matching.length > 0) {
+      throw new Error(
+        `Expected ${JobClass.name} NOT to have been dispatched, but it was (${matching.length}×).`,
+      );
+    }
+  }
+
+  /** Assert that no jobs were dispatched. */
+  assertNothingDispatched(): void {
+    if (this._dispatched.length > 0) {
+      const names = this._dispatched.map((j) => j.constructor.name).join(", ");
+      throw new Error(
+        `Expected nothing to be dispatched, but ${this._dispatched.length} job(s) were: ${names}.`,
+      );
+    }
+  }
+
+  /** Assert the exact number of dispatched jobs. */
+  assertDispatchedCount(count: number): void {
+    if (this._dispatched.length !== count) {
+      throw new Error(
+        `Expected ${count} job(s) to be dispatched, but ${this._dispatched.length} were.`,
+      );
+    }
+  }
+}