@maroonedsoftware/jobbroker 1.12.3 → 1.14.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,65 @@
1
+ import { DateTime } from 'luxon';
2
+ /**
3
+ * Options controlling a recurring schedule created by {@link JobBroker.schedule}.
4
+ *
5
+ * Like {@link JobSendOptions}, these describe intent rather than a particular
6
+ * backend's wire format. A backend that cannot honour one of them throws a
7
+ * `NotSupportedError` rather than silently ignoring it (see {@link JobBroker}).
8
+ */
9
+ export interface JobScheduleOptions {
10
+ /**
11
+ * Distinguishes this schedule from the others on the same job name.
12
+ *
13
+ * A job name holds one schedule per key, so a single queue can carry many
14
+ * independent schedules (one per user, per tenant, per routine) by giving
15
+ * each its own key. Scheduling again with a key that already exists replaces
16
+ * that schedule and leaves the others alone.
17
+ *
18
+ * When omitted, the schedule is the job name's single unkeyed schedule, which
19
+ * is what a call without options has always created.
20
+ */
21
+ key?: string;
22
+ /**
23
+ * The IANA time zone the recurrence is evaluated in (e.g. `America/Chicago`).
24
+ *
25
+ * A daily `0 9 * * *` with `timeZone: 'Europe/Paris'` fires at 09:00 Paris
26
+ * time, tracking daylight saving. When omitted, the recurrence is evaluated
27
+ * in UTC. An unknown zone is rejected when the schedule is created.
28
+ */
29
+ timeZone?: string;
30
+ /**
31
+ * What to do about occurrences that came due while nothing was running to
32
+ * send them, such as during a deploy or an outage.
33
+ *
34
+ * - `'skip'` sends nothing for them and waits for the next occurrence.
35
+ * - `'once'` sends a single job for the most recent missed occurrence, however
36
+ * many were missed.
37
+ *
38
+ * When omitted, the backend's default applies (`'skip'` for pg-boss).
39
+ */
40
+ missed?: 'skip' | 'once';
41
+ }
42
+ /**
43
+ * Options for {@link JobBroker.previewSchedule}.
44
+ */
45
+ export interface JobSchedulePreviewOptions {
46
+ /**
47
+ * The IANA time zone to evaluate the recurrence in, as
48
+ * {@link JobScheduleOptions.timeZone} would. Defaults to UTC. The returned
49
+ * `DateTime`s are in this zone.
50
+ */
51
+ timeZone?: string;
52
+ /**
53
+ * The point the preview starts from. Occurrences are strictly after it, so
54
+ * passing the last occurrence of one page back in yields the next page.
55
+ * Defaults to now.
56
+ */
57
+ from?: DateTime;
58
+ /**
59
+ * How many occurrences to return. A finite recurrence rule may return fewer,
60
+ * and one whose last occurrence has passed returns none. Defaults to the
61
+ * backend's default (5 for pg-boss, which allows at most 1000).
62
+ */
63
+ count?: number;
64
+ }
65
+ //# sourceMappingURL=job.schedule.options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"job.schedule.options.d.ts","sourceRoot":"","sources":["../src/job.schedule.options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
@@ -29,5 +29,30 @@ export interface JobSendOptions {
29
29
  * `NotSupportedError`.
30
30
  */
31
31
  startAfter?: Duration | DateTime;
32
+ /**
33
+ * Put the job in a group, so a worker can cap how many jobs of one group run
34
+ * at once (see {@link JobWorkerPolicy.groupConcurrency}).
35
+ *
36
+ * - `id` names the group. Jobs that must not overlap share an id: with a
37
+ * group concurrency of 1, jobs sharing an id run one after another while
38
+ * jobs in other groups run alongside them.
39
+ * - `tier` optionally places the group in a tier, so a worker can give
40
+ * different tiers different limits (`groupConcurrency.tiers`).
41
+ *
42
+ * Grouping has no effect on its own; it only matters once the queue's
43
+ * worker sets a group concurrency. Backends map this onto their native
44
+ * grouping (pg-boss's `group` job option). A backend without job groups
45
+ * throws a `NotSupportedError`.
46
+ *
47
+ * @example
48
+ * ```typescript
49
+ * // One conversation's replies stay in order; other conversations run in parallel.
50
+ * await broker.send('chat.reply', payload, { group: { id: conversationId } });
51
+ * ```
52
+ */
53
+ group?: {
54
+ id: string;
55
+ tier?: string;
56
+ };
32
57
  }
