@lovable.dev/workflows-sdk 0.0.0-dev.22 → 0.0.0-dev.23

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 CHANGED
@@ -83,7 +83,11 @@ await Promise.all(
83
83
  ```
84
84
 
85
85
  Group IDs are unique per workflow callsite. Ordinary sequential steps and
86
- fixed `Promise.all([stepA, stepB])` branches do not need a group.
86
+ fixed `Promise.all([stepA, stepB])` branches do not need a group. For dynamic
87
+ sequential work, await one step directly as the only statement in a `for...of`
88
+ loop. For dynamic parallel work, use the mapped `Promise.all()` form above;
89
+ manifest generation rejects loops that collect step promises for a later
90
+ `Promise.all()`.
87
91
 
88
92
  ## Triggers
89
93
 
@@ -314,10 +318,12 @@ Sequential awaited `ctx.step("name", callback, options)` calls produce order edg
314
318
  `await Promise.all([ctx.step(...), ctx.step(...)])` produces parallel branches
315
319
  that join at the next step. A `Promise.all()` mapped over a collection with the
316
320
  step ID template `step-${item.id}` produces one dynamic parallel node labeled
317
- from `meta.group.label`. Returned step promises work too. Keep step IDs literal
318
- outside this mapped form. A `try` block retains its durable operations when the
319
- `catch` only handles the error in ordinary code. Durable operations in a `catch`
320
- remain visible in a partial graph because edges do not encode error outcomes.
321
+ from `meta.group.label`. A `for...of` loop whose only statement directly awaits
322
+ a step with such an ID template produces one dynamic sequential `loop` node.
323
+ Returned step promises work too. Keep step IDs literal outside these dynamic
324
+ forms. A `try` block retains its durable operations when the `catch` only handles
325
+ the error in ordinary code. Durable operations in a `catch` remain visible in a
326
+ partial graph because edges do not encode error outcomes.
321
327
 
322
328
  An `if` whose body contains durable operations produces a `branch` node. Every
323
329
  durable operation inside it includes an outer-to-inner `meta.branches` path;
@@ -336,15 +342,16 @@ meta: {
336
342
  | Field | Meaning |
337
343
  | --- | --- |
338
344
  | `nodes[].id` | Unique occurrence ID within this graph; use as the UI node key |
339
- | `nodes[].kind` | Durable operation, `branch`, `parallel`, or `unknown` |
345
+ | `nodes[].kind` | Durable operation, `branch`, `parallel`, `loop`, or `unknown` |
340
346
  | `nodes[].stepId` | Runtime durable ID for every statically known operation |
341
347
  | `nodes[].description` | User-facing description for every known durable operation and branch |
342
348
  | `nodes[].branchId` | Stable ID for an inferred `if` node |
343
349
  | `nodes[].condition` | Source expression from the corresponding `if` statement |
344
- | `nodes[].groupId` | Stable callsite ID for a dynamic parallel node |
345
- | `nodes[].cardinality` | `dynamic` for a runtime-sized parallel fan-out |
346
- | `nodes[].operation.kind` | Durable operation repeated by a parallel node |
347
- | `nodes[].operation.stepIdTemplate` | Display template for steps in a dynamic parallel node |
350
+ | `nodes[].groupId` | Stable callsite ID for a dynamic parallel or loop node |
351
+ | `nodes[].cardinality` | `dynamic` for a runtime-sized repeated operation |
352
+ | `nodes[].execution` | `sequential` for a dynamic loop node |
353
+ | `nodes[].operation.kind` | Durable operation repeated by a dynamic node |
354
+ | `nodes[].operation.stepIdTemplate` | Display template for steps in a dynamic node |
348
355
  | `nodes[].operation.description` | User-facing description shared by the repeated steps |
349
356
  | `nodes[].label` | Step ID, branch description, group label, or explanation of unsupported code |
350
357
  | `edges[]` | Order edges or branch edges with an AST-derived boolean `outcome`, referencing node IDs |
@@ -364,11 +371,13 @@ Graphs have `source: "inferred"` and `scope: "handler"`. They describe source
364
371
  structure, not run history or data dependencies, and exclude middleware and
365
372
  initialization. A mapped `Promise.all` is complete when its callback directly
366
373
  returns `ctx.step()` with a template-literal ID derived from a callback parameter.
367
- Loops, switch statements, conditional expressions, helper calls, dynamic step IDs,
368
- and unawaited steps produce `unknown` nodes and `complete: false`; steps inside
369
- unsupported code are not expanded. The UI should show these unknown nodes and mark
370
- partial graphs. Transforms that rewrite the handler may also produce a partial
371
- graph. A handler with no steps can have an empty graph.
374
+ A `for...of` loop is complete when its only statement directly awaits the same
375
+ shape of step using the loop variable. Other loops, switch statements,
376
+ conditional expressions, helper calls, dynamic step IDs, and unawaited steps
377
+ produce `unknown` nodes and `complete: false`; steps inside unsupported code are
378
+ not expanded. The UI should show these unknown nodes and mark partial graphs.
379
+ Transforms that rewrite the handler may also produce a partial graph. A handler
380
+ with no steps can have an empty graph.
372
381
 
373
382
  A step body is one atomic execution unit. Manifest generation rejects statically
374
383
  visible durable calls inside it, including `ctx.step`, `ctx.sleep`, `ctx.now`,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
2
2
  //#region src/manifests/branch-metadata.ts
3
3
  const optionsArgument = {
4
4
  step: 2,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
2
2
  //#region src/manifests/context-escapes.ts
3
3
  const durableMethods = /* @__PURE__ */ new Set([
4
4
  "step",
@@ -1,5 +1,5 @@
1
1
  import { t as defaultDurableId } from "./durable-ids-LsygHSZC.js";
2
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
2
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
3
3
  //#region src/manifests/duplicate-ids.ts
4
4
  /** Where an explicit `{ id }` would sit for each operation. */
5
5
  const optionsArgument = {
@@ -83,6 +83,11 @@ async function findDuplicateOperationIds(handler) {
83
83
  case "step": return;
84
84
  }
85
85
  }
86
+ function repeatedLoopRegion(parent, child) {
87
+ if (ts.isForOfStatement(parent) || ts.isForInStatement(parent)) return parent.statement === child;
88
+ if (ts.isForStatement(parent)) return parent.statement === child || parent.condition === child || parent.incrementor === child;
89
+ return ts.isWhileStatement(parent) || ts.isDoStatement(parent);
90
+ }
86
91
  function placement(call) {
87
92
  const branches = /* @__PURE__ */ new Map();
88
93
  let repeatable = false;
@@ -96,7 +101,7 @@ async function findDuplicateOperationIds(handler) {
96
101
  if (parent.whenTrue === child) branches.set(String(parent.pos), "true");
97
102
  else if (parent.whenFalse === child) branches.set(String(parent.pos), "false");
98
103
  } else if (ts.isCaseClause(parent) || ts.isDefaultClause(parent)) branches.set(String(parent.parent.pos), String(parent.parent.clauses.indexOf(parent)));
99
- else if (parent !== fn && (ts.isForStatement(parent) || ts.isForOfStatement(parent) || ts.isForInStatement(parent) || ts.isWhileStatement(parent) || ts.isDoStatement(parent) || ts.isFunctionLike(parent))) repeatable = true;
104
+ else if (parent !== fn && (repeatedLoopRegion(parent, child) || ts.isFunctionLike(parent))) repeatable = true;
100
105
  child = parent;
101
106
  parent = parent.parent;
102
107
  }
@@ -183,13 +183,13 @@ function serializeSchema(schema, direction, label) {
183
183
  }
184
184
  }
185
185
  async function generateManifests(definition) {
186
- const { extractWorkflowGraph } = await import("./graph-DKuhUjgo.js");
187
- const { findBranchMetadataIssues } = await import("./branch-metadata-BBVwmGtr.js");
188
- const { findWorkflowContextEscapes } = await import("./context-escapes-hJTV5O7I.js");
189
- const { findDuplicateOperationIds } = await import("./duplicate-ids-CBASgH8g.js");
190
- const { findNestedDurableOperations } = await import("./nested-operations-CspliO3h.js");
191
- const { findOperationDescriptionIssues } = await import("./operation-descriptions-ugamonwF.js");
192
- const { findStepMetadataIssues } = await import("./step-metadata-DJRmHyNE.js");
186
+ const { extractWorkflowGraph } = await import("./graph-Qx9mvqnC.js");
187
+ const { findBranchMetadataIssues } = await import("./branch-metadata-IXuazOmY.js");
188
+ const { findWorkflowContextEscapes } = await import("./context-escapes-x0J0HUgC.js");
189
+ const { findDuplicateOperationIds } = await import("./duplicate-ids-NnTrnieX.js");
190
+ const { findNestedDurableOperations } = await import("./nested-operations-DYVa5c5A.js");
191
+ const { findOperationDescriptionIssues } = await import("./operation-descriptions-BLZC8bxV.js");
192
+ const { findStepMetadataIssues } = await import("./step-metadata-MjyYQjOy.js");
193
193
  const collection = registerWorkflows(definition);
194
194
  const manifests = [];
195
195
  for (const workflow of collection.workflows) {
@@ -220,6 +220,10 @@ async function generateManifests(definition) {
220
220
  const step = metadataIssue.stepId ? `ctx.step(${JSON.stringify(metadataIssue.stepId)})` : "ctx.step()";
221
221
  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: "..." } } }`);
