@zerotal/queue 1.0.0

package/src/admin.ts

@@ -0,0 +1,254 @@
+/**
+ * Queue → admin panel contribution.
+ *
+ * The queue already knows how to introspect itself — failed jobs, pending depth
+ * per queue, retry, forget, flush. This module describes that as a console the
+ * admin panel renders, so operators get the same operations the CLI commands
+ * expose without an SSH session.
+ *
+ * The panel's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, exactly as the observer bridges in
+ * `observability.ts` are: the queue depends on `@zerotal/admin` not at all, and
+ * an app running the queue without the panel pulls in nothing extra — the binding
+ * simply isn't there and this returns.
+ */
+import type { Application } from "@zerotal/core";
+import { queueStats } from "./QueueManager.ts";
+import { Queue } from "./facades/Queue.ts";
+
+/** The slice of the admin panel's contribution surface this module uses. */
+interface AdminPanelSink {
+  enabled(id: string): boolean;
+  console(contribution: ConsoleSpec): void;
+}
+
+type Row = Record<string, unknown>;
+type Tone = "primary" | "success" | "muted" | "destructive" | "default";
+
+interface ConsoleSpec {
+  slug: string;
+  title: string;
+  ability: string;
+  navigationIcon?: string;
+  navigationGroup?: string;
+  navigationSort?: number;
+  navigationBadge?: () => Promise<string | number | null>;
+  navigationBadgeColor?: Tone;
+  tabs: Array<{
+    key: string;
+    label: string;
+    description?: string;
+    columns: Array<{
+      key: string;
+      label: string;
+      align?: "start" | "center" | "end";
+      mono?: boolean;
+      format?: (value: unknown, row: Row) => string;
+      badge?: (value: unknown, row: Row) => Tone | null;
+    }>;
+    rows: () => Promise<Row[]>;
+    rowKey?: string;
+    rowActions?: Array<{
+      key: string;
+      label: string;
+      icon?: string;
+      danger?: boolean;
+      confirm?: string;
+      run: (row: Row) => Promise<string | void>;
+    }>;
+    headerActions?: Array<{
+      key: string;
+      label: string;
+      icon?: string;
+      danger?: boolean;
+      confirm?: string;
+      run: () => Promise<string | void>;
+    }>;
+    empty?: string;
+    badge?: () => Promise<number | null>;
+  }>;
+}
+
+/** The ability an operator needs to see and act on the queue console. */
+const ABILITY = "queue.view";
+
+/** Trim a stack trace down to its first line — the table shows the summary. */
+function firstLine(value: unknown): string {
+  const text = value === null || value === undefined ? "" : String(value);
+  const line = text.split("\n")[0]?.trim() ?? "";
+  return line.length > 140 ? `${line.slice(0, 137)}…` : line || "—";
+}
+
+/** Strip the namespace off a job class so the column stays readable. */
+function shortClass(value: unknown): string {
+  const text = String(value ?? "");
+  return text.split(/[\\/.]/).pop() || text;
+}
+
+function formatTime(value: unknown): string {
+  if (value === null || value === undefined || value === "") return "—";
+  const date = typeof value === "number" ? new Date(value * 1000) : new Date(String(value));
+  return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+}
+
+/**
+ * Contribute the queue console to the admin panel, when one is installed.
+ *
+ * Call from `QueueProvider.onBooting()` — the panel binds its surface during the
+ * registration phase, so it is reachable from any provider's booting phase
+ * regardless of the order the two were registered in.
+ */
+export function installQueueAdmin(app: Application): void {
+  const panel = app.container.tryMake("admin.panel" as never) as AdminPanelSink | undefined;
+  if (!panel?.enabled("queue")) return;
+
+  panel.console({
+    slug: "jobs",
+    title: "Jobs",
+    ability: ABILITY,
+    navigationIcon: "collection",
+    navigationGroup: "Operations",
+    navigationBadgeColor: "destructive",
+    // A failed-job count in the sidebar is the whole point of putting the queue in
+    // front of an operator: it is the number you want to notice without looking.
+    navigationBadge: async () => {
+      const failed = await Queue.failed();
+      return failed.length > 0 ? failed.length : null;
+    },
+    tabs: [
+      {
+        key: "failed",
+        label: "Failed",
+        description: "Jobs that exhausted their attempts. Retry puts one back on its queue.",
+        empty: "No failed jobs.",
+        badge: async () => (await Queue.failed()).length,
+        columns: [
+          { key: "id", label: "ID", mono: true },
+          { key: "queue", label: "Queue", badge: () => "muted" },
+          { key: "className", label: "Job", format: shortClass },
+          { key: "attempts", label: "Attempts", align: "end" },
+          { key: "error", label: "Error", mono: true, format: firstLine },
+          { key: "failedAt", label: "Failed", format: formatTime },
+        ],
+        // Projected field by field rather than passed straight through: the
+        // driver record carries the serialized job payload, which has no place
+        // in a table an operator reads over someone's shoulder.
+        rows: async () =>
+          (await Queue.failed()).map((r) => ({
+            id: r.id,
+            queue: r.queue,
+            className: r.className,
+            attempts: r.attempts,
+            error: r.error,
+            failedAt: r.failedAt,
+          })),
+        rowActions: [
+          {
+            key: "retry",
+            label: "Retry",
+            icon: "undo",
+            run: async (row) => {
+              const ok = await Queue.retryFailed(Number(row["id"]));
+              if (!ok) throw new Error("That job is no longer in the failed table.");
+              return `Job ${String(row["id"])} queued for retry.`;
+            },
+          },
+          {
+            key: "forget",
+            label: "Forget",
+            icon: "trash",
+            danger: true,
+            confirm: "Delete this failed job? It cannot be retried afterwards.",
+            run: async (row) => {
+              await Queue.forgetFailed(Number(row["id"]));
+              return `Job ${String(row["id"])} deleted.`;
+            },
+          },
+        ],
+        headerActions: [
+          {
+            key: "clear-failed",
+            label: "Clear failed",
+            icon: "trash",
+            danger: true,
+            confirm: "Delete every failed job? They cannot be retried afterwards.",
+            run: async () => {
+              await Queue.clearFailed();
+              return "Failed jobs cleared.";
+            },
+          },
+        ],
+      },
+      {
+        key: "pending",
+        label: "Pending",
+        description: "Jobs waiting to be picked up by a worker.",
+        empty: "Nothing waiting.",
+        badge: async () => (await Queue.pending()).length,
+        columns: [
+          { key: "id", label: "ID", mono: true },
+          { key: "queue", label: "Queue", badge: () => "muted" },
+          { key: "className", label: "Job", format: shortClass },
+          { key: "attempts", label: "Attempts", align: "end" },
+          { key: "availableAt", label: "Available", format: formatTime },
+          { key: "createdAt", label: "Queued", format: formatTime },
+        ],
+        rows: async () =>
+          (await Queue.pending()).map((r) => ({
+            id: r.id,
+            queue: r.queue,
+            className: r.className,
+            attempts: r.attempts,
+            availableAt: r.availableAt,
+            createdAt: r.createdAt,
+          })),
+        headerActions: [
+          {
+            key: "flush",
+            label: "Flush",
+            icon: "trash",
+            danger: true,
+            confirm: "Discard every pending job? This cannot be undone.",
+            run: async () => {
+              await Queue.flush();
+              return "Pending jobs flushed.";
+            },
+          },
+        ],
+      },
+      {
+        key: "queues",
+        label: "Queues",
+        description: "Pending depth per queue, plus totals since this process started.",
+        empty: "No queues have been used yet.",
+        columns: [
+          { key: "queue", label: "Queue" },
+          { key: "pending", label: "Pending", align: "end" },
+        ],
+        rowKey: "queue",
+        rows: async () =>
+          (await Queue.queues()).map((q) => ({ queue: q.queue, pending: q.pending })),
+      },
+      {
+        key: "throughput",
+        label: "Throughput",
+        description: "Counters kept by this process since it booted — not persisted history.",
+        empty: "Nothing processed yet.",
+        columns: [
+          { key: "metric", label: "Metric" },
+          { key: "value", label: "Count", align: "end" },
+        ],
+        rowKey: "metric",
+        rows: async () => {
+          const s = queueStats();
+          return [
+            { metric: "Processed (total)", value: s.processedTotal },
+            { metric: "Processed (last 5m)", value: s.processedLast5m },
+            { metric: "Failed (total)", value: s.failedTotal },
+            { metric: "Failed (last 5m)", value: s.failedLast5m },
+          ];
+        },
+      },
+    ],
+  });
+}

