@maroonedsoftware/jobbroker 1.8.2 → 1.10.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
@@ -21,10 +23,10 @@ pnpm add @maroonedsoftware/jobbroker injectkit pg-boss reflect-metadata
21
23
 
22
24
  `pg-boss` is an optional peer dependency. The pg-boss backend lives behind a subpath export so importing the core (`@maroonedsoftware/jobbroker`) never loads it:
23
25
 
24
- | Import | Contents | Pulls in |
25
- | ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------- |
26
- | `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobInfo`, `JobState`, `NotSupportedError` | nothing extra |
27
- | `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
26
+ | Import | Contents | Pulls in |
27
+ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
28
+ | `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobMonitor`, `JobInfo`, `JobState`, `JobQueuePolicy`, `NotSupportedError` | nothing extra |
29
+ | `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobMonitor`, `PgBossJobRegistryMap`, `PgBossConnectionProvider`, `KyselyTransactionConnectionProvider` | `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,14 @@ 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 {
101
+ PgBossJobBroker,
102
+ PgBossJobRunner,
103
+ PgBossJobMonitor,
104
+ PgBossJobRegistryMap,
105
+ PgBossConnectionProvider,
106
+ } from '@maroonedsoftware/jobbroker/pgboss';
88
107
 
89
108
  // Initialize pg-boss
90
109
  const pgboss = new PgBoss('postgres://user:pass@localhost/mydb');
@@ -98,6 +117,7 @@ diRegistry.register(Logger).useClass(ConsoleLogger).asSingleton();
98
117
  diRegistry.register(PgBossConnectionProvider).useClass(PgBossConnectionProvider).asSingleton();
99
118
  diRegistry.register(JobBroker).useClass(PgBossJobBroker).asSingleton();
100
119
  diRegistry.register(JobRunner).useClass(PgBossJobRunner).asSingleton();
120
+ diRegistry.register(JobMonitor).useClass(PgBossJobMonitor).asSingleton();
101
121
 
102
122
  // Build the container
103
123
  const container = diRegistry.build();
@@ -160,11 +180,85 @@ runner.cancelPollIntervalSeconds = 2; // default 5; set to 0 to disable polling
160
180
 
161
181
  Lower values reduce cancellation latency at the cost of one extra lookup query per running job per interval.
162
182
 
183
+ ## Retry & dead-letter policy
184
+
185
+ 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.
186
+
187
+ 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):
188
+
189
+ ```typescript
190
+ import { Duration } from 'luxon';
191
+
192
+ registry.set('deliver-webhook', {
193
+ job: DeliverWebhookJob,
194
+ policy: {
195
+ retryLimit: 5, // attempts before the job is failed / dead-lettered
196
+ retryDelay: Duration.fromObject({ seconds: 30 }), // base delay between attempts
197
+ retryBackoff: true, // grow the delay exponentially (with jitter) from retryDelay
198
+ retryDelayMax: Duration.fromObject({ minutes: 10 }), // cap for the backoff curve
199
+ expiresIn: Duration.fromObject({ minutes: 2 }), // a run is considered stuck after this
200
+ deadLetter: 'deliver-webhook-dead', // where exhausted jobs land
201
+ },
202
+ });
203
+ ```
204
+
205
+ 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.
206
+
207
+ **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.
208
+
209
+ 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:
210
+
211
+ ```typescript
212
+ const runner = container.get(JobRunner) as PgBossJobRunner;
213
+ runner.defaultQueuePolicy = {
214
+ retryLimit: 3,
215
+ retryBackoff: true,
216
+ retryDelay: Duration.fromObject({ seconds: 10 }),
217
+ };
218
+ await runner.start();
219
+ ```
220
+
221
+ 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.
222
+
223
+ ## Monitoring & draining dead-letter queues
224
+
225
+ 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.
226
+
227
+ ```typescript
228
+ const monitor = container.get(JobMonitor);
229
+
230
+ // Observe — poll depth/health (e.g. from a reconciliation cron) to alert on a growing DLQ
231
+ const stats = await monitor.getQueueStats('deliver-webhook-dead');
232
+ // stats: { name, queued, active, failed, total } | null (null when the queue does not exist)
233
+
234
+ if (stats && stats.total > 0) {
235
+ // Retrieve — inspect the poison messages (id, state, original payload)
236
+ const stuck = await monitor.listJobs<WebhookPayload>('deliver-webhook-dead');
237
+ logger.warn(`${stuck.length} webhooks in the dead-letter queue`, { ids: stuck.map(j => j.id) });
238
+
239
+ // Act — move them back to their original source queue to reprocess, oldest first, rate-limited
240
+ const moved = await monitor.redrive('deliver-webhook-dead', { limit: 100 });
241
+
242
+ // ...or discard a specific unrecoverable message
243
+ await monitor.deleteJob('deliver-webhook-dead', stuck[0].id);
244
+ }
245
+ ```
246
+
247
+ | Method | Description |
248
+ | ----------------------------- | --------------------------------------------------------------------------------------------------- |
249
+ | `getQueueStats(name)` | Point-in-time `{ name, queued, active, failed, total }`, or `null` if the queue does not exist. |
250
+ | `listJobs<P>(name, options?)` | List retained jobs as `JobInfo<P>[]`; filter by `id`, partial `data`, or `queuedOnly`. |
251
+ | `redrive(name, options?)` | Move dead-lettered jobs back to their source (or a `destination`), oldest first; returns count. |
252
+ | `deleteJob(name, id)` | Permanently discard one or more jobs (no registry check, so DLQ sinks are serviceable). |
253
+ | `retryJob(name, id)` | Re-attempt failed jobs **in place**; for a DLQ sink prefer `redrive`, which moves them to a worker. |
254
+
255
+ `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)).
256
+
163
257
  ### Backend portability
164
258
 
165
259
  `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.
