@zudojs/queue 0.1.0 → 1.0.0

package/dist/inMemoryQueue/inMemoryQueue.processing.js

@@ -1,31 +1,61 @@
-import { updateJobState } from "../job/job.core.js";
+import { updateJobState, incrementJobAttempt } from "../job/job.core.js";
+import { DEFAULT_JOB_OPTIONS } from "../jobOptions/jobOptions.core.js";
 import { JobState as JobStateEnum } from "../jobTypes/jobTypes.type.js";
 import { createJobContext } from "../jobContext/jobContext.core.js";
 import { createMiddlewareChain, createTimeoutMiddleware, } from "../middleware/middleware.core.js";
-import { calculateRetryDelay, shouldRetry, } from "../retryPolicy/retryPolicy.core.js";
+import { calculateRetryDelay, resolveBackoff, shouldRetry, } from "../retryPolicy/retryPolicy.core.js";
 import { moveToDeadLetter } from "../deadLetter/deadLetter.core.js";
 import { JobMaxAttemptsError } from "@zudojs/errors";
+/**
+ * Narrows a processor's return value to a `JobResult`.
+ *
+ * A processor may return a `JobResult`, a plain value, or nothing.
+ * Testing `"success" in result` without this guard throws a `TypeError`
+ * for a primitive return, which surfaced as the job failing and being
+ * dead-lettered.
+ */
+function isJobResult(value) {
+    return typeof value === "object" && value !== null && "success" in value;
+}
 /**
  * Process a single job with middleware, retry, and failure handling.
+ *
+ * The job is expected to already be claimed (`active`); this records the
+ * start time, runs the middleware chain, and routes the outcome to
+ * completion, retry, or the dead letter store.
  */