package/src/commands/QueueFailedCommand.ts

@@ -0,0 +1,57 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { QueueManager } from "../QueueManager.ts";
+import type { QueueDriver } from "../drivers/QueueDriver.ts";
+
+export class QueueFailedCommand extends Command {
+  static override commandName = "queue:failed";
+  static override description = "List all failed jobs";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "queue",
+      short: "q",
+      type: "string" as const,
+      description: "Filter by queue name",
+      default: "",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    const driver = this._driver(app);
+    if (!driver) return;
+
+    const queueName = (this.flags["queue"] as string | undefined) ?? "";
+    const records = await driver.listFailed(queueName || undefined);
+
+    if (records.length === 0) {
+      this.info("No failed jobs found.");
+      return;
+    }
+
+    this.section(`Failed jobs (${records.length})`);
+    for (const r of records) {
+      const err = r.error.length > 70 ? r.error.slice(0, 70) + "…" : r.error;
+      this.table([
+        ["ID", String(r.id)],
+        ["Queue", r.queue],
+        ["Class", r.className],
+        ["Attempts", String(r.attempts)],
+        ["Failed at", r.failedAt],
+        ["Error", err],
+      ]);
+      this.newLine();
+    }
+  }
+
+  private _driver(app: Application | undefined): QueueDriver | null {
+    const manager = app?.container.tryMake("queue") as QueueManager | undefined;
+    if (!manager) {
+      this.error("Queue driver not registered.");
+      return null;
+    }
+    return (manager as unknown as { _driver: QueueDriver })._driver;
+  }
+}

