@zerotal/queue 1.13.1 → 1.13.3

package/CHANGELOG.md

@@ -8,6 +8,18 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.13.3] — 2026-08-31
+
+### Added
+
+- **A `zt doctor` check for jobs waiting with no worker.** The same failure as an unrun
+  schedule, one layer over: the queue fills, nothing errors, and you find out when a
+  customer asks where their email went.
+
+  Keyed on the pending depth rather than on whether any job class is registered — an app
+  with an empty queue and no worker may be perfectly fine, and a doctor that says otherwise
+  is one people scroll past.
+
 ## [1.13.1] — 2026-08-31
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/queue",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.13.1",
-    "@zerotal/orm": "1.13.1"
+    "@zerotal/core": "1.13.3",
+    "@zerotal/orm": "1.13.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/WorkerPool.ts

@@ -1,5 +1,6 @@
 import type { JobRecord } from "./drivers/QueueDriver.ts";
 import { frameworkLog } from "@zerotal/core/logger";
+import { Heartbeat } from "@zerotal/core/heartbeat";
 
 export interface WorkerPoolOptions {
   /** Number of OS threads to spawn. */
@@ -60,6 +61,9 @@ export class WorkerPool {
   /** True once {@link terminate} has run, so a dying worker is not respawned. */
   private _terminated = false;
 
+  /** Stops the liveness beat. Set while the pool is up. */
+  private _stopBeat: (() => void) | undefined;
+
   /** Spawn all worker threads and wait until every thread has bootstrapped. */
   async start(): Promise<void> {
     this._terminated = false;
@@ -72,6 +76,10 @@ export class WorkerPool {
     }
 
     await Promise.all(readyPromises);
+
+    // Beat once the pool is actually up, not when start() was called: a pool that
+    // failed to bootstrap should look like no worker, because that is what it is.
+    this._stopBeat = Heartbeat.start("queue", { detail: `${this.opts.size} thread(s)` });
   }
 
   /**
@@ -211,6 +219,8 @@ export class WorkerPool {
     // Set first: terminate() closes every worker, and the close listener must not read
     // that as a crash and respawn what we are shutting down.
     this._terminated = true;
+    this._stopBeat?.();
+    this._stopBeat = undefined;
 
     // Reject any callers still waiting for a worker — avoids hanging promises.
     for (const { resolve } of this._pending) {

package/src/provider/QueueProvider.ts

@@ -14,6 +14,8 @@ import { installQueueObservability } from "../observability.ts";
 import { installQueueAdmin } from "../admin.ts";
 import { validateQueueConfig } from "../config.ts";
 import { frameworkLog } from "@zerotal/core/logger";
+import { workerLivenessCheck } from "@zerotal/core/heartbeat";
+import type { DoctorCheck } from "@zerotal/core";
 
 declare module "@zerotal/core" {
   interface ContainerBindings {
@@ -177,4 +179,35 @@ export class QueueProvider extends ServiceProvider {
       import("../commands/QueueFlushCommand.ts").then((m) => m.QueueFlushCommand),
     );
   }
+
+  /**
+   * Report jobs waiting with no worker running.
+   *
+   * Same failure as the scheduler's, one layer over: jobs accumulate, nothing
+   * errors, and you learn about it when a customer asks where their email went.
+   *
+   * Keyed on the *pending depth* rather than on whether any job class is
+   * registered — an app with an empty queue and no worker may be perfectly fine,
+   * and a doctor that says otherwise is one people scroll past.
+   */
+  override doctorChecks(): DoctorCheck[] {
+    return [
+      workerLivenessCheck({
+        id: "queue-worker-running",
+        label: "Queue worker",
+        name: "queue",
+        hasWork: async () => {
+          try {
+            const depth = (await this.app.container.tryMake("queue")?.size()) ?? 0;
+            return { has: depth > 0, summary: `${depth} job(s) waiting` };
+          } catch {
+            // An unreadable queue is not a finding about the worker.
+            return { has: false, summary: "" };
+          }
+        },
+        staleAfter: 15 * 60,
+        command: "bun zt worker",
+      }),
+    ];
+  }
 }