@basaltkit/queue 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt 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

package/README.md

@@ -184,6 +184,20 @@ queuePlugin({
 
 If a job reaches a worker that hasn't registered it, `UnknownJobError` is thrown.
 
+### CLI commands (`basalt queue:*`)
+
+Registering `queuePlugin` also wires three CLI commands (run via the `@basaltkit/cli` runner):
+
+```bash
+basalt queue:work --queue=default --concurrency=5   # run a worker until Ctrl+C
+basalt queue:stats --queue=billing                  # waiting/active/completed/failed/delayed
+basalt queue:retry --queue=billing --limit=100      # re-enqueue failed jobs
+```
+
+`queue:stats` and `queue:retry` need a driver that can introspect job state — the
+**BullMQ** driver (a Redis `connection`). With the inline `sync` driver they
+report the operation as unsupported (it keeps no job state), rather than guessing.
+
 ### Manual use without a plugin (e.g. in tests)
 
 ```ts

package/dist/index.d.ts

@@ -3,6 +3,11 @@ 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?: {
@@ -11,6 +16,10 @@ interface AddJobOptions {
     } | 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>;
 /**
@@ -30,6 +39,14 @@ interface DriverCapabilities {
     /** 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'). */
@@ -43,6 +60,19 @@ interface QueueDriver {
     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>;
 }
 
@@ -68,6 +98,10 @@ declare class BullmqQueueDriver implements QueueDriver {
     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;
 }
@@ -96,12 +130,26 @@ 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>;
@@ -128,6 +176,8 @@ declare function defineJob<T = unknown>(config: {
     queue?: string;
     attempts?: number;
     backoff?: JobBackoff;
+    removeOnComplete?: JobRetention;
+    removeOnFail?: JobRetention;
     handle(payload: T): void | Promise<void>;
 }): JobDefinition<T>;
 
@@ -151,6 +201,10 @@ interface QueueManagerOptions {
     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;
@@ -158,6 +212,8 @@ declare class QueueManager implements JobDispatcher {
     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.
@@ -170,6 +226,15 @@ declare class QueueManager implements JobDispatcher {
     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;
@@ -236,7 +301,18 @@ interface QueuePluginOptions {
      * 'throw' in production for a hard guarantee, 'ignore' for the old behavior.
      */
     onUnsupported?: UnsupportedPolicy;
+    /**
+     * Default retention for completed jobs in Redis (BullMQ). `true` removes on
+     * finish, a number keeps that many, `{ age: '7d', count: 500 }` caps both.
+     * Default: keep the last 1000. A job can override via `defineJob`.
+     */
+    removeOnComplete?: JobRetention;
+    /**
+     * Default retention for failed jobs. Default `false` (keep all, for inspection
+     * and retries) — set e.g. `{ age: '14d' }` so failures don't grow unbounded.
+     */
+    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 JobSchema, JobValidationError, QUEUE, type QueueDriver, QueueManager, type QueueManagerOptions, type QueuePluginOptions, type QueuedListenerOptions, SyncQueueDriver, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, defineJob, queuePlugin, queuedOn };
+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 };

package/dist/index.js

@@ -1,8 +1,16 @@
 // src/index.ts
-import { createToken, definePlugin } from "@basaltkit/core";
+import { createToken, definePlugin, ensureMetadata } from "@basaltkit/core";
 
 // src/drivers/bullmq.ts
 import { Queue, Worker } from "bullmq";
+function toBullRetention(retention, fallback) {
+  if (retention === void 0) return fallback;
+  if (typeof retention === "boolean" || typeof retention === "number") return retention;
+  const out = {};
+  if (retention.ageMs !== void 0) out.age = Math.max(1, Math.round(retention.ageMs / 1e3));
+  if (retention.count !== void 0) out.count = retention.count;
+  return out;
+}
 var BullmqQueueDriver = class {
   name = "bullmq";
   capabilities = { delayed: true, priority: true, retries: true, backoff: true };
@@ -22,8 +30,8 @@ var BullmqQueueDriver = class {
       ...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
+      removeOnComplete: toBullRetention(options.removeOnComplete, { count: 1e3 }),
+      removeOnFail: toBullRetention(options.removeOnFail, false)
     });
   }
   startWorker(queue, options = {}) {
@@ -34,6 +42,26 @@ var BullmqQueueDriver = class {
       })
     );
   }
+  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 ?? 1e3;
+    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()));
@@ -128,6 +156,8 @@ function defineJob(config) {
     queue: config.queue ?? "default",
     attempts: config.attempts ?? 1,
     backoff: config.backoff,
+    removeOnComplete: config.removeOnComplete,
+    removeOnFail: config.removeOnFail,
     handle: config.handle,
     async dispatch(payload, options) {
       if (!dispatcher) throw new JobNotRegisteredError(config.name);
@@ -150,6 +180,14 @@ function validatePayload(job, payload) {
 }
 
 // src/manager.ts
+function resolveRetention(retention) {
+  if (retention === void 0) return void 0;
+  if (typeof retention === "boolean" || typeof retention === "number") return retention;
+  const out = {};
+  if (retention.age !== void 0) out.ageMs = parseDuration(retention.age);
+  if (retention.count !== void 0) out.count = retention.count;
+  return out;
+}
 var UnknownJobError = class extends BasaltError2 {
   constructor(job) {
     super(
@@ -187,6 +225,8 @@ var QueueManager = class {
     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));
   }
   driver;
@@ -194,6 +234,8 @@ var QueueManager = class {
   onUnsupported;
   warn;
   warned = /* @__PURE__ */ new Set();
+  defaultRemoveOnComplete;
+  defaultRemoveOnFail;
   /**
    * Checks the dispatch's options against the driver's declared capabilities.
    * A driver that omits `capabilities` is assumed fully capable (back-compat).
@@ -228,7 +270,10 @@ var QueueManager = class {
       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
+      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);
@@ -237,6 +282,17 @@ var QueueManager = class {
   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();
   }
@@ -285,12 +341,14 @@ function queuePlugin(options = {}) {
   return definePlugin({
     name: "basalt:queue",
     register({ container }) {
+      registerQueueCommands(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 } : {}
-        );
+        const manager = new QueueManager(driver, {
+          ...options.onUnsupported !== void 0 ? { onUnsupported: options.onUnsupported } : {},
+          ...options.removeOnComplete !== void 0 ? { removeOnComplete: options.removeOnComplete } : {},
+          ...options.removeOnFail !== void 0 ? { removeOnFail: options.removeOnFail } : {}
+        });
         for (const job of options.jobs ?? []) manager.register(job);
         return manager;
       });
@@ -309,6 +367,54 @@ function queuePlugin(options = {}) {
     }
   });
 }
+function registerQueueCommands(container) {
+  const manager = () => container.get(QUEUE);
+  const unsupported = "Not supported by the active queue driver \u2014 the inline sync driver keeps no job state. Use the BullMQ driver (a Redis `connection`).";
+  ensureMetadata(container).add("commands", {
+    name: "queue:work",
+    description: "Run a worker that processes jobs for a queue (Ctrl+C to stop)",
+    async handle({ io, flags }) {
+      const queue = typeof flags["queue"] === "string" ? flags["queue"] : "default";
+      const concurrency = typeof flags["concurrency"] === "string" ? Number(flags["concurrency"]) : void 0;
+      manager().work(queue, concurrency !== void 0 ? { concurrency } : {});
+      io.log(`Worker started on queue "${queue}"${concurrency ? ` (concurrency ${concurrency})` : ""}. Ctrl+C to stop.`);
+      await new Promise((resolve) => process.once("SIGINT", resolve));
+    }
+  });
+  ensureMetadata(container).add("commands", {
+    name: "queue:stats",
+    description: "Show job counts (waiting/active/completed/failed/delayed) for a queue",
+    async handle({
+      io,
+      flags
+    }) {
+      const queue = typeof flags["queue"] === "string" ? flags["queue"] : "default";
+      const stats = await manager().stats(queue);
+      if (!stats) {
+        io.log(unsupported);
+        return;
+      }
+      io.table([{ queue, ...stats }]);
+    }
+  });
+  ensureMetadata(container).add("commands", {
+    name: "queue:retry",
+    description: "Re-enqueue failed jobs on a queue",
+    async handle({
+      io,
+      flags
+    }) {
+      const queue = typeof flags["queue"] === "string" ? flags["queue"] : "default";
+      const limit = typeof flags["limit"] === "string" ? Number(flags["limit"]) : void 0;
+      const retried = await manager().retryFailed(queue, limit !== void 0 ? { limit } : {});
+      if (retried === void 0) {
+        io.log(unsupported);
+        return;
+      }
+      io.log(`Re-enqueued ${retried} failed job(s) on "${queue}".`);
+    }
+  });
+}
 export {
   BullmqQueueDriver,
   JobNotRegisteredError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.0.0",
+  "version": "1.2.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",