@warlock.js/queue 5.41.0 → 5.43.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@warlock.js/queue` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.43.0 - 2026-11-01
+
+### Added
+
+- Job timeouts: `defineJob({ timeout: "2m", failOnTimeout?: boolean })`, also accepted per dispatch and in `queue.defaultJobOptions` (dispatch > `defineJob` > defaults). An attempt that outlives its limit fails with the new exported `JobTimeoutError` (job name, limit in `timeout`, `failOnTimeout`), so failed jobs and events show a clear reason, and normal `attempts` and `backoff` apply. `failOnTimeout: true` fails the job without retrying (BullMQ `UnrecoverableError` on Redis). Enforced in the shared processing path, so BullMQ, `local` and `memory` behave the same. A zero, negative or unparsable timeout throws.
+- `ctx.signal` is now passed to handlers on every driver whenever the job has a `timeout`, and aborts with the `JobTimeoutError`. A handler that ignores the signal keeps running in the background after its attempt fails, so pass the signal to `fetch` and database calls.
+
 ## 5.34.3 - 2026-10-20
 
 ### Changed

package/cjs/index.cjs

@@ -67,6 +67,20 @@ var UnrecoverableJobError = class extends Error {
 		this.name = "UnrecoverableJobError";
 	}
 };
+/**
+* The failure recorded when a job attempt outlives its `timeout`. It appears
+* as the failed reason of the attempt and as the abort reason of
+* `ctx.signal`. With `failOnTimeout` the job is not retried.
+*/
+var JobTimeoutError = class extends Error {
+	constructor(jobName, timeout, failOnTimeout = false) {
+		super(`Job "${jobName}" timed out after ${timeout}ms.`);
+		this.jobName = jobName;
+		this.timeout = timeout;
+		this.failOnTimeout = failOnTimeout;
+		this.name = "JobTimeoutError";
+	}
+};
 
 //#endregion
 //#region ../../packages/queue/src/config.ts
@@ -192,6 +206,86 @@ function onJobRegistered(listener) {
 	return () => listeners.delete(listener);
 }
 
+//#endregion
+//#region ../../packages/queue/src/duration.ts
+const UNIT_MILLISECONDS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+/**
+* Convert a {@link Duration} to milliseconds. Numbers are already
+* milliseconds. Anything else is rejected loudly rather than guessed at.
+*/
+function toMilliseconds(value) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value < 0) throw new InvalidDurationError(value);
+		return Math.round(value);
+	}
+	const match = typeof value === "string" ? DURATION_PATTERN.exec(value.trim()) : null;
+	if (!match) throw new InvalidDurationError(value);
+	return Math.round(Number(match[1]) * UNIT_MILLISECONDS[match[2]]);
+}
+
+//#endregion
+//#region ../../packages/queue/src/job-timeout.ts
+/**
+* Convert a `timeout` option to milliseconds. Unparsable values throw
+* `InvalidDurationError`; zero and negative limits throw
+* `InvalidJobDefinitionError` — a timeout is never silently repaired or ignored.
+*/
+function resolveTimeout(value, label = "timeout") {
+	const milliseconds = toMilliseconds(value);
+	if (milliseconds <= 0) throw new InvalidJobDefinitionError(`\`${label}\` must be greater than zero, got ${JSON.stringify(value)}.`);
+	return milliseconds;
+}
+/** Throw unless `failOnTimeout` is a boolean (or unset). */
+function assertFailOnTimeout(value, label = "failOnTimeout") {
+	if (value !== void 0 && typeof value !== "boolean") throw new InvalidJobDefinitionError(`\`${label}\` must be a boolean, got ${JSON.stringify(value)}.`);
+}
+/**
+* One attempt's time limit, shared by every driver. Without a `timeout` it
+* passes the parent signal through and adds nothing. On expiry the signal
+* aborts with the `JobTimeoutError` and the attempt fails; a handler that
+* ignores the signal keeps running in the background, because JavaScript
+* cannot stop it.
+*/
+function createJobAbort(name, settings, parent) {
+	const { timeout } = settings;
+	if (timeout === void 0) return {
+		signal: parent,
+		guard: (work) => work(),
+		dispose() {}
+	};
+	const controller = new AbortController();
+	const onParentAbort = () => controller.abort(parent?.reason);
+	if (parent?.aborted) controller.abort(parent.reason);
+	else parent?.addEventListener("abort", onParentAbort, { once: true });
+	let timer;
+	return {
+		signal: controller.signal,
+		guard(work) {
+			const expired = new Promise((_, reject) => {
+				timer = setTimeout(() => {
+					const error = new JobTimeoutError(name, timeout, settings.failOnTimeout === true);
+					controller.abort(error);
+					reject(error);
+				}, timeout);
+			});
+			const running = work();
+			running.catch(() => {});
+			return Promise.race([running, expired]);
+		},
+		dispose() {
+			clearTimeout(timer);
+			parent?.removeEventListener("abort", onParentAbort);
+		}
+	};
+}
+
 //#endregion
 //#region ../../packages/queue/src/queue-context.ts
 /**
@@ -259,6 +353,7 @@ async function processJob(job) {
 	const definition = findRegisteredJob(job.name);
 	if (!definition) throw new bullmq.UnrecoverableError(`No job named "${job.name}" is defined in this process. Make sure the module that calls defineJob() is imported by the worker process.`);
 	const { payload, context: captured } = unwrapPayload(job.data);
+	const abort = createJobAbort(job.name, job.opts);
 	const context = {
 		id: String(job.id),
 		name: job.name,
@@ -269,15 +364,19 @@ async function processJob(job) {
 		log: async (line) => {
 			await job.log(line);
 		},
-		context: captured
+		context: captured,
+		signal: abort.signal
 	};
 	const run = async () => definition.handle(payload, context);
 	const queueContext = getQueueContext();
 	try {
-		return captured !== void 0 && queueContext ? await queueContext.restore(captured, run) : await run();
+		return await abort.guard(async () => captured !== void 0 && queueContext ? queueContext.restore(captured, run) : run());
 	} catch (error) {
 		if (error instanceof UnrecoverableJobError) throw new bullmq.UnrecoverableError(error.message);
+		if (error instanceof JobTimeoutError && error.failOnTimeout) throw new bullmq.UnrecoverableError(error.message);
 		throw error;
+	} finally {
+		abort.dispose();
 	}
 }
 
@@ -601,6 +700,7 @@ var LocalDriver = class {
 	}
 	async execute(entry) {
 		const { job, token, controller } = entry;
+		const abort = createJobAbort(job.name, job.options, controller.signal);
 		try {
 			const definition = findRegisteredJob(job.name);
 			if (!definition) throw new UnrecoverableJobError(`No job named "${job.name}" is defined in this process. Import its definition in the worker.`);
@@ -612,7 +712,7 @@ var LocalDriver = class {
 				attempt: job.attemptsMade + 1,
 				maxAttempts: job.options.attempts ?? 1,
 				context: captured,
-				signal: controller.signal,
+				signal: abort.signal,
 				progress: async (value) => {
 					if (!this.mutate(job, token, (current) => {
 						current.progress = jsonCopy(value);
@@ -626,7 +726,7 @@ var LocalDriver = class {
 			};
 			const run = async () => definition.handle(payload, context);
 			const queueContext = getQueueContext();
-			const result = jsonCopy(captured !== void 0 && queueContext ? await queueContext.restore(captured, run) : await run());
+			const result = jsonCopy(await abort.guard(async () => captured !== void 0 && queueContext ? queueContext.restore(captured, run) : run()));
 			this.mutate(job, token, (current) => {
 				current.attemptsMade++;
 				current.result = result;
@@ -642,7 +742,7 @@ var LocalDriver = class {
 				current.stacktrace.push(error instanceof Error ? error.stack ?? error.message : String(error));
 				current.leaseUntil = 0;
 				delete current.token;
-				if (error instanceof UnrecoverableJobError || current.attemptsMade >= (current.options.attempts ?? 1)) {
+				if (error instanceof UnrecoverableJobError || error instanceof JobTimeoutError && error.failOnTimeout || current.attemptsMade >= (current.options.attempts ?? 1)) {
 					current.state = "failed";
 					current.finishedAt = Date.now();
 				} else {
@@ -653,6 +753,8 @@ var LocalDriver = class {
 					current.state = delay > 0 ? "delayed" : current.priority ? "prioritized" : "waiting";
 				}
 			}, true);
+		} finally {
+			abort.dispose();
 		}
 	}
 	/** Fencing: expired owners cannot renew, finish, or overwrite a new owner's job. */
