@basaltkit/queue 1.2.0 → 1.3.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @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.

package/dist/bridge.d.ts

@@ -0,0 +1,18 @@
+import type { EventBus, BasaltEvent } from '@basaltkit/events';
+import { type JobBackoff } from './job.js';
+import type { QueueManager } from './manager.js';
+export 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.
+ */
+export declare function queuedOn<T>(bus: EventBus, manager: QueueManager, event: BasaltEvent<T>, handler: (payload: T) => void | Promise<void>, options?: QueuedListenerOptions): () => void;

package/dist/bridge.js

@@ -0,0 +1,24 @@
+import { defineJob } from './job.js';
+/**
+ * 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.
+ */
+export 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 !== undefined ? { attempts: options.attempts } : {}),
+        ...(options.backoff ? { backoff: options.backoff } : {}),
+        handle: handler,
+    });
+    manager.register(job);
+    return bus.on(event, async (payload) => {
+        await job.dispatch(payload);
+    });
+}

package/dist/driver.d.ts

@@ -0,0 +1,72 @@
+/** Driver-neutral retention: `true`/`false`, a count, or `{ ageMs, count }`. */
+export type RetentionOption = boolean | number | {
+    ageMs?: number;
+    count?: number;
+};
+export interface AddJobOptions {
+    attempts: number;
+    backoff?: {
+        type: 'exponential' | 'fixed';
+        delayMs: number;
+    } | undefined;
+    delayMs?: number | undefined;
+    priority?: number | undefined;
+    /** Retention for completed jobs. Undefined → the driver's default. */
+    removeOnComplete?: RetentionOption | undefined;
+    /** Retention for failed jobs. Undefined → the driver's default. */
+    removeOnFail?: RetentionOption | undefined;
+}
+export 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).
+ */
+export 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;
+}
+/** Job counts per state, for `basalt queue:stats`. */
+export interface QueueStats {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+}
+/** Queue driver contract. BullMQ in production; sync in tests/dev. */
+export 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;
+    /**
+     * Optional: job counts per state, for `basalt queue:stats`. Backends that
+     * cannot introspect (e.g. the inline sync driver) omit it — the CLI then
+     * reports the operation as unsupported rather than guessing.
+     */
+    stats?(queue: string): Promise<QueueStats>;
+    /**
+     * Optional: re-enqueue failed jobs (`basalt queue:retry`). Returns how many
+     * were retried. `limit` caps how many are processed (default driver's choice).
+     */
+    retryFailed?(queue: string, options?: {
+        limit?: number;
+    }): Promise<number>;
+    close(): Promise<void>;
+}

package/dist/driver.js

@@ -0,0 +1 @@
+export {};

package/dist/drivers/bullmq.d.ts

@@ -0,0 +1,53 @@
+import { type ConnectionOptions } from 'bullmq';
+import type { AddJobOptions, JobExecutor, QueueDriver, QueueStats } from '../driver.js';
+export interface BullmqDriverOptions {
+    /** Redis URL (redis://... or rediss://...) or ioredis connection options. */
+    connection: string | ConnectionOptions;
+    /**
+     * Infra errors from BullMQ's Worker/Queue emitters (e.g. Redis down). BullMQ
+     * emits these as EventEmitter 'error' events — unhandled, they CRASH the
+     * process. Default: logged via console.error with full context — observable,
+     * never fatal, never silent. (Same pattern as realtime's onBridgeError.)
+     */
+    onError?: (error: unknown, info: {
+        queue: string;
+        source: 'worker' | 'queue';
+    }) => void;
+    /**
+     * A job exhausted its retries (BullMQ 'failed'). Default: console.error —
+     * without this, exhausted jobs were only visible by polling queue stats.
+     */
+    onJobFailed?: (info: {
+        queue: string;
+        job: string;
+        jobId?: string;
+        error: unknown;
+    }) => void;
+}
+export 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;
+    private readonly onError;
+    private readonly onJobFailed;
+    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;
+    stats(queue: string): Promise<QueueStats>;
+    retryFailed(queue: string, options?: {
+        limit?: number;
+    }): Promise<number>;
+    close(): Promise<void>;
+    private queue;
+}

package/dist/drivers/bullmq.js