166
260
 
167
- `send`'s `startAfter` is deliberately expressed as *intent* (a relative `Duration` or an absolute `DateTime`), not a wire format, so it maps cleanly onto each backend's native deferral mechanism — pg-boss `startAfter` (unbounded), SQS `DelaySeconds` (max 15 minutes), Cloud Tasks `scheduleTime` (up to 30 days). A backend that cannot honor a requested delay (e.g. an SQS backend asked for a 1-hour delay) throws `NotSupportedError` rather than clamping silently.
261
+ `send`'s `startAfter` is deliberately expressed as _intent_ (a relative `Duration` or an absolute `DateTime`), not a wire format, so it maps cleanly onto each backend's native deferral mechanism — pg-boss `startAfter` (unbounded), SQS `DelaySeconds` (max 15 minutes), Cloud Tasks `scheduleTime` (up to 30 days). A backend that cannot honor a requested delay (e.g. an SQS backend asked for a 1-hour delay) throws `NotSupportedError` rather than clamping silently.
168
262
 
169
263
  ## API Reference
170
264
 
@@ -180,15 +274,15 @@ Abstract base class for job handlers.
180
274
 
181
275
  Abstract base class for sending, cancelling, and inspecting jobs. Operations a backend cannot honor throw `NotSupportedError`.
182
276
 
183
- | Method | Description |
184
- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
277
+ | Method | Description |
278
+ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
185
279
  | `send<P>(name: string, payload: P, options?: JobSendOptions): Promise<string>` | Queue a job; resolves with the new job id. Pass `options.startAfter` (a Luxon `Duration` or `DateTime`) to defer it |
186
- | `schedule<P>(name: string, cron: string, payload?: P): Promise<void>` | Create a recurring job schedule |
187
- | `unschedule(name: string): Promise<void>` | Remove a recurring job schedule |
188
- | `cancel(name: string, id: string \| string[]): Promise<void>` | Request cancellation of queued or running jobs (cooperative) |
189
- | `resume(name: string, id: string \| string[]): Promise<void>` | Re-queue previously cancelled jobs |
190
- | `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently delete jobs |
191
- | `getJob<P>(name: string, id: string): Promise<JobInfo<P> \| null>` | Look up a job's current state, or `null` if it does not exist |
280
+ | `schedule<P>(name: string, cron: string, payload?: P): Promise<void>` | Create a recurring job schedule |
281
+ | `unschedule(name: string): Promise<void>` | Remove a recurring job schedule |
282
+ | `cancel(name: string, id: string \| string[]): Promise<void>` | Request cancellation of queued or running jobs (cooperative) |
283
+ | `resume(name: string, id: string \| string[]): Promise<void>` | Re-queue previously cancelled jobs |
284
+ | `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently delete jobs |
285
+ | `getJob<P>(name: string, id: string): Promise<JobInfo<P> \| null>` | Look up a job's current state, or `null` if it does not exist |
192
286
 