package/src/commands/QueueFlushCommand.ts

@@ -0,0 +1,61 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { QueueManager } from "../QueueManager.ts";
+import type { QueueDriver } from "../drivers/QueueDriver.ts";
+
+export class QueueFlushCommand extends Command {
+  static override commandName = "queue:flush";
+  static override description = "Delete all failed jobs from the database";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "queue",
+      short: "q",
+      type: "string" as const,
+      description: "Only flush failed jobs from the given queue",
+      default: "",
+    },
+    {
+      name: "force",
+      type: "boolean" as const,
+      description: "Skip confirmation prompt",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    const driver = this._driver(app);
+    if (!driver) return;
+
+    const queueName = (this.flags["queue"] as string | undefined) ?? "";
+    const force = (this.flags["force"] as boolean | undefined) ?? false;
+
+    if (!force) {
+      const target = queueName ? `queue "${queueName}"` : "all queues";
+      const ok = await this.confirm(
+        `This will permanently delete all failed jobs for ${target}. Proceed?`,
+      );
+      if (!ok) {
+        this.info("Aborted.");
+        return;
+      }
+    }
+
+    await driver.clearFailed(queueName || undefined);
+
+    this.info(
+      queueName ? `Flushed failed jobs for queue "${queueName}".` : "Flushed all failed jobs.",
+    );
+  }
+
+  private _driver(app: Application | undefined): QueueDriver | null {
+    const manager = app?.container.tryMake("queue") as QueueManager | undefined;
+    if (!manager) {
+      this.error("Queue driver not registered.");
+      return null;
+    }
+    return (manager as unknown as { _driver: QueueDriver })._driver;
+  }
+}

package/src/commands/QueueRetryCommand.ts

