@warlock.js/queue 5.13.0

package/cjs/index.cjs

@@ -0,0 +1,180 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_define_job = require('./define-job-DideGKQK.cjs');
+let _warlock_js_logger = require("@warlock.js/logger");
+
+//#region ../queue/src/dashboard.ts
+/**
+* Mount the bull-board failed/active/delayed job UI on Warlock's Fastify
+* server. Requires the optional packages `@bull-board/api` and
+* `@bull-board/fastify`; they are loaded only when this is called, and a
+* missing one throws {@link QueueDashboardDependencyError}.
+*
+* Call it before the HTTP server starts listening, and put it behind your
+* own authentication — the dashboard can retry and delete jobs.
+*
+* @example
+* import { getHttpServer } from "@warlock.js/core";
+* await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+*/
+async function queueDashboard(server, options = {}) {
+	const basePath = options.basePath ?? "/admin/queues";
+	const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();
+	const queueNames = options.queues ?? [...new Set([require_define_job.defaultQueueName(), ...require_define_job.registeredJobs().map((job) => require_define_job.queueOf(job))])];
+	const serverAdapter = new FastifyAdapter();
+	serverAdapter.setBasePath(basePath);
+	createBullBoard({
+		queues: queueNames.map((name) => new BullMQAdapter(require_define_job.getQueue(name))),
+		serverAdapter
+	});
+	await server.register(serverAdapter.registerPlugin(), { prefix: basePath });
+}
+/**
+* Load the optional bull-board packages. Exported for tests of the missing
+* dependency path; `importer` defaults to a real dynamic import.
+*/
+async function loadBullBoard(importer = (specifier) => import(specifier)) {
+	const api = await importOptional(importer, "@bull-board/api");
+	const adapter = await importOptional(importer, "@bull-board/api/bullMQAdapter");
+	const fastify = await importOptional(importer, "@bull-board/fastify");
+	return {
+		createBullBoard: api.createBullBoard,
+		BullMQAdapter: adapter.BullMQAdapter,
+		FastifyAdapter: fastify.FastifyAdapter
+	};
+}
+async function importOptional(importer, specifier) {
+	try {
+		return await importer(specifier);
+	} catch (error) {
+		if (isModuleNotFound(error)) throw new require_define_job.QueueDashboardDependencyError(specifier.split("/").slice(0, 2).join("/"));
+		throw error;
+	}
+}
+function isModuleNotFound(error) {
+	const code = error?.code;
+	return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+
+//#endregion
+//#region ../queue/src/failed-jobs.ts
+/**
+* List failed jobs, newest first — jobs that used up every attempt, or
+* failed unrecoverably. Each entry can be retried.
+*/
+async function failedJobs(options = {}) {
+	return (await require_define_job.getQueue(options.queue ?? require_define_job.defaultQueueName()).getFailed(options.start ?? 0, options.end ?? 99)).map((job) => toFailedJob(job));
+}
+/**
+* Retry one failed job by id: it goes back to waiting with its attempts reset.
+* Throws {@link FailedJobNotFoundError} when no FAILED job has that id.
+*/
+async function retryFailedJob(id, options = {}) {
+	const queueName = options.queue ?? require_define_job.defaultQueueName();
+	const job = await require_define_job.getQueue(queueName).getJob(id);
+	if (!job || !await job.isFailed()) throw new require_define_job.FailedJobNotFoundError(id, queueName);
+	await job.retry("failed");
+}
+function toFailedJob(job) {
+	return {
+		id: String(job.id),
+		name: job.name,
+		queue: job.queueName,
+		payload: job.data,
+		attemptsMade: job.attemptsMade,
+		failedReason: job.failedReason,
+		stacktrace: job.stacktrace ?? [],
+		failedAt: job.finishedOn ? new Date(job.finishedOn) : void 0,
+		retry: () => job.retry("failed")
+	};
+}
+
+//#endregion
+//#region ../queue/src/queue-connector.ts
+/**
+* Boots after every built-in connector (`ConnectorPriority.AI` is `10`), so
+* the logger is up and anything a job handler needs is already connected;
+* shuts down before them for the same reason.
+*/
+const QUEUE_CONNECTOR_PRIORITY = 11;
+const WATCHED_FILES = ["src/config/queue.ts"];
+/**
+* Construct the queue connector.
+*
+* Runs in the `late` lifecycle phase — after app code is imported — so every
+* `defineJob` in the app has registered before workers start. At start it
+* reads the `queue` config and starts in-process workers unless
+* `workers.enabled` is `false`; at shutdown it closes workers (waiting for
+* active jobs, bounded by `workers.shutdownTimeout`) and then the queues.
+*
+* @example
+* // warlock.config.ts
+* import { queueConnector } from "@warlock.js/queue";
+*
+* export default defineConfig({ connectors: [queueConnector()] });
+*/
+function queueConnector(options = {}) {
+	let active = false;
+	const connector = {
+		name: "queue",
+		priority: 11,
+		lifecyclePhase: "late",
+		isActive: () => active,
+		boot: () => void 0,
+		async start() {
+			const queueConfig = options.config ?? await readQueueConfig();
+			if (!queueConfig) {
+				_warlock_js_logger.log.warn("queue", "configured", "queueConnector() is registered but no `queue` config was found (src/config/queue.ts); queue not started");
+				return;
+			}
+			require_define_job.setQueueConfig(queueConfig);
+			const started = await require_define_job.startWorkers();
+			active = true;
+			_warlock_js_logger.log.info("queue", "configured", started.length > 0 ? `Queue workers running for: ${started.join(", ")}` : "Queue configured (no in-process workers)");
+		},
+		async restart() {
+			await connector.shutdown();
+			await connector.start();
+		},
+		async shutdown() {
+			if (!active) return;
+			await require_define_job.closeQueue();
+			require_define_job.resetQueueConfig();
+			active = false;
+		},
+		shouldRestart(changedFiles) {
+			return changedFiles.some((file) => {
+				const normalized = file.replace(/\\/g, "/");
+				return WATCHED_FILES.some((watched) => normalized === watched || normalized.endsWith(`/${watched}`));
+			});
+		}
+	};
+	return connector;
+}
+async function readQueueConfig() {
+	const { config } = await import("@warlock.js/core");
+	return config.get("queue");
+}
+
+//#endregion
+exports.FailedJobNotFoundError = require_define_job.FailedJobNotFoundError;
+exports.InvalidDurationError = require_define_job.InvalidDurationError;
+exports.InvalidJobDefinitionError = require_define_job.InvalidJobDefinitionError;
+exports.QUEUE_CONNECTOR_PRIORITY = QUEUE_CONNECTOR_PRIORITY;
+exports.QueueDashboardDependencyError = require_define_job.QueueDashboardDependencyError;
+exports.QueueNotConfiguredError = require_define_job.QueueNotConfiguredError;
+exports.closeQueue = require_define_job.closeQueue;
+exports.defaultQueueName = require_define_job.defaultQueueName;
+exports.defineJob = require_define_job.defineJob;
+exports.failedJobs = failedJobs;
+exports.getQueue = require_define_job.getQueue;
+exports.getQueueConfig = require_define_job.getQueueConfig;
+exports.loadBullBoard = loadBullBoard;
+exports.queueConnector = queueConnector;
+exports.queueDashboard = queueDashboard;
+exports.resetQueueConfig = require_define_job.resetQueueConfig;
+exports.retryFailedJob = retryFailedJob;
+exports.runningWorkers = require_define_job.runningWorkers;
+exports.setQueueConfig = require_define_job.setQueueConfig;
+exports.startWorkers = require_define_job.startWorkers;
+exports.toMilliseconds = require_define_job.toMilliseconds;
+//# sourceMappingURL=index.cjs.map

package/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["defaultQueueName","registeredJobs","queueOf","getQueue","QueueDashboardDependencyError","getQueue","defaultQueueName","FailedJobNotFoundError","startWorkers","closeQueue"],"sources":["../../../../../../queue/src/dashboard.ts","../../../../../../queue/src/failed-jobs.ts","../../../../../../queue/src/queue-connector.ts"],"sourcesContent":["import { defaultQueueName } from \"./config\";\nimport { QueueDashboardDependencyError } from \"./errors\";\nimport { queueOf, registeredJobs } from \"./job-registry\";\nimport { getQueue } from \"./queue-manager\";\n\n/**\n * The part of a Fastify instance the dashboard needs. Warlock's HTTP server\n * (`getHttpServer()` from `@warlock.js/core`) satisfies it.\n */\nexport type DashboardServer = {\n  register(plugin: never, options: { prefix: string }): unknown;\n};\n\nexport type QueueDashboardOptions = {\n  /** URL prefix the dashboard is mounted on. Default `\"/admin/queues\"`. */\n  basePath?: string;\n  /** Queues to show. Default: every queue with a defined job, plus the default queue. */\n  queues?: string[];\n};\n\ntype BullBoardModules = {\n  createBullBoard: (options: { queues: unknown[]; serverAdapter: unknown }) => unknown;\n  BullMQAdapter: new (queue: unknown) => unknown;\n  FastifyAdapter: new () => {\n    setBasePath(path: string): unknown;\n    registerPlugin(): unknown;\n  };\n};\n\n/**\n * Mount the bull-board failed/active/delayed job UI on Warlock's Fastify\n * server. Requires the optional packages `@bull-board/api` and\n * `@bull-board/fastify`; they are loaded only when this is called, and a\n * missing one throws {@link QueueDashboardDependencyError}.\n *\n * Call it before the HTTP server starts listening, and put it behind your\n * own authentication — the dashboard can retry and delete jobs.\n *\n * @example\n * import { getHttpServer } from \"@warlock.js/core\";\n * await queueDashboard(getHttpServer(), { basePath: \"/admin/queues\" });\n */\nexport async function queueDashboard(\n  server: DashboardServer,\n  options: QueueDashboardOptions = {},\n): Promise<void> {\n  const basePath = options.basePath ?? \"/admin/queues\";\n  const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();\n  const queueNames =\n    options.queues ?? [...new Set([defaultQueueName(), ...registeredJobs().map((job) => queueOf(job))])];\n\n  const serverAdapter = new FastifyAdapter();\n  serverAdapter.setBasePath(basePath);\n\n  createBullBoard({\n    queues: queueNames.map((name) => new BullMQAdapter(getQueue(name))),\n    serverAdapter,\n  });\n\n  await server.register(serverAdapter.registerPlugin() as never, { prefix: basePath });\n}\n\n/**\n * Load the optional bull-board packages. Exported for tests of the missing\n * dependency path; `importer` defaults to a real dynamic import.\n */\nexport async function loadBullBoard(\n  importer: (specifier: string) => Promise<Record<string, unknown>> = (specifier) => import(specifier),\n): Promise<BullBoardModules> {\n  const api = await importOptional(importer, \"@bull-board/api\");\n  const adapter = await importOptional(importer, \"@bull-board/api/bullMQAdapter\");\n  const fastify = await importOptional(importer, \"@bull-board/fastify\");\n\n  return {\n    createBullBoard: api.createBullBoard as BullBoardModules[\"createBullBoard\"],\n    BullMQAdapter: adapter.BullMQAdapter as BullBoardModules[\"BullMQAdapter\"],\n    FastifyAdapter: fastify.FastifyAdapter as BullBoardModules[\"FastifyAdapter\"],\n  };\n}\n\nasync function importOptional(\n  importer: (specifier: string) => Promise<Record<string, unknown>>,\n  specifier: string,\n): Promise<Record<string, unknown>> {\n  try {\n    return await importer(specifier);\n  } catch (error) {\n    if (isModuleNotFound(error)) {\n      throw new QueueDashboardDependencyError(specifier.split(\"/\").slice(0, 2).join(\"/\"));\n    }\n\n    throw error;\n  }\n}\n\nfunction isModuleNotFound(error: unknown): boolean {\n  const code = (error as { code?: unknown } | undefined)?.code;\n\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n","import type { Job } from \"bullmq\";\nimport { defaultQueueName } from \"./config\";\nimport { FailedJobNotFoundError } from \"./errors\";\nimport { getQueue } from \"./queue-manager\";\nimport type { FailedJob } from \"./types\";\n\nexport type FailedJobsOptions = {\n  /** Queue to read. Default: the default queue. */\n  queue?: string;\n  /** First index (newest first). Default `0`. */\n  start?: number;\n  /** Last index, inclusive. Default `99`. */\n  end?: number;\n};\n\n/**\n * List failed jobs, newest first — jobs that used up every attempt, or\n * failed unrecoverably. Each entry can be retried.\n */\nexport async function failedJobs(options: FailedJobsOptions = {}): Promise<FailedJob[]> {\n  const queueName = options.queue ?? defaultQueueName();\n  const jobs = await getQueue(queueName).getFailed(options.start ?? 0, options.end ?? 99);\n\n  return jobs.map((job) => toFailedJob(job));\n}\n\n/**\n * Retry one failed job by id: it goes back to waiting with its attempts reset.\n * Throws {@link FailedJobNotFoundError} when no FAILED job has that id.\n */\nexport async function retryFailedJob(id: string, options: { queue?: string } = {}): Promise<void> {\n  const queueName = options.queue ?? defaultQueueName();\n  const job = await getQueue(queueName).getJob(id);\n\n  if (!job || !(await job.isFailed())) {\n    throw new FailedJobNotFoundError(id, queueName);\n  }\n\n  await job.retry(\"failed\");\n}\n\nfunction toFailedJob(job: Job): FailedJob {\n  return {\n    id: String(job.id),\n    name: job.name,\n    queue: job.queueName,\n    payload: job.data,\n    attemptsMade: job.attemptsMade,\n    failedReason: job.failedReason,\n    stacktrace: job.stacktrace ?? [],\n    failedAt: job.finishedOn ? new Date(job.finishedOn) : undefined,\n    retry: () => job.retry(\"failed\"),\n  };\n}\n","/**\n * The queue's connector for `warlock.config.ts > connectors`.\n *\n * Deliberately a plain object with TYPE-ONLY imports from core: the config\n * file that constructs it must not drag core's runtime graph (or BullMQ) in\n * at config-load time. Core is imported lazily inside `start()`, where the\n * app has already loaded it.\n */\nimport type { Connector, ConnectorLifecyclePhase } from \"@warlock.js/core\";\nimport { log } from \"@warlock.js/logger\";\nimport { resetQueueConfig, setQueueConfig } from \"./config\";\nimport { closeQueue, startWorkers } from \"./queue-manager\";\nimport type { QueueConfig } from \"./types\";\n\n/**\n * Boots after every built-in connector (`ConnectorPriority.AI` is `10`), so\n * the logger is up and anything a job handler needs is already connected;\n * shuts down before them for the same reason.\n */\nexport const QUEUE_CONNECTOR_PRIORITY = 11;\n\nconst WATCHED_FILES = [\"src/config/queue.ts\"];\n\nexport type QueueConnectorOptions = {\n  /**\n   * Supply the configuration directly instead of reading the `queue` config\n   * key (`src/config/queue.ts`).\n   */\n  config?: QueueConfig;\n};\n\n/**\n * Construct the queue connector.\n *\n * Runs in the `late` lifecycle phase — after app code is imported — so every\n * `defineJob` in the app has registered before workers start. At start it\n * reads the `queue` config and starts in-process workers unless\n * `workers.enabled` is `false`; at shutdown it closes workers (waiting for\n * active jobs, bounded by `workers.shutdownTimeout`) and then the queues.\n *\n * @example\n * // warlock.config.ts\n * import { queueConnector } from \"@warlock.js/queue\";\n *\n * export default defineConfig({ connectors: [queueConnector()] });\n */\nexport function queueConnector(options: QueueConnectorOptions = {}): Connector {\n  let active = false;\n\n  const connector: Connector = {\n    name: \"queue\",\n    priority: QUEUE_CONNECTOR_PRIORITY,\n    // Core's `ConnectorLifecyclePhase.Late`; the value is spelled out so this\n    // module stays free of a runtime import of core.\n    lifecyclePhase: \"late\" as ConnectorLifecyclePhase,\n    isActive: () => active,\n    boot: () => undefined,\n    async start() {\n      const queueConfig = options.config ?? (await readQueueConfig());\n\n      if (!queueConfig) {\n        log.warn(\n          \"queue\",\n          \"configured\",\n          \"queueConnector() is registered but no `queue` config was found (src/config/queue.ts); queue not started\",\n        );\n        return;\n      }\n\n      setQueueConfig(queueConfig);\n      const started = await startWorkers();\n      active = true;\n\n      log.info(\n        \"queue\",\n        \"configured\",\n        started.length > 0\n          ? `Queue workers running for: ${started.join(\", \")}`\n          : \"Queue configured (no in-process workers)\",\n      );\n    },\n    async restart() {\n      await connector.shutdown();\n      await connector.start();\n    },\n    async shutdown() {\n      if (!active) {\n        return;\n      }\n\n      await closeQueue();\n      resetQueueConfig();\n      active = false;\n    },\n    shouldRestart(changedFiles) {\n      return changedFiles.some((file) => {\n        const normalized = file.replace(/\\\\/g, \"/\");\n\n        return WATCHED_FILES.some((watched) => normalized === watched || normalized.endsWith(`/${watched}`));\n      });\n    },\n  };\n\n  return connector;\n}\n\nasync function readQueueConfig(): Promise<QueueConfig | undefined> {\n  const { config } = await import(\"@warlock.js/core\");\n\n  return config.get<QueueConfig | undefined>(\"queue\");\n}\n"],"mappings":"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"}

