@zudojs/queue 1.5.1 → 1.6.0

package/dist/contextCarrier/contextCarrier.core.d.ts

@@ -33,4 +33,3 @@ export declare function captureContext(carriers: readonly QueueContextCarrier[]
  * @returns Whatever `fn` resolves to.
  */
 export declare function runWithContext<T>(carriers: readonly QueueContextCarrier[] | undefined, job: Job<unknown>, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=contextCarrier.core.d.ts.map

package/dist/contextCarrier/contextCarrier.core.js

@@ -77,4 +77,3 @@ export function runWithContext(carriers, job, fn) {
     }
     return run();
 }
-//# sourceMappingURL=contextCarrier.core.js.map

package/dist/contextCarrier/contextCarrier.type.d.ts

@@ -38,4 +38,3 @@ export interface QueueContextCarrier<TValue = unknown> {
      */
     restore<T>(value: TValue, run: () => Promise<T>): Promise<T>;
 }
-//# sourceMappingURL=contextCarrier.type.d.ts.map

package/dist/contextCarrier/contextCarrier.type.js

@@ -4,4 +4,3 @@
  * @module contextCarrier/contextCarrier.type
  */
 export {};
-//# sourceMappingURL=contextCarrier.type.js.map

package/dist/contextCarrier/index.d.ts

@@ -8,4 +8,3 @@
  */
 export type { QueueContextCarrier } from "./contextCarrier.type.js";
 export { CONTEXT_METADATA_KEY, captureContext, runWithContext, } from "./contextCarrier.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/contextCarrier/index.js

@@ -7,4 +7,3 @@
  * the request that enqueued it.
  */
 export { CONTEXT_METADATA_KEY, captureContext, runWithContext, } from "./contextCarrier.core.js";
-//# sourceMappingURL=index.js.map

package/dist/deadLetter/deadLetter.core.d.ts

@@ -35,4 +35,3 @@ export declare function createInMemoryDeadLetterStore<TData = unknown>(options?:
 export declare function moveToDeadLetter<TData>(store: DeadLetterStore<TData>, job: Job<TData>, error: Error, options?: {
     reason?: string;
 }): Promise<void>;
-//# sourceMappingURL=deadLetter.core.d.ts.map

package/dist/deadLetter/deadLetter.core.js

@@ -64,4 +64,3 @@ export async function moveToDeadLetter(store, job, error, options) {
     };
     await store.add(deadLetterJob);
 }
-//# sourceMappingURL=deadLetter.core.js.map

package/dist/deadLetter/deadLetter.type.d.ts

@@ -30,4 +30,3 @@ export interface DeadLetterStore<TData = unknown> {
     /** Clear all dead letter jobs. */
     clear(): Promise<void>;
 }
-//# sourceMappingURL=deadLetter.type.d.ts.map

package/dist/deadLetter/deadLetter.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=deadLetter.type.js.map

package/dist/deadLetter/index.d.ts

@@ -7,4 +7,3 @@
 export { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
 export type { InMemoryDeadLetterStoreOptions } from "./deadLetter.core.js";
 export type { DeadLetterJob, DeadLetterStore } from "./deadLetter.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/deadLetter/index.js

@@ -5,4 +5,3 @@
  * exceeded their retry attempts.
  */
 export { DEFAULT_DEAD_LETTER_JOBS, createInMemoryDeadLetterStore, moveToDeadLetter, } from "./deadLetter.core.js";
-//# sourceMappingURL=index.js.map

package/dist/inMemoryQueue/inMemoryQueue.core.d.ts

@@ -177,4 +177,3 @@ export declare class InMemoryQueue<TData = unknown> implements Queue<TData> {
      */
     private pruneSettled;
 }
-//# sourceMappingURL=inMemoryQueue.core.d.ts.map

package/dist/inMemoryQueue/inMemoryQueue.core.js

@@ -489,6 +489,7 @@ export class InMemoryQueue {
                 onJobReady: () => this.jobReady(),
                 isDisposed: () => this.disposed,
                 ...(this.options.logger ? { logger: this.options.logger } : {}),
+                ...(this.options.random ? { random: this.options.random } : {}),
             });
         }
         catch (error) {
@@ -631,4 +632,3 @@ export class InMemoryQueue {
         }
     }
 }
