@maroonedsoftware/jobbroker 1.11.5 → 1.12.1

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/AGENTS.md CHANGED
@@ -40,40 +40,42 @@ Notably **not** a dependency: `kysely`. Transactional enqueue is supported throu
40
40
 
41
41
  ### `.` — abstractions
42
42
 
43
- | Export | Kind | Shape | Notes |
44
- | ------------------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
45
- | `Job<Payload>` | abstract class | `@Injectable() abstract run(payload: Payload, signal?: AbortSignal): Promise<void>` | `Payload extends object = object`. |
46
- | `JobBroker` | abstract class | `@Injectable()`. Producer side. | Unsupported operations throw `NotSupportedError` rather than no-op. |
47
- | `#send` | method | `<P extends object>(name: string, payload: P, options?: JobSendOptions) => Promise<string>` | Returns the job id. Throws if `name` is not registered. |
48
- | `#schedule` | method | `<P extends object>(name: string, cron: string, payload?: P) => Promise<void>` | — |
49
- | `#unschedule` | method | `(name: string) => Promise<void>` | — |
50
- | `#cancel` / `#resume` / `#deleteJob` | method | `(name: string, id: string \| string[]) => Promise<void>` | `cancel` aborts the signal for a running job. |
51
- | `#getJob` | method | `<P extends object>(name: string, id: string) => Promise<JobInfo<P> \| null>` | — |
52
- | `JobRunner` | abstract class | `@Injectable()`. `start()`, `stop()` | Consumer side. `stop()` waits for in-flight jobs. |
53
- | `JobMonitor` | abstract class | `@Injectable()`. `getQueueStats`, `listJobs`, `redrive`, `deleteJob`, `retryJob` | Operational surface — dashboards, dead-letter drains. |
54
- | `JobContext` | interface + abstract class | `{ id: string; name: string; signal: AbortSignal; expiresIn?: Duration }` | Declaration-merged so one symbol is both the type and the DI token. |
55
- | `registerJobContext` | function | `<T extends Registry>(registry: T) => T` | **Required** if any service injects `JobContext`. Registers a throwing placeholder. |
56
- | `JobSendOptions` | interface | `{ startAfter?: Duration \| DateTime }` | Relative delay or absolute earliest-run time. A lower bound, not exact scheduling. |
57
- | `JobQueuePolicy` | interface | `{ retryLimit?, retryDelay?: Duration, retryBackoff?, retryDelayMax?: Duration, expiresIn?: Duration, deadLetter?: string }` | Applied per queue when the runner starts. `expiresIn` is what surfaces as `JobContext.expiresIn`. |
58
- | `JobInfo<Payload>` | interface | `{ id, name, state: JobState, data: Payload }` | Lowest common denominator across backends. |
59
- | `JobState` | type | `'created' \| 'retry' \| 'active' \| 'completed' \| 'cancelled' \| 'failed'` | — |
60
- | `JobQueueStats` | interface | `{ name, queued, active, failed, total }` | `failed` is a **retained** count, not an all-time total. |
61
- | `JobQueryOptions` | interface | `{ id?, data?: Record<string, unknown>, queuedOnly? }` | `data` is a partial-match payload filter. |
62
- | `JobRedriveOptions` | interface | `{ destination?, sourceName?, limit? }` | Without `destination`, each job returns to its original queue. |
63
- | `NotSupportedError` | class | `extends ServerkitError` | Thrown by a backend that cannot honour an operation. |
43
+ | Export | Kind | Shape | Notes |
44
+ | ------------------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
45
+ | `Job<Payload>` | abstract class | `@Injectable() abstract run(payload: Payload, signal?: AbortSignal): Promise<void>` | `Payload extends object = object`. |
46
+ | `JobBroker` | abstract class | `@Injectable()`. Producer side. | Unsupported operations throw `NotSupportedError` rather than no-op. |
47
+ | `#send` | method | `<P extends object>(name: string, payload: P, options?: JobSendOptions) => Promise<string>` | Returns the job id. Throws if `name` is not registered. |
48
+ | `#schedule` | method | `<P extends object>(name: string, cron: string, payload?: P) => Promise<void>` | — |
49
+ | `#unschedule` | method | `(name: string) => Promise<void>` | — |
50
+ | `#cancel` / `#resume` / `#deleteJob` | method | `(name: string, id: string \| string[]) => Promise<void>` | `cancel` aborts the signal for a running job. |
51
+ | `#getJob` | method | `<P extends object>(name: string, id: string) => Promise<JobInfo<P> \| null>` | — |
52
+ | `JobRunner` | abstract class | `@Injectable()`. `start()`, `stop()` | Consumer side. `stop()` waits for in-flight jobs. |
53
+ | `JobMonitor` | abstract class | `@Injectable()`. `getQueueStats`, `listJobs`, `redrive`, `deleteJob`, `retryJob` | Operational surface — dashboards, dead-letter drains. |
54
+ | `JobContext` | interface + abstract class | `{ id: string; name: string; signal: AbortSignal; expiresIn?: Duration }` | Declaration-merged so one symbol is both the type and the DI token. |
55
+ | `registerJobContext` | function | `<T extends Registry>(registry: T) => T` | **Required** if any service injects `JobContext`. Registers a throwing placeholder. |
56
+ | `JobSendOptions` | interface | `{ startAfter?: Duration \| DateTime }` | Relative delay or absolute earliest-run time. A lower bound, not exact scheduling. |
57
+ | `JobQueuePolicy` | interface | `{ retryLimit?, retryDelay?: Duration, retryBackoff?, retryDelayMax?: Duration, expiresIn?: Duration, deadLetter?: string }` | Applied per queue when the runner starts. `expiresIn` is what surfaces as `JobContext.expiresIn`. |
58
+ | `JobWorkerPolicy` | interface | `{ concurrency?: number, batchSize?: number, pollInterval?: Duration }` | Configures the worker **this node** starts, not the queue. Applied when the runner registers the worker. |
59
+ | `JobInfo<Payload>` | interface | `{ id, name, state: JobState, data: Payload }` | Lowest common denominator across backends. |
60
+ | `JobState` | type | `'created' \| 'retry' \| 'active' \| 'completed' \| 'cancelled' \| 'failed'` | — |
61
+ | `JobQueueStats` | interface | `{ name, queued, active, failed, total }` | `failed` is a **retained** count, not an all-time total. |
62
+ | `JobQueryOptions` | interface | `{ id?, data?: Record<string, unknown>, queuedOnly? }` | `data` is a partial-match payload filter. |
63
+ | `JobRedriveOptions` | interface | `{ destination?, sourceName?, limit? }` | Without `destination`, each job returns to its original queue. |
64
+ | `NotSupportedError` | class | `extends ServerkitError` | Thrown by a backend that cannot honour an operation. |
65
+ | `PermanentJobError` | class | `extends ServerkitError`. `new (message, options?: { cause?: unknown })` | Thrown by a job to skip its remaining retries and dead-letter immediately. Matched by direct `instanceof`. |
64
66
 