package/cjs/notifications/index.cjs

@@ -0,0 +1,68 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_define_job = require('../define-job-DideGKQK.cjs');
+let bullmq = require("bullmq");
+let _warlock_js_notifications = require("@warlock.js/notifications");
+
+//#region ../queue/src/notifications/queue-notification-dispatcher.ts
+/**
+* BullMQ-backed `QueueDispatcher` for `@warlock.js/notifications`.
+*
+* Notifications renders the payload and resolves the route BEFORE handing a
+* job to its dispatcher, so the job (`{ channel, route, payload, options }`)
+* is plain JSON. This adapter enqueues it as a queue job; the job's handler,
+* running in any worker process, looks the channel up by name in that
+* process's notifications config and calls `channel.send`.
+*
+* Notifications itself has no dependency on this package.
+*/
+/** The job name notification deliveries run under. */
+const NOTIFICATION_JOB_NAME = "warlock.notifications.deliver";
+/**
+* Create the dispatcher for `NotificationConfig.queue`.
+*
+* - `SendOptions.delay` is honoured: a number is SECONDS (notifications'
+*   convention), a string is a duration such as `"10m"`.
+* - A failing `channel.send` throws, so the delivery is retried per
+*   `attempts` / `backoff` and ends in `failedJobs()` when exhausted.
+* - A channel missing from the worker's notifications config fails at once,
+*   without retries.
+*
+* @example src/config/notifications.ts
+* import { queueNotificationDispatcher } from "@warlock.js/queue/notifications";
+*
+* const config: NotificationConfig = {
+*   channels: { mail: mailChannel() },
+*   queue: queueNotificationDispatcher({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+* };
+*/
+function queueNotificationDispatcher(options = {}) {
+	const deliver = defineNotificationJob(options);
+	return { async dispatch(job) {
+		await deliver.dispatch(job, { delay: job.options.delay === void 0 ? void 0 : notificationDelay(job.options.delay) });
+	} };
+}
+function defineNotificationJob(options) {
+	return require_define_job.defineJob({
+		name: NOTIFICATION_JOB_NAME,
+		queue: options.queue,
+		attempts: options.attempts,
+		backoff: options.backoff,
+		async handle(job) {
+			const channel = (0, _warlock_js_notifications.getNotificationConfig)().channels[job.channel];
+			if (!channel) throw new bullmq.UnrecoverableError(`Notification channel "${job.channel}" is not configured in this worker's notifications config.`);
+			await channel.send({
+				payload: job.payload,
+				route: job.route,
+				options: job.options
+			});
+		}
+	});
+}
+function notificationDelay(delay) {
+	return typeof delay === "number" ? delay * 1e3 : require_define_job.toMilliseconds(delay);
+}
+
+//#endregion
+exports.NOTIFICATION_JOB_NAME = NOTIFICATION_JOB_NAME;
+exports.queueNotificationDispatcher = queueNotificationDispatcher;
+//# sourceMappingURL=index.cjs.map

