@zudojs/queue 0.1.0 → 1.1.0

package/dist/worker/worker.core.js

@@ -1,48 +1,138 @@
-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 polling = false;
     let abortController = null;
-    const poll = async () => {
-        if (state !== WorkerState.RUNNING || abortController?.signal.aborted) {
-            return;
-        }
-        if (activeJobs >= concurrency) {
-            pollTimer = setTimeout(poll, pollInterval);
-            return;
-        }
-        const job = await queue.getNextJob();
-        if (!job) {
-            pollTimer = setTimeout(poll, pollInterval);
+    const onError = options?.onError ??
+        ((error) => {
+            queueMicrotask(() => {
+                console.error(`[@zudojs/queue] Worker "${id}" poll failed.`, error);
+            });
+        });
+    /**
+     * Arms the next poll. At most one timer is ever armed: a delayed poll
+     * already pending is left alone, while an immediate poll (capacity just
+     * freed up, or a job was just dispatched) supersedes it.
+     */
+    const scheduleNextPoll = (delay) => {
+        if (state !== WorkerState.RUNNING) {
             return;
         }
-        const proc = queue.getProcessor(job.name);
-        if (!proc) {
-            pollTimer = setTimeout(poll, pollInterval);
-            return;
+        if (pollTimer !== null) {
+            if (delay > 0)
+                return;
+            clearTimeout(pollTimer);
         }
-        activeJobs++;
-        stats.processed++;
+        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 = () => {
+        pollTimer = null;
+        void poll().catch((error) => {
+            onError(error);
+            scheduleNextPoll(pollInterval);
+        });
+    };
+    /**
+     * Runs one claimed job to completion and frees its concurrency slot.
+     *
+     * Deliberately not awaited by `poll`: awaiting it there serialised the
+     * worker, so `concurrency` was reported by `getStats()` and honoured by
+     * nothing.
+     */
+    const runClaimedJob = async (job) => {
         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);
+            // A slot just opened: poll again immediately, yielding to the event
+            // loop first so a saturated queue cannot starve timers.
+            scheduleNextPoll(0);
+        }
+    };
+    const poll = async () => {
+        if (polling ||
+            state !== WorkerState.RUNNING ||
+            abortController?.signal.aborted) {
+            return;
+        }
+        polling = true;
+        try {
+            if (activeJobs >= concurrency) {
+                scheduleNextPoll(pollInterval);
+                return;
+            }
+            const job = await queue.claimNextJob();
+            if (!job) {
+                scheduleNextPoll(pollInterval);
+                return;
+            }
+            const proc = queue.getProcessor(job.name);
+            if (!proc) {
+                // 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++;
+            void runClaimedJob(job);
+            // Capacity may remain: look for more work now, not after this job
+            // settles.
+            scheduleNextPoll(0);
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const clearPollTimer = () => {
+        if (pollTimer) {
+            clearTimeout(pollTimer);
+            pollTimer = null;
         }
     };
     return {
@@ -60,34 +150,46 @@ 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;
-            abortController?.abort();
-            while (activeJobs > 0) {
-                await new Promise((resolve) => setTimeout(resolve, 50));
+            clearPollTimer();
+            // Graceful means graceful: in-flight jobs get `drainTimeout` to
+            // finish on their own. Aborting them up front — as this once did —
+            // made `stop()` indistinguishable from `forceStop()` for any
+            // processor that honours its signal, and turned every routine
+            // shutdown into a batch of failed jobs.
+            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 }));
+                abortController?.abort();
             }
+            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,8 +1,12 @@
 {
   "name": "@zudojs/queue",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Background job and asynchronous task infrastructure with in-memory and adapter-based queue implementations.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -15,19 +19,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.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/serialization": "1.0.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",
@@ -47,8 +47,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"
   }
-}
+}