33
58
  //# sourceMappingURL=job.send.options.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"job.send.options.d.ts","sourceRoot":"","sources":["../src/job.send.options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAClC"}
1
+ {"version":3,"file":"job.send.options.d.ts","sourceRoot":"","sources":["../src/job.send.options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC"}
@@ -55,5 +55,30 @@ export interface JobWorkerPolicy {
55
55
  * it as a fractional second count, not rounded.
56
56
  */
57
57
  pollInterval?: Duration;
58
+ /**
59
+ * The most jobs of one group (see {@link JobSendOptions.group}) that may run
60
+ * at once, across every node consuming the queue. pg-boss tracks it in the
61
+ * database, so the limit holds however many nodes and workers are running.
62
+ * Jobs sent without a group are not limited by it.
63
+ *
64
+ * The count is shared, but the limit is still this worker's: each node checks
65
+ * the database against the value it was started with, so give every node
66
+ * consuming the queue the same value.
67
+ *
68
+ * Pass a number for one limit on every group, or `{ default, tiers }` to give
69
+ * groups in particular tiers their own limit, with `default` covering the
70
+ * rest. A limit of 1 keeps each group's jobs strictly one at a time while
71
+ * {@link concurrency} still lets different groups run side by side.
72
+ *
73
+ * @example
74
+ * ```typescript
75
+ * // Three jobs at once on this node, but never two from the same group.
76
+ * const worker: JobWorkerPolicy = { concurrency: 3, groupConcurrency: 1 };
77
+ * ```
78
+ */
79
+ groupConcurrency?: number | {
80
+ default: number;
81
+ tiers?: Record<string, number>;
82
+ };
58
83
  }
59
84
  //# sourceMappingURL=job.worker.policy.d.ts.map
@@ -1 +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"}
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;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CACjF"}
@@ -1,6 +1,9 @@
1
1
  import { PgBoss } from 'pg-boss';
2
+ import { DateTime } from 'luxon';
2
3
  import { JobBroker } from '../job.broker.js';
3
4
  import { JobInfo } from '../job.info.js';
5
+ import { JobSchedule } from '../job.schedule.js';
6
+ import { JobScheduleOptions, JobSchedulePreviewOptions } from '../job.schedule.options.js';
4
7
  import { JobSendOptions } from '../job.send.options.js';
5
8
  import { PgBossJobRegistryMap } from './pgboss.job.registration.js';
6
9
  import { PgBossConnectionProvider } from './pgboss.connection.provider.js';
@@ -9,7 +12,8 @@ import { PgBossConnectionProvider } from './pgboss.connection.provider.js';
9
12
  *
10
13
  * This broker uses PostgreSQL (via pg-boss) as the backing queue for job
11
14
  * processing. It provides reliable, transactional job queuing with support
12
- * for scheduled jobs using cron expressions.
15
+ * for recurring schedules on cron expressions or RFC 5545 recurrence rules,
16
+ * many per queue when each has its own key.
13
17
  *
14
18
  * Each enqueue and schedule call sources its pg-boss `db` executor from the
15
19
  * injected {@link PgBossConnectionProvider}. The default provider returns
@@ -59,10 +63,14 @@ export declare class PgBossJobBroker extends JobBroker {
59
63
  * {@link Duration} is converted to a relative number of seconds and a
60
64
  * {@link DateTime} to an absolute `Date`.
61
65
  *
66
+ * When `options.group` is supplied it is passed through as pg-boss's `group`
67
+ * job option, so a worker's `groupConcurrency` can limit how many jobs of that
68
+ * group run at once.
69
+ *
62
70
  * @typeParam Payload - The type of the job payload.
63
71
  * @param name - The name of the registered job to execute.
64
72
  * @param payload - The data to pass to the job handler.
65
- * @param options - Optional enqueue options, e.g. `startAfter` to defer the job.
73
+ * @param options - Optional enqueue options, e.g. `startAfter` to defer the job or `group` to group it.
66
74
  * @returns A promise that resolves with the id of the queued job.
67
75
  * @throws Error if the job name is not found in the registry.
68
76
  * @throws Error if pg-boss does not return a job id (e.g. the job was
@@ -79,35 +87,89 @@ export declare class PgBossJobBroker extends JobBroker {
79
87
  */
80
88
  private toStartAfter;
81
89
  /**
82
- * Schedules a recurring job using a cron expression.
90
+ * Schedules a recurring job on a cron expression or an RFC 5545 recurrence rule.
83
91
  *
84
- * The job will be automatically enqueued by pg-boss according to the
85
- * specified cron schedule. If a schedule already exists for this job,
86
- * it will be updated with the new cron expression and payload.
92
+ * pg-boss decides the format from the expression itself and stores one row
93
+ * per job name and key, so scheduling again with the same name and key
94
+ * replaces that row. The options map onto pg-boss's own: `key` to `key`,
95
+ * `timeZone` to `tz`, and `missed` to `missed`. pg-boss validates the
96
+ * recurrence and the zone before writing and throws on either.
87
97
  *
88
98
  * The schedule-insert SQL runs against the executor returned by the injected
89
- * {@link PgBossConnectionProvider}; the default executor uses pg-boss's own
90
- * pool, which is the expected behavior for bootstrap-time scheduling.
99
+ * {@link PgBossConnectionProvider}; when that executor is bound to an active
100
+ * transaction, the schedule commits or rolls back with it.
91
101
  *
92
102
  * @typeParam Payload - The type of the job payload.
93
103
  * @param name - The name of the registered job to schedule.
94
- * @param cron - A cron expression (e.g., '0 9 * * *' for daily at 9am).
104
+ * @param recurrence - A cron expression or an RFC 5545 recurrence rule.
95
105
  * @param payload - Optional data to pass to the job on each execution.
96
- * @returns A promise that resolves when the schedule has been created.
106
+ * @param options - Optional key, time zone and missed-occurrence policy.
107
+ * @returns A promise that resolves when the schedule has been created or replaced.
97
108
  * @throws Error if the job name is not found in the registry.
109
+ * @throws Error if pg-boss rejects the recurrence, the time zone or the key.
110
+ */
111
+ schedule<Payload extends object>(name: string, recurrence: string, payload?: Payload, options?: JobScheduleOptions): Promise<void>;
112
+ /**
113
+ * Maps backend-agnostic schedule options onto pg-boss's `key`, `tz` and
114
+ * `missed`, leaving out any that were not given so pg-boss applies its own
115
+ * defaults (the unkeyed schedule, UTC, and `skip`).
98
116
  */
99
- schedule<Payload extends object>(name: string, cron: string, payload?: Payload): Promise<void>;
117
+ private toScheduleOptions;
100
118
  /**
101
119
  * Removes a scheduled job from pg-boss.
102
120
  *
103
- * This stops future executions of the scheduled job. Jobs that are
104
- * already queued will still be processed.
121
+ * This stops future executions of the schedule with the given name and key.
122
+ * Jobs that are already queued will still be processed. pg-boss reads a
123
+ * missing key as the empty key, so `unschedule(name)` removes only the
124
+ * unkeyed schedule and leaves keyed ones in place.
105
125
  *
106
- * @param name - The name of the scheduled job to remove.
126
+ * The delete runs against the executor returned by the injected
127
+ * {@link PgBossConnectionProvider}, so inside a transaction it rolls back
128
+ * with the transaction.
129
+ *
130
+ * @param name - The name of the scheduled job.
131
+ * @param key - The key the schedule was created with, if any.
107
132
  * @returns A promise that resolves when the schedule has been removed.
108
133
  * @throws Error if the job name is not found in the registry.
109
134
  */
110
- unschedule(name: string): Promise<void>;
135
+ unschedule(name: string, key?: string): Promise<void>;
136
+ /**
137
+ * Lists the schedules on a job name from pg-boss.
138
+ *
139
+ * With a key this reads the one row by its primary key. Without one it pages
140
+ * through every schedule on the name, so a queue with many keyed schedules is
141
+ * returned whole rather than cut off at pg-boss's page size.
142
+ *
143
+ * pg-boss offers no connection option for this read, so it always runs on
144
+ * pg-boss's own pool: a schedule written inside a transaction that has not
145
+ * committed yet is not visible here.
146
+ *
147
+ * @typeParam Payload - The type of the scheduled payload.
148
+ * @param name - The name of the registered job.
149
+ * @param key - When given, only the schedule with this key.
150
+ * @returns A promise that resolves with the matching schedules, ordered by key.
151
+ * @throws Error if the job name is not found in the registry.
152
+ */
153
+ getSchedules<Payload extends object>(name: string, key?: string): Promise<JobSchedule<Payload>[]>;
154
+ /** Rows read per page when {@link getSchedules} lists every schedule on a name. */
155
+ private static readonly schedulePageSize;
156
+ /** Maps a pg-boss schedule row onto the backend-agnostic {@link JobSchedule}. */
157
+ private toJobSchedule;
158
+ /**
159
+ * Computes the next occurrences of a recurrence with pg-boss's
160
+ * `previewSchedule`, which validates exactly as {@link schedule} does and
161
+ * touches neither the database nor the schedule table.
162
+ *
163
+ * `from` defaults to pg-boss's reading of database time, which on an instance
164
+ * that runs schedules accounts for clock skew against the database. The
165
+ * returned `DateTime`s are in `options.timeZone`, or UTC when omitted.
166
+ *
167
+ * @param recurrence - A cron expression or an RFC 5545 recurrence rule.
168
+ * @param options - Optional time zone, starting point and count.
169
+ * @returns A promise that resolves with the occurrences, earliest first.
170
+ * @throws Error if pg-boss rejects the recurrence, the time zone or the count.
171
+ */
172
+ previewSchedule(recurrence: string, options?: JobSchedulePreviewOptions): Promise<DateTime[]>;
111
173
  /**
112
174
  * Cancels one or more jobs in the PgBoss queue.
113
175
  *
@@ -1 +1 @@
1
- {"version":3,"file":"pgboss.job.broker.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.broker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGjC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAW1C,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAZrC;;;;;;;;OAQG;gBAEgB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,wBAAwB;IAK/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB7G;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;;;;;;;;OAiBG;IACG,QAAQ,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpG;;;;;;;;;OASG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnE;;;;;;;;;OASG;IACG,MAAM,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAYjG"}
1
+ {"version":3,"file":"pgboss.job.broker.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.broker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAuC,MAAM,SAAS,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAY,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAW1C,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAZrC;;;;;;;;OAQG;gBAEgB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,wBAAwB;IAK/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,IAAI,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB7G;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxI;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3D;;;;;;;;;;;;;;;;OAgBG;IACG,YAAY,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAyBvG,mFAAmF;IACnF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IAEhD,iFAAiF;IACjF,OAAO,CAAC,aAAa;IAUrB;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAWnG;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhE;;;;;;;OAOG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnE;;;;;;;;;OASG;IACG,MAAM,CAAC,OAAO,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAYjG"}
@@ -194,6 +194,8 @@ export declare class PgBossJobRunner extends JobRunner {
194
194
  * options. `pollInterval` is passed as a fractional second count rather than
195
195
  * rounded — pg-boss accepts intervals down to 0.5s, so rounding would turn a
196
196
  * deliberate sub-second poll into either 0 (rejected) or 1.
197
+ * `groupConcurrency` maps to pg-boss's database-tracked `groupConcurrency`, so
198
+ * the per-group limit holds across nodes, not just within this one.
197
199
  *
198
200
  * Always returns options, because `perJobResults` is always on: it is what makes
199
201
  * pg-boss settle each job in a batch individually, and what gives
@@ -1 +1 @@
1
- {"version":3,"file":"pgboss.job.runner.d.ts","sourceRoot":"","sources":["../../src/pgboss/pgboss.job.runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,MAAM,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAyB,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAiClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAuD1C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzDzB;;;;;;;;OAQG;IACH,yBAAyB,SAAK;IAE9B;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,cAAc,CAAC;IAEpC;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,EAAE,eAAe,CAAC;IAEtC;;;;;;;;OAQG;gBAEgB,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;IAKjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2G5B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;OAWG;YACW,WAAW;IAuBzB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;;;;;;;;;;;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,EAA2B,MAAM,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAyB,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAiClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,eAAgB,SAAQ,SAAS;IAuD1C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzDzB;;;;;;;;OAQG;IACH,yBAAyB,SAAK;IAE9B;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,cAAc,CAAC;IAEpC;;;;;;;;;;;;;;;;OAgBG;IACH,mBAAmB,CAAC,EAAE,eAAe,CAAC;IAEtC;;;;;;;;OAQG;gBAEgB,SAAS,EAAE,SAAS,EACpB,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;IAKjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2G5B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;OAWG;YACW,WAAW;IAuBzB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,aAAa;IAiBrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
package/dist/pgboss.js CHANGED
@@ -5,7 +5,7 @@ import {
5
5
  JobRunner,
6
6
  PermanentJobError,
7
7
  __name
8
- } from "./chunk-MR3BBUMG.js";
8
+ } from "./chunk-KI5S6IPU.js";
9
9
 
10
10
  // src/pgboss/pgboss.job.broker.ts
11
11
  import { PgBoss } from "pg-boss";
@@ -70,7 +70,7 @@ function _ts_metadata(k, v) {
70
70
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
71
71
  }
72
72
  __name(_ts_metadata, "_ts_metadata");
73
- var PgBossJobBroker = class extends JobBroker {
73
+ var PgBossJobBroker = class _PgBossJobBroker extends JobBroker {
74
74
  static {
75
75
  __name(this, "PgBossJobBroker");
76
76
  }
@@ -101,10 +101,14 @@ var PgBossJobBroker = class extends JobBroker {
101
101
  * {@link Duration} is converted to a relative number of seconds and a
102
102
  * {@link DateTime} to an absolute `Date`.
103
103
  *
104
+ * When `options.group` is supplied it is passed through as pg-boss's `group`
105
+ * job option, so a worker's `groupConcurrency` can limit how many jobs of that
106
+ * group run at once.
107
+ *
104
108
  * @typeParam Payload - The type of the job payload.
105
109
  * @param name - The name of the registered job to execute.
106
110
  * @param payload - The data to pass to the job handler.
107
- * @param options - Optional enqueue options, e.g. `startAfter` to defer the job.
111
+ * @param options - Optional enqueue options, e.g. `startAfter` to defer the job or `group` to group it.
108
112
  * @returns A promise that resolves with the id of the queued job.
109
113
  * @throws Error if the job name is not found in the registry.
110
114
  * @throws Error if pg-boss does not return a job id (e.g. the job was
@@ -116,7 +120,10 @@ var PgBossJobBroker = class extends JobBroker {
116
120
  }
117
121
  const id = await this.pgboss.send(name, payload, {
118
122
  db: this.connectionProvider.executor(),
119
- ...this.toStartAfter(options?.startAfter)
123
+ ...this.toStartAfter(options?.startAfter),
124
+ ...options?.group ? {
125
+ group: options.group
126
+ } : {}
120
127
  });
121
128
  if (!id) {
122
129
  throw new Error(`Failed to enqueue job ${name}`);
@@ -145,46 +152,169 @@ var PgBossJobBroker = class extends JobBroker {
145
152
  return {};
146
153
  }
147
154
  /**
148
- * Schedules a recurring job using a cron expression.
155
+ * Schedules a recurring job on a cron expression or an RFC 5545 recurrence rule.
149
156
  *
150
- * The job will be automatically enqueued by pg-boss according to the
151
- * specified cron schedule. If a schedule already exists for this job,
152
- * it will be updated with the new cron expression and payload.
157
+ * pg-boss decides the format from the expression itself and stores one row
158
+ * per job name and key, so scheduling again with the same name and key
159
+ * replaces that row. The options map onto pg-boss's own: `key` to `key`,
160
+ * `timeZone` to `tz`, and `missed` to `missed`. pg-boss validates the
161
+ * recurrence and the zone before writing and throws on either.
153
162
  *
154
163
  * The schedule-insert SQL runs against the executor returned by the injected
155
- * {@link PgBossConnectionProvider}; the default executor uses pg-boss's own
156
- * pool, which is the expected behavior for bootstrap-time scheduling.
164
+ * {@link PgBossConnectionProvider}; when that executor is bound to an active
165
+ * transaction, the schedule commits or rolls back with it.
157
166
  *
158
167
  * @typeParam Payload - The type of the job payload.
159
168
  * @param name - The name of the registered job to schedule.
160
- * @param cron - A cron expression (e.g., '0 9 * * *' for daily at 9am).
169
+ * @param recurrence - A cron expression or an RFC 5545 recurrence rule.
161
170
  * @param payload - Optional data to pass to the job on each execution.
162
- * @returns A promise that resolves when the schedule has been created.
171
+ * @param options - Optional key, time zone and missed-occurrence policy.
172
+ * @returns A promise that resolves when the schedule has been created or replaced.
163
173
  * @throws Error if the job name is not found in the registry.
174
+ * @throws Error if pg-boss rejects the recurrence, the time zone or the key.
164
175
  */
165
- async schedule(name, cron, payload) {
176
+ async schedule(name, recurrence, payload, options) {
166
177
  if (!this.registrations.has(name)) {
167
178
  throw new Error(`Job ${name} is not registered`);
168
179
  }
169
- await this.pgboss.schedule(name, cron, payload, {
170
- db: this.connectionProvider.executor()
180
+ await this.pgboss.schedule(name, recurrence, payload, {
181
+ db: this.connectionProvider.executor(),
182
+ ...this.toScheduleOptions(options)
171
183
  });
172
184
  }
173
185
  /**
186
+ * Maps backend-agnostic schedule options onto pg-boss's `key`, `tz` and
187
+ * `missed`, leaving out any that were not given so pg-boss applies its own
188
+ * defaults (the unkeyed schedule, UTC, and `skip`).
189
+ */
190
+ toScheduleOptions(options) {
191
+ return {
192
+ ...options?.key !== void 0 && {
193
+ key: options.key
194
+ },
195
+ ...options?.timeZone !== void 0 && {
196
+ tz: options.timeZone
197
+ },
198
+ ...options?.missed !== void 0 && {
199
+ missed: options.missed
200
+ }
201
+ };
202
+ }
203
+ /**
174
204
  * Removes a scheduled job from pg-boss.
175
205
  *
176
- * This stops future executions of the scheduled job. Jobs that are
177
- * already queued will still be processed.
206
+ * This stops future executions of the schedule with the given name and key.
207
+ * Jobs that are already queued will still be processed. pg-boss reads a
208
+ * missing key as the empty key, so `unschedule(name)` removes only the
209
+ * unkeyed schedule and leaves keyed ones in place.
178
210
  *
179
- * @param name - The name of the scheduled job to remove.
211
+ * The delete runs against the executor returned by the injected
212
+ * {@link PgBossConnectionProvider}, so inside a transaction it rolls back
213
+ * with the transaction.
214
+ *
215
+ * @param name - The name of the scheduled job.
216
+ * @param key - The key the schedule was created with, if any.
180
217
  * @returns A promise that resolves when the schedule has been removed.
181
218
  * @throws Error if the job name is not found in the registry.
182
219
  */
183
- async unschedule(name) {
220
+ async unschedule(name, key) {
184
221
  if (!this.registrations.has(name)) {
185
222
  throw new Error(`Job ${name} is not registered`);
186
223
  }
187
- await this.pgboss.unschedule(name);
224
+ await this.pgboss.unschedule(name, key, {
225
+ db: this.connectionProvider.executor()
226
+ });
227
+ }
228
+ /**
229
+ * Lists the schedules on a job name from pg-boss.
230
+ *
231
+ * With a key this reads the one row by its primary key. Without one it pages
232
+ * through every schedule on the name, so a queue with many keyed schedules is
233
+ * returned whole rather than cut off at pg-boss's page size.
234
+ *
235
+ * pg-boss offers no connection option for this read, so it always runs on
236
+ * pg-boss's own pool: a schedule written inside a transaction that has not
237
+ * committed yet is not visible here.
238
+ *
239
+ * @typeParam Payload - The type of the scheduled payload.
240
+ * @param name - The name of the registered job.
241
+ * @param key - When given, only the schedule with this key.
242
+ * @returns A promise that resolves with the matching schedules, ordered by key.
243
+ * @throws Error if the job name is not found in the registry.
244
+ */
245
+ async getSchedules(name, key) {
246
+ if (!this.registrations.has(name)) {
247
+ throw new Error(`Job ${name} is not registered`);
248
+ }
249
+ if (key !== void 0) {
250
+ const schedule = await this.pgboss.getSchedule(name, key);
251
+ return schedule ? [
252
+ this.toJobSchedule(schedule)
253
+ ] : [];
254
+ }
255
+ const schedules = [];
256
+ let after;
257
+ for (; ; ) {
258
+ const page = await this.pgboss.getSchedules(name, void 0, {
259
+ limit: _PgBossJobBroker.schedulePageSize,
260
+ ...after && {
261
+ after
262
+ }
263
+ });
264
+ schedules.push(...page);
265
+ const last = page.at(-1);
266
+ if (page.length < _PgBossJobBroker.schedulePageSize || !last) {
267
+ break;
268
+ }
269
+ after = {
270
+ name: last.name,
271
+ key: last.key
272
+ };
273
+ }
274
+ return schedules.map((schedule) => this.toJobSchedule(schedule));
275
+ }
276
+ /** Rows read per page when {@link getSchedules} lists every schedule on a name. */
277
+ static schedulePageSize = 1e3;
278
+ /** Maps a pg-boss schedule row onto the backend-agnostic {@link JobSchedule}. */
279
+ toJobSchedule(schedule) {
280
+ return {
281
+ name: schedule.name,
282
+ key: schedule.key,
283
+ recurrence: schedule.cron,
284
+ timeZone: schedule.timezone || "UTC",
285
+ ...schedule.data != null && {
286
+ payload: schedule.data
287
+ }
288
+ };
289
+ }
290
+ /**
291
+ * Computes the next occurrences of a recurrence with pg-boss's
292
+ * `previewSchedule`, which validates exactly as {@link schedule} does and
293
+ * touches neither the database nor the schedule table.
294
+ *
295
+ * `from` defaults to pg-boss's reading of database time, which on an instance
296
+ * that runs schedules accounts for clock skew against the database. The
297
+ * returned `DateTime`s are in `options.timeZone`, or UTC when omitted.
298
+ *
299
+ * @param recurrence - A cron expression or an RFC 5545 recurrence rule.
300
+ * @param options - Optional time zone, starting point and count.
301
+ * @returns A promise that resolves with the occurrences, earliest first.
302
+ * @throws Error if pg-boss rejects the recurrence, the time zone or the count.
303
+ */
304
+ async previewSchedule(recurrence, options) {
305
+ const zone = options?.timeZone ?? "UTC";
306
+ const occurrences = this.pgboss.previewSchedule(recurrence, {
307
+ tz: zone,
308
+ ...options?.from !== void 0 && {
309
+ from: options.from.toJSDate()
310
+ },
311
+ ...options?.count !== void 0 && {
312
+ count: options.count
313
+ }
314
+ });
315
+ return occurrences.map((occurrence) => DateTime.fromJSDate(occurrence, {
316
+ zone
317
+ }));
188
318
  }
189
319
  /**
190
320
  * Cancels one or more jobs in the PgBoss queue.
@@ -714,6 +844,8 @@ var PgBossJobRunner = class extends JobRunner {
714
844
  * options. `pollInterval` is passed as a fractional second count rather than
715
845
  * rounded — pg-boss accepts intervals down to 0.5s, so rounding would turn a
716
846
  * deliberate sub-second poll into either 0 (rejected) or 1.
847
+ * `groupConcurrency` maps to pg-boss's database-tracked `groupConcurrency`, so
848
+ * the per-group limit holds across nodes, not just within this one.
717
849
  *
718
850
  * Always returns options, because `perJobResults` is always on: it is what makes
719
851
  * pg-boss settle each job in a batch individually, and what gives
@@ -737,6 +869,9 @@ var PgBossJobRunner = class extends JobRunner {
737
869
  if (policy?.pollInterval !== void 0) {
738
870
  options.pollingIntervalSeconds = policy.pollInterval.as("seconds");
739
871
  }
872
+ if (policy?.groupConcurrency !== void 0) {
873
+ options.groupConcurrency = policy.groupConcurrency;
874
+ }
740
875
  return options;
741
876
  }
742
877
  /**