@basaltkit/queue 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+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,319 @@
+# @basaltkit/queue
+
+Job queues for Basalt applications: define declarative "jobs" with Zod validation, run them in the background with BullMQ/Redis in production, and synchronously in development and tests — without changing a line of code.
+
+You need this module when you have work that **must not block the user's request**: sending emails, generating reports, processing images, syncing data, etc.
+
+---
+
+## What this module solves
+
+A **queue** is a waiting list of tasks. Instead of doing the heavy work immediately (and making the user wait), you put the task on the queue and respond right away. A **worker** — a process that may live on another machine — pulls tasks off the queue and runs them, one at a time or several in parallel. Each individual task is called a **job**.
+
+This module gives you three things you'd normally have to build by hand:
+
+1. **Declarative, type-safe jobs** — you define each job once with `defineJob` (name, validation schema, number of attempts) and then call `MyJob.dispatch(data)` anywhere in the application. Data is validated with Zod *before* entering the queue, so invalid data never reaches the worker.
+2. **Context propagation** — information from the current request (`requestId`, `tenantId`, `userId`, etc.) automatically travels along with the job and is restored inside the worker. Your logs and tenant checks work in the worker the same way they did in the HTTP request.
+3. **Two interchangeable drivers** — in production, use **BullMQ** (over Redis, with real retries and delays); in development and tests, use the **sync** driver, which runs the job immediately, in the same process, without needing Redis installed.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/queue
+```
+
+The package depends on `@basaltkit/core` and `@basaltkit/events` (installed automatically). For production you also need an accessible **Redis** server (BullMQ stores the queues there). For development and tests you need nothing.
+
+## Get started in 5 minutes
+
+Step by step to get a job working:
+
+**1. Define the job** (in its own file, e.g. `src/jobs/send-welcome-email.ts`):
+
+```ts
+import { defineJob } from '@basaltkit/queue'
+import { z } from 'zod'
+
+export const SendWelcomeEmail = defineJob({
+  name: 'email.welcome',                       // unique job name
+  schema: z.object({ userId: z.string() }),    // shape of the data (validated)
+  attempts: 3,                                 // retry up to 3 times on failure
+  backoff: { type: 'exponential', delay: '30s' }, // growing wait time between attempts
+  async handle({ userId }) {
+    // the actual work — runs on the worker
+    console.log(`Sending welcome email to user ${userId}`)
+  },
+})
+```
+
+**2. Register the plugin in the application** (e.g. `src/app.ts`):
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { queuePlugin } from '@basaltkit/queue'
+import { SendWelcomeEmail } from './jobs/send-welcome-email.js'
+
+const app = await createApp({
+  plugins: [
+    queuePlugin({
+      jobs: [SendWelcomeEmail],
+      // no `connection` → sync driver: runs immediately, no Redis needed (ideal for dev)
+    }),
+  ],
+}).boot()
+```
+
+**3. Dispatch the job wherever you need it:**
+
+```ts
+await SendWelcomeEmail.dispatch({ userId: 'u-123' })
+```
+
+Done. In dev, `handle` runs immediately. When you want real production behavior, add the Redis connection and the workers:
+
+```ts
+queuePlugin({
+  jobs: [SendWelcomeEmail],
+  connection: 'redis://localhost:6379',        // activates the BullMQ driver
+  workers: [{ queue: 'default', concurrency: 5 }], // this process processes the queue
+})
+```
+
+## Usage guide
+
+### Defining a job with `defineJob`
+
+```ts
+import { defineJob } from '@basaltkit/queue'
+import { z } from 'zod'
+
+export const GenerateInvoice = defineJob({
+  name: 'billing.invoice',
+  schema: z.object({ orderId: z.string() }),
+  queue: 'billing',      // dedicated queue (default: 'default')
+  attempts: 5,
+  backoff: { type: 'fixed', delay: '1m' },
+  async handle({ orderId }) {
+    // generate the invoice…
+  },
+})
+```
+
+`schema` is optional but recommended: it validates the data **twice** — on `dispatch` (before entering the queue) and on the worker (before running). An invalid payload throws `JobValidationError` right at `dispatch`, without polluting the queue.
+
+### Dispatching with delay or priority
+
+```ts
+import { GenerateInvoice } from './jobs/generate-invoice.js'
+
+// runs 10 minutes from now
+await GenerateInvoice.dispatch({ orderId: 'o-1' }, { delay: '10m' })
+
+// priority (lower number = higher priority, BullMQ semantics)
+await GenerateInvoice.dispatch({ orderId: 'o-2' }, { priority: 1 })
+```
+
+Note: with the sync driver, `delay` is ignored — the job runs immediately.
+
+### Context propagation (tenant, requestId…)
+
+If you dispatch a job inside a request with active context (`runWithContext` from `@basaltkit/core`, usually done by HTTP middleware), the fields `requestId`, `correlationId`, `traceId`, `userId`, `tenantId` — and `tenant.id` / `user.id` — are captured and restored inside `handle`:
+
+```ts
+import { ctx, runWithContext } from '@basaltkit/core'
+import { defineJob, QueueManager, SyncQueueDriver } from '@basaltkit/queue'
+
+const job = defineJob({
+  name: 'ctx.probe',
+  handle: () => {
+    // inside the worker, the original context is available
+    console.log(ctx().requestId, ctx()['tenant'])
+  },
+})
+
+const manager = new QueueManager(new SyncQueueDriver())
+manager.register(job)
+
+await runWithContext({ requestId: 'req-7', tenant: { id: 'acme', name: 'Acme' } }, () =>
+  job.dispatch({}),
+)
+// inside handle: requestId = 'req-7', tenant = { id: 'acme' }  (only the id is serialized)
+```
+
+### Turning an event listener into a job: `queuedOn`
+
+If you use `@basaltkit/events`, `queuedOn` bridges events→queue: `emit` just puts the job on the queue, and the handler runs on the worker with retries and restored context.
+
+```ts
+import { EventBus, defineEvent } from '@basaltkit/events'
+import { QueueManager, SyncQueueDriver, queuedOn } from '@basaltkit/queue'
+import { z } from 'zod'
+
+const bus = new EventBus()
+const manager = new QueueManager(new SyncQueueDriver())
+const OrderCreated = defineEvent('order.created', z.object({ orderId: z.string() }))
+
+const unsubscribe = queuedOn(bus, manager, OrderCreated, async ({ orderId }) => {
+  // runs on the worker, with the driver's retry/backoff
+}, { queue: 'orders', attempts: 3 })
+
+await bus.emit(OrderCreated, { orderId: 'o-1' })
+// the created job is named 'listener:order.created'
+```
+
+`queuedOn` returns the function to cancel the subscription.
+
+### Producer and worker in separate processes (production)
+
+One process can only **produce** (call `dispatch`) and another only **consume** (run workers). Both must register the **same jobs** (the worker needs the `handle`):
+
+```ts
+// API process (produces only)
+queuePlugin({ jobs: [SendWelcomeEmail, GenerateInvoice], connection: process.env.REDIS_URL! })
+
+// worker process (consumes)
+queuePlugin({
+  jobs: [SendWelcomeEmail, GenerateInvoice],
+  connection: process.env.REDIS_URL!,
+  workers: [
+    { queue: 'default', concurrency: 5 },
+    { queue: 'billing', concurrency: 2 },
+  ],
+})
+```
+
+If a job reaches a worker that hasn't registered it, `UnknownJobError` is thrown.
+
+### Manual use without a plugin (e.g. in tests)
+
+```ts
+import { QueueManager, SyncQueueDriver, defineJob } from '@basaltkit/queue'
+
+const driver = new SyncQueueDriver()
+const manager = new QueueManager(driver)
+
+const job = defineJob({ name: 'demo', handle: () => {} })
+manager.register(job)
+
+await job.dispatch({})
+console.log(driver.executed) // [{ queue: 'default', jobName: 'demo', attempts: 1 }]
+```
+
+`SyncQueueDriver` keeps a history in `driver.executed` — very handy for test assertions.
+
+## API reference
+
+### `defineJob<T>(config): JobDefinition<T>`
+
+| Option | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `name` | `string` | Yes | — | Unique job name (e.g. `'email.welcome'`). |
+| `schema` | `JobSchema<T>` (Zod-compatible) | No | — | Validates the payload on dispatch and on the worker. |
+| `queue` | `string` | No | `'default'` | Name of the queue the job goes into. |
+| `attempts` | `number` | No | `1` | Maximum number of attempts on failure. |
+| `backoff` | `JobBackoff` | No | — | Wait strategy between attempts. |
+| `handle` | `(payload: T) => void \| Promise<void>` | Yes | — | The function that does the work (runs on the worker). |
+
+The returned object (`JobDefinition<T>`) exposes:
+
+- `dispatch(payload, options?)` — puts the job on the queue. Throws `JobNotRegisteredError` if the job hasn't yet been registered with a `QueueManager`.
+- `name`, `schema`, `queue`, `attempts`, `backoff`, `handle` — the configured values.
+- `__bind(dispatcher)` — **Advanced/internal**: used by `QueueManager` on registration.
+
+### `DispatchOptions`
+
+| Field | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `delay` | `DurationInput` (e.g. `'30s'`, `'10m'`, or ms) | No | no delay | Delays execution (BullMQ driver only). |
+| `priority` | `number` | No | — | BullMQ priority (lower = higher priority). |
+
+### `JobBackoff`
+
+| Field | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `type` | `'exponential' \| 'fixed'` | Yes | — | Growing or constant wait between attempts. |
+| `delay` | `DurationInput` | Yes | — | Base wait (e.g. `'30s'`). |
+
+### `queuePlugin(options?: QueuePluginOptions)`
+
+Basalt plugin that registers a `QueueManager` in the container under the `QUEUE` token, starts workers on `boot`, and closes everything on `shutdown`.
+
+| Option | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `jobs` | `JobDefinition[]` | No | `[]` | Jobs known to this process (producer and/or worker). |
+| `connection` | `string \| ConnectionOptions` | No | — | Redis URL (`redis://…` or `rediss://…`) or ioredis options. With a value → BullMQ driver; without one → sync driver. |
+| `driver` | `QueueDriver` | No | — | Custom driver — takes precedence over `connection`. |
+| `workers` | `{ queue: string; concurrency?: number }[]` | No | `[]` | Queues whose workers start in this process on boot. |
+
+```ts
+import { QUEUE } from '@basaltkit/queue'
+const manager = app.container.get(QUEUE) // get the QueueManager from the container
+```
+
+### `class QueueManager` — implements `JobDispatcher`
+
+| Method | Signature | Description |
+|---|---|---|
+| `constructor` | `new QueueManager(driver: QueueDriver)` | Creates the manager over a driver. |
+| `register` | `(job) => this` | Registers a job and wires its `dispatch`. |
+| `dispatch` | `<T>(job, payload: T, options?: DispatchOptions) => Promise<void>` | Validates and puts the job on the queue. Auto-registers the job if not registered yet. |
+| `work` | `(queue = 'default', { concurrency? }?) => void` | Starts a worker for the queue (no-op on the sync driver). |
+| `close` | `() => Promise<void>` | Closes workers and connections. |
+
+### `queuedOn<T>(bus, manager, event, handler, options?): () => void`
+
+Creates the event→job bridge. Returns the subscription cancel function.
+
+`QueuedListenerOptions`:
+
+| Field | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `queue` | `string` | No | `'default'` | Queue for the created job. |
+| `attempts` | `number` | No | `1` | Job attempts. |
+| `backoff` | `JobBackoff` | No | — | Job backoff. |
+
+### Drivers
+
+- **`class SyncQueueDriver`** — runs inline on `dispatch`, honors `attempts` (immediate retry). Public property `executed: { queue, jobName, attempts }[]` with the execution history. For testing and dev without Redis.
+- **`class BullmqQueueDriver`** — production over Redis. `new BullmqQueueDriver({ connection })`, where `connection` is a Redis URL or ioredis options (`BullmqDriverOptions`). Completed jobs are cleaned up (keeps 1000); failed jobs are kept.
+- **`interface QueueDriver`** (Advanced) — contract for custom drivers: `setExecutor(executor)`, `add(queue, jobName, data, options: AddJobOptions)`, `startWorker(queue, { concurrency? })`, `close()`. Helper types: `AddJobOptions`, `JobExecutor`.
+
+### Exported errors
+
+| Class | Code | When it occurs |
+|---|---|---|
+| `JobValidationError` | `JOB_INVALID` | Payload doesn't pass the `schema` (has `.job` and `.issues`). |
+| `JobNotRegisteredError` | `QUEUE_JOB_NOT_REGISTERED` | `dispatch` before registering the job with a manager. |
+| `UnknownJobError` | `QUEUE_UNKNOWN_JOB` | The job reached the worker but isn't registered in that process. |
+
+### Token
+
+- `QUEUE: Token<QueueManager>` — injection token to get the manager from the container.
+
+## Common issues and solutions (FAQ)
+
+**"Job X has not been registered in a QueueManager yet" on `dispatch`.**
+The job wasn't passed in `queuePlugin({ jobs: [...] })` nor registered with `manager.register(job)`. Add it to the plugin's job list.
+
+**"Job X reached the worker but is not registered in this process".**
+The worker process doesn't know that job. Producer and worker must register the **same** list of jobs.
+
+**The job never runs in production.**
+Check whether any process started workers for the right queue: `queuePlugin({ workers: [{ queue: 'default' }] })` or `manager.work('default')`. Also check that the job's `queue` matches the worker's.
+
+**`JobValidationError: Invalid payload…`**
+The data passed to `dispatch` doesn't match the `schema`. The error includes `issues` with Zod's details. This is intentional — it protects the queue from corrupted data.
+
+**In dev, `delay` doesn't work.**
+The sync driver always runs immediately. Delays, timed backoff, and priority only have a real effect with the BullMQ driver (with `connection`).
+
+**Do I need Redis to run the tests?**
+No. Without `connection`, the plugin uses `SyncQueueDriver`. You can also instantiate the driver directly and inspect `driver.executed`.
+
+## How it connects to other modules
+
+- **`@basaltkit/core`** — provides `createApp`/`definePlugin` (`queuePlugin` is a core plugin), the ALS context (`runWithContext`/`ctx`) propagated to workers, `parseDuration` (formats `'30s'`, `'10m'`), and the base `BasaltError` class.
+- **`@basaltkit/events`** — via `queuedOn`, any domain event can be processed in the background with retries.
+- **`@basaltkit/scheduler`** — `schedule.job(MyJob, payload)` schedules a `dispatch` for a job from this queue on cron schedules (e.g. daily reconciliation at 03:00).
+- **`@basaltkit/logger`** — since context is restored on the worker, logs written inside `handle` automatically carry `requestId`/`tenantId` from the original request.
+- **`@basaltkit/audit`** and **`@basaltkit/activity`** — records made inside a `handle` inherit the same context (actor, tenant), keeping the trail consistent between the request and the worker.