222
222
  }
223
+ if (metadataIssue?.kind === "loop-form") {
224
+ const step = metadataIssue.stepId ? `ctx.step(${JSON.stringify(metadataIssue.stepId)})` : "ctx.step()";
225
+ throw new Error(`@lovable.dev/workflows-sdk: workflow "${workflow.id}" ${step} uses an unsupported loop form; await ctx.step() directly as the only statement in a for...of loop for sequential execution, or use Promise.all(items.map((item) => ctx.step(...))) for parallel execution`);
226
+ }
223
227
  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`);
224
228
  const operationDescriptionIssue = (await findOperationDescriptionIssues(workflow.handler))[0];
225
229
  if (operationDescriptionIssue) {
@@ -152,6 +152,27 @@ async function extractWorkflowGraph(handler) {
152
152
  template
153
153
  };
154
154
  }
155
+ function sequentialLoopStep(node) {
156
+ if (node.awaitModifier || !ts.isVariableDeclarationList(node.initializer)) return void 0;
157
+ const declarations = node.initializer.declarations;
158
+ if (declarations.length !== 1) return void 0;
159
+ const declaration = declarations[0];
160
+ if (!ts.isIdentifier(declaration.name) || declaration.initializer) return void 0;
161
+ let statement = node.statement;
162
+ if (ts.isBlock(statement)) statement = statement.statements.length === 1 ? statement.statements[0] : void 0;
163
+ if (!statement || !ts.isExpressionStatement(statement)) return void 0;
164
+ let body = statement.expression;
165
+ while (ts.isParenthesizedExpression(body)) body = body.expression;
166
+ if (!ts.isAwaitExpression(body)) return void 0;
167
+ let awaited = body.expression;
168
+ while (ts.isParenthesizedExpression(awaited)) awaited = awaited.expression;
169
+ if (!durableCall(awaited) || awaited.expression.name.text !== "step") return;
170
+ const template = stepIdTemplate(awaited.arguments[0], /* @__PURE__ */ new Set([declaration.name.text]));
171
+ return template === void 0 ? void 0 : {
172
+ call: awaited,
173
+ template
174
+ };
175
+ }
155
176
  function readableOptions(node) {
156
177
  return node && ts.isObjectLiteralExpression(node) && node.properties.every(ts.isPropertyAssignment) ? node : void 0;
157
178
  }
@@ -530,6 +551,26 @@ async function extractWorkflowGraph(handler) {
530
551
  const completedFinally = finallyFlow.normal.reachable;
531
552
  return statementFlow(path(finallyFlow.normal.tails, normal.reachable && completedFinally), mergePaths(finallyFlow.thrown, path(finallyFlow.normal.tails, thrown.reachable && completedFinally)), mergePaths(finallyFlow.returned, path(finallyFlow.normal.tails, returned.reachable && completedFinally)), mergePaths(finallyFlow.stopped, path(finallyFlow.normal.tails, stopped.reachable && completedFinally)));
532
553
  }
554
+ if (ts.isForOfStatement(statement)) {
555
+ const repeated = sequentialLoopStep(statement);
556
+ if (repeated) {
557
+ const iterable = expression(statement.expression, parents);
558
+ const metadata = stepMetadata(repeated.call);
559
+ const tails = metadata?.group ? addNode({
560
+ kind: "loop",
561
+ groupId: metadata.group.id,
562
+ cardinality: "dynamic",
563
+ execution: "sequential",
564
+ operation: {
565
+ kind: "step",
566
+ stepIdTemplate: repeated.template,
567
+ description: metadata.description
568
+ },
569
+ label: metadata.group.label
570
+ }, iterable.tails) : unknown("Dynamic sequential steps need static group metadata", iterable.tails);
571
+ return statementFlow(path(tails), mergePaths(iterable.thrown, path(tails)));
572
+ }
573
+ }
533
574
  if (ts.isEmptyStatement(statement)) return statementFlow(path(parents));
534
575
  return statementFlow(path(unknown("Loops and other control flow are not supported yet", parents)));
535
576
  }
package/dist/index.d.ts CHANGED
@@ -82,6 +82,16 @@ type WorkflowGraphNodeDetails = {
82
82
  stepIdTemplate: string;
83
83
  description: string;
84
84
  };
85
+ } | {
86
+ kind: "loop";
87
+ groupId: string;
88
+ cardinality: "dynamic";
89
+ execution: "sequential";
90
+ operation: {
91
+ kind: "step";
92
+ stepIdTemplate: string;
93
+ description: string;
94
+ };
85
95
  } | {
86
96
  kind: "approve";
87
97
  stepId: string;
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-DJ7bQOT7.js";
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-BNbOHB23.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
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
2
2
  //#region src/manifests/nested-operations.ts
3
3
  const durableMethods = [
4
4
  "step",
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
2
2
  //#region src/manifests/operation-descriptions.ts
3
3
  const optionsArgument = {
4
4
  approve: 0,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-DKuhUjgo.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-Qx9mvqnC.js";
2
2
  //#region src/manifests/step-metadata.ts
3
3
  async function findStepMetadataIssues(handler) {
4
4
  const api = await loadTypeScript();
@@ -22,19 +22,56 @@ async function findStepMetadataIssues(handler) {
22
22
  if ((ts.isIdentifier(entry.name) || ts.isStringLiteral(entry.name) ? entry.name.text : void 0) === name) return entry.initializer;
23
23
  }
24
24
  }
25
+ function repeatedLoopRegion(parent, child) {
26
+ if (ts.isForOfStatement(parent) || ts.isForInStatement(parent)) return parent.statement === child;
27
+ if (ts.isForStatement(parent)) return parent.statement === child || parent.condition === child || parent.incrementor === child;
28
+ return ts.isWhileStatement(parent) || ts.isDoStatement(parent);
29
+ }
25
30
  function repeatable(call) {
31
+ let child = call;
26
32
  let parent = call.parent;
27
33
  while (parent && parent !== fn) {
28
- if (ts.isForStatement(parent) || ts.isForOfStatement(parent) || ts.isForInStatement(parent) || ts.isWhileStatement(parent) || ts.isDoStatement(parent) || ts.isFunctionLike(parent)) return true;
34
+ if (repeatedLoopRegion(parent, child) || ts.isFunctionLike(parent)) return true;
35
+ child = parent;
29
36
  parent = parent.parent;
30
37
  }
31
38
  return false;
32
39
  }
40
+ function loopAncestors(call) {
41
+ const loops = [];
42
+ let child = call;
43
+ let parent = call.parent;
44
+ while (parent && parent !== fn) {
45
+ if (repeatedLoopRegion(parent, child)) loops.push(parent);
46
+ child = parent;
47
+ parent = parent.parent;
48
+ }
49
+ return loops;
50
+ }
51
+ function isDirectSequentialLoopStep(loop, call) {
52
+ if (!ts.isForOfStatement(loop) || loop.awaitModifier || !ts.isVariableDeclarationList(loop.initializer)) return false;
53
+ const declarations = loop.initializer.declarations;
54
+ if (declarations.length !== 1 || !ts.isIdentifier(declarations[0].name) || declarations[0].initializer) return false;
55
+ let statement = loop.statement;
56
+ if (ts.isBlock(statement)) statement = statement.statements.length === 1 ? statement.statements[0] : void 0;
57
+ if (!statement || !ts.isExpressionStatement(statement)) return false;
58
+ let expression = statement.expression;
59
+ while (ts.isParenthesizedExpression(expression)) expression = expression.expression;
60
+ if (!ts.isAwaitExpression(expression)) return false;
61
+ let awaited = expression.expression;
62
+ while (ts.isParenthesizedExpression(awaited)) awaited = awaited.expression;
63
+ return awaited === call;
64
+ }
33
65
  const issues = [];
34
66
  const groups = /* @__PURE__ */ new Set();
35
67
  const visit = (node) => {
36
68
  if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === context && node.expression.name.text === "step") {
37
69
  const stepId = literalString(node.arguments[0]);
70
+ const loops = loopAncestors(node);
71
+ if (loops.length > 0 && (loops.length !== 1 || !isDirectSequentialLoopStep(loops[0], node))) issues.push({
72
+ kind: "loop-form",
73
+ ...stepId === void 0 ? {} : { stepId }
74
+ });
38
75
  const meta = property(node.arguments[2], "meta");
39
76
  if (literalString(property(meta, "description")) === void 0) issues.push({
40
77
  kind: "description",
package/dist/vite.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as generateManifests } from "./generate-DJ7bQOT7.js";
1
+ import { t as generateManifests } from "./generate-BNbOHB23.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";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovable.dev/workflows-sdk",
3
- "version": "0.0.0-dev.22",
3
+ "version": "0.0.0-dev.23",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",