@lovable.dev/workflows-sdk 0.0.0-dev.15 → 0.0.0-dev.17
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/README.md +67 -12
- package/dist/{duplicate-ids-ClNLIwAz.js → duplicate-ids-DeCwJVrP.js} +1 -1
- package/dist/{generate-CVoNE4Kn.js → generate-B-owFpem.js} +21 -3
- package/dist/{graph-Bt-31WQT.js → graph-DW4JTyGa.js} +84 -28
- package/dist/index.d.ts +33 -3
- package/dist/index.js +31 -13
- package/dist/{nested-operations-Cpzs_PHo.js → nested-operations-CPCNe0xy.js} +1 -1
- package/dist/operation-descriptions-BalrfRnU.js +45 -0
- package/dist/step-metadata-CIGA9vth.js +63 -0
- package/dist/vite.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -46,6 +46,45 @@ definitions as immutable after registration.
|
|
|
46
46
|
See [the authoring example](examples/src/lib/workflows/greet/index.ts) for schemas,
|
|
47
47
|
typed middleware, and a durable step. The package typecheck includes this example.
|
|
48
48
|
|
|
49
|
+
Every durable operation needs a static, user-facing description. Lovable's
|
|
50
|
+
agent supplies this text so the workflow UI can explain each operation before
|
|
51
|
+
and during a run. Put it in the operation's options:
|
|
52
|
+
|
|
53
|
+
| Operation | Description field |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| `ctx.step` | Third argument: `meta.description` |
|
|
56
|
+
| `ctx.sleep`, `ctx.sleepUntil` | Second argument: `meta.description` |
|
|
57
|
+
| `ctx.waitForEvent` | Second argument: `meta.description` |
|
|
58
|
+
| `ctx.now`, `ctx.uuid` | First argument: `meta.description` |
|
|
59
|
+
| `ctx.approve` | First argument: `description` |
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
await ctx.step("load-customer", () => loadCustomer(ctx.input.customerId), {
|
|
63
|
+
meta: { description: "Load the customer record" },
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Manifest generation rejects a missing or computed description. A step declared
|
|
68
|
+
inside a loop or callback also needs a group with a stable ID and user-facing
|
|
69
|
+
label. The group identifies the repeated callsite while each runtime step keeps
|
|
70
|
+
its own concrete ID:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
await Promise.all(
|
|
74
|
+
ctx.input.items.map((item) =>
|
|
75
|
+
ctx.step(`process-${item.id}`, () => processItem(item), {
|
|
76
|
+
meta: {
|
|
77
|
+
description: "Process an item",
|
|
78
|
+
group: { id: "process-items", label: "Process items" },
|
|
79
|
+
},
|
|
80
|
+
}),
|
|
81
|
+
),
|
|
82
|
+
);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Group IDs are unique per workflow callsite. Ordinary sequential steps and
|
|
86
|
+
fixed `Promise.all([stepA, stepB])` branches do not need a group.
|
|
87
|
+
|
|
49
88
|
## Triggers
|
|
50
89
|
|
|
51
90
|
A workflow runs when something triggers it, and a schedule is the first kind of
|
|
@@ -271,22 +310,25 @@ from a Lovable template already have it. Without it — or with a copy exposing
|
|
|
271
310
|
stable JS API, as TypeScript 7 does before 7.1 — the build still succeeds and
|
|
272
311
|
every graph carries one `unknown` node and the diagnostic
|
|
273
312
|
`Install typescript to infer step graphs`.
|
|
274
|
-
Sequential awaited `ctx.step("name", callback)` calls produce order edges;
|
|
313
|
+
Sequential awaited `ctx.step("name", callback, options)` calls produce order edges;
|
|
275
314
|
`await Promise.all([ctx.step(...), ctx.step(...)])` produces parallel branches
|
|
276
315
|
that join at the next step. A `Promise.all()` mapped over a collection with the
|
|
277
316
|
step ID template `step-${item.id}` produces one dynamic parallel node labeled
|
|
278
|
-
`
|
|
279
|
-
this mapped form.
|
|
317
|
+
from `meta.group.label`. Returned step promises work too. Keep step IDs literal
|
|
318
|
+
outside this mapped form.
|
|
280
319
|
|
|
281
320
|
| Field | Meaning |
|
|
282
321
|
| --- | --- |
|
|
283
322
|
| `nodes[].id` | Unique occurrence ID within this graph; use as the UI node key |
|
|
284
323
|
| `nodes[].kind` | Durable operation, `parallel`, or `unknown` |
|
|
285
324
|
| `nodes[].stepId` | Runtime durable ID for every statically known operation |
|
|
325
|
+
| `nodes[].description` | User-facing description for every known durable operation |
|
|
326
|
+
| `nodes[].groupId` | Stable callsite ID for a dynamic parallel node |
|
|
286
327
|
| `nodes[].cardinality` | `dynamic` for a runtime-sized parallel fan-out |
|
|
287
328
|
| `nodes[].operation.kind` | Durable operation repeated by a parallel node |
|
|
288
329
|
| `nodes[].operation.stepIdTemplate` | Display template for steps in a dynamic parallel node |
|
|
289
|
-
| `nodes[].
|
|
330
|
+
| `nodes[].operation.description` | User-facing description shared by the repeated steps |
|
|
331
|
+
| `nodes[].label` | Step ID, group label, or explanation of unsupported code |
|
|
290
332
|
| `edges[]` | `{ source, target, kind: "order" }`, referencing node IDs |
|
|
291
333
|
| `complete` | Whether the handler uses only supported syntax |
|
|
292
334
|
| `diagnostics` | Reasons the graph is partial |
|
|
@@ -417,7 +459,15 @@ There is no run store. A run's entire state is its **memo** — the list of
|
|
|
417
459
|
settled operations — and the caller carries it between calls:
|
|
418
460
|
|
|
419
461
|
```jsonc
|
|
420
|
-
[{
|
|
462
|
+
[{
|
|
463
|
+
"seq": 0,
|
|
464
|
+
"stepId": "greeting",
|
|
465
|
+
"occurrence": 0,
|
|
466
|
+
"kind": "step",
|
|
467
|
+
"meta": { "description": "Create a personalized greeting" },
|
|
468
|
+
"status": "completed",
|
|
469
|
+
"result": "Hello, yehya!"
|
|
470
|
+
}]
|
|
421
471
|
```
|
|
422
472
|
|
|
423
473
|
An entry is keyed by `stepId` and `occurrence` (which call of that id in the
|
|
@@ -536,11 +586,14 @@ inside the step and return the key.
|
|
|
536
586
|
Each call re-runs the handler from the top. Step bodies run only in their
|
|
537
587
|
selected request, so side effects belong inside a step.
|
|
538
588
|
|
|
539
|
-
`next` reports
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
589
|
+
`next` reports an operation's `stepId`, `kind`, and author-supplied `meta`,
|
|
590
|
+
including its description and group. An approval's top-level authoring
|
|
591
|
+
description is copied into runtime metadata for the same response shape. `next`
|
|
592
|
+
does not report a step's input:
|
|
593
|
+
`ctx.step(id, fn, options)` closes over its arguments rather than declaring
|
|
594
|
+
them, so the input is not knowable without running `fn`. Deterministic values
|
|
595
|
+
(`ctx.now`, `ctx.uuid`) are pinned into `memoDelta`, so concurrent calls replay
|
|
596
|
+
the same values after the engine merges the delta.
|
|
544
597
|
|
|
545
598
|
### Waiting on something outside the app
|
|
546
599
|
|
|
@@ -550,14 +603,16 @@ a caller needs to resolve them:
|
|
|
550
603
|
|
|
551
604
|
```json
|
|
552
605
|
{ "seq": 1, "stepId": "approve:Approve refund", "kind": "approve",
|
|
553
|
-
"
|
|
606
|
+
"meta": { "description": "Ask a reviewer to approve the refund" },
|
|
607
|
+
"config": { "title": "Approve refund", "description": "Ask a reviewer to approve the refund" } }
|
|
554
608
|
```
|
|
555
609
|
|
|
556
610
|
The endpoint returns `waiting` with that list in `next`. Resume by appending the
|
|
557
|
-
decision to the memo and calling `advance`:
|
|
611
|
+
decision to the memo, preserving its `meta`, and calling `advance`:
|
|
558
612
|
|
|
559
613
|
```jsonc
|
|
560
614
|
{ "seq": 1, "stepId": "approve:Approve refund", "kind": "approve",
|
|
615
|
+
"meta": { "description": "Ask a reviewer to approve the refund" },
|
|
561
616
|
"status": "completed", "result": { "approved": true, "approvalId": "apr_1" } }
|
|
562
617
|
```
|
|
563
618
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { t as defaultDurableId } from "./durable-ids-LsygHSZC.js";
|
|
2
|
-
import { loadTypeScript } from "./graph-
|
|
2
|
+
import { loadTypeScript } from "./graph-DW4JTyGa.js";
|
|
3
3
|
//#region src/manifests/duplicate-ids.ts
|
|
4
4
|
/** Where an explicit `{ id }` would sit for each operation. */
|
|
5
5
|
const optionsArgument = {
|
|
@@ -183,9 +183,11 @@ function serializeSchema(schema, direction, label) {
|
|
|
183
183
|
}
|
|
184
184
|
}
|
|
185
185
|
async function generateManifests(definition) {
|
|
186
|
-
const { extractWorkflowGraph } = await import("./graph-
|
|
187
|
-
const { findDuplicateOperationIds } = await import("./duplicate-ids-
|
|
188
|
-
const { findNestedDurableOperations } = await import("./nested-operations-
|
|
186
|
+
const { extractWorkflowGraph } = await import("./graph-DW4JTyGa.js");
|
|
187
|
+
const { findDuplicateOperationIds } = await import("./duplicate-ids-DeCwJVrP.js");
|
|
188
|
+
const { findNestedDurableOperations } = await import("./nested-operations-CPCNe0xy.js");
|
|
189
|
+
const { findOperationDescriptionIssues } = await import("./operation-descriptions-BalrfRnU.js");
|
|
190
|
+
const { findStepMetadataIssues } = await import("./step-metadata-CIGA9vth.js");
|
|
189
191
|
const collection = registerWorkflows(definition);
|
|
190
192
|
const manifests = [];
|
|
191
193
|
for (const workflow of collection.workflows) {
|
|
@@ -203,6 +205,22 @@ async function generateManifests(definition) {
|
|
|
203
205
|
const where = duplicate.reason === "loop" ? "inside a loop" : "more than once";
|
|
204
206
|
throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" calls ctx.${duplicate.method}() ${where} with the default id "${duplicate.id}"; replay cannot tell the occurrences apart, so pass an explicit { id } per call site`);
|
|
205
207
|
}
|
|
208
|
+
const metadataIssue = (await findStepMetadataIssues(workflow.handler))[0];
|
|
209
|
+
if (metadataIssue?.kind === "description") {
|
|
210
|
+
const step = metadataIssue.stepId ? `ctx.step(${JSON.stringify(metadataIssue.stepId)})` : "ctx.step()";
|
|
211
|
+
throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ${step} must include a static { meta: { description: "..." } }`);
|
|
212
|
+
}
|
|
213
|
+
if (metadataIssue?.kind === "group") {
|
|
214
|
+
const step = metadataIssue.stepId ? `ctx.step(${JSON.stringify(metadataIssue.stepId)})` : "ctx.step()";
|
|
215
|
+
throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ${step} is declared in a loop or callback and must include a static { meta: { group: { id: "...", label: "..." } } }`);
|
|
216
|
+
}
|
|
217
|
+
if (metadataIssue?.kind === "duplicate-group") throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" uses group id ${JSON.stringify(metadataIssue.groupId)} at more than one repeated step callsite; every group id must identify one callsite`);
|
|
218
|
+
const operationDescriptionIssue = (await findOperationDescriptionIssues(workflow.handler))[0];
|
|
219
|
+
if (operationDescriptionIssue) {
|
|
220
|
+
const { method } = operationDescriptionIssue;
|
|
221
|
+
const description = method === "approve" ? "{ description: \"...\" }" : "{ meta: { description: \"...\" } }";
|
|
222
|
+
throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ctx.${method}() must include a static ${description}`);
|
|
223
|
+
}
|
|
206
224
|
const metadata = {
|
|
207
225
|
id: workflow.id,
|
|
208
226
|
...workflow.description === void 0 ? {} : { description: workflow.description },
|
|
@@ -5,7 +5,9 @@ const durableMethods = {
|
|
|
5
5
|
approve: 0,
|
|
6
6
|
waitForEvent: 0,
|
|
7
7
|
sleep: 0,
|
|
8
|
-
sleepUntil: 0
|
|
8
|
+
sleepUntil: 0,
|
|
9
|
+
now: 0,
|
|
10
|
+
uuid: 0
|
|
9
11
|
};
|
|
10
12
|
let loaded;
|
|
11
13
|
async function loadTypeScript() {
|
|
@@ -104,7 +106,7 @@ async function extractWorkflowGraph(handler) {
|
|
|
104
106
|
}
|
|
105
107
|
return template;
|
|
106
108
|
}
|
|
107
|
-
function
|
|
109
|
+
function mappedStep(node) {
|
|
108
110
|
while (ts.isParenthesizedExpression(node)) node = node.expression;
|
|
109
111
|
if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "map" || node.arguments.length !== 1) return;
|
|
110
112
|
const callback = node.arguments[0];
|
|
@@ -117,7 +119,11 @@ async function extractWorkflowGraph(handler) {
|
|
|
117
119
|
} else body = callback.body;
|
|
118
120
|
while (body && (ts.isParenthesizedExpression(body) || ts.isAwaitExpression(body))) body = body.expression;
|
|
119
121
|
if (!body || !durableCall(body) || body.expression.name.text !== "step") return;
|
|
120
|
-
|
|
122
|
+
const template = stepIdTemplate(body.arguments[0], parameters);
|
|
123
|
+
return template === void 0 ? void 0 : {
|
|
124
|
+
call: body,
|
|
125
|
+
template
|
|
126
|
+
};
|
|
121
127
|
}
|
|
122
128
|
function readableOptions(node) {
|
|
123
129
|
return node && ts.isObjectLiteralExpression(node) && node.properties.every(ts.isPropertyAssignment) ? node : void 0;
|
|
@@ -128,6 +134,25 @@ async function extractWorkflowGraph(handler) {
|
|
|
128
134
|
if ((ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : void 0) === name) return property.initializer;
|
|
129
135
|
}
|
|
130
136
|
}
|
|
137
|
+
function stepMetadata(call) {
|
|
138
|
+
const meta = readableOptions(option(readableOptions(call.arguments[2]), "meta"));
|
|
139
|
+
const description = stringLiteral(option(meta, "description"));
|
|
140
|
+
if (description === void 0) return void 0;
|
|
141
|
+
const groupOptions = readableOptions(option(meta, "group"));
|
|
142
|
+
if (!groupOptions) return { description };
|
|
143
|
+
const id = stringLiteral(option(groupOptions, "id"));
|
|
144
|
+
const label = stringLiteral(option(groupOptions, "label"));
|
|
145
|
+
return id === void 0 || label === void 0 ? { description } : {
|
|
146
|
+
description,
|
|
147
|
+
group: {
|
|
148
|
+
id,
|
|
149
|
+
label
|
|
150
|
+
}
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
function operationDescription(options) {
|
|
154
|
+
return stringLiteral(option(readableOptions(option(options, "meta")), "description"));
|
|
155
|
+
}
|
|
131
156
|
function durableStepId(argument, options, fallback) {
|
|
132
157
|
if (argument && !options) return void 0;
|
|
133
158
|
const given = option(options, "id");
|
|
@@ -138,9 +163,12 @@ async function extractWorkflowGraph(handler) {
|
|
|
138
163
|
if (method === "step") {
|
|
139
164
|
const stepId = stringLiteral(call.arguments[0]);
|
|
140
165
|
if (stepId === void 0) return unknown("Dynamic step IDs are not supported yet", parents);
|
|
166
|
+
const metadata = stepMetadata(call);
|
|
167
|
+
if (!metadata) return unknown("Step descriptions must be static strings", parents);
|
|
141
168
|
return addNode({
|
|
142
169
|
kind: "step",
|
|
143
170
|
stepId,
|
|
171
|
+
description: metadata.description,
|
|
144
172
|
label: stepId
|
|
145
173
|
}, parents);
|
|
146
174
|
}
|
|
@@ -153,15 +181,15 @@ async function extractWorkflowGraph(handler) {
|
|
|
153
181
|
title
|
|
154
182
|
}));
|
|
155
183
|
if (stepId === void 0) return unknown("Dynamic approval IDs are not supported yet", parents);
|
|
156
|
-
const
|
|
157
|
-
|
|
158
|
-
if (given && description === void 0) degrade("Dynamic approval descriptions are not recorded");
|
|
184
|
+
const description = stringLiteral(option(options, "description"));
|
|
185
|
+
if (description === void 0) return unknown("Approval descriptions must be static strings", parents);
|
|
159
186
|
return addNode({
|
|
160
187
|
kind: "approve",
|
|
161
188
|
stepId,
|
|
189
|
+
description,
|
|
162
190
|
config: {
|
|
163
191
|
title,
|
|
164
|
-
|
|
192
|
+
description
|
|
165
193
|
},
|
|
166
194
|
label: title
|
|
167
195
|
}, parents);
|
|
@@ -175,12 +203,15 @@ async function extractWorkflowGraph(handler) {
|
|
|
175
203
|
name: event
|
|
176
204
|
}));
|
|
177
205
|
if (stepId === void 0) return unknown("Dynamic waitForEvent IDs are not supported yet", parents);
|
|
206
|
+
const description = operationDescription(options);
|
|
207
|
+
if (description === void 0) return unknown("Wait descriptions must be static strings", parents);
|
|
178
208
|
const given = option(options, "deadline");
|
|
179
209
|
const deadline = numberLiteral(given);
|
|
180
210
|
if (given && deadline === void 0) degrade("Dynamic waitForEvent deadlines are not recorded");
|
|
181
211
|
return addNode({
|
|
182
212
|
kind: "wait-for-event",
|
|
183
213
|
stepId,
|
|
214
|
+
description,
|
|
184
215
|
config: {
|
|
185
216
|
event,
|
|
186
217
|
...deadline === void 0 ? {} : { deadline }
|
|
@@ -197,26 +228,45 @@ async function extractWorkflowGraph(handler) {
|
|
|
197
228
|
ms
|
|
198
229
|
}));
|
|
199
230
|
if (stepId === void 0) return unknown("Dynamic sleep IDs are not supported yet", parents);
|
|
231
|
+
const description = operationDescription(options);
|
|
232
|
+
if (description === void 0) return unknown("Sleep descriptions must be static strings", parents);
|
|
200
233
|
return addNode({
|
|
201
234
|
kind: "sleep",
|
|
202
235
|
stepId,
|
|
236
|
+
description,
|
|
203
237
|
config: { ms },
|
|
204
238
|
label: `sleep ${ms}ms`
|
|
205
239
|
}, parents);
|
|
206
240
|
}
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
241
|
+
if (method === "sleepUntil") {
|
|
242
|
+
const timestamp = numberLiteral(call.arguments[0]);
|
|
243
|
+
if (timestamp === void 0) return unknown("Dynamic sleepUntil timestamps are not supported yet", parents);
|
|
244
|
+
const options = readableOptions(call.arguments[1]);
|
|
245
|
+
const stepId = durableStepId(call.arguments[1], options, defaultDurableId({
|
|
246
|
+
kind: "sleepUntil",
|
|
247
|
+
timestamp
|
|
248
|
+
}));
|
|
249
|
+
if (stepId === void 0) return unknown("Dynamic sleepUntil IDs are not supported yet", parents);
|
|
250
|
+
const description = operationDescription(options);
|
|
251
|
+
if (description === void 0) return unknown("Sleep descriptions must be static strings", parents);
|
|
252
|
+
return addNode({
|
|
253
|
+
kind: "sleep-until",
|
|
254
|
+
stepId,
|
|
255
|
+
description,
|
|
256
|
+
config: { timestamp },
|
|
257
|
+
label: `sleep until ${timestamp}`
|
|
258
|
+
}, parents);
|
|
259
|
+
}
|
|
260
|
+
const options = readableOptions(call.arguments[0]);
|
|
261
|
+
const stepId = durableStepId(call.arguments[0], options, defaultDurableId({ kind: method }));
|
|
262
|
+
if (stepId === void 0) return unknown(`Dynamic ${method} IDs are not supported yet`, parents);
|
|
263
|
+
const description = operationDescription(options);
|
|
264
|
+
if (description === void 0) return unknown(`${method} descriptions must be static strings`, parents);
|
|
215
265
|
return addNode({
|
|
216
|
-
kind:
|
|
266
|
+
kind: method,
|
|
217
267
|
stepId,
|
|
218
|
-
|
|
219
|
-
label:
|
|
268
|
+
description,
|
|
269
|
+
label: stepId
|
|
220
270
|
}, parents);
|
|
221
271
|
}
|
|
222
272
|
function expression(node, parents, awaited = false) {
|
|
@@ -238,16 +288,22 @@ async function extractWorkflowGraph(handler) {
|
|
|
238
288
|
return ts.isCallExpression(element) ? expression(element, parents, true) : unknown("Dynamic Promise.all entries are not followed", parents);
|
|
239
289
|
}) : parents;
|
|
240
290
|
}
|
|
241
|
-
const
|
|
242
|
-
if (
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
kind: "
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
291
|
+
const mapped = mappedStep(argument);
|
|
292
|
+
if (mapped !== void 0) {
|
|
293
|
+
const metadata = stepMetadata(mapped.call);
|
|
294
|
+
if (!metadata?.group) return unknown("Dynamic parallel steps need static group metadata", parents);
|
|
295
|
+
return addNode({
|
|
296
|
+
kind: "parallel",
|
|
297
|
+
groupId: metadata.group.id,
|
|
298
|
+
cardinality: "dynamic",
|
|
299
|
+
operation: {
|
|
300
|
+
kind: "step",
|
|
301
|
+
stepIdTemplate: mapped.template,
|
|
302
|
+
description: metadata.description
|
|
303
|
+
},
|
|
304
|
+
label: metadata.group.label
|
|
305
|
+
}, parents);
|
|
306
|
+
}
|
|
251
307
|
}
|
|
252
308
|
if (contains(node, (child) => ts.isCallExpression(child) || ts.isAwaitExpression(child) || ts.isNewExpression(child))) return unknown("Helper calls and dynamic expressions are not followed", parents);
|
|
253
309
|
if (ts.isIdentifier(node) && node.text === context) return unknown("Workflow context aliases are not followed", parents);
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AnyWorkflowDefinition, AnyWorkflowDefinition as AnyWorkflowDefinition$1, Ctx, RunStore, StepContext, StepOptions, WorkflowDefinition, WorkflowEvent, WorkflowInput, WorkflowInput as WorkflowInput$1, WorkflowOutput, WorkflowState, createMiddleware, createWorkflow } from "@tanstack/workflow-core";
|
|
1
|
+
import { AnyWorkflowDefinition, AnyWorkflowDefinition as AnyWorkflowDefinition$1, Ctx, RunStore, StepContext, StepOptions, WorkflowDefinition, WorkflowEvent, WorkflowInput, WorkflowInput as WorkflowInput$1, WorkflowMetadata, WorkflowOutput, WorkflowState, createMiddleware, createWorkflow } from "@tanstack/workflow-core";
|
|
2
2
|
import "typescript";
|
|
3
3
|
//#region src/core/cadence.d.ts
|
|
4
4
|
type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
|
|
@@ -51,27 +51,44 @@ declare function registerWorkflows<const TWorkflows extends readonly AnyWorkflow
|
|
|
51
51
|
triggers?: readonly TriggerDefinition[];
|
|
52
52
|
}): WorkflowsDefinition<TWorkflows[number]>;
|
|
53
53
|
//#endregion
|
|
54
|
+
//#region src/core/step-metadata.d.ts
|
|
55
|
+
interface WorkflowStepGroup {
|
|
56
|
+
id: string;
|
|
57
|
+
label: string;
|
|
58
|
+
}
|
|
59
|
+
type WorkflowOperationMetadata = Record<string, unknown> & {
|
|
60
|
+
description: string;
|
|
61
|
+
};
|
|
62
|
+
type WorkflowStepMetadata = WorkflowOperationMetadata & {
|
|
63
|
+
group?: WorkflowStepGroup;
|
|
64
|
+
};
|
|
65
|
+
//#endregion
|
|
54
66
|
//#region src/manifests/graph.d.ts
|
|
55
67
|
type WorkflowGraphNodeDetails = {
|
|
56
68
|
kind: "step";
|
|
57
69
|
stepId: string;
|
|
70
|
+
description: string;
|
|
58
71
|
} | {
|
|
59
72
|
kind: "parallel";
|
|
73
|
+
groupId: string;
|
|
60
74
|
cardinality: "dynamic";
|
|
61
75
|
operation: {
|
|
62
76
|
kind: "step";
|
|
63
77
|
stepIdTemplate: string;
|
|
78
|
+
description: string;
|
|
64
79
|
};
|
|
65
80
|
} | {
|
|
66
81
|
kind: "approve";
|
|
67
82
|
stepId: string;
|
|
83
|
+
description: string;
|
|
68
84
|
config: {
|
|
69
85
|
title: string;
|
|
70
|
-
description
|
|
86
|
+
description: string;
|
|
71
87
|
};
|
|
72
88
|
} | {
|
|
73
89
|
kind: "wait-for-event";
|
|
74
90
|
stepId: string;
|
|
91
|
+
description: string;
|
|
75
92
|
config: {
|
|
76
93
|
event: string;
|
|
77
94
|
deadline?: number;
|
|
@@ -79,15 +96,25 @@ type WorkflowGraphNodeDetails = {
|
|
|
79
96
|
} | {
|
|
80
97
|
kind: "sleep";
|
|
81
98
|
stepId: string;
|
|
99
|
+
description: string;
|
|
82
100
|
config: {
|
|
83
101
|
ms: number;
|
|
84
102
|
};
|
|
85
103
|
} | {
|
|
86
104
|
kind: "sleep-until";
|
|
87
105
|
stepId: string;
|
|
106
|
+
description: string;
|
|
88
107
|
config: {
|
|
89
108
|
timestamp: number;
|
|
90
109
|
};
|
|
110
|
+
} | {
|
|
111
|
+
kind: "now";
|
|
112
|
+
stepId: string;
|
|
113
|
+
description: string;
|
|
114
|
+
} | {
|
|
115
|
+
kind: "uuid";
|
|
116
|
+
stepId: string;
|
|
117
|
+
description: string;
|
|
91
118
|
} | {
|
|
92
119
|
kind: "unknown";
|
|
93
120
|
};
|
|
@@ -176,6 +203,7 @@ interface MemoEntry {
|
|
|
176
203
|
/** Key of the step whose body recorded this, if any; a memoized parent hides it. */
|
|
177
204
|
parent?: string;
|
|
178
205
|
kind: StepKind;
|
|
206
|
+
meta?: WorkflowMetadata;
|
|
179
207
|
status: "completed" | "failed";
|
|
180
208
|
result?: unknown;
|
|
181
209
|
error?: string;
|
|
@@ -186,6 +214,7 @@ interface StepIntentBase {
|
|
|
186
214
|
occurrence: number;
|
|
187
215
|
/** Kind-specific detail: sleep `ms`, `waitForEvent` name, approval title. */
|
|
188
216
|
config?: Record<string, unknown>;
|
|
217
|
+
meta?: WorkflowMetadata;
|
|
189
218
|
}
|
|
190
219
|
/** A durable operation the replay reached but could not answer. */
|
|
191
220
|
type StepIntent = StepIntentBase & ({
|
|
@@ -198,6 +227,7 @@ interface StepResult<K extends StepKind = StepKind> {
|
|
|
198
227
|
stepId: string;
|
|
199
228
|
occurrence: number;
|
|
200
229
|
kind: K;
|
|
230
|
+
meta?: WorkflowMetadata;
|
|
201
231
|
status: "completed" | "failed";
|
|
202
232
|
result?: unknown;
|
|
203
233
|
error?: string;
|
|
@@ -272,4 +302,4 @@ declare function createStepsHandler(collection: WorkflowCollection, options?: St
|
|
|
272
302
|
*/
|
|
273
303
|
declare function toServerSentEventsResponse(events: AsyncIterable<WorkflowEvent>): Response;
|
|
274
304
|
//#endregion
|
|
275
|
-
export { type AnyWorkflowDefinition, type Cadence, type Ctx, type MemoEntry, type OverlapPolicy, type ReplayOutcome, type ResolvedSchedule, type ResolvedTrigger, type ScheduleDefinition, type StepContext, type StepIntent, type StepKind, type StepOptions, type StepReference, type StepResult, type StepsDisposition, type StepsHandler, type StepsHandlerOptions, type StepsRequest, type StepsResponse, type TanStackWorkflowHandler, type TanStackWorkflowHandlerOptions, type TriggerDefinition, type Weekday, type WorkflowCollection, type WorkflowDefinition, type WorkflowGraph, type WorkflowGraphNode, type WorkflowGraphNodeDetails, type WorkflowInput, type WorkflowManifest, type WorkflowOutput, type WorkflowState, type WorkflowsDefinition, createMiddleware, createStepsHandler, createTanStackWorkflowHandler, createWorkflow, daily, defineSchedule, generateManifests, hourly, registerWorkflows, toServerSentEventsResponse, weekly };
|
|
305
|
+
export { type AnyWorkflowDefinition, type Cadence, type Ctx, type MemoEntry, type OverlapPolicy, type ReplayOutcome, type ResolvedSchedule, type ResolvedTrigger, type ScheduleDefinition, type StepContext, type StepIntent, type StepKind, type StepOptions, type StepReference, type StepResult, type StepsDisposition, type StepsHandler, type StepsHandlerOptions, type StepsRequest, type StepsResponse, type TanStackWorkflowHandler, type TanStackWorkflowHandlerOptions, type TriggerDefinition, type Weekday, type WorkflowCollection, type WorkflowDefinition, type WorkflowGraph, type WorkflowGraphNode, type WorkflowGraphNodeDetails, type WorkflowInput, type WorkflowManifest, type WorkflowOperationMetadata, type WorkflowOutput, type WorkflowState, type WorkflowStepGroup, type WorkflowStepMetadata, type WorkflowsDefinition, createMiddleware, createStepsHandler, createTanStackWorkflowHandler, createWorkflow, daily, defineSchedule, generateManifests, hourly, registerWorkflows, toServerSentEventsResponse, weekly };
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as defineSchedule, c as weekly, i as registerWorkflows, n as createMiddleware, o as daily, r as createWorkflow, s as hourly, t as generateManifests } from "./generate-
|
|
1
|
+
import { a as defineSchedule, c as weekly, i as registerWorkflows, n as createMiddleware, o as daily, r as createWorkflow, s as hourly, t as generateManifests } from "./generate-B-owFpem.js";
|
|
2
2
|
import { t as defaultDurableId } from "./durable-ids-LsygHSZC.js";
|
|
3
3
|
import { WorkflowRequestParseError, inMemoryRunStore, parseWorkflowRequest, runWorkflow } from "@tanstack/workflow-core";
|
|
4
4
|
//#region src/stacks/tanstack/sse.ts
|
|
@@ -129,6 +129,12 @@ const EXECUTABLE = /* @__PURE__ */ new Set([
|
|
|
129
129
|
function describe(error) {
|
|
130
130
|
return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
|
|
131
131
|
}
|
|
132
|
+
function groupId(meta) {
|
|
133
|
+
const group = meta?.group;
|
|
134
|
+
if (group === null || typeof group !== "object") return void 0;
|
|
135
|
+
const id = group.id;
|
|
136
|
+
return typeof id === "string" ? id : void 0;
|
|
137
|
+
}
|
|
132
138
|
function runtimeContext() {
|
|
133
139
|
return {
|
|
134
140
|
timeRemaining: () => Number.POSITIVE_INFINITY,
|
|
@@ -178,6 +184,7 @@ async function replay(options) {
|
|
|
178
184
|
stepId: entry.stepId,
|
|
179
185
|
occurrence: entry.occurrence,
|
|
180
186
|
kind: entry.kind,
|
|
187
|
+
...entry.meta ? { meta: entry.meta } : {},
|
|
181
188
|
status: entry.status,
|
|
182
189
|
result: entry.result,
|
|
183
190
|
error: entry.error
|
|
@@ -185,7 +192,7 @@ async function replay(options) {
|
|
|
185
192
|
results.push(result);
|
|
186
193
|
options.onStepSettle?.(result);
|
|
187
194
|
}
|
|
188
|
-
function durable(kind, stepId, run, config, defaulted = false) {
|
|
195
|
+
function durable(kind, stepId, run, config, defaulted = false, meta) {
|
|
189
196
|
const index = seq++;
|
|
190
197
|
const occurrence = occurrences.get(stepId) ?? 0;
|
|
191
198
|
occurrences.set(stepId, occurrence + 1);
|
|
@@ -205,6 +212,11 @@ async function replay(options) {
|
|
|
205
212
|
nonDeterminism = `memo has ${answered.kind} "${stepId}" (#${occurrence}), replay produced ${kind}`;
|
|
206
213
|
return never;
|
|
207
214
|
}
|
|
215
|
+
const recordedGroupId = groupId(answered.meta);
|
|
216
|
+
if (recordedGroupId !== void 0 && recordedGroupId !== groupId(meta)) {
|
|
217
|
+
nonDeterminism = `memo has group "${recordedGroupId}" for step "${stepId}", replay produced a different group`;
|
|
218
|
+
return never;
|
|
219
|
+
}
|
|
208
220
|
if (answered.status === "completed") return Promise.resolve(answered.result);
|
|
209
221
|
return Promise.reject(new Error(answered.error ?? `step "${stepId}" failed`));
|
|
210
222
|
}
|
|
@@ -214,7 +226,8 @@ async function replay(options) {
|
|
|
214
226
|
stepId,
|
|
215
227
|
occurrence,
|
|
216
228
|
kind,
|
|
217
|
-
...config ? { config } : {}
|
|
229
|
+
...config ? { config } : {},
|
|
230
|
+
...meta ? { meta } : {}
|
|
218
231
|
};
|
|
219
232
|
if (!run || !EXECUTABLE.has(kind) || !allow(intent, pass)) {
|
|
220
233
|
pending.push(intent);
|
|
@@ -237,7 +250,8 @@ async function replay(options) {
|
|
|
237
250
|
kind,
|
|
238
251
|
status: "completed",
|
|
239
252
|
result,
|
|
240
|
-
...parent ? { parent } : {}
|
|
253
|
+
...parent ? { parent } : {},
|
|
254
|
+
...meta ? { meta } : {}
|
|
241
255
|
});
|
|
242
256
|
return result;
|
|
243
257
|
}, (error) => {
|
|
@@ -248,7 +262,8 @@ async function replay(options) {
|
|
|
248
262
|
kind,
|
|
249
263
|
status: "failed",
|
|
250
264
|
error: describe(error),
|
|
251
|
-
...parent ? { parent } : {}
|
|
265
|
+
...parent ? { parent } : {},
|
|
266
|
+
...meta ? { meta } : {}
|
|
252
267
|
});
|
|
253
268
|
throw error;
|
|
254
269
|
});
|
|
@@ -264,33 +279,36 @@ async function replay(options) {
|
|
|
264
279
|
state,
|
|
265
280
|
signal: controller.signal,
|
|
266
281
|
runtime,
|
|
267
|
-
step: (id, fn,
|
|
282
|
+
step: (id, fn, stepOptions) => durable("step", id, async () => fn({
|
|
268
283
|
id,
|
|
269
284
|
attempt: 1,
|
|
270
285
|
runtime,
|
|
271
286
|
signal: controller.signal
|
|
272
|
-
})),
|
|
287
|
+
}), void 0, false, stepOptions?.meta),
|
|
273
288
|
sleep: (ms, opts) => durable("sleep", opts?.id ?? defaultDurableId({
|
|
274
289
|
kind: "sleep",
|
|
275
290
|
ms
|
|
276
|
-
}), void 0, { ms }, opts?.id === void 0),
|
|
291
|
+
}), void 0, { ms }, opts?.id === void 0, opts?.meta),
|
|
277
292
|
sleepUntil: (timestamp, opts) => durable("sleep", opts?.id ?? defaultDurableId({
|
|
278
293
|
kind: "sleepUntil",
|
|
279
294
|
timestamp
|
|
280
|
-
}), void 0, { timestamp }, opts?.id === void 0),
|
|
295
|
+
}), void 0, { timestamp }, opts?.id === void 0, opts?.meta),
|
|
281
296
|
waitForEvent: (name, opts) => durable("waitForEvent", opts?.id ?? defaultDurableId({
|
|
282
297
|
kind: "waitForEvent",
|
|
283
298
|
name
|
|
284
|
-
}), void 0, { name }, opts?.id === void 0),
|
|
299
|
+
}), void 0, { name }, opts?.id === void 0, opts?.meta),
|
|
285
300
|
approve: (opts) => durable("approve", opts.id ?? defaultDurableId({
|
|
286
301
|
kind: "approve",
|
|
287
302
|
title: opts.title
|
|
288
303
|
}), void 0, {
|
|
289
304
|
title: opts.title,
|
|
290
305
|
...opts.description === void 0 ? {} : { description: opts.description }
|
|
291
|
-
}, opts.id === void 0
|
|
292
|
-
|
|
293
|
-
|
|
306
|
+
}, opts.id === void 0, {
|
|
307
|
+
...opts.meta,
|
|
308
|
+
...opts.description === void 0 ? {} : { description: opts.description }
|
|
309
|
+
}),
|
|
310
|
+
now: (opts) => durable("now", opts?.id ?? defaultDurableId({ kind: "now" }), async () => Date.now(), void 0, opts?.id === void 0, opts?.meta),
|
|
311
|
+
uuid: (opts) => durable("uuid", opts?.id ?? defaultDurableId({ kind: "uuid" }), async () => crypto.randomUUID(), void 0, opts?.id === void 0, opts?.meta),
|
|
294
312
|
emit: (name, value) => {
|
|
295
313
|
emitted.push({
|
|
296
314
|
name,
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { loadTypeScript } from "./graph-DW4JTyGa.js";
|
|
2
|
+
//#region src/manifests/operation-descriptions.ts
|
|
3
|
+
const optionsArgument = {
|
|
4
|
+
approve: 0,
|
|
5
|
+
sleep: 1,
|
|
6
|
+
sleepUntil: 1,
|
|
7
|
+
waitForEvent: 1,
|
|
8
|
+
now: 0,
|
|
9
|
+
uuid: 0
|
|
10
|
+
};
|
|
11
|
+
async function findOperationDescriptionIssues(handler) {
|
|
12
|
+
const api = await loadTypeScript();
|
|
13
|
+
if (!api) return [];
|
|
14
|
+
const ts = api;
|
|
15
|
+
const source = ts.createSourceFile("handler.js", `const handler = ${Function.prototype.toString.call(handler)};`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.JS);
|
|
16
|
+
const declaration = source.statements[0];
|
|
17
|
+
const fn = declaration && ts.isVariableStatement(declaration) ? declaration.declarationList.declarations[0]?.initializer : void 0;
|
|
18
|
+
if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) || source.text.includes("[native code]")) return [];
|
|
19
|
+
const parameter = fn.parameters[0]?.name;
|
|
20
|
+
if (!parameter || !ts.isIdentifier(parameter)) return [];
|
|
21
|
+
const context = parameter.text;
|
|
22
|
+
function literalString(node) {
|
|
23
|
+
return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : void 0;
|
|
24
|
+
}
|
|
25
|
+
function property(node, name) {
|
|
26
|
+
if (!node || !ts.isObjectLiteralExpression(node)) return void 0;
|
|
27
|
+
for (const entry of node.properties) {
|
|
28
|
+
if (!ts.isPropertyAssignment(entry)) continue;
|
|
29
|
+
if ((ts.isIdentifier(entry.name) || ts.isStringLiteral(entry.name) ? entry.name.text : void 0) === name) return entry.initializer;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
const issues = [];
|
|
33
|
+
const visit = (node) => {
|
|
34
|
+
if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text in optionsArgument) {
|
|
35
|
+
const method = node.expression.name.text;
|
|
36
|
+
const options = node.arguments[optionsArgument[method]];
|
|
37
|
+
if ((method === "approve" ? literalString(property(options, "description")) : literalString(property(property(options, "meta"), "description"))) === void 0) issues.push({ method });
|
|
38
|
+
}
|
|
39
|
+
ts.forEachChild(node, visit);
|
|
40
|
+
};
|
|
41
|
+
visit(fn);
|
|
42
|
+
return issues;
|
|
43
|
+
}
|
|
44
|
+
//#endregion
|
|
45
|
+
export { findOperationDescriptionIssues };
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { loadTypeScript } from "./graph-DW4JTyGa.js";
|
|
2
|
+
//#region src/manifests/step-metadata.ts
|
|
3
|
+
async function findStepMetadataIssues(handler) {
|
|
4
|
+
const api = await loadTypeScript();
|
|
5
|
+
if (!api) return [];
|
|
6
|
+
const ts = api;
|
|
7
|
+
const source = ts.createSourceFile("handler.js", `const handler = ${Function.prototype.toString.call(handler)};`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.JS);
|
|
8
|
+
const declaration = source.statements[0];
|
|
9
|
+
const fn = declaration && ts.isVariableStatement(declaration) ? declaration.declarationList.declarations[0]?.initializer : void 0;
|
|
10
|
+
if (!fn || !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) || source.text.includes("[native code]")) return [];
|
|
11
|
+
const parameter = fn.parameters[0]?.name;
|
|
12
|
+
if (!parameter || !ts.isIdentifier(parameter)) return [];
|
|
13
|
+
const context = parameter.text;
|
|
14
|
+
function literalString(node) {
|
|
15
|
+
return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : void 0;
|
|
16
|
+
}
|
|
17
|
+
function property(node, name) {
|
|
18
|
+
if (!node || !ts.isObjectLiteralExpression(node)) return void 0;
|
|
19
|
+
for (const entry of node.properties) {
|
|
20
|
+
if (!ts.isPropertyAssignment(entry)) continue;
|
|
21
|
+
if ((ts.isIdentifier(entry.name) || ts.isStringLiteral(entry.name) ? entry.name.text : void 0) === name) return entry.initializer;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
function repeatable(call) {
|
|
25
|
+
let parent = call.parent;
|
|
26
|
+
while (parent && parent !== fn) {
|
|
27
|
+
if (ts.isForStatement(parent) || ts.isForOfStatement(parent) || ts.isForInStatement(parent) || ts.isWhileStatement(parent) || ts.isDoStatement(parent) || ts.isFunctionLike(parent)) return true;
|
|
28
|
+
parent = parent.parent;
|
|
29
|
+
}
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
|
+
const issues = [];
|
|
33
|
+
const groups = /* @__PURE__ */ new Set();
|
|
34
|
+
const visit = (node) => {
|
|
35
|
+
if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text === "step") {
|
|
36
|
+
const stepId = literalString(node.arguments[0]);
|
|
37
|
+
const meta = property(node.arguments[2], "meta");
|
|
38
|
+
if (literalString(property(meta, "description")) === void 0) issues.push({
|
|
39
|
+
kind: "description",
|
|
40
|
+
...stepId === void 0 ? {} : { stepId }
|
|
41
|
+
});
|
|
42
|
+
if (repeatable(node)) {
|
|
43
|
+
const group = property(meta, "group");
|
|
44
|
+
const groupId = literalString(property(group, "id"));
|
|
45
|
+
const label = literalString(property(group, "label"));
|
|
46
|
+
if (groupId === void 0 || label === void 0) issues.push({
|
|
47
|
+
kind: "group",
|
|
48
|
+
...stepId === void 0 ? {} : { stepId }
|
|
49
|
+
});
|
|
50
|
+
else if (groups.has(groupId)) issues.push({
|
|
51
|
+
kind: "duplicate-group",
|
|
52
|
+
groupId
|
|
53
|
+
});
|
|
54
|
+
else groups.add(groupId);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
ts.forEachChild(node, visit);
|
|
58
|
+
};
|
|
59
|
+
visit(fn);
|
|
60
|
+
return issues;
|
|
61
|
+
}
|
|
62
|
+
//#endregion
|
|
63
|
+
export { findStepMetadataIssues };
|
package/dist/vite.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { t as generateManifests } from "./generate-
|
|
1
|
+
import { t as generateManifests } from "./generate-B-owFpem.js";
|
|
2
2
|
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
3
3
|
import { createServer } from "vite";
|
|
4
4
|
import { lstat, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
|