@warlock.js/queue 5.30.0 → 5.32.0

package/esm/types.d.mts

@@ -1,46 +1,52 @@
 import { ConnectionOptions } from "bullmq";
 import { Middleware } from "@warlock.js/core";
-
 //#region ../../packages/queue/src/types.d.ts
 /** Units accepted in a {@link Duration} string. */
-type DurationUnit = "ms" | "s" | "m" | "h" | "d";
+export type DurationUnit = "ms" | "s" | "m" | "h" | "d";
 /**
  * A duration: milliseconds as a number, or a string such as `"500ms"`,
  * `"30s"`, `"10m"`, `"2h"`, `"1d"`.
  */
-type Duration = number | `${number}${DurationUnit}`;
+export type Duration = number | `${number}${DurationUnit}`;
 /**
  * How a failed attempt waits before the next one. A number is a fixed delay in
  * milliseconds.
  */
-type JobBackoff = number | {
-  /** `fixed` waits `delay` every time; `exponential` waits `delay * 2^(attempt - 1)`. */type: "fixed" | "exponential"; /** Base delay in milliseconds. */
+export type JobBackoff = number | {
+  /** `fixed` waits `delay` every time; `exponential` waits `delay * 2^(attempt - 1)`. */
+  type: "fixed" | "exponential";
+  /** Base delay in milliseconds. */
   delay: number;
 };
 /**
  * How many finished jobs to keep: `true` removes them immediately, `false`
  * keeps them all, a number keeps the newest N.
  */
-type JobRetention = boolean | number;
+export type JobRetention = boolean | number;
 /**
  * Options that shape how a job is retried and retained. Set app-wide in
  * `queue.defaultJobOptions`, per job in `defineJob`.
  */
-type JobOptions = {
-  /** Total attempts including the first. Default `1` (no retry). */attempts?: number; /** Wait between attempts. */
-  backoff?: JobBackoff; /** Retention for completed jobs. Default keeps them. */
-  removeOnComplete?: JobRetention; /** Retention for failed jobs. Default keeps them, so `failedJobs()` can list them. */
+export type JobOptions = {
+  /** Total attempts including the first. Default `1` (no retry). */
+  attempts?: number;
+  /** Wait between attempts. */
+  backoff?: JobBackoff;
+  /** Retention for completed jobs. Default keeps them. */
+  removeOnComplete?: JobRetention;
+  /** Retention for failed jobs. Default keeps them, so `failedJobs()` can list them. */
   removeOnFail?: JobRetention;
 };
 /**
  * In-process worker settings.
  */
-type QueueWorkersConfig = {
+export type QueueWorkersConfig = {
   /**
    * Start workers in this process. Default `true`. Set `false` for a process
    * that only dispatches jobs while another process consumes them.
    */
-  enabled?: boolean; /** Jobs processed in parallel per queue. Default `1`. */
+  enabled?: boolean;
+  /** Jobs processed in parallel per queue. Default `1`. */
   concurrency?: number;
   /**
    * How long shutdown waits for active jobs before force-closing the workers,
@@ -53,8 +59,10 @@ type QueueWorkersConfig = {
  * `enabled` is `true`. Equivalent to calling `queueDashboard()` yourself at
  * boot, driven by config instead — see `warlock add bull-board`.
  */
-type QueueDashboardConfig = {
-  /** Mount the dashboard at boot. Default `false`. */enabled?: boolean; /** URL path the dashboard is mounted on. Default `"/admin/queues"`. */
+export type QueueDashboardConfig = {
+  /** Mount the dashboard at boot. Default `false`. */
+  enabled?: boolean;
+  /** URL path the dashboard is mounted on. Default `"/admin/queues"`. */
   path?: string;
   /**
    * Run before every dashboard route — this is how the dashboard is guarded.
@@ -66,47 +74,65 @@ type QueueDashboardConfig = {
 /**
  * The `queue` configuration key — `src/config/queue.ts`.
  */
-type QueueConfig = {
+export type QueueConfig = {
   /**
    * Redis connection. Any BullMQ connection option: `{ host, port, password, db }`,
    * `{ url }`, or an ioredis instance.
    */
-  connection: ConnectionOptions; /** Redis key prefix for every queue. Default `"warlock"`. */
-  prefix?: string; /** Queue name used when a job does not name one. Default `"default"`. */
-  defaultQueue?: string; /** Defaults merged under every job's own options. */
-  defaultJobOptions?: JobOptions; /** In-process workers. */
-  workers?: QueueWorkersConfig; /** The bull-board job dashboard. */
+  connection: ConnectionOptions;
+  /** Redis key prefix for every queue. Default `"warlock"`. */
+  prefix?: string;
+  /** Queue name used when a job does not name one. Default `"default"`. */
+  defaultQueue?: string;
+  /** Defaults merged under every job's own options. */
+  defaultJobOptions?: JobOptions;
+  /** In-process workers. */
+  workers?: QueueWorkersConfig;
+  /** The bull-board job dashboard. */
   dashboard?: QueueDashboardConfig;
 };
 /** A progress value: a number (e.g. a percentage) or a JSON object. */
-type JobProgress = number | Record<string, unknown>;
+export type JobProgress = number | Record<string, unknown>;
 /**
  * What a job handler receives beside its payload.
  */
-type JobContext = {
-  /** The job id. */id: string; /** The job name given to `defineJob`. */
-  name: string; /** The queue the job runs on. */
-  queue: string; /** The current attempt, starting at `1`. */
-  attempt: number; /** Total attempts allowed. */
-  maxAttempts: number; /** Record progress; readable through `job.find(id)`. */
-  progress(value: JobProgress): Promise<void>; /** Append a line to the job's log. */
-  log(line: string): Promise<void>; /** State captured at dispatch by the registered queue context, if any. */
+export type JobContext = {
+  /** The job id. */
+  id: string;
+  /** The job name given to `defineJob`. */
+  name: string;
+  /** The queue the job runs on. */
+  queue: string;
+  /** The current attempt, starting at `1`. */
+  attempt: number;
+  /** Total attempts allowed. */
+  maxAttempts: number;
+  /** Record progress; readable through `job.find(id)`. */
+  progress(value: JobProgress): Promise<void>;
+  /** Append a line to the job's log. */
+  log(line: string): Promise<void>;
+  /** State captured at dispatch by the registered queue context, if any. */
   context: unknown;
 };
 /**
  * The definition passed to `defineJob`.
  */
-type JobDefinition<TPayload, TResult> = JobOptions & {
-  /** Set `false` to skip capturing the queue context for this job. */context?: false; /** Unique job name, e.g. `"invoices.send"`. */
-  name: string; /** Queue to run on. Default: `queue.defaultQueue` (`"default"`). */
-  queue?: string; /** The work. Throw to fail the attempt; the return value is stored as the job result. */
+export type JobDefinition<TPayload, TResult> = JobOptions & {
+  /** Set `false` to skip capturing the queue context for this job. */
+  context?: false;
+  /** Unique job name, e.g. `"invoices.send"`. */
+  name: string;
+  /** Queue to run on. Default: `queue.defaultQueue` (`"default"`). */
+  queue?: string;
+  /** The work. Throw to fail the attempt; the return value is stored as the job result. */
   handle(payload: TPayload, context: JobContext): Promise<TResult> | TResult;
 };
 /**
  * Per-dispatch options.
  */
-type DispatchOptions = {
-  /** Wait before the job becomes available. */delay?: Duration;
+export type DispatchOptions = {
+  /** Wait before the job becomes available. */
+  delay?: Duration;
   /**
    * Priority: `1` is the highest; larger numbers run later. Omit for no
    * priority — such jobs run ahead of every prioritized job.
@@ -116,20 +142,22 @@ type DispatchOptions = {
    * Explicit job id. Dispatching again with an id that still exists is a
    * no-op, which makes dispatch idempotent.
    */
-  jobId?: string; /** Override the job's attempts for this dispatch. */
-  attempts?: number; /** Override the job's backoff for this dispatch. */
+  jobId?: string;
+  /** Override the job's attempts for this dispatch. */
+  attempts?: number;
+  /** Override the job's backoff for this dispatch. */
   backoff?: JobBackoff;
 };
 /** What `dispatch` resolves with. */
-type DispatchedJob = {
+export type DispatchedJob = {
   id: string;
   name: string;
   queue: string;
 };
 /** A job's lifecycle state. */
-type JobState = "waiting" | "delayed" | "prioritized" | "active" | "completed" | "failed" | "waiting-children" | "unknown";
+export type JobState = "waiting" | "delayed" | "prioritized" | "active" | "completed" | "failed" | "waiting-children" | "unknown";
 /** A point-in-time view of a job. */
-type JobSnapshot<TPayload = unknown, TResult = unknown> = {
+export type JobSnapshot<TPayload = unknown, TResult = unknown> = {
   id: string;
   name: string;
   queue: string;
@@ -143,7 +171,7 @@ type JobSnapshot<TPayload = unknown, TResult = unknown> = {
   finishedAt?: Date;
 };
 /** A failed job, with the means to retry it. */
-type FailedJob<TPayload = unknown> = {
+export type FailedJob<TPayload = unknown> = {
   id: string;
   name: string;
   queue: string;
@@ -151,18 +179,20 @@ type FailedJob<TPayload = unknown> = {
   attemptsMade: number;
   failedReason: string;
   stacktrace: string[];
-  failedAt?: Date; /** Move the job back to waiting so a worker picks it up again. */
+  failedAt?: Date;
+  /** Move the job back to waiting so a worker picks it up again. */
   retry(): Promise<void>;
 };
 /**
  * A job returned by `defineJob`.
  */
-type QueueJob<TPayload, TResult = unknown> = {
+export type QueueJob<TPayload, TResult = unknown> = {
   readonly name: string;
-  readonly queue: string; /** Enqueue the job. */
-  dispatch(payload: TPayload, options?: DispatchOptions): Promise<DispatchedJob>; /** Read a job of this type by id; `undefined` when it no longer exists. */
+  readonly queue: string;
+  /** Enqueue the job. */
+  dispatch(payload: TPayload, options?: DispatchOptions): Promise<DispatchedJob>;
+  /** Read a job of this type by id; `undefined` when it no longer exists. */
   find(id: string): Promise<JobSnapshot<TPayload, TResult> | undefined>;
 };
 //#endregion
-export { DispatchOptions, DispatchedJob, Duration, DurationUnit, FailedJob, JobBackoff, JobContext, JobDefinition, JobOptions, JobProgress, JobRetention, JobSnapshot, JobState, QueueConfig, QueueDashboardConfig, QueueJob, QueueWorkersConfig };
 //# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../packages/queue/src/types.ts"],"mappings":";;;;;KAIY,YAAA;AAAZ;;;;AAAA,KAMY,QAAA,wBAAgC,YAAY;AAAxD;;;;AAAA,KAMY,UAAA;EAAA,uFAIN,IAAA;EAEA,KAAK;AAAA;AAOX;;;;AAAA,KAAY,YAAA;AAMZ;;;;AAAA,KAAY,UAAA;EAQK,kEANf,QAAA,WAM2B;EAJ3B,OAAA,GAAU,UAAA,EAAV;EAEA,gBAAA,GAAmB,YAAA,EAAnB;EAEA,YAAA,GAAe,YAAA;AAAA;;;AAAY;KAMjB,kBAAA;EAAkB;;;;EAK5B,OAAA,YAOA;EALA,WAAA;EAKe;AAQjB;;;EARE,eAAA;AAAA;;;;;AAkBuB;KAVb,oBAAA;EAgBW,oDAdrB,OAAA,YAmBY;EAjBZ,IAAA;EAyBU;;;;;EAnBV,UAAA,GAAa,UAAU;AAAA;;;;KAMb,WAAA;EAaA;;;;EARV,UAAA,EAAY,iBAAA,EAcF;EAZV,MAAA;EAEA,YAAA,WAUuC;EARvC,iBAAA,GAAoB,UAAA,EAaA;EAXpB,OAAA,GAAU,kBAAA,EAuBM;EArBhB,SAAA,GAAY,oBAAA;AAAA;;KAIF,WAAA,YAAuB,MAAM;;;;KAK7B,UAAA;EAUV,kBARA,EAAA,UAUgB;EARhB,IAAA,UAQ8B;EAN9B,KAAA,UAQI;EANJ,OAAA,UAQA;EANA,WAAA,UAMO;EAJP,QAAA,CAAS,KAAA,EAAO,WAAA,GAAc,OAAA,QAUP;EARvB,GAAA,CAAI,IAAA,WAAe,OAAA,QAQ0B;EAN7C,OAAA;AAAA;;;;KAMU,aAAA,sBAAmC,UAAA;EAQ6B,oEAN1E,OAAA,UAFkC;EAIlC,IAAA,UAFA;EAIA,KAAA;EAEA,MAAA,CAAO,OAAA,EAAS,QAAA,EAAU,OAAA,EAAS,UAAA,GAAa,OAAA,CAAQ,OAAA,IAAW,OAAA;AAAA;;;;KAMzD,eAAA;EAN8C,6CAQxD,KAAA,GAAQ,QAAA;EARkE;AAAA;AAM5E;;EAOE,QAAA;EASoB;;;;EAJpB,KAAA,WAEA;EAAA,QAAA,WAEU;EAAV,OAAA,GAAU,UAAU;AAAA;AAItB;AAAA,KAAY,aAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;AAAA;;KAIU,QAAA;AAJL;AAAA,KAeK,WAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA,EAAO,QAAA;EACP,OAAA,EAAS,QAAA;EACT,QAAA,EAAU,WAAA;EACV,YAAA;EACA,MAAA,GAAS,OAAA;EACT,YAAA;EACA,SAAA,EAAW,IAAA;EACX,UAAA,GAAa,IAAA;AAAA;;KAIH,SAAA;EACV,EAAA;EACA,IAAA;EACA,KAAA;EACA,OAAA,EAAS,QAAA;EACT,YAAA;EACA,YAAA;EACA,UAAA;EACA,QAAA,GAAW,IAAA,EAlBX;EAoBA,KAAA,IAAS,OAAA;AAAA;;;;KAMC,QAAA;EAAA,SACD,IAAA;EAAA,SACA,KAAA,UAvBE;EAyBX,QAAA,CAAS,OAAA,EAAS,QAAA,EAAU,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,aAAA,GAxBnD;EA0Bb,IAAA,CAAK,EAAA,WAAa,OAAA,CAAQ,WAAA,CAAY,QAAA,EAAU,OAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../packages/queue/src/types.ts"],"mappings":";;;;YAIY;;;;;YAMA,gCAAgC;;;;;YAMhC;;EAIN;;EAEA;;;;;;YAOM;;;;;YAMA;;EAEV;;EAEA,UAAU;;EAEV,mBAAmB;;EAEnB,eAAe;;;;;YAML;;;;;EAKV;;EAEA;;;;;EAKA;;;;;;;YAQU;;EAEV;;EAEA;;;;;;EAMA,aAAa;;;;;YAMH;;;;;EAKV,YAAY;;EAEZ;;EAEA;;EAEA,oBAAoB;;EAEpB,UAAU;;EAEV,YAAY;;;YAIF,uBAAuB;;;;YAKvB;;EAEV;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,SAAS,OAAO,cAAc;;EAE9B,IAAI,eAAe;;EAEnB;;;;;YAMU,cAAc,UAAU,WAAW;;EAE7C;;EAEA;;EAEA;;EAEA,OAAO,SAAS,UAAU,SAAS,aAAa,QAAQ,WAAW;;;;;YAMzD;;EAEV,QAAQ;;;;;EAKR;;;;;EAKA;;EAEA;;EAEA,UAAU;;;YAIA;EACV;EACA;EACA;;;YAIU;;YAWA,YAAY,oBAAoB;EAC1C;EACA;EACA;EACA,OAAO;EACP,SAAS;EACT,UAAU;EACV;EACA,SAAS;EACT;EACA,WAAW;EACX,aAAa;;;YAIH,UAAU;EACpB;EACA;EACA;EACA,SAAS;EACT;EACA;EACA;EACA,WAAW;;EAEX,SAAS;;;;;YAMC,SAAS,UAAU;WACpB;WACA;;EAET,SAAS,SAAS,UAAU,UAAU,kBAAkB,QAAQ;;EAEhE,KAAK,aAAa,QAAQ,YAAY,UAAU"}

package/llms-full.txt

@@ -71,7 +71,7 @@ Every process must use the same `prefix`, or they will not see each other's jobs
 
 ---
 name: define-jobs
-description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.'
+description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `setDispatchInterceptor`, `queueFake`, `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.'
 ---
 
 # Define and dispatch jobs
@@ -99,11 +99,14 @@ The job module must be imported by the process that runs workers — in a Warloc
 ```ts
 const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
 
-await sendInvoice.dispatch({ invoiceId: "43" }, {
-  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
-  priority: 1, // 1 runs first; larger numbers later
-  jobId: "invoice:43", // a second dispatch with a live id is ignored
-});
+await sendInvoice.dispatch(
+  { invoiceId: "43" },
+  {
+    delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
+    priority: 1, // 1 runs first; larger numbers later
+    jobId: "invoice:43", // a second dispatch with a live id is ignored
+  },
+);
 ```
 
 Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
@@ -115,6 +118,16 @@ const job = await sendInvoice.find(id);
 // { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
 ```
 
+## List the defined jobs
+
+`registeredJobs()` returns every definition `defineJob()` registered in this process, and `queueOf(definition)` the queue it runs on. Neither touches Redis; `warlock inspect --section jobs` prints the same list for a whole app.
+
+```ts
+import { queueOf, registeredJobs } from "@warlock.js/queue";
+
+const jobs = registeredJobs().map((job) => ({ name: job.name, queue: queueOf(job) }));
+```
+
 ## Carry request context into jobs
 
 ```ts
@@ -131,6 +144,23 @@ setQueueContext(
 - `defineJob({ context: false })` opts a job out.
 - Throw `UnrecoverableJobError` from a handler or `restore` to fail the job without retries.
 
+## Test dispatches without Redis
+
+In the test environment `queueFake` from `@warlock.js/core/tests` is installed by default: dispatches are recorded, not pushed, and `find()` answers from the record.
+
+```ts
+// with: import { queueFake } from "@warlock.js/core/tests";
+//       plus your job (sendInvoice) and service (placeOrderService)
+it("queues the invoice", async () => {
+  const order = await placeOrderService({ items: ["pen"] });
+
+  queueFake.assertPushed(sendInvoice, { invoiceId: order.invoiceId });
+  expect(queueFake.pushed(sendInvoice)).toHaveLength(1);
+});
+```
+
+Jobs are not run — call the handler to test it. Opt out with `tests.fakes: { queue: false }`. The seam is `setDispatchInterceptor({ dispatch, find? })`: while set, every job's `dispatch()` / `find()` goes to it instead of BullMQ; set it back to `undefined` to restore the broker.
+
 ## Rules
 
 - A job name with no handler in the worker process fails at once, without retries.
@@ -278,4 +308,3 @@ await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10
 - Deliveries run under the job name `warlock.notifications.deliver`.
 
 
-

package/llms.txt

@@ -7,7 +7,7 @@
 ## Skills
 
 - [configure-queue](@warlock.js/queue/configure-queue/SKILL.md): Configure `@warlock.js/queue`: the declarative `src/config/queue.ts` (`QueueConfig` — `connection`, `prefix`, `defaultQueue`, `defaultJobOptions`, `workers: { enabled, concurrency, shutdownTimeout }`), registering `queueConnector()` in `warlock.config.ts > connectors`, running a dispatch-only process, and graceful shutdown. Programmatic `setQueueConfig` / `startWorkers` / `closeQueue` for scripts and tests. Triggers: `QueueConfig`, `queueConnector`, `setQueueConfig`, `startWorkers`, `closeQueue`, `workers.enabled`, `shutdownTimeout`; "configure the queue", "connect BullMQ to Redis", "disable workers in the web process", "graceful shutdown of jobs". Skip: writing jobs — the `define-jobs` topic.
-- [define-jobs](@warlock.js/queue/define-jobs/SKILL.md): Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.
+- [define-jobs](@warlock.js/queue/define-jobs/SKILL.md): Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `setDispatchInterceptor`, `queueFake`, `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.
 - [manage-failed-jobs](@warlock.js/queue/manage-failed-jobs/SKILL.md): Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — the `define-jobs` topic.
 - [overview](@warlock.js/queue/overview/SKILL.md): @warlock.js/queue overview for orientation and choosing the focused skill for the task.
 - [queue-notifications](@warlock.js/queue/queue-notifications/SKILL.md): Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — the `queue-notifications` topic of the `warlock-js-notifications` skill.

package/package.json

@@ -11,8 +11,8 @@
   "peerDependencies": {
     "@bull-board/api": "^9.0.0",
     "@bull-board/fastify": "^9.0.0",
-    "@warlock.js/core": "5.30.0",
-    "@warlock.js/logger": "5.30.0"
+    "@warlock.js/core": "5.32.0",
+    "@warlock.js/logger": "5.32.0"
   },
   "peerDependenciesMeta": {
     "@bull-board/api": {
@@ -38,7 +38,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/define-jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: define-jobs
-description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.'
+description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `setDispatchInterceptor`, `queueFake`, `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — the `configure-queue` topic; failed jobs — the `manage-failed-jobs` topic.'
 ---
 
 # Define and dispatch jobs
@@ -28,11 +28,14 @@ The job module must be imported by the process that runs workers — in a Warloc
 ```ts
 const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
 
-await sendInvoice.dispatch({ invoiceId: "43" }, {
-  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
-  priority: 1, // 1 runs first; larger numbers later
-  jobId: "invoice:43", // a second dispatch with a live id is ignored
-});
+await sendInvoice.dispatch(
+  { invoiceId: "43" },
+  {
+    delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
+    priority: 1, // 1 runs first; larger numbers later
+    jobId: "invoice:43", // a second dispatch with a live id is ignored
+  },
+);
 ```
 
 Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
@@ -44,6 +47,16 @@ const job = await sendInvoice.find(id);
 // { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
 ```
 
+## List the defined jobs
+
+`registeredJobs()` returns every definition `defineJob()` registered in this process, and `queueOf(definition)` the queue it runs on. Neither touches Redis; `warlock inspect --section jobs` prints the same list for a whole app.
+
+```ts
+import { queueOf, registeredJobs } from "@warlock.js/queue";
+
+const jobs = registeredJobs().map((job) => ({ name: job.name, queue: queueOf(job) }));
+```
+
 ## Carry request context into jobs
 
 ```ts
@@ -60,6 +73,23 @@ setQueueContext(
 - `defineJob({ context: false })` opts a job out.
 - Throw `UnrecoverableJobError` from a handler or `restore` to fail the job without retries.
 
+## Test dispatches without Redis
+
+In the test environment `queueFake` from `@warlock.js/core/tests` is installed by default: dispatches are recorded, not pushed, and `find()` answers from the record.
+
+```ts
+// with: import { queueFake } from "@warlock.js/core/tests";
+//       plus your job (sendInvoice) and service (placeOrderService)
+it("queues the invoice", async () => {
+  const order = await placeOrderService({ items: ["pen"] });
+
+  queueFake.assertPushed(sendInvoice, { invoiceId: order.invoiceId });
+  expect(queueFake.pushed(sendInvoice)).toHaveLength(1);
+});
+```
+
+Jobs are not run — call the handler to test it. Opt out with `tests.fakes: { queue: false }`. The seam is `setDispatchInterceptor({ dispatch, find? })`: while set, every job's `dispatch()` / `find()` goes to it instead of BullMQ; set it back to `undefined` to restore the broker.
+
 ## Rules
 
 - A job name with no handler in the worker process fails at once, without retries.

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
-description: "Durable background jobs on BullMQ + Redis: retries, delays, priorities, workers, failed-job recovery. Exports `defineJob`, `queueConnector`, `startWorkers`, `closeQueue`, `getQueue`, `failedJobs`, `retryFailedJob`, `mountQueueDashboard`, `QueueConfig`, `QueueJob`. Use for: \"run this in the background\", \"retry a failed job\", \"delay a job\", \"survive restarts\", \"job dashboard\". Not this package: cron or recurring schedules → @warlock.js/scheduler; broker pub/sub messaging → @warlock.js/herald; core `Queue` is an in-memory batcher."
+description: 'Durable background jobs on BullMQ + Redis: retries, delays, priorities, workers, failed-job recovery. Exports `defineJob`, `queueConnector`, `startWorkers`, `closeQueue`, `getQueue`, `failedJobs`, `retryFailedJob`, `mountQueueDashboard`, `QueueConfig`, `QueueJob`. Use for: "run this in the background", "retry a failed job", "delay a job", "survive restarts", "job dashboard". Not this package: cron or recurring schedules → @warlock.js/scheduler; broker pub/sub messaging → @warlock.js/herald; core `Queue` is an in-memory batcher.'
 ---
+
 # @warlock.js/queue
 
 Jobs are stored in Redis (required; not bundled), retried on failure, and run by workers, in the app process by default. `defineJob({ name, handle })` registers a handler and returns a typed job; `job.dispatch(payload, options)` enqueues it. Any process with the same definition and a worker can run it. Server-only.
 
 ## The 80% path
+
 1. Orient with `overview.md`.
 2. Configure `src/config/queue.ts` and register `queueConnector()`: `configure-queue.md`.
 3. Define and dispatch jobs (attempts, backoff, delay, priority, progress): `define-jobs.md`.
@@ -13,6 +15,7 @@ Jobs are stored in Redis (required; not bundled), retried on failure, and run by
 5. Back `@warlock.js/notifications` `.queue()` with BullMQ: `queue-notifications.md`.
 
 ## Conventions and pitfalls
+
 - Job names are the routing key; a job with no matching `defineJob` in the worker process cannot run.
 - Handlers must be idempotent: retries re-run them.
 - Shutdown lets active jobs finish up to `workers.shutdownTimeout`, then closes connections.

package/skills/queue-notifications/SKILL.md

@@ -32,4 +32,3 @@ await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10
 - `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
 - Channel not configured in the worker → fails at once, no retries.
 - Deliveries run under the job name `warlock.notifications.deliver`.
-