65
67
  ### `./pgboss`
66
68
 
67
- | Export | Kind | Shape | Notes |
68
- | ------------------------------------- | --------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
69
- | `PgBossJobBroker` | class | `extends JobBroker` | Supports every `JobBroker` operation. |
70
- | `PgBossJobRunner` | class | `extends JobRunner` | Creates the per-execution scope and registers the live `JobContext`. |
71
- | `PgBossJobMonitor` | class | `extends JobMonitor` | — |
72
- | `PgBossJobRegistration` | type | `{ job: Identifier<Job>; cron?: string; policy?: JobQueuePolicy }` | — |
73
- | `PgBossJobRegistryMap` | class | `extends Map<string, Identifier<Job> \| PgBossJobRegistration>` | Job name → handler. Read by both the broker (validation) and the runner. |
74
- | `PgBossConnectionProvider` | class | `@Injectable()`. `executor(): Db \| undefined` | Default returns `undefined` — pg-boss uses its own pool. |
75
- | `KyselyTransactionConnectionProvider` | class | `extends PgBossConnectionProvider`. `new (trx: KyselyLike)` | Enqueue inside the caller's transaction. Strips Kysely plugins first. |
76
- | `KyselyLike` | interface | `{ withoutPlugins(): … }` | Structural, so no `kysely` dependency. Accepts `Kysely<DB>` and `Transaction<DB>`. |
69
+ | Export | Kind | Shape | Notes |
70
+ | ------------------------------------- | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
71
+ | `PgBossJobBroker` | class | `extends JobBroker` | Supports every `JobBroker` operation. |
72
+ | `PgBossJobRunner` | class | `extends JobRunner` | Creates the per-execution scope and registers the live `JobContext`. Fields: `cancelPollIntervalSeconds`, `defaultQueuePolicy`, `defaultWorkerPolicy`. |
73
+ | `PgBossJobMonitor` | class | `extends JobMonitor` | — |
74
+ | `PgBossJobRegistration` | type | `{ job: Identifier<Job>; cron?: string; policy?: JobQueuePolicy; worker?: JobWorkerPolicy }` | `policy` configures the queue, `worker` configures this node's worker. |
75
+ | `PgBossJobRegistryMap` | class | `extends Map<string, Identifier<Job> \| PgBossJobRegistration>` | Job name → handler. Read by both the broker (validation) and the runner. |
76
+ | `PgBossConnectionProvider` | class | `@Injectable()`. `executor(): Db \| undefined` | Default returns `undefined` — pg-boss uses its own pool. |
77
+ | `KyselyTransactionConnectionProvider` | class | `extends PgBossConnectionProvider`. `new (trx: KyselyLike)` | Enqueue inside the caller's transaction. Strips Kysely plugins first. |
78
+ | `KyselyLike` | interface | `{ withoutPlugins(): … }` | Structural, so no `kysely` dependency. Accepts `Kysely<DB>` and `Transaction<DB>`. |
77
79
 
78
80
  ## Canonical usage
79
81
 
@@ -106,6 +108,10 @@ jobs.set('webhook.deliver', {
106
108
  job: DeliverWebhookJob,
107
109
  policy: { retryLimit: 5, retryDelay: Duration.fromObject({ seconds: 30 }), retryBackoff: true, deadLetter: 'webhook.deliver.dead' },
108
110
  });
