@basaltkit/queue 1.4.1 → 2.0.0

package/README.md

@@ -20,15 +20,20 @@ This module gives you three things you'd normally have to build by hand:
 
 1. **Declarative, type-safe jobs** — you define each job once with `defineJob` (name, validation schema, number of attempts) and then call `MyJob.dispatch(data)` anywhere in the application. Data is validated with Zod *before* entering the queue, so invalid data never reaches the worker.
 2. **Context propagation** — information from the current request (`requestId`, `tenantId`, `userId`, etc.) automatically travels along with the job and is restored inside the worker. Your logs and tenant checks work in the worker the same way they did in the HTTP request.
-3. **Two interchangeable drivers** — in production, use **BullMQ** (over Redis, with real retries and delays); in development and tests, use the **sync** driver, which runs the job immediately, in the same process, without needing Redis installed.
+3. **Interchangeable drivers** — in production, use **BullMQ** (over Redis, with real retries and delays), or RabbitMQ/SQS/Kafka through a driver package; in development and tests, use the **sync** driver, which runs the job immediately, in the same process, without needing Redis installed. The core itself is backend-neutral: it depends on no broker client.
 
 ## Installation
 
 ```bash
 pnpm add @basaltkit/queue
+
+# only if you use the BullMQ/Redis driver (`connection` or `BullmqQueueDriver`):
+pnpm add bullmq
 ```
 
