@basaltkit/queue 1.1.0 → 1.2.0

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

@@ -39,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'). */
@@ -52,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>;
 }
 
@@ -77,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;
 }
@@ -201,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;
@@ -281,4 +315,4 @@ interface QueuePluginOptions {
 }
 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 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,5 +1,5 @@
 // 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";
@@ -42,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()));
@@ -262,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();
   }
@@ -310,6 +341,7 @@ 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, {
@@ -335,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.1.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",