@@ -0,0 +1,113 @@
+import { Queue, Worker } from 'bullmq';
+/** Map the driver-neutral retention to BullMQ's (age in seconds), falling back to a default. */
+function toBullRetention(retention, fallback) {
+    if (retention === undefined)
+        return fallback;
+    if (typeof retention === 'boolean' || typeof retention === 'number')
+        return retention;
+    const out = {};
+    if (retention.ageMs !== undefined)
+        out.age = Math.max(1, Math.round(retention.ageMs / 1000));
+    if (retention.count !== undefined)
+        out.count = retention.count;
+    return out;
+}
+export class BullmqQueueDriver {
+    name = 'bullmq';
+    capabilities = { delayed: true, priority: true, retries: true, backoff: true };
+    connection;
+    queues = new Map();
+    workers = [];
+    executor;
+    onError;
+    onJobFailed;
+    constructor(options) {
+        this.connection =
+            typeof options.connection === 'string'
+                ? parseRedisUrl(options.connection)
+                : options.connection;
+        this.onError =
+            options.onError ??
+                ((error, info) => console.error(`[basalt:queue] bullmq ${info.source} error (queue "${info.queue}"):`, error));
+        this.onJobFailed =
+            options.onJobFailed ??
+                ((info) => console.error(`[basalt:queue] job "${info.job}"${info.jobId ? ` (id ${info.jobId})` : ''} on queue "${info.queue}" failed permanently:`, info.error));
+    }
+    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 !== undefined ? { delay: options.delayMs } : {}),
+            ...(options.priority !== undefined ? { priority: options.priority } : {}),
+            removeOnComplete: toBullRetention(options.removeOnComplete, { count: 1000 }),
+            removeOnFail: toBullRetention(options.removeOnFail, false),
+        });
+    }
+    startWorker(queue, options = {}) {
+        const worker = new Worker(queue, async (job) => this.executor?.(job.name, job.data), {
+            connection: this.connection,
+            concurrency: options.concurrency ?? 1,
+        });
+        // Without these listeners an emitted 'error' crashes the process (Node
+        // EventEmitter semantics) and exhausted jobs fail invisibly (Q-2).
+        worker.on('error', (error) => this.onError(error, { queue, source: 'worker' }));
+        worker.on('failed', (job, error) => this.onJobFailed({
+            queue,
+            job: job?.name ?? '(unknown)',
+            ...(job?.id !== undefined ? { jobId: String(job.id) } : {}),
+            error,
+        }));
+        this.workers.push(worker);
+    }
+    async stats(queue) {
+        const c = await this.queue(queue).getJobCounts('waiting', 'active', 'completed', 'failed', 'delayed');
+        return {
+            waiting: c['waiting'] ?? 0,
+            active: c['active'] ?? 0,
+            completed: c['completed'] ?? 0,
+            failed: c['failed'] ?? 0,
+            delayed: c['delayed'] ?? 0,
+        };
+    }
+    async retryFailed(queue, options = {}) {
+        const limit = options.limit ?? 1000;
+        const failed = await this.queue(queue).getFailed(0, limit - 1);
+        let retried = 0;
+        for (const job of failed) {
+            await job.retry();
+            retried++;
+        }
+        return retried;
+    }
+    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 });
+            queue.on('error', (error) => this.onError(error, { queue: name, source: 'queue' }));
+            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,
+    };
+}

package/dist/drivers/sync.d.ts

@@ -0,0 +1,26 @@
+import type { AddJobOptions, JobExecutor, QueueDriver } from '../driver.js';
+/**
+ * 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.
+ */
+export 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>;
+}

package/dist/drivers/sync.js

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export class SyncQueueDriver {
+    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() {
+        // no-op: add() already executes inline
+    }
+    async close() { }
+}

package/dist/index.d.ts

