@maroonedsoftware/jobbroker 1.8.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,82 @@
1
+ import { PgBoss } from 'pg-boss';
2
+ import { JobInfo } from '../job.info.js';
3
+ import { JobMonitor, JobQueryOptions, JobQueueStats, JobRedriveOptions } from '../job.monitor.js';
4
+ import { PgBossConnectionProvider } from './pgboss.connection.provider.js';
5
+ /**
6
+ * pg-boss implementation of the {@link JobMonitor} interface.
7
+ *
8
+ * Provides the operator-side view of pg-boss queues — depth/health stats, job
9
+ * enumeration, and dead-letter remediation (redrive, discard, retry) — on top of
10
+ * pg-boss's native `getQueue`, `findJobs`, `redrive`, `deleteJob`, and `retry`.
11
+ *
12
+ * Like {@link PgBossJobBroker}, every operation sources its pg-boss `db` executor
13
+ * from the injected {@link PgBossConnectionProvider}, so a remediation action can
14
+ * participate in a surrounding transaction when a request-scoped override supplies
15
+ * a transaction-bound executor. Unlike the broker, the monitor does not consult
16
+ * the job registry: it works on any queue name, including an unregistered
17
+ * dead-letter sink.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * const monitor = new PgBossJobMonitor(pgboss, new PgBossConnectionProvider());
22
+ *
23
+ * const stats = await monitor.getQueueStats('charge.webhook.dead');
24
+ * if (stats && stats.total > 0) {
25
+ * await monitor.redrive('charge.webhook.dead', { limit: 100 });
26
+ * }
27
+ * ```
28
+ */
29
+ export declare class PgBossJobMonitor extends JobMonitor {
30
+ private readonly pgboss;
31
+ private readonly connectionProvider;
32
+ /**
33
+ * Creates a new PgBossJobMonitor instance.
34
+ *
35
+ * @param pgboss - The pg-boss instance to use for queue operations.
36
+ * @param connectionProvider - Supplies the pg-boss `db` executor for each
37
+ * operation; the default returns `undefined` (pg-boss's own pool),
38
+ * while a request-scoped override enables transactional remediation.
39
+ */
40
+ constructor(pgboss: PgBoss, connectionProvider: PgBossConnectionProvider);
41
+ /**
42
+ * Reports the depth and health of a queue by reading pg-boss's cached queue
43
+ * counters.
44
+ *
45
+ * @param name - The queue name to inspect.
46
+ * @returns The {@link JobQueueStats}, or `null` if the queue does not exist.
47
+ */
48
+ getQueueStats(name: string): Promise<JobQueueStats | null>;
49
+ /**
50
+ * Lists jobs retained in a queue, mapping pg-boss's records down to the
51
+ * backend-agnostic {@link JobInfo} shape.
52
+ *
53
+ * @typeParam Payload - The type of the job payloads.
54
+ * @param name - The queue name to list.
55
+ * @param options - Optional {@link JobQueryOptions} filters.
56
+ * @returns The matching jobs (empty if none, or if the queue does not exist).
57
+ */
58
+ listJobs<Payload extends object>(name: string, options?: JobQueryOptions): Promise<JobInfo<Payload>[]>;
59
+ /**
60
+ * Moves dead-lettered jobs back into circulation via pg-boss `redrive`.
61
+ *
62
+ * @param name - The (dead-letter) queue to drain.
63
+ * @param options - Optional {@link JobRedriveOptions}.
64
+ * @returns The number of jobs moved.
65
+ */
66
+ redrive(name: string, options?: JobRedriveOptions): Promise<number>;
67
+ /**
68
+ * Permanently deletes one or more jobs from a queue.
69
+ *
70
+ * @param name - The queue name the jobs live in.
71
+ * @param id - A single job id, or an array of ids, to delete.
72
+ */
73
+ deleteJob(name: string, id: string | string[]): Promise<void>;
74
+ /**
75
+ * Re-attempts one or more failed jobs in place via pg-boss `retry`.
76
+ *
77
+ * @param name - The queue name the jobs live in.
78
+ * @param id - A single job id, or an array of ids, to retry.
79
+ */
80
+ retryJob(name: string, id: string | string[]): Promise<void>;
81
+ }
82
+ //# sourceMappingURL=pgboss.job.monitor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pgboss.job.monitor.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.monitor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAClG,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,gBAAiB,SAAQ,UAAU;IAU5C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAVrC;;;;;;;OAOG;gBAEgB,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,wBAAwB;IAK/D;;;;;;OAMG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAehE;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;IAW5G;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IASzE;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAGnE"}
@@ -1,31 +1,56 @@
1
1
  import { Identifier } from 'injectkit';