-//# sourceMappingURL=inMemoryQueue.core.js.map

package/dist/inMemoryQueue/inMemoryQueue.factory.d.ts

@@ -4,4 +4,3 @@ import type { QueueOptions, Queue } from "../queue/queue.type.js";
  * Creates an InMemoryQueue.
  */
 export declare function createInMemoryQueue<TData>(name: QueueName, options?: QueueOptions): Queue<TData>;
-//# sourceMappingURL=inMemoryQueue.factory.d.ts.map

package/dist/inMemoryQueue/inMemoryQueue.factory.js

@@ -5,4 +5,3 @@ import { InMemoryQueue } from "./inMemoryQueue.core.js";
 export function createInMemoryQueue(name, options) {
     return new InMemoryQueue(name, options);
 }
-//# sourceMappingURL=inMemoryQueue.factory.js.map

package/dist/inMemoryQueue/inMemoryQueue.processing.d.ts

@@ -46,6 +46,21 @@ export interface ProcessJobDependencies<TData> {
      * when the queue was configured without a logger.
      */
     readonly logger?: QueueLogger;
+    /** See `QueueOptions.random`. */
+    readonly random?: () => number;
+}
+/**
+ * How an attempt failed, beyond its message.
+ */
+export interface JobFailureDetails {
+    /** The value the processor threw or the result it returned, if any. */
+    readonly error?: unknown;
+    /**
+     * The failure is permanent: dead-letter the job now rather than retry.
+     * Set when the thrown error was marked with `markUnrecoverable` or the
+     * returned `JobResult` carries `unrecoverable: true`.
+     */
+    readonly unrecoverable?: boolean;
 }
 /**
  * Process a single job with middleware, retry, and failure handling.
@@ -67,7 +82,8 @@ export declare function processJob<TData>(job: Job<TData>, processor: Processor<
  *
  * 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.
+ * counters describe outcomes rather than attempts. An unrecoverable failure
+ * skips the remaining attempts and is dead-lettered with the processor's
+ * own error.
  */
-export declare function handleJobFailure<TData>(job: Job<TData>, errorMessage: string, deps: ProcessJobDependencies<TData>): Promise<void>;
-//# sourceMappingURL=inMemoryQueue.processing.d.ts.map
+export declare function handleJobFailure<TData>(job: Job<TData>, errorMessage: string, deps: ProcessJobDependencies<TData>, details?: JobFailureDetails): Promise<void>;

package/dist/inMemoryQueue/inMemoryQueue.processing.js

@@ -7,6 +7,7 @@ import { calculateRetryDelay, resolveBackoff, shouldRetry, } from "../retryPolic
 import { moveToDeadLetter } from "../deadLetter/deadLetter.core.js";
 import { runWithContext } from "../contextCarrier/contextCarrier.core.js";
 import { DEFAULT_TIMEOUT_GRACE_MS, settleWithin, } from "./inMemoryQueue.settle.js";