package/cjs/notifications/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["defineJob","UnrecoverableError","toMilliseconds"],"sources":["../../../../../../../queue/src/notifications/queue-notification-dispatcher.ts"],"sourcesContent":["/**\n * BullMQ-backed `QueueDispatcher` for `@warlock.js/notifications`.\n *\n * Notifications renders the payload and resolves the route BEFORE handing a\n * job to its dispatcher, so the job (`{ channel, route, payload, options }`)\n * is plain JSON. This adapter enqueues it as a queue job; the job's handler,\n * running in any worker process, looks the channel up by name in that\n * process's notifications config and calls `channel.send`.\n *\n * Notifications itself has no dependency on this package.\n */\nimport { getNotificationConfig, type QueueDispatcher } from \"@warlock.js/notifications\";\nimport { UnrecoverableError } from \"bullmq\";\nimport { defineJob } from \"../define-job\";\nimport { toMilliseconds } from \"../duration\";\nimport type { Duration, JobBackoff, QueueJob } from \"../types\";\n\n/** The job name notification deliveries run under. */\nexport const NOTIFICATION_JOB_NAME = \"warlock.notifications.deliver\";\n\nexport type NotificationJobPayload = Parameters<QueueDispatcher[\"dispatch\"]>[0];\n\nexport type QueueNotificationDispatcherOptions = {\n  /** Queue to deliver on. Default: the default queue. */\n  queue?: string;\n  /** Attempts per delivery. Default: `queue.defaultJobOptions.attempts`, else `1`. */\n  attempts?: number;\n  /** Backoff between attempts. */\n  backoff?: JobBackoff;\n};\n\n/**\n * Create the dispatcher for `NotificationConfig.queue`.\n *\n * - `SendOptions.delay` is honoured: a number is SECONDS (notifications'\n *   convention), a string is a duration such as `\"10m\"`.\n * - A failing `channel.send` throws, so the delivery is retried per\n *   `attempts` / `backoff` and ends in `failedJobs()` when exhausted.\n * - A channel missing from the worker's notifications config fails at once,\n *   without retries.\n *\n * @example src/config/notifications.ts\n * import { queueNotificationDispatcher } from \"@warlock.js/queue/notifications\";\n *\n * const config: NotificationConfig = {\n *   channels: { mail: mailChannel() },\n *   queue: queueNotificationDispatcher({ attempts: 3, backoff: { type: \"exponential\", delay: 5000 } }),\n * };\n */\nexport function queueNotificationDispatcher(\n  options: QueueNotificationDispatcherOptions = {},\n): QueueDispatcher {\n  const deliver = defineNotificationJob(options);\n\n  return {\n    async dispatch(job) {\n      await deliver.dispatch(job, {\n        delay: job.options.delay === undefined ? undefined : notificationDelay(job.options.delay),\n      });\n    },\n  };\n}\n\nfunction defineNotificationJob(\n  options: QueueNotificationDispatcherOptions,\n): QueueJob<NotificationJobPayload, void> {\n  return defineJob<NotificationJobPayload, void>({\n    name: NOTIFICATION_JOB_NAME,\n    queue: options.queue,\n    attempts: options.attempts,\n    backoff: options.backoff,\n    async handle(job) {\n      const channels = getNotificationConfig().channels as Record<\n        string,\n        { send(context: never): Promise<void> } | undefined\n      >;\n      const channel = channels[job.channel];\n\n      if (!channel) {\n        throw new UnrecoverableError(\n          `Notification channel \"${job.channel}\" is not configured in this worker's notifications config.`,\n        );\n      }\n\n      await channel.send({ payload: job.payload, route: job.route, options: job.options } as never);\n    },\n  });\n}\n\nfunction notificationDelay(delay: number | string): Duration {\n  return typeof delay === \"number\" ? delay * 1_000 : toMilliseconds(delay);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;;AA+BrC,SAAgB,4BACd,UAA8C,CAAC,GAC9B;CACjB,MAAM,UAAU,sBAAsB,OAAO;CAE7C,OAAO,EACL,MAAM,SAAS,KAAK;EAClB,MAAM,QAAQ,SAAS,KAAK,EAC1B,OAAO,IAAI,QAAQ,UAAU,SAAY,SAAY,kBAAkB,IAAI,QAAQ,KAAK,EAC1F,CAAC;CACH,EACF;AACF;AAEA,SAAS,sBACP,SACwC;CACxC,OAAOA,6BAAwC;EAC7C,MAAM;EACN,OAAO,QAAQ;EACf,UAAU,QAAQ;EAClB,SAAS,QAAQ;EACjB,MAAM,OAAO,KAAK;GAKhB,MAAM,+DAJiC,CAAC,CAAC,SAIhB,IAAI;GAE7B,IAAI,CAAC,SACH,MAAM,IAAIC,0BACR,yBAAyB,IAAI,QAAQ,2DACvC;GAGF,MAAM,QAAQ,KAAK;IAAE,SAAS,IAAI;IAAS,OAAO,IAAI;IAAO,SAAS,IAAI;GAAQ,CAAU;EAC9F;CACF,CAAC;AACH;AAEA,SAAS,kBAAkB,OAAkC;CAC3D,OAAO,OAAO,UAAU,WAAW,QAAQ,MAAQC,kCAAe,KAAK;AACzE"}