2
2
  import { Job } from '../job.js';
3
+ import { JobQueuePolicy } from '../job.queue.policy.js';
3
4
  /**
4
- * Configuration for a scheduled job registration.
5
+ * Configuration object for a job registration.
5
6
  *
6
- * Use this type when you need to register a job that runs on a schedule
7
- * rather than being triggered manually.
7
+ * Use the object form (rather than a bare job identifier) when you need to
8
+ * attach a cron schedule, a per-queue {@link JobQueuePolicy}, or both. Every
9
+ * field beyond `job` is optional, so this shape covers three cases:
10
+ *
11
+ * - `{ job }` — an on-demand job (equivalent to registering the bare identifier).
12
+ * - `{ job, cron }` — a job that also runs on a schedule.
13
+ * - `{ job, policy }` / `{ job, cron, policy }` — either of the above with retry
14
+ * and dead-letter behavior declared where the job is mapped.
8
15
  *
9
16
  * @example
10
17
  * ```typescript
18
+ * // Scheduled job
11
19
  * const scheduledJob: PgBossJobRegistration = {
12
20
  * job: DailyReportJob,
13
- * cron: '0 9 * * *' // Every day at 9 AM
21
+ * cron: '0 9 * * *', // Every day at 9 AM
22
+ * };
23
+ *
24
+ * // On-demand job with a retry / dead-letter policy
25
+ * const webhookJob: PgBossJobRegistration = {
26
+ * job: DeliverWebhookJob,
27
+ * policy: {
28
+ * retryLimit: 5,
29
+ * retryDelay: Duration.fromObject({ seconds: 30 }),
30
+ * retryBackoff: true,
31
+ * deadLetter: 'deliver.webhook.dead',
32
+ * },
14
33
  * };
15
34
  * ```
16
35
  */
17
36
  export type PgBossJobRegistration = {
18
37
  /** The job class identifier to instantiate when the job runs. */
19
38
  job: Identifier<Job>;
20
- /** A cron expression defining when the job should run. */
21
- cron: string;
39
+ /** An optional cron expression defining when the job should run. */
40
+ cron?: string;
41
+ /**
42
+ * An optional per-queue retry and dead-letter policy applied to this job's
43
+ * queue when the runner starts. See {@link JobQueuePolicy}.
44
+ */
45
+ policy?: JobQueuePolicy;
22
46
  };
23
47
  /**
24
48
  * Registry map for PgBoss job registrations.
25
49
  *
26
50
  * This map holds all job registrations, mapping job names to either:
27
- * - A job class identifier (for on-demand jobs)
28
- * - A {@link PgBossJobRegistration} object (for scheduled jobs)
51
+ * - A bare job class identifier (for a plain on-demand job)
52
+ * - A {@link PgBossJobRegistration} object, which adds an optional cron schedule
53
+ * and/or an optional per-queue {@link JobQueuePolicy}
29
54
  *
30
55
  * The registry is used by both {@link PgBossJobBroker} and {@link PgBossJobRunner}
31
56
  * to validate job names and resolve job handlers.
@@ -43,6 +68,12 @@ export type PgBossJobRegistration = {
43
68
  * cron: '0 0 * * *'
44
69
  * });
45
70
  *
71
+ * // Register an on-demand job with a retry / dead-letter policy
72
+ * registry.set('deliver-webhook', {
73
+ * job: DeliverWebhookJob,
74
+ * policy: { retryLimit: 5, deadLetter: 'deliver-webhook-dead' }
75
+ * });
76
+ *
46
77
  * // Use with dependency injection
47
78
  * container.bind(PgBossJobRegistryMap).toValue(registry);
48
79
  * ```
@@ -1 +1 @@
1
- {"version":3,"file":"pgboss.job.registration.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAc,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iEAAiE;IACjE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACrB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,oBAAqB,SAAQ,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,qBAAqB,CAAC;CAAG"}
1
+ {"version":3,"file":"pgboss.job.registration.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAc,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,iEAAiE;IACjE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACrB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,oBAAqB,SAAQ,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,qBAAqB,CAAC;CAAG"}
@@ -1,5 +1,6 @@
1
1
  import { PgBoss } from 'pg-boss';
2
2
  import { Container } from 'injectkit';
3
+ import { JobQueuePolicy } from '../job.queue.policy.js';
3
4
  import { JobRunner } from '../job.runner.js';
4
5
  import { PgBossJobRegistryMap } from './pgboss.job.registration.js';
5
6
  import { Logger } from '@maroonedsoftware/logger';
@@ -49,6 +50,19 @@ export declare class PgBossJobRunner extends JobRunner {
49
50
  * @default 5
50
51
  */