+import { isUnrecoverableJobError } from "../jobFailure/jobFailure.unrecoverable.js";
 import { JobMaxAttemptsError } from "@zudojs/errors";
 /**
  * Narrows a processor's return value to a `JobResult`.
@@ -77,7 +78,9 @@ export async function processJob(job, processor, options, deps) {
             },
         }));
         if (isJobResult(result) && !result.success) {
-            await handleJobFailure(updatedJob, result.error ?? "Job failed", deps);
+            await handleJobFailure(updatedJob, result.error ?? "Job failed", deps, {
+                unrecoverable: result.unrecoverable === true,
+            });
         }
         else {
             const completedJob = updateJobState(updatedJob, JobStateEnum.COMPLETED, {
@@ -100,7 +103,10 @@ export async function processJob(job, processor, options, deps) {
         if (abortController.signal.aborted && !timedOut) {
             emitter.emit("job:cancelled", { job: updatedJob });
         }
-        await handleJobFailure(updatedJob, errorMessage, deps);
+        await handleJobFailure(updatedJob, errorMessage, deps, {
+            error,
+            unrecoverable: isUnrecoverableJobError(error),
+        });
     }
     finally {
         counters.processedCount++;
@@ -111,22 +117,23 @@ export async function processJob(job, processor, options, deps) {
  *
  * 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.
+ * counters describe outcomes rather than attempts. An unrecoverable failure
+ * skips the remaining attempts and is dead-lettered with the processor's
+ * own error.
  */