111
+ jobs.set('image.thumbnail', { job: ThumbnailJob, worker: { concurrency: 8 } });
112
+
113
+ // Inside a handler: skip the retries for input that can never succeed.
114
+ // throw new PermanentJobError('Malformed payload').withDetails({ issues });
109
115
 
110
116
  registerJobContext(registry); // required because services inject JobContext
111
117
  registry.register(PgBossJobRegistryMap).useValue(jobs);
@@ -151,6 +157,12 @@ See [.claude/skills/job](../../.claude/skills/job) for the generator and its exa
151
157
  - Use `startAfter` with a Luxon `Duration` or `DateTime`, never a millisecond number.
152
158
  - Give any queue that talks to an external service a `JobQueuePolicy` with `retryBackoff` and a
153
159
  `deadLetter` queue. Without one you get the backend's defaults and no dead-letter capture.
160
+ - A queue that is falling behind gets `worker: { concurrency: n }`, **not** `batchSize`. See the
161
+ gotcha below — they are not interchangeable.
162
+ - Throw `PermanentJobError` for input that can never succeed (a malformed payload, a `422` from a
163
+ receiver), and a plain `Error` for anything that might succeed on a retry (a timeout, a `503`, a
164
+ rate limit). Getting this backwards either burns a retry budget on a hopeless job or dead-letters a
165
+ blip on its first attempt. When in doubt, a plain `Error` is the safe default — it retries.
154
166
  - Import pg-boss classes from `@maroonedsoftware/jobbroker/pgboss`, never from the root.
155
167
  - Wire `runner.start()` into a module's `ready` hook and `runner.stop()` into `shutdown`. Starting
156
168
  in `start` delays boot for every module after it.
@@ -169,6 +181,30 @@ See [.claude/skills/job](../../.claude/skills/job) for the generator and its exa
169
181
  - **A backend that cannot honour an option throws `NotSupportedError`** rather than silently
170
182
  ignoring it. SQS caps delays at 15 minutes, for instance. pg-boss supports everything, so this
171
183
  only bites on a backend swap.
184
+ - **`JobWorkerPolicy.concurrency` and `batchSize` are not interchangeable.** `concurrency` spawns
185
+ N independent workers, each fetching and settling its own job. `batchSize` makes _one_ worker
186
+ fetch N jobs and hand them to the handler together, trading round trips for latency on any one
187
+ job. Failure isolation is _not_ part of that trade — the runner reports a per-job outcome, so a
188
+ poison message in a batch fails alone. Prefer `concurrency` for throughput anyway.
189
+ - **The runner always registers workers with `perJobResults: true`**, so its handler resolves with a
190
+ `JobResult[]` instead of throwing. This is not optional and not tied to `batchSize`: it is what
191
+ makes per-job settlement work, and the only route pg-boss offers to the `deadletter` disposition
192
+ that `PermanentJobError` needs. Throwing from the handler still fails the _whole_ batch, which is
193
+ correct for a runner-level bug but wrong for a job-level one — never rethrow a job's error there.
194
+ - **A job omitted from the returned `JobResult[]` is failed by pg-boss**, with
195
+ `Error('no disposition returned by handler')`, and retried. Silence is not success, which is why
196
+ the runner maps over `jobs` rather than over the `allSettled` results.
197
+ - **`PermanentJobError` is matched by direct `instanceof`, not by walking the `cause` chain.** The
198
+ meaning is "this handler declared the failure permanent". Wrapping a transient error in one makes
199
+ it permanent; a transient error that merely carries one as its cause stays retryable.
200
+ - **`JobWorkerPolicy` is not stored on the queue.** Unlike `JobQueuePolicy`, which the runner
201
+ reconciles onto the queue via `createQueue`/`updateQueue`, a worker policy configures only the
202
+ workers _this process_ starts. Two nodes on the same queue may use different values, and a change
203
+ takes effect on the next runner start for that node alone.
204
+ - **The peer floor is pg-boss >= 12.21.0**, and it is load-bearing. `concurrency` maps to
205
+ `localConcurrency` (added in 12.6.0) and per-job settlement to `perJobResults` (added in 12.21.0).
206
+ An older peer would ignore `perJobResults`, take the handler's `JobResult[]` as the batch's single
207
+ output, and mark **every job complete, including the failed ones**.
172
208
  - **`JobQueueStats.failed` is a retained count**, bounded by the queue's retention policy, not an
173
209
  all-time total. It goes down on its own.
174
210
  - **`KyselyTransactionConnectionProvider` strips plugins before adapting the transaction.**
@@ -198,7 +234,9 @@ src/
198
234
  job.info.ts JobState, JobInfo
199
235
  job.send.options.ts JobSendOptions
200
236
  job.queue.policy.ts JobQueuePolicy
237
+ job.worker.policy.ts JobWorkerPolicy
201
238
  not.supported.error.ts NotSupportedError
239
+ permanent.job.error.ts PermanentJobError
202
240
  pgboss.ts Subpath entry for ./pgboss
203
241
  pgboss/
204
242
  pgboss.job.broker.ts
