@marianmeres/workflow 1.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/AGENTS.md +240 -0
- package/API.md +529 -0
- package/CLAUDE.md +3 -0
- package/LICENSE +21 -0
- package/README.md +227 -0
- package/dist/correlator.d.ts +56 -0
- package/dist/correlator.js +144 -0
- package/dist/definition.d.ts +20 -0
- package/dist/definition.js +109 -0
- package/dist/driver.d.ts +71 -0
- package/dist/driver.js +298 -0
- package/dist/log.d.ts +3 -0
- package/dist/log.js +3 -0
- package/dist/migrations/1_0_0.d.ts +8 -0
- package/dist/migrations/1_0_0.js +86 -0
- package/dist/migrations/index.d.ts +22 -0
- package/dist/migrations/index.js +60 -0
- package/dist/mod.d.ts +46 -0
- package/dist/mod.js +46 -0
- package/dist/persistence/history.d.ts +26 -0
- package/dist/persistence/history.js +33 -0
- package/dist/persistence/inbox.d.ts +23 -0
- package/dist/persistence/inbox.js +37 -0
- package/dist/persistence/instances.d.ts +50 -0
- package/dist/persistence/instances.js +112 -0
- package/dist/persistence/tx.d.ts +6 -0
- package/dist/persistence/tx.js +25 -0
- package/dist/registry.d.ts +36 -0
- package/dist/registry.js +78 -0
- package/dist/scheduler.d.ts +49 -0
- package/dist/scheduler.js +67 -0
- package/dist/types.d.ts +155 -0
- package/dist/types.js +33 -0
- package/dist/workflow.d.ts +82 -0
- package/dist/workflow.js +129 -0
- package/package.json +39 -0
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
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";
|
|
6
|
+
/** Options accepted by {@link Workflow}. */
|
|
7
|
+
export interface WorkflowOptions {
|
|
8
|
+
/** PostgreSQL pool. Used for direct SQL (persistence helpers, transactions). */
|
|
9
|
+
db: pg.Pool;
|
|
10
|
+
/**
|
|
11
|
+
* Externally-owned `@marianmeres/steve` `Jobs` instance. The framework
|
|
12
|
+
* registers its handlers (`workflow.advance` + `workflow.effect.<name>`) on
|
|
13
|
+
* this instance via `setHandler` at construction time. The consumer owns
|
|
14
|
+
* the lifecycle: `await jobs.start(N)` / `await jobs.stop()`.
|
|
15
|
+
*
|
|
16
|
+
* Sharing this `Jobs` with the app's own job types is fine — they coexist
|
|
17
|
+
* by `type` on the same `__job` table.
|
|
18
|
+
*/
|
|
19
|
+
jobs: Jobs;
|
|
20
|
+
/** Project scope (multi-tenancy). Defaults to `_default`. */
|
|
21
|
+
projectId?: string;
|
|
22
|
+
/** Workflow definitions to register. Each is keyed by `(id, version)`. */
|
|
23
|
+
definitions: WorkflowDefinition[];
|
|
24
|
+
/** Handlers keyed by name (referenced from `state.meta.handler`). */
|
|
25
|
+
handlers: Record<string, Handler>;
|
|
26
|
+
/** Matchers keyed by name (referenced from `state.meta.matcher`). */
|
|
27
|
+
matchers?: Record<string, Matcher>;
|
|
28
|
+
/** Per-effect-job retry count. Default: 3 (steve default). */
|
|
29
|
+
effectMaxAttempts?: number;
|
|
30
|
+
/** Per-effect-job timeout in ms. Default: 0 (no limit). */
|
|
31
|
+
effectMaxAttemptDurationMs?: number;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The user-facing API for creating workflow instances and appending inbox
|
|
35
|
+
* signals.
|
|
36
|
+
*
|
|
37
|
+
* Attaches two kinds of handlers to the injected `Jobs` instance:
|
|
38
|
+
* - `workflow.advance` — the durable driver step.
|
|
39
|
+
* - `workflow.effect.<handlerName>` — one per registered effect handler.
|
|
40
|
+
*
|
|
41
|
+
* The consumer constructs and owns the `Jobs` lifecycle (`start` / `stop`).
|
|
42
|
+
* Use {@link WorkflowScheduler} and {@link WorkflowInboxCorrelator} alongside
|
|
43
|
+
* this class to wake suspended instances and correlate inbox signals; both
|
|
44
|
+
* accept an externally-owned `Cron` instance the same way.
|
|
45
|
+
*/
|
|
46
|
+
export declare class Workflow implements JobEnqueuer {
|
|
47
|
+
#private;
|
|
48
|
+
readonly db: pg.Pool;
|
|
49
|
+
readonly jobs: Jobs;
|
|
50
|
+
readonly projectId: string;
|
|
51
|
+
readonly registry: WorkflowRegistry;
|
|
52
|
+
constructor(options: WorkflowOptions);
|
|
53
|
+
/** Internal — used by the driver to enqueue an advance job. */
|
|
54
|
+
enqueueAdvance(_client: pg.PoolClient | pg.Client | pg.Pool, payload: AdvanceJobPayload): Promise<void>;
|
|
55
|
+
/** Internal — used by the driver to enqueue an effect job. */
|
|
56
|
+
enqueueEffect(_client: pg.PoolClient | pg.Client | pg.Pool, handler: string, payload: EffectJobPayload): Promise<void>;
|
|
57
|
+
/**
|
|
58
|
+
* Creates a new workflow instance and enqueues its first advance.
|
|
59
|
+
*
|
|
60
|
+
* @param input.correlationToken - optional, set up-front for signal-suspending
|
|
61
|
+
* nodes that need to be matchable from the moment the instance is born
|
|
62
|
+
* (e.g., outbound emails using UUID subaddressing).
|
|
63
|
+
*/
|
|
64
|
+
create(input: {
|
|
65
|
+
definitionId: string;
|
|
66
|
+
definitionVersion: string;
|
|
67
|
+
context?: WorkflowContext;
|
|
68
|
+
correlationToken?: string | null;
|
|
69
|
+
}): Promise<WorkflowInstanceRow>;
|
|
70
|
+
/** Looks up an instance by id, scoped to this Workflow's project. */
|
|
71
|
+
find(id: string): Promise<WorkflowInstanceRow | null>;
|
|
72
|
+
/**
|
|
73
|
+
* Appends an external signal to the inbox. The {@link WorkflowInboxCorrelator}
|
|
74
|
+
* will pick it up on its next tick and dispatch an advance if a matching
|
|
75
|
+
* waiting instance is found.
|
|
76
|
+
*/
|
|
77
|
+
appendInbox(input: {
|
|
78
|
+
source: string;
|
|
79
|
+
correlationToken: string;
|
|
80
|
+
payload: Record<string, unknown>;
|
|
81
|
+
}): Promise<InboxRow>;
|
|
82
|
+
}
|
package/dist/workflow.js
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
import { JOB_STATUS, } from "@marianmeres/steve";
|
|
2
|
+
import { effectJobType, failEffectJob, JOB_TYPE_ADVANCE, runAdvance, runEffect, } from "./driver.js";
|
|
3
|
+
import { clog } from "./log.js";
|
|
4
|
+
import { appendHistory } from "./persistence/history.js";
|
|
5
|
+
import { appendInbox } from "./persistence/inbox.js";
|
|
6
|
+
import { createInstance, findInstance, } from "./persistence/instances.js";
|
|
7
|
+
import { WorkflowRegistry } from "./registry.js";
|
|
8
|
+
import { DEFAULT_PROJECT_ID, HISTORY_EVENT, } from "./types.js";
|
|
9
|
+
/**
|
|
10
|
+
* The user-facing API for creating workflow instances and appending inbox
|
|
11
|
+
* signals.
|
|
12
|
+
*
|
|
13
|
+
* Attaches two kinds of handlers to the injected `Jobs` instance:
|
|
14
|
+
* - `workflow.advance` — the durable driver step.
|
|
15
|
+
* - `workflow.effect.<handlerName>` — one per registered effect handler.
|
|
16
|
+
*
|
|
17
|
+
* The consumer constructs and owns the `Jobs` lifecycle (`start` / `stop`).
|
|
18
|
+
* Use {@link WorkflowScheduler} and {@link WorkflowInboxCorrelator} alongside
|
|
19
|
+
* this class to wake suspended instances and correlate inbox signals; both
|
|
20
|
+
* accept an externally-owned `Cron` instance the same way.
|
|
21
|
+
*/
|
|
22
|
+
export class Workflow {
|
|
23
|
+
db;
|
|
24
|
+
jobs;
|
|
25
|
+
projectId;
|
|
26
|
+
registry;
|
|
27
|
+
#effectMaxAttempts;
|
|
28
|
+
#effectMaxAttemptDurationMs;
|
|
29
|
+
constructor(options) {
|
|
30
|
+
this.db = options.db;
|
|
31
|
+
this.jobs = options.jobs;
|
|
32
|
+
this.projectId = options.projectId ?? DEFAULT_PROJECT_ID;
|
|
33
|
+
this.registry = new WorkflowRegistry({
|
|
34
|
+
definitions: options.definitions,
|
|
35
|
+
handlers: options.handlers,
|
|
36
|
+
matchers: options.matchers,
|
|
37
|
+
});
|
|
38
|
+
this.#effectMaxAttempts = options.effectMaxAttempts ?? 3;
|
|
39
|
+
this.#effectMaxAttemptDurationMs = options.effectMaxAttemptDurationMs ?? 0;
|
|
40
|
+
// Register the advance handler.
|
|
41
|
+
this.jobs.setHandler(JOB_TYPE_ADVANCE, async (job, _signal) => {
|
|
42
|
+
await runAdvance(this.db, this.registry, this, job.payload);
|
|
43
|
+
return { ok: true };
|
|
44
|
+
});
|
|
45
|
+
// Register one job-type handler per registered effect handler.
|
|
46
|
+
const handlerNames = this.registry.handlerNames();
|
|
47
|
+
for (const name of handlerNames) {
|
|
48
|
+
this.jobs.setHandler(effectJobType(name), async (job, signal) => {
|
|
49
|
+
return await runEffect(this.db, this.registry, this, job.payload, signal);
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
// Watch effect-job terminal failures to mark the workflow instance failed.
|
|
53
|
+
// onDone fires on completed / failed / expired — we react only to non-success.
|
|
54
|
+
for (const name of handlerNames) {
|
|
55
|
+
const type = effectJobType(name);
|
|
56
|
+
this.jobs.onDone(type, (job) => {
|
|
57
|
+
if (job.status === JOB_STATUS.FAILED ||
|
|
58
|
+
job.status === JOB_STATUS.EXPIRED) {
|
|
59
|
+
const payload = job.payload;
|
|
60
|
+
failEffectJob(this.db, payload, `steve: ${job.status}`).catch((e) => clog.error?.(`failEffectJob: ${e}`));
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
/** Internal — used by the driver to enqueue an advance job. */
|
|
66
|
+
async enqueueAdvance(_client, payload) {
|
|
67
|
+
// Steve creates within its own connection/tx; passing the locked client
|
|
68
|
+
// would not gain us atomicity vs steve's bookkeeping. The advance is
|
|
69
|
+
// idempotent (cursor-aware) so an enqueue-but-no-commit race is recoverable.
|
|
70
|
+
await this.jobs.create(JOB_TYPE_ADVANCE, payload);
|
|
71
|
+
}
|
|
72
|
+
/** Internal — used by the driver to enqueue an effect job. */
|
|
73
|
+
async enqueueEffect(_client, handler, payload) {
|
|
74
|
+
await this.jobs.create(effectJobType(handler), payload, {
|
|
75
|
+
max_attempts: this.#effectMaxAttempts,
|
|
76
|
+
max_attempt_duration_ms: this.#effectMaxAttemptDurationMs,
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Creates a new workflow instance and enqueues its first advance.
|
|
81
|
+
*
|
|
82
|
+
* @param input.correlationToken - optional, set up-front for signal-suspending
|
|
83
|
+
* nodes that need to be matchable from the moment the instance is born
|
|
84
|
+
* (e.g., outbound emails using UUID subaddressing).
|
|
85
|
+
*/
|
|
86
|
+
async create(input) {
|
|
87
|
+
const def = this.registry.requireDefinition(input.definitionId, input.definitionVersion);
|
|
88
|
+
const row = await createInstance(this.db, {
|
|
89
|
+
project_id: this.projectId,
|
|
90
|
+
definition_id: input.definitionId,
|
|
91
|
+
definition_version: input.definitionVersion,
|
|
92
|
+
cursor: def.fsm.initial,
|
|
93
|
+
context: input.context ?? {},
|
|
94
|
+
correlation_token: input.correlationToken ?? null,
|
|
95
|
+
});
|
|
96
|
+
await appendHistory(this.db, {
|
|
97
|
+
project_id: this.projectId,
|
|
98
|
+
instance_id: row.id,
|
|
99
|
+
event_type: HISTORY_EVENT.CREATED,
|
|
100
|
+
to_node: row.cursor,
|
|
101
|
+
data: { definitionId: input.definitionId, definitionVersion: input.definitionVersion },
|
|
102
|
+
});
|
|
103
|
+
await this.jobs.create(JOB_TYPE_ADVANCE, {
|
|
104
|
+
project_id: this.projectId,
|
|
105
|
+
instance_id: row.id,
|
|
106
|
+
});
|
|
107
|
+
return row;
|
|
108
|
+
}
|
|
109
|
+
/** Looks up an instance by id, scoped to this Workflow's project. */
|
|
110
|
+
async find(id) {
|
|
111
|
+
const row = await findInstance(this.db, id);
|
|
112
|
+
if (row && row.project_id !== this.projectId)
|
|
113
|
+
return null;
|
|
114
|
+
return row;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Appends an external signal to the inbox. The {@link WorkflowInboxCorrelator}
|
|
118
|
+
* will pick it up on its next tick and dispatch an advance if a matching
|
|
119
|
+
* waiting instance is found.
|
|
120
|
+
*/
|
|
121
|
+
async appendInbox(input) {
|
|
122
|
+
return await appendInbox(this.db, {
|
|
123
|
+
project_id: this.projectId,
|
|
124
|
+
source: input.source,
|
|
125
|
+
correlation_token: input.correlationToken,
|
|
126
|
+
payload: input.payload,
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@marianmeres/workflow",
|
|
3
|
+
"version": "1.0.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
|
+
],
|
|
21
|
+
"author": "Marian Meres",
|
|
22
|
+
"license": "MIT",
|
|
23
|
+
"dependencies": {
|
|
24
|
+
"@marianmeres/clog": "^3.21.0",
|
|
25
|
+
"@marianmeres/cron": "^2.0.1",
|
|
26
|
+
"@marianmeres/fsm": "^3.1.0",
|
|
27
|
+
"@marianmeres/migrate": "^1.2.2",
|
|
28
|
+
"@marianmeres/steve": "^2.0.2",
|
|
29
|
+
"@types/pg": "^8.20.0",
|
|
30
|
+
"pg": "^8.21.0"
|
|
31
|
+
},
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/marianmeres/workflow.git"
|
|
35
|
+
},
|
|
36
|
+
"bugs": {
|
|
37
|
+
"url": "https://github.com/marianmeres/workflow/issues"
|
|
38
|
+
}
|
|
39
|
+
}
|