@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.
@@ -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
+ }
@@ -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
+ }