@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
package/API.md
ADDED
|
@@ -0,0 +1,529 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
Full public API for [`@marianmeres/workflow`](./README.md).
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Classes](#classes)
|
|
8
|
+
- [Workflow](#workflow)
|
|
9
|
+
- [WorkflowScheduler](#workflowscheduler)
|
|
10
|
+
- [WorkflowInboxCorrelator](#workflowinboxcorrelator)
|
|
11
|
+
- [WorkflowRegistry](#workflowregistry)
|
|
12
|
+
- [Functions](#functions)
|
|
13
|
+
- [createMigrate](#creatempool)
|
|
14
|
+
- [validateDefinition](#validatedefinitiondef-available)
|
|
15
|
+
- [defKey](#defkeyid-version)
|
|
16
|
+
- [effectJobType](#effectjobtypename)
|
|
17
|
+
- [Types](#types)
|
|
18
|
+
- [WorkflowDefinition](#workflowdefinition)
|
|
19
|
+
- [NodeMeta](#nodemeta)
|
|
20
|
+
- [Handler](#handler--handlerargs--handlerresult)
|
|
21
|
+
- [Matcher](#matcher--matcherargs)
|
|
22
|
+
- [WorkflowInstanceRow](#workflowinstancerow)
|
|
23
|
+
- [InboxRow](#inboxrow)
|
|
24
|
+
- [HistoryRow](#historyrow)
|
|
25
|
+
- [Job payloads](#advancejobpayload--effectjobpayload)
|
|
26
|
+
- [Constants](#constants)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Classes
|
|
31
|
+
|
|
32
|
+
### `Workflow`
|
|
33
|
+
|
|
34
|
+
The user-facing API for creating workflow instances and appending inbox signals. Attaches handlers (`workflow.advance` + `workflow.effect.<name>`) to an **externally-owned** `@marianmeres/steve` `Jobs` instance via `setHandler` at construction time. The consumer owns the Jobs lifecycle.
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
import { Workflow } from "@marianmeres/workflow";
|
|
38
|
+
import { Jobs } from "@marianmeres/steve";
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
#### Constructor
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
new Workflow(options: WorkflowOptions)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**`WorkflowOptions`:**
|
|
48
|
+
|
|
49
|
+
| Field | Type | Default | Description |
|
|
50
|
+
|---|---|---|---|
|
|
51
|
+
| `db` | `pg.Pool` | required | PostgreSQL pool. Used for direct SQL (persistence helpers, transactions). |
|
|
52
|
+
| `jobs` | `Jobs` | required | Externally-owned `steve.Jobs` instance. Workflow registers its handlers on it via `setHandler`. The consumer runs `jobs.start()` / `jobs.stop()`. |
|
|
53
|
+
| `projectId` | `string` | `"_default"` | Multi-tenant scope. |
|
|
54
|
+
| `definitions` | `WorkflowDefinition[]` | required | Definitions to register. Validated on construction. |
|
|
55
|
+
| `handlers` | `Record<string, Handler>` | required | Effect handlers keyed by name. |
|
|
56
|
+
| `matchers` | `Record<string, Matcher>` | `{}` | Signal matchers keyed by name. |
|
|
57
|
+
| `effectMaxAttempts` | `number` | `3` | Max retries for effect handlers (steve `max_attempts`). |
|
|
58
|
+
| `effectMaxAttemptDurationMs` | `number` | `0` | Per-attempt timeout in ms (`0` = none). |
|
|
59
|
+
|
|
60
|
+
Throws on construction if any definition references a handler/matcher not present in the maps, or if any other structural problem is found (unknown transition target, missing terminal state, etc.). See [`validateDefinition`](#validatedefinitiondef-available).
|
|
61
|
+
|
|
62
|
+
The constructor also subscribes (`jobs.onDone`) to terminal failures of each `workflow.effect.<name>` type and marks the corresponding workflow instance `failed` on `failed` / `expired`.
|
|
63
|
+
|
|
64
|
+
#### Properties
|
|
65
|
+
|
|
66
|
+
| Name | Type | Description |
|
|
67
|
+
|---|---|---|
|
|
68
|
+
| `db` | `pg.Pool` | The provided pool. |
|
|
69
|
+
| `jobs` | `Jobs` | The injected `Jobs` instance. |
|
|
70
|
+
| `projectId` | `string` | Scope. |
|
|
71
|
+
| `registry` | `WorkflowRegistry` | Read-only access to definitions/handlers/matchers. |
|
|
72
|
+
|
|
73
|
+
#### Methods
|
|
74
|
+
|
|
75
|
+
> **No `start()` or `stop()`.** The consumer manages the `Jobs` lifecycle.
|
|
76
|
+
|
|
77
|
+
##### `create(input): Promise<WorkflowInstanceRow>`
|
|
78
|
+
|
|
79
|
+
Creates a new workflow instance, appends a `created` history entry, and enqueues the first `workflow.advance` job.
|
|
80
|
+
|
|
81
|
+
| Field | Type | Description |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| `definitionId` | `string` | Must be registered. |
|
|
84
|
+
| `definitionVersion` | `string` | Must be registered. |
|
|
85
|
+
| `context` | `WorkflowContext` (optional) | Initial context. Default: `{}`. |
|
|
86
|
+
| `correlationToken` | `string \| null` (optional) | Set up-front for signal-suspending nodes that need to be matchable before the workflow reaches them (e.g. outbound emails using UUID subaddressing). |
|
|
87
|
+
|
|
88
|
+
##### `find(id: string): Promise<WorkflowInstanceRow | null>`
|
|
89
|
+
|
|
90
|
+
Looks up an instance by id, scoped to this Workflow's `projectId`. Returns `null` if not found or scoped to a different project.
|
|
91
|
+
|
|
92
|
+
##### `appendInbox(input): Promise<InboxRow>`
|
|
93
|
+
|
|
94
|
+
Appends an external signal to `__workflow_inbox`. The correlator's next tick matches it to a waiting instance, runs the matcher, and (on match) enqueues an advance with `outcome: 'MATCHED'` and `outcome_data: payload`.
|
|
95
|
+
|
|
96
|
+
| Field | Type | Description |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `source` | `string` | Free-form classifier, e.g. `"email"`, `"webhook"`. |
|
|
99
|
+
| `correlationToken` | `string` | Index key into waiting instances. |
|
|
100
|
+
| `payload` | `Record<string, unknown>` | Signal data, surfaced to the matcher and forwarded to the FSM. |
|
|
101
|
+
|
|
102
|
+
##### `enqueueAdvance` / `enqueueEffect`
|
|
103
|
+
|
|
104
|
+
Internal `JobEnqueuer` interface methods used by the driver. Public so the scheduler and correlator can call them. You normally don't call these directly.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
### `WorkflowScheduler`
|
|
109
|
+
|
|
110
|
+
Cron-driven scheduler that wakes time-suspended instances. Attaches its tick to an **externally-owned** `@marianmeres/cron` `Cron` instance when `register()` is called. Each tick claims due rows and enqueues advance jobs with `outcome: 'TIMEOUT'`.
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
import { WorkflowScheduler } from "@marianmeres/workflow";
|
|
114
|
+
import { Cron } from "@marianmeres/cron";
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### Constructor
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
new WorkflowScheduler(options: WorkflowSchedulerOptions)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
**`WorkflowSchedulerOptions`:**
|
|
124
|
+
|
|
125
|
+
| Field | Type | Default | Description |
|
|
126
|
+
|---|---|---|---|
|
|
127
|
+
| `cron` | `Cron` | required | Externally-owned `Cron` instance. Scheduler registers its tick on this via `cron.register`. The consumer runs `cron.start()` / `cron.stop()`. |
|
|
128
|
+
| `workflow` | `Workflow` | required | The Workflow whose instances this scheduler wakes. `projectId` and `db` are derived from it. |
|
|
129
|
+
| `tickExpression` | `string` | `"* * * * *"` | 5-field cron expression. |
|
|
130
|
+
| `timezone` | `string \| null` | host local | IANA timezone for the cron expression. |
|
|
131
|
+
| `tickBatchSize` | `number` | `100` | Max rows claimed per tick. |
|
|
132
|
+
| `tickName` | `string` | `workflow.scheduler.<projectId>` | Cron job name. |
|
|
133
|
+
|
|
134
|
+
#### Methods
|
|
135
|
+
|
|
136
|
+
> **No `start()` or `stop()`.** The consumer manages the `Cron` lifecycle.
|
|
137
|
+
|
|
138
|
+
| Method | Description |
|
|
139
|
+
|---|---|
|
|
140
|
+
| `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. Idempotent (re-registering preserves `next_run_at`). |
|
|
141
|
+
| `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
|
|
142
|
+
| `tickOnce(): Promise<number>` | Runs one tick immediately. Returns rows woken. Exposed for tests and on-demand wakes. |
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
### `WorkflowInboxCorrelator`
|
|
147
|
+
|
|
148
|
+
Cron-driven correlator that matches inbox signals to waiting instances. Attaches its tick to an externally-owned `Cron` instance when `register()` is called.
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
import { WorkflowInboxCorrelator } from "@marianmeres/workflow";
|
|
152
|
+
import { Cron } from "@marianmeres/cron";
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
#### Constructor
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
new WorkflowInboxCorrelator(options: WorkflowInboxCorrelatorOptions)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**`WorkflowInboxCorrelatorOptions`** has the same shape as `WorkflowSchedulerOptions` (cron / workflow / tickExpression / timezone / tickBatchSize / tickName), with `tickName` defaulting to `workflow.correlator.<projectId>`.
|
|
162
|
+
|
|
163
|
+
#### Methods
|
|
164
|
+
|
|
165
|
+
> **No `start()` or `stop()`.** The consumer manages the `Cron` lifecycle.
|
|
166
|
+
|
|
167
|
+
| Method | Description |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `register(): Promise<void>` | Registers the tick on the injected `Cron`. Call once after construction. |
|
|
170
|
+
| `unregister(): Promise<void>` | Removes the tick from the injected `Cron`. |
|
|
171
|
+
| `tickOnce(): Promise<number>` | Runs one tick immediately. Returns signals processed. Exposed for tests and on-demand correlation. |
|
|
172
|
+
|
|
173
|
+
#### Per-tick behavior
|
|
174
|
+
|
|
175
|
+
For each unprocessed inbox row (claimed via `FOR UPDATE SKIP LOCKED`):
|
|
176
|
+
|
|
177
|
+
1. Find a `waiting` instance with the same `correlation_token`. None → mark processed, done.
|
|
178
|
+
2. Resolve `meta.matcher` on the instance's current state. Missing matcher (string id) → unregistered matcher → `signal_rejected` history, mark processed.
|
|
179
|
+
3. Run the matcher with `{ instanceId, projectId, context, signal }`.
|
|
180
|
+
4. Matcher returns `false` → `signal_rejected` history, mark processed.
|
|
181
|
+
5. Matcher returns `true` → `signal_received` history, flip instance to `pending`, mark processed, enqueue advance with `outcome: 'MATCHED'` and `outcome_data: signal.payload`.
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
### `WorkflowRegistry`
|
|
186
|
+
|
|
187
|
+
In-memory registry of definitions, handlers, and matchers. Built once at construction time; immutable after. You normally don't construct this directly — `Workflow` builds one internally.
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
import { WorkflowRegistry } from "@marianmeres/workflow";
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
#### Constructor
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
new WorkflowRegistry({
|
|
197
|
+
definitions: WorkflowDefinition[],
|
|
198
|
+
handlers: Record<string, Handler>,
|
|
199
|
+
matchers?: Record<string, Matcher>,
|
|
200
|
+
})
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Validates every definition against the registered handler/matcher names. Throws on the first structural problem.
|
|
204
|
+
|
|
205
|
+
#### Methods
|
|
206
|
+
|
|
207
|
+
| Method | Returns | Description |
|
|
208
|
+
|---|---|---|
|
|
209
|
+
| `getDefinition(id, version)` | `WorkflowDefinition \| undefined` | Lookup. |
|
|
210
|
+
| `requireDefinition(id, version)` | `WorkflowDefinition` | Throws if missing. |
|
|
211
|
+
| `getHandler(name)` | `Handler \| undefined` | Lookup. |
|
|
212
|
+
| `requireHandler(name)` | `Handler` | Throws if missing. |
|
|
213
|
+
| `getMatcher(name)` | `Matcher \| undefined` | Lookup. |
|
|
214
|
+
| `requireMatcher(name)` | `Matcher` | Throws if missing. |
|
|
215
|
+
| `handlerNames()` | `string[]` | All registered handler names. |
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Functions
|
|
220
|
+
|
|
221
|
+
### `createMigrate(pool, options?)`
|
|
222
|
+
|
|
223
|
+
Builds a `@marianmeres/migrate` instance pre-loaded with the package's schema versions. The caller drives it (`.up('latest')`, `.down(...)`, `.status()`, etc.).
|
|
224
|
+
|
|
225
|
+
```typescript
|
|
226
|
+
import { createMigrate } from "@marianmeres/workflow";
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
**Parameters:**
|
|
230
|
+
- `pool` (`pg.Pool`) — required
|
|
231
|
+
- `options.logger` (`(...args: unknown[]) => void`, optional) — passed through to `Migrate`
|
|
232
|
+
|
|
233
|
+
**Returns:** `Migrate` — see [`@marianmeres/migrate`](https://jsr.io/@marianmeres/migrate)
|
|
234
|
+
|
|
235
|
+
**Example:**
|
|
236
|
+
|
|
237
|
+
```typescript
|
|
238
|
+
const migrate = createMigrate(pool);
|
|
239
|
+
await migrate.up("latest");
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Active version is stored in `__workflow_migrations`. The migration creates `__workflow_instances`, `__workflow_inbox`, `__workflow_history` and their indexes.
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
### `validateDefinition(def, available)`
|
|
247
|
+
|
|
248
|
+
Standalone validator. Throws on the first structural problem.
|
|
249
|
+
|
|
250
|
+
**Parameters:**
|
|
251
|
+
- `def` (`WorkflowDefinition`)
|
|
252
|
+
- `available.handlers` (`ReadonlySet<string>`)
|
|
253
|
+
- `available.matchers` (`ReadonlySet<string>`)
|
|
254
|
+
|
|
255
|
+
Checks performed:
|
|
256
|
+
|
|
257
|
+
- `id`, `version` are non-empty strings.
|
|
258
|
+
- `fsm.initial` exists in `fsm.states`.
|
|
259
|
+
- Every state has a `meta` field with a known `kind`.
|
|
260
|
+
- Every `effectful` state names a handler in `available.handlers`.
|
|
261
|
+
- Every `suspending` state's matcher (if present) is in `available.matchers`.
|
|
262
|
+
- Every transition target resolves to a defined state.
|
|
263
|
+
- At least one `terminal` state exists.
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
### `defKey(id, version)`
|
|
268
|
+
|
|
269
|
+
Composite key used in the definition registry.
|
|
270
|
+
|
|
271
|
+
**Returns:** `"id@version"` (string)
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
### `effectJobType(name)`
|
|
276
|
+
|
|
277
|
+
Builds the steve job-type string for an effect handler.
|
|
278
|
+
|
|
279
|
+
**Returns:** `"workflow.effect.<name>"` (string)
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
### `getHistory(exec, instanceId, limit?)`
|
|
284
|
+
|
|
285
|
+
Reads the append-only history rows for an instance in chronological order. Useful for `/admin/workflows`-style observability views.
|
|
286
|
+
|
|
287
|
+
**Parameters:**
|
|
288
|
+
- `exec` (`pg.Pool | pg.PoolClient | pg.Client`)
|
|
289
|
+
- `instanceId` (`string`)
|
|
290
|
+
- `limit` (`number`, optional) — Default: `200`
|
|
291
|
+
|
|
292
|
+
**Returns:** `Promise<HistoryRow[]>`
|
|
293
|
+
|
|
294
|
+
**Example:**
|
|
295
|
+
|
|
296
|
+
```typescript
|
|
297
|
+
import { getHistory } from "@marianmeres/workflow";
|
|
298
|
+
const events = await getHistory(pool, instance.id);
|
|
299
|
+
for (const e of events) {
|
|
300
|
+
console.log(e.at.toISOString(), e.event_type, e.from_node, "→", e.to_node);
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## Types
|
|
307
|
+
|
|
308
|
+
### `WorkflowDefinition`
|
|
309
|
+
|
|
310
|
+
```typescript
|
|
311
|
+
type WorkflowDefinition<TState extends string = string, TEvent extends string = string> = {
|
|
312
|
+
id: string;
|
|
313
|
+
version: string;
|
|
314
|
+
fsm: FSMConfig<TState, TEvent, WorkflowContext>;
|
|
315
|
+
};
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
The `fsm` field is a [`@marianmeres/fsm`](https://jsr.io/@marianmeres/fsm) config. Each state config carries `meta: NodeMeta` — the FSM passes it through, the workflow driver dispatches on it.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
### `NodeMeta`
|
|
323
|
+
|
|
324
|
+
```typescript
|
|
325
|
+
type NodeMeta =
|
|
326
|
+
| { kind: "pure" }
|
|
327
|
+
| { kind: "effectful"; handler: string }
|
|
328
|
+
| { kind: "suspending"; matcher?: string; timeoutSec?: number }
|
|
329
|
+
| { kind: "terminal" };
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
Discriminated union of node kinds. The driver dispatches on `kind`:
|
|
333
|
+
|
|
334
|
+
| Kind | Driver behavior |
|
|
335
|
+
|---|---|
|
|
336
|
+
| `pure` | Auto-fires `ENTER`. User wires guarded transitions. Inline-expands. |
|
|
337
|
+
| `effectful` | Enqueues a steve job for `handler`. Waits for completion. |
|
|
338
|
+
| `suspending` | Parks the instance. Wakes on `wake_at` (`TIMEOUT`) or matched inbox signal (`MATCHED`). |
|
|
339
|
+
| `terminal` | Marks instance `completed`. |
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
### `Handler` / `HandlerArgs` / `HandlerResult`
|
|
344
|
+
|
|
345
|
+
```typescript
|
|
346
|
+
type Handler = (args: HandlerArgs) => Promise<HandlerResult> | HandlerResult;
|
|
347
|
+
|
|
348
|
+
interface HandlerArgs {
|
|
349
|
+
instanceId: string;
|
|
350
|
+
projectId: string;
|
|
351
|
+
context: WorkflowContext;
|
|
352
|
+
signal?: AbortSignal;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
interface HandlerResult {
|
|
356
|
+
outcome: string;
|
|
357
|
+
data?: Record<string, unknown>;
|
|
358
|
+
}
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
Handlers are async functions referenced by string name from `effectful` node metas. The driver passes the AbortSignal from steve — long-running handlers should observe it for cooperative cancellation.
|
|
362
|
+
|
|
363
|
+
The returned `outcome` is the FSM event name that drives the next transition. `data` is forwarded as the transition payload (available in guards/actions if the user wires them).
|
|
364
|
+
|
|
365
|
+
**Idempotency:** handlers can run multiple times in failure scenarios. Design them accordingly.
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
### `Matcher` / `MatcherArgs`
|
|
370
|
+
|
|
371
|
+
```typescript
|
|
372
|
+
type Matcher = (args: MatcherArgs) => boolean | Promise<boolean>;
|
|
373
|
+
|
|
374
|
+
interface MatcherArgs {
|
|
375
|
+
instanceId: string;
|
|
376
|
+
projectId: string;
|
|
377
|
+
context: WorkflowContext;
|
|
378
|
+
signal: InboxRow;
|
|
379
|
+
}
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
Matchers are predicate functions referenced from `suspending` node metas. The correlation token alone is just an index lookup — the matcher is the *semantic* gate.
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
### `WorkflowInstanceRow`
|
|
387
|
+
|
|
388
|
+
```typescript
|
|
389
|
+
interface WorkflowInstanceRow {
|
|
390
|
+
id: string;
|
|
391
|
+
project_id: string;
|
|
392
|
+
definition_id: string;
|
|
393
|
+
definition_version: string;
|
|
394
|
+
cursor: string; // current FSM state
|
|
395
|
+
previous_cursor: string | null; // feeds FSM.fromSnapshot's snapshot.previous
|
|
396
|
+
context: WorkflowContext;
|
|
397
|
+
execution_state: ExecutionState;
|
|
398
|
+
wake_at: Date | null;
|
|
399
|
+
correlation_token: string | null;
|
|
400
|
+
created_at: Date;
|
|
401
|
+
updated_at: Date;
|
|
402
|
+
}
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Schema-aligned. `cursor` and `execution_state` are deliberately separate columns — see [Two Orthogonal States](./AGENTS.md#two-orthogonal-states).
|
|
406
|
+
|
|
407
|
+
---
|
|
408
|
+
|
|
409
|
+
### `InboxRow`
|
|
410
|
+
|
|
411
|
+
```typescript
|
|
412
|
+
interface InboxRow {
|
|
413
|
+
id: string;
|
|
414
|
+
project_id: string;
|
|
415
|
+
received_at: Date;
|
|
416
|
+
source: string;
|
|
417
|
+
correlation_token: string;
|
|
418
|
+
payload: Record<string, unknown>;
|
|
419
|
+
processed_at: Date | null;
|
|
420
|
+
}
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
### `HistoryRow`
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
interface HistoryRow {
|
|
429
|
+
id: number;
|
|
430
|
+
project_id: string;
|
|
431
|
+
instance_id: string;
|
|
432
|
+
at: Date;
|
|
433
|
+
event_type: HistoryEventType;
|
|
434
|
+
from_node: string | null;
|
|
435
|
+
to_node: string | null;
|
|
436
|
+
data: Record<string, unknown>;
|
|
437
|
+
}
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
`event_type` is one of [`HISTORY_EVENT`](#history_event) values.
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
### `AdvanceJobPayload` / `EffectJobPayload`
|
|
445
|
+
|
|
446
|
+
```typescript
|
|
447
|
+
interface AdvanceJobPayload {
|
|
448
|
+
project_id: string;
|
|
449
|
+
instance_id: string;
|
|
450
|
+
outcome?: string;
|
|
451
|
+
outcome_data?: Record<string, unknown>;
|
|
452
|
+
timeout?: boolean;
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
interface EffectJobPayload {
|
|
456
|
+
project_id: string;
|
|
457
|
+
instance_id: string;
|
|
458
|
+
handler: string;
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
Steve job payloads. You don't normally construct these directly — `Workflow.create` and the scheduler/correlator do it for you.
|
|
463
|
+
|
|
464
|
+
---
|
|
465
|
+
|
|
466
|
+
### Other re-exported types
|
|
467
|
+
|
|
468
|
+
| Type | Description |
|
|
469
|
+
|---|---|
|
|
470
|
+
| `WorkflowContext` | `Record<string, unknown>` — accumulated payload carried in `__workflow_instances.context` |
|
|
471
|
+
| `WorkflowSnapshot` | `FSMSnapshot<string, WorkflowContext>` — passthrough re-export for convenience |
|
|
472
|
+
| `ExecutionState` | Union of execution-state strings |
|
|
473
|
+
| `HistoryEventType` | Union of history-event-type strings |
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
## Constants
|
|
478
|
+
|
|
479
|
+
### `EXECUTION_STATE`
|
|
480
|
+
|
|
481
|
+
```typescript
|
|
482
|
+
const EXECUTION_STATE = {
|
|
483
|
+
PENDING: "pending",
|
|
484
|
+
RUNNING: "running",
|
|
485
|
+
WAITING: "waiting",
|
|
486
|
+
COMPLETED: "completed",
|
|
487
|
+
FAILED: "failed",
|
|
488
|
+
CANCELLED: "cancelled",
|
|
489
|
+
} as const;
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
### `HISTORY_EVENT`
|
|
493
|
+
|
|
494
|
+
```typescript
|
|
495
|
+
const HISTORY_EVENT = {
|
|
496
|
+
CREATED: "created",
|
|
497
|
+
TRANSITION: "transition",
|
|
498
|
+
EFFECT_DISPATCHED: "effect_dispatched",
|
|
499
|
+
EFFECT_COMPLETED: "effect_completed",
|
|
500
|
+
EFFECT_FAILED: "effect_failed",
|
|
501
|
+
SIGNAL_RECEIVED: "signal_received",
|
|
502
|
+
SIGNAL_REJECTED: "signal_rejected",
|
|
503
|
+
TIMEOUT: "timeout",
|
|
504
|
+
TRANSITION_REJECTED: "transition_rejected",
|
|
505
|
+
COMPLETED: "completed",
|
|
506
|
+
FAILED: "failed",
|
|
507
|
+
CANCELLED: "cancelled",
|
|
508
|
+
} as const;
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
### Misc
|
|
512
|
+
|
|
513
|
+
| Name | Value | Notes |
|
|
514
|
+
|---|---|---|
|
|
515
|
+
| `DEFAULT_PROJECT_ID` | `"_default"` | Used when `projectId` not supplied. Matches `@marianmeres/cron`'s default. |
|
|
516
|
+
| `JOB_TYPE_ADVANCE` | `"workflow.advance"` | Steve job type for one driver step. |
|
|
517
|
+
| `JOB_TYPE_EFFECT_PREFIX` | `"workflow.effect."` | Full type: `workflow.effect.<handlerName>`. |
|
|
518
|
+
| `PURE_ENTER_EVENT` | `"ENTER"` | Synthetic event fired by the driver into pure nodes. Wire guarded transitions on this event. |
|
|
519
|
+
|
|
520
|
+
---
|
|
521
|
+
|
|
522
|
+
## See Also
|
|
523
|
+
|
|
524
|
+
- [README.md](./README.md) — overview, install, end-to-end example
|
|
525
|
+
- [AGENTS.md](./AGENTS.md) — architectural deep-dive for coding agents
|
|
526
|
+
- [`@marianmeres/fsm`](https://jsr.io/@marianmeres/fsm) — the underlying state-graph library
|
|
527
|
+
- [`@marianmeres/steve`](https://jsr.io/@marianmeres/steve) — the underlying job queue
|
|
528
|
+
- [`@marianmeres/cron`](https://jsr.io/@marianmeres/cron) — the underlying cron scheduler
|
|
529
|
+
- [`@marianmeres/migrate`](https://jsr.io/@marianmeres/migrate) — the underlying migration runner
|
package/CLAUDE.md
ADDED
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Marian Meres
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|