@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/driver.js CHANGED
@@ -2,8 +2,7 @@ import { FSM } from "@marianmeres/fsm";
2
2
  import { clog } from "./log.js";
3
3
  import { appendHistory } from "./persistence/history.js";
4
4
  import { lockInboxRow, markProcessed } from "./persistence/inbox.js";
5
- import { lockInstance, updateInstance } from "./persistence/instances.js";
6
- import { withTransaction } from "./persistence/tx.js";
5
+ import { findInstance, lockInstance, updateInstance } from "./persistence/instances.js";
7
6
  import { EXECUTION_STATE, HISTORY_EVENT, JOB_TYPE_ADVANCE, JOB_TYPE_EFFECT_PREFIX, PURE_ENTER_EVENT, SIGNAL_MATCHED_EVENT, } from "./types.js";
8
7
  /**
9
8
  * Reads the tenant scope off a job payload, tolerating the legacy `project_id`
@@ -43,7 +42,8 @@ const MAX_PURE_HOPS = 64;
43
42
  /**
44
43
  * The `workflow.advance` job body.
45
44
  *
46
- * Wrapped in a single PG transaction:
45
+ * Wrapped in a single PG transaction (`db.transaction()`; a call made from
46
+ * inside a caller's own transaction on the same driver joins that one):
47
47
  * 1. Lock the instance row.
48
48
  * 2. If in a terminal execution_state, no-op.
49
49
  * 2b. If the payload's fence (`expected_seq`) does not match the locked row, or
@@ -59,17 +59,19 @@ const MAX_PURE_HOPS = 64;
59
59
  * - effectful → enqueue an effect job + mark running, return.
60
60
  * - suspending → mark waiting, set wake_at/correlation_token, return.
61
61
  */