193
287
  ### `JobInfo<Payload>` / `JobState`
194
288
 
@@ -203,6 +297,20 @@ Abstract base class for processing jobs from the queue.
203
297
  | `start(): Promise<void>` | Start processing jobs |
204
298
  | `stop(): Promise<void>` | Gracefully stop processing |
205
299
 
300
+ ### `JobMonitor`
301
+
302
+ 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).
303
+
304
+ | Method | Description |
305
+ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
306
+ | `getQueueStats(name: string): Promise<JobQueueStats \| null>` | Queue depth/health counts, or `null` if the queue does not exist |
307
+ | `listJobs<P>(name: string, options?: JobQueryOptions): Promise<JobInfo<P>[]>` | List retained jobs, optionally filtered by `id`, `data`, or `queuedOnly` |
308
+ | `redrive(name: string, options?: JobRedriveOptions): Promise<number>` | Move dead-lettered jobs back to source (or a `destination`); returns count moved |
309
+ | `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently discard jobs |
310
+ | `retryJob(name: string, id: string \| string[]): Promise<void>` | Re-attempt failed jobs in place |
311
+
312
+ `JobQueueStats` is `{ name, queued, active, failed, total }`. `JobQueryOptions` is `{ id?, data?, queuedOnly? }`. `JobRedriveOptions` is `{ destination?, sourceName?, limit? }`.
313
+
206
314
  ### `PgBossJobRegistryMap`
207
315
 
208
316
  A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
@@ -210,16 +318,30 @@ A `Map<string, Identifier<Job> | PgBossJobRegistration>` for registering jobs.
210
318
  Entries can be either:
211
319
 
212
320
  - A job class identifier (for on-demand jobs)
213
- - A `PgBossJobRegistration` object with `job` and `cron` properties (for scheduled jobs)
321
+ - A `PgBossJobRegistration` object (for scheduled jobs, jobs with a queue policy, or both)
214
322
 
215
323
  ### `PgBossJobRegistration`
216
324
 
217
- Configuration object for a scheduled job.
325
+ 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.
326
+
327
+ | Property | Type | Description |
328
+ | -------- | ----------------- | -------------------------------------------------------------------- |
329
+ | `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
330
+ | `cron` | `string` | Optional cron expression defining when the job should run. |
331
+ | `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
332
+
333
+ ### `JobQueuePolicy`
334
+
335
+ 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.
218
336
 
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. |
337
+ | Property | Type | Description |
338
+ | --------------- | ---------- | ------------------------------------------------------------------------------------ |
339
+ | `retryLimit` | `number` | Attempts before a job is failed (and dead-lettered, if `deadLetter` is set). |
340
+ | `retryDelay` | `Duration` | Delay before retrying; the base of the curve when `retryBackoff` is on. |
341
+ | `retryBackoff` | `boolean` | Grow the retry delay exponentially (with jitter) from `retryDelay` instead of fixed. |
342
+ | `retryDelayMax` | `Duration` | Upper bound on the backoff delay. Only used when `retryBackoff` is on. |
343
+ | `expiresIn` | `Duration` | How long a run may take before it is considered stuck and made eligible for retry. |
344
+ | `deadLetter` | `string` | Name of the dead-letter queue that receives jobs which exhaust their retries. |
223
345
 
224
346
  ### `PgBossJobBroker`
225
347
 
@@ -235,27 +357,26 @@ Supplies the pg-boss `db` executor used when enqueuing or scheduling jobs.
235
357
 
236
358
  The default implementation returns `undefined`, so pg-boss uses its own connection pool (standard, non-transactional behavior). Override it on a request-scoped DI container to return a transaction-bound executor and enqueue jobs atomically with the surrounding database transaction — see [Transactional enqueue](#transactional-enqueue).
237
359
 
238
- ## Transactional enqueue
360
+ ### `KyselyTransactionConnectionProvider`
239
361
 
240
- By default a job row is inserted on pg-boss's own connection, so it commits independently of any database work happening in the same request. To make an enqueue commit (or roll back) together with your business writes, override `PgBossConnectionProvider` in the request scope so its `executor()` returns the active transaction's connection. pg-boss ships adapters for the common query builders (`fromKysely`, `fromKnex`, `fromDrizzle`, `fromPrisma`) that wrap a transaction into the executor shape pg-boss expects:
362
+ `PgBossConnectionProvider` bound to an active Kysely transaction. Constructor signature: `new KyselyTransactionConnectionProvider(trx: KyselyLike)`. Register it as a request-scoped override of `PgBossConnectionProvider` and every enqueue performed during the request inserts on the transaction's connection, so the job row and the surrounding writes commit or roll back together.
241
363
 
242
- ```typescript
243
- import { fromKysely } from 'pg-boss';
244
- import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
364
+ The constructor takes `KyselyLike`, a structural type satisfied by both `Kysely<DB>` and `Transaction<DB>` with no type argument or cast. Declaring it structurally means the package has no dependency on `kysely`, not even an optional peer.
245
365
 