@@ -0,0 +1,84 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { QueueManager } from "../QueueManager.ts";
+import type { QueueDriver } from "../drivers/QueueDriver.ts";
+import { JobRegistry } from "../JobRegistry.ts";
+import type { Job } from "../Job.ts";
+
+export class QueueRetryCommand extends Command {
+  static override commandName = "queue:retry";
+  static override description = "Retry a failed job by ID (or 'all' to retry everything)";
+  static override needsApp = true;
+
+  static override args = [{ name: "id", required: true, description: "Failed job ID, or 'all'" }];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    const driver = this._driver(app);
+    if (!driver) return;
+
+    const idArg = this.args["id"] as string;
+    const all = idArg === "all";
+    const id = all ? null : Number(idArg);
+
+    if (!all && isNaN(id!)) {
+      this.error(`Invalid ID "${idArg}". Pass a numeric ID or "all".`);
+      return;
+    }
+
+    const failed = await driver.listFailed();
+    const targets = all ? failed : failed.filter((r) => r.id === id);
+
+    if (targets.length === 0) {
+      this.error(all ? "No failed jobs found." : `No failed job found with ID ${id}.`);
+      return;
+    }
+
+    let retried = 0;
+    for (const record of targets) {
+      const JobClass = JobRegistry.resolve(record.className);
+
+      let instance: Job;
+      if (!JobClass) {
+        this.warn(`Unknown job class "${record.className}" — skipping ID ${record.id}.`);
+        continue;
+      }
+
+      const payload = JSON.parse(record.payload) as Record<string, unknown>;
+      if (
+        "fromPayload" in JobClass &&
+        typeof (JobClass as Record<string, unknown>)["fromPayload"] === "function"
+      ) {
+        instance = (JobClass as { fromPayload(p: Record<string, unknown>): Job }).fromPayload(
+          payload,
+        );
+      } else {
+        instance = new (JobClass as new () => Job)();
+      }
+
+      await driver.push({
+        queue: record.queue,
+        className: record.className,
+        payload: record.payload,
+        attempts: 0,
+        maxAttempts: instance.maxAttempts,
+        retryDelay: instance.retryDelay,
+        availableAt: Math.floor(Date.now() / 1000),
+      });
+
+      await driver.deleteFailedRecord(record.id);
+      retried++;
+    }
+
+    this.info(`Retried ${retried} job(s).`);
+  }
+
+  private _driver(app: Application | undefined): QueueDriver | null {
+    const manager = app?.container.tryMake("queue") as QueueManager | undefined;
+    if (!manager) {
+      this.error("Queue driver not registered.");
+      return null;
+    }
+    return (manager as unknown as { _driver: QueueDriver })._driver;
+  }
+}

package/src/commands/QueueWorkCommand.ts

