@marianmeres/workflow 2.2.0 → 3.0.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/dist/scheduler.js CHANGED
@@ -81,7 +81,7 @@ export class WorkflowScheduler {
81
81
  return { woken: due.length, repoked: stale.length };
82
82
  }
83
83
  #poke(row, what) {
84
- return this.#workflow.enqueueAdvance(this.#workflow.db, {
84
+ return this.#workflow.enqueueAdvance({
85
85
  tenant_id: this.tenantId,
86
86
  instance_id: row.id,
87
87
  expected_seq: row.seq,
@@ -1,12 +1,25 @@
1
+ import type { Driver } from "@marianmeres/sqlkit";
2
+ import { type PgDb } from "@marianmeres/sqlkit/pg";
1
3
  import { type Jobs } from "@marianmeres/steve";
2
- import type pg from "pg";
3
- import { type JobEnqueuer } from "./driver.js";
4
- import { WorkflowRegistry } from "./registry.js";
5
- import { type AdvanceJobPayload, type EffectJobPayload, type Handler, type InboxRow, type Matcher, type WorkflowContext, type WorkflowDefinition, type WorkflowInstanceRow } from "./types.js";
4
+ import { type JobEnqueuer } from "./driver.ts";
5
+ import { WorkflowRegistry } from "./registry.ts";
6
+ import { type AdvanceJobPayload, type EffectJobPayload, type Handler, type InboxRow, type Matcher, type WorkflowContext, type WorkflowDefinition, type WorkflowInstanceRow } from "./types.ts";
6
7
  /** Options accepted by {@link Workflow}. */