@@ -700,6 +802,7 @@ function positiveInteger(value, name, minimum = 1) {
 function validateOptions({ options }) {
 	positiveInteger(options.attempts ?? 1, "attempts");
 	if (options.priority !== void 0 && (!Number.isInteger(options.priority) || options.priority < 0 || options.priority > 2097152)) throw new Error("priority must be an integer between 0 and 2097152.");
+	if (options.timeout !== void 0 && !(Number.isFinite(options.timeout) && options.timeout > 0)) throw new Error("timeout must be a positive finite number of milliseconds.");
 	const backoff = options.backoff;
 	const delay = typeof backoff === "number" ? backoff : backoff?.delay ?? 0;
 	if (!Number.isFinite(delay) || delay < 0 || typeof backoff === "object" && !["fixed", "exponential"].includes(backoff.type)) throw new Error("backoff must have a non-negative finite delay and fixed or exponential type.");
@@ -1035,39 +1138,20 @@ function getDispatchInterceptor() {
 	return globalThis[INTERCEPTOR_KEY];
 }
 
-//#endregion
-//#region ../../packages/queue/src/duration.ts
-const UNIT_MILLISECONDS = {
-	ms: 1,
-	s: 1e3,
-	m: 6e4,
-	h: 36e5,
-	d: 864e5
-};
-const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
-/**
-* Convert a {@link Duration} to milliseconds. Numbers are already
-* milliseconds. Anything else is rejected loudly rather than guessed at.
-*/
-function toMilliseconds(value) {
-	if (typeof value === "number") {
-		if (!Number.isFinite(value) || value < 0) throw new InvalidDurationError(value);
-		return Math.round(value);
-	}
-	const match = typeof value === "string" ? DURATION_PATTERN.exec(value.trim()) : null;
-	if (!match) throw new InvalidDurationError(value);
-	return Math.round(Number(match[1]) * UNIT_MILLISECONDS[match[2]]);
-}
-
 //#endregion
 //#region ../../packages/queue/src/job-options.ts
 function resolveJobOptions(definition, options) {
 	const defaults = getQueueConfig().defaultJobOptions ?? {};
+	const timeout = options.timeout ?? definition.timeout ?? defaults.timeout;
+	const failOnTimeout = options.failOnTimeout ?? definition.failOnTimeout ?? defaults.failOnTimeout;
+	assertFailOnTimeout(failOnTimeout);
 	return {
 		attempts: options.attempts ?? definition.attempts ?? defaults.attempts,
 		backoff: options.backoff ?? definition.backoff ?? defaults.backoff,
 		removeOnComplete: definition.removeOnComplete ?? defaults.removeOnComplete,
 		removeOnFail: definition.removeOnFail ?? defaults.removeOnFail,
+		timeout: timeout === void 0 ? void 0 : resolveTimeout(timeout),
+		failOnTimeout,
 		delay: options.delay === void 0 ? void 0 : toMilliseconds(options.delay),
 		priority: options.priority,
 		jobId: options.jobId
@@ -1135,6 +1219,12 @@ function assertValidDefinition(definition) {
 	if (typeof definition.name !== "string" || definition.name.trim() === "") throw new InvalidJobDefinitionError("defineJob() requires a non-empty `name`.");
 	if (typeof definition.handle !== "function") throw new InvalidJobDefinitionError(`defineJob("${definition.name}") requires a \`handle(payload, ctx)\` function.`);
 	if (definition.attempts !== void 0 && !(Number.isInteger(definition.attempts) && definition.attempts >= 1)) throw new InvalidJobDefinitionError(`defineJob("${definition.name}"): \`attempts\` must be an integer >= 1, got ${definition.attempts}.`);
+	if (definition.timeout !== void 0) try {
+		resolveTimeout(definition.timeout);
+	} catch (error) {
+		throw new InvalidJobDefinitionError(`defineJob("${definition.name}"): ${error instanceof Error ? error.message : String(error)}`);
+	}
+	assertFailOnTimeout(definition.failOnTimeout);
 }
 
 //#endregion
@@ -1235,6 +1325,7 @@ exports.DEFAULT_DASHBOARD_PATH = DEFAULT_DASHBOARD_PATH;
 exports.FailedJobNotFoundError = FailedJobNotFoundError;
 exports.InvalidDurationError = InvalidDurationError;
 exports.InvalidJobDefinitionError = InvalidJobDefinitionError;
+exports.JobTimeoutError = JobTimeoutError;
 exports.QUEUE_CONNECTOR_PRIORITY = QUEUE_CONNECTOR_PRIORITY;
 exports.QueueDashboardDependencyError = QueueDashboardDependencyError;
 exports.QueueDashboardUnguardedError = QueueDashboardUnguardedError;