package/esm/config.d.mts

@@ -0,0 +1,21 @@
+import { QueueConfig } from "./types.mjs";
+
+//#region ../queue/src/config.d.ts
+/**
+ * Set the active queue configuration. In a Warlock app the queue connector
+ * calls this at boot with `src/config/queue.ts`; scripts and tests may call
+ * it directly. Replaces (does not merge) any previous configuration.
+ */
+declare function setQueueConfig(config: QueueConfig): void;
+/**
+ * The active queue configuration. Throws {@link QueueNotConfiguredError}
+ * when none was set.
+ */
+declare function getQueueConfig(): QueueConfig;
+/** Forget the active configuration. */
+declare function resetQueueConfig(): void;
+/** The queue a job runs on when it names none. */
+declare function defaultQueueName(): string;
+//#endregion
+export { defaultQueueName, getQueueConfig, resetQueueConfig, setQueueConfig };
+//# sourceMappingURL=config.d.mts.map

package/esm/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../../../../../queue/src/config.ts"],"mappings":";;;;;AAUA;;;iBAAgB,cAAA,CAAe,MAAmB,EAAX,WAAW;AAAA;AAQlD;;;AARkD,iBAQlC,cAAA,IAAkB,WAAW;AAAA;AAAA,iBAS7B,gBAAA;;iBAKA,gBAAA"}

package/esm/config.mjs

@@ -0,0 +1,32 @@
+import { QueueNotConfiguredError } from "./errors.mjs";
+
+//#region ../queue/src/config.ts
+let activeConfig;
+/**
+* Set the active queue configuration. In a Warlock app the queue connector
+* calls this at boot with `src/config/queue.ts`; scripts and tests may call
+* it directly. Replaces (does not merge) any previous configuration.
+*/
+function setQueueConfig(config) {
+	activeConfig = config;
+}
+/**
+* The active queue configuration. Throws {@link QueueNotConfiguredError}
+* when none was set.
+*/
+function getQueueConfig() {
+	if (!activeConfig) throw new QueueNotConfiguredError();
+	return activeConfig;
+}
+/** Forget the active configuration. */
+function resetQueueConfig() {
+	activeConfig = void 0;
+}
+/** The queue a job runs on when it names none. */
+function defaultQueueName() {
+	return activeConfig?.defaultQueue ?? "default";
+}
+
+//#endregion
+export { defaultQueueName, getQueueConfig, resetQueueConfig, setQueueConfig };
+//# sourceMappingURL=config.mjs.map

