@maroonedsoftware/jobbroker 1.5.0 → 1.7.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/LICENSE +1 -1
- package/README.md +76 -24
- package/dist/chunk-VPYK6KC5.js +45 -0
- package/dist/chunk-VPYK6KC5.js.map +1 -0
- package/dist/index.d.ts +2 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +25 -295
- package/dist/index.js.map +1 -1
- package/dist/job.broker.d.ts +73 -7
- package/dist/job.broker.d.ts.map +1 -1
- package/dist/job.d.ts +14 -3
- package/dist/job.d.ts.map +1 -1
- package/dist/job.info.d.ts +38 -0
- package/dist/job.info.d.ts.map +1 -0
- package/dist/not.supported.error.d.ts +37 -0
- package/dist/not.supported.error.d.ts.map +1 -0
- package/dist/pgboss/pgboss.job.broker.d.ts +51 -2
- package/dist/pgboss/pgboss.job.broker.d.ts.map +1 -1
- package/dist/pgboss/pgboss.job.runner.d.ts +26 -0
- package/dist/pgboss/pgboss.job.runner.d.ts.map +1 -1
- package/dist/pgboss.d.ts +5 -0
- package/dist/pgboss.d.ts.map +1 -0
- package/dist/pgboss.js +417 -0
- package/dist/pgboss.js.map +1 -0
- package/package.json +22 -5
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -8,6 +8,7 @@ A flexible background job processing library with support for scheduled and on-d
|
|
|
8
8
|
- **Dependency injection** support via [injectkit](https://www.npmjs.com/package/injectkit)
|
|
9
9
|
- **Scheduled jobs** using cron expressions
|
|
10
10
|
- **On-demand jobs** for immediate execution
|
|
11
|
+
- **Cancellation** of queued _and_ running jobs, plus state lookup, delete, and resume
|
|
11
12
|
- **PostgreSQL backing** for reliability and transactional guarantees
|
|
12
13
|
|
|
13
14
|
## Installation
|
|
@@ -18,6 +19,13 @@ pnpm add @maroonedsoftware/jobbroker injectkit pg-boss reflect-metadata
|
|
|
18
19
|
|
|
19
20
|
> **Note:** InjectKit requires `reflect-metadata` to be imported at your application entry point and TypeScript configured with `experimentalDecorators: true` and `emitDecoratorMetadata: true`.
|
|
20
21
|
|
|
22
|
+
`pg-boss` is an optional peer dependency. The pg-boss backend lives behind a subpath export so importing the core (`@maroonedsoftware/jobbroker`) never loads it:
|
|
23
|
+
|
|
24
|
+
| Import | Contents | Pulls in |
|
|
25
|
+
| ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------- |
|
|
26
|
+
| `@maroonedsoftware/jobbroker` | `Job`, `JobBroker`, `JobRunner`, `JobInfo`, `JobState`, `NotSupportedError` | nothing extra |
|
|
27
|
+
| `@maroonedsoftware/jobbroker/pgboss` | `PgBossJobBroker`, `PgBossJobRunner`, `PgBossJobRegistryMap`, `PgBossConnectionProvider` | `pg-boss` |
|
|
28
|
+
|
|
21
29
|
## Quick Start
|
|
22
30
|
|
|
23
31
|
### 1. Define a Job
|
|
@@ -40,18 +48,21 @@ export class SendEmailJob extends Job<EmailPayload> {
|
|
|
40
48
|
super();
|
|
41
49
|
}
|
|
42
50
|
|
|
43
|
-
async run(payload: EmailPayload): Promise<void> {
|
|
44
|
-
|
|
51
|
+
async run(payload: EmailPayload, signal?: AbortSignal): Promise<void> {
|
|
52
|
+
// Forward `signal` to async work so the job stops promptly when cancelled.
|
|
53
|
+
await this.emailService.send(payload.to, payload.subject, payload.body, { signal });
|
|
45
54
|
}
|
|
46
55
|
}
|
|
47
56
|
```
|
|
48
57
|
|
|
58
|
+
> The optional `signal` is aborted when the job is cancelled or the runner shuts down. Honoring it is how a long-running job becomes cancellable — see [Cancelling jobs](#cancelling-jobs).
|
|
59
|
+
|
|
49
60
|
### 2. Register Jobs
|
|
50
61
|
|
|
51
62
|
Create a registry and register your jobs:
|
|
52
63
|
|
|
53
64
|
```typescript
|
|
54
|
-
import { PgBossJobRegistryMap } from '@maroonedsoftware/jobbroker';
|
|
65
|
+
import { PgBossJobRegistryMap } from '@maroonedsoftware/jobbroker/pgboss';
|
|
55
66
|
|
|
56
67
|
const registry = new PgBossJobRegistryMap();
|
|
57
68
|
|
|
@@ -72,7 +83,8 @@ import 'reflect-metadata';
|
|
|
72
83
|
import { PgBoss } from 'pg-boss';
|
|
73
84
|
import { InjectKitRegistry } from 'injectkit';
|
|
74
85
|
import { ConsoleLogger, Logger } from '@maroonedsoftware/logger';
|
|
75
|
-
import {
|
|
86
|
+
import { JobBroker, JobRunner } from '@maroonedsoftware/jobbroker';
|
|
87
|
+
import { PgBossJobBroker, PgBossJobRunner, PgBossJobRegistryMap, PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
76
88
|
|
|
77
89
|
// Initialize pg-boss
|
|
78
90
|
const pgboss = new PgBoss('postgres://user:pass@localhost/mydb');
|
|
@@ -102,13 +114,23 @@ Use the broker to queue jobs for processing:
|
|
|
102
114
|
```typescript
|
|
103
115
|
const broker = container.get(JobBroker);
|
|
104
116
|
|
|
105
|
-
// Send an immediate job
|
|
106
|
-
await broker.send('send-email', {
|
|
117
|
+
// Send an immediate job — returns the job id so you can reference it later
|
|
118
|
+
const id = await broker.send('send-email', {
|
|
107
119
|
to: 'user@example.com',
|
|
108
120
|
subject: 'Welcome!',
|
|
109
121
|
body: 'Thanks for signing up.',
|
|
110
122
|
});
|
|
111
123
|
|
|
124
|
+
// Inspect a job's current state
|
|
125
|
+
const info = await broker.getJob('send-email', id); // { id, name, state, data } | null
|
|
126
|
+
|
|
127
|
+
// Cancel it (works whether it is still queued or already running)
|
|
128
|
+
await broker.cancel('send-email', id);
|
|
129
|
+
|
|
130
|
+
// Bring a cancelled job back, or remove it entirely
|
|
131
|
+
await broker.resume('send-email', id);
|
|
132
|
+
await broker.deleteJob('send-email', id);
|
|
133
|
+
|
|
112
134
|
// Schedule a recurring job programmatically
|
|
113
135
|
await broker.schedule('cleanup', '0 0 * * *', { olderThan: 30 });
|
|
114
136
|
|
|
@@ -116,25 +138,53 @@ await broker.schedule('cleanup', '0 0 * * *', { olderThan: 30 });
|
|
|
116
138
|
await broker.unschedule('cleanup');
|
|
117
139
|
```
|
|
118
140
|
|
|
141
|
+
## Cancelling jobs
|
|
142
|
+
|
|
143
|
+
`broker.cancel(name, id)` requests cancellation of a job **whatever state it is in**:
|
|
144
|
+
|
|
145
|
+
- A job that is still **queued** is marked cancelled and never picked up by a worker.
|
|
146
|
+
- A job that is **already running** is asked to stop. Cancellation is _cooperative_: the runner detects the cancellation and aborts the `AbortSignal` passed to the job's `run(payload, signal)`. Handlers must honor the signal (forward it to `fetch`/DB calls, or check `signal.aborted`) to actually stop. **A handler that ignores the signal runs to completion** — Node cannot forcibly terminate it.
|
|
147
|
+
|
|
148
|
+
Cancellation works **across processes**. `cancel` records the state change on the shared PostgreSQL row, and whichever worker process is running the job observes it. That observation is done by polling: while a job runs, `PgBossJobRunner` periodically looks the job up (via pg-boss `findJobs`) and aborts the signal once the state becomes `cancelled` (or the job is deleted). The poll cadence is configurable:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
const runner = container.get(JobRunner) as PgBossJobRunner;
|
|
152
|
+
runner.cancelPollIntervalSeconds = 2; // default 5; set to 0 to disable polling
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Lower values reduce cancellation latency at the cost of one extra lookup query per running job per interval.
|
|
156
|
+
|
|
157
|
+
### Backend portability
|
|
158
|
+
|
|
159
|
+
`cancel`, `resume`, `deleteJob`, and `getJob` are best-effort by contract: a backend that cannot honor an operation throws `NotSupportedError` rather than silently doing nothing. `JobState` (`created | retry | active | completed | cancelled | failed`) is the normalized, lowest-common-denominator lifecycle; alternative backends map their native states to the nearest value. The bundled pg-boss backend supports every operation.
|
|
160
|
+
|
|
119
161
|
## API Reference
|
|
120
162
|
|
|
121
163
|
### `Job<Payload>`
|
|
122
164
|
|
|
123
165
|
Abstract base class for job handlers.
|
|
124
166
|
|
|
125
|
-
| Method
|
|
126
|
-
|
|
|
127
|
-
| `run(payload: Payload): Promise<void>` | Execute the job
|
|
167
|
+
| Method | Description |
|
|
168
|
+
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
|
|
169
|
+
| `run(payload: Payload, signal?: AbortSignal): Promise<void>` | Execute the job. `signal` is aborted on cancellation/shutdown; honoring it is optional. |
|
|
128
170
|
|
|
129
171
|
### `JobBroker`
|
|
130
172
|
|
|
131
|
-
Abstract base class for sending jobs
|
|
173
|
+
Abstract base class for sending, cancelling, and inspecting jobs. Operations a backend cannot honor throw `NotSupportedError`.
|
|
174
|
+
|
|
175
|
+
| Method | Description |
|
|
176
|
+
| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
177
|
+
| `send<P>(name: string, payload: P): Promise<string>` | Queue a job for immediate processing; resolves with the new job id |
|
|
178
|
+
| `schedule<P>(name: string, cron: string, payload?: P): Promise<void>` | Create a recurring job schedule |
|
|
179
|
+
| `unschedule(name: string): Promise<void>` | Remove a recurring job schedule |
|
|
180
|
+
| `cancel(name: string, id: string \| string[]): Promise<void>` | Request cancellation of queued or running jobs (cooperative) |
|
|
181
|
+
| `resume(name: string, id: string \| string[]): Promise<void>` | Re-queue previously cancelled jobs |
|
|
182
|
+
| `deleteJob(name: string, id: string \| string[]): Promise<void>` | Permanently delete jobs |
|
|
183
|
+
| `getJob<P>(name: string, id: string): Promise<JobInfo<P> \| null>` | Look up a job's current state, or `null` if it does not exist |
|
|
132
184
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
| `schedule<P>(name: string, cron: string, payload?: P): Promise<void>` | Create a recurring job schedule |
|
|
137
|
-
| `unschedule(name: string): Promise<void>` | Remove a recurring job schedule |
|
|
185
|
+
### `JobInfo<Payload>` / `JobState`
|
|
186
|
+
|
|
187
|
+
Backend-agnostic snapshot returned by `getJob`. `JobInfo` has `id`, `name`, `state`, and `data`. `JobState` is one of `created`, `retry`, `active`, `completed`, `cancelled`, or `failed`.
|
|
138
188
|
|
|
139
189
|
### `JobRunner`
|
|
140
190
|
|
|
@@ -158,22 +208,22 @@ Entries can be either:
|
|
|
158
208
|
|
|
159
209
|
Configuration object for a scheduled job.
|
|
160
210
|
|
|
161
|
-
| Property | Type
|
|
162
|
-
| -------- |
|
|
163
|
-
| `job` | `Identifier<Job>`
|
|
164
|
-
| `cron` | `string`
|
|
211
|
+
| Property | Type | Description |
|
|
212
|
+
| -------- | ----------------- | ---------------------------------------------------------- |
|
|
213
|
+
| `job` | `Identifier<Job>` | The job class identifier to instantiate when the job runs. |
|
|
214
|
+
| `cron` | `string` | A cron expression defining when the job should run. |
|
|
165
215
|
|
|
166
216
|
### `PgBossJobBroker`
|
|
167
217
|
|
|
168
|
-
Concrete `JobBroker` implementation backed by pg-boss. Constructor signature: `new PgBossJobBroker(registrations: PgBossJobRegistryMap, pgboss: PgBoss, connectionProvider: PgBossConnectionProvider)`.
|
|
218
|
+
Concrete `JobBroker` implementation backed by pg-boss. Constructor signature: `new PgBossJobBroker(registrations: PgBossJobRegistryMap, pgboss: PgBoss, connectionProvider: PgBossConnectionProvider)`. Every operation sources its pg-boss `db` executor from the injected `PgBossConnectionProvider`. Typically resolved through the DI container rather than instantiated directly.
|
|
169
219
|
|
|
170
220
|
### `PgBossConnectionProvider`
|
|
171
221
|
|
|
172
222
|
Supplies the pg-boss `db` executor used when enqueuing or scheduling jobs.
|
|
173
223
|
|
|
174
|
-
| Method
|
|
175
|
-
|
|
|
176
|
-
| `executor(): Db \| undefined`
|
|
224
|
+
| Method | Description |
|
|
225
|
+
| ----------------------------- | -------------------------------------------------------------------------------- |
|
|
226
|
+
| `executor(): Db \| undefined` | The executor to run job-insert SQL against; `undefined` uses pg-boss's own pool. |
|
|
177
227
|
|
|
178
228
|
The default implementation returns `undefined`, so pg-boss uses its own connection pool (standard, non-transactional behavior). Override it on a request-scoped DI container to return a transaction-bound executor and enqueue jobs atomically with the surrounding database transaction — see [Transactional enqueue](#transactional-enqueue).
|
|
179
229
|
|
|
@@ -183,7 +233,7 @@ By default a job row is inserted on pg-boss's own connection, so it commits inde
|
|
|
183
233
|
|
|
184
234
|
```typescript
|
|
185
235
|
import { fromKysely } from 'pg-boss';
|
|
186
|
-
import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker';
|
|
236
|
+
import { PgBossConnectionProvider } from '@maroonedsoftware/jobbroker/pgboss';
|
|
187
237
|
|
|
188
238
|
class TransactionalConnectionProvider extends PgBossConnectionProvider {
|
|
189
239
|
constructor(private readonly trx: Transaction<DB>) {
|
|
@@ -209,6 +259,8 @@ await repository.withTransaction(async trx => {
|
|
|
209
259
|
|
|
210
260
|
Concrete `JobRunner` implementation backed by pg-boss. Constructor signature: `new PgBossJobRunner(container: Container, registrations: PgBossJobRegistryMap, pgboss: PgBoss, logger: Logger)`. Calls `pgboss.start()` during `start()` and `pgboss.stop()` during `stop()`. Job instances are resolved from the DI container on each invocation. Typically resolved through the DI container rather than instantiated directly.
|
|
211
261
|
|
|
262
|
+
Exposes a `cancelPollIntervalSeconds` property (default `5`) that controls how often a running job is polled for cancellation; set it to `0` to disable polling. See [Cancelling jobs](#cancelling-jobs).
|
|
263
|
+
|
|
212
264
|
## Graceful Shutdown
|
|
213
265
|
|
|
214
266
|
Ensure you stop the runner during application shutdown:
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
var __defProp = Object.defineProperty;
|
|
2
|
+
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
|
|
3
|
+
|
|
4
|
+
// src/job.broker.ts
|
|
5
|
+
import { Injectable } from "injectkit";
|
|
6
|
+
function _ts_decorate(decorators, target, key, desc) {
|
|
7
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
8
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
9
|
+
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;
|
|
10
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
11
|
+
}
|
|
12
|
+
__name(_ts_decorate, "_ts_decorate");
|
|
13
|
+
var JobBroker = class {
|
|
14
|
+
static {
|
|
15
|
+
__name(this, "JobBroker");
|
|
16
|
+
}
|
|
17
|
+
};
|
|
18
|
+
JobBroker = _ts_decorate([
|
|
19
|
+
Injectable()
|
|
20
|
+
], JobBroker);
|
|
21
|
+
|
|
22
|
+
// src/job.runner.ts
|
|
23
|
+
import { Injectable as Injectable2 } from "injectkit";
|
|
24
|
+
function _ts_decorate2(decorators, target, key, desc) {
|
|
25
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
26
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
27
|
+
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;
|
|
28
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
29
|
+
}
|
|
30
|
+
__name(_ts_decorate2, "_ts_decorate");
|
|
31
|
+
var JobRunner = class {
|
|
32
|
+
static {
|
|
33
|
+
__name(this, "JobRunner");
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
JobRunner = _ts_decorate2([
|
|
37
|
+
Injectable2()
|
|
38
|
+
], JobRunner);
|
|
39
|
+
|
|
40
|
+
export {
|
|
41
|
+
__name,
|
|
42
|
+
JobBroker,
|
|
43
|
+
JobRunner
|
|
44
|
+
};
|
|
45
|
+
//# sourceMappingURL=chunk-VPYK6KC5.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/job.broker.ts","../src/job.runner.ts"],"sourcesContent":["import { Injectable } from 'injectkit';\nimport { JobInfo } from './job.info.js';\n\n/**\n * Abstract base class for job broker implementations.\n *\n * A job broker is responsible for sending jobs to a queue, cancelling and\n * inspecting jobs, and managing scheduled jobs. It provides the producer-side\n * interface for the job processing system.\n *\n * Backends differ in what they can do. Operations a backend cannot honor throw\n * a `NotSupportedError` rather than silently doing nothing. The bundled pg-boss\n * backend supports every operation.\n *\n * @example\n * ```typescript\n * // Sending a job immediately (returns the job id)\n * const id = await jobBroker.send('send-email', {\n * to: 'user@example.com',\n * subject: 'Welcome!',\n * body: 'Thanks for signing up.'\n * });\n *\n * // Cancelling it later, whether it is still queued or already running\n * await jobBroker.cancel('send-email', id);\n *\n * // Scheduling a recurring job with cron\n * await jobBroker.schedule('daily-report', '0 9 * * *', {\n * reportType: 'sales'\n * });\n *\n * // Removing a scheduled job\n * await jobBroker.unschedule('daily-report');\n * ```\n */\n@Injectable()\nexport abstract class JobBroker {\n /**\n * Sends a job to the queue for immediate processing.\n *\n * The job will be picked up by a worker as soon as one is available.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param payload - The data to pass to the job handler.\n * @returns A promise that resolves with the id of the queued job. The id can\n * be passed to {@link cancel}, {@link resume}, {@link deleteJob}, or\n * {@link getJob}.\n * @throws If the job name is not registered.\n */\n abstract send<Payload extends object>(name: string, payload: Payload): Promise<string>;\n\n /**\n * Schedules a recurring job using a cron expression.\n *\n * The job will be automatically enqueued according to the cron schedule.\n * If a schedule already exists for this job name, it will be updated.\n *\n * @typeParam Payload - The type of the job payload. Must be an object.\n * @param name - The unique name identifying the job type.\n * Must match a registered job handler.\n * @param cron - A cron expression defining the schedule (e.g., '0 9 * * *' for daily at 9am).\n * @param payload - Optional data to pass to the job handler on each execution.\n * @returns A promise that resolves when the schedule has been created.\n * @throws If the job name is not registered.\n */\n abstract schedule<Payload extends object>(name: string, cron: string, payload?: Payload): Promise<void>;\n\n /**\n * Removes a scheduled job.\n *\n * Stops the recurring execution of the specified job.\n * Does not affect jobs that are already queued.\n *\n * @param name - The unique name of the scheduled job to remove.\n * @returns A promise that resolves when the schedule has been removed.\n * @throws If the job name is not registered.\n */\n abstract unschedule(name: string): Promise<void>;\n\n /**\n * Requests cancellation of one or more jobs.\n *\n * Cancellation is best-effort and applies regardless of the job's state: a\n * job that is still queued is prevented from running, and a job that is\n * already running is asked to stop. For a running job, cancellation is\n * cooperative — the job's handler receives an aborted `AbortSignal` (see\n * {@link Job.run}) and must honor it. A handler that ignores the signal runs\n * to completion. Some backends may forcefully terminate the running compute\n * instead; this contract only guarantees the request is delivered.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to cancel.\n * @returns A promise that resolves once the cancellation has been requested.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot cancel jobs.\n */\n abstract cancel(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Resumes one or more previously cancelled jobs, re-queuing them for processing.\n *\n * Only jobs in the `cancelled` state can be resumed; other states are\n * unaffected.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to resume.\n * @returns A promise that resolves once the jobs have been re-queued.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot resume jobs.\n */\n abstract resume(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Permanently deletes one or more jobs.\n *\n * Removes the job records entirely. Unlike {@link cancel}, a deleted job\n * leaves no `cancelled` record behind and cannot be resumed.\n *\n * @param name - The name of the registered job type.\n * @param id - A single job id, or an array of ids, to delete.\n * @returns A promise that resolves once the jobs have been deleted.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot delete jobs.\n */\n abstract deleteJob(name: string, id: string | string[]): Promise<void>;\n\n /**\n * Looks up the current state of a single job.\n *\n * @typeParam Payload - The type of the job payload.\n * @param name - The name of the registered job type.\n * @param id - The id of the job to look up.\n * @returns A promise that resolves with the {@link JobInfo} for the job, or\n * `null` if no job with that id exists.\n * @throws If the job name is not registered.\n * @throws `NotSupportedError` if the backend cannot report per-job state.\n */\n abstract getJob<Payload extends object>(name: string, id: string): Promise<JobInfo<Payload> | null>;\n}\n","import { Injectable } from 'injectkit';\n\n/**\n * Abstract base class for job runner implementations.\n *\n * A job runner is responsible for consuming jobs from the queue and\n * executing the appropriate job handlers. It manages the worker lifecycle\n * and provides the consumer-side interface for the job processing system.\n *\n * @example\n * ```typescript\n * // Start processing jobs\n * await jobRunner.start();\n *\n * // Gracefully stop processing (e.g., on shutdown)\n * process.on('SIGTERM', async () => {\n * await jobRunner.stop();\n * process.exit(0);\n * });\n * ```\n */\n@Injectable()\nexport abstract class JobRunner {\n /**\n * Starts the job runner and begins processing jobs.\n *\n * This method initializes all registered job handlers and starts\n * listening for jobs on their respective queues. It should be called\n * during application startup.\n *\n * @returns A promise that resolves when the runner has started successfully.\n */\n abstract start(): Promise<void>;\n\n /**\n * Stops the job runner gracefully.\n *\n * This method stops accepting new jobs and waits for currently\n * executing jobs to complete. It should be called during application\n * shutdown to ensure clean termination.\n *\n * @returns A promise that resolves when the runner has stopped completely.\n */\n abstract stop(): Promise<void>;\n}\n"],"mappings":";;;;AAAA,SAASA,kBAAkB;;;;;;;;AAoCpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAwGtB;;;;;;AC5IA,SAASC,cAAAA,mBAAkB;;;;;;;;AAsBpB,IAAeC,YAAf,MAAeA;SAAAA;;;AAsBtB;;;;","names":["Injectable","JobBroker","Injectable","JobRunner"]}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
export * from './job.broker.js';
|
|
2
2
|
export * from './job.js';
|
|
3
|
+
export * from './job.info.js';
|
|
3
4
|
export * from './job.runner.js';
|
|
4
|
-
export * from './
|
|
5
|
-
export * from './pgboss/pgboss.job.runner.js';
|
|
6
|
-
export * from './pgboss/pgboss.job.registration.js';
|
|
7
|
-
export * from './pgboss/pgboss.connection.provider.js';
|
|
5
|
+
export * from './not.supported.error.js';
|
|
8
6
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
import {
|
|
2
|
+
JobBroker,
|
|
3
|
+
JobRunner,
|
|
4
|
+
__name
|
|
5
|
+
} from "./chunk-VPYK6KC5.js";
|
|
3
6
|
|
|
4
|
-
// src/job.
|
|
7
|
+
// src/job.ts
|
|
5
8
|
import { Injectable } from "injectkit";
|
|
6
9
|
function _ts_decorate(decorators, target, key, desc) {
|
|
7
10
|
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
@@ -10,315 +13,42 @@ function _ts_decorate(decorators, target, key, desc) {
|
|
|
10
13
|
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
11
14
|
}
|
|
12
15
|
__name(_ts_decorate, "_ts_decorate");
|
|
13
|
-
var JobBroker = class {
|
|
14
|
-
static {
|
|
15
|
-
__name(this, "JobBroker");
|
|
16
|
-
}
|
|
17
|
-
};
|
|
18
|
-
JobBroker = _ts_decorate([
|
|
19
|
-
Injectable()
|
|
20
|
-
], JobBroker);
|
|
21
|
-
|
|
22
|
-
// src/job.ts
|
|
23
|
-
import { Injectable as Injectable2 } from "injectkit";
|
|
24
|
-
function _ts_decorate2(decorators, target, key, desc) {
|
|
25
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
26
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
27
|
-
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;
|
|
28
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
29
|
-
}
|
|
30
|
-
__name(_ts_decorate2, "_ts_decorate");
|
|
31
16
|
var Job = class {
|
|
32
17
|
static {
|
|
33
18
|
__name(this, "Job");
|
|
34
19
|
}
|
|
35
20
|
};
|
|
36
|
-
Job =
|
|
37
|
-
|
|
21
|
+
Job = _ts_decorate([
|
|
22
|
+
Injectable()
|
|
38
23
|
], Job);
|
|
39
24
|
|
|
40
|
-
// src/
|
|
41
|
-
import {
|
|
42
|
-
|
|
43
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
44
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
45
|
-
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
46
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
47
|
-
}
|
|
48
|
-
__name(_ts_decorate3, "_ts_decorate");
|
|
49
|
-
var JobRunner = class {
|
|
50
|
-
static {
|
|
51
|
-
__name(this, "JobRunner");
|
|
52
|
-
}
|
|
53
|
-
};
|
|
54
|
-
JobRunner = _ts_decorate3([
|
|
55
|
-
Injectable3()
|
|
56
|
-
], JobRunner);
|
|
57
|
-
|
|
58
|
-
// src/pgboss/pgboss.job.broker.ts
|
|
59
|
-
import { PgBoss } from "pg-boss";
|
|
60
|
-
import { Injectable as Injectable6 } from "injectkit";
|
|
61
|
-
|
|
62
|
-
// src/pgboss/pgboss.job.registration.ts
|
|
63
|
-
import { Injectable as Injectable4 } from "injectkit";
|
|
64
|
-
function _ts_decorate4(decorators, target, key, desc) {
|
|
65
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
66
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
67
|
-
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;
|
|
68
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
69
|
-
}
|
|
70
|
-
__name(_ts_decorate4, "_ts_decorate");
|
|
71
|
-
var PgBossJobRegistryMap = class extends Map {
|
|
72
|
-
static {
|
|
73
|
-
__name(this, "PgBossJobRegistryMap");
|
|
74
|
-
}
|
|
75
|
-
};
|
|
76
|
-
PgBossJobRegistryMap = _ts_decorate4([
|
|
77
|
-
Injectable4()
|
|
78
|
-
], PgBossJobRegistryMap);
|
|
79
|
-
|
|
80
|
-
// src/pgboss/pgboss.connection.provider.ts
|
|
81
|
-
import { Injectable as Injectable5 } from "injectkit";
|
|
82
|
-
function _ts_decorate5(decorators, target, key, desc) {
|
|
83
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
84
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
85
|
-
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;
|
|
86
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
87
|
-
}
|
|
88
|
-
__name(_ts_decorate5, "_ts_decorate");
|
|
89
|
-
var PgBossConnectionProvider = class {
|
|
90
|
-
static {
|
|
91
|
-
__name(this, "PgBossConnectionProvider");
|
|
92
|
-
}
|
|
93
|
-
/**
|
|
94
|
-
* Returns the pg-boss executor to run job-insert SQL against, or `undefined`
|
|
95
|
-
* to use pg-boss's internal connection pool.
|
|
96
|
-
*
|
|
97
|
-
* @returns A transaction-bound {@link Db} executor, or `undefined` for the
|
|
98
|
-
* default pooled (non-transactional) behavior.
|
|
99
|
-
*/
|
|
100
|
-
executor() {
|
|
101
|
-
return void 0;
|
|
102
|
-
}
|
|
103
|
-
};
|
|
104
|
-
PgBossConnectionProvider = _ts_decorate5([
|
|
105
|
-
Injectable5()
|
|
106
|
-
], PgBossConnectionProvider);
|
|
107
|
-
|
|
108
|
-
// src/pgboss/pgboss.job.broker.ts
|
|
109
|
-
function _ts_decorate6(decorators, target, key, desc) {
|
|
110
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
111
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
112
|
-
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;
|
|
113
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
114
|
-
}
|
|
115
|
-
__name(_ts_decorate6, "_ts_decorate");
|
|
116
|
-
function _ts_metadata(k, v) {
|
|
117
|
-
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
118
|
-
}
|
|
119
|
-
__name(_ts_metadata, "_ts_metadata");
|
|
120
|
-
var PgBossJobBroker = class extends JobBroker {
|
|
25
|
+
// src/not.supported.error.ts
|
|
26
|
+
import { ServerkitError } from "@maroonedsoftware/errors";
|
|
27
|
+
var NotSupportedError = class extends ServerkitError {
|
|
121
28
|
static {
|
|
122
|
-
__name(this, "
|
|
123
|
-
}
|
|
124
|
-
registrations;
|
|
125
|
-
pgboss;
|
|
126
|
-
connectionProvider;
|
|
127
|
-
/**
|
|
128
|
-
* Creates a new PgBossJobBroker instance.
|
|
129
|
-
*
|
|
130
|
-
* @param registrations - The registry map containing all registered jobs.
|
|
131
|
-
* @param pgboss - The pg-boss instance to use for queue operations.
|
|
132
|
-
* @param connectionProvider - Supplies the pg-boss `db` executor for each
|
|
133
|
-
* enqueue/schedule; the default returns `undefined` (pg-boss's own
|
|
134
|
-
* pool), while a request-scoped override enables transactional enqueue.
|
|
135
|
-
*/
|
|
136
|
-
constructor(registrations, pgboss, connectionProvider) {
|
|
137
|
-
super(), this.registrations = registrations, this.pgboss = pgboss, this.connectionProvider = connectionProvider;
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* Sends a job to the PgBoss queue for immediate processing.
|
|
141
|
-
*
|
|
142
|
-
* The job-insert SQL runs against the executor returned by the injected
|
|
143
|
-
* {@link PgBossConnectionProvider}; when that executor is bound to an active
|
|
144
|
-
* transaction, the job is enqueued atomically with that transaction.
|
|
145
|
-
*
|
|
146
|
-
* @typeParam Payload - The type of the job payload.
|
|
147
|
-
* @param name - The name of the registered job to execute.
|
|
148
|
-
* @param payload - The data to pass to the job handler.
|
|
149
|
-
* @returns A promise that resolves when the job has been queued.
|
|
150
|
-
* @throws Error if the job name is not found in the registry.
|
|
151
|
-
*/
|
|
152
|
-
async send(name, payload) {
|
|
153
|
-
if (!this.registrations.has(name)) {
|
|
154
|
-
throw new Error(`Job ${name} is not registered`);
|
|
155
|
-
}
|
|
156
|
-
await this.pgboss.send(name, payload, {
|
|
157
|
-
db: this.connectionProvider.executor()
|
|
158
|
-
});
|
|
159
|
-
}
|
|
160
|
-
/**
|
|
161
|
-
* Schedules a recurring job using a cron expression.
|
|
162
|
-
*
|
|
163
|
-
* The job will be automatically enqueued by pg-boss according to the
|
|
164
|
-
* specified cron schedule. If a schedule already exists for this job,
|
|
165
|
-
* it will be updated with the new cron expression and payload.
|
|
166
|
-
*
|
|
167
|
-
* The schedule-insert SQL runs against the executor returned by the injected
|
|
168
|
-
* {@link PgBossConnectionProvider}; the default executor uses pg-boss's own
|
|
169
|
-
* pool, which is the expected behavior for bootstrap-time scheduling.
|
|
170
|
-
*
|
|
171
|
-
* @typeParam Payload - The type of the job payload.
|
|
172
|
-
* @param name - The name of the registered job to schedule.
|
|
173
|
-
* @param cron - A cron expression (e.g., '0 9 * * *' for daily at 9am).
|
|
174
|
-
* @param payload - Optional data to pass to the job on each execution.
|
|
175
|
-
* @returns A promise that resolves when the schedule has been created.
|
|
176
|
-
* @throws Error if the job name is not found in the registry.
|
|
177
|
-
*/
|
|
178
|
-
async schedule(name, cron, payload) {
|
|
179
|
-
if (!this.registrations.has(name)) {
|
|
180
|
-
throw new Error(`Job ${name} is not registered`);
|
|
181
|
-
}
|
|
182
|
-
await this.pgboss.schedule(name, cron, payload, {
|
|
183
|
-
db: this.connectionProvider.executor()
|
|
184
|
-
});
|
|
29
|
+
__name(this, "NotSupportedError");
|
|
185
30
|
}
|
|
31
|
+
/** The name of the operation that is not supported (e.g. `'cancel'`). */
|
|
32
|
+
operation;
|
|
33
|
+
/** The backend that does not support the operation, when known (e.g. `'sqs'`). */
|
|
34
|
+
backend;
|
|
186
35
|
/**
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
* This stops future executions of the scheduled job. Jobs that are
|
|
190
|
-
* already queued will still be processed.
|
|
191
|
-
*
|
|
192
|
-
* @param name - The name of the scheduled job to remove.
|
|
193
|
-
* @returns A promise that resolves when the schedule has been removed.
|
|
194
|
-
* @throws Error if the job name is not found in the registry.
|
|
195
|
-
*/
|
|
196
|
-
async unschedule(name) {
|
|
197
|
-
if (!this.registrations.has(name)) {
|
|
198
|
-
throw new Error(`Job ${name} is not registered`);
|
|
199
|
-
}
|
|
200
|
-
await this.pgboss.unschedule(name);
|
|
201
|
-
}
|
|
202
|
-
};
|
|
203
|
-
PgBossJobBroker = _ts_decorate6([
|
|
204
|
-
Injectable6(),
|
|
205
|
-
_ts_metadata("design:type", Function),
|
|
206
|
-
_ts_metadata("design:paramtypes", [
|
|
207
|
-
typeof PgBossJobRegistryMap === "undefined" ? Object : PgBossJobRegistryMap,
|
|
208
|
-
typeof PgBoss === "undefined" ? Object : PgBoss,
|
|
209
|
-
typeof PgBossConnectionProvider === "undefined" ? Object : PgBossConnectionProvider
|
|
210
|
-
])
|
|
211
|
-
], PgBossJobBroker);
|
|
212
|
-
|
|
213
|
-
// src/pgboss/pgboss.job.runner.ts
|
|
214
|
-
import { PgBoss as PgBoss2 } from "pg-boss";
|
|
215
|
-
import { Container, Injectable as Injectable7 } from "injectkit";
|
|
216
|
-
import { Logger } from "@maroonedsoftware/logger";
|
|
217
|
-
function _ts_decorate7(decorators, target, key, desc) {
|
|
218
|
-
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
219
|
-
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
220
|
-
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;
|
|
221
|
-
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
222
|
-
}
|
|
223
|
-
__name(_ts_decorate7, "_ts_decorate");
|
|
224
|
-
function _ts_metadata2(k, v) {
|
|
225
|
-
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
226
|
-
}
|
|
227
|
-
__name(_ts_metadata2, "_ts_metadata");
|
|
228
|
-
var isPgBossJobRegistration = /* @__PURE__ */ __name((registration) => {
|
|
229
|
-
return registration && "job" in registration && "cron" in registration;
|
|
230
|
-
}, "isPgBossJobRegistration");
|
|
231
|
-
var PgBossJobRunner = class extends JobRunner {
|
|
232
|
-
static {
|
|
233
|
-
__name(this, "PgBossJobRunner");
|
|
234
|
-
}
|
|
235
|
-
container;
|
|
236
|
-
registrations;
|
|
237
|
-
pgboss;
|
|
238
|
-
logger;
|
|
239
|
-
/**
|
|
240
|
-
* Creates a new PgBossJobRunner instance.
|
|
241
|
-
*
|
|
242
|
-
* @param container - The DI container for resolving job instances.
|
|
243
|
-
* @param registrations - The registry map containing all registered jobs.
|
|
244
|
-
* @param pgboss - The pg-boss instance to use for queue operations.
|
|
245
|
-
* @param logger - The logger for recording job execution errors.
|
|
246
|
-
*/
|
|
247
|
-
constructor(container, registrations, pgboss, logger) {
|
|
248
|
-
super(), this.container = container, this.registrations = registrations, this.pgboss = pgboss, this.logger = logger;
|
|
249
|
-
}
|
|
250
|
-
/**
|
|
251
|
-
* Starts the job runner and begins processing registered jobs.
|
|
252
|
-
*
|
|
253
|
-
* For each registered job, this method:
|
|
254
|
-
* 1. Creates the queue if it doesn't exist
|
|
255
|
-
* 2. Sets up the cron schedule (for scheduled jobs)
|
|
256
|
-
* 3. Starts a worker to process jobs from the queue
|
|
257
|
-
*
|
|
258
|
-
* Each item in a batch resolves its `Job` instance from the DI container
|
|
259
|
-
* individually and execution is awaited via `Promise.allSettled`, so pg-boss
|
|
260
|
-
* does not acknowledge a batch until every job has actually finished and
|
|
261
|
-
* one job's failure cannot suppress its sibling's logs.
|
|
262
|
-
*
|
|
263
|
-
* @returns A promise that resolves when all workers are registered with pg-boss.
|
|
264
|
-
*/
|
|
265
|
-
async start() {
|
|
266
|
-
await this.pgboss.start();
|
|
267
|
-
for (const [name, registration] of this.registrations.entries()) {
|
|
268
|
-
const queue = await this.pgboss.getQueue(name);
|
|
269
|
-
if (!queue) {
|
|
270
|
-
await this.pgboss.createQueue(name);
|
|
271
|
-
}
|
|
272
|
-
let identifier;
|
|
273
|
-
if (isPgBossJobRegistration(registration)) {
|
|
274
|
-
identifier = registration.job;
|
|
275
|
-
await this.pgboss.schedule(name, registration.cron);
|
|
276
|
-
} else {
|
|
277
|
-
identifier = registration;
|
|
278
|
-
}
|
|
279
|
-
await this.pgboss.work(name, async (jobs) => {
|
|
280
|
-
await Promise.allSettled(jobs.map(async (job) => {
|
|
281
|
-
const jobRunner = this.container.get(identifier);
|
|
282
|
-
try {
|
|
283
|
-
await jobRunner.run(job.data);
|
|
284
|
-
} catch (error) {
|
|
285
|
-
this.logger.error(error);
|
|
286
|
-
}
|
|
287
|
-
}));
|
|
288
|
-
});
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
/**
|
|
292
|
-
* Stops the job runner gracefully.
|
|
293
|
-
*
|
|
294
|
-
* This method stops the pg-boss instance, which will:
|
|
295
|
-
* - Stop accepting new jobs
|
|
296
|
-
* - Wait for currently executing jobs to complete
|
|
297
|
-
* - Clean up database connections
|
|
36
|
+
* Creates a new NotSupportedError.
|
|
298
37
|
*
|
|
299
|
-
* @
|
|
38
|
+
* @param operation - The name of the unsupported operation.
|
|
39
|
+
* @param backend - The backend that does not support it, if known.
|
|
300
40
|
*/
|
|
301
|
-
|
|
302
|
-
|
|
41
|
+
constructor(operation, backend) {
|
|
42
|
+
super(backend ? `Operation "${operation}" is not supported by the ${backend} job broker` : `Operation "${operation}" is not supported by this job broker`);
|
|
43
|
+
this.name = "NotSupportedError";
|
|
44
|
+
this.operation = operation;
|
|
45
|
+
this.backend = backend;
|
|
303
46
|
}
|
|
304
47
|
};
|
|
305
|
-
PgBossJobRunner = _ts_decorate7([
|
|
306
|
-
Injectable7(),
|
|
307
|
-
_ts_metadata2("design:type", Function),
|
|
308
|
-
_ts_metadata2("design:paramtypes", [
|
|
309
|
-
typeof Container === "undefined" ? Object : Container,
|
|
310
|
-
typeof PgBossJobRegistryMap === "undefined" ? Object : PgBossJobRegistryMap,
|
|
311
|
-
typeof PgBoss2 === "undefined" ? Object : PgBoss2,
|
|
312
|
-
typeof Logger === "undefined" ? Object : Logger
|
|
313
|
-
])
|
|
314
|
-
], PgBossJobRunner);
|
|
315
48
|
export {
|
|
316
49
|
Job,
|
|
317
50
|
JobBroker,
|
|
318
51
|
JobRunner,
|
|
319
|
-
|
|
320
|
-
PgBossJobBroker,
|
|
321
|
-
PgBossJobRegistryMap,
|
|
322
|
-
PgBossJobRunner
|
|
52
|
+
NotSupportedError
|
|
323
53
|
};
|
|
324
54
|
//# sourceMappingURL=index.js.map
|