package/README.md CHANGED
@@ -10,6 +10,9 @@ A flexible background job processing library with support for scheduled and on-d
10
10
  - **On-demand jobs** for immediate execution
11
11
  - **Cancellation** of queued _and_ running jobs, plus state lookup, delete, and resume
12
12
  - **Per-queue retry & dead-letter policy** for retry limits, backoff, and poison-message capture
13
+ - **Per-queue worker policy** for concurrency, batch size, and poll interval
14
+ - **Per-job settlement** so one failing job in a batch never drags its siblings into retry
15
+ - **Permanent failures** that skip remaining retries and dead-letter immediately
13
16
  - **Dead-letter monitoring** to inspect, redrive, retry, or discard failed jobs
14
17
  - **PostgreSQL backing** for reliability and transactional guarantees
15
18
 
@@ -263,6 +266,71 @@ await runner.start();
263
266
 
264
267
  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.
265
268
 
269
+ ## Permanent failures
270
+
271
+ Retries exist for failures that might not happen next time — a timeout, a rate limit, a deploy in progress. They are wasted on a job that can never succeed: a malformed payload, a `422` from a receiver that will reject the same body every time. A queue with `retryLimit: 5` and exponential backoff will spend hours re-running such a job before it finally dead-letters.
272
+
273
+ Throw a `PermanentJobError` to skip straight to the end:
274
+
275
+ ```typescript
276
+ import { Job, PermanentJobError } from '@maroonedsoftware/jobbroker';
277
+
278
+ class DeliverWebhookJob extends Job<DeliverWebhookPayload> {
279
+ async run(payload: DeliverWebhookPayload): Promise<void> {
280
+ const parsed = webhookSchema.safeParse(payload);
281
+ if (!parsed.success) {
282
+ throw new PermanentJobError('Malformed webhook payload').withDetails({ issues: parsed.error.issues });
283
+ }
284
+
285
+ const response = await fetch(parsed.data.url, { method: 'POST', body: parsed.data.body });
286
+ if (response.status === 422) {
287
+ throw new PermanentJobError(`Receiver rejected the payload with ${response.status}`);
288
+ }
289
+ if (!response.ok) {
290
+ throw new Error(`Delivery failed with ${response.status}`); // transient — let it retry
291
+ }
292
+ }
293
+ }
294
+ ```
295
+
296
+ The job goes straight to the queue's `deadLetter` queue on its first attempt, with the error as its output, where [`JobMonitor`](#monitoring--draining-dead-letter-queues) can inspect or redrive it. A queue with no dead-letter queue simply fails the job terminally. Anything attached with `withDetails` is persisted alongside it — worth using, since that is what an operator reads when draining the queue.
297
+
298
+ The match is a direct `instanceof`, deliberately: it means "this handler declared the failure permanent", not "something permanent happened somewhere underneath". Wrapping a transient error in a `PermanentJobError` makes it permanent; a transient error that merely _has_ a `PermanentJobError` as its cause stays retryable.
299
+
300
+ ## Worker concurrency
301
+
302
+ Out of the box each queue is consumed by a single worker fetching one job at a time — safe, and slow if a queue is busy. A `JobWorkerPolicy` on the registration says how much of this node's capacity the queue gets:
303
+
304
+ ```typescript
305
+ import { Duration } from 'luxon';
306
+
307
+ registry.set('image.thumbnail', {
308
+ job: ThumbnailJob,
309
+ worker: {
310
+ concurrency: 8, // run up to 8 of these at once on this node
311
+ pollInterval: Duration.fromObject({ seconds: 1 }), // check for work this often when idle
312
+ },
313
+ });
314
+ ```
315
+
316
+ `concurrency` is the knob you want when a queue is falling behind. Each unit is an independent worker that fetches and settles its own job, so one job failing has no effect on its siblings.
317
+
318
+ `batchSize` is the other one, and it is **not** a synonym. It makes a single worker fetch that many jobs and hand them to the handler together, trading round trips for latency on any single job. Each job in the batch still settles on its own — the runner reports a per-job outcome, so one poison message fails, retries, and dead-letters alone while its siblings complete normally. Reach for it when the work is batch-shaped; prefer `concurrency` when you simply want more throughput.
319
+
320
+ The policy is applied when `runner.start()` registers the worker. Nothing is stored on the queue — this configures _this process_, so two nodes consuming the same queue may legitimately use different values, and changing one takes effect on the next runner start rather than for everyone at once. That is the difference from `JobQueuePolicy`, which is queue state and does apply to everyone.
321
+
322
+ As with queue policies, `defaultWorkerPolicy` on the runner sets a baseline for every queue, and each queue's own `worker` is layered on top field-by-field:
323
+
324
+ ```typescript
325
+ const runner = container.get(JobRunner) as PgBossJobRunner;
326
+ runner.defaultWorkerPolicy = { concurrency: 4 };
327
+ await runner.start();
328
+ ```
329
+
330
+ When a registration declares no worker policy and no default is set, pg-boss's own defaults apply: one worker, one job per fetch.
331
+
332
+ > `concurrency` maps to pg-boss `localConcurrency` and per-job settlement to `perJobResults`, both of which the package's peer floor (**pg-boss >= 12.21.0**) guarantees.
333
+
266
334
  ## Monitoring & draining dead-letter queues