@@ -0,0 +1,58 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { QueueManager } from "../QueueManager.ts";
+
+export class QueueWorkCommand extends Command {
+  static commandName = "queue:work";
+  static description = "Process jobs from the queue (run this as a daemon in production)";
+  static needsApp = true;
+
+  static flags = [
+    {
+      name: "queue",
+      short: "q",
+      type: "string" as const,
+      description: "Queue name to process",
+      default: "default",
+    },
+    {
+      name: "once",
+      type: "boolean" as const,
+      description: "Process one job then exit",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const queueName = this.flags["queue"] as string;
+    const once = this.flags["once"] as boolean;
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const manager = app.container.makeSync("queue") as QueueManager;
+
+    if (once) {
+      const processed = await manager.processNext(queueName);
+      this.info(processed ? "Processed 1 job." : "Queue is empty.");
+      return;
+    }
+
+    this.info(`Processing queue "${queueName}" — Ctrl+C to stop.`);
+    while (!manager.isShuttingDown) {
+      // Sleep whenever nothing was *claimable* this tick — not merely when the
+      // queue is empty. size() counts not-yet-due delayed jobs and jobs reserved
+      // by other workers, so keying the sleep off size() busy-spins at 100% CPU
+      // whenever a delayed/reserved job exists but nothing is ready.
+      const processed = await manager
+        .processNext(queueName)
+        .catch((err) => (console.error(err), false));
+      if (!processed) {
+        await new Promise<void>((r) => setTimeout(r, 500));
+      }
+    }
+    this.info("Queue worker stopped.");
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,4 @@
+export { QueueWorkCommand } from "./QueueWorkCommand.ts";
+export { QueueFailedCommand } from "./QueueFailedCommand.ts";
+export { QueueRetryCommand } from "./QueueRetryCommand.ts";
+export { QueueFlushCommand } from "./QueueFlushCommand.ts";

package/src/config.ts

@@ -0,0 +1,118 @@
+import { deepMerge } from "@zerotal/core";
+import type { ConfigValidator, ConfigIssue } from "@zerotal/core/config";
+
+export interface QueueConfigShape {
+  /** Queue driver. Default: 'sqlite' */
+  driver: "sqlite" | "redis" | "sync";
+  /** How often the worker polls for new jobs (ms). Default: 500 */
+  pollInterval: number;
+  /** Queue names the worker listens on. Default: ['default'] */
+  queues: string[];
+  /**
+   * Number of Bun Worker threads to spawn for job execution.
+   * When > 0, the HTTP server process processes jobs in background OS threads
+   * instead of on the main event loop - preserving HTTP throughput.
+   * Default: 0 (main-thread only; use queue:work command instead).
+   */
+  workers: number;
+  /**
+   * Absolute path or file URL to a module that imports all job classes.
+   * Each imported file must call `JobRegistry.register(MyJob)` (jobs do this automatically
+   * via the self-registration pattern). Required when `workers > 0`.
+   *
+   * @example
+   * workerBootstrap: new URL('../bootstrap/queue-worker.ts', import.meta.url).href
+   */
+  workerBootstrap?: string;
+}
+
+const defaults: QueueConfigShape = {
+  driver: "sqlite",
+  pollInterval: 500,
+  queues: ["default"],
+  workers: 0,
+};
+
+/**
+ * Create a typed queue configuration object with defaults.
+ *
+ * @example
+ * import { QueueConfig } from '@zerotal/queue';
+ * export default QueueConfig({ driver: 'sqlite', queues: ['default', 'emails'] });
+ */
+export function QueueConfig(options: Partial<QueueConfigShape> = {}): QueueConfigShape {
+  return deepMerge(defaults, options);
+}
+
+const DRIVERS = new Set<string>(["sqlite", "redis", "sync"]);
+
+/**
+ * Validate the `queue` config namespace at boot. Structural mistakes (an
+ * unknown driver, a worker pool with no bootstrap module, a poll interval that
+ * would busy-loop) are errors in any environment; a `sync` driver in production
+ * — where every dispatched job runs inline on the request — is flagged as a
+ * warning. Registered by {@link QueueProvider} via
+ * `app.registerConfigValidator("queue", …)`.
+ */
+export const validateQueueConfig: ConfigValidator = (value, { isProduction }) => {
+  const cfg = value as Partial<QueueConfigShape> | undefined;
+  const issues: ConfigIssue[] = [];
+  const driver = cfg?.driver ?? "sqlite";
+
+  if (!DRIVERS.has(driver)) {
+    issues.push({
+      level: "error",
+      message: `queue.driver "${driver}" is unknown — use "sqlite", "redis", or "sync".`,
+    });
+  }
+
+  const poll = cfg?.pollInterval;
+  if (poll !== undefined && (!Number.isFinite(poll) || poll < 1)) {
+    issues.push({
+      level: "error",
+      message: `queue.pollInterval must be a positive number of milliseconds, got ${String(poll)}.`,
+    });
+  }
+
+  const workers = cfg?.workers;
+  if (workers !== undefined && (!Number.isInteger(workers) || workers < 0)) {
+    issues.push({
+      level: "error",
+      message: `queue.workers must be a non-negative integer, got ${String(workers)}.`,
+    });
+  } else if ((workers ?? 0) > 0 && !cfg?.workerBootstrap) {
+    issues.push({
+      level: "error",
+      message:
+        "queue.workers is set but queue.workerBootstrap is not — worker threads cannot " +
+        "deserialize jobs without a bootstrap module that imports every job class.",
+    });
+  }
+
+  if (cfg?.queues !== undefined && cfg.queues.length === 0) {
+    issues.push({
+      level: "warning",
+      message:
+        "queue.queues is an empty list — a worker started with this config listens on " +
+        "nothing and every queued job waits forever.",
+    });
+  }
+
+  if (isProduction && driver === "sync") {
+    issues.push({
+      level: "warning",
+      message:
+        'queue.driver is "sync" in production — every dispatched job runs inline on the ' +
+        "request that queued it. Use the sqlite or redis driver for real background work.",
+    });
+  }
+
+  return issues;
+};
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    queue: QueueConfigShape;
+  }
+}