246
- class TransactionalConnectionProvider extends PgBossConnectionProvider {
247
- constructor(private readonly trx: Transaction<DB>) {
248
- super();
249
- }
366
+ Plugins are stripped (`withoutPlugins()`) before the transaction is adapted: pg-boss runs raw SQL straight through `executeQuery`, so a column-rewriting plugin on the caller's instance would corrupt pg-boss's own result columns. The stripped instance shares the same connection-bound executor, so atomicity is preserved.
250
367
 
251
- override executor() {
252
- return fromKysely(this.trx);
253
- }
254
- }
368
+ ## Transactional enqueue
369
+
370
+ By default a job row is inserted on pg-boss's own connection, so it commits independently of any database work happening in the same request. To make an enqueue commit (or roll back) together with your business writes, override `PgBossConnectionProvider` in the request scope so its `executor()` returns the active transaction's connection.
371
+
372
+ For Kysely, `KyselyTransactionConnectionProvider` does this for you:
373
+
374
+ ```typescript
375
+ import { PgBossConnectionProvider, KyselyTransactionConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
255
376
 
256
377
  // Inside a transaction, bind the provider on the scoped container before resolving the broker:
257
378
  await repository.withTransaction(async trx => {
258
- scopedContainer.override(PgBossConnectionProvider, new TransactionalConnectionProvider(trx));
379
+ scopedContainer.override(PgBossConnectionProvider, new KyselyTransactionConnectionProvider(trx));
259
380
 
260
381
  await doBusinessWrites(trx);
261
382
  await scopedContainer.get(JobBroker).send('send-email', { to: 'user@example.com' });
@@ -263,12 +384,35 @@ await repository.withTransaction(async trx => {
263
384
  });
264
385
  ```
265
386
 
387
+ For the other query builders, pg-boss ships adapters (`fromKnex`, `fromDrizzle`, `fromPrisma`) that wrap a transaction into the executor shape pg-boss expects. Subclass the provider yourself:
388
+
389
+ ```typescript
390
+ import { fromKnex } from 'pg-boss';
391
+ import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
392
+
393
+ class KnexTransactionConnectionProvider extends PgBossConnectionProvider {
394
+ constructor(private readonly trx: Knex.Transaction) {
395
+ super();
396
+ }
397
+
398
+ override executor() {
399
+ return fromKnex(this.trx);
400
+ }
401
+ }
402
+ ```
403
+
266
404
  ### `PgBossJobRunner`
267
405
 
268
406
  Concrete `JobRunner` implementation backed by pg-boss. Constructor signature: `new PgBossJobRunner(container: Container, registrations: PgBossJobRegistryMap, pgboss: PgBoss, logger: Logger)`. Calls `pgboss.start()` during `start()` and `pgboss.stop()` during `stop()`. Job instances are resolved from the DI container on each invocation. Typically resolved through the DI container rather than instantiated directly.
269
407
 
270
408
  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
409
 
410
+ 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).
411
+
412
+ ### `PgBossJobMonitor`
413
+
414
+ 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.
415
+
272
416
  ## Graceful Shutdown
273
417
 
274
418
  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"}