@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 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
- `step-{item.id}`. Returned step promises work too. Keep step IDs literal outside
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[].label` | Step name or explanation of unsupported code |
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
- [{ "seq": 0, "stepId": "greeting", "occurrence": 0, "kind": "step", "status": "completed", "result": "Hello, yehya!" }]
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 a step's `stepId` and `kind` but not its input:
540
- `ctx.step(id, fn)` closes over its arguments rather than declaring them, so the
541
- input is not knowable without running `fn`. Deterministic values (`ctx.now`,
542
- `ctx.uuid`) are pinned into `memoDelta`, so concurrent calls replay the same
543
- values after the engine merges the delta.
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
- "config": { "title": "Approve refund", "description": "refund of $40" } }
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-Bt-31WQT.js";
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-Bt-31WQT.js");
187
- const { findDuplicateOperationIds } = await import("./duplicate-ids-ClNLIwAz.js");
188
- const { findNestedDurableOperations } = await import("./nested-operations-Cpzs_PHo.js");
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 mappedStepTemplate(node) {
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
- return stepIdTemplate(body.arguments[0], parameters);
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 given = option(options, "description");
157
- const description = stringLiteral(given);
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
- ...description === void 0 ? {} : { description }
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
- const timestamp = numberLiteral(call.arguments[0]);
208
- if (timestamp === void 0) return unknown("Dynamic sleepUntil timestamps are not supported yet", parents);
209
- const options = readableOptions(call.arguments[1]);
210
- const stepId = durableStepId(call.arguments[1], options, defaultDurableId({
211
- kind: "sleepUntil",
212
- timestamp
213
- }));
214
- if (stepId === void 0) return unknown("Dynamic sleepUntil IDs are not supported yet", parents);
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: "sleep-until",
266
+ kind: method,
217
267
  stepId,
218
- config: { timestamp },
219
- label: `sleep until ${timestamp}`
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 template = mappedStepTemplate(argument);
242
- if (template !== void 0) return addNode({
243
- kind: "parallel",
244
- cardinality: "dynamic",
245
- operation: {
246
- kind: "step",
247
- stepIdTemplate: template
248
- },
249
- label: template
250
- }, parents);
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?: string;
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-CVoNE4Kn.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-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, _options) => durable("step", id, async () => 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
- now: (opts) => durable("now", opts?.id ?? defaultDurableId({ kind: "now" }), async () => Date.now(), void 0, opts?.id === void 0),
293
- uuid: (opts) => durable("uuid", opts?.id ?? defaultDurableId({ kind: "uuid" }), async () => crypto.randomUUID(), void 0, opts?.id === void 0),
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,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript } from "./graph-Bt-31WQT.js";
1
+ import { loadTypeScript } from "./graph-DW4JTyGa.js";
2
2
  //#region src/manifests/nested-operations.ts
3
3
  const durableMethods = [
4
4
  "step",
@@ -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-CVoNE4Kn.js";
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";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovable.dev/workflows-sdk",
3
- "version": "0.0.0-dev.15",
3
+ "version": "0.0.0-dev.17",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",