@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.
- package/AGENTS.md +74 -25
- package/README.md +82 -18
- package/dist/{chunk-MR3BBUMG.js → chunk-KI5S6IPU.js} +1 -1
- package/dist/chunk-KI5S6IPU.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/job.broker.d.ts +65 -11
- package/dist/job.broker.d.ts.map +1 -1
- package/dist/job.schedule.d.ts +23 -0
- package/dist/job.schedule.d.ts.map +1 -0
- package/dist/job.schedule.options.d.ts +65 -0
- package/dist/job.schedule.options.d.ts.map +1 -0
- package/dist/job.send.options.d.ts +25 -0
- package/dist/job.send.options.d.ts.map +1 -1
- package/dist/job.worker.policy.d.ts +25 -0
- package/dist/job.worker.policy.d.ts.map +1 -1
- package/dist/pgboss/pgboss.job.broker.d.ts +77 -15
- package/dist/pgboss/pgboss.job.broker.d.ts.map +1 -1
- package/dist/pgboss/pgboss.job.runner.d.ts +2 -0
- package/dist/pgboss/pgboss.job.runner.d.ts.map +1 -1
- package/dist/pgboss.js +155 -20
- package/dist/pgboss.js.map +1 -1
- package/package.json +6 -5
- package/dist/chunk-MR3BBUMG.js.map +0 -1
|
@@ -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;
|
|
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;
|
|
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
|
|
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
|
|
90
|
+
* Schedules a recurring job on a cron expression or an RFC 5545 recurrence rule.
|
|
83
91
|
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
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};
|
|
90
|
-
*
|
|
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
|
|
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
|
-
* @
|
|
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
|
-
|
|
117
|
+
private toScheduleOptions;
|
|
100
118
|
/**
|
|
101
119
|
* Removes a scheduled job from pg-boss.
|
|
102
120
|
*
|
|
103
|
-
* This stops future executions of the
|
|
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
|
-
*
|
|
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,
|
|
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
|
|
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-
|
|
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
|
|
155
|
+
* Schedules a recurring job on a cron expression or an RFC 5545 recurrence rule.
|
|
149
156
|
*
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
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};
|
|
156
|
-
*
|
|
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
|
|
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
|
-
* @
|
|
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,
|
|
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,
|
|
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
|
|
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
|
-
*
|
|
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
|
/**
|