package/esm/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../../../../../../queue/src/config.ts"],"sourcesContent":["import { QueueNotConfiguredError } from \"./errors\";\nimport type { QueueConfig } from \"./types\";\n\nlet activeConfig: QueueConfig | undefined;\n\n/**\n * Set the active queue configuration. In a Warlock app the queue connector\n * calls this at boot with `src/config/queue.ts`; scripts and tests may call\n * it directly. Replaces (does not merge) any previous configuration.\n */\nexport function setQueueConfig(config: QueueConfig): void {\n  activeConfig = config;\n}\n\n/**\n * The active queue configuration. Throws {@link QueueNotConfiguredError}\n * when none was set.\n */\nexport function getQueueConfig(): QueueConfig {\n  if (!activeConfig) {\n    throw new QueueNotConfiguredError();\n  }\n\n  return activeConfig;\n}\n\n/** Forget the active configuration. */\nexport function resetQueueConfig(): void {\n  activeConfig = undefined;\n}\n\n/** The queue a job runs on when it names none. */\nexport function defaultQueueName(): string {\n  return activeConfig?.defaultQueue ?? \"default\";\n}\n"],"mappings":";;;AAGA,IAAI;;;;;;AAOJ,SAAgB,eAAe,QAA2B;CACxD,eAAe;AACjB;;;;;AAMA,SAAgB,iBAA8B;CAC5C,IAAI,CAAC,cACH,MAAM,IAAI,wBAAwB;CAGpC,OAAO;AACT;;AAGA,SAAgB,mBAAyB;CACvC,eAAe;AACjB;;AAGA,SAAgB,mBAA2B;CACzC,OAAO,cAAc,gBAAgB;AACvC"}

package/esm/dashboard.d.mts

@@ -0,0 +1,47 @@
+//#region ../queue/src/dashboard.d.ts
+/**
+ * The part of a Fastify instance the dashboard needs. Warlock's HTTP server
+ * (`getHttpServer()` from `@warlock.js/core`) satisfies it.
+ */
+type DashboardServer = {
+  register(plugin: never, options: {
+    prefix: string;
+  }): unknown;
+};
+type QueueDashboardOptions = {
+  /** URL prefix the dashboard is mounted on. Default `"/admin/queues"`. */basePath?: string; /** Queues to show. Default: every queue with a defined job, plus the default queue. */
+  queues?: string[];
+};
+type BullBoardModules = {
+  createBullBoard: (options: {
+    queues: unknown[];
+    serverAdapter: unknown;
+  }) => unknown;
+  BullMQAdapter: new (queue: unknown) => unknown;
+  FastifyAdapter: new () => {
+    setBasePath(path: string): unknown;
+    registerPlugin(): unknown;
+  };
+};
+/**
+ * Mount the bull-board failed/active/delayed job UI on Warlock's Fastify
+ * server. Requires the optional packages `@bull-board/api` and
+ * `@bull-board/fastify`; they are loaded only when this is called, and a
+ * missing one throws {@link QueueDashboardDependencyError}.
+ *
+ * Call it before the HTTP server starts listening, and put it behind your
+ * own authentication — the dashboard can retry and delete jobs.
+ *
+ * @example
+ * import { getHttpServer } from "@warlock.js/core";
+ * await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+ */
+declare function queueDashboard(server: DashboardServer, options?: QueueDashboardOptions): Promise<void>;
+/**
+ * Load the optional bull-board packages. Exported for tests of the missing
+ * dependency path; `importer` defaults to a real dynamic import.
+ */
+declare function loadBullBoard(importer?: (specifier: string) => Promise<Record<string, unknown>>): Promise<BullBoardModules>;
+//#endregion
+export { DashboardServer, QueueDashboardOptions, loadBullBoard, queueDashboard };
+//# sourceMappingURL=dashboard.d.mts.map

package/esm/dashboard.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.mts","names":[],"sources":["../../../../../../queue/src/dashboard.ts"],"mappings":";;AASA;;;KAAY,eAAA;EACV,QAAA,CAAS,MAAA,SAAe,OAAA;IAAW,MAAA;EAAA;AAAA;AAAA,KAGzB,qBAAA;EAHyC,yEAKnD,QAAA,WAF+B;EAI/B,MAAM;AAAA;AAAA,KAGH,gBAAA;EACH,eAAA,GAAkB,OAAA;IAAW,MAAA;IAAmB,aAAA;EAAA;EAChD,aAAA,OAAoB,KAAA;EACpB,cAAA;IACE,WAAA,CAAY,IAAA;IACZ,cAAA;EAAA;AAAA;;;;;;AAAc;AAiBlB;;;;;;;iBAAsB,cAAA,CACpB,MAAA,EAAQ,eAAA,EACR,OAAA,GAAS,qBAAA,GACR,OAAA;;;;;iBAqBmB,aAAA,CACpB,QAAA,IAAW,SAAA,aAAsB,OAAA,CAAQ,MAAA,qBACxC,OAAA,CAAQ,gBAAA"}

package/esm/dashboard.mjs