-export async function handleJobFailure(job, errorMessage, deps) {
+export async function handleJobFailure(job, errorMessage, deps, details = {}) {
     const { jobs, emitter, counters, deadLetterStore } = deps;
+    const thrown = details.error instanceof Error ? details.error : new Error(errorMessage);
     const failedJob = updateJobState(job, JobStateEnum.FAILED, {
         error: errorMessage,
         failedAt: new Date().toISOString(),
     });
     jobs.set(job.id, failedJob);
-    emitter.emit("job:failed", {
-        job: failedJob,
-        error: new Error(errorMessage),
-    });
+    emitter.emit("job:failed", { job: failedJob, error: thrown });
     const incrementedJob = incrementJobAttempt(failedJob);
     jobs.set(job.id, incrementedJob);
-    if (shouldRetry(incrementedJob.attempt, incrementedJob.maxAttempts)) {
+    if (details.unrecoverable !== true &&
+        shouldRetry(incrementedJob.attempt, incrementedJob.maxAttempts)) {
         const retryingJob = updateJobState(incrementedJob, JobStateEnum.RETRYING);
         jobs.set(job.id, retryingJob);
         counters.retriedCount++;
@@ -135,7 +142,7 @@ export async function handleJobFailure(job, errorMessage, deps) {
             attempt: incrementedJob.attempt,
         });
         const backoff = resolveBackoff(incrementedJob.backoff);
-        const delay = calculateRetryDelay(incrementedJob.attempt, backoff);
+        const delay = calculateRetryDelay(incrementedJob.attempt, backoff, deps.random);
         const timer = setTimeout(() => {
             deps.deregisterRetryTimer?.(job.id);
             if (deps.isDisposed()) {
@@ -159,9 +166,11 @@ export async function handleJobFailure(job, errorMessage, deps) {
     }
     counters.failedCount++;
     counters.deadLetteredCount++;
-    const maxAttemptsError = new JobMaxAttemptsError(job.id, incrementedJob.attempt, incrementedJob.maxAttempts, { queueName: job.queueName });
+    const deadLetterError = details.unrecoverable === true
+        ? thrown
+        : describeExhaustedAttempts(incrementedJob, errorMessage);
     try {
-        await moveToDeadLetter(deadLetterStore, incrementedJob, maxAttemptsError, {
+        await moveToDeadLetter(deadLetterStore, incrementedJob, deadLetterError, {
             reason: errorMessage,
         });
     }
@@ -169,13 +178,26 @@ export async function handleJobFailure(job, errorMessage, deps) {
         // 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 });
+    const deadLetterJob = updateJobState(incrementedJob, JobStateEnum.DEAD_LETTER, { error: deadLetterError.message });
     jobs.set(job.id, deadLetterJob);
     emitter.emit("job:dead-lettered", {
         job: deadLetterJob,
-        error: maxAttemptsError,
+        error: deadLetterError,
         reason: errorMessage,
     });
     deps.onSettled?.(deadLetterJob);
 }
-//# sourceMappingURL=inMemoryQueue.processing.js.map
+/**
+ * The error recorded for a job whose attempts ran out.
+ *
+ * The message names the last failure, so a dead-letter entry says what
+ * went wrong ("... Last error: card declined") rather than only that the
+ * attempts were used up; the bare reason is still on `reason`.
+ */
+function describeExhaustedAttempts(job, lastError) {
+    const error = new JobMaxAttemptsError(job.id, job.attempt, job.maxAttempts, {
+        queueName: job.queueName,
+    });
+    error.message = `${error.message} Last error: ${lastError}`;
+    return error;
+}

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

@@ -26,4 +26,3 @@ export declare function promoteDueScheduledJobs<TData>(jobs: Map<string, Job<TDa
  * 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

@@ -72,4 +72,3 @@ export function promoteDueScheduledJobs(jobs, scheduledTimers) {
 export function scheduleDelayedJobs(jobs) {
     promoteDueScheduledJobs(jobs);
 }
-//# sourceMappingURL=inMemoryQueue.scheduling.js.map

package/dist/inMemoryQueue/inMemoryQueue.settle.d.ts

@@ -21,4 +21,3 @@ export declare const DEFAULT_TIMEOUT_GRACE_MS = 5000;
  * @returns True when the processor settled within the grace period.
  */
 export declare function settleWithin(pending: Promise<unknown> | undefined, graceMs: number): Promise<boolean>;
-//# sourceMappingURL=inMemoryQueue.settle.d.ts.map

package/dist/inMemoryQueue/inMemoryQueue.settle.js

@@ -36,4 +36,3 @@ export async function settleWithin(pending, graceMs) {
             clearTimeout(timer);
     }
 }
-//# sourceMappingURL=inMemoryQueue.settle.js.map

package/dist/inMemoryQueue/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./inMemoryQueue.core.js";
 export * from "./inMemoryQueue.factory.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/inMemoryQueue/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./inMemoryQueue.core.js";
 export * from "./inMemoryQueue.factory.js";
-//# sourceMappingURL=index.js.map

package/dist/inMemoryQueue/polling/inMemoryQueue.poller.d.ts

@@ -61,4 +61,3 @@ export declare class QueuePoller {
     private run;
     private nextDelay;
 }
-//# sourceMappingURL=inMemoryQueue.poller.d.ts.map

package/dist/inMemoryQueue/polling/inMemoryQueue.poller.js

@@ -129,4 +129,3 @@ export class QueuePoller {
         return this.backoffMs;
     }
 }
-//# sourceMappingURL=inMemoryQueue.poller.js.map

package/dist/inMemoryQueue/polling/inMemoryQueue.select.d.ts

@@ -19,8 +19,12 @@ export declare function runnableAt(job: Job<unknown>): number;
  * first ({@link runnableAt}); among equals, the one added first. The
  * incumbent is tracked by reference rather than by a sentinel priority, so
  * negative priorities are selectable like any other.
+ *
+ * One pass over the job map per selection. A job that cannot beat the
+ * incumbent on priority is skipped before its timestamps are consulted, and
+ * timestamps are parsed once per record, so the pass is a state check per
+ * job rather than a date parse per job.
  */
 export declare function selectNextJob<TData>(jobs: Iterable<Job<TData>>, now: number, predicate?: (job: Job<TData>) => boolean): Job<TData> | null;
 /** Whether any job a consumer can run is still owed a run. */
 export declare function hasPendingWork<TData>(jobs: Iterable<Job<TData>>, isConsumable: (job: Job<TData>) => boolean): boolean;
-//# sourceMappingURL=inMemoryQueue.select.d.ts.map

package/dist/inMemoryQueue/polling/inMemoryQueue.select.js

@@ -11,6 +11,27 @@ const PENDING_STATES = new Set([
     JobStateEnum.RETRYING,
     JobStateEnum.ACTIVE,
 ]);
+/**
+ * Job records are immutable and replaced on every state change, so a parsed
+ * timestamp stays valid for as long as the record itself is reachable. The
+ * cache turns the per-poll cost of a waiting job from an ISO-8601 parse (or
+ * two, for a delayed job) into a map lookup.
+ */
+const jobTimes = new WeakMap();
+function timesOf(job) {
+    const cached = jobTimes.get(job);
+    if (cached !== undefined)
+        return cached;
+    const created = new Date(job.createdAt).getTime();
+    const scheduled = job.scheduledAt
+        ? new Date(job.scheduledAt).getTime()
+        : Number.NaN;
+    const times = Number.isNaN(scheduled)
+        ? { runnableAt: created, dueAt: Number.NEGATIVE_INFINITY }
+        : { runnableAt: Math.max(created, scheduled), dueAt: scheduled };
+    jobTimes.set(job, times);
+    return times;
+}
 /**
  * When a job became runnable, in epoch milliseconds: its creation, or for a
  * delayed job the moment its delay elapsed.
@@ -19,11 +40,7 @@ const PENDING_STATES = new Set([
  * that had been ready and waiting while it was still delayed.
  */
 export function runnableAt(job) {
-    const created = new Date(job.createdAt).getTime();
-    if (!job.scheduledAt)
-        return created;
-    const scheduled = new Date(job.scheduledAt).getTime();
-    return Number.isNaN(scheduled) ? created : Math.max(created, scheduled);
+    return timesOf(job).runnableAt;
 }
 /**
  * Selects the job that runs next among those that are waiting and due.
@@ -32,6 +49,11 @@ export function runnableAt(job) {
  * first ({@link runnableAt}); among equals, the one added first. The
  * incumbent is tracked by reference rather than by a sentinel priority, so
  * negative priorities are selectable like any other.
+ *
+ * One pass over the job map per selection. A job that cannot beat the
+ * incumbent on priority is skipped before its timestamps are consulted, and
+ * timestamps are parsed once per record, so the pass is a state check per
+ * job rather than a date parse per job.
  */
 export function selectNextJob(jobs, now, predicate) {
     let next = null;
@@ -39,16 +61,18 @@ export function selectNextJob(jobs, now, predicate) {
     for (const job of jobs) {
         if (job.state !== JobStateEnum.WAITING)
             continue;
-        if (job.scheduledAt && new Date(job.scheduledAt).getTime() > now)
+        if (next !== null && job.priority < next.priority)
+            continue;
+        const times = timesOf(job);
+        if (times.dueAt > now)
             continue;
         if (predicate && !predicate(job))
             continue;
-        const at = runnableAt(job);
         if (next === null ||
             job.priority > next.priority ||
-            (job.priority === next.priority && at < nextAt)) {
+            times.runnableAt < nextAt) {
             next = job;
-            nextAt = at;
+            nextAt = times.runnableAt;
         }
     }
     return next;
@@ -61,4 +85,3 @@ export function hasPendingWork(jobs, isConsumable) {
     }
     return false;
 }
-//# sourceMappingURL=inMemoryQueue.select.js.map

package/dist/inMemoryQueue/polling/index.d.ts

@@ -7,4 +7,3 @@
  */
 export * from "./inMemoryQueue.poller.js";
 export * from "./inMemoryQueue.select.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/inMemoryQueue/polling/index.js

@@ -7,4 +7,3 @@
  */
 export * from "./inMemoryQueue.poller.js";
 export * from "./inMemoryQueue.select.js";
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -24,4 +24,5 @@ export * from "./worker/index.js";
 export * from "./inMemoryQueue/index.js";
 export * from "./deadLetter/index.js";
 export * from "./contextCarrier/index.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./jobFailure/index.js";
+export * from "./queueErrors/index.js";

package/dist/index.js

@@ -41,4 +41,7 @@ export * from "./inMemoryQueue/index.js";
 export * from "./deadLetter/index.js";
 // Context propagation across the queue boundary
 export * from "./contextCarrier/index.js";
-//# sourceMappingURL=index.js.map
+// Permanent failures
+export * from "./jobFailure/index.js";
+// Error classes (owned by @zudojs/errors)
+export * from "./queueErrors/index.js";

package/dist/job/index.d.ts

@@ -6,4 +6,3 @@
  */
 export { createJob, isJob, updateJobState, incrementJobAttempt, } from "./job.core.js";
 export type { Job, JobInput } from "./job.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/job/index.js

@@ -5,4 +5,3 @@
  * and manipulating job instances.
  */
 export { createJob, isJob, updateJobState, incrementJobAttempt, } from "./job.core.js";
-//# sourceMappingURL=index.js.map

package/dist/job/job.core.d.ts

@@ -16,4 +16,3 @@ export declare function updateJobState<TData>(job: Job<TData>, state: JobState,
  * Increments a job's attempt counter.
  */
 export declare function incrementJobAttempt<TData>(job: Job<TData>): Job<TData>;
-//# sourceMappingURL=job.core.d.ts.map

package/dist/job/job.core.js

@@ -79,4 +79,3 @@ export function incrementJobAttempt(job) {
         updatedAt: new Date().toISOString(),
     };
 }
-//# sourceMappingURL=job.core.js.map

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

@@ -67,4 +67,3 @@ export interface JobInput<TData = unknown> {
     /** Job options. */
     readonly options?: JobOptions;
 }
-//# sourceMappingURL=job.type.d.ts.map

package/dist/job/job.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=job.type.js.map

package/dist/jobContext/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { createJobContext, isJobContext } from "./jobContext.core.js";
 export type { JobContext } from "./jobContext.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/jobContext/index.js

@@ -4,4 +4,3 @@
  * Provides context information to job processors during execution.
  */
 export { createJobContext, isJobContext } from "./jobContext.core.js";
-//# sourceMappingURL=index.js.map

package/dist/jobContext/jobContext.core.d.ts

@@ -14,4 +14,3 @@ export declare function createJobContext<TData>(job: Job<TData>, signal: AbortSi
  * Checks if a value is a valid JobContext.
  */
 export declare function isJobContext(value: unknown): value is JobContext;
-//# sourceMappingURL=jobContext.core.d.ts.map

package/dist/jobContext/jobContext.core.js

@@ -34,4 +34,3 @@ export function isJobContext(value) {
         "updateProgress" in value &&
         "log" in value);
 }
-//# sourceMappingURL=jobContext.core.js.map

package/dist/jobContext/jobContext.type.d.ts

@@ -20,4 +20,3 @@ export interface JobContext<TData = unknown> {
     /** Log a message with job context. */
     log(message: string, data?: Record<string, unknown>): void;
 }
-//# sourceMappingURL=jobContext.type.d.ts.map

package/dist/jobContext/jobContext.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=jobContext.type.js.map

package/dist/jobFailure/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Permanent job failures: marking an error so the job is dead-lettered
+ * without further attempts.
+ *
+ * @module jobFailure
+ */
+export { markUnrecoverable, createUnrecoverableJobError, isUnrecoverableJobError, } from "./jobFailure.unrecoverable.js";
+export type { UnrecoverableJobErrorOptions } from "./jobFailure.unrecoverable.js";

package/dist/jobFailure/index.js

@@ -0,0 +1,7 @@
+/**
+ * Permanent job failures: marking an error so the job is dead-lettered
+ * without further attempts.
+ *
+ * @module jobFailure
+ */
+export { markUnrecoverable, createUnrecoverableJobError, isUnrecoverableJobError, } from "./jobFailure.unrecoverable.js";

package/dist/jobFailure/jobFailure.unrecoverable.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Marking a job failure as permanent.
+ *
+ * By default every failure is retried until `attempts` is exhausted. Some
+ * failures are known to be permanent the moment they happen — a payload
+ * that fails validation, a record that no longer exists — and retrying them
+ * only burns the remaining attempts and delays the dead-letter entry an
+ * operator needs to see. A processor marks such a failure unrecoverable and
+ * the queue dead-letters the job at once.
+ *
+ * @module jobFailure/unrecoverable
+ */
+import { JobError } from "@zudojs/errors";
+/**
+ * Options for {@link createUnrecoverableJobError}.
+ */
+export interface UnrecoverableJobErrorOptions {
+    readonly queueName?: string;
+    readonly jobId?: string;
+    readonly cause?: unknown;
+}
+/**
+ * Marks an error so the job that throws it is dead-lettered without
+ * further attempts. Works on any error, including one from a library the
+ * processor calls into.
+ *
+ * @example
+ * ```ts
+ * queue.process("charge", async (job) => {
+ *   const card = await cards.find(job.data.cardId);
+ *   if (!card) throw markUnrecoverable(new Error("card no longer exists"));
+ * });
+ * ```
+ */
+export declare function markUnrecoverable<TError extends object>(error: TError): TError;
+/**
+ * Creates a `JobError` already marked unrecoverable.
+ *
+ * @example
+ * ```ts
+ * throw createUnrecoverableJobError("payload failed validation", {
+ *   jobId: job.id,
+ *   queueName: job.queueName,
+ * });
+ * ```
+ */
+export declare function createUnrecoverableJobError(message: string, options?: UnrecoverableJobErrorOptions): JobError;
+/**
+ * Whether a thrown value was marked with {@link markUnrecoverable}.
+ */
+export declare function isUnrecoverableJobError(value: unknown): boolean;

package/dist/jobFailure/jobFailure.unrecoverable.js

@@ -0,0 +1,65 @@
+/**
+ * Marking a job failure as permanent.
+ *
+ * By default every failure is retried until `attempts` is exhausted. Some
+ * failures are known to be permanent the moment they happen — a payload
+ * that fails validation, a record that no longer exists — and retrying them
+ * only burns the remaining attempts and delays the dead-letter entry an
+ * operator needs to see. A processor marks such a failure unrecoverable and
+ * the queue dead-letters the job at once.
+ *
+ * @module jobFailure/unrecoverable
+ */
+import { JobError } from "@zudojs/errors";
+/** Brand carried by an error whose job must not be retried. */
+const UNRECOVERABLE = Symbol.for("@zudojs/queue.unrecoverable");
+/**
+ * Marks an error so the job that throws it is dead-lettered without
+ * further attempts. Works on any error, including one from a library the
+ * processor calls into.
+ *
+ * @example
+ * ```ts
+ * queue.process("charge", async (job) => {
+ *   const card = await cards.find(job.data.cardId);
+ *   if (!card) throw markUnrecoverable(new Error("card no longer exists"));
+ * });
+ * ```
+ */
+export function markUnrecoverable(error) {
+    if (!Object.prototype.hasOwnProperty.call(error, UNRECOVERABLE)) {
+        Object.defineProperty(error, UNRECOVERABLE, {
+            value: true,
+            enumerable: false,
+            configurable: false,
+            writable: false,
+        });
+    }
+    return error;
+}
+/**
+ * Creates a `JobError` already marked unrecoverable.
+ *
+ * @example
+ * ```ts
+ * throw createUnrecoverableJobError("payload failed validation", {
+ *   jobId: job.id,
+ *   queueName: job.queueName,
+ * });
+ * ```
+ */
+export function createUnrecoverableJobError(message, options = {}) {
+    return markUnrecoverable(new JobError(message, {
+        queueName: options.queueName,
+        jobId: options.jobId,
+        cause: options.cause,
+    }));
+}
+/**
+ * Whether a thrown value was marked with {@link markUnrecoverable}.
+ */
+export function isUnrecoverableJobError(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[UNRECOVERABLE] === true);
+}

package/dist/jobOptions/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { DEFAULT_JOB_OPTIONS, mergeJobOptions } from "./jobOptions.core.js";
 export type { BackoffOptions, JobOptions } from "./jobOptions.type.js";
-//# sourceMappingURL=index.d.ts.map