51
52
  cancelPollIntervalSeconds: number;
53
+ /**
54
+ * A base {@link JobQueuePolicy} applied to *every* registered queue, beneath
55
+ * each queue's own policy. Set it to give all queues sane retry/dead-letter
56
+ * defaults without repeating them on each registration; a field a queue sets
57
+ * on its own `policy` overrides the same field here.
58
+ *
59
+ * Leave it unset (the default) to opt in per queue only. When neither this nor
60
+ * a queue's own policy supplies any option, that queue is created exactly as
61
+ * before, with no options passed.
62
+ *
63
+ * @default undefined
64
+ */
65
+ defaultQueuePolicy?: JobQueuePolicy;
52
66
  /**
53
67
  * Creates a new PgBossJobRunner instance.
54
68
  *
@@ -62,9 +76,15 @@ export declare class PgBossJobRunner extends JobRunner {
62
76
  * Starts the job runner and begins processing registered jobs.
63
77
  *
64
78
  * For each registered job, this method:
65
- * 1. Creates the queue if it doesn't exist
66
- * 2. Sets up the cron schedule (for scheduled jobs)
67
- * 3. Starts a worker to process jobs from the queue
79
+ * 1. Resolves the effective queue policy (the runner's {@link defaultQueuePolicy}
80
+ * merged with the registration's own policy, if any)
81
+ * 2. Auto-creates any dead-letter queue the policy references, before the queue
82
+ * that references it
83
+ * 3. Creates the queue with the policy's options if it doesn't exist, or updates
84
+ * an existing queue to match; when no policy applies, the queue is created
85
+ * with the name only (unchanged pre-policy behavior)
86
+ * 4. Sets up the cron schedule (for scheduled jobs)
87
+ * 5. Starts a worker to process jobs from the queue
68
88
  *
69
89
  * Each item in a batch resolves its `Job` instance from the DI container
70
90
  * individually and execution is awaited via `Promise.allSettled`, so pg-boss
@@ -74,6 +94,41 @@ export declare class PgBossJobRunner extends JobRunner {
74
94
  * @returns A promise that resolves when all workers are registered with pg-boss.
75
95
  */
76
96
  start(): Promise<void>;