@@ -0,0 +1,61 @@
+import { QueueDashboardDependencyError } from "./errors.mjs";
+import { defaultQueueName } from "./config.mjs";
+import { queueOf, registeredJobs } from "./job-registry.mjs";
+import { getQueue } from "./queue-manager.mjs";
+
+//#region ../queue/src/dashboard.ts
+/**
+* Mount the bull-board failed/active/delayed job UI on Warlock's Fastify
+* server. Requires the optional packages `@bull-board/api` and
+* `@bull-board/fastify`; they are loaded only when this is called, and a
+* missing one throws {@link QueueDashboardDependencyError}.
+*
+* Call it before the HTTP server starts listening, and put it behind your
+* own authentication — the dashboard can retry and delete jobs.
+*
+* @example
+* import { getHttpServer } from "@warlock.js/core";
+* await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+*/
+async function queueDashboard(server, options = {}) {
+	const basePath = options.basePath ?? "/admin/queues";
+	const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();
+	const queueNames = options.queues ?? [...new Set([defaultQueueName(), ...registeredJobs().map((job) => queueOf(job))])];
+	const serverAdapter = new FastifyAdapter();
+	serverAdapter.setBasePath(basePath);
+	createBullBoard({
+		queues: queueNames.map((name) => new BullMQAdapter(getQueue(name))),
+		serverAdapter
+	});
+	await server.register(serverAdapter.registerPlugin(), { prefix: basePath });
+}
+/**
+* Load the optional bull-board packages. Exported for tests of the missing
+* dependency path; `importer` defaults to a real dynamic import.
+*/
+async function loadBullBoard(importer = (specifier) => import(specifier)) {
+	const api = await importOptional(importer, "@bull-board/api");
+	const adapter = await importOptional(importer, "@bull-board/api/bullMQAdapter");
+	const fastify = await importOptional(importer, "@bull-board/fastify");
+	return {
+		createBullBoard: api.createBullBoard,
+		BullMQAdapter: adapter.BullMQAdapter,
+		FastifyAdapter: fastify.FastifyAdapter
+	};
+}
+async function importOptional(importer, specifier) {
+	try {
+		return await importer(specifier);
+	} catch (error) {
+		if (isModuleNotFound(error)) throw new QueueDashboardDependencyError(specifier.split("/").slice(0, 2).join("/"));
+		throw error;
+	}
+}
+function isModuleNotFound(error) {
+	const code = error?.code;
+	return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+
+//#endregion
+export { loadBullBoard, queueDashboard };
+//# sourceMappingURL=dashboard.mjs.map

package/esm/dashboard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.mjs","names":[],"sources":["../../../../../../queue/src/dashboard.ts"],"sourcesContent":["import { defaultQueueName } from \"./config\";\nimport { QueueDashboardDependencyError } from \"./errors\";\nimport { queueOf, registeredJobs } from \"./job-registry\";\nimport { getQueue } from \"./queue-manager\";\n\n/**\n * The part of a Fastify instance the dashboard needs. Warlock's HTTP server\n * (`getHttpServer()` from `@warlock.js/core`) satisfies it.\n */\nexport type DashboardServer = {\n  register(plugin: never, options: { prefix: string }): unknown;\n};\n\nexport type QueueDashboardOptions = {\n  /** URL prefix the dashboard is mounted on. Default `\"/admin/queues\"`. */\n  basePath?: string;\n  /** Queues to show. Default: every queue with a defined job, plus the default queue. */\n  queues?: string[];\n};\n\ntype BullBoardModules = {\n  createBullBoard: (options: { queues: unknown[]; serverAdapter: unknown }) => unknown;\n  BullMQAdapter: new (queue: unknown) => unknown;\n  FastifyAdapter: new () => {\n    setBasePath(path: string): unknown;\n    registerPlugin(): unknown;\n  };\n};\n\n/**\n * Mount the bull-board failed/active/delayed job UI on Warlock's Fastify\n * server. Requires the optional packages `@bull-board/api` and\n * `@bull-board/fastify`; they are loaded only when this is called, and a\n * missing one throws {@link QueueDashboardDependencyError}.\n *\n * Call it before the HTTP server starts listening, and put it behind your\n * own authentication — the dashboard can retry and delete jobs.\n *\n * @example\n * import { getHttpServer } from \"@warlock.js/core\";\n * await queueDashboard(getHttpServer(), { basePath: \"/admin/queues\" });\n */\nexport async function queueDashboard(\n  server: DashboardServer,\n  options: QueueDashboardOptions = {},\n): Promise<void> {\n  const basePath = options.basePath ?? \"/admin/queues\";\n  const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();\n  const queueNames =\n    options.queues ?? [...new Set([defaultQueueName(), ...registeredJobs().map((job) => queueOf(job))])];\n\n  const serverAdapter = new FastifyAdapter();\n  serverAdapter.setBasePath(basePath);\n\n  createBullBoard({\n    queues: queueNames.map((name) => new BullMQAdapter(getQueue(name))),\n    serverAdapter,\n  });\n\n  await server.register(serverAdapter.registerPlugin() as never, { prefix: basePath });\n}\n\n/**\n * Load the optional bull-board packages. Exported for tests of the missing\n * dependency path; `importer` defaults to a real dynamic import.\n */\nexport async function loadBullBoard(\n  importer: (specifier: string) => Promise<Record<string, unknown>> = (specifier) => import(specifier),\n): Promise<BullBoardModules> {\n  const api = await importOptional(importer, \"@bull-board/api\");\n  const adapter = await importOptional(importer, \"@bull-board/api/bullMQAdapter\");\n  const fastify = await importOptional(importer, \"@bull-board/fastify\");\n\n  return {\n    createBullBoard: api.createBullBoard as BullBoardModules[\"createBullBoard\"],\n    BullMQAdapter: adapter.BullMQAdapter as BullBoardModules[\"BullMQAdapter\"],\n    FastifyAdapter: fastify.FastifyAdapter as BullBoardModules[\"FastifyAdapter\"],\n  };\n}\n\nasync function importOptional(\n  importer: (specifier: string) => Promise<Record<string, unknown>>,\n  specifier: string,\n): Promise<Record<string, unknown>> {\n  try {\n    return await importer(specifier);\n  } catch (error) {\n    if (isModuleNotFound(error)) {\n      throw new QueueDashboardDependencyError(specifier.split(\"/\").slice(0, 2).join(\"/\"));\n    }\n\n    throw error;\n  }\n}\n\nfunction isModuleNotFound(error: unknown): boolean {\n  const code = (error as { code?: unknown } | undefined)?.code;\n\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA0CA,eAAsB,eACpB,QACA,UAAiC,CAAC,GACnB;CACf,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,EAAE,iBAAiB,eAAe,mBAAmB,MAAM,cAAc;CAC/E,MAAM,aACJ,QAAQ,UAAU,CAAC,GAAG,IAAI,IAAI,CAAC,iBAAiB,GAAG,GAAG,eAAe,CAAC,CAAC,KAAK,QAAQ,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;CAErG,MAAM,gBAAgB,IAAI,eAAe;CACzC,cAAc,YAAY,QAAQ;CAElC,gBAAgB;EACd,QAAQ,WAAW,KAAK,SAAS,IAAI,cAAc,SAAS,IAAI,CAAC,CAAC;EAClE;CACF,CAAC;CAED,MAAM,OAAO,SAAS,cAAc,eAAe,GAAY,EAAE,QAAQ,SAAS,CAAC;AACrF;;;;;AAMA,eAAsB,cACpB,YAAqE,cAAc,OAAO,YAC/D;CAC3B,MAAM,MAAM,MAAM,eAAe,UAAU,iBAAiB;CAC5D,MAAM,UAAU,MAAM,eAAe,UAAU,+BAA+B;CAC9E,MAAM,UAAU,MAAM,eAAe,UAAU,qBAAqB;CAEpE,OAAO;EACL,iBAAiB,IAAI;EACrB,eAAe,QAAQ;EACvB,gBAAgB,QAAQ;CAC1B;AACF;AAEA,eAAe,eACb,UACA,WACkC;CAClC,IAAI;EACF,OAAO,MAAM,SAAS,SAAS;CACjC,SAAS,OAAO;EACd,IAAI,iBAAiB,KAAK,GACxB,MAAM,IAAI,8BAA8B,UAAU,MAAM,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;EAGpF,MAAM;CACR;AACF;AAEA,SAAS,iBAAiB,OAAyB;CACjD,MAAM,OAAQ,OAA0C;CAExD,OAAO,SAAS,0BAA0B,SAAS;AACrD"}

package/esm/define-job.d.mts

@@ -0,0 +1,24 @@
+import { JobDefinition, QueueJob } from "./types.mjs";
+//#region ../queue/src/define-job.d.ts
+/**
+ * Define a background job.
+ *
+ * The definition is registered by name so any worker in the process can run
+ * it; the returned object dispatches it with a typed payload.
+ *
+ * @example
+ * export const sendInvoice = defineJob({
+ *   name: "invoices.send",
+ *   attempts: 5,
+ *   backoff: { type: "exponential", delay: 2000 },
+ *   async handle(payload: { invoiceId: string }, ctx) {
+ *     await ctx.progress(50);
+ *   },
+ * });
+ *
+ * await sendInvoice.dispatch({ invoiceId: "42" }, { delay: "10m", priority: 1 });
+ */
+declare function defineJob<TPayload, TResult = unknown>(definition: JobDefinition<TPayload, TResult>): QueueJob<TPayload, TResult>;
+//#endregion
+export { defineJob };
+//# sourceMappingURL=define-job.d.mts.map