62
- export async function runAdvance(pool, registry, enqueuer, payload) {
62
+ export async function runAdvance(db, registry, enqueuer, payload) {
63
63
  const { instance_id } = payload;
64
64
  const tenant_id = payloadTenantId(payload);
65
65
  const kind = advanceKind(payload);
66
- await withTransaction(pool, async (client) => {
67
- const row = await lockInstance(client, instance_id);
66
+ await db.transaction(async (tx) => {
67
+ const row = await lockInstance(tx, instance_id);
68
68
  if (!row) {
69
- // Also the window where the creating transaction has not committed yet
70
- // (steve's job insert is autocommit on its own connection, so the job
71
- // can be claimed first). Throw rather than drop the only job the
72
- // instance will ever get — steve retries.
69
+ // Also the window where the creating transaction has not committed yet:
70
+ // a queue on a database connection of its own inserts the job outside
71
+ // that transaction, so the job can be claimed first. (A queue that
72
+ // shares the workflow's driver inserts it inside, and never gets here.)
73
+ // Throw rather than drop the only job the instance will ever get —
74
+ // steve retries.
73
75
  throw new Error(`advance: instance ${instance_id} not found`);
74
76
  }
75
77
  if (row.execution_state === EXECUTION_STATE.COMPLETED ||
@@ -99,7 +101,8 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
99
101
  (payload.kind === "signal" &&
100
102
  row.execution_state !== EXECUTION_STATE.WAITING) ||
101
103
  (payload.kind === "timeout" &&
102
- (row.execution_state !== EXECUTION_STATE.WAITING || !row.wake_at ||
104
+ (row.execution_state !== EXECUTION_STATE.WAITING ||
105
+ !row.wake_at ||
103
106
  row.wake_at > new Date()))) {
104
107
  clog.debug?.(`advance: ${payload.kind} precondition not met (${row.execution_state}); no-op`);
105
108
  return;
@@ -111,7 +114,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
111
114
  let outcome_data = payload.outcome_data;
112
115
  let inbox = null;
113
116
  if (payload.kind === "signal" && payload.inbox_id) {
114
- inbox = await lockInboxRow(client, payload.inbox_id);
117
+ inbox = await lockInboxRow(tx, payload.inbox_id);
115
118
  if (!inbox || inbox.processed_at) {
116
119
  clog.debug?.(`advance: inbox row ${payload.inbox_id} already delivered; no-op`);
117
120
  return;
@@ -130,7 +133,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
130
133
  def = registry.requireDefinition(row.definition_id, row.definition_version);
131
134
  }
132
135
  catch (e) {
133
- await failInstance(client, row, `Unknown definition ${row.definition_id}@${row.definition_version}: ${String(e)}`);
136
+ await failInstance(tx, row, `Unknown definition ${row.definition_id}@${row.definition_version}: ${String(e)}`);
134
137
  return;
135
138
  }
136
139
  // Construct the FSM at the saved cursor. fromSnapshot skips onEnter
@@ -150,14 +153,14 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
150
153
  const before = positioned.state;
151
154
  const result = positioned.transition(outcome, outcome_data ?? undefined, false);
152
155
  if (result === null) {
153
- await appendHistory(client, {
156
+ await appendHistory(tx, {
154
157
  tenant_id,
155
158
  instance_id,
156
159
  event_type: HISTORY_EVENT.TRANSITION_REJECTED,
157
160
  from_node: before,
158
161
  data: { outcome, outcome_data, reason: "fsm rejected transition" },
159
162
  });
160
- await failInstance(client, row, `fsm rejected outcome "${outcome}" at state "${before}"`);
163
+ await failInstance(tx, row, `fsm rejected outcome "${outcome}" at state "${before}"`);
161
164
  return;
162
165
  }
163
166
  // `outcome_data` stays the fsm payload and is never auto-merged: what
@@ -165,7 +168,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
165
168
  // what the handler explicitly returned in `HandlerResult.context`
166
169
  // (merged above).
167
170
  if (kind === "effect" && payload.handler) {
168
- await appendHistory(client, {
171
+ await appendHistory(tx, {
169
172
  tenant_id,
170
173
  instance_id,
171
174
  event_type: HISTORY_EVENT.EFFECT_COMPLETED,
@@ -174,21 +177,19 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
174
177
  });
175
178
  }
176
179
  if (inbox) {
177
- await appendHistory(client, {
180
+ await appendHistory(tx, {
178
181
  tenant_id,
179
182
  instance_id,
180
183
  event_type: HISTORY_EVENT.SIGNAL_RECEIVED,
181
184
  from_node: before,
182
185
  data: { inbox_id: inbox.id, source: inbox.source },
183
186
  });
184
- await markProcessed(client, inbox.id);
187
+ await markProcessed(tx, inbox.id);
185
188
  }
186
- await appendHistory(client, {
189
+ await appendHistory(tx, {
187
190
  tenant_id,
188
191
  instance_id,
189
- event_type: kind === "timeout"
190
- ? HISTORY_EVENT.TIMEOUT
191
- : HISTORY_EVENT.TRANSITION,
192
+ event_type: kind === "timeout" ? HISTORY_EVENT.TIMEOUT : HISTORY_EVENT.TRANSITION,
192
193
  from_node: before,
193
194
  to_node: positioned.state,
194
195
  data: { outcome, outcome_data, ...tokenPatch },
@@ -198,12 +199,12 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
198
199
  for (let hop = 0; hop < MAX_PURE_HOPS; hop++) {
199
200
  const meta = positioned.getCurrentMeta();
200
201
  if (!meta) {
201
- await failInstance(client, row, `state "${positioned.state}" has no meta`);
202
+ await failInstance(tx, row, `state "${positioned.state}" has no meta`);
202
203
  return;
203
204
  }
204
205
  switch (meta.kind) {
205
206
  case "terminal": {
206
- await updateInstance(client, instance_id, {
207
+ await updateInstance(tx, instance_id, {
207
208
  cursor: positioned.state,
208
209
  previous_cursor: positioned.previous,
209
210
  context: positioned.context,
@@ -211,7 +212,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
211
212
  wake_at: null,
212
213
  correlation_token: null,
213
214
  }, { bumpSeq: true });
214
- await appendHistory(client, {
215
+ await appendHistory(tx, {
215
216
  tenant_id,
216
217
  instance_id,
217
218
  event_type: HISTORY_EVENT.COMPLETED,
@@ -221,7 +222,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
221
222
  }
222
223
  case "effectful": {
223
224
  // Persist context (any guards/actions may have updated it) + flip to running.
224
- const settled = await updateInstance(client, instance_id, {
225
+ const settled = await updateInstance(tx, instance_id, {
225
226
  cursor: positioned.state,
226
227
  previous_cursor: positioned.previous,
227
228
  context: positioned.context,
@@ -229,14 +230,19 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
229
230
  wake_at: null,
230
231
  ...tokenPatch,
231
232
  }, { bumpSeq: true });
232
- await enqueuer.enqueueEffect(client, meta.handler, {
233
+ // Issued inside this transaction's callback: on a queue that
234
+ // shares the workflow's driver the effect job commits with the
235
+ // row it was dispatched from, or not at all (a transactional
236
+ // outbox). On a queue with a connection of its own the insert
237
+ // stands alone, and `runEffect`'s fence covers the gap.
238
+ await enqueuer.enqueueEffect(meta.handler, {
233
239
  tenant_id,
234
240
  instance_id,
235
241
  handler: meta.handler,
236
242
  seq: settled.seq,
237
243
  cursor: settled.cursor,
238
244
  });
239
- await appendHistory(client, {
245
+ await appendHistory(tx, {
240
246
  tenant_id,
241
247
  instance_id,
242
248
  event_type: HISTORY_EVENT.EFFECT_DISPATCHED,
@@ -251,7 +257,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
251
257
  : null;
252
258
  // The token is whatever create() set or the handler returned — the
253
259
  // driver never generates one.
254
- const settled = await updateInstance(client, instance_id, {
260
+ const settled = await updateInstance(tx, instance_id, {
255
261
  cursor: positioned.state,
256
262
  previous_cursor: positioned.previous,
257
263
  context: positioned.context,
@@ -267,7 +273,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
267
273
  clog.warn?.(`advance: instance ${instance_id} waits at "${positioned.state}" ` +
268
274
  `with no correlation_token — no signal can reach it`);
269
275
  }
270
- await appendHistory(client, {
276
+ await appendHistory(tx, {
271
277
  tenant_id,
272
278
  instance_id,
273
279
  event_type: HISTORY_EVENT.TRANSITION,
@@ -280,7 +286,7 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
280
286
  const before = positioned.state;
281
287
  const result = positioned.transition(PURE_ENTER_EVENT, undefined, false);
282
288
  if (result === null) {
283
- await appendHistory(client, {
289
+ await appendHistory(tx, {
284
290
  tenant_id,
285
291
  instance_id,
286
292
  event_type: HISTORY_EVENT.TRANSITION_REJECTED,
@@ -290,10 +296,10 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
290
296
  reason: "no guarded transition matched",
291
297
  },
292
298
  });
293
- await failInstance(client, row, `pure state "${before}" did not route on ENTER`);
299
+ await failInstance(tx, row, `pure state "${before}" did not route on ENTER`);
294
300
  return;
295
301
  }
296
- await appendHistory(client, {
302
+ await appendHistory(tx, {
297
303
  tenant_id,
298
304
  instance_id,
299
305
  event_type: HISTORY_EVENT.TRANSITION,
@@ -305,20 +311,20 @@ export async function runAdvance(pool, registry, enqueuer, payload) {
305
311
  break;
306
312
  }
307
313
  default: {
308
- await failInstance(client, row, `unknown meta.kind "${String(meta.kind)}" at state "${positioned.state}"`);
314
+ await failInstance(tx, row, `unknown meta.kind "${String(meta.kind)}" at state "${positioned.state}"`);
309
315
  return;
310
316
  }
311
317
  }
312
318
  }
313
- await failInstance(client, row, `exceeded ${MAX_PURE_HOPS} pure-state hops (likely cycle)`);
319
+ await failInstance(tx, row, `exceeded ${MAX_PURE_HOPS} pure-state hops (likely cycle)`);
314
320
  });
315
321
  }
316
- async function failInstance(client, row, reason, extra = {}) {
322
+ async function failInstance(db, row, reason, extra = {}) {
317
323
  clog.error?.(`workflow instance ${row.id} failed: ${reason}`);
318
- await updateInstance(client, row.id, {
324
+ await updateInstance(db, row.id, {
319
325
  execution_state: EXECUTION_STATE.FAILED,
320
326
  }, { bumpSeq: true });
321
- await appendHistory(client, {
327
+ await appendHistory(db, {
322
328
  tenant_id: row.tenant_id,
323
329
  instance_id: row.id,
324
330
  event_type: HISTORY_EVENT.FAILED,
@@ -335,9 +341,9 @@ async function failInstance(client, row, reason, extra = {}) {
335
341
  * Fenced like every other write: an advance that lost the race to a later one
336
342
  * must not fail the instance that later one moved on.
337
343
  */
338
- export async function failAdvanceJob(pool, payload, reason, jobUid) {
339
- await withTransaction(pool, async (client) => {
340
- const row = await lockInstance(client, payload.instance_id);
344
+ export async function failAdvanceJob(db, payload, reason, jobUid) {
345
+ await db.transaction(async (tx) => {
346
+ const row = await lockInstance(tx, payload.instance_id);
341
347
  if (!row)
342
348
  return;
343
349
  if (payload.expected_seq !== undefined && row.seq !== payload.expected_seq) {
@@ -349,7 +355,7 @@ export async function failAdvanceJob(pool, payload, reason, jobUid) {
349
355
  row.execution_state === EXECUTION_STATE.CANCELLED) {
350
356
  return;
351
357
  }
352
- await failInstance(client, row, reason, { job_uid: jobUid ?? null });
358
+ await failInstance(tx, row, reason, { job_uid: jobUid ?? null });
353
359
  });
354
360
  }
355
361
  /**
@@ -371,30 +377,20 @@ export async function failAdvanceJob(pool, payload, reason, jobUid) {
371
377
  * mid-execution, and even successful handlers can run twice if completion-write
372
378
  * fails after the advance has been enqueued.
373
379
  */
374
- export async function runEffect(pool, registry, enqueuer, payload, signal) {
380
+ export async function runEffect(db, registry, enqueuer, payload, signal) {
375
381
  const { instance_id, handler: handlerName } = payload;
376
382
  const tenant_id = payloadTenantId(payload);
377
383
  const handler = registry.requireHandler(handlerName);
378
- const client = await pool.connect();
379
- let row;
380
- try {
381
- const r = await client.query(`SELECT id, tenant_id, definition_id, definition_version, cursor,
382
- previous_cursor, context, execution_state, wake_at,
383
- correlation_token, seq, created_at, updated_at
384
- FROM __workflow_instances WHERE id = $1`, [instance_id]);
385
- row = r.rows[0] ?? null;
386
- }
387
- finally {
388
- client.release();
389
- }
384
+ const row = await findInstance(db, instance_id);
390
385
  if (!row) {
391
386
  throw new Error(`effect: instance ${instance_id} not found`);
392
387
  }
393
388
  if (payload.seq !== undefined && row.seq !== payload.seq) {
394
389
  if (row.seq < payload.seq) {
395
- // The dispatching advance has not committed yet — steve's job insert
396
- // is autocommit on its own connection, so the job can be claimed
397
- // before the transaction that enqueued it lands. Throw to retry.
390
+ // The dispatching advance has not committed yet: a queue on a database
391
+ // connection of its own inserts the job outside that transaction, so
392
+ // the job can be claimed before it lands. Throw to retry. (A queue
393
+ // that shares the workflow's driver inserts it inside: no such window.)
398
394
  throw new Error(`effect: instance ${instance_id} not yet at seq ${payload.seq} (row.seq=${row.seq})`);
399
395
  }
400
396
  clog.debug?.(`effect: stale ${handlerName} (row.seq=${row.seq}, job seq=${payload.seq}); skipped`);
@@ -410,7 +406,7 @@ export async function runEffect(pool, registry, enqueuer, payload, signal) {
410
406
  context: row.context,
411
407
  signal,
412
408
  });
413
- await enqueuer.enqueueAdvance(pool, {
409
+ await enqueuer.enqueueAdvance({
414
410
  tenant_id,
415
411
  instance_id,
416
412
  kind: "effect",
@@ -429,9 +425,9 @@ export async function runEffect(pool, registry, enqueuer, payload, signal) {
429
425
  * unless the job is fenced out, i.e. it belongs to a step the instance has
430
426
  * already left, in which case a dead job must not kill a healthy instance.
431
427
  */
432
- export async function failEffectJob(pool, payload, reason) {
433
- await withTransaction(pool, async (client) => {
434
- const row = await lockInstance(client, payload.instance_id);
428
+ export async function failEffectJob(db, payload, reason) {
429
+ await db.transaction(async (tx) => {
430
+ const row = await lockInstance(tx, payload.instance_id);
435
431
  if (!row)
436
432
  return;
437
433
  if (payload.seq !== undefined && row.seq !== payload.seq) {
@@ -443,10 +439,10 @@ export async function failEffectJob(pool, payload, reason) {
443
439
  row.execution_state === EXECUTION_STATE.CANCELLED) {
444
440
  return;
445
441
  }
446
- await updateInstance(client, row.id, {
442
+ await updateInstance(tx, row.id, {
447
443
  execution_state: EXECUTION_STATE.FAILED,
448
444
  }, { bumpSeq: true });
449
- await appendHistory(client, {
445
+ await appendHistory(tx, {
450
446
  tenant_id: row.tenant_id,
451
447
  instance_id: row.id,
452
448
  event_type: HISTORY_EVENT.EFFECT_FAILED,
@@ -1,8 +1,9 @@
1
+ import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
1
2
  /**
2
3
  * Forward migration for schema version 1.0.0 — creates the three framework
3
- * tables and their indexes. Expects `ctx.pool` to be a `pg.Pool` (the shape
4
- * created by {@link createMigrate}).
4
+ * tables and their indexes. Runs on the driver {@link createMigrate} hands every
5
+ * worker, inside the step's transaction.
5
6
  */
6
- export declare function up(ctx?: Record<string, unknown>): Promise<void>;
7
+ export declare function up({ db }: MigrateContext): Promise<void>;
7
8
  /** Reverse migration — drops the three framework tables. Destructive. */
8
- export declare function down(ctx?: Record<string, unknown>): Promise<void>;
9
+ export declare function down({ db }: MigrateContext): Promise<void>;
@@ -60,27 +60,13 @@ DROP TABLE IF EXISTS __workflow_instances;
60
60
  `;
61
61
  /**
62
62
  * Forward migration for schema version 1.0.0 — creates the three framework
63
- * tables and their indexes. Expects `ctx.pool` to be a `pg.Pool` (the shape
64
- * created by {@link createMigrate}).
63
+ * tables and their indexes. Runs on the driver {@link createMigrate} hands every
64
+ * worker, inside the step's transaction.
65
65
  */
66
- export async function up(ctx) {
67
- const { pool } = ctx;
68
- const client = await pool.connect();
69
- try {
70
- await client.query(SQL_UP);
71
- }
72
- finally {
73
- client.release();
74
- }
66
+ export async function up({ db }) {
67
+ await db.exec(SQL_UP);
75
68
  }
76
69
  /** Reverse migration — drops the three framework tables. Destructive. */
77
- export async function down(ctx) {
78
- const { pool } = ctx;
79
- const client = await pool.connect();
80
- try {
81
- await client.query(SQL_DOWN);
82
- }
83
- finally {
84
- client.release();
85
- }
70
+ export async function down({ db }) {
71
+ await db.exec(SQL_DOWN);
86
72
  }
@@ -1,3 +1,4 @@
1
+ import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
1
2
  /**
2
3
  * Forward migration for schema version 1.1.0 — renames `project_id` to
3
4
  * `tenant_id` on all three framework tables, aligning with the ecosystem's
@@ -6,6 +7,6 @@
6
7
  * The rename is in place: existing data is preserved. Idempotent — safe to run
7
8
  * against a schema that already uses `tenant_id`.
8
9
  */
9
- export declare function up(ctx?: Record<string, unknown>): Promise<void>;
10
+ export declare function up({ db }: MigrateContext): Promise<void>;
10
11
  /** Reverse migration — renames `tenant_id` back to `project_id`. Non-destructive. */
11
- export declare function down(ctx?: Record<string, unknown>): Promise<void>;
12
+ export declare function down({ db }: MigrateContext): Promise<void>;
@@ -23,11 +23,7 @@ function renameColumn(table, from, to) {
23
23
  END $$;
24
24
  `;
25
25
  }
26
- const TABLES = [
27
- "__workflow_instances",
28
- "__workflow_inbox",
29
- "__workflow_history",
30
- ];
26
+ const TABLES = ["__workflow_instances", "__workflow_inbox", "__workflow_history"];
31
27
  const SQL_UP = TABLES.map((t) => renameColumn(t, "project_id", "tenant_id")).join("\n");
32
28
  const SQL_DOWN = TABLES.map((t) => renameColumn(t, "tenant_id", "project_id")).join("\n");
33
29
  /**
@@ -38,24 +34,10 @@ const SQL_DOWN = TABLES.map((t) => renameColumn(t, "tenant_id", "project_id")).j
38
34
  * The rename is in place: existing data is preserved. Idempotent — safe to run
39
35
  * against a schema that already uses `tenant_id`.
40
36
  */
41
- export async function up(ctx) {
42
- const { pool } = ctx;
43
- const client = await pool.connect();
44
- try {
45
- await client.query(SQL_UP);
46
- }
47
- finally {
48
- client.release();
49
- }
37
+ export async function up({ db }) {
38
+ await db.exec(SQL_UP);
50
39
  }
51
40
  /** Reverse migration — renames `tenant_id` back to `project_id`. Non-destructive. */
52
- export async function down(ctx) {
53
- const { pool } = ctx;
54
- const client = await pool.connect();
55
- try {
56
- await client.query(SQL_DOWN);
57
- }
58
- finally {
59
- client.release();
60
- }
41
+ export async function down({ db }) {
42
+ await db.exec(SQL_DOWN);
61
43
  }
@@ -1,3 +1,4 @@
1
+ import type { MigrateContext } from "@marianmeres/sqlkit/migrate";
1
2
  /**
2
3
  * Forward migration for schema version 1.2.0 — adds the `seq` fencing token to
3
4
  * `__workflow_instances`, plus the partial index the scheduler's stale-`pending`
@@ -11,6 +12,6 @@
11
12
  * change: existing rows are not rewritten and start at `0`. The index is partial
12
13
  * on a transient state, so it stays tiny.
13
14
  */
14
- export declare function up(ctx?: Record<string, unknown>): Promise<void>;
15
+ export declare function up({ db }: MigrateContext): Promise<void>;
15
16
  /** Reverse migration — drops `seq`. Destructive only of the fence itself. */
16
- export declare function down(ctx?: Record<string, unknown>): Promise<void>;
17
+ export declare function down({ db }: MigrateContext): Promise<void>;
@@ -21,24 +21,10 @@ ALTER TABLE __workflow_instances DROP COLUMN IF EXISTS seq;
21
21
  * change: existing rows are not rewritten and start at `0`. The index is partial
22
22
  * on a transient state, so it stays tiny.
23
23
  */
24
- export async function up(ctx) {
25
- const { pool } = ctx;
26
- const client = await pool.connect();
27
- try {
28
- await client.query(SQL_UP);
29
- }
30
- finally {
31
- client.release();
32
- }
24
+ export async function up({ db }) {
25
+ await db.exec(SQL_UP);
33
26
  }
34
27
  /** Reverse migration — drops `seq`. Destructive only of the fence itself. */
35
- export async function down(ctx) {
36
- const { pool } = ctx;
37
- const client = await pool.connect();
38
- try {
39
- await client.query(SQL_DOWN);
40
- }
41
- finally {
42
- client.release();
43
- }
28
+ export async function down({ db }) {
29
+ await db.exec(SQL_DOWN);
44
30
  }
@@ -1,11 +1,21 @@
1
- import { Migrate } from "@marianmeres/migrate";
2
- import type pg from "pg";
1
+ import type { Migrate } from "@marianmeres/migrate";
2
+ import { type MigrateContext } from "@marianmeres/sqlkit/migrate";
3
+ import { type PgDb } from "@marianmeres/sqlkit/pg";
3
4
  /**
4
5
  * Builds a {@link Migrate} instance pre-loaded with the package's schema
5
6
  * versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
6
7
  *
8
+ * It is sqlkit's migrate wiring over `db`: a run holds an advisory lock, so two
9
+ * processes booting at once wait for each other, and each version is applied in
10
+ * a transaction of its own, together with its version mark.
11
+ *
7
12
  * The active version is stored in `__workflow_migrations` (one row per change,
8
- * latest row wins).
13
+ * latest row wins). A table an earlier version of this package created is read
14
+ * and continued as it is.
15
+ *
16
+ * @param db - a `pg.Pool`, a connected `pg.Client`, or a sqlkit `Driver` of the
17
+ * `pg` dialect. Never closed here.
18
+ * @throws {TypeError} If `db` is none of the three.
9
19
  *
10
20
  * @example
11
21
  * ```ts
@@ -17,6 +27,6 @@ import type pg from "pg";
17
27
  * await migrate.up("latest");
18
28
  * ```
19
29
  */
20
- export declare function createMigrate(pool: pg.Pool, options?: {
30
+ export declare function createMigrate(db: PgDb, options?: {
21
31
  logger?: (...args: unknown[]) => void;
22
- }): Migrate;
32
+ }): Migrate<MigrateContext>;
@@ -1,4 +1,5 @@
1
- import { Migrate } from "@marianmeres/migrate";
1
+ import { createMigrate as createDriverMigrate, } from "@marianmeres/sqlkit/migrate";
2
+ import { toPgDriver } from "@marianmeres/sqlkit/pg";
2
3
  import { down as down_1_0_0, up as up_1_0_0 } from "./1_0_0.js";
3
4
  import { down as down_1_1_0, up as up_1_1_0 } from "./1_1_0.js";
4
5
  import { down as down_1_2_0, up as up_1_2_0 } from "./1_2_0.js";
@@ -7,8 +8,17 @@ const VERSION_TABLE = "__workflow_migrations";
7
8
  * Builds a {@link Migrate} instance pre-loaded with the package's schema
8
9
  * versions. The caller drives it (`.up('latest')`, `.down(...)`, etc.).
9
10
  *
11
+ * It is sqlkit's migrate wiring over `db`: a run holds an advisory lock, so two
12
+ * processes booting at once wait for each other, and each version is applied in
13
+ * a transaction of its own, together with its version mark.
14
+ *
10
15
  * The active version is stored in `__workflow_migrations` (one row per change,
11
- * latest row wins).
16
+ * latest row wins). A table an earlier version of this package created is read
17
+ * and continued as it is.
18
+ *
19
+ * @param db - a `pg.Pool`, a connected `pg.Client`, or a sqlkit `Driver` of the
20
+ * `pg` dialect. Never closed here.
21
+ * @throws {TypeError} If `db` is none of the three.
12
22
  *
13
23
  * @example
14
24
  * ```ts
@@ -20,45 +30,13 @@ const VERSION_TABLE = "__workflow_migrations";
20
30
  * await migrate.up("latest");
21
31
  * ```
22
32
  */
23
- export function createMigrate(pool, options = {}) {
24
- const migrate = new Migrate({
25
- getActiveVersion: getActiveVersion,
26
- setActiveVersion: setActiveVersion,
33
+ export function createMigrate(db, options = {}) {
34
+ const migrate = createDriverMigrate(toPgDriver(db), {
35
+ table: VERSION_TABLE,
27
36
  logger: options.logger,
28
- }, { pool });
37
+ });
29
38
  migrate.addVersion("1.0.0", up_1_0_0, down_1_0_0);
30
39
  migrate.addVersion("1.1.0", up_1_1_0, down_1_1_0);
31
40
  migrate.addVersion("1.2.0", up_1_2_0, down_1_2_0);
32
41
  return migrate;
33
42
  }
34
- async function ensureVersionTable(client) {
35
- await client.query(`CREATE TABLE IF NOT EXISTS ${VERSION_TABLE} (
36
- id serial PRIMARY KEY,
37
- version text NULL,
38
- created_at timestamptz NOT NULL DEFAULT now()
39
- )`);
40
- }
41
- async function getActiveVersion(ctx) {
42
- const { pool } = ctx;
43
- const client = await pool.connect();
44
- try {
45
- await ensureVersionTable(client);
46
- const r = await client.query(`SELECT version FROM ${VERSION_TABLE} ORDER BY id DESC LIMIT 1`);
47
- return r.rows[0]?.version ?? undefined;
48
- }
49
- finally {
50
- client.release();
51
- }
52
- }
53
- async function setActiveVersion(version, ctx) {
54
- const { pool } = ctx;
55
- const client = await pool.connect();
56
- try {
57
- await ensureVersionTable(client);
58
- await client.query(`INSERT INTO ${VERSION_TABLE} (version) VALUES ($1)`, [version ?? null]);
59
- return version;
60
- }
61
- finally {
62
- client.release();
63
- }
64
- }
package/dist/mod.d.ts CHANGED
@@ -4,11 +4,14 @@
4
4
  * Durable workflow / orchestration framework for long-lived state machines.
5
5
  * Built on PostgreSQL. Instances persist across process restarts, sleep for
6
6
  * days waiting for a signal or a timer, and resume from disk via
7
- * {@link https://jsr.io/@marianmeres/fsm | @marianmeres/fsm}'s `fromSnapshot`.
8
- * Effects run as {@link https://jsr.io/@marianmeres/steve | @marianmeres/steve}
7
+ * {@link https://www.npmjs.com/package/@marianmeres/fsm | @marianmeres/fsm}'s `fromSnapshot`.
8
+ * Effects run as {@link https://www.npmjs.com/package/@marianmeres/steve | @marianmeres/steve}
9
9
  * jobs (transactional outbox). The scheduler and inbox correlator are driven
10
- * by {@link https://jsr.io/@marianmeres/cron | @marianmeres/cron}. Schema is
11
- * managed by {@link https://jsr.io/@marianmeres/migrate | @marianmeres/migrate}.
10
+ * by {@link https://www.npmjs.com/package/@marianmeres/cron | @marianmeres/cron}.
11
+ * Every statement runs through
12
+ * {@link https://www.npmjs.com/package/@marianmeres/sqlkit | @marianmeres/sqlkit},
13
+ * which also runs the schema migrations
14
+ * ({@link https://www.npmjs.com/package/@marianmeres/migrate | @marianmeres/migrate}).
12
15
  *
13
16
  * Ships no domain code — userland brings the definitions, handlers, and
14
17
  * matchers. The framework provides the dispatch core and the durability story.
@@ -20,6 +23,9 @@
20
23
  * import { Cron } from "@marianmeres/cron";
21
24
  * import { createMigrate, Workflow } from "@marianmeres/workflow";
22
25
  *
26
+ * // `db` is a pg.Pool, a connected pg.Client, or a sqlkit Driver. Give the
27
+ * // same one to Jobs and Workflow: they then share transactions, so a job is
28
+ * // enqueued in the same transaction as the instance write it belongs to.
23
29
  * const pool = new pg.Pool({ /* ... *\/ });
24
30
  * await createMigrate(pool).up("latest");
25
31
  *
@@ -38,12 +44,12 @@
38
44
  * await wf.create({ definitionId: "...", definitionVersion: "1.0.0" });
39
45
  * ```
40
46
  */
41
- export { Workflow, type WorkflowOptions } from "./workflow.js";
42
- export { type SchedulerTickResult, WorkflowScheduler, type WorkflowSchedulerOptions, } from "./scheduler.js";
43
- export { WorkflowInboxCorrelator, type WorkflowInboxCorrelatorOptions, } from "./correlator.js";
44
- export { WorkflowRegistry } from "./registry.js";
45
- export { defKey, validateDefinition } from "./definition.js";
46
- export { createMigrate } from "./migrations/index.js";
47
- export { getHistory } from "./persistence/history.js";
48
- export { effectJobType, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT } from "./driver.js";
49
- export { type AdvanceJobPayload, type AdvanceKind, DEFAULT_TENANT_ID, type EffectJobPayload, EXECUTION_STATE, type ExecutionState, type Handler, type HandlerArgs, type HandlerResult, HISTORY_EVENT, type HistoryEventType, type HistoryRow, type InboxRow, JOB_TYPE_EFFECT_PREFIX, type Matcher, type MatcherArgs, type NodeMeta, type WorkflowContext, type WorkflowDefinition, type WorkflowFSMConfig, type WorkflowInstanceRow, type WorkflowSnapshot, type WorkflowStateConfig, } from "./types.js";
47
+ export { WorkflowInboxCorrelator, type WorkflowInboxCorrelatorOptions, } from "./correlator.ts";
48
+ export { defKey, validateDefinition } from "./definition.ts";
49
+ export { effectJobType, JOB_TYPE_ADVANCE, PURE_ENTER_EVENT } from "./driver.ts";
50
+ export { createMigrate } from "./migrations/index.ts";
51
+ export { getHistory } from "./persistence/history.ts";
52
+ export { WorkflowRegistry } from "./registry.ts";
53
+ export { type SchedulerTickResult, WorkflowScheduler, type WorkflowSchedulerOptions, } from "./scheduler.ts";
54
+ export { type AdvanceJobPayload, type AdvanceKind, DEFAULT_TENANT_ID, type EffectJobPayload, EXECUTION_STATE, type ExecutionState, type Handler, type HandlerArgs, type HandlerResult, HISTORY_EVENT, type HistoryEventType, type HistoryRow, type InboxRow, JOB_TYPE_EFFECT_PREFIX, type Matcher, type MatcherArgs, type NodeMeta, type WorkflowContext, type WorkflowDefinition, type WorkflowFSMConfig, type WorkflowInstanceRow, type WorkflowSnapshot, type WorkflowStateConfig, } from "./types.ts";
55
+ export { Workflow, type WorkflowOptions } from "./workflow.ts";