97
+ /**
98
+ * Merges the runner-wide {@link defaultQueuePolicy} with a registration's own
99
+ * policy, letting the registration override individual fields. Returns
100
+ * `undefined` when neither supplies a policy, so a queue with no policy is left
101
+ * to pg-boss defaults and created exactly as it was before this feature.
102
+ *
103
+ * @param registration - The registry entry (a bare identifier or an object).
104
+ * @returns The effective policy for the queue, or `undefined` if none applies.
105
+ * @internal
106
+ */
107
+ private resolvePolicy;
108
+ /**
109
+ * Ensures a queue exists and, when a policy is supplied, that its retry and
110
+ * dead-letter options match. Creates the queue (with options) when absent, and
111
+ * updates an existing queue's options when a policy is given. When no policy
112
+ * option resolves, an absent queue is created with the name only — byte-for-byte
113
+ * the pre-policy behavior — and an existing queue is left untouched.
114
+ *
115
+ * @param name - The queue name to ensure.
116
+ * @param policy - The effective policy, or `undefined` for none.
117
+ * @param ensured - Names already ensured during this start pass (mutated).
118
+ * @internal
119
+ */
120
+ private ensureQueue;
121
+ /**
122
+ * Maps a backend-agnostic {@link JobQueuePolicy} onto pg-boss's native queue
123
+ * options. Luxon {@link Duration}s become whole-second counts (pg-boss measures
124
+ * these in seconds). Returns `undefined` when the policy carries no options to
125
+ * apply, so callers fall back to the name-only create/no-op update path.
126
+ *
127
+ * @param policy - The effective policy for a queue.
128
+ * @returns The pg-boss queue options, or `undefined` if the policy is empty.
129
+ * @internal
130
+ */
131
+ private toQueueOptions;
77
132
  /**
78
133
  * Polls pg-boss for a running job and aborts the given controller when the job
79
134
  * has been cancelled (or has disappeared, e.g. via {@link PgBossJobBroker.deleteJob}).
@@ -1 +1 @@
1
- {"version":3,"file":"pgboss.job.runner.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAyB,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAclD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAqB1C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAvBzB;;;;;;;;OAQG;IACH,yBAAyB,SAAK;IAE9B;;;;;;;OAOG;gBAEgB,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;IAKjC;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD5B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
1
+ {"version":3,"file":"pgboss.job.runner.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAyB,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAsBlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAmC1C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IArCzB;;;;;;;;OAQG;IACH,yBAAyB,SAAK;IAE9B;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,cAAc,CAAC;IAEpC;;;;;;;OAOG;gBAEgB,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;IAKjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoE5B;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;OAWG;YACW,WAAW;IAuBzB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
package/dist/pgboss.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export * from './pgboss/pgboss.job.broker.js';
2
+ export * from './pgboss/pgboss.job.monitor.js';
2
3
  export * from './pgboss/pgboss.job.runner.js';
3
4
  export * from './pgboss/pgboss.job.registration.js';
4
5
  export * from './pgboss/pgboss.connection.provider.js';
@@ -1 +1 @@
1
- {"version":3,"file":"pgboss.d.ts","sourceRoot":"","sources":["../src/pgboss.ts"],"names":[],"mappings":"AAEA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wCAAwC,CAAC"}
1
+ {"version":3,"file":"pgboss.d.ts","sourceRoot":"","sources":["../src/pgboss.ts"],"names":[],"mappings":"AAEA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wCAAwC,CAAC"}
package/dist/pgboss.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/pgboss/pgboss.job.broker.ts
8
9
  import { PgBoss } from "pg-boss";
@@ -278,10 +279,9 @@ PgBossJobBroker = _ts_decorate3([
278
279
  ])
279
280
  ], PgBossJobBroker);
280
281
 
281
- // src/pgboss/pgboss.job.runner.ts
282
+ // src/pgboss/pgboss.job.monitor.ts
282
283
  import { PgBoss as PgBoss2 } from "pg-boss";
283
- import { Container, Injectable as Injectable4 } from "injectkit";
284
- import { Logger } from "@maroonedsoftware/logger";
284
+ import { Injectable as Injectable4 } from "injectkit";
285
285
  function _ts_decorate4(decorators, target, key, desc) {
286
286
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
287
287
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -293,8 +293,130 @@ function _ts_metadata2(k, v) {
293
293
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
294
294
  }
295
295
  __name(_ts_metadata2, "_ts_metadata");
296
+ var PgBossJobMonitor = class extends JobMonitor {
297
+ static {
298
+ __name(this, "PgBossJobMonitor");
299
+ }
300
+ pgboss;
301
+ connectionProvider;
302
+ /**
303
+ * Creates a new PgBossJobMonitor instance.
304
+ *
305
+ * @param pgboss - The pg-boss instance to use for queue operations.
306
+ * @param connectionProvider - Supplies the pg-boss `db` executor for each
307
+ * operation; the default returns `undefined` (pg-boss's own pool),
308
+ * while a request-scoped override enables transactional remediation.
309
+ */
310
+ constructor(pgboss, connectionProvider) {
311
+ super(), this.pgboss = pgboss, this.connectionProvider = connectionProvider;
312
+ }
313
+ /**
314
+ * Reports the depth and health of a queue by reading pg-boss's cached queue
315
+ * counters.
316
+ *
317
+ * @param name - The queue name to inspect.
318
+ * @returns The {@link JobQueueStats}, or `null` if the queue does not exist.
319
+ */
320
+ async getQueueStats(name) {
321
+ const queue = await this.pgboss.getQueue(name);
322
+ if (!queue) {
323
+ return null;
324
+ }
325
+ return {
326
+ name: queue.name,
327
+ queued: queue.queuedCount,
328
+ active: queue.activeCount,
329
+ failed: queue.failedCount,
330
+ total: queue.totalCount
331
+ };
332
+ }
333
+ /**
334
+ * Lists jobs retained in a queue, mapping pg-boss's records down to the
335
+ * backend-agnostic {@link JobInfo} shape.
336
+ *
337
+ * @typeParam Payload - The type of the job payloads.
338
+ * @param name - The queue name to list.
339
+ * @param options - Optional {@link JobQueryOptions} filters.
340
+ * @returns The matching jobs (empty if none, or if the queue does not exist).
341
+ */
342
+ async listJobs(name, options) {
343
+ const jobs = await this.pgboss.findJobs(name, {
344
+ id: options?.id,
345
+ data: options?.data,
346
+ queued: options?.queuedOnly,
347
+ db: this.connectionProvider.executor()
348
+ });
349
+ return jobs.map((job) => ({
350
+ id: job.id,
351
+ name: job.name,
352
+ state: job.state,
353
+ data: job.data
354
+ }));
355
+ }
356
+ /**
357
+ * Moves dead-lettered jobs back into circulation via pg-boss `redrive`.
358
+ *
359
+ * @param name - The (dead-letter) queue to drain.
360
+ * @param options - Optional {@link JobRedriveOptions}.
361
+ * @returns The number of jobs moved.
362
+ */
363
+ async redrive(name, options) {
364
+ return this.pgboss.redrive(name, {
365
+ destination: options?.destination,
366
+ sourceName: options?.sourceName,
367
+ limit: options?.limit,
368
+ db: this.connectionProvider.executor()
369
+ });
370
+ }
371
+ /**
372
+ * Permanently deletes one or more jobs from a queue.
373
+ *
374
+ * @param name - The queue name the jobs live in.
375
+ * @param id - A single job id, or an array of ids, to delete.
376
+ */
377
+ async deleteJob(name, id) {
378
+ await this.pgboss.deleteJob(name, id, {
379
+ db: this.connectionProvider.executor()
380
+ });
381
+ }
382
+ /**
383
+ * Re-attempts one or more failed jobs in place via pg-boss `retry`.
384
+ *
385
+ * @param name - The queue name the jobs live in.
386
+ * @param id - A single job id, or an array of ids, to retry.
387
+ */
388
+ async retryJob(name, id) {
389
+ await this.pgboss.retry(name, id, {
390
+ db: this.connectionProvider.executor()
391
+ });
392
+ }
393
+ };
394
+ PgBossJobMonitor = _ts_decorate4([
395
+ Injectable4(),
396
+ _ts_metadata2("design:type", Function),
397
+ _ts_metadata2("design:paramtypes", [
398
+ typeof PgBoss2 === "undefined" ? Object : PgBoss2,
399
+ typeof PgBossConnectionProvider === "undefined" ? Object : PgBossConnectionProvider
400
+ ])
401
+ ], PgBossJobMonitor);
402
+
403
+ // src/pgboss/pgboss.job.runner.ts
404
+ import { PgBoss as PgBoss3 } from "pg-boss";
405
+ import { Container, Injectable as Injectable5 } from "injectkit";
406
+ import { Logger } from "@maroonedsoftware/logger";
407
+ function _ts_decorate5(decorators, target, key, desc) {
408
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
409
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
410
+ 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;
411
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
412
+ }
413
+ __name(_ts_decorate5, "_ts_decorate");
414
+ function _ts_metadata3(k, v) {
415
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
416
+ }
417
+ __name(_ts_metadata3, "_ts_metadata");
296
418
  var isPgBossJobRegistration = /* @__PURE__ */ __name((registration) => {
297
- return registration && "job" in registration && "cron" in registration;
419
+ return typeof registration === "object" && registration !== null && "job" in registration;
298
420
  }, "isPgBossJobRegistration");