-The package depends on `@basaltkit/core` and `@basaltkit/events` (installed automatically). For production you also need an accessible **Redis** server (BullMQ stores the queues there). For development and tests you need nothing.
+The package depends on `@basaltkit/core` and `@basaltkit/events` (installed automatically). For development and tests you need nothing else — the sync driver has no dependencies.
+
+`bullmq` is an **optional peer dependency**, not a dependency: `@basaltkit/queue` is the driver-agnostic core, so an application running on [RabbitMQ](https://www.npmjs.com/package/@basaltkit/queue-rabbitmq), [SQS](https://www.npmjs.com/package/@basaltkit/queue-sqs), [Kafka](https://www.npmjs.com/package/@basaltkit/queue-kafka) or the sync driver never installs (or loads) BullMQ and its ioredis transitive weight. Install `bullmq` yourself the moment you pass `connection` or construct `BullmqQueueDriver`; forget it and boot fails with a `MissingQueueDriverPackageError` telling you exactly that. For production with BullMQ you also need an accessible **Redis** server (it stores the queues there).
 
 ## Get started in 5 minutes
 
@@ -195,17 +200,35 @@ If a job reaches a worker that hasn't registered it, `UnknownJobError` is thrown
 
 ### CLI commands (`basalt queue:*`)
 
-Registering `queuePlugin` also wires three CLI commands (run via the `@basaltkit/cli` runner):
+Registering `queuePlugin` also wires four CLI commands (run via the `@basaltkit/cli` runner):
 
 ```bash
 basalt queue:work --queue=default --concurrency=5   # run a worker until Ctrl+C
 basalt queue:stats --queue=billing                  # waiting/active/completed/failed/delayed
 basalt queue:retry --queue=billing --limit=100      # re-enqueue failed jobs
+basalt queue:jobs  --queue=billing --states=failed  # list individual jobs
+```
+
+`queue:jobs` flags:
+
+| Flag | Default | Description |
+|---|---|---|
+| `--queue` | `default` | Queue to inspect. |
+| `--states` | `completed,failed,waiting,active` | Comma-separated states from `waiting`, `active`, `completed`, `failed`, `delayed`. An unknown state is rejected with the valid list, never silently dropped. |
+| `--limit` | `20` | Maximum rows in **total** (newest first), capped at `1000`. |
+| `--payload` | off | Also print each job's payload (truncated). **Off by default: payloads can contain personal data.** |
+
+```
+id    name           state      attempts  age
+1042  email.welcome  completed  1         3s
+1041  email.welcome  failed     3         2m
+2 job(s) on "billing" (completed, failed, waiting, active, limit 20). Payloads hidden — add --payload to include them.
 ```
 
-`queue:stats` and `queue:retry` need a driver that can introspect job state — the
-**BullMQ** driver (a Redis `connection`). With the inline `sync` driver they
-report the operation as unsupported (it keeps no job state), rather than guessing.
+`queue:stats`, `queue:retry` and `queue:jobs` need a driver that can introspect job
+state — the **BullMQ** driver (a Redis `connection`). With the inline `sync` driver,
+or a broker driver that cannot read a job without consuming it (RabbitMQ, SQS, Kafka),
+they report the operation as unsupported rather than guessing.
 
 ### Manual use without a plugin (e.g. in tests)
 
@@ -300,6 +323,7 @@ const manager = app.container.get(QUEUE) // get the QueueManager from the contai
 | `work` | `(queue = 'default', { concurrency? }?) => void` | Starts a worker for the queue (no-op on the sync driver). |
 | `stats` | `(queue = 'default') => Promise<QueueStats \| undefined>` | Job counts per state, or `undefined` when the driver can't introspect (sync). |
 | `retryFailed` | `(queue = 'default', { limit? }?) => Promise<number \| undefined>` | Re-enqueues failed jobs; returns the count, or `undefined` when the driver doesn't support it. |
+| `list` | `(queue = 'default', options?: ListJobsOptions) => Promise<JobSummary[] \| undefined>` | Lists individual jobs, newest first, payload already unwrapped from the dispatch envelope. `undefined` when the driver can't list. |
 | `close` | `() => Promise<void>` | Closes workers and connections. |
 
 `QueueManagerOptions`:
@@ -311,6 +335,60 @@ const manager = app.container.get(QUEUE) // get the QueueManager from the contai
 | `removeOnComplete` | `JobRetention` | driver default | Default retention for completed jobs. |
 | `removeOnFail` | `JobRetention` | driver default | Default retention for failed jobs. |
 
+### Listing jobs — `manager.list(queue?, options?)`
+
+The supported way to see *which* jobs are on a queue, without reaching into the
+broker's own client (which re-couples your app to one backend):
+
+```ts
+import { QUEUE } from '@basaltkit/queue'
+
+const jobs = await app.container.get(QUEUE).list('billing', { states: ['failed'], limit: 10 })
+if (!jobs) {
+  // the active driver cannot list — handle it, don't assume an empty queue
+} else {
+  for (const job of jobs) console.log(job.id, job.name, job.state, job.payload)
+}
+```
+
+`ListJobsOptions`:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `states` | `JobState[]` | `['completed', 'failed', 'waiting', 'active']` | Which states to look in. `JobState` = `'waiting' \| 'active' \| 'completed' \| 'failed' \| 'delayed'` — the same vocabulary as `QueueStats`. |
+| `limit` | `number` | `20` (max `1000`) | Maximum jobs returned in **total**, newest first — not per state. Each state is read up to `limit` and the merged result is truncated, so one busy state can't starve the others. |
+
+**Why `completed` and `failed` are in the default.** A worker drains `waiting` in
+milliseconds, so a healthy queue shows `waiting: 0, active: 0` almost always.
+Defaulting to only those would answer "did my job run?" with an empty list on a
+queue that is working perfectly. `delayed` is *not* in the default — it is a
+separate question; ask for it explicitly.
+
+`JobSummary` (driver-neutral — never the backend's own job object):
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Backend-assigned job id. |
+| `name` | `string` | The job name from `defineJob({ name })`. |
+| `state` | `JobState` | Where the job was found. |
+| `attemptsMade` | `number` | Attempts so far (`0` before the first run). |
+| `timestamp` | `number` | Creation time, epoch ms. |
+| `payload` | `unknown` | **Your** payload — already unwrapped from the `{ payload, context }` dispatch envelope. |
+| `context` | `RequestContext \| undefined` | The request context captured at dispatch (`requestId`, `tenantId`, …), when there was one. |
+| `failedReason` | `string \| undefined` | Why it failed — only for `state: 'failed'`. |
+
+**A `JobSummary` carries the job's payload, so it can carry personal data.** Treat
+the result like the records it came from: never log it wholesale, and if you expose
+it over HTTP, require authentication (`meta: { auth: true }`), authorize it per
+tenant, and put raw payloads behind an explicit opt-in. `basalt queue:jobs` follows
+the same rule — it hides payloads unless you pass `--payload`.
+
+`readJobEnvelope(data)` is exported for custom drivers implementing `list`: it
+opens the `{ payload, context }` envelope defensively, treating anything that
+isn't one (an older producer, a hand-written job) as the payload itself.
+`DEFAULT_LIST_STATES`, `DEFAULT_LIST_LIMIT` and `MAX_LIST_LIMIT` are exported so
+a custom driver defaults the same way BullMQ does.
+
 ### `queuedOn<T>(bus, manager, event, handler, options?): () => void`
 
 Creates the event→job bridge. Returns the subscription cancel function.
@@ -326,11 +404,30 @@ Creates the event→job bridge. Returns the subscription cancel function.
 ### Drivers
 
 - **`class SyncQueueDriver`** — runs inline on `dispatch`, honors `attempts` (immediate retry). Public property `executed: { queue, jobName, attempts }[]` with the execution history (capped at 1000 entries). For testing and dev without Redis.
-- **`class BullmqQueueDriver`** — production over Redis; see the options table below.
-- **`interface QueueDriver`** (Advanced) — contract for custom drivers: `setExecutor(executor)`, `add(queue, jobName, data, options: AddJobOptions)`, `startWorker(queue, { concurrency? })`, optional `stats(queue)` / `retryFailed(queue, { limit? })`, `close()`, plus the optional `name` and `capabilities` fields. Helper types: `AddJobOptions`, `JobExecutor`, `QueueStats`, `DriverCapabilities`.
+- **`class BullmqQueueDriver`** — production over Redis; see the options table below. Imported from its own entry point, `@basaltkit/queue/bullmq` (one import path per backend, like the RabbitMQ/SQS/Kafka driver packages), and requires the optional `bullmq` peer.
+- **`interface QueueDriver`** (Advanced) — contract for custom drivers: `setExecutor(executor)`, `add(queue, jobName, data, options: AddJobOptions)`, `startWorker(queue, { concurrency? })`, optional `stats(queue)` / `retryFailed(queue, { limit? })` / `list(queue, options)`, `close()`, plus the optional `name` and `capabilities` fields. Helper types: `AddJobOptions`, `JobExecutor`, `QueueStats`, `DriverCapabilities`, `JobState`, `JobSummary`, `JobEnvelope`, `ListJobsOptions`.
+
+  The three optional methods are a deliberate pattern: a driver **omits** what its
+  backend cannot do, `QueueManager` returns `undefined`, and the caller gets an
+  honest "unsupported" instead of a guess. Omit `list` rather than implement it
+  with a destructive read — merely *looking* at a queue must never change it.
+
+  | Driver | `stats` | `retryFailed` | `list` | Why |
+  |---|:---:|:---:|:---:|---|
+  | `bullmq` | ✅ | ✅ | ✅ | Redis keeps jobs; reading them is non-destructive. |
+  | `sync` | ❌ | ❌ | ❌ | Runs inline and stores nothing. |
+  | [`rabbitmq`](https://www.npmjs.com/package/@basaltkit/queue-rabbitmq) | ❌ | ❌ | ❌ | AMQP has no non-destructive read: `basic.get`/consume hide the message from real workers and mark it redelivered. |
+  | [`sqs`](https://www.npmjs.com/package/@basaltkit/queue-sqs) | ❌ | ❌ | ❌ | `ReceiveMessage` starts the visibility timeout and bumps `ApproximateReceiveCount` — peeking could redrive jobs to the DLQ. |
+  | [`kafka`](https://www.npmjs.com/package/@basaltkit/queue-kafka) | ❌ | ❌ | ❌ | Reading is non-destructive, but a log has no per-message state — any job states would be invented. |
 
 #### `new BullmqQueueDriver(options: BullmqDriverOptions)`
 
+```ts
+import { BullmqQueueDriver } from '@basaltkit/queue/bullmq'   // needs `pnpm add bullmq`
+```
+
+(The `BullmqDriverOptions` **type** is also re-exported from `@basaltkit/queue` — types are erased at build, so they cost nothing.)
+
 | Option | Type | Default | Purpose |
 |---|---|---|---|
 | `connection` | `string \| ConnectionOptions` | — (required) | Redis URL (`redis://…`, `rediss://…` → TLS) or ioredis options. |
@@ -391,7 +488,8 @@ Passing your own `driver` bypasses that forwarding — a supplied driver owns it
 so set them in its constructor:
 
 ```ts
-import { queuePlugin, BullmqQueueDriver } from '@basaltkit/queue'
+import { queuePlugin } from '@basaltkit/queue'
+import { BullmqQueueDriver } from '@basaltkit/queue/bullmq'
 
 queuePlugin({
   jobs: [SendWelcomeEmail],
@@ -410,6 +508,7 @@ queuePlugin({
 | `JobNotRegisteredError` | `QUEUE_JOB_NOT_REGISTERED` | `job.dispatch()` was called before the job was registered in a `QueueManager`. |
 | `UnknownJobError` | `QUEUE_UNKNOWN_JOB` | A job reached the worker but is not registered in that process — producer and worker registered different job lists. |
 | `UnsupportedJobOptionError` | `QUEUE_UNSUPPORTED_OPTION` | With `onUnsupported: 'throw'`, a dispatch used an option the active driver's `capabilities` do not include. `status = 500`. |
+| `MissingQueueDriverPackageError` | `QUEUE_MISSING_DRIVER_PACKAGE` | `queuePlugin({ connection })` selected the BullMQ driver but the optional `bullmq` peer is not installed. Thrown at boot, with the fix in the message; `.cause` holds the original resolution error. |
 
 Errors thrown outside these classes come from the driver's client (ioredis, amqplib, kafkajs,
 the AWS SDK) and reach you through that driver's `onError`.
@@ -441,6 +540,13 @@ The `onUnsupported` policy caught a dispatch option the active driver can't hono
 **A job failed for good and nothing was logged.**
 Only the BullMQ driver reports exhausted jobs, via `onJobFailed` (default `console.error`). If you replaced it with a no-op, you removed the only signal. On the broker drivers, inspect the dead-letter destination (`q.dead`, `<topic>.dead`, `<queue>-dead`).
 
+**How do I see what's actually on the queue?**
+`basalt queue:stats` for the counts and `basalt queue:jobs` for the individual jobs
+(or `QUEUE`'s `manager.stats()` / `manager.list()` in code). Don't open the broker's
+own client — that couples your app to one backend and hands you the raw dispatch
+envelope instead of your payload. On a driver that can't introspect, both return
+`undefined` / print "Not supported" — an honest gap, not an empty queue.
+
 **Do I need Redis to run the tests?**
 No. Without `connection`, the plugin uses `SyncQueueDriver`. You can also instantiate the driver directly and inspect `driver.executed`.
 

package/dist/driver.d.ts

@@ -1,3 +1,4 @@
+import type { RequestContext } from '@basaltkit/core';
 /** Driver-neutral retention: `true`/`false`, a count, or `{ ageMs, count }`. */
 export type RetentionOption = boolean | number | {
     ageMs?: number;
@@ -42,6 +43,80 @@ export interface QueueStats {
     failed: number;
     delayed: number;
 }
+/**
+ * Driver-neutral job state — deliberately the same vocabulary as
+ * {@link QueueStats}, so `stats()` and `list()` describe the same lifecycle.
+ * Backend-specific states are mapped onto these by the driver.
+ */
+export type JobState = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed';
+/**
+ * States {@link QueueDriver.list} returns when the caller picks none.
+ *
+ * `completed` and `failed` come FIRST and are included on purpose: a worker
+ * drains `waiting` in milliseconds, so a healthy queue has `waiting: 0,
+ * active: 0` nearly always. Defaulting to only those would answer "did my job
+ * run?" with an empty list on a queue that is working perfectly — the classic
+ * false alarm. `delayed` is left out of the default (it is a deliberate,
+ * separate question); ask for it explicitly.
+ */
+export declare const DEFAULT_LIST_STATES: readonly JobState[];
+/** Default `limit` for {@link QueueDriver.list} — a screenful, not a dump. */
+export declare const DEFAULT_LIST_LIMIT = 20;
+/** Hard ceiling on `limit`, so an inspection call can't turn into a full scan. */
+export declare const MAX_LIST_LIMIT = 1000;
+export interface ListJobsOptions {
+    /** States to look in. Default {@link DEFAULT_LIST_STATES}. */
+    states?: JobState[] | undefined;
+    /**
+     * Maximum jobs returned in TOTAL (newest first), not per state. Default
+     * {@link DEFAULT_LIST_LIMIT}, capped at {@link MAX_LIST_LIMIT}.
+     */
+    limit?: number | undefined;
+}
+/**
+ * A driver-neutral view of ONE job. Drivers must return this — never their
+ * backend's own job object (a BullMQ `Job`, an amqplib message, …). Leaking
+ * that would invert the coupling this API exists to remove: the app would be
+ * back to writing broker-specific code, just through a Basalt method.
+ */
+export interface JobSummary {
+    /** Backend-assigned job id, as a string. */
+    id: string;
+    /** The job name — what `defineJob({ name })` declared. */
+    name: string;
+    /** Which state the job was found in. */
+    state: JobState;
+    /** Attempts made so far (0 before the first run). */
+    attemptsMade: number;
+    /** When the job was created, epoch milliseconds. */
+    timestamp: number;
+    /** The APP's payload — unwrapped from the dispatch envelope. */
+    payload: unknown;
+    /** The request context captured at dispatch (requestId, tenantId, …), if any. */
+    context?: RequestContext | undefined;
+    /** Why it failed — only meaningful for `state: 'failed'`. */
+    failedReason?: string | undefined;
+}
+/**
+ * The wire shape `QueueManager.dispatch` hands to {@link QueueDriver.add} as
+ * `data`: the app's payload plus a snapshot of the request context, so the
+ * context survives the hop to the worker. Drivers store it opaquely; only
+ * `list()` needs to open it — via {@link readJobEnvelope}.
+ */
+export interface JobEnvelope {
+    payload: unknown;
+    context?: RequestContext | undefined;
+}
+/**
+ * Opens a dispatch envelope for {@link JobSummary}. Defensive on purpose: a
+ * queue can also hold data written by an older version or by a non-Basalt
+ * producer, and an inspection command must never throw on it — anything that
+ * is not an envelope is reported as the payload itself.
+ */
+export declare function readJobEnvelope(data: unknown): {
+    payload: unknown;
+    context?: RequestContext | undefined;
+};
 /** Queue driver contract. BullMQ in production; sync in tests/dev. */
 export interface QueueDriver {
     /** Short identifier used in diagnostics (e.g. 'bullmq', 'sync'). */
@@ -68,5 +143,17 @@ export interface QueueDriver {
     retryFailed?(queue: string, options?: {
         limit?: number;
     }): Promise<number>;
+    /**
+     * Optional: list individual jobs (`basalt queue:jobs`) as driver-neutral
+     * {@link JobSummary} objects — newest first, `payload` unwrapped from the
+     * dispatch envelope via {@link readJobEnvelope}.
+     *
+     * Omit it when the backend cannot read a job WITHOUT consuming it: faking
+     * the capability with a destructive read (an AMQP `basic.get`, an SQS
+     * `ReceiveMessage`) would make merely *looking* at a queue change it. The
+     * QueueManager then returns `undefined` and the CLI reports the operation as
+     * unsupported — an honest gap beats a dangerous guess.
+     */
+    list?(queue: string, options?: ListJobsOptions): Promise<JobSummary[]>;
     close(): Promise<void>;
 }

package/dist/driver.js

@@ -1 +1,31 @@
-export {};
+/**
+ * States {@link QueueDriver.list} returns when the caller picks none.
+ *
+ * `completed` and `failed` come FIRST and are included on purpose: a worker
+ * drains `waiting` in milliseconds, so a healthy queue has `waiting: 0,
+ * active: 0` nearly always. Defaulting to only those would answer "did my job
+ * run?" with an empty list on a queue that is working perfectly — the classic
+ * false alarm. `delayed` is left out of the default (it is a deliberate,
+ * separate question); ask for it explicitly.
+ */
+export const DEFAULT_LIST_STATES = ['completed', 'failed', 'waiting', 'active'];
+/** Default `limit` for {@link QueueDriver.list} — a screenful, not a dump. */
+export const DEFAULT_LIST_LIMIT = 20;
+/** Hard ceiling on `limit`, so an inspection call can't turn into a full scan. */
+export const MAX_LIST_LIMIT = 1000;
+/**
+ * Opens a dispatch envelope for {@link JobSummary}. Defensive on purpose: a
+ * queue can also hold data written by an older version or by a non-Basalt
+ * producer, and an inspection command must never throw on it — anything that
+ * is not an envelope is reported as the payload itself.
+ */
+export function readJobEnvelope(data) {
+    if (typeof data === 'object' && data !== null && 'payload' in data) {
+        const envelope = data;
+        return {
+            payload: envelope.payload,
+            ...(envelope.context !== undefined ? { context: envelope.context } : {}),
+        };
+    }
+    return { payload: data };
+}

package/dist/drivers/bullmq.d.ts

@@ -1,5 +1,5 @@
 import { type ConnectionOptions } from 'bullmq';
-import type { AddJobOptions, JobExecutor, QueueDriver, QueueStats } from '../driver.js';
+import { type AddJobOptions, type JobExecutor, type JobSummary, type ListJobsOptions, type QueueDriver, type QueueStats } from '../driver.js';
 export interface BullmqDriverOptions {
     /** Redis URL (redis://... or rediss://...) or ioredis connection options. */
     connection: string | ConnectionOptions;
@@ -48,6 +48,17 @@ export declare class BullmqQueueDriver implements QueueDriver {
     retryFailed(queue: string, options?: {
         limit?: number;
     }): Promise<number>;
+    /**
+     * Reads jobs WITHOUT consuming them — Redis keeps finished jobs (subject to
+     * retention), so inspection here is non-destructive, which is why BullMQ can
+     * offer `list` at all.
+     *
+     * One `getJobs` per state, each capped at `limit`: that keeps every job's
+     * state known without an extra `job.getState()` round-trip per job, and
+     * stops one busy state (usually `completed`) from starving the others. The
+     * merged result is sorted newest-first and truncated to `limit`.
+     */
+    list(queue: string, options?: ListJobsOptions): Promise<JobSummary[]>;
     close(): Promise<void>;
     private queue;
 }

package/dist/drivers/bullmq.js

@@ -1,4 +1,5 @@
 import { Queue, Worker } from 'bullmq';
+import { DEFAULT_LIST_LIMIT, DEFAULT_LIST_STATES, MAX_LIST_LIMIT, readJobEnvelope, } from '../driver.js';
 /** Map the driver-neutral retention to BullMQ's (age in seconds), falling back to a default. */
 function toBullRetention(retention, fallback) {
     if (retention === undefined)
@@ -84,6 +85,32 @@ export class BullmqQueueDriver {
         }
         return retried;
     }
+    /**
+     * Reads jobs WITHOUT consuming them — Redis keeps finished jobs (subject to
+     * retention), so inspection here is non-destructive, which is why BullMQ can
+     * offer `list` at all.
+     *
+     * One `getJobs` per state, each capped at `limit`: that keeps every job's
+     * state known without an extra `job.getState()` round-trip per job, and
+     * stops one busy state (usually `completed`) from starving the others. The
+     * merged result is sorted newest-first and truncated to `limit`.
+     */
+    async list(queue, options = {}) {
+        const requested = options.states?.length ? options.states : DEFAULT_LIST_STATES;
+        const states = [...new Set(requested)];
+        const limit = Math.min(Math.max(1, Math.trunc(options.limit ?? DEFAULT_LIST_LIMIT)), MAX_LIST_LIMIT);
+        const summaries = [];
+        for (const state of states) {
+            const jobs = await this.queue(queue).getJobs([state], 0, limit - 1);
+            for (const job of jobs) {
+                // getJobs can yield holes when a job is removed mid-read (retention).
+                if (job)
+                    summaries.push(toSummary(job, state));
+            }
+        }
+        summaries.sort((a, b) => b.timestamp - a.timestamp);
+        return summaries.slice(0, limit);
+    }
     async close() {
         await Promise.all(this.workers.map((worker) => worker.close()));
         await Promise.all([...this.queues.values()].map((queue) => queue.close()));
@@ -98,6 +125,24 @@ export class BullmqQueueDriver {
         return queue;
     }
 }
+/**
+ * BullMQ `Job` → driver-neutral {@link JobSummary}. The BullMQ object never
+ * escapes the driver, and `job.data` (the dispatch envelope) is opened so the
+ * caller sees its own payload.
+ */
+function toSummary(job, state) {
+    const { payload, context } = readJobEnvelope(job.data);
+    return {
+        id: String(job.id ?? ''),
+        name: job.name,
+        state,
+        attemptsMade: job.attemptsMade ?? 0,
+        timestamp: job.timestamp ?? 0,
+        payload,
+        ...(context !== undefined ? { context } : {}),
+        ...(job.failedReason ? { failedReason: job.failedReason } : {}),
+    };
+}
 function parseRedisUrl(url) {
     const parsed = new URL(url);
     return {

package/dist/index.d.ts

@@ -1,14 +1,24 @@
-import { type BullmqDriverOptions } from './drivers/bullmq.js';
-import type { QueueDriver } from './driver.js';
+import { BasaltError } from '@basaltkit/core';
+import { type QueueDriver } from './driver.js';
+import type { BullmqDriverOptions } from './drivers/bullmq.js';
 import type { JobDefinition, JobRetention } from './job.js';
 import { QueueManager, type UnsupportedPolicy } from './manager.js';
 export { defineJob, JobValidationError, JobNotRegisteredError, type JobDefinition, type JobSchema, type JobBackoff, type JobRetention, type DispatchOptions, } from './job.js';
 export { QueueManager, UnknownJobError, UnsupportedJobOptionError, type UnsupportedPolicy, type QueueManagerOptions, } from './manager.js';
 export { queuedOn, type QueuedListenerOptions } from './bridge.js';
 export { SyncQueueDriver } from './drivers/sync.js';
-export { BullmqQueueDriver, type BullmqDriverOptions } from './drivers/bullmq.js';
-export type { QueueDriver, QueueStats, AddJobOptions, JobExecutor, DriverCapabilities } from './driver.js';
+/**
+ * The BullMQ driver's *types* stay on the barrel (erased at build, so they cost
+ * a consumer nothing). The CLASS lives at its own entry point:
+ * `import { BullmqQueueDriver } from '@basaltkit/queue/bullmq'` — the same
+ * shape as the RabbitMQ/SQS/Kafka driver packages, one import path per backend.
+ */
+export type { BullmqDriverOptions } from './drivers/bullmq.js';
+export { readJobEnvelope, DEFAULT_LIST_STATES, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, type QueueDriver, type QueueStats, type AddJobOptions, type JobExecutor, type DriverCapabilities, type JobState, type JobSummary, type JobEnvelope, type ListJobsOptions, } from './driver.js';
 export declare const QUEUE: import("@basaltkit/core").Token<QueueManager>;
+export declare class MissingQueueDriverPackageError extends BasaltError {
+    constructor(options?: ErrorOptions);
+}
 export interface QueuePluginOptions {
     /** Jobs known to this process (producer and/or worker). */
     jobs?: JobDefinition<unknown>[];

package/dist/index.js

@@ -1,23 +1,59 @@
-import { createToken, definePlugin, ensureMetadata } from '@basaltkit/core';
-import { BullmqQueueDriver } from './drivers/bullmq.js';
+import { BasaltError, createToken, definePlugin, ensureMetadata } from '@basaltkit/core';
+import { DEFAULT_LIST_LIMIT, DEFAULT_LIST_STATES, } from './driver.js';
 import { SyncQueueDriver } from './drivers/sync.js';
 import { QueueManager } from './manager.js';
 export { defineJob, JobValidationError, JobNotRegisteredError, } from './job.js';
 export { QueueManager, UnknownJobError, UnsupportedJobOptionError, } from './manager.js';
 export { queuedOn } from './bridge.js';
 export { SyncQueueDriver } from './drivers/sync.js';
-export { BullmqQueueDriver } from './drivers/bullmq.js';
+export { readJobEnvelope, DEFAULT_LIST_STATES, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, } from './driver.js';
 export const QUEUE = createToken('queue');
+let bullmqDriverModule;
+/** Actionable guidance instead of a bare ERR_MODULE_NOT_FOUND from deep inside the driver. */
+const MISSING_BULLMQ = '`queuePlugin({ connection })` selects the BullMQ driver, which needs the `bullmq` package — ' +
+    'an optional peer dependency of @basaltkit/queue that is not installed. ' +
+    'Either install it (`pnpm add bullmq`), or pass an explicit `driver:` — ' +
+    '`@basaltkit/queue-rabbitmq`, `@basaltkit/queue-sqs`, `@basaltkit/queue-kafka`, ' +
+    'or `new SyncQueueDriver()` for dev/tests.';
+export class MissingQueueDriverPackageError extends BasaltError {
+    constructor(options) {
+        super('QUEUE_MISSING_DRIVER_PACKAGE', MISSING_BULLMQ, options);
+    }
+}
+async function loadBullmqDriver() {
+    if (bullmqDriverModule)
+        return bullmqDriverModule;
+    try {
+        bullmqDriverModule = await import('./drivers/bullmq.js');
+    }
+    catch (error) {
+        throw new MissingQueueDriverPackageError({ cause: error });
+    }
+    return bullmqDriverModule;
+}
 export function queuePlugin(options = {}) {
     return definePlugin({
         name: 'basalt:queue',
-        register({ container }) {
+        async register({ container }) {
+            // Resolve the BullMQ driver MODULE here — `BasaltApp.boot()` awaits
+            // `register`, so the class is in hand before anything can resolve QUEUE,
+            // and the container factory below stays synchronous. This is still a
+            // bindings-only phase: loading a module is not I/O against the world —
+            // no Redis connection is opened until the singleton is first resolved.
+            // Doing it in `boot` instead would leave a hole: a plugin booting earlier
+            // that resolves QUEUE would hit an unloaded driver.
+            if (!options.driver && options.connection)
+                await loadBullmqDriver();
             registerQueueCommands(container);
             container.singleton(QUEUE, () => {
                 let driver = options.driver;
                 if (!driver) {
                     if (options.connection) {
-                        driver = new BullmqQueueDriver({
+                        // Defensive: only reachable if `register`'s promise was dropped by
+                        // a non-standard host instead of awaited.
+                        if (!bullmqDriverModule)
+                            throw new MissingQueueDriverPackageError();
+                        driver = new bullmqDriverModule.BullmqQueueDriver({
                             connection: options.connection,
                             ...(options.onError !== undefined ? { onError: options.onError } : {}),
                             ...(options.onJobFailed !== undefined ? { onJobFailed: options.onJobFailed } : {}),
@@ -58,14 +94,52 @@ export function queuePlugin(options = {}) {
         },
     });
 }
+/** The states `queue:jobs --states` accepts — the driver-neutral vocabulary. */
+const LIST_STATES = ['waiting', 'active', 'completed', 'failed', 'delayed'];
+/** Parses `--states failed,waiting`. Throws on an unknown state rather than silently dropping it. */
+function parseStates(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    const states = raw.split(',').map((part) => part.trim()).filter(Boolean);
+    const unknown = states.filter((state) => !LIST_STATES.includes(state));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown job state(s): ${unknown.join(', ')}. Valid states: ${LIST_STATES.join(', ')}.`);
+    }
+    return states;
+}
+/** Compact age for the CLI table ('3s', '12m', '4h', '2d') — friendlier than an epoch. */
+function formatAge(timestamp, now) {
+    const seconds = Math.max(0, Math.round((now - timestamp) / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.round(seconds / 60)}m`;
+    if (seconds < 86_400)
+        return `${Math.round(seconds / 3600)}h`;
+    return `${Math.round(seconds / 86_400)}d`;
+}
+/** One-line, length-capped rendering of an arbitrary value for a table cell. */
+function preview(value, max = 120) {
+    let text;
+    try {
+        text = typeof value === 'string' ? value : JSON.stringify(value);
+    }
+    catch {
+        text = String(value);
+    }
+    text = (text ?? String(value)).replace(/\s+/g, ' ');
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
 /**
- * Registers `queue:work`, `queue:stats` and `queue:retry` into the CLI command
- * bucket. Commands resolve the manager lazily, so they work with whatever driver
+ * Registers `queue:work`, `queue:stats`, `queue:retry` and `queue:jobs` into the
+ * CLI command bucket. Commands resolve the manager lazily, so they work with whatever driver
  * the app configured. Registered structurally to avoid a hard @basaltkit/cli dep.
  */
 function registerQueueCommands(container) {
     const manager = () => container.get(QUEUE);
     const unsupported = 'Not supported by the active queue driver — the inline sync driver keeps no job state. Use the BullMQ driver (a Redis `connection`).';
+    const unsupportedList = 'Not supported by the active queue driver — listing jobs needs a backend that can read a job WITHOUT consuming it. ' +
+        'Use the BullMQ driver (a Redis `connection`); the sync driver keeps no job state, and the RabbitMQ/SQS/Kafka drivers cannot list non-destructively.';
     ensureMetadata(container).add('commands', {
         name: 'queue:work',
         description: 'Run a worker that processes jobs for a queue (Ctrl+C to stop)',
@@ -104,4 +178,44 @@ function registerQueueCommands(container) {
             io.log(`Re-enqueued ${retried} failed job(s) on "${queue}".`);
         },
     });
+    ensureMetadata(container).add('commands', {
+        name: 'queue:jobs',
+        description: 'List individual jobs on a queue (id/name/state/attempts); --payload also prints their data',
+        async handle({ io, flags, }) {
+            const queue = typeof flags['queue'] === 'string' ? flags['queue'] : 'default';
+            const states = parseStates(flags['states']);
+            const limit = typeof flags['limit'] === 'string' ? Number(flags['limit']) : undefined;
+            const jobs = await manager().list(queue, {
+                ...(states !== undefined ? { states } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+            });
+            if (!jobs) {
+                io.log(unsupportedList);
+                return;
+            }
+            const asked = (states ?? DEFAULT_LIST_STATES).join(', ');
+            if (jobs.length === 0) {
+                io.log(`No jobs on "${queue}" in ${asked}.`);
+                return;
+            }
+            // Payloads can hold personal data, so they are NOT printed by default —
+            // `--payload` is the deliberate opt-in (same posture as the docs' warning).
+            const withPayload = flags['payload'] === true || flags['payload'] === 'true';
+            const now = Date.now();
+            const anyFailed = jobs.some((job) => job.failedReason !== undefined);
+            io.table(jobs.map((job) => ({
+                id: job.id,
+                name: job.name,
+                state: job.state,
+                attempts: job.attemptsMade,
+                age: formatAge(job.timestamp, now),
+                ...(anyFailed ? { reason: job.failedReason ? preview(job.failedReason, 60) : '' } : {}),
+                ...(withPayload ? { payload: preview(job.payload) } : {}),
+            })));
+            io.log(`${jobs.length} job(s) on "${queue}" (${asked}, limit ${limit ?? DEFAULT_LIST_LIMIT}).` +
+                (withPayload
+                    ? ' Payloads shown — they can contain personal data.'
+                    : ' Payloads hidden — add --payload to include them.'));
+        },
+    });
 }

package/dist/manager.d.ts

@@ -1,5 +1,5 @@
 import { BasaltError } from '@basaltkit/core';
-import type { QueueDriver, QueueStats } from './driver.js';
+import type { JobSummary, ListJobsOptions, QueueDriver, QueueStats } from './driver.js';
 import { type DispatchOptions, type JobDefinition, type JobDispatcher, type JobRetention } from './job.js';
 export declare class UnknownJobError extends BasaltError {
     constructor(job: string);
@@ -55,6 +55,19 @@ export declare class QueueManager implements JobDispatcher {
     retryFailed(queue?: string, options?: {
         limit?: number;
     }): Promise<number | undefined>;
+    /**
+     * Lists individual jobs on the queue — newest first, with each job's own
+     * payload already unwrapped from the dispatch envelope. Returns `undefined`
+     * when the driver can't list (the sync driver keeps no state; a broker that
+     * cannot read a message without consuming it deliberately omits `list`).
+     *
+     * This is the supported alternative to reaching around the framework into
+     * the broker's own client, which couples the app to one backend.
+     *
+     * A summary carries the job's payload, so it can carry personal data —
+     * treat the result as sensitive (see the queues guide).
+     */
+    list(queue?: string, options?: ListJobsOptions): Promise<JobSummary[] | undefined>;
     close(): Promise<void>;
     /** Executes a job received from the driver: validates, restores the context, runs the handler. */
     private execute;

package/dist/manager.js

@@ -128,6 +128,21 @@ export class QueueManager {
     async retryFailed(queue = 'default', options = {}) {
         return this.driver.retryFailed?.(queue, options);
     }
+    /**
+     * Lists individual jobs on the queue — newest first, with each job's own
+     * payload already unwrapped from the dispatch envelope. Returns `undefined`
+     * when the driver can't list (the sync driver keeps no state; a broker that
+     * cannot read a message without consuming it deliberately omits `list`).
+     *
+     * This is the supported alternative to reaching around the framework into
+     * the broker's own client, which couples the app to one backend.
+     *
+     * A summary carries the job's payload, so it can carry personal data —
+     * treat the result as sensitive (see the queues guide).
+     */
+    async list(queue = 'default', options = {}) {
+        return this.driver.list?.(queue, options);
+    }
     async close() {
         await this.driver.close();
     }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.4.1",
+  "version": "2.0.0",
   "engines": {
     "node": ">=22.5.0"
   },
-  "description": "Basalt queues on top of BullMQ: declarative jobs with Zod payloads, context propagation (tenant/requestId) to workers and a sync driver for tests.",
+  "description": "Driver-agnostic Basalt queues: declarative jobs with Zod payloads, context propagation (tenant/requestId) to workers, a BullMQ/Redis driver behind an optional peer, and a sync driver for tests.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -12,18 +12,30 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./bullmq": {
+      "types": "./dist/drivers/bullmq.d.ts",
+      "import": "./dist/drivers/bullmq.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "bullmq": "^6.2.1",
-    "@basaltkit/core": "^1.3.1",
-    "@basaltkit/events": "^1.1.1"
+    "@basaltkit/events": "^1.1.1",
+    "@basaltkit/core": "^1.3.1"
+  },
+  "peerDependencies": {
+    "bullmq": "^6.2.1"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
+    "bullmq": "^6.2.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "zod": "^3.24.0 || ^4.0.0",