@zudojs/queue 0.1.0 → 1.0.0

package/dist/worker/worker.core.js

@@ -1,48 +1,105 @@
-import { WorkerState } from "../jobTypes/jobTypes.type.js";
+import { JobState as JobStateEnum, WorkerState, } from "../jobTypes/jobTypes.type.js";
 import { WorkerLifecycleError } from "@zudojs/errors";
+/** How long `stop()` waits for in-flight jobs before forcing a stop. */
+const DEFAULT_DRAIN_TIMEOUT_MS = 30_000;
 /**
  * Creates a new Worker.
+ *
+ * The worker claims each job before running it, so a job is never picked
+ * up twice — by this worker on its next poll, or by another worker on the
+ * same queue.
  */
 export function createWorker(id, queue, options) {
     let state = WorkerState.CREATED;
-    let stats = { processed: 0, succeeded: 0, failed: 0, concurrency: 0 };
-    const concurrency = options?.concurrency ?? 1;
+    const stats = { processed: 0, succeeded: 0, failed: 0 };
+    const concurrency = Math.max(1, options?.concurrency ?? 1);
     const pollInterval = options?.pollInterval ?? 100;
+    const drainTimeout = options?.drainTimeout ?? DEFAULT_DRAIN_TIMEOUT_MS;
     let pollTimer = null;
     let activeJobs = 0;
     let abortController = null;
+    const onError = options?.onError ??
+        ((error) => {
+            queueMicrotask(() => {
+                console.error(`[@zudojs/queue] Worker "${id}" poll failed.`, error);
+            });
+        });
+    const scheduleNextPoll = (delay) => {
+        if (state !== WorkerState.RUNNING) {
+            return;
+        }
+        pollTimer = setTimeout(runPoll, delay);
+        pollTimer.unref?.();
+    };
+    /**
+     * Wraps `poll` so a rejection can never escape as an unhandled promise
+     * rejection — which, under a runtime configured to treat those as
+     * fatal, would take down the whole application.
+     */
+    const runPoll = () => {
+        void poll().catch((error) => {
+            onError(error);
+            scheduleNextPoll(pollInterval);
+        });
+    };
     const poll = async () => {
         if (state !== WorkerState.RUNNING || abortController?.signal.aborted) {
             return;
         }
         if (activeJobs >= concurrency) {
-            pollTimer = setTimeout(poll, pollInterval);
+            scheduleNextPoll(pollInterval);
             return;
         }
-        const job = await queue.getNextJob();
+        const job = await queue.claimNextJob();
         if (!job) {
-            pollTimer = setTimeout(poll, pollInterval);
+            scheduleNextPoll(pollInterval);
             return;
         }
         const proc = queue.getProcessor(job.name);
         if (!proc) {
-            pollTimer = setTimeout(poll, pollInterval);
+            // Claimed but unrunnable: release it rather than stranding it in
+            // `active` where nothing would ever pick it up again.
+            await queue.releaseJob(job.id);
+            scheduleNextPoll(pollInterval);
             return;
         }
         activeJobs++;
         stats.processed++;
         try {
-            await proc(job, {
-                signal: abortController?.signal ?? new AbortController().signal,
+            // Dispatch through the queue rather than invoking the processor
+            // directly. The queue owns job state, retry, dead-lettering and
+            // middleware; calling the processor here left every job the worker
+            // ran stuck in `active` forever.
+            await queue.runJob(job, {
+                ...(options?.middleware ? { middleware: options.middleware } : {}),
+                ...(abortController ? { signal: abortController.signal } : {}),
+                ...(options?.timeoutMs !== undefined
+                    ? { timeoutMs: options.timeoutMs }
+                    : {}),
             });
-            stats.succeeded++;
+            const settled = await queue.getJob(job.id);
+            if (settled?.state === JobStateEnum.COMPLETED) {
+                stats.succeeded++;
+            }
+            else {
+                stats.failed++;
+            }
         }
-        catch {
+        catch (error) {
             stats.failed++;
+            onError(error);
         }
         finally {
             activeJobs--;
-            pollTimer = setTimeout(poll, 0);
+            // Poll again immediately while there is capacity, but yield to the
+            // event loop first so a saturated queue cannot starve timers.
+            scheduleNextPoll(0);
+        }
+    };
+    const clearPollTimer = () => {
+        if (pollTimer) {
+            clearTimeout(pollTimer);
+            pollTimer = null;
         }
     };
     return {
@@ -60,34 +117,41 @@ export function createWorker(id, queue, options) {
             abortController = new AbortController();
             try {
                 state = WorkerState.RUNNING;
-                pollTimer = setTimeout(poll, 0);
+                scheduleNextPoll(0);
             }
             catch (error) {
                 state = WorkerState.FAILED;
                 throw error;
             }
         },
+        /**
+         * Stops accepting new jobs and waits for in-flight ones to finish.
+         *
+         * The wait is bounded: past `drainTimeout` the worker force-stops
+         * rather than hanging shutdown on a job that never settles.
+         */
         async stop() {
-            if (state !== WorkerState.RUNNING) {
+            if (state !== WorkerState.RUNNING && state !== WorkerState.STARTING) {
+                // Still clear any timer armed before the state moved on.
+                clearPollTimer();
                 return;
             }
             state = WorkerState.DRAINING;
+            clearPollTimer();
             abortController?.abort();
-            while (activeJobs > 0) {
-                await new Promise((resolve) => setTimeout(resolve, 50));
+            const deadline = Date.now() + Math.max(0, drainTimeout);
+            while (activeJobs > 0 && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
             }
-            if (pollTimer) {
-                clearTimeout(pollTimer);
-                pollTimer = null;
+            if (activeJobs > 0) {
+                onError(new WorkerLifecycleError(`Worker "${id}" still had ${activeJobs} job(s) in flight after ${drainTimeout}ms; forcing stop.`, { workerId: id }));
             }
+            clearPollTimer();
             state = WorkerState.STOPPED;
         },
         async forceStop() {
             abortController?.abort();
-            if (pollTimer) {
-                clearTimeout(pollTimer);
-                pollTimer = null;
-            }
+            clearPollTimer();
             state = WorkerState.STOPPED;
         },
         isRunning() {

package/dist/worker/worker.type.d.ts

@@ -9,12 +9,26 @@ export interface WorkerOptions {
     readonly concurrency?: number;
     /** Poll interval in milliseconds. */
     readonly pollInterval?: number;
-    /** Maximum number of stalled jobs before marking as failed. */
-    readonly maxStalledCount?: number;
-    /** Job timeout in milliseconds. */
+    /**
+     * Default job timeout in milliseconds, applied to jobs that do not
+     * carry their own. Stall detection is a queue-level concern; configure
+     * it with `QueueOptions.stalledAfter` and `maxStalledCount`.
+     */
     readonly timeoutMs?: number;
     /** Middleware for job processing. */
     readonly middleware?: QueueMiddleware[];
+    /**
+     * How long `stop()` waits for in-flight jobs before forcing a stop, in
+     * milliseconds. Defaults to 30000. Without a bound, one stuck job
+     * hangs shutdown forever.
+     */
+    readonly drainTimeout?: number;
+    /**
+     * Invoked for errors raised outside a job — a failing poll, a job that
+     * threw, or a drain that timed out. Defaults to reporting on the
+     * console. Poll errors are never left as unhandled rejections.
+     */
+    readonly onError?: (error: unknown) => void;
 }
 /**
  * Worker lifecycle states.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/queue",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Background job and asynchronous task infrastructure with in-memory and adapter-based queue implementations.",
   "license": "MIT",
   "type": "module",
@@ -15,19 +15,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/serialization": "0.1.0"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0",
+    "@zudojs/serialization": "1.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
@@ -47,8 +43,19 @@
     "worker"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/queue"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}