@@ -1,289 +1,15 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { DurationInput, BasaltError } from '@basaltkit/core';
-import { ConnectionOptions } from 'bullmq';
-import { EventBus, BasaltEvent } from '@basaltkit/events';
-
-/** Driver-neutral retention: `true`/`false`, a count, or `{ ageMs, count }`. */
-type RetentionOption = boolean | number | {
-    ageMs?: number;
-    count?: number;
-};
-interface AddJobOptions {
-    attempts: number;
-    backoff?: {
-        type: 'exponential' | 'fixed';
-        delayMs: number;
-    } | undefined;
-    delayMs?: number | undefined;
-    priority?: number | undefined;
-    /** Retention for completed jobs. Undefined → the driver's default. */
-    removeOnComplete?: RetentionOption | undefined;
-    /** Retention for failed jobs. Undefined → the driver's default. */
-    removeOnFail?: RetentionOption | 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;
-}
-/** Job counts per state, for `basalt queue:stats`. */
-interface QueueStats {
-    waiting: number;
-    active: number;
-    completed: number;
-    failed: number;
-    delayed: number;
-}
-/** 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;
-    /**
-     * Optional: job counts per state, for `basalt queue:stats`. Backends that
-     * cannot introspect (e.g. the inline sync driver) omit it — the CLI then
-     * reports the operation as unsupported rather than guessing.
-     */
-    stats?(queue: string): Promise<QueueStats>;
-    /**
-     * Optional: re-enqueue failed jobs (`basalt queue:retry`). Returns how many
-     * were retried. `limit` caps how many are processed (default driver's choice).
-     */
-    retryFailed?(queue: string, options?: {
-        limit?: number;
-    }): Promise<number>;
-    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;
-    stats(queue: string): Promise<QueueStats>;
-    retryFailed(queue: string, options?: {
-        limit?: number;
-    }): Promise<number>;
-    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;
-}
-/**
- * Redis retention for finished jobs (BullMQ driver): `true` removes it as soon as
- * it finishes, `false` keeps it forever, a number keeps that many most-recent, and
- * `{ age, count }` keeps by age and/or count. Defaults: completed `{ count: 1000 }`,
- * failed `false` (keep all). The sync driver ignores it (it stores nothing).
- */
-type JobRetention = boolean | number | {
-    age?: DurationInput;
-    count?: number;
-};
-interface JobDefinition<T = unknown> {
-    readonly name: string;
-    readonly schema?: JobSchema<T> | undefined;
-    readonly queue: string;
-    readonly attempts: number;
-    readonly backoff?: JobBackoff | undefined;
-    /** Retention for completed jobs. Overrides the queuePlugin default. */
-    readonly removeOnComplete?: JobRetention | undefined;
-    /** Retention for failed jobs. Overrides the queuePlugin default. */
-    readonly removeOnFail?: JobRetention | 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;
-    removeOnComplete?: JobRetention;
-    removeOnFail?: JobRetention;
-    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;
-    /** Default retention for completed jobs (a job can override). Driver default: keep 1000. */
-    removeOnComplete?: JobRetention;
-    /** Default retention for failed jobs (a job can override). Driver default: keep all. */
-    removeOnFail?: JobRetention;
-}
-declare class QueueManager implements JobDispatcher {
-    private readonly driver;
-    private readonly jobs;
-    private readonly onUnsupported;
-    private readonly warn;
-    private readonly warned;
-    private readonly defaultRemoveOnComplete;
-    private readonly defaultRemoveOnFail;
-    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;
-    /** Job counts per state, or `undefined` if the driver can't introspect. */
-    stats(queue?: string): Promise<QueueStats | undefined>;
-    /**
-     * Re-enqueues failed jobs; returns the count, or `undefined` if the driver
-     * doesn't support retrying (e.g. the inline sync driver).
-     */
-    retryFailed(queue?: string, options?: {
-        limit?: number;
-    }): Promise<number | undefined>;
-    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 {
+import { type BullmqDriverOptions } from './drivers/bullmq.js';
+import type { QueueDriver } from './driver.js';
+import type { JobDefinition, JobRetention } from './job.js';
+import { QueueManager, type UnsupportedPolicy } from './manager.js';
+export { defineJob, JobValidationError, JobNotRegisteredError, type JobDefinition, type JobSchema, type JobBackoff, type JobRetention, type DispatchOptions, } from './job.js';
+export { QueueManager, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, type QueueManagerOptions, } from './manager.js';
+export { queuedOn, type QueuedListenerOptions } from './bridge.js';
+export { SyncQueueDriver } from './drivers/sync.js';
+export { BullmqQueueDriver, type BullmqDriverOptions } from './drivers/bullmq.js';
+export type { QueueDriver, QueueStats, AddJobOptions, JobExecutor, DriverCapabilities } from './driver.js';
+export declare const QUEUE: import("@basaltkit/core").Token<QueueManager>;
+export interface QueuePluginOptions {
     /** Jobs known to this process (producer and/or worker). */
     jobs?: JobDefinition<unknown>[];
     /** Redis connection → BullMQ driver. No connection → sync driver (dev/test). */
@@ -313,6 +39,4 @@ interface QueuePluginOptions {
      */
     removeOnFail?: JobRetention;
 }
-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 JobRetention, type JobSchema, JobValidationError, QUEUE, type QueueDriver, QueueManager, type QueueManagerOptions, type QueuePluginOptions, type QueueStats, type QueuedListenerOptions, SyncQueueDriver, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, defineJob, queuePlugin, queuedOn };
+export declare function queuePlugin(options?: QueuePluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;