package/dist/index.d.ts

@@ -0,0 +1,242 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { DurationInput, BasaltError } from '@basaltkit/core';
+import { ConnectionOptions } from 'bullmq';
+import { EventBus, BasaltEvent } from '@basaltkit/events';
+
+interface AddJobOptions {
+    attempts: number;
+    backoff?: {
+        type: 'exponential' | 'fixed';
+        delayMs: number;
+    } | undefined;
+    delayMs?: number | undefined;
+    priority?: number | undefined;
+}
+type JobExecutor = (jobName: string, data: unknown) => Promise<void>;
+/**
+ * What a driver's backend honors. Backends differ: RabbitMQ needs a
+ * dead-letter setup for delayed jobs, Kafka has no message priority, etc. The
+ * QueueManager checks a dispatch's options against these and reacts per the
+ * `onUnsupported` policy instead of silently dropping them. A driver that omits
+ * `capabilities` is assumed fully capable (back-compat for existing drivers).
+ */
+interface DriverCapabilities {
+    /** Honors delayed delivery (`delay`). */
+    delayed: boolean;
+    /** Honors message priority. */
+    priority: boolean;
+    /** Re-runs a failed job up to `attempts` times. */
+    retries: boolean;
+    /** Waits `backoff` between retries (vs retrying immediately). */
+    backoff: boolean;
+}
+/** Queue driver contract. BullMQ in production; sync in tests/dev. */
+interface QueueDriver {
+    /** Short identifier used in diagnostics (e.g. 'bullmq', 'sync'). */
+    readonly name?: string;
+    /** What this backend honors — see {@link DriverCapabilities}. */
+    readonly capabilities?: DriverCapabilities;
+    /** Called once by the QueueManager — how to execute a received job. */
+    setExecutor(executor: JobExecutor): void;
+    add(queue: string, jobName: string, data: unknown, options: AddJobOptions): Promise<void>;
+    /** Starts a worker for the queue (no-op in the sync driver: add executes inline). */
+    startWorker(queue: string, options?: {
+        concurrency?: number;
+    }): void;
+    close(): Promise<void>;
+}
+
+interface BullmqDriverOptions {
+    /** Redis URL (redis://... or rediss://...) or ioredis connection options. */
+    connection: string | ConnectionOptions;
+}
+declare class BullmqQueueDriver implements QueueDriver {
+    readonly name = "bullmq";
+    readonly capabilities: {
+        delayed: boolean;
+        priority: boolean;
+        retries: boolean;
+        backoff: boolean;
+    };
+    private readonly connection;
+    private readonly queues;
+    private readonly workers;
+    private executor;
+    constructor(options: BullmqDriverOptions);
+    setExecutor(executor: JobExecutor): void;
+    add(queue: string, jobName: string, data: unknown, options: AddJobOptions): Promise<void>;
+    startWorker(queue: string, options?: {
+        concurrency?: number;
+    }): void;
+    close(): Promise<void>;
+    private queue;
+}
+
+/** Structural schema compatible with Zod. */
+interface JobSchema<T> {
+    safeParse(input: unknown): {
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    };
+}
+declare class JobValidationError extends BasaltError {
+    readonly job: string;
+    readonly issues: unknown;
+    constructor(job: string, issues: unknown);
+}
+declare class JobNotRegisteredError extends BasaltError {
+    constructor(job: string);
+}
+interface DispatchOptions {
+    delay?: DurationInput;
+    priority?: number;
+}
+interface JobBackoff {
+    type: 'exponential' | 'fixed';
+    delay: DurationInput;
+}
+interface JobDefinition<T = unknown> {
+    readonly name: string;
+    readonly schema?: JobSchema<T> | undefined;
+    readonly queue: string;
+    readonly attempts: number;
+    readonly backoff?: JobBackoff | undefined;
+    handle(payload: T): void | Promise<void>;
+    /** Enqueues the job — available after registration in a QueueManager. */
+    dispatch(payload: T, options?: DispatchOptions): Promise<void>;
+    /** @internal used by the QueueManager when registering */
+    __bind(dispatcher: JobDispatcher): void;
+}
+interface JobDispatcher {
+    dispatch<T>(job: JobDefinition<T>, payload: T, options?: DispatchOptions): Promise<void>;
+}
+/**
+ * Defines a declarative job:
+ *
+ * export const SendWelcomeEmail = defineJob({
+ *   name: 'email.welcome',
+ *   schema: z.object({ userId: z.string() }),
+ *   attempts: 3,
+ *   backoff: { type: 'exponential', delay: '30s' },
+ *   async handle({ userId }) { ... },
+ * })
+ */
+declare function defineJob<T = unknown>(config: {
+    name: string;
+    schema?: JobSchema<T>;
+    queue?: string;
+    attempts?: number;
+    backoff?: JobBackoff;
+    handle(payload: T): void | Promise<void>;
+}): JobDefinition<T>;
+
+declare class UnknownJobError extends BasaltError {
+    constructor(job: string);
+}
+/** A job used an option the active driver doesn't support (with policy 'throw'). */
+declare class UnsupportedJobOptionError extends BasaltError {
+    readonly status = 500;
+    constructor(driver: string, job: string, features: string[]);
+}
+/**
+ * What to do when a dispatch uses an option the driver can't honor:
+ * - `throw`: raise {@link UnsupportedJobOptionError} (strict; recommended in prod)
+ * - `warn`: log once per job+feature and proceed (default — never silent)
+ * - `ignore`: proceed silently (legacy behavior)
+ */
+type UnsupportedPolicy = 'throw' | 'warn' | 'ignore';
+interface QueueManagerOptions {
+    /** Reaction when a job uses an option the driver can't honor. Default 'warn'. */
+    onUnsupported?: UnsupportedPolicy;
+    /** Sink for 'warn' diagnostics. Default console.warn. */
+    warn?: (message: string) => void;
+}
+declare class QueueManager implements JobDispatcher {
+    private readonly driver;
+    private readonly jobs;
+    private readonly onUnsupported;
+    private readonly warn;
+    private readonly warned;
+    constructor(driver: QueueDriver, options?: QueueManagerOptions);
+    /**
+     * Checks the dispatch's options against the driver's declared capabilities.
+     * A driver that omits `capabilities` is assumed fully capable (back-compat).
+     */
+    private assertSupported;
+    register(job: JobDefinition<never> | JobDefinition<unknown>): this;
+    dispatch<T>(job: JobDefinition<T>, payload: T, options?: DispatchOptions): Promise<void>;
+    /** Starts a worker for the queue. With the sync driver it is a no-op. */
+    work(queue?: string, options?: {
+        concurrency?: number;
+    }): void;
+    close(): Promise<void>;
+    /** Executes a job received from the driver: validates, restores the context, runs the handler. */
+    private execute;
+}
+
+interface QueuedListenerOptions {
+    queue?: string;
+    attempts?: number;
+    backoff?: JobBackoff;
+}
+/**
+ * The events→queue bridge: the listener becomes a job — emit only enqueues,
+ * and the handler runs in the worker with the driver's retry/backoff and the
+ * context (tenant/requestId) restored.
+ *
+ * queuedOn(bus, queue, OrderCreated, async ({ orderId }) => { ... })
+ *
+ * Returns the listener's unsubscribe function.
+ */
+declare function queuedOn<T>(bus: EventBus, manager: QueueManager, event: BasaltEvent<T>, handler: (payload: T) => void | Promise<void>, options?: QueuedListenerOptions): () => void;
+
+/**
+ * Synchronous driver: executes the job inline on dispatch, honoring `attempts`
+ * (immediate retry). It is the driver for tests and Redis-less dev — the
+ * equivalent of Laravel's `sync` queue driver.
+ */
+declare class SyncQueueDriver implements QueueDriver {
+    readonly name = "sync";
+    readonly capabilities: {
+        delayed: boolean;
+        priority: boolean;
+        retries: boolean;
+        backoff: boolean;
+    };
+    private executor;
+    /** execution history — useful in test assertions */
+    readonly executed: {
+        queue: string;
+        jobName: string;
+        attempts: number;
+    }[];
+    setExecutor(executor: JobExecutor): void;
+    add(queue: string, jobName: string, data: unknown, options: AddJobOptions): Promise<void>;
+    startWorker(): void;
+    close(): Promise<void>;
+}
+
+declare const QUEUE: _basaltkit_core.Token<QueueManager>;
+interface QueuePluginOptions {
+    /** Jobs known to this process (producer and/or worker). */
+    jobs?: JobDefinition<unknown>[];
+    /** Redis connection → BullMQ driver. No connection → sync driver (dev/test). */
+    connection?: BullmqDriverOptions['connection'];
+    /** Custom driver — overrides `connection`. */
+    driver?: QueueDriver;
+    /** Queues to start workers for in this process at boot. */
+    workers?: {
+        queue: string;
+        concurrency?: number;
+    }[];
+    /**
+     * What to do when a job uses an option the driver can't honor (e.g. a
+     * delayed job on a driver without delayed delivery). Default 'warn' — set
+     * 'throw' in production for a hard guarantee, 'ignore' for the old behavior.
+     */
+    onUnsupported?: UnsupportedPolicy;
+}
+declare function queuePlugin(options?: QueuePluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+
+export { type AddJobOptions, type BullmqDriverOptions, BullmqQueueDriver, type DispatchOptions, type DriverCapabilities, type JobBackoff, type JobDefinition, type JobExecutor, JobNotRegisteredError, type JobSchema, JobValidationError, QUEUE, type QueueDriver, QueueManager, type QueueManagerOptions, type QueuePluginOptions, type QueuedListenerOptions, SyncQueueDriver, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, defineJob, queuePlugin, queuedOn };

package/dist/index.js

@@ -0,0 +1,324 @@
+// src/index.ts
+import { createToken, definePlugin } from "@basaltkit/core";
+
+// src/drivers/bullmq.ts
+import { Queue, Worker } from "bullmq";
+var BullmqQueueDriver = class {
+  name = "bullmq";
+  capabilities = { delayed: true, priority: true, retries: true, backoff: true };
+  connection;
+  queues = /* @__PURE__ */ new Map();
+  workers = [];
+  executor;
+  constructor(options) {
+    this.connection = typeof options.connection === "string" ? parseRedisUrl(options.connection) : options.connection;
+  }
+  setExecutor(executor) {
+    this.executor = executor;
+  }
+  async add(queue, jobName, data, options) {
+    await this.queue(queue).add(jobName, data, {
+      attempts: options.attempts,
+      ...options.backoff ? { backoff: { type: options.backoff.type, delay: options.backoff.delayMs } } : {},
+      ...options.delayMs !== void 0 ? { delay: options.delayMs } : {},
+      ...options.priority !== void 0 ? { priority: options.priority } : {},
+      removeOnComplete: { count: 1e3 },
+      removeOnFail: false
+    });
+  }
+  startWorker(queue, options = {}) {
+    this.workers.push(
+      new Worker(queue, async (job) => this.executor?.(job.name, job.data), {
+        connection: this.connection,
+        concurrency: options.concurrency ?? 1
+      })
+    );
+  }
+  async close() {
+    await Promise.all(this.workers.map((worker) => worker.close()));
+    await Promise.all([...this.queues.values()].map((queue) => queue.close()));
+  }
+  queue(name) {
+    let queue = this.queues.get(name);
+    if (!queue) {
+      queue = new Queue(name, { connection: this.connection });
+      this.queues.set(name, queue);
+    }
+    return queue;
+  }
+};
+function parseRedisUrl(url) {
+  const parsed = new URL(url);
+  return {
+    host: parsed.hostname,
+    port: parsed.port ? Number(parsed.port) : 6379,
+    ...parsed.username ? { username: parsed.username } : {},
+    ...parsed.password ? { password: parsed.password } : {},
+    ...parsed.pathname && parsed.pathname !== "/" ? { db: Number(parsed.pathname.slice(1)) } : {},
+    ...parsed.protocol === "rediss:" ? { tls: {} } : {},
+    // required by BullMQ for workers
+    maxRetriesPerRequest: null
+  };
+}
+
+// src/drivers/sync.ts
+var SyncQueueDriver = class {
+  name = "sync";
+  // Runs inline on dispatch: retries are honored (immediately), but there is no
+  // deferred delivery and no ordering, so delayed/priority are not supported.
+  capabilities = { delayed: false, priority: false, retries: true, backoff: false };
+  executor;
+  /** execution history — useful in test assertions */
+  executed = [];
+  setExecutor(executor) {
+    this.executor = executor;
+  }
+  async add(queue, jobName, data, options) {
+    let lastError;
+    for (let attempt = 1; attempt <= options.attempts; attempt++) {
+      try {
+        await this.executor?.(jobName, data);
+        this.executed.push({ queue, jobName, attempts: attempt });
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    this.executed.push({ queue, jobName, attempts: options.attempts });
+    throw lastError;
+  }
+  startWorker() {
+  }
+  async close() {
+  }
+};
+
+// src/manager.ts
+import {
+  BasaltError as BasaltError2,
+  parseDuration,
+  runWithContext,
+  tryCtx
+} from "@basaltkit/core";
+
+// src/job.ts
+import { BasaltError } from "@basaltkit/core";
+var JobValidationError = class extends BasaltError {
+  constructor(job, issues) {
+    super("JOB_INVALID", `Invalid payload for job "${job}": ${JSON.stringify(issues)}`);
+    this.job = job;
+    this.issues = issues;
+  }
+  job;
+  issues;
+};
+var JobNotRegisteredError = class extends BasaltError {
+  constructor(job) {
+    super(
+      "QUEUE_JOB_NOT_REGISTERED",
+      `Job "${job}" has not been registered in a QueueManager yet. Add it to queuePlugin({ jobs: [...] }) or call manager.register(job).`
+    );
+  }
+};
+function defineJob(config) {
+  let dispatcher;
+  const job = {
+    name: config.name,
+    schema: config.schema,
+    queue: config.queue ?? "default",
+    attempts: config.attempts ?? 1,
+    backoff: config.backoff,
+    handle: config.handle,
+    async dispatch(payload, options) {
+      if (!dispatcher) throw new JobNotRegisteredError(config.name);
+      return dispatcher.dispatch(job, payload, options);
+    },
+    __bind(d) {
+      dispatcher = d;
+    }
+  };
+  return job;
+}
+function validatePayload(job, payload) {
+  if (!job.schema) return payload;
+  const result = job.schema.safeParse(payload);
+  if (!result.success) {
+    const issues = result.error?.issues ?? result.error ?? "unknown";
+    throw new JobValidationError(job.name, issues);
+  }
+  return result.data;
+}
+
+// src/manager.ts
+var UnknownJobError = class extends BasaltError2 {
+  constructor(job) {
+    super(
+      "QUEUE_UNKNOWN_JOB",
+      `Job "${job}" reached the worker but is not registered in this process. Make sure the worker registers the same jobs as the producer.`
+    );
+  }
+};
+var UnsupportedJobOptionError = class extends BasaltError2 {
+  status = 500;
+  constructor(driver, job, features) {
+    super(
+      "QUEUE_UNSUPPORTED_OPTION",
+      `The "${driver}" queue driver does not support ${features.join(", ")} (job "${job}"). Use a driver that supports it, remove the option, or set queuePlugin({ onUnsupported: 'warn' | 'ignore' }).`
+    );
+  }
+};
+var requiredCapabilities = (options) => {
+  const needed = [];
+  if (options.delayMs !== void 0 && options.delayMs > 0) needed.push("delayed");
+  if (options.priority !== void 0) needed.push("priority");
+  if (options.attempts > 1) needed.push("retries");
+  if (options.backoff && options.attempts > 1) needed.push("backoff");
+  return needed;
+};
+var FEATURE_LABELS = {
+  delayed: "delayed jobs (delay)",
+  priority: "priority",
+  retries: "retries (attempts > 1)",
+  backoff: "retry backoff"
+};
+var SNAPSHOT_FIELDS = ["requestId", "correlationId", "traceId", "userId", "tenantId"];
+var QueueManager = class {
+  constructor(driver, options = {}) {
+    this.driver = driver;
+    this.onUnsupported = options.onUnsupported ?? "warn";
+    this.warn = options.warn ?? ((message) => console.warn(message));
+    driver.setExecutor((jobName, data) => this.execute(jobName, data));
+  }
+  driver;
+  jobs = /* @__PURE__ */ new Map();
+  onUnsupported;
+  warn;
+  warned = /* @__PURE__ */ new Set();
+  /**
+   * Checks the dispatch's options against the driver's declared capabilities.
+   * A driver that omits `capabilities` is assumed fully capable (back-compat).
+   */
+  assertSupported(jobName, options) {
+    const caps = this.driver.capabilities;
+    if (!caps || this.onUnsupported === "ignore") return;
+    const missing = requiredCapabilities(options).filter((cap) => !caps[cap]);
+    if (missing.length === 0) return;
+    const driverName = this.driver.name ?? "queue";
+    const features = missing.map((cap) => FEATURE_LABELS[cap]);
+    if (this.onUnsupported === "throw") throw new UnsupportedJobOptionError(driverName, jobName, features);
+    const key = `${jobName}:${missing.join(",")}`;
+    if (this.warned.has(key)) return;
+    this.warned.add(key);
+    this.warn(
+      `[basalt/queue] The "${driverName}" driver does not support ${features.join(", ")} \u2014 job "${jobName}" will run without it.`
+    );
+  }
+  register(job) {
+    this.jobs.set(job.name, job);
+    job.__bind(this);
+    return this;
+  }
+  async dispatch(job, payload, options = {}) {
+    if (!this.jobs.has(job.name)) this.register(job);
+    const envelope = {
+      payload: validatePayload(job, payload),
+      context: snapshotContext()
+    };
+    const addOptions = {
+      attempts: job.attempts,
+      backoff: job.backoff ? { type: job.backoff.type, delayMs: parseDuration(job.backoff.delay) } : void 0,
+      delayMs: options.delay === void 0 ? void 0 : parseDuration(options.delay),
+      priority: options.priority
+    };
+    this.assertSupported(job.name, addOptions);
+    await this.driver.add(job.queue, job.name, envelope, addOptions);
+  }
+  /** Starts a worker for the queue. With the sync driver it is a no-op. */
+  work(queue = "default", options = {}) {
+    this.driver.startWorker(queue, options);
+  }
+  async close() {
+    await this.driver.close();
+  }
+  /** Executes a job received from the driver: validates, restores the context, runs the handler. */
+  async execute(jobName, data) {
+    const job = this.jobs.get(jobName);
+    if (!job) throw new UnknownJobError(jobName);
+    const envelope = data;
+    const payload = validatePayload(job, envelope.payload);
+    await runWithContext({ ...envelope.context ?? {} }, () => job.handle(payload));
+  }
+};
+function snapshotContext() {
+  const context = tryCtx();
+  if (!context) return void 0;
+  const snapshot = {};
+  for (const field of SNAPSHOT_FIELDS) {
+    if (context[field] !== void 0) snapshot[field] = context[field];
+  }
+  const tenant = context["tenant"];
+  if (tenant?.id) snapshot["tenant"] = { id: tenant.id };
+  const user = context["user"];
+  if (user?.id && snapshot["userId"] === void 0) snapshot["userId"] = user.id;
+  return Object.keys(snapshot).length > 0 ? snapshot : void 0;
+}
+
+// src/bridge.ts
+function queuedOn(bus, manager, event, handler, options = {}) {
+  const job = defineJob({
+    name: `listener:${event.name}`,
+    ...event.schema ? { schema: event.schema } : {},
+    ...options.queue ? { queue: options.queue } : {},
+    ...options.attempts !== void 0 ? { attempts: options.attempts } : {},
+    ...options.backoff ? { backoff: options.backoff } : {},
+    handle: handler
+  });
+  manager.register(job);
+  return bus.on(event, async (payload) => {
+    await job.dispatch(payload);
+  });
+}
+
+// src/index.ts
+var QUEUE = createToken("queue");
+function queuePlugin(options = {}) {
+  return definePlugin({
+    name: "basalt:queue",
+    register({ container }) {
+      container.singleton(QUEUE, () => {
+        const driver = options.driver ?? (options.connection ? new BullmqQueueDriver({ connection: options.connection }) : new SyncQueueDriver());
+        const manager = new QueueManager(
+          driver,
+          options.onUnsupported !== void 0 ? { onUnsupported: options.onUnsupported } : {}
+        );
+        for (const job of options.jobs ?? []) manager.register(job);
+        return manager;
+      });
+    },
+    boot({ container }) {
+      const manager = container.get(QUEUE);
+      for (const worker of options.workers ?? []) {
+        manager.work(
+          worker.queue,
+          worker.concurrency !== void 0 ? { concurrency: worker.concurrency } : {}
+        );
+      }
+    },
+    async shutdown({ container }) {
+      await container.get(QUEUE).close();
+    }
+  });
+}
+export {
+  BullmqQueueDriver,
+  JobNotRegisteredError,
+  JobValidationError,
+  QUEUE,
+  QueueManager,
+  SyncQueueDriver,
+  UnknownJobError,
+  UnsupportedJobOptionError,
+  defineJob,
+  queuePlugin,
+  queuedOn
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@basaltkit/queue",
+  "version": "1.0.0",
+  "description": "Basalt queues on top of BullMQ: declarative jobs with Zod payloads, context propagation (tenant/requestId) to workers and a sync driver for tests.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "bullmq": "^5.44.0",
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/events": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/queue"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/queue#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "queue",
+    "jobs",
+    "bullmq"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}