7
8
  export interface WorkflowOptions {
8
- /** PostgreSQL pool. Used for direct SQL (persistence helpers, transactions). */
9
- db: pg.Pool;
9
+ /**
10
+ * The database: a node-postgres `pg.Pool` (the recommendation), a connected
11
+ * `pg.Client`, or a `@marianmeres/sqlkit` `Driver` of the `pg` dialect. A
12
+ * pool or a client is turned into sqlkit's driver for it (`toPgDriver`), which
13
+ * sqlkit keeps one of per pool and per client. Never closed here: ending it
14
+ * stays the caller's.
15
+ *
16
+ * Give `jobs` the same one. A `Jobs` on the same pool, client or driver
17
+ * shares the workflow's transactions, so an instance and the job that moves
18
+ * it are written together or not at all. A `Jobs` with a database connection
19
+ * of its own still works: its inserts stand alone, and the `seq` fence covers
20
+ * what that leaves open.
21
+ */
22
+ db: PgDb;
10
23
  /**
11
24
  * Externally-owned `@marianmeres/steve` `Jobs` instance. The framework
12
25
  * registers its handlers (`workflow.advance` + `workflow.effect.<name>`) on
@@ -67,7 +80,8 @@ export interface WorkflowOptions {
67
80
  */
68
81
  export declare class Workflow implements JobEnqueuer {
69
82
  #private;
70
- readonly db: pg.Pool;
83
+ /** The sqlkit driver every statement runs on: `toPgDriver(options.db)`. */
84
+ readonly db: Driver;
71
85
  readonly jobs: Jobs;
72
86
  readonly tenantId: string;
73
87
  readonly registry: WorkflowRegistry;
@@ -86,10 +100,18 @@ export declare class Workflow implements JobEnqueuer {
86
100
  * superseded by a later `Workflow`).
87
101
  */
88
102
  detach(): void;
89
- /** Internal — used by the driver to enqueue an advance job. */
90
- enqueueAdvance(_client: pg.PoolClient | pg.Client | pg.Pool, payload: AdvanceJobPayload): Promise<void>;
91
- /** Internal — used by the driver to enqueue an effect job. */
92
- enqueueEffect(_client: pg.PoolClient | pg.Client | pg.Pool, handler: string, payload: EffectJobPayload): Promise<void>;
103
+ /**
104
+ * Internal — used by the driver to enqueue an advance job.
105
+ *
106
+ * Where the insert lands is decided by where this is called, not by a handle:
107
+ * inside a `db.transaction()` callback, with a `Jobs` that shares this
108
+ * workflow's driver, the job is part of that transaction. Otherwise it is a
109
+ * statement of its own — and the advance is fenced (`expected_seq`), so a job
110
+ * that outlives a rolled-back transaction, or runs twice, is a no-op.
111
+ */
112
+ enqueueAdvance(payload: AdvanceJobPayload): Promise<void>;
113
+ /** Internal — used by the driver to enqueue an effect job. See {@link enqueueAdvance}. */
114
+ enqueueEffect(handler: string, payload: EffectJobPayload): Promise<void>;
93
115
  /**
94
116
  * Creates a new workflow instance and enqueues its first advance.
95
117
  *
package/dist/workflow.js CHANGED
@@ -1,10 +1,10 @@
1
+ import { toPgDriver } from "@marianmeres/sqlkit/pg";
1
2
  import { JOB_STATUS } from "@marianmeres/steve";
2
3
  import { effectJobType, failAdvanceJob, failEffectJob, JOB_TYPE_ADVANCE, runAdvance, runEffect, } from "./driver.js";
3
4
  import { clog } from "./log.js";
4
5
  import { appendHistory } from "./persistence/history.js";
5
6
  import { appendInbox } from "./persistence/inbox.js";
6
7
  import { createInstance, findInstance, lockInstance, updateInstance, } from "./persistence/instances.js";
7
- import { withTransaction } from "./persistence/tx.js";
8
8
  import { WorkflowRegistry } from "./registry.js";
9
9
  import { DEFAULT_TENANT_ID, EXECUTION_STATE, HISTORY_EVENT, } from "./types.js";
10
10
  /**
@@ -28,6 +28,7 @@ const attachedWorkflows = new WeakMap();
28
28
  * accept an externally-owned `Cron` instance the same way.
29
29
  */
30
30
  export class Workflow {
31
+ /** The sqlkit driver every statement runs on: `toPgDriver(options.db)`. */
31
32
  db;
32
33
  jobs;
33
34
  tenantId;
@@ -43,7 +44,6 @@ export class Workflow {
43
44
  throw new Error("Workflow: a Workflow is already attached to this Jobs instance. " +
44
45
  "Call detach() on it first, or pass a separate Jobs instance.");
45
46
  }
46
- this.db = options.db;
47
47
  this.jobs = options.jobs;
48
48
  this.tenantId = options.tenantId ?? DEFAULT_TENANT_ID;
49
49
  this.registry = new WorkflowRegistry({
@@ -51,6 +51,10 @@ export class Workflow {
51
51
  handlers: options.handlers,
52
52
  matchers: options.matchers,
53
53
  });
54
+ // Throws a TypeError for anything that is not a pool, a client or a driver
55
+ // of the pg dialect: here, not at the first query. After the registry, so
56
+ // a definition that does not validate is still what gets reported first.
57
+ this.db = toPgDriver(options.db);
54
58
  this.#effectMaxAttempts = options.effectMaxAttempts ?? 3;
55
59
  this.#effectMaxAttemptDurationMs = options.effectMaxAttemptDurationMs ?? 0;
56
60
  this.#advanceMaxAttempts = options.advanceMaxAttempts ?? 10;
@@ -131,7 +135,7 @@ export class Workflow {
131
135
  return;
132
136
  }
133
137
  clog.debug?.(`effect ${payload.handler} expired; re-dispatch #${next} (job ${job.uid})`);
134
- await this.enqueueEffect(this.db, payload.handler, {
138
+ await this.enqueueEffect(payload.handler, {
135
139
  ...payload,
136
140
  redispatch: next,
137
141
  });
@@ -143,25 +147,29 @@ export class Workflow {
143
147
  return;
144
148
  }
145
149
  clog.debug?.(`advance expired; re-dispatch #${next} (job ${job.uid})`);
146
- await this.enqueueAdvance(this.db, { ...payload, redispatch: next });
150
+ await this.enqueueAdvance({ ...payload, redispatch: next });
147
151
  }
148
152
  async #failAdvance(job, payload) {
149
153
  const { attempts } = await this.jobs.find(job.uid, true);
150
154
  const last = attempts?.at(-1)?.error_message;
151
155
  await failAdvanceJob(this.db, payload, `advance job failed: ${last ?? `steve: ${job.status}`}`, job.uid);
152
156
  }
153
- /** Internal — used by the driver to enqueue an advance job. */
154
- async enqueueAdvance(_client, payload) {
155
- // Steve creates within its own connection/tx; passing the locked client
156
- // would not gain us atomicity vs steve's bookkeeping. The advance is
157
- // fenced (`expected_seq`), so an enqueue-but-no-commit race costs at most
158
- // a duplicate job that no-ops.
157
+ /**
158
+ * Internal — used by the driver to enqueue an advance job.
159
+ *
160
+ * Where the insert lands is decided by where this is called, not by a handle:
161
+ * inside a `db.transaction()` callback, with a `Jobs` that shares this
162
+ * workflow's driver, the job is part of that transaction. Otherwise it is a
163
+ * statement of its own — and the advance is fenced (`expected_seq`), so a job
164
+ * that outlives a rolled-back transaction, or runs twice, is a no-op.
165
+ */
166
+ async enqueueAdvance(payload) {
159
167
  await this.jobs.create(JOB_TYPE_ADVANCE, payload, {
160
168
  max_attempts: this.#advanceMaxAttempts,
161
169
  });
162
170
  }
163
- /** Internal — used by the driver to enqueue an effect job. */
164
- async enqueueEffect(_client, handler, payload) {
171
+ /** Internal — used by the driver to enqueue an effect job. See {@link enqueueAdvance}. */
172
+ async enqueueEffect(handler, payload) {
165
173
  await this.jobs.create(effectJobType(handler), payload, {
166
174
  max_attempts: this.#effectMaxAttempts,
167
175
  max_attempt_duration_ms: this.#effectMaxAttemptDurationMs,
@@ -185,11 +193,14 @@ export class Workflow {
185
193
  ? def.fsm.context()
186
194
  : structuredClone(def.fsm.context ?? {});
187
195
  // One transaction: a throwing enqueue rolls the instance back rather than
188
- // leaving a row nothing will ever advance. Steve inserts on its own
189
- // connection, so the job can be claimed before this commits — the advance
190
- // throws on the not-yet-visible row and steve retries it.
191
- return await withTransaction(this.db, async (client) => {
192
- const row = await createInstance(client, {
196
+ // leaving a row nothing will ever advance. With a `Jobs` on this driver the
197
+ // job is in the transaction too, so row, history and job commit together.
198
+ // A `Jobs` on a connection of its own inserts outside it: the job can then
199
+ // be claimed before this commits (the advance throws on the not-yet-visible
200
+ // row and steve retries it), and outlives a rollback (the orphan finds no
201
+ // row and steve gives up on it).
202
+ return await this.db.transaction(async (tx) => {
203
+ const row = await createInstance(tx, {
193
204
  tenant_id: this.tenantId,
194
205
  definition_id: input.definitionId,
195
206
  definition_version: input.definitionVersion,
@@ -197,7 +208,7 @@ export class Workflow {
197
208
  context: { ...defaults, ...input.context },
198
209
  correlation_token: input.correlationToken ?? null,
199
210
  });
200
- await appendHistory(client, {
211
+ await appendHistory(tx, {
201
212
  tenant_id: this.tenantId,
202
213
  instance_id: row.id,
203
214
  event_type: HISTORY_EVENT.CREATED,
@@ -229,8 +240,8 @@ export class Workflow {
229
240
  * @param reason - free-form, recorded on the `cancelled` history row.
230
241
  */
231
242
  async cancel(id, reason) {
232
- return await withTransaction(this.db, async (client) => {
233
- const row = await lockInstance(client, id);
243
+ return await this.db.transaction(async (tx) => {
244
+ const row = await lockInstance(tx, id);
234
245
  if (!row || row.tenant_id !== this.tenantId)
235
246
  return false;
236
247
  if (row.execution_state === EXECUTION_STATE.COMPLETED ||
@@ -238,12 +249,12 @@ export class Workflow {
238
249
  row.execution_state === EXECUTION_STATE.CANCELLED) {
239
250
  return false;
240
251
  }
241
- await updateInstance(client, row.id, {
252
+ await updateInstance(tx, row.id, {
242
253
  execution_state: EXECUTION_STATE.CANCELLED,
243
254
  wake_at: null,
244
255
  correlation_token: null,
245
256
  }, { bumpSeq: true });
246
- await appendHistory(client, {
257
+ await appendHistory(tx, {
247
258
  tenant_id: this.tenantId,
248
259
  instance_id: row.id,
249
260
  event_type: HISTORY_EVENT.CANCELLED,
@@ -272,20 +283,19 @@ export class Workflow {
272
283
  * stale, so a late completion is dropped.
273
284
  */
274
285
  async retry(id, opts = {}) {
275
- const settled = await withTransaction(this.db, async (client) => {
276
- const row = await lockInstance(client, id);
286
+ const settled = await this.db.transaction(async (tx) => {
287
+ const row = await lockInstance(tx, id);
277
288
  if (!row || row.tenant_id !== this.tenantId)
278
289
  return null;
279
290
  const allowed = row.execution_state === EXECUTION_STATE.FAILED ||
280
- (opts.force === true &&
281
- row.execution_state === EXECUTION_STATE.RUNNING);
291
+ (opts.force === true && row.execution_state === EXECUTION_STATE.RUNNING);
282
292
  if (!allowed)
283
293
  return null;
284
- const updated = await updateInstance(client, row.id, {
294
+ const updated = await updateInstance(tx, row.id, {
285
295
  execution_state: EXECUTION_STATE.PENDING,
286
296
  wake_at: null,
287
297
  }, { bumpSeq: true });
288
- await appendHistory(client, {
298
+ await appendHistory(tx, {
289
299
  tenant_id: this.tenantId,
290
300
  instance_id: row.id,
291
301
  event_type: HISTORY_EVENT.RETRIED,
@@ -296,11 +306,12 @@ export class Workflow {
296
306
  });
297
307
  if (!settled)
298
308
  return false;
299
- // After the commit, not inside it: an advance claimed before the commit
300
- // landed would see the row still `failed` at the old `seq` and drop itself
301
- // as stale. A crash in this gap leaves a `pending` row, which the
302
- // scheduler's stale-pending scan re-pokes.
303
- await this.enqueueAdvance(this.db, {
309
+ // After the commit, not inside it: with a `Jobs` on a connection of its
310
+ // own, an advance claimed before the commit landed would see the row still
311
+ // `failed` at the old `seq` and drop itself as stale. A crash in this gap
312
+ // leaves a `pending` row, which the scheduler's stale-pending scan re-pokes.
313
+ // (Called from inside a caller's transaction, this is still inside that one.)
314
+ await this.enqueueAdvance({
304
315
  tenant_id: this.tenantId,
305
316
  instance_id: settled.id,
306
317
  kind: "start",
package/package.json CHANGED
@@ -1,40 +1,90 @@
1
1
  {
2
- "name": "@marianmeres/workflow",
3
- "version": "2.2.0",
4
- "type": "module",
5
- "main": "dist/mod.js",
6
- "types": "dist/mod.d.ts",
7
- "exports": {
8
- ".": {
9
- "types": "./dist/mod.d.ts",
10
- "import": "./dist/mod.js"
11
- }
12
- },
13
- "files": [
14
- "dist",
15
- "LICENSE",
16
- "README.md",
17
- "API.md",
18
- "AGENTS.md",
19
- "CLAUDE.md",
20
- "docs"
21
- ],
22
- "author": "Marian Meres",
23
- "license": "MIT",
24
- "dependencies": {
25
- "@marianmeres/clog": "^3.23.0",
26
- "@marianmeres/cron": "^3.3.0",
27
- "@marianmeres/fsm": "^3.1.0",
28
- "@marianmeres/migrate": "^1.3.1",
29
- "@marianmeres/steve": "^3.1.0",
30
- "@types/pg": "^8.23.1",
31
- "pg": "^8.23.1"
32
- },
33
- "repository": {
34
- "type": "git",
35
- "url": "git+https://github.com/marianmeres/workflow.git"
36
- },
37
- "bugs": {
38
- "url": "https://github.com/marianmeres/workflow/issues"
39
- }
40
- }
2
+ "name": "@marianmeres/workflow",
3
+ "version": "3.0.0",
4
+ "description": "PostgreSQL-backed durable workflow / orchestration framework: long-lived persisted FSM instances with version-pinned definitions, durable timer wake-ups, external-signal correlation via an inbox and matchers, and effects run as transactional outbox jobs.",
5
+ "license": "MIT",
6
+ "author": "Marian Meres",
7
+ "type": "module",
8
+ "engines": {
9
+ "node": "^24.20.0 || >=26.6.0"
10
+ },
11
+ "publishConfig": {
12
+ "access": "public"
13
+ },
14
+ "main": "./dist/mod.js",
15
+ "types": "./dist/mod.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/mod.d.ts",
19
+ "import": "./dist/mod.js"
20
+ }
21
+ },
22
+ "files": [
23
+ "dist",
24
+ "LICENSE",
25
+ "README.md",
26
+ "API.md",
27
+ "AGENTS.md",
28
+ "CLAUDE.md",
29
+ "docs"
30
+ ],
31
+ "repository": {
32
+ "type": "git",
33
+ "url": "git+https://github.com/marianmeres/workflow.git"
34
+ },
35
+ "bugs": {
36
+ "url": "https://github.com/marianmeres/workflow/issues"
37
+ },
38
+ "homepage": "https://github.com/marianmeres/workflow#readme",
39
+ "keywords": [
40
+ "workflow",
41
+ "orchestration",
42
+ "durable",
43
+ "state-machine",
44
+ "fsm",
45
+ "postgres",
46
+ "postgresql",
47
+ "outbox",
48
+ "job-queue",
49
+ "scheduler",
50
+ "correlation",
51
+ "long-running"
52
+ ],
53
+ "dependencies": {
54
+ "@marianmeres/clog": "^3.23.1",
55
+ "@marianmeres/cron": "^4.0.1",
56
+ "@marianmeres/fsm": "^3.1.0",
57
+ "@marianmeres/migrate": "^2.0.0",
58
+ "@marianmeres/sqlkit": "^0.3.2",
59
+ "@marianmeres/steve": "^4.3.0"
60
+ },
61
+ "devDependencies": {
62
+ "@biomejs/biome": "^2.6.8",
63
+ "@marianmeres/bundle": "^1.0.0",
64
+ "@marianmeres/demino": "^2.1.1",
65
+ "@marianmeres/design-tokens": "^1.20.0",
66
+ "@marianmeres/vanilla": "^1.10.0",
67
+ "@types/node": "^26.6.6",
68
+ "@types/pg": "^8.23.1",
69
+ "pg": "^8.23.1",
70
+ "typescript": "^7.0.2"
71
+ },
72
+ "scripts": {
73
+ "build": "pnpm run clean && tsc -p tsconfig.build.json",
74
+ "clean": "rm -rf dist",
75
+ "typecheck": "tsc --noEmit",
76
+ "lint": "biome check .",
77
+ "format": "biome check --write .",
78
+ "test": "node --test --test-concurrency=1 --env-file-if-exists=.env \"tests/**/*.test.ts\"",
79
+ "test:watch": "node --test --test-concurrency=1 --watch --env-file-if-exists=.env \"tests/**/*.test.ts\"",
80
+ "ci": "pnpm run typecheck && pnpm run lint && pnpm test",
81
+ "example": "node --env-file-if-exists=.env example/server.ts",
82
+ "example:version": "node scripts/gen-example-version.ts",
83
+ "example:theme": "node scripts/gen-example-theme.ts",
84
+ "example:build": "pnpm run example:version && bundle --root example/src --entry main.ts --outdir example/dist --strict --minify",
85
+ "example:dev": "pnpm run example:version && bundle --root example/src --entry main.ts --outdir example/dist --watch --watch-dir example/src",
86
+ "release": "npx --yes @marianmeres/release@^2.3.0 --before-bump \"pnpm run ci\" --before-commit \"pnpm run example:build\"",
87
+ "rp": "npm whoami >/dev/null && pnpm run release -y --before-push \"pnpm publish\"",
88
+ "rpm": "npm whoami >/dev/null && pnpm run release minor -y --before-push \"pnpm publish\""
89
+ }
90
+ }
@@ -1,6 +0,0 @@
1
- import type pg from "pg";
2
- /**
3
- * Runs `fn` inside a single PG transaction on a checked-out client.
4
- * Commits on resolve, rolls back on throw. Always releases the client.
5
- */
6
- export declare function withTransaction<T>(pool: pg.Pool, fn: (client: pg.PoolClient) => Promise<T>): Promise<T>;
@@ -1,25 +0,0 @@
1
- /**
2
- * Runs `fn` inside a single PG transaction on a checked-out client.
3
- * Commits on resolve, rolls back on throw. Always releases the client.
4
- */
5
- export async function withTransaction(pool, fn) {
6
- const client = await pool.connect();
7
- try {
8
- await client.query("BEGIN");
9
- const result = await fn(client);
10
- await client.query("COMMIT");
11
- return result;
12
- }
13
- catch (err) {
14
- try {
15
- await client.query("ROLLBACK");
16
- }
17
- catch {
18
- // rollback best-effort; surface the original error
19
- }
20
- throw err;
21
- }
22
- finally {
23
- client.release();
24
- }
25
- }