299
421
  var PgBossJobRunner = class extends JobRunner {
300
422
  static {
@@ -315,6 +437,19 @@ var PgBossJobRunner = class extends JobRunner {
315
437
  */
316
438
  cancelPollIntervalSeconds = 5;
317
439
  /**
440
+ * A base {@link JobQueuePolicy} applied to *every* registered queue, beneath
441
+ * each queue's own policy. Set it to give all queues sane retry/dead-letter
442
+ * defaults without repeating them on each registration; a field a queue sets
443
+ * on its own `policy` overrides the same field here.
444
+ *
445
+ * Leave it unset (the default) to opt in per queue only. When neither this nor
446
+ * a queue's own policy supplies any option, that queue is created exactly as
447
+ * before, with no options passed.
448
+ *
449
+ * @default undefined
450
+ */
451
+ defaultQueuePolicy;
452
+ /**
318
453
  * Creates a new PgBossJobRunner instance.
319
454
  *
320
455
  * @param container - The DI container for resolving job instances.
@@ -329,9 +464,15 @@ var PgBossJobRunner = class extends JobRunner {
329
464
  * Starts the job runner and begins processing registered jobs.
330
465
  *
331
466
  * For each registered job, this method:
332
- * 1. Creates the queue if it doesn't exist
333
- * 2. Sets up the cron schedule (for scheduled jobs)
334
- * 3. Starts a worker to process jobs from the queue
467
+ * 1. Resolves the effective queue policy (the runner's {@link defaultQueuePolicy}
468
+ * merged with the registration's own policy, if any)
469
+ * 2. Auto-creates any dead-letter queue the policy references, before the queue
470
+ * that references it
471
+ * 3. Creates the queue with the policy's options if it doesn't exist, or updates
472
+ * an existing queue to match; when no policy applies, the queue is created
473
+ * with the name only (unchanged pre-policy behavior)
474
+ * 4. Sets up the cron schedule (for scheduled jobs)
475
+ * 5. Starts a worker to process jobs from the queue
335
476
  *
336
477
  * Each item in a batch resolves its `Job` instance from the DI container
337
478
  * individually and execution is awaited via `Promise.allSettled`, so pg-boss
@@ -342,15 +483,19 @@ var PgBossJobRunner = class extends JobRunner {
342
483
  */
343
484
  async start() {
344
485
  await this.pgboss.start();
486
+ const ensured = /* @__PURE__ */ new Set();
345
487
  for (const [name, registration] of this.registrations.entries()) {
346
- const queue = await this.pgboss.getQueue(name);
347
- if (!queue) {
348
- await this.pgboss.createQueue(name);
488
+ const policy = this.resolvePolicy(registration);
489
+ if (policy?.deadLetter) {
490
+ await this.ensureQueue(policy.deadLetter, void 0, ensured);
349
491
  }
492
+ await this.ensureQueue(name, policy, ensured);
350
493
  let identifier;
351
494
  if (isPgBossJobRegistration(registration)) {
352
495
  identifier = registration.job;
353
- await this.pgboss.schedule(name, registration.cron);
496
+ if (registration.cron) {
497
+ await this.pgboss.schedule(name, registration.cron);
498
+ }
354
499
  } else {
355
500
  identifier = registration;
356
501
  }
@@ -386,6 +531,89 @@ var PgBossJobRunner = class extends JobRunner {
386
531
  }
387
532
  }
388
533
  /**
534
+ * Merges the runner-wide {@link defaultQueuePolicy} with a registration's own
535
+ * policy, letting the registration override individual fields. Returns
536
+ * `undefined` when neither supplies a policy, so a queue with no policy is left
537
+ * to pg-boss defaults and created exactly as it was before this feature.
538
+ *
539
+ * @param registration - The registry entry (a bare identifier or an object).
540
+ * @returns The effective policy for the queue, or `undefined` if none applies.
541
+ * @internal
542
+ */
543
+ resolvePolicy(registration) {
544
+ const own = isPgBossJobRegistration(registration) ? registration.policy : void 0;
545
+ if (!this.defaultQueuePolicy && !own) {
546
+ return void 0;
547
+ }
548
+ return {
549
+ ...this.defaultQueuePolicy,
550
+ ...own
551
+ };
552
+ }
553
+ /**
554
+ * Ensures a queue exists and, when a policy is supplied, that its retry and
555
+ * dead-letter options match. Creates the queue (with options) when absent, and
556
+ * updates an existing queue's options when a policy is given. When no policy
557
+ * option resolves, an absent queue is created with the name only — byte-for-byte
558
+ * the pre-policy behavior — and an existing queue is left untouched.
559
+ *
560
+ * @param name - The queue name to ensure.
561
+ * @param policy - The effective policy, or `undefined` for none.
562
+ * @param ensured - Names already ensured during this start pass (mutated).
563
+ * @internal
564
+ */
565
+ async ensureQueue(name, policy, ensured) {
566
+ if (ensured.has(name)) {
567
+ return;
568
+ }
569
+ ensured.add(name);
570
+ const options = policy ? this.toQueueOptions(policy) : void 0;
571
+ const queue = await this.pgboss.getQueue(name);
572
+ if (!queue) {
573
+ if (options) {
574
+ await this.pgboss.createQueue(name, options);
575
+ } else {
576
+ await this.pgboss.createQueue(name);
577
+ }
578
+ return;
579
+ }
580
+ if (options) {
581
+ await this.pgboss.updateQueue(name, options);
582
+ }
583
+ }
584
+ /**
585
+ * Maps a backend-agnostic {@link JobQueuePolicy} onto pg-boss's native queue
586
+ * options. Luxon {@link Duration}s become whole-second counts (pg-boss measures
587
+ * these in seconds). Returns `undefined` when the policy carries no options to
588
+ * apply, so callers fall back to the name-only create/no-op update path.
589
+ *
590
+ * @param policy - The effective policy for a queue.
591
+ * @returns The pg-boss queue options, or `undefined` if the policy is empty.
592
+ * @internal
593
+ */
594
+ toQueueOptions(policy) {
595
+ const options = {};
596
+ if (policy.retryLimit !== void 0) {
597
+ options.retryLimit = policy.retryLimit;
598
+ }
599
+ if (policy.retryDelay !== void 0) {
600
+ options.retryDelay = Math.round(policy.retryDelay.as("seconds"));
601
+ }
602
+ if (policy.retryBackoff !== void 0) {
603
+ options.retryBackoff = policy.retryBackoff;
604
+ }
605
+ if (policy.retryDelayMax !== void 0) {
606
+ options.retryDelayMax = Math.round(policy.retryDelayMax.as("seconds"));
607
+ }
608
+ if (policy.expiresIn !== void 0) {
609
+ options.expireInSeconds = Math.round(policy.expiresIn.as("seconds"));
610
+ }
611
+ if (policy.deadLetter !== void 0) {
612
+ options.deadLetter = policy.deadLetter;
613
+ }
614
+ return Object.keys(options).length > 0 ? options : void 0;
615
+ }
616
+ /**
389
617
  * Polls pg-boss for a running job and aborts the given controller when the job
390
618
  * has been cancelled (or has disappeared, e.g. via {@link PgBossJobBroker.deleteJob}).
391
619
  *
@@ -435,19 +663,20 @@ var PgBossJobRunner = class extends JobRunner {
435
663
  await this.pgboss.stop();
436
664
  }
437
665
  };
438
- PgBossJobRunner = _ts_decorate4([
439
- Injectable4(),
440
- _ts_metadata2("design:type", Function),
441
- _ts_metadata2("design:paramtypes", [
666
+ PgBossJobRunner = _ts_decorate5([
667
+ Injectable5(),
668
+ _ts_metadata3("design:type", Function),
669
+ _ts_metadata3("design:paramtypes", [
442
670
  typeof Container === "undefined" ? Object : Container,
443
671
  typeof PgBossJobRegistryMap === "undefined" ? Object : PgBossJobRegistryMap,
444
- typeof PgBoss2 === "undefined" ? Object : PgBoss2,
672
+ typeof PgBoss3 === "undefined" ? Object : PgBoss3,
445
673
  typeof Logger === "undefined" ? Object : Logger
446
674
  ])
447
675
  ], PgBossJobRunner);
448
676
  export {
449
677
  PgBossConnectionProvider,
450
678
  PgBossJobBroker,
679
+ PgBossJobMonitor,
451
680
  PgBossJobRegistryMap,
452
681
  PgBossJobRunner
453
682
  };