@basaltkit/queue 1.2.0 → 1.3.0

package/dist/manager.d.ts

@@ -0,0 +1,61 @@
+import { BasaltError } from '@basaltkit/core';
+import type { QueueDriver, QueueStats } from './driver.js';
+import { type DispatchOptions, type JobDefinition, type JobDispatcher, type JobRetention } from './job.js';
+export declare class UnknownJobError extends BasaltError {
+    constructor(job: string);
+}
+/** A job used an option the active driver doesn't support (with policy 'throw'). */
+export 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)
+ */
+export type UnsupportedPolicy = 'throw' | 'warn' | 'ignore';
+export 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;
+}
+export 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;
+}

package/dist/manager.js

@@ -0,0 +1,161 @@
+import { BasaltError, parseDuration, runWithContext, tryCtx, } from '@basaltkit/core';
+import { validatePayload, } from './job.js';
+/** Convert a public {@link JobRetention} to the driver-neutral shape (age → ms). */
+function resolveRetention(retention) {
+    if (retention === undefined)
+        return undefined;
+    if (typeof retention === 'boolean' || typeof retention === 'number')
+        return retention;
+    const out = {};
+    if (retention.age !== undefined)
+        out.ageMs = parseDuration(retention.age);
+    if (retention.count !== undefined)
+        out.count = retention.count;
+    return out;
+}
+export class UnknownJobError extends BasaltError {
+    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.');
+    }
+}
+/** A job used an option the active driver doesn't support (with policy 'throw'). */
+export class UnsupportedJobOptionError extends BasaltError {
+    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' }).`);
+    }
+}
+/** Maps a dispatch's options to the capability each one requires. */
+const requiredCapabilities = (options) => {
+    const needed = [];
+    if (options.delayMs !== undefined && options.delayMs > 0)
+        needed.push('delayed');
+    if (options.priority !== undefined)
+        needed.push('priority');
+    if (options.attempts > 1)
+        needed.push('retries');
+    if (options.backoff && options.attempts > 1)
+        needed.push('backoff');
+    return needed;
+};
+const FEATURE_LABELS = {
+    delayed: 'delayed jobs (delay)',
+    priority: 'priority',
+    retries: 'retries (attempts > 1)',
+    backoff: 'retry backoff',
+};
+/** Context fields serialized along with the payload and restored in the worker. */
+const SNAPSHOT_FIELDS = ['requestId', 'correlationId', 'traceId', 'userId', 'tenantId'];
+export class QueueManager {
+    driver;
+    jobs = new Map();
+    onUnsupported;
+    warn;
+    warned = new Set();
+    defaultRemoveOnComplete;
+    defaultRemoveOnFail;
+    constructor(driver, options = {}) {
+        this.driver = driver;
+        this.onUnsupported = options.onUnsupported ?? 'warn';
+        this.warn = options.warn ?? ((message) => console.warn(message));
+        this.defaultRemoveOnComplete = options.removeOnComplete;
+        this.defaultRemoveOnFail = options.removeOnFail;
+        driver.setExecutor((jobName, data) => this.execute(jobName, data));
+    }
+    /**
+     * 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; // warn once per job+feature combination
+        this.warned.add(key);
+        this.warn(`[basalt/queue] The "${driverName}" driver does not support ${features.join(', ')} — ` +
+            `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) }
+                : undefined,
+            delayMs: options.delay === undefined ? undefined : parseDuration(options.delay),
+            priority: options.priority,
+            // Per-job overrides the queuePlugin default; undefined leaves the driver default.
+            removeOnComplete: resolveRetention(job.removeOnComplete ?? this.defaultRemoveOnComplete),
+            removeOnFail: resolveRetention(job.removeOnFail ?? this.defaultRemoveOnFail),
+        };
+        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);
+    }
+    /** Job counts per state, or `undefined` if the driver can't introspect. */
+    async stats(queue = 'default') {
+        return this.driver.stats?.(queue);
+    }
+    /**
+     * Re-enqueues failed jobs; returns the count, or `undefined` if the driver
+     * doesn't support retrying (e.g. the inline sync driver).
+     */
+    async retryFailed(queue = 'default', options = {}) {
+        return this.driver.retryFailed?.(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));
+    }
+}
+/** Extracts from the current context only what is serializable and useful in the worker. */
+function snapshotContext() {
+    const context = tryCtx();
+    if (!context)
+        return undefined;
+    const snapshot = {};
+    for (const field of SNAPSHOT_FIELDS) {
+        if (context[field] !== undefined)
+            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'] === undefined)
+        snapshot['userId'] = user.id;
+    return Object.keys(snapshot).length > 0 ? snapshot : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.2.0",
+  "version": "1.3.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",
@@ -14,16 +14,15 @@
     "dist"
   ],
   "dependencies": {
-    "bullmq": "^5.44.0",
-    "@basaltkit/core": "^1.0.0",
-    "@basaltkit/events": "^1.0.0"
+    "bullmq": "^6.2.1",
+    "@basaltkit/core": "^1.3.0",
+    "@basaltkit/events": "^1.0.1"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "zod": "^3.24.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^3.24.0 || ^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -31,11 +30,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/queue"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/queue#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/queue#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -44,7 +43,7 @@
     "bullmq"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }