@maroonedsoftware/jobbroker 1.8.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,6 +9,8 @@ A flexible background job processing library with support for scheduled and on-d
9
9
  - **Scheduled jobs** using cron expressions
10
10
  - **On-demand jobs** for immediate execution
11
11
  - **Cancellation** of queued _and_ running jobs, plus state lookup, delete, and resume
12
+ - **Per-queue retry & dead-letter policy** for retry limits, backoff, and poison-message capture
13
+ - **Dead-letter monitoring** to inspect, redrive, retry, or discard failed jobs
12
14
  - **PostgreSQL backing** for reliability and transactional guarantees
13
15
 
14
16
  ## Installation
@@ -23,8 +25,8 @@ pnpm add @maroonedsoftware/jobbroker injectkit pg-boss reflect-metadata
23
25
 
24
26
  | Import | Contents | Pulls in |
25
27
  | ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------- |
26
- | `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobInfo`, `JobState`, `NotSupportedError` | nothing extra |
27
- | `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
28
+ | `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobMonitor`, `JobInfo`, `JobState`, `JobQueuePolicy`, `NotSupportedError` | nothing extra |
29
+ | `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobMonitor`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
28
30
 
29
31
  ## Quick Start
30
32
 
@@ -74,6 +76,17 @@ registry.set('daily-report', {
74
76
  job: DailyReportJob,
75
77
  cron: '0 9 * * *', // Every day at 9 AM
76
78
  });
79
+
80
+ // On-demand job with a retry / dead-letter policy (see "Retry & dead-letter policy")
81
+ registry.set('deliver-webhook', {
82
+ job: DeliverWebhookJob,
83
+ policy: {
84
+ retryLimit: 5,
85
+ retryDelay: Duration.fromObject({ seconds: 30 }),
86
+ retryBackoff: true,
87
+ deadLetter: 'deliver-webhook-dead',
88
+ },
89
+ });
77
90
  ```
78
91
 
79
92
  ### 3. Set Up the Broker and Runner
@@ -83,8 +96,8 @@ import 'reflect-metadata';
83
96
  import { PgBoss } from 'pg-boss';
84
97
  import { InjectKitRegistry } from 'injectkit';
85
98
  import { ConsoleLogger, Logger } from '@maroonedsoftware/logger';