-export async function processJob(job, processor, middleware, jobs, options, emitter, deadLetterStore, counters) {
+export async function processJob(job, processor, options, deps) {
+    const { jobs, emitter, counters } = deps;
     const updatedJob = updateJobState(job, JobStateEnum.ACTIVE, {
         startedAt: new Date().toISOString(),
     });
     jobs.set(updatedJob.id, updatedJob);
     emitter.emit("job:started", { job: updatedJob });
-    const abortController = new AbortController();
+    const abortController = options.abortController ?? new AbortController();
     const context = createJobContext(updatedJob, abortController.signal, {
-        onProgress: async () => {
-            const progressJob = updateJobState(updatedJob, JobStateEnum.ACTIVE);
-            jobs.set(updatedJob.id, progressJob);
+        ...(deps.logger ? { logger: deps.logger } : {}),
+        onProgress: async (progress) => {
+            const current = jobs.get(updatedJob.id);
+            if (current === undefined) {
+                return;
+            }
+            emitter.emit("job:progress", {
+                job: current,
+                progress: progress.percent,
+            });
         },
     });
-    const timeoutMs = options.timeoutMs ?? 30_000;
-    const timeoutMiddleware = createTimeoutMiddleware(timeoutMs);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_JOB_OPTIONS.timeout ?? 30_000;
+    const timeoutMiddleware = createTimeoutMiddleware(timeoutMs, () => {
+        // Let a cooperative processor observe the timeout and stop working
+        // instead of running on with its result discarded.
+        if (!abortController.signal.aborted) {
+            abortController.abort(new Error(`Job "${updatedJob.id}" timed out after ${timeoutMs}ms.`));
+        }
+    });
     const middlewareChain = createMiddlewareChain([
         timeoutMiddleware,
-        ...middleware,
+        ...deps.middleware,
     ]);
     try {
         const result = await middlewareChain({
@@ -35,16 +65,8 @@ export async function processJob(job, processor, middleware, jobs, options, emit
                 return processor(updatedJob, context);
             },
         });
-        if (result && "success" in result && result.success) {
-            const completedJob = updateJobState(updatedJob, JobStateEnum.COMPLETED, {
-                completedAt: new Date().toISOString(),
-            });
-            jobs.set(updatedJob.id, completedJob);
-            counters.succeededCount++;
-            emitter.emit("job:completed", { job: completedJob, result: result.data });
-        }
-        else if (result && "success" in result && !result.success) {
-            await handleJobFailure(updatedJob, result.error ?? "Job failed", processor, abortController, jobs, emitter, deadLetterStore, counters);
+        if (isJobResult(result) && !result.success) {
+            await handleJobFailure(updatedJob, result.error ?? "Job failed", deps);
         }
         else {
             const completedJob = updateJobState(updatedJob, JobStateEnum.COMPLETED, {
@@ -52,12 +74,18 @@ export async function processJob(job, processor, middleware, jobs, options, emit
             });
             jobs.set(updatedJob.id, completedJob);
             counters.succeededCount++;
-            emitter.emit("job:completed", { job: completedJob, result: undefined });
+            emitter.emit("job:completed", {
+                job: completedJob,
+                // A processor may return a `JobResult`, a plain value, or
+                // nothing. Only the first carries its payload under `data`.
+                result: isJobResult(result) ? result.data : result,
+            });
+            deps.onSettled?.(completedJob);
         }
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        await handleJobFailure(updatedJob, errorMessage, processor, abortController, jobs, emitter, deadLetterStore, counters);
+        await handleJobFailure(updatedJob, errorMessage, deps);
     }
     finally {
         counters.processedCount++;
@@ -65,15 +93,18 @@ export async function processJob(job, processor, middleware, jobs, options, emit
 }
 /**
  * Handle job failure with retry logic.
+ *
+ * A failure that will be retried is reported as `job:retrying` and counted
+ * separately; only a terminal failure increments `failedCount`, so the
+ * counters describe outcomes rather than attempts.
  */
-export async function handleJobFailure(job, errorMessage, processor, abortController, jobs, emitter, deadLetterStore, counters) {
-    const { updateJobState: update, incrementJobAttempt } = await import("../job/job.core.js");
-    const failedJob = update(job, JobStateEnum.FAILED, {
+export async function handleJobFailure(job, errorMessage, deps) {
+    const { jobs, emitter, counters, deadLetterStore } = deps;
+    const failedJob = updateJobState(job, JobStateEnum.FAILED, {
         error: errorMessage,
         failedAt: new Date().toISOString(),
     });
     jobs.set(job.id, failedJob);
-    counters.failedCount++;
     emitter.emit("job:failed", {
         job: failedJob,
         error: new Error(errorMessage),
@@ -81,32 +112,48 @@ export async function handleJobFailure(job, errorMessage, processor, abortContro
     const incrementedJob = incrementJobAttempt(failedJob);
     jobs.set(job.id, incrementedJob);
     if (shouldRetry(incrementedJob.attempt, incrementedJob.maxAttempts)) {
-        const retryingJob = update(incrementedJob, JobStateEnum.RETRYING);
+        const retryingJob = updateJobState(incrementedJob, JobStateEnum.RETRYING);
         jobs.set(job.id, retryingJob);
+        counters.retriedCount++;
         emitter.emit("job:retrying", {
             job: retryingJob,
             attempt: incrementedJob.attempt,
         });
-        const backoff = incrementedJob.backoff;
+        const backoff = resolveBackoff(incrementedJob.backoff);
         const delay = calculateRetryDelay(incrementedJob.attempt, backoff);
-        setTimeout(() => {
+        const timer = setTimeout(() => {
+            if (deps.isDisposed()) {
+                return;
+            }
             const currentJob = jobs.get(job.id);
             if (currentJob && currentJob.state === JobStateEnum.RETRYING) {
-                const waitingJob = update(currentJob, JobStateEnum.WAITING, {
+                const waitingJob = updateJobState(currentJob, JobStateEnum.WAITING, {
                     error: undefined,
                     failedAt: undefined,
                 });
                 jobs.set(job.id, waitingJob);
             }
         }, delay);
+        // `unref` keeps a pending retry from holding the process open; the
+        // queue clears the timer explicitly on close.
+        timer.unref?.();
+        deps.registerRetryTimer(job.id, timer);
+        return;
     }
-    else {
-        const maxAttemptsError = new JobMaxAttemptsError(job.id, incrementedJob.attempt, incrementedJob.maxAttempts, { queueName: job.queueName });
-        await moveToDeadLetter(deadLetterStore, incrementedJob, maxAttemptsError);
-        const deadLetterJob = update(incrementedJob, JobStateEnum.DEAD_LETTER, {
-            error: maxAttemptsError.message,
+    counters.failedCount++;
+    counters.deadLetteredCount++;
+    const maxAttemptsError = new JobMaxAttemptsError(job.id, incrementedJob.attempt, incrementedJob.maxAttempts, { queueName: job.queueName });
+    try {
+        await moveToDeadLetter(deadLetterStore, incrementedJob, maxAttemptsError, {
+            reason: errorMessage,
         });
-        jobs.set(job.id, deadLetterJob);
     }
+    catch {
+        // A dead letter store that rejects must not mask the original
+        // failure or strand the job in `failed`.
+    }
+    const deadLetterJob = updateJobState(incrementedJob, JobStateEnum.DEAD_LETTER, { error: maxAttemptsError.message });
+    jobs.set(job.id, deadLetterJob);
+    deps.onSettled?.(deadLetterJob);
 }
 //# sourceMappingURL=inMemoryQueue.processing.js.map

package/dist/inMemoryQueue/inMemoryQueue.scheduling.d.ts

@@ -1,10 +1,26 @@
 import type { Job } from "../job/job.type.js";
+import type { JobId } from "../jobTypes/jobTypes.type.js";
 /**
  * Schedule a job for future execution.
+ *
+ * The timer is registered so the queue can clear it on close, and
+ * unreferenced so a scheduled job never by itself keeps the process
+ * alive.
  */
-export declare function scheduleJob<TData>(job: Job<TData>, scheduledTimers: Map<string, ReturnType<typeof setTimeout>>, jobs: Map<string, Job<TData>>): void;
+export declare function scheduleJob<TData>(job: Job<TData>, scheduledTimers: Map<JobId, ReturnType<typeof setTimeout>>, jobs: Map<string, Job<TData>>): void;
+/**
+ * Promotes scheduled jobs whose time has arrived.
+ *
+ * This backstops the per-job timers: a timer that was never armed, or
+ * that was delayed by a blocked event loop, still gets promoted on the
+ * next poll.
+ */
+export declare function promoteDueScheduledJobs<TData>(jobs: Map<string, Job<TData>>, scheduledTimers?: Map<JobId, ReturnType<typeof setTimeout>>): void;
 /**
  * Promote scheduled jobs that are ready to run.
+ *
+ * @deprecated Use {@link promoteDueScheduledJobs}, which also clears the
+ * timer belonging to a promoted job.
  */
 export declare function scheduleDelayedJobs<TData>(jobs: Map<string, Job<TData>>): void;
 //# sourceMappingURL=inMemoryQueue.scheduling.d.ts.map

package/dist/inMemoryQueue/inMemoryQueue.scheduling.js

@@ -1,38 +1,70 @@
 import { updateJobState } from "../job/job.core.js";
 import { JobState as JobStateEnum } from "../jobTypes/jobTypes.type.js";
+import { MAX_TIMER_DELAY } from "../retryPolicy/retryPolicy.core.js";
 /**
  * Schedule a job for future execution.
+ *
+ * The timer is registered so the queue can clear it on close, and
+ * unreferenced so a scheduled job never by itself keeps the process
+ * alive.
  */
 export function scheduleJob(job, scheduledTimers, jobs) {
     if (!job.scheduledAt) {
         return;
     }
     const scheduledTime = new Date(job.scheduledAt).getTime();
-    const now = Date.now();
-    const delay = Math.max(0, scheduledTime - now);
+    if (Number.isNaN(scheduledTime)) {
+        // An unparseable schedule would otherwise fire immediately via NaN
+        // coercion; promote the job instead of guessing at a delay.
+        jobs.set(job.id, updateJobState(job, JobStateEnum.WAITING));
+        return;
+    }
+    const delay = Math.min(Math.max(0, scheduledTime - Date.now()), MAX_TIMER_DELAY);
+    const existing = scheduledTimers.get(job.id);
+    if (existing) {
+        clearTimeout(existing);
+    }
     const timer = setTimeout(() => {
         scheduledTimers.delete(job.id);
         const currentJob = jobs.get(job.id);
         if (currentJob && currentJob.state === JobStateEnum.SCHEDULED) {
-            const waitingJob = updateJobState(currentJob, JobStateEnum.WAITING);
-            jobs.set(job.id, waitingJob);
+            jobs.set(job.id, updateJobState(currentJob, JobStateEnum.WAITING));
         }
     }, delay);
+    timer.unref?.();
     scheduledTimers.set(job.id, timer);
 }
 /**
- * Promote scheduled jobs that are ready to run.
+ * Promotes scheduled jobs whose time has arrived.
+ *
+ * This backstops the per-job timers: a timer that was never armed, or
+ * that was delayed by a blocked event loop, still gets promoted on the
+ * next poll.
  */
-export function scheduleDelayedJobs(jobs) {
+export function promoteDueScheduledJobs(jobs, scheduledTimers) {
     const now = Date.now();
     for (const job of jobs.values()) {
-        if (job.state === JobStateEnum.SCHEDULED && job.scheduledAt) {
-            const scheduledTime = new Date(job.scheduledAt).getTime();
-            if (scheduledTime <= now) {
-                const waitingJob = updateJobState(job, JobStateEnum.WAITING);
-                jobs.set(job.id, waitingJob);
+        if (job.state !== JobStateEnum.SCHEDULED || !job.scheduledAt) {
+            continue;
+        }
+        const scheduledTime = new Date(job.scheduledAt).getTime();
+        if (Number.isNaN(scheduledTime) || scheduledTime <= now) {
+            jobs.set(job.id, updateJobState(job, JobStateEnum.WAITING));
+            const timer = scheduledTimers?.get(job.id);
+            if (timer) {
+                clearTimeout(timer);
+                scheduledTimers?.delete(job.id);
             }
         }
     }
 }
+/**
+ * Promote scheduled jobs that are ready to run.
+ *
+ * @deprecated Use {@link promoteDueScheduledJobs}, which also clears the
+ * timer belonging to a promoted job.
+ */
+export function scheduleDelayedJobs(jobs) {
+    promoteDueScheduledJobs(jobs);
+}
 //# sourceMappingURL=inMemoryQueue.scheduling.js.map

package/dist/index.d.ts

@@ -16,7 +16,6 @@ export * from "./processor/index.js";
 export * from "./queue/index.js";
 export * from "./queueManager/index.js";
 export * from "./queueRegistry/index.js";
-export * from "./queueEvents/index.js";
 export * from "./queueEmitter/index.js";
 export * from "./retryPolicy/index.js";
 export * from "./serializer/index.js";

package/dist/index.js

@@ -25,8 +25,6 @@ export * from "./queue/index.js";
 export * from "./queueManager/index.js";
 // Queue registry
 export * from "./queueRegistry/index.js";
-// Queue events
-export * from "./queueEvents/index.js";
 // Queue emitter
 export * from "./queueEmitter/index.js";
 // Retry policy

package/dist/job/job.core.js

@@ -1,39 +1,47 @@
-import { randomBytes } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { createJobId, JobState as JobStateEnum, } from "../jobTypes/jobTypes.type.js";
+import { mergeJobOptions } from "../jobOptions/jobOptions.core.js";
 /**
  * Creates a new job instance.
  */
 export function createJob(input, id) {
     const now = new Date().toISOString();
-    const options = input.options;
-    const jobId = id ?? createJobId(`job_${Date.now()}_${randomBytes(6).toString("hex")}`);
+    // Defaults live in `mergeJobOptions`; duplicating them here is how
+    // `DEFAULT_JOB_OPTIONS.timeout` came to be exported, documented, and
+    // ignored by every job this factory produced.
+    const options = mergeJobOptions(input.options);
+    const jobId = id ?? createJobId(`job_${Date.now()}_${randomUUID().replace(/-/g, "")}`);
     return {
         id: jobId,
         name: input.name,
         queueName: input.queueName,
         data: input.data,
-        state: options?.delay || options?.scheduledAt
+        state: options.delay || options.scheduledAt
             ? JobStateEnum.SCHEDULED
             : JobStateEnum.WAITING,
         attempt: 0,
-        maxAttempts: options?.attempts ?? 1,
-        priority: options?.priority ?? 50,
+        maxAttempts: options.attempts,
+        priority: options.priority ?? 50,
         createdAt: now,
         updatedAt: now,
-        scheduledAt: options?.scheduledAt
+        scheduledAt: options.scheduledAt
             ? options.scheduledAt.toISOString()
-            : options?.delay
+            : options.delay
                 ? new Date(Date.now() + options.delay).toISOString()
                 : undefined,
-        timeoutMs: options?.timeout,
-        deduplicationKey: options?.deduplicationKey,
-        metadata: options?.metadata,
-        backoff: options?.backoff
+        // Deliberately the caller's own value, not the merged default: a job
+        // that carries no timeout is what lets `WorkerOptions.timeoutMs` and the
+        // queue-wide fallback apply.
+        timeoutMs: input.options?.timeout,
+        deduplicationKey: options.deduplicationKey,
+        metadata: options.metadata,
+        backoff: options.backoff
             ? {
                 type: options.backoff.type,
                 delay: options.backoff.delay,
                 maxDelay: options.backoff.maxDelay,
                 multiplier: options.backoff.multiplier,
+                jitter: options.backoff.jitter,
             }
             : undefined,
     };

package/dist/job/job.type.d.ts

@@ -1,5 +1,5 @@
 import type { Timestamp } from "@zudojs/constants";
-import type { JobId, JobName, JobState, JobPriority, BackoffType } from "../jobTypes/jobTypes.type.js";
+import type { JobId, JobName, JobState, JobPriority, BackoffStrategy } from "../jobTypes/jobTypes.type.js";
 import type { JobOptions } from "../jobOptions/jobOptions.type.js";
 /**
  * A unit of work in the queue system.
@@ -43,10 +43,11 @@ export interface Job<TData = unknown> {
     readonly metadata?: Record<string, unknown>;
     /** Backoff configuration. */
     readonly backoff?: {
-        readonly type: BackoffType;
+        readonly type: BackoffStrategy;
         readonly delay: number;
         readonly maxDelay?: number;
         readonly multiplier?: number;
+        readonly jitter?: "none" | "full" | "equal";
     };
 }
 /**

package/dist/jobOptions/jobOptions.type.d.ts

@@ -1,16 +1,25 @@
-import type { BackoffType } from "../jobTypes/jobTypes.type.js";
+import type { BackoffStrategy } from "../jobTypes/jobTypes.type.js";
 /**
  * Backoff configuration for retry attempts.
  */
 export interface BackoffOptions {
-    /** Backoff strategy type. */
-    readonly type: BackoffType;
+    /** Backoff strategy type. Accepts `BackoffType` or its string value. */
+    readonly type: BackoffStrategy;
     /** Initial delay in milliseconds. */
     readonly delay: number;
     /** Maximum delay in milliseconds (for exponential). */
     readonly maxDelay?: number;
     /** Multiplier for exponential backoff. */
     readonly multiplier?: number;
+    /**
+     * Randomisation applied to the computed delay.
+     *
+     * `"full"` spreads retries uniformly over `[0, delay]`, `"equal"` keeps
+     * half the delay fixed, `"none"` (the default) leaves the delay
+     * deterministic. Jitter prevents jobs that failed together from
+     * retrying together.
+     */
+    readonly jitter?: "none" | "full" | "equal";
 }
 /**
  * Options for adding a job to the queue.

package/dist/jobTypes/index.d.ts

@@ -5,5 +5,5 @@
  * as well as lifecycle state enums and priority constants.
  */
 export { JobState, JobPriorityLevels, BackoffType, WorkerState, createJobId, createQueueName, createJobName, isJobId, isQueueName, isJobName, } from "./jobTypes.type.js";
-export type { JobId, QueueName, JobName, JobPriority, } from "./jobTypes.type.js";
+export type { JobId, QueueName, JobName, JobPriority, BackoffStrategy, } from "./jobTypes.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/jobTypes/jobTypes.type.d.ts

@@ -51,6 +51,15 @@ export declare enum BackoffType {
     FIXED = "fixed",
     EXPONENTIAL = "exponential"
 }
+/**
+ * A backoff strategy as either the enum member or its string value.
+ *
+ * Job options routinely arrive from JSON — a config file, a broker payload,
+ * an HTTP body — where `"fixed"` is the only spelling available. The runtime
+ * has always compared against the string values, but a bare `BackoffType`
+ * annotation rejected them, so correct calls failed to typecheck.
+ */
+export type BackoffStrategy = `${BackoffType}`;
 /**
  * Worker lifecycle states.
  */

package/dist/middleware/middleware.core.d.ts

@@ -1,6 +1,10 @@
 import type { QueueMiddleware } from "./middleware.type.js";
 /**
  * Creates a middleware chain from an array of middleware.
+ *
+ * Each middleware may call `next()` exactly once. A second call throws
+ * rather than silently re-entering the chain and running the processor
+ * twice.
  */
 export declare function createMiddlewareChain(middleware: QueueMiddleware[]): QueueMiddleware;
 /**
@@ -11,6 +15,11 @@ export declare function createLoggingMiddleware(logger?: {
 }): QueueMiddleware;
 /**
  * Timeout middleware for queue processing.
+ *
+ * The timer is always cleared once the race settles, so a completed job
+ * never leaves an armed timer holding the event loop open. When the
+ * timeout wins, `onTimeout` is invoked so the caller can abort the job's
+ * `AbortSignal` and let a cooperative processor stop its own work.
  */
-export declare function createTimeoutMiddleware(timeoutMs: number): QueueMiddleware;
+export declare function createTimeoutMiddleware(timeoutMs: number, onTimeout?: () => void): QueueMiddleware;
 //# sourceMappingURL=middleware.core.d.ts.map

package/dist/middleware/middleware.core.js

@@ -1,22 +1,30 @@
 import { JobTimeoutError } from "@zudojs/errors";
+import { MAX_TIMER_DELAY } from "../retryPolicy/retryPolicy.core.js";
 /**
  * Creates a middleware chain from an array of middleware.
+ *
+ * Each middleware may call `next()` exactly once. A second call throws
+ * rather than silently re-entering the chain and running the processor
+ * twice.
  */
 export function createMiddlewareChain(middleware) {
     return async (ctx) => {
         let index = -1;
-        const dispatch = async () => {
-            index++;
-            if (index < middleware.length) {
-                const current = middleware[index];
+        const dispatch = async (position) => {
+            if (position <= index) {
+                throw new Error(`Queue middleware at index ${position} called next() more than once.`);
+            }
+            index = position;
+            if (position < middleware.length) {
+                const current = middleware[position];
                 return current({
                     ...ctx,
-                    next: dispatch,
+                    next: () => dispatch(position + 1),
                 });
             }
             return ctx.next();
         };
-        return dispatch();
+        return dispatch(0);
     };
 }
 /**
@@ -58,19 +66,34 @@ export function createLoggingMiddleware(logger) {
 }
 /**
  * Timeout middleware for queue processing.
+ *
+ * The timer is always cleared once the race settles, so a completed job
+ * never leaves an armed timer holding the event loop open. When the
+ * timeout wins, `onTimeout` is invoked so the caller can abort the job's
+ * `AbortSignal` and let a cooperative processor stop its own work.
  */
-export function createTimeoutMiddleware(timeoutMs) {
+export function createTimeoutMiddleware(timeoutMs, onTimeout) {
+    const delay = Math.min(Math.max(0, timeoutMs), MAX_TIMER_DELAY);
     return async (ctx) => {
-        return Promise.race([
-            ctx.next(),
-            new Promise((_, reject) => {
-                setTimeout(() => {
-                    reject(new JobTimeoutError(ctx.job.id, timeoutMs, {
-                        queueName: ctx.job.queueName,
-                    }));
-                }, timeoutMs);
-            }),
-        ]);
+        let timer;
+        try {
+            return await Promise.race([
+                ctx.next(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        onTimeout?.();
+                        reject(new JobTimeoutError(ctx.job.id, timeoutMs, {
+                            queueName: ctx.job.queueName,
+                        }));
+                    }, delay);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
     };
 }
 //# sourceMappingURL=middleware.core.js.map

package/dist/processor/index.d.ts

@@ -5,6 +5,6 @@
  * managing job processors.
  */
 export { createProcessorRegistry } from "./processor.core.js";
-export { isProcessor } from "./processor.type.js";
+export { assertProcessor, isProcessor } from "./processor.type.js";
 export type { Processor, ProcessorInfo, ProcessorRegistry, } from "./processor.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/processor/index.js

@@ -5,5 +5,5 @@
  * managing job processors.
  */
 export { createProcessorRegistry } from "./processor.core.js";
-export { isProcessor } from "./processor.type.js";
+export { assertProcessor, isProcessor } from "./processor.type.js";
 //# sourceMappingURL=index.js.map

package/dist/processor/processor.core.js

@@ -1,4 +1,5 @@
 import { JobError } from "@zudojs/errors";
+import { assertProcessor } from "./processor.type.js";
 /**
  * Creates a new ProcessorRegistry.
  */
@@ -7,6 +8,7 @@ export function createProcessorRegistry() {
     const infoMap = new Map();
     return {
         register(jobName, processor, options) {
+            assertProcessor(processor, jobName);
             if (processors.has(jobName)) {
                 throw new JobError(`Processor already registered for job "${jobName}".`, { jobId: jobName });
             }

package/dist/processor/processor.type.d.ts

@@ -3,8 +3,14 @@ import type { JobContext } from "../jobContext/jobContext.type.js";
 import type { JobResult } from "../jobResult/jobResult.type.js";
 /**
  * A function that processes a job.
+ *
+ * A processor may return a {@link JobResult} to report success or failure
+ * explicitly, a plain value to be carried on `job:completed`, or nothing at
+ * all. The queue narrows the three cases at runtime; the previous signature
+ * admitted only the first two, so a processor returning its own value — the
+ * common case — failed to typecheck against a queue that handled it happily.
  */
-export type Processor<TData = unknown, TResult = unknown> = (job: Job<TData>, context: JobContext<TData>) => Promise<JobResult<TResult>> | Promise<void>;
+export type Processor<TData = unknown, TResult = unknown> = (job: Job<TData>, context: JobContext<TData>) => Promise<JobResult<TResult> | TResult | void>;
 /**
  * Metadata about a registered processor.
  */
@@ -39,4 +45,15 @@ export interface ProcessorRegistry {
  * Checks if a value is a valid Processor.
  */
 export declare function isProcessor(value: unknown): value is Processor;
+/**
+ * Assert that a value can actually process a job.
+ *
+ * Registering a non-function succeeded silently and failed much later, deep
+ * inside job processing, as a job that "failed" and was dead-lettered.
+ *
+ * @param value - The candidate processor.
+ * @param jobName - The job name it is being registered for.
+ * @throws {TypeError} when the value is not callable.
+ */
+export declare function assertProcessor(value: unknown, jobName: string): asserts value is Processor;
 //# sourceMappingURL=processor.type.d.ts.map

package/dist/processor/processor.type.js

@@ -4,4 +4,19 @@
 export function isProcessor(value) {
     return typeof value === "function";
 }
+/**
+ * Assert that a value can actually process a job.
+ *
+ * Registering a non-function succeeded silently and failed much later, deep
+ * inside job processing, as a job that "failed" and was dead-lettered.
+ *
+ * @param value - The candidate processor.
+ * @param jobName - The job name it is being registered for.
+ * @throws {TypeError} when the value is not callable.
+ */
+export function assertProcessor(value, jobName) {
+    if (!isProcessor(value)) {
+        throw new TypeError(`Processor for job "${jobName}" must be a function; received ${value === null ? "null" : typeof value}.`);
+    }
+}
 //# sourceMappingURL=processor.type.js.map