package/esm/define-job.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-job.d.mts","names":[],"sources":["../../../../../../queue/src/define-job.ts"],"mappings":";;;;AAkCA;;;;;;;;;;;;;;;;iBAAgB,SAAA,8BACd,UAAA,EAAY,aAAA,CAAc,QAAA,EAAU,OAAA,IACnC,QAAA,CAAS,QAAA,EAAU,OAAA"}

package/esm/define-job.mjs

@@ -0,0 +1,102 @@
+import { InvalidJobDefinitionError } from "./errors.mjs";
+import { getQueueConfig } from "./config.mjs";
+import { queueOf, registerJob } from "./job-registry.mjs";
+import { getQueue } from "./queue-manager.mjs";
+import { toMilliseconds } from "./duration.mjs";
+
+//#region ../queue/src/define-job.ts
+/**
+* Define a background job.
+*
+* The definition is registered by name so any worker in the process can run
+* it; the returned object dispatches it with a typed payload.
+*
+* @example
+* export const sendInvoice = defineJob({
+*   name: "invoices.send",
+*   attempts: 5,
+*   backoff: { type: "exponential", delay: 2000 },
+*   async handle(payload: { invoiceId: string }, ctx) {
+*     await ctx.progress(50);
+*   },
+* });
+*
+* await sendInvoice.dispatch({ invoiceId: "42" }, { delay: "10m", priority: 1 });
+*/
+function defineJob(definition) {
+	assertValidDefinition(definition);
+	registerJob(definition);
+	return {
+		name: definition.name,
+		get queue() {
+			return queueOf(definition);
+		},
+		async dispatch(payload, options = {}) {
+			const queueName = queueOf(definition);
+			const job = await getQueue(queueName).add(definition.name, payload, toBullJobOptions(definition, options));
+			return {
+				id: String(job.id),
+				name: definition.name,
+				queue: queueName
+			};
+		},
+		async find(id) {
+			const job = await getQueue(queueOf(definition)).getJob(id);
+			if (!job || job.name !== definition.name) return;
+			return toSnapshot(job);
+		}
+	};
+}
+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}.`);
+}
+/**
+* Merge app defaults < job definition < dispatch options into BullMQ's shape.
+*/
+function toBullJobOptions(definition, options) {
+	const defaults = getQueueConfig().defaultJobOptions ?? {};
+	const attempts = options.attempts ?? definition.attempts ?? defaults.attempts;
+	const backoff = options.backoff ?? definition.backoff ?? defaults.backoff;
+	const removeOnComplete = definition.removeOnComplete ?? defaults.removeOnComplete;
+	const removeOnFail = definition.removeOnFail ?? defaults.removeOnFail;
+	const bullOptions = {};
+	if (attempts !== void 0) bullOptions.attempts = attempts;
+	if (backoff !== void 0) bullOptions.backoff = toBullBackoff(backoff);
+	if (removeOnComplete !== void 0) bullOptions.removeOnComplete = removeOnComplete;
+	if (removeOnFail !== void 0) bullOptions.removeOnFail = removeOnFail;
+	if (options.delay !== void 0) bullOptions.delay = toMilliseconds(options.delay);
+	if (options.priority !== void 0) bullOptions.priority = options.priority;
+	if (options.jobId !== void 0) bullOptions.jobId = options.jobId;
+	return bullOptions;
+}
+function toBullBackoff(backoff) {
+	return typeof backoff === "number" ? {
+		type: "fixed",
+		delay: backoff
+	} : backoff;
+}
+/**
+* A plain view of a BullMQ job.
+*/
+async function toSnapshot(job) {
+	const state = await job.getState();
+	return {
+		id: String(job.id),
+		name: job.name,
+		queue: job.queueName,
+		state,
+		payload: job.data,
+		progress: job.progress,
+		attemptsMade: job.attemptsMade,
+		result: job.returnvalue,
+		failedReason: job.failedReason || void 0,
+		createdAt: new Date(job.timestamp),
+		finishedAt: job.finishedOn ? new Date(job.finishedOn) : void 0
+	};
+}
+
+//#endregion
+export { defineJob };
+//# sourceMappingURL=define-job.mjs.map

package/esm/define-job.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-job.mjs","names":[],"sources":["../../../../../../queue/src/define-job.ts"],"sourcesContent":["import type { Job, JobsOptions } from \"bullmq\";\nimport { getQueueConfig } from \"./config\";\nimport { toMilliseconds } from \"./duration\";\nimport { InvalidJobDefinitionError } from \"./errors\";\nimport { queueOf, registerJob, type RegisteredJob } from \"./job-registry\";\nimport { getQueue } from \"./queue-manager\";\nimport type {\n  DispatchOptions,\n  JobBackoff,\n  JobDefinition,\n  JobOptions,\n  JobSnapshot,\n  JobState,\n  QueueJob,\n} from \"./types\";\n\n/**\n * Define a background job.\n *\n * The definition is registered by name so any worker in the process can run\n * it; the returned object dispatches it with a typed payload.\n *\n * @example\n * export const sendInvoice = defineJob({\n *   name: \"invoices.send\",\n *   attempts: 5,\n *   backoff: { type: \"exponential\", delay: 2000 },\n *   async handle(payload: { invoiceId: string }, ctx) {\n *     await ctx.progress(50);\n *   },\n * });\n *\n * await sendInvoice.dispatch({ invoiceId: \"42\" }, { delay: \"10m\", priority: 1 });\n */\nexport function defineJob<TPayload, TResult = unknown>(\n  definition: JobDefinition<TPayload, TResult>,\n): QueueJob<TPayload, TResult> {\n  assertValidDefinition(definition);\n  registerJob(definition as RegisteredJob);\n\n  return {\n    name: definition.name,\n    get queue() {\n      return queueOf(definition);\n    },\n    async dispatch(payload, options = {}) {\n      const queueName = queueOf(definition);\n      const job = await getQueue(queueName).add(\n        definition.name,\n        payload,\n        toBullJobOptions(definition, options),\n      );\n\n      return { id: String(job.id), name: definition.name, queue: queueName };\n    },\n    async find(id) {\n      const job = await getQueue(queueOf(definition)).getJob(id);\n\n      if (!job || job.name !== definition.name) {\n        return undefined;\n      }\n\n      return toSnapshot<TPayload, TResult>(job);\n    },\n  };\n}\n\nfunction assertValidDefinition(definition: JobDefinition<unknown, unknown>): void {\n  if (typeof definition.name !== \"string\" || definition.name.trim() === \"\") {\n    throw new InvalidJobDefinitionError(\"defineJob() requires a non-empty `name`.\");\n  }\n\n  if (typeof definition.handle !== \"function\") {\n    throw new InvalidJobDefinitionError(\n      `defineJob(\"${definition.name}\") requires a \\`handle(payload, ctx)\\` function.`,\n    );\n  }\n\n  if (definition.attempts !== undefined && !(Number.isInteger(definition.attempts) && definition.attempts >= 1)) {\n    throw new InvalidJobDefinitionError(\n      `defineJob(\"${definition.name}\"): \\`attempts\\` must be an integer >= 1, got ${definition.attempts}.`,\n    );\n  }\n}\n\n/**\n * Merge app defaults < job definition < dispatch options into BullMQ's shape.\n */\nfunction toBullJobOptions(definition: JobOptions, options: DispatchOptions): JobsOptions {\n  const defaults = getQueueConfig().defaultJobOptions ?? {};\n  const attempts = options.attempts ?? definition.attempts ?? defaults.attempts;\n  const backoff = options.backoff ?? definition.backoff ?? defaults.backoff;\n  const removeOnComplete = definition.removeOnComplete ?? defaults.removeOnComplete;\n  const removeOnFail = definition.removeOnFail ?? defaults.removeOnFail;\n\n  const bullOptions: JobsOptions = {};\n\n  if (attempts !== undefined) bullOptions.attempts = attempts;\n  if (backoff !== undefined) bullOptions.backoff = toBullBackoff(backoff);\n  if (removeOnComplete !== undefined) bullOptions.removeOnComplete = removeOnComplete;\n  if (removeOnFail !== undefined) bullOptions.removeOnFail = removeOnFail;\n  if (options.delay !== undefined) bullOptions.delay = toMilliseconds(options.delay);\n  if (options.priority !== undefined) bullOptions.priority = options.priority;\n  if (options.jobId !== undefined) bullOptions.jobId = options.jobId;\n\n  return bullOptions;\n}\n\nfunction toBullBackoff(backoff: JobBackoff): JobsOptions[\"backoff\"] {\n  return typeof backoff === \"number\" ? { type: \"fixed\", delay: backoff } : backoff;\n}\n\n/**\n * A plain view of a BullMQ job.\n */\nexport async function toSnapshot<TPayload, TResult>(\n  job: Job,\n): Promise<JobSnapshot<TPayload, TResult>> {\n  const state = (await job.getState()) as JobState;\n\n  return {\n    id: String(job.id),\n    name: job.name,\n    queue: job.queueName,\n    state,\n    payload: job.data as TPayload,\n    progress: job.progress as JobSnapshot[\"progress\"],\n    attemptsMade: job.attemptsMade,\n    result: job.returnvalue as TResult | undefined,\n    failedReason: job.failedReason || undefined,\n    createdAt: new Date(job.timestamp),\n    finishedAt: job.finishedOn ? new Date(job.finishedOn) : undefined,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,UACd,YAC6B;CAC7B,sBAAsB,UAAU;CAChC,YAAY,UAA2B;CAEvC,OAAO;EACL,MAAM,WAAW;EACjB,IAAI,QAAQ;GACV,OAAO,QAAQ,UAAU;EAC3B;EACA,MAAM,SAAS,SAAS,UAAU,CAAC,GAAG;GACpC,MAAM,YAAY,QAAQ,UAAU;GACpC,MAAM,MAAM,MAAM,SAAS,SAAS,CAAC,CAAC,IACpC,WAAW,MACX,SACA,iBAAiB,YAAY,OAAO,CACtC;GAEA,OAAO;IAAE,IAAI,OAAO,IAAI,EAAE;IAAG,MAAM,WAAW;IAAM,OAAO;GAAU;EACvE;EACA,MAAM,KAAK,IAAI;GACb,MAAM,MAAM,MAAM,SAAS,QAAQ,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE;GAEzD,IAAI,CAAC,OAAO,IAAI,SAAS,WAAW,MAClC;GAGF,OAAO,WAA8B,GAAG;EAC1C;CACF;AACF;AAEA,SAAS,sBAAsB,YAAmD;CAChF,IAAI,OAAO,WAAW,SAAS,YAAY,WAAW,KAAK,KAAK,MAAM,IACpE,MAAM,IAAI,0BAA0B,0CAA0C;CAGhF,IAAI,OAAO,WAAW,WAAW,YAC/B,MAAM,IAAI,0BACR,cAAc,WAAW,KAAK,iDAChC;CAGF,IAAI,WAAW,aAAa,UAAa,EAAE,OAAO,UAAU,WAAW,QAAQ,KAAK,WAAW,YAAY,IACzG,MAAM,IAAI,0BACR,cAAc,WAAW,KAAK,gDAAgD,WAAW,SAAS,EACpG;AAEJ;;;;AAKA,SAAS,iBAAiB,YAAwB,SAAuC;CACvF,MAAM,WAAW,eAAe,CAAC,CAAC,qBAAqB,CAAC;CACxD,MAAM,WAAW,QAAQ,YAAY,WAAW,YAAY,SAAS;CACrE,MAAM,UAAU,QAAQ,WAAW,WAAW,WAAW,SAAS;CAClE,MAAM,mBAAmB,WAAW,oBAAoB,SAAS;CACjE,MAAM,eAAe,WAAW,gBAAgB,SAAS;CAEzD,MAAM,cAA2B,CAAC;CAElC,IAAI,aAAa,QAAW,YAAY,WAAW;CACnD,IAAI,YAAY,QAAW,YAAY,UAAU,cAAc,OAAO;CACtE,IAAI,qBAAqB,QAAW,YAAY,mBAAmB;CACnE,IAAI,iBAAiB,QAAW,YAAY,eAAe;CAC3D,IAAI,QAAQ,UAAU,QAAW,YAAY,QAAQ,eAAe,QAAQ,KAAK;CACjF,IAAI,QAAQ,aAAa,QAAW,YAAY,WAAW,QAAQ;CACnE,IAAI,QAAQ,UAAU,QAAW,YAAY,QAAQ,QAAQ;CAE7D,OAAO;AACT;AAEA,SAAS,cAAc,SAA6C;CAClE,OAAO,OAAO,YAAY,WAAW;EAAE,MAAM;EAAS,OAAO;CAAQ,IAAI;AAC3E;;;;AAKA,eAAsB,WACpB,KACyC;CACzC,MAAM,QAAS,MAAM,IAAI,SAAS;CAElC,OAAO;EACL,IAAI,OAAO,IAAI,EAAE;EACjB,MAAM,IAAI;EACV,OAAO,IAAI;EACX;EACA,SAAS,IAAI;EACb,UAAU,IAAI;EACd,cAAc,IAAI;EAClB,QAAQ,IAAI;EACZ,cAAc,IAAI,gBAAgB;EAClC,WAAW,IAAI,KAAK,IAAI,SAAS;EACjC,YAAY,IAAI,aAAa,IAAI,KAAK,IAAI,UAAU,IAAI;CAC1D;AACF"}

package/esm/duration.d.mts

@@ -0,0 +1,11 @@
+import { Duration } from "./types.mjs";
+
+//#region ../queue/src/duration.d.ts
+/**
+ * Convert a {@link Duration} to milliseconds. Numbers are already
+ * milliseconds. Anything else is rejected loudly rather than guessed at.
+ */
+declare function toMilliseconds(value: Duration | string): number;
+//#endregion
+export { toMilliseconds };
+//# sourceMappingURL=duration.d.mts.map

package/esm/duration.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.mts","names":[],"sources":["../../../../../../queue/src/duration.ts"],"mappings":";;;;;AAiBA;;iBAAgB,cAAA,CAAe,KAAwB,EAAjB,QAAQ"}