267
335
 
268
336
  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.
@@ -378,13 +446,14 @@ Entries can be either:
378
446
 
379
447
  ### `PgBossJobRegistration`
380
448
 
381
- 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.
449
+ 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 and/or a worker policy attached.
382
450
 
383
- | Property | Type | Description |
384
- | -------- | ----------------- | -------------------------------------------------------------------- |
385
- | `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
386
- | `cron` | `string` | Optional cron expression defining when the job should run. |
387
- | `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
451
+ | Property | Type | Description |
452
+ | -------- | ----------------- | -------------------------------------------------------------------------- |
453
+ | `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
454
+ | `cron` | `string` | Optional cron expression defining when the job should run. |
455
+ | `policy` | `JobQueuePolicy` | Optional per-queue retry and dead-letter policy for the job's queue. |
456
+ | `worker` | `JobWorkerPolicy` | Optional per-queue worker policy for this node — concurrency and batching. |
388
457
 
389
458
  ### `JobQueuePolicy`
390
459
 
@@ -399,6 +468,26 @@ Backend-agnostic per-queue retry and dead-letter policy (see [Retry & dead-lette
399
468
  | `expiresIn` | `Duration` | How long a run may take before it is considered stuck and made eligible for retry. |
400
469
  | `deadLetter` | `string` | Name of the dead-letter queue that receives jobs which exhaust their retries. |
401
470
 
471
+ ### `JobWorkerPolicy`
472
+
473
+ Per-queue worker throughput, declared on the registration's `worker` field or runner-wide via `defaultWorkerPolicy`. All fields optional.
474
+
475
+ | Field | Type | Meaning |
476
+ | -------------- | ---------- | -------------------------------------------------------------------------------- |
477
+ | `concurrency` | `number` | Jobs this node may run at once for the queue. Each unit settles its own job. |
478
+ | `batchSize` | `number` | Jobs fetched per trip and handed to the handler as one batch, settled as a unit. |
479
+ | `pollInterval` | `Duration` | How long a worker waits between fetches while idle. Passed through unrounded. |
480
+
481
+ Configures the worker this process starts, not the queue. See [Worker concurrency](#worker-concurrency).
482
+
483
+ ### `PermanentJobError`
484
+
485
+ `extends ServerkitError`. Thrown by a job to declare its failure permanent: the remaining retries are skipped and the job dead-letters immediately. See [Permanent failures](#permanent-failures).
486
+
487
+ | Signature | Description |
488
+ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
489
+ | `new PermanentJobError(message: string, options?: { cause?: unknown })` | `message` says why the job can never succeed. Chain `withDetails` to persist context on the job's output. |
490
+
402
491
  ### `PgBossJobBroker`
403
492
 
404
493
  Concrete `JobBroker` implementation backed by pg-boss. Constructor signature: `new PgBossJobBroker(registrations: PgBossJobRegistryMap, pgboss: PgBoss, connectionProvider: PgBossConnectionProvider)`. Every operation sources its pg-boss `db` executor from the injected `PgBossConnectionProvider`. Typically resolved through the DI container rather than instantiated directly.
@@ -467,6 +556,8 @@ Exposes a `cancelPollIntervalSeconds` property (default `5`) that controls how o
467
556
 
468
557
  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).
469
558
 
559
+ Exposes an optional `defaultWorkerPolicy` (a `JobWorkerPolicy`) applied beneath every queue's own `worker` policy, so all queues can share a concurrency or poll-interval baseline. See [Worker concurrency](#worker-concurrency).
560
+
470
561
  ### `PgBossJobMonitor`
471
562
 
472
563
  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.
@@ -484,7 +575,7 @@ process.on('SIGTERM', async () => {
484
575
 
485
576
  ## Peer Dependencies
486
577
 
487
- - `pg-boss` ^12.5.4 - PostgreSQL-based job queue
578
+ - `pg-boss` ^12.21.0 - PostgreSQL-based job queue
488
579
  - `reflect-metadata` - Required by InjectKit for decorator metadata
489
580
 
490
581
  ## License
@@ -79,12 +79,32 @@ JobRunner = _ts_decorate4([
79
79
  Injectable4()
80
80
  ], JobRunner);
81
81
 
82
+ // src/permanent.job.error.ts
83
+ import { ServerkitError } from "@maroonedsoftware/errors";
84
+ var PermanentJobError = class extends ServerkitError {
85
+ static {
86
+ __name(this, "PermanentJobError");
87
+ }
88
+ /**
89
+ * Creates a new PermanentJobError.
90
+ *
91
+ * @param message - Why the job can never succeed.
92
+ * @param options - Standard error options. To chain an underlying error, prefer
93
+ * the inherited `withCause` setter.
94
+ */
95
+ constructor(message, options) {
96
+ super(message, options);
97
+ this.name = "PermanentJobError";
98
+ }
99
+ };
100
+
82
101
  export {
83
102
  __name,
84
103
  JobBroker,
85
104
  JobContext,
86
105
  registerJobContext,
87
106
  JobMonitor,
88
- JobRunner
107
+ JobRunner,
108
+ PermanentJobError
89
109
  };
90
- //# sourceMappingURL=chunk-TIW3NS7E.js.map
110
+ //# sourceMappingURL=chunk-MR3BBUMG.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/job.broker.ts","../src/job.context.ts","../src/job.monitor.ts","../src/job.runner.ts","../src/permanent.job.error.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, Registry } from 'injectkit';\nimport { Duration } from 'luxon';\n\n/**\n * Metadata describing the job execution currently in flight.\n *\n * A {@link JobRunner} registers this against the {@link JobContext} injection token\n * in the per-execution scoped container, so any service resolved during that\n * execution can declare `JobContext` as a constructor dependency and see which\n * job it is running under. This is the job-side counterpart of ServerKit's\n * request context: it is what lets a logger, a metrics recorder, or an outbox\n * writer sitting deep in the dependency graph attribute its work to a job\n * without every layer threading the metadata through by hand.\n *\n * Only fields every backend can supply are declared here. In particular there is\n * no attempt/retry counter: pg-boss hands the work handler a bare `Job`, and the\n * retry count lives on `JobWithMetadata`, which would cost an extra query per\n * execution to fetch. Read it from {@link JobMonitor} when you need it.\n *\n * @example\n * ```typescript\n * @Injectable()\n * class AuditLog {\n * constructor(private readonly context: JobContext) {}\n *\n * record(message: string): void {\n * // Attributed to the job automatically, with no plumbing at the call site.\n * logger.info({ jobId: this.context.id, queue: this.context.name }, message);\n * }\n * }\n * ```\n */\n// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging\nexport interface JobContext {\n /** Backend-assigned identifier of the running job. Matches the id `JobBroker.send` returned. */\n id: string;\n /** Name of the queue the job was dequeued from, which is also its registered job name. */\n name: string;\n /**\n * Aborted when the job is cancelled (see {@link JobBroker.cancel}) or when the\n * runner shuts down. The same signal the runner passes to {@link Job.run}, exposed\n * here so collaborators can observe cancellation without the handler forwarding it.\n */\n signal: AbortSignal;\n /**\n * How long the backend allows this execution to run before it is considered\n * expired, when the backend reports a limit. Useful for deciding whether there\n * is time left to start another unit of work.\n */\n expiresIn?: Duration;\n}\n\n/**\n * Abstract class merged with the {@link JobContext} interface so it can serve as an\n * injectkit injection token. A {@link JobRunner} registers the live context against\n * this token in the execution-scoped container, so services can inject `JobContext`\n * and receive the job currently being run.\n *\n * Resolving it outside a job execution throws, exactly as resolving ServerKit's\n * request context outside a request does. A service that must work in both places\n * should not depend on it directly.\n */\n@Injectable()\n// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging\nexport abstract class JobContext implements JobContext {}\n\n/**\n * Registers the {@link JobContext} token so services may declare it as a dependency.\n *\n * Call this on the registry whenever any registered service injects `JobContext`.\n * `Registry.build()` validates the dependency graph up front and rejects a service\n * whose dependency has no registration, and the runner's per-execution override\n * cannot satisfy that check because it only exists at runtime, inside a scope.\n *\n * What this registers is a placeholder that throws when resolved. During a job the\n * runner's scoped override shadows it, so the real context is what gets injected;\n * anywhere else (at boot, in a request, from a singleton) resolution fails with an\n * explanation rather than handing back a fake context.\n *\n * @param registry - The registry to register into, before `build()`.\n * @returns The registry, for chaining.\n *\n * @example\n * ```typescript\n * const registry = new InjectKitRegistry();\n * registerJobContext(registry);\n * registry.register(SendEmailJob).useClass(SendEmailJob).asTransient();\n * const container = registry.build();\n * ```\n */\nexport const registerJobContext = <T extends Registry>(registry: T): T => {\n registry\n .register(JobContext)\n .useFactory(() => {\n throw new Error(\n 'JobContext is only available during a job execution. It cannot be resolved at boot, from a request scope, or from a singleton.',\n );\n })\n .asScoped();\n return registry;\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","import { ServerkitError } from '@maroonedsoftware/errors';\n\n/**\n * Thrown by a {@link Job} to declare that its failure is **permanent** — the\n * input will never succeed, so retrying it is wasted work.\n *\n * An ordinary error thrown from a handler is treated as transient: the job goes\n * back on the queue and burns its full retry budget before it is finally failed\n * (and dead-lettered, if the queue has a dead-letter queue). That is right for a\n * network blip or a rate limit, and wrong for a malformed payload or a `422`\n * from an upstream API — nothing about waiting makes those succeed.\n *\n * Throwing this instead skips the remaining retries and routes the job straight\n * to the queue's dead-letter queue, where it is preserved for inspection or\n * replay. A queue with no dead-letter queue simply fails the job terminally.\n *\n * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and\n * the `withDetails` / `withCause` / `withInternalDetails` setters apply. Attach\n * the offending field or upstream status with `withDetails` — it is persisted as\n * the job's output, which is what an operator reads when draining the queue.\n *\n * The runner matches this type with a direct `instanceof` and does **not** walk\n * the `cause` chain: the meaning is \"this handler declared the failure\n * permanent\", not \"something permanent happened somewhere underneath\". Wrapping\n * a transient error in one of these makes it permanent, deliberately.\n *\n * @example\n * ```typescript\n * async run(payload: DeliverWebhookPayload): Promise<void> {\n * const parsed = schema.safeParse(payload);\n * if (!parsed.success) {\n * throw new PermanentJobError('Malformed webhook payload').withDetails({ issues: parsed.error.issues });\n * }\n *\n * const response = await fetch(parsed.data.url, { method: 'POST' });\n * if (response.status === 422) {\n * // The receiver will reject this body every time; retrying cannot help.\n * throw new PermanentJobError(`Webhook rejected with ${response.status}`);\n * }\n * if (!response.ok) {\n * // Transient — let it retry with the queue's backoff.\n * throw new Error(`Webhook failed with ${response.status}`);\n * }\n * }\n * ```\n */\nexport class PermanentJobError extends ServerkitError {\n /**\n * Creates a new PermanentJobError.\n *\n * @param message - Why the job can never succeed.\n * @param options - Standard error options. To chain an underlying error, prefer\n * the inherited `withCause` setter.\n */\n constructor(message: string, options?: { cause?: unknown }) {\n super(message, options);\n this.name = 'PermanentJobError';\n }\n}\n"],"mappings":";;;;AAAA,SAASA,kBAAkB;;;;;;;;AA+CpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAgHtB;;;;;;AC/JA,SAASC,cAAAA,mBAA4B;;;;;;;;AAgE9B,IAAeC,aAAf,MAAeA;SAAAA;;;AAAkC;;;;AA0BjD,IAAMC,qBAAqB,wBAAqBC,aAAAA;AACrDA,WACGC,SAASH,UAAAA,EACTI,WAAW,MAAA;AACV,UAAM,IAAIC,MACR,gIAAA;EAEJ,CAAA,EACCC,SAAQ;AACX,SAAOJ;AACT,GAVkC;;;AC1FlC,SAASK,cAAAA,mBAAkB;;;;;;;;AA6FpB,IAAeC,aAAf,MAAeA;SAAAA;;;AAwEtB;;;;;;ACrKA,SAASC,cAAAA,mBAAkB;;;;;;;;AAsBpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAsBtB;;;;;;AC5CA,SAASC,sBAAsB;AA8CxB,IAAMC,oBAAN,cAAgCC,eAAAA;EA9CvC,OA8CuCA;;;;;;;;;;EAQrC,YAAYC,SAAiBC,SAA+B;AAC1D,UAAMD,SAASC,OAAAA;AACf,SAAKC,OAAO;EACd;AACF;","names":["Injectable","JobBroker","Injectable","JobContext","registerJobContext","registry","register","useFactory","Error","asScoped","Injectable","JobMonitor","Injectable","JobRunner","ServerkitError","PermanentJobError","ServerkitError","message","options","name"]}
package/dist/index.d.ts CHANGED
@@ -4,7 +4,9 @@ export * from './job.context.js';
4
4
  export * from './job.info.js';
5
5
  export * from './job.send.options.js';
6
6
  export * from './job.queue.policy.js';
7
+ export * from './job.worker.policy.js';
7
8
  export * from './job.monitor.js';
8
9
  export * from './job.runner.js';
9
10
  export * from './not.supported.error.js';
11
+ export * from './permanent.job.error.js';
10
12
  //# 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,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,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,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC"}
package/dist/index.js CHANGED
@@ -3,9 +3,10 @@ import {
3
3
  JobContext,
4
4
  JobMonitor,
5
5
  JobRunner,
6
+ PermanentJobError,
6
7
  __name,
7
8
  registerJobContext
8
- } from "./chunk-TIW3NS7E.js";
9
+ } from "./chunk-MR3BBUMG.js";
9
10
 
10
11
  // src/job.ts
11
12
  import { Injectable } from "injectkit";
@@ -55,6 +56,7 @@ export {
55
56
  JobMonitor,
56
57
  JobRunner,
57
58
  NotSupportedError,
59
+ PermanentJobError,
58
60
  registerJobContext
59
61
  };
60
62
  //# sourceMappingURL=index.js.map
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,59 @@
1
+ import { Duration } from 'luxon';
2
+ /**
3
+ * Backend-agnostic throughput policy for a job *worker*: how many jobs a single
4
+ * node may run at once for a queue, how many it fetches per trip to the backend,
5
+ * and how long it waits between fetches when the queue is idle.
6
+ *
7
+ * Like {@link JobQueuePolicy}, this describes *intent* rather than any one
8
+ * backend's wire format. Worker concurrency, batching, and poll interval are
9
+ * consumer-side concepts on every mainstream queue (pg-boss
10
+ * `localConcurrency`/`batchSize`/`pollingIntervalSeconds`, BullMQ's worker
11
+ * `concurrency`, an SQS consumer's concurrency plus `MaxNumberOfMessages` and
12
+ * wait time), so a policy declared here maps cleanly onto whichever backend is
13
+ * in use. A backend that cannot honor a requested knob throws a
14
+ * `NotSupportedError` rather than silently ignoring it.
15
+ *
16
+ * Unlike {@link JobQueuePolicy}, none of this is stored on the queue: it
17
+ * configures the worker this process starts, so two nodes consuming the same
18
+ * queue may legitimately use different values, and changing one takes effect on
19
+ * the next runner start rather than for everyone at once.
20
+ *
21
+ * @example
22
+ * ```typescript
23
+ * const worker: JobWorkerPolicy = {
24
+ * concurrency: 8,
25
+ * pollInterval: Duration.fromObject({ seconds: 1 }),
26
+ * };
27
+ * ```
28
+ */
29
+ export interface JobWorkerPolicy {
30
+ /**
31
+ * How many jobs this node may run at once for the queue. Each unit of
32
+ * concurrency is an independent worker that fetches and settles its own job,
33
+ * so one job's failure has no effect on its siblings. Omit to use the
34
+ * backend's default (a single worker, on pg-boss).
35
+ *
36
+ * This is the knob to reach for when a queue is falling behind. See
37
+ * {@link batchSize} for why the other one usually is not.
38
+ */
39
+ concurrency?: number;
40
+ /**
41
+ * How many jobs a single worker fetches per trip to the backend, handed to the
42
+ * handler together as one batch. Omit to use the backend's default (one job
43
+ * per fetch, on pg-boss).
44
+ *
45
+ * Prefer {@link concurrency} for throughput. Backends that settle a batch as a
46
+ * unit — pg-boss does — will retry every job in a batch when any one of them
47
+ * fails, so raising this trades failure isolation for fewer round trips. Raise
48
+ * it only when the work is genuinely batch-shaped.
49
+ */
50
+ batchSize?: number;
51
+ /**
52
+ * How long a worker waits between fetches while the queue is idle. Lower it to
53
+ * cut the latency between a job being sent and being picked up; raise it to
54
+ * cut idle load on the backend. Backends that measure this in seconds receive
55
+ * it as a fractional second count, not rounded.
56
+ */
57
+ pollInterval?: Duration;
58
+ }
59
+ //# sourceMappingURL=job.worker.policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"job.worker.policy.d.ts","sourceRoot":"","sources":["../src/job.worker.policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC;CACzB"}
@@ -0,0 +1,58 @@
1
+ import { ServerkitError } from '@maroonedsoftware/errors';
2
+ /**
3
+ * Thrown by a {@link Job} to declare that its failure is **permanent** — the
4
+ * input will never succeed, so retrying it is wasted work.
5
+ *
6
+ * An ordinary error thrown from a handler is treated as transient: the job goes
7
+ * back on the queue and burns its full retry budget before it is finally failed
8
+ * (and dead-lettered, if the queue has a dead-letter queue). That is right for a
9
+ * network blip or a rate limit, and wrong for a malformed payload or a `422`
10
+ * from an upstream API — nothing about waiting makes those succeed.
11
+ *
12
+ * Throwing this instead skips the remaining retries and routes the job straight
13
+ * to the queue's dead-letter queue, where it is preserved for inspection or
14
+ * replay. A queue with no dead-letter queue simply fails the job terminally.
15
+ *
16
+ * Extends {@link ServerkitError}, so `errorMiddleware` renders it (as a 500) and
17
+ * the `withDetails` / `withCause` / `withInternalDetails` setters apply. Attach
18
+ * the offending field or upstream status with `withDetails` — it is persisted as
19
+ * the job's output, which is what an operator reads when draining the queue.
20
+ *
21
+ * The runner matches this type with a direct `instanceof` and does **not** walk
22
+ * the `cause` chain: the meaning is "this handler declared the failure
23
+ * permanent", not "something permanent happened somewhere underneath". Wrapping
24
+ * a transient error in one of these makes it permanent, deliberately.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * async run(payload: DeliverWebhookPayload): Promise<void> {
29
+ * const parsed = schema.safeParse(payload);
30
+ * if (!parsed.success) {
31
+ * throw new PermanentJobError('Malformed webhook payload').withDetails({ issues: parsed.error.issues });
32
+ * }
33
+ *
34
+ * const response = await fetch(parsed.data.url, { method: 'POST' });
35
+ * if (response.status === 422) {
36
+ * // The receiver will reject this body every time; retrying cannot help.
37
+ * throw new PermanentJobError(`Webhook rejected with ${response.status}`);
38
+ * }
39
+ * if (!response.ok) {
40
+ * // Transient — let it retry with the queue's backoff.
41
+ * throw new Error(`Webhook failed with ${response.status}`);
42
+ * }
43
+ * }
44
+ * ```
45
+ */
46
+ export declare class PermanentJobError extends ServerkitError {
47
+ /**
48
+ * Creates a new PermanentJobError.
49
+ *
50
+ * @param message - Why the job can never succeed.
51
+ * @param options - Standard error options. To chain an underlying error, prefer
52
+ * the inherited `withCause` setter.
53
+ */
54
+ constructor(message: string, options?: {
55
+ cause?: unknown;
56
+ });
57
+ }
58
+ //# sourceMappingURL=permanent.job.error.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permanent.job.error.d.ts","sourceRoot":"","sources":["../src/permanent.job.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}