86
- import { JobBroker, JobRunner } from '@maroonedsoftware/jobbroker';
87
- import { PgBossJobBroker, PgBossJobRunner, PgBossJobRegistryMap, PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
99
+ import { JobBroker, JobRunner, JobMonitor } from '@maroonedsoftware/jobbroker';
100
+ import { PgBossJobBroker, PgBossJobRunner, PgBossJobMonitor, PgBossJobRegistryMap, PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
88
101
 
89
102
  // Initialize pg-boss
90
103
  const pgboss = new PgBoss('postgres://user:pass@localhost/mydb');
@@ -98,6 +111,7 @@ diRegistry.register(Logger).useClass(ConsoleLogger).asSingleton();
98
111
  diRegistry.register(PgBossConnectionProvider).useClass(PgBossConnectionProvider).asSingleton();
99
112
  diRegistry.register(JobBroker).useClass(PgBossJobBroker).asSingleton();
100
113
  diRegistry.register(JobRunner).useClass(PgBossJobRunner).asSingleton();
114
+ diRegistry.register(JobMonitor).useClass(PgBossJobMonitor).asSingleton();
101
115
 
102
116
  // Build the container
103
117
  const container = diRegistry.build();
@@ -160,6 +174,80 @@ runner.cancelPollIntervalSeconds = 2; // default 5; set to 0 to disable polling
160
174
 
161
175
  Lower values reduce cancellation latency at the cost of one extra lookup query per running job per interval.
162
176
 
177
+ ## Retry & dead-letter policy
178
+
179
+ By default a job that keeps failing is retried a couple of times and then marked `failed` — where it stays, with nothing draining it. For money-critical or webhook work you usually want an explicit retry budget, backoff between attempts, and a **dead-letter queue (DLQ)** so a job that exhausts its retries is preserved for inspection or replay instead of being dropped.
180
+
181
+ Declare a `JobQueuePolicy` on the registration, right where the job is mapped. Every field is optional, and durations are Luxon `Duration`s (mapped to whole seconds for pg-boss):
182
+
183
+ ```typescript
184
+ import { Duration } from 'luxon';
185
+
186
+ registry.set('deliver-webhook', {
187
+ job: DeliverWebhookJob,
188
+ policy: {
189
+ retryLimit: 5, // attempts before the job is failed / dead-lettered
190
+ retryDelay: Duration.fromObject({ seconds: 30 }), // base delay between attempts
191
+ retryBackoff: true, // grow the delay exponentially (with jitter) from retryDelay
192
+ retryDelayMax: Duration.fromObject({ minutes: 10 }), // cap for the backoff curve
193
+ expiresIn: Duration.fromObject({ minutes: 2 }), // a run is considered stuck after this
194
+ deadLetter: 'deliver-webhook-dead', // where exhausted jobs land
195
+ },
196
+ });
197
+ ```
198
+
199
+ The policy is applied to the queue when `runner.start()` runs: an absent queue is **created** with these options, and an existing queue is **updated** to match, so changing a policy and restarting reconciles it. When a registration declares no policy, its queue is created exactly as before — this feature is fully backward-compatible.
200
+
201
+ **Dead-letter queues are auto-created.** If `deadLetter` names a queue that does not yet exist, the runner creates it (as a plain queue) before the source queue that references it, so you don't have to register a placeholder. A DLQ you actually want to *drain* is just another registered job whose name matches — give it its own handler (and, if you like, its own policy). A DLQ you only want to inspect can be left unregistered; jobs simply accumulate there for manual review or redrive.
202
+
203
+ To apply the same defaults to **every** queue without repeating them, set `defaultQueuePolicy` on the runner. Each queue's own policy is layered on top, so a field a queue sets wins over the default:
204
+
205
+ ```typescript
206
+ const runner = container.get(JobRunner) as PgBossJobRunner;
207
+ runner.defaultQueuePolicy = {
208
+ retryLimit: 3,
209
+ retryBackoff: true,
210
+ retryDelay: Duration.fromObject({ seconds: 10 }),
211
+ };
212
+ await runner.start();
213
+ ```
214
+
215
+ Retry and dead-letter behavior is a **queue-level** concern here, not a per-`send` one: it is declared once where the job is registered rather than on each `broker.send(...)`. This matches how the mainstream backends model it (pg-boss `retryLimit`/`deadLetter`, SQS's redrive policy, Cloud Tasks' `maxAttempts`), none of which support per-message retry overrides — so `JobQueuePolicy` stays portable across backends.
216
+
217
+ ## Monitoring & draining dead-letter queues
218
+
219
+ Capturing a poison message is only half the job: a consumer needs to see what landed in a dead-letter queue and act on it. `JobMonitor` is the operator-side companion to `JobBroker` (produce) and `JobRunner` (consume) — it reads queue depth, lists the stuck jobs, and remediates them. Unlike the broker, it operates on **any queue name and does not require the queue to be registered**, because a dead-letter queue is often an unregistered sink with no worker of its own.
220
+
221
+ ```typescript
222
+ const monitor = container.get(JobMonitor);
223
+
224
+ // Observe — poll depth/health (e.g. from a reconciliation cron) to alert on a growing DLQ
225
+ const stats = await monitor.getQueueStats('deliver-webhook-dead');
226
+ // stats: { name, queued, active, failed, total } | null (null when the queue does not exist)
227
+
228
+ if (stats && stats.total > 0) {
229
+ // Retrieve — inspect the poison messages (id, state, original payload)
230
+ const stuck = await monitor.listJobs<WebhookPayload>('deliver-webhook-dead');
231
+ logger.warn(`${stuck.length} webhooks in the dead-letter queue`, { ids: stuck.map(j => j.id) });
232
+
233
+ // Act — move them back to their original source queue to reprocess, oldest first, rate-limited
234
+ const moved = await monitor.redrive('deliver-webhook-dead', { limit: 100 });
235
+
236
+ // ...or discard a specific unrecoverable message
237
+ await monitor.deleteJob('deliver-webhook-dead', stuck[0].id);
238
+ }
239
+ ```
240
+
241
+ | Method | Description |
242
+ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
243
+ | `getQueueStats(name)` | Point-in-time `{ name, queued, active, failed, total }`, or `null` if the queue does not exist. |
244
+ | `listJobs<P>(name, options?)` | List retained jobs as `JobInfo<P>[]`; filter by `id`, partial `data`, or `queuedOnly`. |
245
+ | `redrive(name, options?)` | Move dead-lettered jobs back to their source (or a `destination`), oldest first; returns count. |
246
+ | `deleteJob(name, id)` | Permanently discard one or more jobs (no registry check, so DLQ sinks are serviceable). |
247
+ | `retryJob(name, id)` | Re-attempt failed jobs **in place**; for a DLQ sink prefer `redrive`, which moves them to a worker. |
248
+
249
+ `redrive` returns each job to the queue it was dead-lettered from by default, so a worker can process it again. Pass `destination` to funnel everything into one queue, `sourceName` to drain just one source's jobs from a shared DLQ, and `limit` to move in controlled batches. All operations source their pg-boss `db` executor from `PgBossConnectionProvider`, so a remediation can run inside a transaction when you override the provider (see [Transactional enqueue](#transactional-enqueue)).
250
+
163
251
  ### Backend portability
164
252
 
165
253
  `cancel`, `resume`, `deleteJob`, and `getJob` are best-effort by contract: a backend that cannot honor an operation throws `NotSupportedError` rather than silently doing nothing. `JobState` (`created | retry | active | completed | cancelled | failed`) is the normalized, lowest-common-denominator lifecycle; alternative backends map their native states to the nearest value. The bundled pg-boss backend supports every operation.
@@ -203,6 +291,20 @@ Abstract base class for processing jobs from the queue.
203
291
  | `start(): Promise<void>` | Start processing jobs |
204
292
  | `stop(): Promise<void>` | Gracefully stop processing |
205
293
 
294
+ ### `JobMonitor`
295
+
296
+ Abstract base class for observing queues and remediating dead-letter queues. Operates on raw queue names (no registry check). Operations a backend cannot honor throw `NotSupportedError`. See [Monitoring & draining dead-letter queues](#monitoring--draining-dead-letter-queues).
297
+
298
+ | Method | Description |
299
+ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
300
+ | `getQueueStats(name: string): Promise<JobQueueStats \| null>` | Queue depth/health counts, or `null` if the queue does not exist |
301
+ | `listJobs<P>(name: string, options?: JobQueryOptions): Promise<JobInfo<P>[]>` | List retained jobs, optionally filtered by `id`, `data`, or `queuedOnly` |
302
+ | `redrive(name: string, options?: JobRedriveOptions): Promise<number>` | Move dead-lettered jobs back to source (or a `destination`); returns count moved |
303
+ | `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently discard jobs |
304
+ | `retryJob(name: string, id: string \| string[]): Promise<void>` | Re-attempt failed jobs in place |
305
+
306
+ `JobQueueStats` is `{ name, queued, active, failed, total }`. `JobQueryOptions` is `{ id?, data?, queuedOnly? }`. `JobRedriveOptions` is `{ destination?, sourceName?, limit? }`.
307
+
206
308
  ### `PgBossJobRegistryMap`
207
309
 
208
310
  A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
@@ -210,16 +312,30 @@ A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
210
312
  Entries can be either:
211
313
 
212
314
  - A job class identifier (for on-demand jobs)
213
- - A `PgBossJobRegistration` object with `job` and `cron` properties (for scheduled jobs)
315
+ - A `PgBossJobRegistration` object (for scheduled jobs, jobs with a queue policy, or both)
214
316
 
215
317
  ### `PgBossJobRegistration`
216
318
 
217
- Configuration object for a scheduled job.
319
+ Configuration object for a job. Only `job` is required, so it covers on-demand jobs (`{ job }`), scheduled jobs (`{ job, cron }`), and either with a retry/dead-letter policy attached.
320
+
321
+ | Property | Type | Description |
322
+ | -------- | ----------------- | ------------------------------------------------------------------- |
323
+ | `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
324
+ | `cron` | `string` | Optional cron expression defining when the job should run. |
325
+ | `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
218
326
 
219
- | Property | Type | Description |
220
- | -------- | ----------------- | ---------------------------------------------------------- |
221
- | `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
222
- | `cron` | `string` | A cron expression defining when the job should run. |
327
+ ### `JobQueuePolicy`
328
+
329
+ Backend-agnostic per-queue retry and dead-letter policy (see [Retry & dead-letter policy](#retry--dead-letter-policy)). Every field is optional; durations are Luxon `Duration`s.
330
+
331
+ | Property | Type | Description |
332
+ | --------------- | ---------- | --------------------------------------------------------------------------------------- |
333
+ | `retryLimit` | `number` | Attempts before a job is failed (and dead-lettered, if `deadLetter` is set). |
334
+ | `retryDelay` | `Duration` | Delay before retrying; the base of the curve when `retryBackoff` is on. |
335
+ | `retryBackoff` | `boolean` | Grow the retry delay exponentially (with jitter) from `retryDelay` instead of fixed. |
336
+ | `retryDelayMax` | `Duration` | Upper bound on the backoff delay. Only used when `retryBackoff` is on. |
337
+ | `expiresIn` | `Duration` | How long a run may take before it is considered stuck and made eligible for retry. |
338
+ | `deadLetter` | `string` | Name of the dead-letter queue that receives jobs which exhaust their retries. |
223
339
 
224
340
  ### `PgBossJobBroker`
225
341
 
@@ -269,6 +385,12 @@ Concrete `JobRunner` implementation backed by pg-boss. Constructor signature: `n
269
385
 
270
386
  Exposes a `cancelPollIntervalSeconds` property (default `5`) that controls how often a running job is polled for cancellation; set it to `0` to disable polling. See [Cancelling jobs](#cancelling-jobs).
271
387
 
388
+ Also exposes an optional `defaultQueuePolicy` (a `JobQueuePolicy`) applied beneath every queue's own policy, so all queues can share retry/dead-letter defaults without repeating them. See [Retry & dead-letter policy](#retry--dead-letter-policy).
389
+
390
+ ### `PgBossJobMonitor`
391
+
392
+ Concrete `JobMonitor` implementation backed by pg-boss. Constructor signature: `new PgBossJobMonitor(pgboss: PgBoss, connectionProvider: PgBossConnectionProvider)`. Reads and remediates queues via pg-boss's `getQueue`, `findJobs`, `redrive`, `deleteJob`, and `retry`, sourcing the `db` executor from the injected `PgBossConnectionProvider` (so remediation can be transactional). Does not consult the job registry, so it works on unregistered dead-letter sinks. Typically resolved through the DI container rather than instantiated directly.
393
+
272
394
  ## Graceful Shutdown
273
395
 
274
396
  Ensure you stop the runner during application shutdown:
@@ -19,7 +19,7 @@ JobBroker = _ts_decorate([
19
19
  Injectable()
20
20
  ], JobBroker);
21
21
 
22
- // src/job.runner.ts
22
+ // src/job.monitor.ts
23
23
  import { Injectable as Injectable2 } from "injectkit";
24
24
  function _ts_decorate2(decorators, target, key, desc) {
25
25
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -28,18 +28,37 @@ function _ts_decorate2(decorators, target, key, desc) {
28
28
  return c > 3 && r && Object.defineProperty(target, key, r), r;
29
29
  }
30
30
  __name(_ts_decorate2, "_ts_decorate");
31
+ var JobMonitor = class {
32
+ static {
33
+ __name(this, "JobMonitor");
34
+ }
35
+ };
36
+ JobMonitor = _ts_decorate2([
37
+ Injectable2()
38
+ ], JobMonitor);
39
+
40
+ // src/job.runner.ts
41
+ import { Injectable as Injectable3 } from "injectkit";
42
+ function _ts_decorate3(decorators, target, key, desc) {
43
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
44
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
45
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
46
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
47
+ }
48
+ __name(_ts_decorate3, "_ts_decorate");
31
49
  var JobRunner = class {
32
50
  static {
33
51
  __name(this, "JobRunner");
34
52
  }
35
53
  };
36
- JobRunner = _ts_decorate2([
37
- Injectable2()
54
+ JobRunner = _ts_decorate3([
55
+ Injectable3()
38
56
  ], JobRunner);
39
57
 
40
58
  export {
41
59
  __name,
42
60
  JobBroker,
61
+ JobMonitor,
43
62
  JobRunner
44
63
  };
45
- //# sourceMappingURL=chunk-GKXLBFUJ.js.map
64
+ //# sourceMappingURL=chunk-VCGAI6CK.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/job.broker.ts","../src/job.monitor.ts","../src/job.runner.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\nimport { JobInfo } from './job.info.js';\nimport { JobSendOptions } from './job.send.options.js';\n\n/**\n * Abstract base class for job broker implementations.\n *\n * A job broker is responsible for sending jobs to a queue, cancelling and\n * inspecting jobs, and managing scheduled jobs. It provides the producer-side\n * interface for the job processing system.\n *\n * Backends differ in what they can do. Operations a backend cannot honor throw\n * a `NotSupportedError` rather than silently doing nothing. The bundled pg-boss\n * backend supports every operation.\n *\n * @example\n * ```typescript\n * // Sending a job immediately (returns the job id)\n * const id = await jobBroker.send('send-email', {\n * to: 'user@example.com',\n * subject: 'Welcome!',\n * body: 'Thanks for signing up.'\n * });\n *\n * // Deferring a job: run it no earlier than five minutes from now\n * await jobBroker.send('send-email', payload, {\n * startAfter: Duration.fromObject({ minutes: 5 })\n * });\n *\n * // Deferring to an absolute time\n * await jobBroker.send('send-email', payload, {\n * startAfter: DateTime.now().plus({ hours: 2 })\n * });\n *\n * // Cancelling it later, whether it is still queued or already running\n * await jobBroker.cancel('send-email', id);\n *\n * // Scheduling a recurring job with cron\n * await jobBroker.schedule('daily-report', '0 9 * * *', {\n * reportType: 'sales'\n * });\n *\n * // Removing a scheduled job\n * await jobBroker.unschedule('daily-report');\n * ```\n */\n@Injectable()\nexport abstract class JobBroker {\n /**\n * Sends a job to the queue.\n *\n * By default the job is eligible for immediate processing and will be picked\n * up by a worker as soon as one is available. Pass {@link JobSendOptions.startAfter}\n * to defer it: the job becomes eligible only once the given delay has elapsed\n * (a {@link Duration}) or the given moment has passed (a {@link DateTime}).\n * Deferral is a lower bound, not a guarantee of exact-time execution — the job\n * runs at the first opportunity after it becomes eligible.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param payload - The data to pass to the job handler.\n * @param options - Optional enqueue options, e.g. `startAfter` to defer the job.\n * @returns A promise that resolves with the id of the queued job. The id can\n * be passed to {@link cancel}, {@link resume}, {@link deleteJob}, or\n * {@link getJob}.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if `options.startAfter` requests a deferral the\n * backend cannot honor (e.g. a delay beyond the backend's maximum).\n */\n abstract send<Payload extends object>(name: string, payload: Payload, options?: JobSendOptions): Promise<string>;\n\n /**\n * Schedules a recurring job using a cron expression.\n *\n * The job will be automatically enqueued according to the cron schedule.\n * If a schedule already exists for this job name, it will be updated.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param cron - A cron expression defining the schedule (e.g., '0 9 * * *' for daily at 9am).\n * @param payload - Optional data to pass to the job handler on each execution.\n * @returns A promise that resolves when the schedule has been created.\n * @throws If the job name is not registered.\n */\n abstract schedule<Payload extends object>(name: string, cron: string, payload?: Payload): Promise<void>;\n\n /**\n * Removes a scheduled job.\n *\n * Stops the recurring execution of the specified job.\n * Does not affect jobs that are already queued.\n *\n * @param name - The unique name of the scheduled job to remove.\n * @returns A promise that resolves when the schedule has been removed.\n * @throws If the job name is not registered.\n */\n abstract unschedule(name: string): Promise<void>;\n\n /**\n * Requests cancellation of one or more jobs.\n *\n * Cancellation is best-effort and applies regardless of the job's state: a\n * job that is still queued is prevented from running, and a job that is\n * already running is asked to stop. For a running job, cancellation is\n * cooperative — the job's handler receives an aborted `AbortSignal` (see\n * {@link Job.run}) and must honor it. A handler that ignores the signal runs\n * to completion. Some backends may forcefully terminate the running compute\n * instead; this contract only guarantees the request is delivered.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to cancel.\n * @returns A promise that resolves once the cancellation has been requested.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot cancel jobs.\n */\n abstract cancel(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Resumes one or more previously cancelled jobs, re-queuing them for processing.\n *\n * Only jobs in the `cancelled` state can be resumed; other states are\n * unaffected.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to resume.\n * @returns A promise that resolves once the jobs have been re-queued.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot resume jobs.\n */\n abstract resume(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Permanently deletes one or more jobs.\n *\n * Removes the job records entirely. Unlike {@link cancel}, a deleted job\n * leaves no `cancelled` record behind and cannot be resumed.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to delete.\n * @returns A promise that resolves once the jobs have been deleted.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot delete jobs.\n */\n abstract deleteJob(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Looks up the current state of a single job.\n *\n * @typeParam Payload - The type of the job payload.\n * @param name - The name of the registered job type.\n * @param id - The id of the job to look up.\n * @returns A promise that resolves with the {@link JobInfo} for the job, or\n * `null` if no job with that id exists.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot report per-job state.\n */\n abstract getJob<Payload extends object>(name: string, id: string): Promise<JobInfo<Payload> | null>;\n}\n","import { Injectable } from 'injectkit';\nimport { JobInfo } from './job.info.js';\n\n/**\n * A backend-agnostic snapshot of a single queue's depth and health, as returned\n * by {@link JobMonitor.getQueueStats}. Every count is a point-in-time reading;\n * poll it on a schedule (for example from a reconciliation job) to drive\n * alerting on a backlog or a growing dead-letter queue.\n *\n * The counts are the lowest common denominator every supported backend can\n * report. `failed` in particular is a *retained* count: it reflects failures\n * still held in the queue subject to the queue's retention policy, not an\n * all-time total.\n */\nexport interface JobQueueStats {\n /** The queue name these stats describe. */\n name: string;\n /** Jobs waiting to be processed (enqueued but not yet active). */\n queued: number;\n /** Jobs currently being executed by a worker. */\n active: number;\n /** Failed jobs still retained in the queue (bounded by the retention policy). */\n failed: number;\n /** All jobs still retained for the queue across every state. */\n total: number;\n}\n\n/**\n * Filters for {@link JobMonitor.listJobs}. All fields are optional; omitting them\n * lists every job currently retained in the queue (the common case when\n * inspecting a small dead-letter queue).\n */\nexport interface JobQueryOptions {\n /** Match a single job by its id. */\n id?: string;\n /** Match jobs whose payload contains these fields (a partial-match filter). */\n data?: Record<string, unknown>;\n /** Restrict the result to jobs still waiting to be processed. */\n queuedOnly?: boolean;\n}\n\n/**\n * Options for {@link JobMonitor.redrive}, which moves dead-lettered jobs out of a\n * queue and back into circulation.\n */\nexport interface JobRedriveOptions {\n /**\n * The queue to move jobs into. When omitted, each job returns to the queue it\n * originally came from before it was dead-lettered — the usual \"reprocess\"\n * behavior. Supply this to funnel everything into a specific queue instead.\n */\n destination?: string;\n /**\n * Only redrive jobs that originated from this source queue. Useful when a\n * single dead-letter queue collects failures from several source queues and\n * you want to drain just one source's worth.\n */\n sourceName?: string;\n /**\n * Maximum number of jobs to move in this call, oldest first. Call repeatedly\n * (or on a schedule) to drain a large dead-letter queue at a controlled rate.\n */\n limit?: number;\n}\n\n/**\n * Read-and-remediate interface for job queues, and in particular for\n * *dead-letter queues*: the queues that collect jobs which have exhausted their\n * retries (see the queue policy on the pg-boss backend's registration).\n *\n * Where {@link JobBroker} is the producer side (enqueue, cancel, inspect a job\n * you hold the id for) and {@link JobRunner} is the consumer side, `JobMonitor`\n * is the operator side: it lets a consumer answer \"how deep is this queue?\",\n * \"what is stuck in this dead-letter queue?\", and \"reprocess / discard those\n * jobs\". Unlike the broker, it operates on raw queue names and does **not**\n * require the queue to be registered, because a dead-letter queue is often an\n * unregistered sink with no worker of its own.\n *\n * Backends that cannot honor an operation throw a `NotSupportedError` rather than\n * silently doing nothing, matching the rest of the package. The bundled pg-boss\n * backend supports every operation.\n *\n * @example\n * ```typescript\n * // A reconciliation sweep over a money-critical dead-letter queue.\n * const stats = await monitor.getQueueStats('charge.webhook.dead');\n * if (stats && stats.total > 0) {\n * const stuck = await monitor.listJobs('charge.webhook.dead'); // inspect / log / alert\n * const moved = await monitor.redrive('charge.webhook.dead', { limit: 100 }); // drain back\n * }\n * ```\n */\n@Injectable()\nexport abstract class JobMonitor {\n /**\n * Reports the current depth and health of a queue.\n *\n * @param name - The queue name to inspect (may be an unregistered dead-letter queue).\n * @returns A promise resolving to the {@link JobQueueStats}, or `null` if no\n * queue with that name exists.\n * @throws `NotSupportedError` if the backend cannot report queue statistics.\n */\n abstract getQueueStats(name: string): Promise<JobQueueStats | null>;\n\n /**\n * Lists the jobs currently retained in a queue, optionally filtered.\n *\n * The primary use is inspecting a dead-letter queue: the returned\n * {@link JobInfo} objects expose each poison message's id, state, and original\n * payload so a consumer can decide whether to reprocess ({@link redrive}),\n * discard ({@link deleteJob}), or escalate it.\n *\n * @typeParam Payload - The type of the job payloads.\n * @param name - The queue name to list (may be an unregistered dead-letter queue).\n * @param options - Optional {@link JobQueryOptions} filters.\n * @returns A promise resolving to the matching jobs (empty if none / no such queue).\n * @throws `NotSupportedError` if the backend cannot enumerate jobs.\n */\n abstract listJobs<Payload extends object>(name: string, options?: JobQueryOptions): Promise<JobInfo<Payload>[]>;\n\n /**\n * Moves dead-lettered jobs out of a queue and back into circulation, returning\n * the number of jobs moved.\n *\n * By default each job goes back to the source queue it was dead-lettered from,\n * so a worker can process it again; pass {@link JobRedriveOptions.destination}\n * to route them elsewhere, {@link JobRedriveOptions.sourceName} to drain only\n * one source's jobs from a shared dead-letter queue, and\n * {@link JobRedriveOptions.limit} to move at a controlled rate.\n *\n * @param name - The (dead-letter) queue to drain.\n * @param options - Optional {@link JobRedriveOptions}.\n * @returns A promise resolving to the count of jobs moved.\n * @throws `NotSupportedError` if the backend cannot redrive jobs.\n */\n abstract redrive(name: string, options?: JobRedriveOptions): Promise<number>;\n\n /**\n * Permanently deletes one or more jobs from a queue.\n *\n * This is the \"discard\" action for a dead-letter queue: a poison message that\n * should not be reprocessed is removed outright. Unlike {@link JobBroker.deleteJob},\n * it does not require the queue to be registered.\n *\n * @param name - The queue name the jobs live in.\n * @param id - A single job id, or an array of ids, to delete.\n * @returns A promise that resolves once the jobs have been deleted.\n * @throws `NotSupportedError` if the backend cannot delete jobs.\n */\n abstract deleteJob(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Re-attempts one or more failed jobs *in place*, re-queuing them within their\n * current queue.\n *\n * Use this to re-run a job that failed in a queue that has its own worker. To\n * reprocess a job sitting in a dead-letter *sink* (a queue with no worker),\n * prefer {@link redrive}, which moves it back to a queue that can run it.\n *\n * @param name - The queue name the jobs live in.\n * @param id - A single job id, or an array of ids, to retry.\n * @returns A promise that resolves once the jobs have been re-queued.\n * @throws `NotSupportedError` if the backend cannot retry jobs.\n */\n abstract retryJob(name: string, id: string | string[]): Promise<void>;\n}\n","import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for job runner implementations.\n *\n * A job runner is responsible for consuming jobs from the queue and\n * executing the appropriate job handlers. It manages the worker lifecycle\n * and provides the consumer-side interface for the job processing system.\n *\n * @example\n * ```typescript\n * // Start processing jobs\n * await jobRunner.start();\n *\n * // Gracefully stop processing (e.g., on shutdown)\n * process.on('SIGTERM', async () => {\n * await jobRunner.stop();\n * process.exit(0);\n * });\n * ```\n */\n@Injectable()\nexport abstract class JobRunner {\n /**\n * Starts the job runner and begins processing jobs.\n *\n * This method initializes all registered job handlers and starts\n * listening for jobs on their respective queues. It should be called\n * during application startup.\n *\n * @returns A promise that resolves when the runner has started successfully.\n */\n abstract start(): Promise<void>;\n\n /**\n * Stops the job runner gracefully.\n *\n * This method stops accepting new jobs and waits for currently\n * executing jobs to complete. It should be called during application\n * shutdown to ensure clean termination.\n *\n * @returns A promise that resolves when the runner has stopped completely.\n */\n abstract stop(): Promise<void>;\n}\n"],"mappings":";;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+CpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAgHtB;;;;;;AC/JA,SAASC,cAAAA,mBAAkB;;;;;;;;AA6FpB,IAAeC,aAAf,MAAeA;SAAAA;;;AAwEtB;;;;;;ACrKA,SAASC,cAAAA,mBAAkB;;;;;;;;AAsBpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAsBtB;;;;","names":["Injectable","JobBroker","Injectable","JobMonitor","Injectable","JobRunner"]}
package/dist/index.d.ts CHANGED
@@ -2,6 +2,8 @@ export * from './job.broker.js';
2
2
  export * from './job.js';
3
3
  export * from './job.info.js';
4
4
  export * from './job.send.options.js';
5
+ export * from './job.queue.policy.js';
6
+ export * from './job.monitor.js';
5
7
  export * from './job.runner.js';
6
8
  export * from './not.supported.error.js';
7
9
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
package/dist/index.js CHANGED
@@ -1,8 +1,9 @@
1
1
  import {
2
2
  JobBroker,
3
+ JobMonitor,
3
4
  JobRunner,
4
5
  __name
5
- } from "./chunk-GKXLBFUJ.js";
6
+ } from "./chunk-VCGAI6CK.js";
6
7
 
7
8
  // src/job.ts
8
9
  import { Injectable } from "injectkit";
@@ -48,6 +49,7 @@ var NotSupportedError = class extends ServerkitError {
48
49
  export {
49
50
  Job,
50
51
  JobBroker,
52
+ JobMonitor,
51
53
  JobRunner,
52
54
  NotSupportedError
53
55
  };
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/job.ts","../src/not.supported.error.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for defining background jobs.\n *\n * Extend this class to create custom job handlers that can be executed\n * asynchronously by a {@link JobRunner}. Each job implementation defines\n * how to process a specific type of payload.\n *\n * @typeParam Payload - The type of data the job expects to receive.\n * Must be an object type. Defaults to `object`.\n *\n * @example\n * ```typescript\n * interface EmailPayload {\n * to: string;\n * subject: string;\n * body: string;\n * }\n *\n * @Injectable()\n * class SendEmailJob extends Job<EmailPayload> {\n * async run(payload: EmailPayload, signal?: AbortSignal): Promise<void> {\n * // Long-running work should honor the signal so the job can be cancelled.\n * await emailService.send(payload.to, payload.subject, payload.body, { signal });\n * if (signal?.aborted) return;\n * }\n * }\n * ```\n */\n@Injectable()\nexport abstract class Job<Payload extends object = object> {\n /**\n * Executes the job with the provided payload.\n *\n * This method is called by the job runner when a job is dequeued\n * and ready for processing. Implementations should contain the\n * business logic for handling the job.\n *\n * The optional `signal` is aborted when the job is cancelled (see\n * {@link JobBroker.cancel}) or when the runner shuts down. Cancellation is\n * cooperative: long-running handlers should forward `signal` to the async\n * operations they perform (fetch, database queries, etc.) or periodically\n * check `signal.aborted` and return early. A handler that ignores the signal\n * cannot be interrupted and will run to completion.\n *\n * @param payload - The data required to execute the job.\n * @param signal - An {@link AbortSignal} that fires when the job is cancelled\n * or the runner stops. Optional; handlers may ignore it.\n * @returns A promise that resolves when the job completes successfully.\n * @throws If the job fails, the error will be caught and logged by the runner.\n */\n abstract run(payload: Payload, signal?: AbortSignal): Promise<void>;\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Thrown by a {@link JobBroker} when a requested operation is not supported by\n * the underlying backend.\n *\n * Backends vary in what they can do: some queue implementations can cancel a\n * queued job but not look up its state, others cannot cancel individual jobs at\n * all. Rather than silently doing nothing (which hides bugs), a backend throws\n * this error from any capability it cannot honor.\n *\n * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and\n * the `withDetails` / `withCause` / `withInternalDetails` setters apply.\n *\n * The bundled pg-boss backend supports every operation and never throws this;\n * it exists as the shared vocabulary for future backends (e.g. SQS, Pub/Sub).\n *\n * @example\n * ```typescript\n * async cancel(): Promise<void> {\n * throw new NotSupportedError('cancel', 'sqs');\n * }\n * ```\n */\nexport class NotSupportedError extends ServerkitError {\n /** The name of the operation that is not supported (e.g. `'cancel'`). */\n readonly operation: string;\n /** The backend that does not support the operation, when known (e.g. `'sqs'`). */\n readonly backend?: string;\n\n /**\n * Creates a new NotSupportedError.\n *\n * @param operation - The name of the unsupported operation.\n * @param backend - The backend that does not support it, if known.\n */\n constructor(operation: string, backend?: string) {\n super(\n backend\n ? `Operation \"${operation}\" is not supported by the ${backend} job broker`\n : `Operation \"${operation}\" is not supported by this job broker`,\n );\n this.name = 'NotSupportedError';\n this.operation = operation;\n this.backend = backend;\n }\n}\n"],"mappings":";;;;;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+BpB,IAAeC,MAAf,MAAeA;SAAAA;;;AAsBtB;;;;;;ACrDA,SAASC,sBAAsB;AAwBxB,IAAMC,oBAAN,cAAgCC,eAAAA;EAxBvC,OAwBuCA;;;;EAE5BC;;EAEAC;;;;;;;EAQT,YAAYD,WAAmBC,SAAkB;AAC/C,UACEA,UACI,cAAcD,SAAAA,6BAAsCC,OAAAA,gBACpD,cAAcD,SAAAA,uCAAgD;AAEpE,SAAKE,OAAO;AACZ,SAAKF,YAAYA;AACjB,SAAKC,UAAUA;EACjB;AACF;","names":["Injectable","Job","ServerkitError","NotSupportedError","ServerkitError","operation","backend","name"]}
1
+ {"version":3,"sources":["../src/job.ts","../src/not.supported.error.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for defining background jobs.\n *\n * Extend this class to create custom job handlers that can be executed\n * asynchronously by a {@link JobRunner}. Each job implementation defines\n * how to process a specific type of payload.\n *\n * @typeParam Payload - The type of data the job expects to receive.\n * Must be an object type. Defaults to `object`.\n *\n * @example\n * ```typescript\n * interface EmailPayload {\n * to: string;\n * subject: string;\n * body: string;\n * }\n *\n * @Injectable()\n * class SendEmailJob extends Job<EmailPayload> {\n * async run(payload: EmailPayload, signal?: AbortSignal): Promise<void> {\n * // Long-running work should honor the signal so the job can be cancelled.\n * await emailService.send(payload.to, payload.subject, payload.body, { signal });\n * if (signal?.aborted) return;\n * }\n * }\n * ```\n */\n@Injectable()\nexport abstract class Job<Payload extends object = object> {\n /**\n * Executes the job with the provided payload.\n *\n * This method is called by the job runner when a job is dequeued\n * and ready for processing. Implementations should contain the\n * business logic for handling the job.\n *\n * The optional `signal` is aborted when the job is cancelled (see\n * {@link JobBroker.cancel}) or when the runner shuts down. Cancellation is\n * cooperative: long-running handlers should forward `signal` to the async\n * operations they perform (fetch, database queries, etc.) or periodically\n * check `signal.aborted` and return early. A handler that ignores the signal\n * cannot be interrupted and will run to completion.\n *\n * @param payload - The data required to execute the job.\n * @param signal - An {@link AbortSignal} that fires when the job is cancelled\n * or the runner stops. Optional; handlers may ignore it.\n * @returns A promise that resolves when the job completes successfully.\n * @throws If the job fails, the error will be caught and logged by the runner.\n */\n abstract run(payload: Payload, signal?: AbortSignal): Promise<void>;\n}\n","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Thrown by a {@link JobBroker} when a requested operation is not supported by\n * the underlying backend.\n *\n * Backends vary in what they can do: some queue implementations can cancel a\n * queued job but not look up its state, others cannot cancel individual jobs at\n * all. Rather than silently doing nothing (which hides bugs), a backend throws\n * this error from any capability it cannot honor.\n *\n * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and\n * the `withDetails` / `withCause` / `withInternalDetails` setters apply.\n *\n * The bundled pg-boss backend supports every operation and never throws this;\n * it exists as the shared vocabulary for future backends (e.g. SQS, Pub/Sub).\n *\n * @example\n * ```typescript\n * async cancel(): Promise<void> {\n * throw new NotSupportedError('cancel', 'sqs');\n * }\n * ```\n */\nexport class NotSupportedError extends ServerkitError {\n /** The name of the operation that is not supported (e.g. `'cancel'`). */\n readonly operation: string;\n /** The backend that does not support the operation, when known (e.g. `'sqs'`). */\n readonly backend?: string;\n\n /**\n * Creates a new NotSupportedError.\n *\n * @param operation - The name of the unsupported operation.\n * @param backend - The backend that does not support it, if known.\n */\n constructor(operation: string, backend?: string) {\n super(\n backend\n ? `Operation \"${operation}\" is not supported by the ${backend} job broker`\n : `Operation \"${operation}\" is not supported by this job broker`,\n );\n this.name = 'NotSupportedError';\n this.operation = operation;\n this.backend = backend;\n }\n}\n"],"mappings":";;;;;;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+BpB,IAAeC,MAAf,MAAeA;SAAAA;;;AAsBtB;;;;;;ACrDA,SAASC,sBAAsB;AAwBxB,IAAMC,oBAAN,cAAgCC,eAAAA;EAxBvC,OAwBuCA;;;;EAE5BC;;EAEAC;;;;;;;EAQT,YAAYD,WAAmBC,SAAkB;AAC/C,UACEA,UACI,cAAcD,SAAAA,6BAAsCC,OAAAA,gBACpD,cAAcD,SAAAA,uCAAgD;AAEpE,SAAKE,OAAO;AACZ,SAAKF,YAAYA;AACjB,SAAKC,UAAUA;EACjB;AACF;","names":["Injectable","Job","ServerkitError","NotSupportedError","ServerkitError","operation","backend","name"]}
@@ -0,0 +1,157 @@
1
+ import { JobInfo } from './job.info.js';
2
+ /**
3
+ * A backend-agnostic snapshot of a single queue's depth and health, as returned
4
+ * by {@link JobMonitor.getQueueStats}. Every count is a point-in-time reading;
5
+ * poll it on a schedule (for example from a reconciliation job) to drive
6
+ * alerting on a backlog or a growing dead-letter queue.
7
+ *
8
+ * The counts are the lowest common denominator every supported backend can
9
+ * report. `failed` in particular is a *retained* count: it reflects failures
10
+ * still held in the queue subject to the queue's retention policy, not an
11
+ * all-time total.
12
+ */
13
+ export interface JobQueueStats {
14
+ /** The queue name these stats describe. */
15
+ name: string;
16
+ /** Jobs waiting to be processed (enqueued but not yet active). */
17
+ queued: number;
18
+ /** Jobs currently being executed by a worker. */
19
+ active: number;
20
+ /** Failed jobs still retained in the queue (bounded by the retention policy). */
21
+ failed: number;
22
+ /** All jobs still retained for the queue across every state. */
23
+ total: number;
24
+ }
25
+ /**
26
+ * Filters for {@link JobMonitor.listJobs}. All fields are optional; omitting them
27
+ * lists every job currently retained in the queue (the common case when
28
+ * inspecting a small dead-letter queue).
29
+ */
30
+ export interface JobQueryOptions {
31
+ /** Match a single job by its id. */
32
+ id?: string;
33
+ /** Match jobs whose payload contains these fields (a partial-match filter). */
34
+ data?: Record<string, unknown>;
35
+ /** Restrict the result to jobs still waiting to be processed. */
36
+ queuedOnly?: boolean;
37
+ }
38
+ /**
39
+ * Options for {@link JobMonitor.redrive}, which moves dead-lettered jobs out of a
40
+ * queue and back into circulation.
41
+ */
42
+ export interface JobRedriveOptions {
43
+ /**
44
+ * The queue to move jobs into. When omitted, each job returns to the queue it
45
+ * originally came from before it was dead-lettered — the usual "reprocess"
46
+ * behavior. Supply this to funnel everything into a specific queue instead.
47
+ */
48
+ destination?: string;
49
+ /**
50
+ * Only redrive jobs that originated from this source queue. Useful when a
51
+ * single dead-letter queue collects failures from several source queues and
52
+ * you want to drain just one source's worth.
53
+ */
54
+ sourceName?: string;
55
+ /**
56
+ * Maximum number of jobs to move in this call, oldest first. Call repeatedly
57
+ * (or on a schedule) to drain a large dead-letter queue at a controlled rate.
58
+ */
59
+ limit?: number;
60
+ }
61
+ /**
62
+ * Read-and-remediate interface for job queues, and in particular for
63
+ * *dead-letter queues*: the queues that collect jobs which have exhausted their
64
+ * retries (see the queue policy on the pg-boss backend's registration).
65
+ *
66
+ * Where {@link JobBroker} is the producer side (enqueue, cancel, inspect a job
67
+ * you hold the id for) and {@link JobRunner} is the consumer side, `JobMonitor`
68
+ * is the operator side: it lets a consumer answer "how deep is this queue?",
69
+ * "what is stuck in this dead-letter queue?", and "reprocess / discard those
70
+ * jobs". Unlike the broker, it operates on raw queue names and does **not**
71
+ * require the queue to be registered, because a dead-letter queue is often an
72
+ * unregistered sink with no worker of its own.
73
+ *
74
+ * Backends that cannot honor an operation throw a `NotSupportedError` rather than
75
+ * silently doing nothing, matching the rest of the package. The bundled pg-boss
76
+ * backend supports every operation.
77
+ *
78
+ * @example
79
+ * ```typescript
80
+ * // A reconciliation sweep over a money-critical dead-letter queue.
81
+ * const stats = await monitor.getQueueStats('charge.webhook.dead');
82
+ * if (stats && stats.total > 0) {
83
+ * const stuck = await monitor.listJobs('charge.webhook.dead'); // inspect / log / alert
84
+ * const moved = await monitor.redrive('charge.webhook.dead', { limit: 100 }); // drain back
85
+ * }
86
+ * ```
87
+ */
88
+ export declare abstract class JobMonitor {
89
+ /**
90
+ * Reports the current depth and health of a queue.
91
+ *
92
+ * @param name - The queue name to inspect (may be an unregistered dead-letter queue).
93
+ * @returns A promise resolving to the {@link JobQueueStats}, or `null` if no
94
+ * queue with that name exists.
95
+ * @throws `NotSupportedError` if the backend cannot report queue statistics.
96
+ */
97
+ abstract getQueueStats(name: string): Promise<JobQueueStats | null>;
98
+ /**
99
+ * Lists the jobs currently retained in a queue, optionally filtered.
100
+ *
101
+ * The primary use is inspecting a dead-letter queue: the returned
102
+ * {@link JobInfo} objects expose each poison message's id, state, and original
103
+ * payload so a consumer can decide whether to reprocess ({@link redrive}),
104
+ * discard ({@link deleteJob}), or escalate it.
105
+ *
106
+ * @typeParam Payload - The type of the job payloads.
107
+ * @param name - The queue name to list (may be an unregistered dead-letter queue).
108
+ * @param options - Optional {@link JobQueryOptions} filters.
109
+ * @returns A promise resolving to the matching jobs (empty if none / no such queue).
110
+ * @throws `NotSupportedError` if the backend cannot enumerate jobs.
111
+ */
112
+ abstract listJobs<Payload extends object>(name: string, options?: JobQueryOptions): Promise<JobInfo<Payload>[]>;
113
+ /**
114
+ * Moves dead-lettered jobs out of a queue and back into circulation, returning
115
+ * the number of jobs moved.
116
+ *
117
+ * By default each job goes back to the source queue it was dead-lettered from,
118
+ * so a worker can process it again; pass {@link JobRedriveOptions.destination}
119
+ * to route them elsewhere, {@link JobRedriveOptions.sourceName} to drain only
120
+ * one source's jobs from a shared dead-letter queue, and
121
+ * {@link JobRedriveOptions.limit} to move at a controlled rate.
122
+ *
123
+ * @param name - The (dead-letter) queue to drain.
124
+ * @param options - Optional {@link JobRedriveOptions}.
125
+ * @returns A promise resolving to the count of jobs moved.
126
+ * @throws `NotSupportedError` if the backend cannot redrive jobs.
127
+ */
128
+ abstract redrive(name: string, options?: JobRedriveOptions): Promise<number>;
129
+ /**
130
+ * Permanently deletes one or more jobs from a queue.
131
+ *
132
+ * This is the "discard" action for a dead-letter queue: a poison message that
133
+ * should not be reprocessed is removed outright. Unlike {@link JobBroker.deleteJob},
134
+ * it does not require the queue to be registered.
135
+ *
136
+ * @param name - The queue name the jobs live in.
137
+ * @param id - A single job id, or an array of ids, to delete.
138
+ * @returns A promise that resolves once the jobs have been deleted.
139
+ * @throws `NotSupportedError` if the backend cannot delete jobs.
140
+ */
141
+ abstract deleteJob(name: string, id: string | string[]): Promise<void>;
142
+ /**
143
+ * Re-attempts one or more failed jobs *in place*, re-queuing them within their
144
+ * current queue.
145
+ *
146
+ * Use this to re-run a job that failed in a queue that has its own worker. To
147
+ * reprocess a job sitting in a dead-letter *sink* (a queue with no worker),
148
+ * prefer {@link redrive}, which moves it back to a queue that can run it.
149
+ *
150
+ * @param name - The queue name the jobs live in.
151
+ * @param id - A single job id, or an array of ids, to retry.
152
+ * @returns A promise that resolves once the jobs have been re-queued.
153
+ * @throws `NotSupportedError` if the backend cannot retry jobs.
154
+ */
155
+ abstract retryJob(name: string, id: string | string[]): Promise<void>;
156
+ }
157
+ //# sourceMappingURL=job.monitor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"job.monitor.d.ts","sourceRoot":"","sources":["../src/job.monitor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BACsB,UAAU;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAEnE;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,QAAQ,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;IAE/G;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAE5E;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAEtE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CACtE"}
@@ -0,0 +1,72 @@
1
+ import { Duration } from 'luxon';
2
+ /**
3
+ * Backend-agnostic reliability policy for a job *queue*: how many times a failed
4
+ * job is retried, how long to wait between attempts, how long a running job may
5
+ * take before it is considered stuck, and where a job goes once it has exhausted
6
+ * its retries.
7
+ *
8
+ * Like {@link JobSendOptions}, this type describes *intent* rather than any one
9
+ * backend's wire format. Retry, backoff, and dead-lettering are queue-level
10
+ * concepts on every mainstream queue (pg-boss `retryLimit`/`deadLetter`, SQS's
11
+ * redrive policy `maxReceiveCount` + DLQ ARN, Cloud Tasks' `maxAttempts` /
12
+ * `minBackoff`), so a policy declared here maps cleanly onto whichever backend
13
+ * is in use. A backend that cannot honor a requested knob throws a
14
+ * `NotSupportedError` rather than silently ignoring it.
15
+ *
16
+ * Because these are queue-level properties, the policy is declared where the job
17
+ * is registered (see the pg-boss `PgBossJobRegistration`), not per individual
18
+ * `send`. Deferring a single job is still a per-send concern (see
19
+ * {@link JobSendOptions.startAfter}); retry/dead-letter behavior is not.
20
+ *
21
+ * @example
22
+ * ```typescript
23
+ * const policy: JobQueuePolicy = {
24
+ * retryLimit: 5,
25
+ * retryDelay: Duration.fromObject({ seconds: 30 }),
26
+ * retryBackoff: true,
27
+ * deadLetter: 'charge.webhook.dead',
28
+ * };
29
+ * ```
30
+ */
31
+ export interface JobQueuePolicy {
32
+ /**
33
+ * How many times a failed job is retried before it is marked failed (and, if a
34
+ * {@link deadLetter} queue is set, dead-lettered). Omit to use the backend's
35
+ * default.
36
+ */
37
+ retryLimit?: number;
38
+ /**
39
+ * Delay to wait before retrying a failed job. When {@link retryBackoff} is
40
+ * enabled this is the *base* delay that the backoff curve grows from. Backends
41
+ * that measure retry delay in whole seconds receive this rounded to the
42
+ * nearest second.
43
+ */
44
+ retryDelay?: Duration;
45
+ /**
46
+ * Grow the delay between successive retries exponentially (with jitter)
47
+ * starting from {@link retryDelay}, instead of waiting a fixed
48
+ * {@link retryDelay} each time. Useful for backing off transient failures such
49
+ * as a rate-limited external API.
50
+ */
51
+ retryBackoff?: boolean;
52
+ /**
53
+ * Upper bound on the delay between retries when {@link retryBackoff} is
54
+ * enabled. Ignored for fixed-delay retries. Rounded to whole seconds for
55
+ * backends that require it.
56
+ */
57
+ retryDelayMax?: Duration;
58
+ /**
59
+ * How long a job may run before it is considered stuck and made eligible for
60
+ * retry (or failure). Maps onto pg-boss `expireInSeconds`, an SQS visibility
61
+ * timeout, and similar. Rounded to whole seconds for backends that require it.
62
+ */
63
+ expiresIn?: Duration;
64
+ /**
65
+ * Name of the dead-letter queue that receives a job once it has exhausted all
66
+ * of its retries, so terminal failures are preserved for inspection or replay
67
+ * instead of being dropped. The referenced queue must exist; backends that can
68
+ * do so (pg-boss) create it automatically when absent.
69
+ */
70
+ deadLetter?: string;
71
+ }
72
+ //# sourceMappingURL=job.queue.policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"job.queue.policy.d.ts","sourceRoot":"","sources":["../src/job.queue.policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC;IAErB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}