workflow 5.0.0-beta.8 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/README.md +68 -23
  2. package/dist/api-workflow.d.ts +3 -1
  3. package/dist/api-workflow.d.ts.map +1 -1
  4. package/dist/api-workflow.js +2 -1
  5. package/dist/api.d.ts +5 -4
  6. package/dist/api.d.ts.map +1 -1
  7. package/dist/api.js +6 -7
  8. package/dist/index.d.ts +1 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +6 -1
  11. package/dist/internal/builtins.d.ts +4 -4
  12. package/dist/internal/builtins.js +6 -6
  13. package/dist/internal/errors.d.ts +1 -1
  14. package/dist/internal/errors.d.ts.map +1 -1
  15. package/dist/internal/errors.js +2 -2
  16. package/dist/nest-builder.d.ts +2 -0
  17. package/dist/nest-builder.d.ts.map +1 -0
  18. package/dist/nest-builder.js +2 -0
  19. package/dist/nest-vercel-builder.d.ts +2 -0
  20. package/dist/nest-vercel-builder.d.ts.map +1 -0
  21. package/dist/nest-vercel-builder.js +2 -0
  22. package/dist/runtime.d.ts +2 -1
  23. package/dist/runtime.d.ts.map +1 -1
  24. package/dist/runtime.js +4 -1
  25. package/docs/advanced/dynamic-workflows.mdx +224 -0
  26. package/docs/ai/chat-session-modeling.mdx +176 -422
  27. package/docs/ai/defining-tools.mdx +6 -7
  28. package/docs/ai/human-in-the-loop.mdx +11 -11
  29. package/docs/ai/index.mdx +67 -72
  30. package/docs/ai/message-queueing.mdx +71 -110
  31. package/docs/ai/meta.json +1 -0
  32. package/docs/ai/resumable-streams.mdx +40 -28
  33. package/docs/ai/sleep-and-delays.mdx +10 -10
  34. package/docs/ai/streaming-updates-from-tools.mdx +6 -6
  35. package/docs/api-reference/index.mdx +25 -1
  36. package/docs/api-reference/meta.json +8 -0
  37. package/docs/api-reference/vitest/index.mdx +68 -15
  38. package/docs/api-reference/workflow/create-hook.mdx +166 -10
  39. package/docs/api-reference/workflow/create-webhook.mdx +16 -15
  40. package/docs/api-reference/workflow/define-hook.mdx +37 -33
  41. package/docs/api-reference/workflow/fatal-error.mdx +30 -8
  42. package/docs/api-reference/workflow/fetch.mdx +14 -10
  43. package/docs/api-reference/workflow/get-step-metadata.mdx +2 -2
  44. package/docs/api-reference/workflow/get-workflow-metadata.mdx +3 -3
  45. package/docs/api-reference/workflow/get-writable.mdx +7 -7
  46. package/docs/api-reference/workflow/index.mdx +4 -1
  47. package/docs/api-reference/workflow/retryable-error.mdx +1 -1
  48. package/docs/api-reference/workflow/set-attributes.mdx +63 -0
  49. package/docs/api-reference/workflow/sleep.mdx +4 -4
  50. package/docs/api-reference/workflow-ai/durable-agent.mdx +63 -101
  51. package/docs/api-reference/workflow-ai/index.mdx +5 -5
  52. package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx +67 -24
  53. package/docs/api-reference/workflow-api/get-hook-by-token.mdx +28 -12
  54. package/docs/api-reference/workflow-api/get-run.mdx +43 -8
  55. package/docs/api-reference/workflow-api/index.mdx +8 -9
  56. package/docs/api-reference/workflow-api/register-lifecycle-hooks.mdx +87 -0
  57. package/docs/api-reference/workflow-api/resume-hook.mdx +73 -12
  58. package/docs/api-reference/workflow-api/resume-webhook.mdx +11 -9
  59. package/docs/api-reference/workflow-api/start.mdx +107 -12
  60. package/docs/api-reference/workflow-astro/index.mdx +18 -0
  61. package/docs/api-reference/workflow-astro/meta.json +4 -0
  62. package/docs/api-reference/workflow-astro/workflow.mdx +45 -0
  63. package/docs/api-reference/workflow-errors/entity-conflict-error.mdx +4 -4
  64. package/docs/api-reference/workflow-errors/hook-conflict-error.mdx +60 -0
  65. package/docs/api-reference/workflow-errors/hook-force-claimed-error.mdx +70 -0
  66. package/docs/api-reference/workflow-errors/hook-not-found-error.mdx +8 -8
  67. package/docs/api-reference/workflow-errors/index.mdx +91 -0
  68. package/docs/api-reference/workflow-errors/meta.json +7 -0
  69. package/docs/api-reference/workflow-errors/precondition-failed-error.mdx +68 -0
  70. package/docs/api-reference/workflow-errors/run-expired-error.mdx +2 -2
  71. package/docs/api-reference/workflow-errors/run-not-supported-error.mdx +58 -0
  72. package/docs/api-reference/workflow-errors/step-not-registered-error.mdx +5 -5
  73. package/docs/api-reference/workflow-errors/throttle-error.mdx +2 -2
  74. package/docs/api-reference/workflow-errors/too-early-error.mdx +2 -2
  75. package/docs/api-reference/workflow-errors/workflow-error.mdx +52 -0
  76. package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx +5 -6
  77. package/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx +13 -6
  78. package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx +12 -5
  79. package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx +58 -0
  80. package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx +4 -4
  81. package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx +58 -0
  82. package/docs/api-reference/workflow-errors/workflow-world-error.mdx +8 -8
  83. package/docs/api-reference/workflow-globals.mdx +15 -11
  84. package/docs/api-reference/workflow-nest/configure-workflow-controller.mdx +37 -0
  85. package/docs/api-reference/workflow-nest/index.mdx +31 -0
  86. package/docs/api-reference/workflow-nest/meta.json +9 -0
  87. package/docs/api-reference/workflow-nest/nest-local-builder.mdx +64 -0
  88. package/docs/api-reference/workflow-nest/workflow-controller.mdx +46 -0
  89. package/docs/api-reference/workflow-nest/workflow-module.mdx +134 -0
  90. package/docs/api-reference/workflow-next/with-workflow.mdx +39 -17
  91. package/docs/api-reference/workflow-nitro/index.mdx +60 -0
  92. package/docs/api-reference/workflow-nuxt/index.mdx +48 -0
  93. package/docs/api-reference/workflow-observability/hydrate-data.mdx +35 -0
  94. package/docs/api-reference/workflow-observability/hydrate-resource-io.mdx +62 -0
  95. package/docs/api-reference/workflow-observability/index.mdx +62 -0
  96. package/docs/api-reference/workflow-observability/meta.json +11 -0
  97. package/docs/api-reference/workflow-observability/observability-revivers.mdx +50 -0
  98. package/docs/api-reference/workflow-observability/parse-class-name.mdx +41 -0
  99. package/docs/api-reference/workflow-observability/parse-step-name.mdx +40 -0
  100. package/docs/api-reference/workflow-observability/parse-workflow-name.mdx +55 -0
  101. package/docs/api-reference/workflow-runtime/create-world.mdx +39 -0
  102. package/docs/api-reference/workflow-runtime/get-world-handlers.mdx +44 -0
  103. package/docs/api-reference/{workflow-api → workflow-runtime}/get-world.mdx +11 -14
  104. package/docs/api-reference/workflow-runtime/health-check.mdx +51 -0
  105. package/docs/api-reference/workflow-runtime/index.mdx +41 -0
  106. package/docs/api-reference/workflow-runtime/meta.json +12 -0
  107. package/docs/api-reference/workflow-runtime/set-world.mdx +51 -0
  108. package/docs/api-reference/workflow-runtime/workflow-entrypoint.mdx +43 -0
  109. package/docs/api-reference/workflow-runtime/world/analytics.mdx +315 -0
  110. package/docs/api-reference/workflow-runtime/world/index.mdx +60 -0
  111. package/docs/api-reference/workflow-runtime/world/meta.json +4 -0
  112. package/docs/api-reference/workflow-runtime/world/queue.mdx +88 -0
  113. package/docs/api-reference/{workflow-api → workflow-runtime}/world/storage.mdx +104 -35
  114. package/docs/api-reference/{workflow-api → workflow-runtime}/world/streams.mdx +8 -8
  115. package/docs/api-reference/workflow-serde/index.mdx +1 -2
  116. package/docs/api-reference/workflow-serde/workflow-deserialize.mdx +3 -4
  117. package/docs/api-reference/workflow-serde/workflow-serialize.mdx +8 -8
  118. package/docs/api-reference/workflow-sveltekit/index.mdx +18 -0
  119. package/docs/api-reference/workflow-sveltekit/meta.json +4 -0
  120. package/docs/api-reference/workflow-sveltekit/workflow-plugin.mdx +42 -0
  121. package/docs/api-reference/workflow-vite/index.mdx +18 -0
  122. package/docs/api-reference/workflow-vite/meta.json +4 -0
  123. package/docs/api-reference/workflow-vite/workflow.mdx +48 -0
  124. package/docs/changelog/attributes-mvp.mdx +61 -46
  125. package/docs/changelog/batched-event-writes.mdx +79 -0
  126. package/docs/changelog/eager-processing.mdx +110 -436
  127. package/docs/changelog/index.mdx +4 -2
  128. package/docs/changelog/lazy-event-creation.md +127 -0
  129. package/docs/changelog/lazy-hook-resume.mdx +78 -0
  130. package/docs/changelog/meta.json +11 -1
  131. package/docs/changelog/resilient-resume.mdx +32 -0
  132. package/docs/changelog/resilient-start.mdx +33 -285
  133. package/docs/changelog/step-message-ownership.mdx +360 -0
  134. package/docs/changelog/turbo-mode.md +87 -0
  135. package/docs/comparisons/index.mdx +66 -0
  136. package/docs/comparisons/meta.json +11 -0
  137. package/docs/comparisons/workflow-sdk-vs-aws-agentcore.mdx +55 -0
  138. package/docs/comparisons/workflow-sdk-vs-aws-step-functions.mdx +111 -0
  139. package/docs/comparisons/workflow-sdk-vs-cloudflare-workflows.mdx +71 -0
  140. package/docs/comparisons/workflow-sdk-vs-inngest.mdx +102 -0
  141. package/docs/comparisons/workflow-sdk-vs-temporal.mdx +123 -0
  142. package/docs/comparisons/workflow-sdk-vs-trigger-dev.mdx +104 -0
  143. package/docs/configuration/build-and-diagnostics.mdx +79 -0
  144. package/docs/configuration/cli-and-web-ui.mdx +241 -0
  145. package/docs/configuration/framework-options.mdx +165 -0
  146. package/docs/configuration/index.mdx +32 -0
  147. package/docs/configuration/meta.json +12 -0
  148. package/docs/configuration/runtime-tuning.mdx +399 -0
  149. package/docs/configuration/worlds.mdx +315 -0
  150. package/docs/cookbook/advanced/child-workflows.mdx +33 -25
  151. package/docs/cookbook/advanced/publishing-libraries.mdx +65 -56
  152. package/docs/cookbook/advanced/serializable-steps.mdx +48 -68
  153. package/docs/cookbook/advanced/upgrading-workflows.mdx +35 -31
  154. package/docs/cookbook/agent-patterns/agent-cancellation.mdx +78 -60
  155. package/docs/cookbook/agent-patterns/durable-agent.mdx +23 -135
  156. package/docs/cookbook/agent-patterns/human-in-the-loop.mdx +180 -195
  157. package/docs/cookbook/common-patterns/batching.mdx +20 -14
  158. package/docs/cookbook/common-patterns/idempotency.mdx +41 -53
  159. package/docs/cookbook/common-patterns/rate-limiting.mdx +8 -4
  160. package/docs/cookbook/common-patterns/saga.mdx +23 -19
  161. package/docs/cookbook/common-patterns/scheduling.mdx +30 -22
  162. package/docs/cookbook/common-patterns/sequential-and-parallel.mdx +29 -25
  163. package/docs/cookbook/common-patterns/timeouts.mdx +26 -21
  164. package/docs/cookbook/common-patterns/webhooks.mdx +10 -6
  165. package/docs/cookbook/common-patterns/workflow-composition.mdx +27 -17
  166. package/docs/cookbook/index.mdx +22 -22
  167. package/docs/cookbook/integrations/ai-sdk.mdx +63 -48
  168. package/docs/cookbook/integrations/chat-sdk.mdx +46 -33
  169. package/docs/cookbook/integrations/sandbox.mdx +58 -45
  170. package/docs/deploying.mdx +106 -0
  171. package/docs/errors/abort-signal-timeout-in-workflow.mdx +16 -12
  172. package/docs/errors/corrupted-event-log.mdx +39 -18
  173. package/docs/errors/deployment-mismatch.mdx +71 -0
  174. package/docs/errors/fetch-in-workflow.mdx +15 -14
  175. package/docs/errors/hook-conflict.mdx +38 -11
  176. package/docs/errors/hook-force-claimed.mdx +96 -0
  177. package/docs/errors/index.mdx +24 -37
  178. package/docs/errors/node-js-module-in-workflow.mdx +9 -5
  179. package/docs/errors/replay-divergence.mdx +27 -0
  180. package/docs/errors/run-expired.mdx +85 -0
  181. package/docs/errors/runtime-decryption-failed.mdx +77 -0
  182. package/docs/errors/serialization-failed.mdx +44 -12
  183. package/docs/errors/start-invalid-workflow-function.mdx +9 -5
  184. package/docs/errors/step-executed-multiple-times.mdx +23 -0
  185. package/docs/errors/step-not-registered.mdx +6 -6
  186. package/docs/errors/timeout-in-workflow.mdx +12 -8
  187. package/docs/errors/webhook-invalid-respond-with-value.mdx +18 -18
  188. package/docs/errors/webhook-response-not-sent.mdx +20 -16
  189. package/docs/errors/workflow-not-registered.mdx +5 -5
  190. package/docs/foundations/cancellation.mdx +31 -32
  191. package/docs/foundations/errors-and-retries.mdx +54 -11
  192. package/docs/foundations/hooks.mdx +98 -35
  193. package/docs/foundations/idempotency.mdx +267 -12
  194. package/docs/foundations/index.mdx +1 -26
  195. package/docs/foundations/serialization.mdx +22 -22
  196. package/docs/foundations/starting-workflows.mdx +104 -30
  197. package/docs/foundations/streaming.mdx +108 -60
  198. package/docs/foundations/versioning.mdx +4 -4
  199. package/docs/foundations/workflows-and-steps.mdx +9 -9
  200. package/docs/getting-started/astro.mdx +22 -18
  201. package/docs/getting-started/express.mdx +15 -11
  202. package/docs/getting-started/fastify.mdx +15 -11
  203. package/docs/getting-started/hono.mdx +15 -11
  204. package/docs/getting-started/index.mdx +10 -3
  205. package/docs/getting-started/meta.json +3 -1
  206. package/docs/getting-started/nestjs.mdx +264 -21
  207. package/docs/getting-started/next.mdx +18 -14
  208. package/docs/getting-started/nitro.mdx +22 -18
  209. package/docs/getting-started/nuxt.mdx +15 -11
  210. package/docs/getting-started/python.mdx +190 -41
  211. package/docs/getting-started/react-router/index.mdx +33 -0
  212. package/docs/getting-started/react-router/meta.json +5 -0
  213. package/docs/getting-started/react-router/v7.mdx +237 -0
  214. package/docs/getting-started/react-router/v8.mdx +232 -0
  215. package/docs/getting-started/sveltekit.mdx +20 -16
  216. package/docs/getting-started/tanstack-start.mdx +17 -13
  217. package/docs/getting-started/vite.mdx +15 -11
  218. package/docs/how-it-works/cancellation.mdx +63 -63
  219. package/docs/how-it-works/code-transform.mdx +82 -66
  220. package/docs/how-it-works/encryption.mdx +30 -26
  221. package/docs/how-it-works/event-sourcing.mdx +132 -35
  222. package/docs/how-it-works/framework-integrations.mdx +96 -337
  223. package/docs/how-it-works/understanding-directives.mdx +22 -22
  224. package/docs/internal/index.mdx +6 -4
  225. package/docs/internal/meta.json +6 -1
  226. package/docs/internal/nitro-native-build.mdx +38 -0
  227. package/docs/internal/nitro-web-ui.mdx +24 -0
  228. package/docs/internal/serializable-abort-controller.mdx +7 -7
  229. package/docs/meta.json +4 -2
  230. package/docs/observability/attributes.mdx +136 -0
  231. package/docs/observability/index.mdx +32 -10
  232. package/docs/observability/lifecycle-hooks.mdx +95 -0
  233. package/docs/observability/meta.json +1 -1
  234. package/docs/observability/retention.mdx +95 -0
  235. package/docs/observability/tracing.mdx +124 -0
  236. package/docs/testing/index.mdx +120 -38
  237. package/docs/testing/server-based.mdx +10 -10
  238. package/docs/whats-new.mdx +190 -0
  239. package/docs/worlds/building-a-world.mdx +538 -0
  240. package/docs/worlds/local.mdx +129 -0
  241. package/docs/worlds/meta.json +10 -0
  242. package/docs/worlds/postgres.mdx +424 -0
  243. package/docs/worlds/upgrading-to-v5.mdx +162 -0
  244. package/docs/worlds/vercel.mdx +345 -0
  245. package/package.json +17 -14
  246. package/docs/api-reference/workflow-api/world/index.mdx +0 -58
  247. package/docs/api-reference/workflow-api/world/meta.json +0 -4
  248. package/docs/api-reference/workflow-api/world/observability.mdx +0 -164
  249. package/docs/api-reference/workflow-api/world/queue.mdx +0 -86
  250. package/docs/deploying/building-a-world.mdx +0 -251
  251. package/docs/deploying/index.mdx +0 -95
  252. package/docs/deploying/meta.json +0 -4
  253. package/docs/deploying/world/local-world.mdx +0 -84
  254. package/docs/deploying/world/meta.json +0 -4
  255. package/docs/deploying/world/postgres-world.mdx +0 -224
  256. package/docs/deploying/world/vercel-world.mdx +0 -181
  257. package/docs/migration-guides/index.mdx +0 -34
  258. package/docs/migration-guides/meta.json +0 -9
  259. package/docs/migration-guides/migrating-from-aws-step-functions.mdx +0 -358
  260. package/docs/migration-guides/migrating-from-inngest.mdx +0 -304
  261. package/docs/migration-guides/migrating-from-temporal.mdx +0 -313
  262. package/docs/migration-guides/migrating-from-trigger-dev.mdx +0 -328
@@ -1,164 +0,0 @@
1
- ---
2
- title: Observability Utilities
3
- description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
4
- type: reference
5
- summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
6
- prerequisites:
7
- - /docs/api-reference/workflow-api/get-world
8
- related:
9
- - /docs/api-reference/workflow-api/world/storage
10
- keywords:
11
- - workflow/observability
12
- - hydrateResourceIO
13
- - observabilityRevivers
14
- - parseStepName
15
- - parseWorkflowName
16
- - parseClassName
17
- - getEncryptionKeyForRun
18
- - hydrateResourceIOWithKey
19
- - data hydration
20
- - devalue deserialization
21
- - encryption decryption
22
- - display name parsing
23
- ---
24
-
25
- The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
26
-
27
- ## Import
28
-
29
- ```typescript lineNumbers
30
- import { // [!code highlight]
31
- hydrateResourceIO, // [!code highlight]
32
- observabilityRevivers, // [!code highlight]
33
- parseStepName, // [!code highlight]
34
- parseWorkflowName, // [!code highlight]
35
- parseClassName, // [!code highlight]
36
- } from "workflow/observability"; // [!code highlight]
37
- ```
38
-
39
- ## Data Hydration
40
-
41
- ### hydrateResourceIO()
42
-
43
- Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Required to display step input/output in your UI.
44
-
45
- ```typescript lineNumbers
46
- import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
47
-
48
- const step = await world.steps.get(runId, stepId);
49
- const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
50
- console.log(hydrated.input, hydrated.output);
51
- ```
52
-
53
- **Parameters:**
54
-
55
- | Parameter | Type | Description |
56
- |-----------|------|-------------|
57
- | `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
58
- | `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
59
-
60
- **Returns:** The resource with hydrated `input` and `output` fields.
61
-
62
- ### observabilityRevivers
63
-
64
- A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
65
-
66
- ## Name Parsing
67
-
68
- Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
69
-
70
- ### parseStepName()
71
-
72
- ```typescript lineNumbers
73
- import { parseStepName } from "workflow/observability"; // [!code highlight]
74
-
75
- const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
76
- // parsed?.shortName → "processPayment"
77
- // parsed?.moduleSpecifier → "./src/workflows/order"
78
- ```
79
-
80
- ### parseWorkflowName()
81
-
82
- ```typescript lineNumbers
83
- import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
84
-
85
- const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
86
- // parsed?.shortName → "processOrder"
87
- ```
88
-
89
- ### parseClassName()
90
-
91
- ```typescript lineNumbers
92
- import { parseClassName } from "workflow/observability"; // [!code highlight]
93
-
94
- const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
95
- // parsed?.shortName → "User"
96
- ```
97
-
98
- ## Encryption
99
-
100
- For workflows with encrypted step data, decrypt before hydrating.
101
-
102
- ### getEncryptionKeyForRun()
103
-
104
- Retrieve the encryption key used for a specific workflow run.
105
-
106
- {/* @expect-error:2305 */}
107
- ```typescript lineNumbers
108
- import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
109
-
110
- const key = await getEncryptionKeyForRun(runId); // [!code highlight]
111
- ```
112
-
113
- **Parameters:**
114
-
115
- | Parameter | Type | Description |
116
- |-----------|------|-------------|
117
- | `runId` | `string` | The workflow run ID |
118
-
119
- **Returns:** Encryption key for the run
120
-
121
- ### hydrateResourceIOWithKey()
122
-
123
- Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
124
-
125
- {/* @expect-error:2305,2724 */}
126
- ```typescript lineNumbers
127
- import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
128
-
129
- const key = await getEncryptionKeyForRun(runId); // [!code highlight]
130
- const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
131
- ```
132
-
133
- **Parameters:**
134
-
135
- | Parameter | Type | Description |
136
- |-----------|------|-------------|
137
- | `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
138
- | `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
139
-
140
- **Returns:** The resource with decrypted and hydrated `input` and `output` fields.
141
-
142
- ## Examples
143
-
144
- ### Parse Display Names for a Run's Steps
145
-
146
- ```typescript lineNumbers
147
- import { getWorld } from "workflow/runtime";
148
- import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
149
-
150
- const world = await getWorld();
151
- const run = await world.runs.get(runId, { resolveData: "none" });
152
- console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
153
-
154
- const steps = await world.steps.list({ runId, resolveData: "none" });
155
- for (const step of steps.data) {
156
- const parsed = parseStepName(step.stepName); // [!code highlight]
157
- console.log(` ${parsed?.shortName}: ${step.status}`); // [!code highlight]
158
- }
159
- ```
160
-
161
- ## Related
162
-
163
- - [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
164
- - [Serialization](/docs/foundations/serialization) — How workflow data is serialized
@@ -1,86 +0,0 @@
1
- ---
2
- title: Queue
3
- description: Low-level queue interface for dispatching workflow and step invocations.
4
- type: reference
5
- summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
6
- prerequisites:
7
- - /docs/api-reference/workflow-api/get-world
8
- related:
9
- - /docs/api-reference/workflow-api/start
10
- - /docs/foundations/starting-workflows
11
- keywords:
12
- - world.queue
13
- - getDeploymentId
14
- - queue
15
- - createQueueHandler
16
- - ValidQueueName
17
- - queue dispatch
18
- ---
19
-
20
- Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
21
-
22
- <Callout type="warn">
23
- These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
24
- </Callout>
25
-
26
- ## Import
27
-
28
- ```typescript lineNumbers
29
- import { getWorld } from "workflow/runtime";
30
-
31
- const world = await getWorld(); // [!code highlight]
32
- // Queue methods are called directly on world — e.g. world.queue()
33
- ```
34
-
35
- ## Methods
36
-
37
- ### getDeploymentId()
38
-
39
- Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
40
-
41
- ```typescript lineNumbers
42
- const deploymentId = await world.getDeploymentId(); // [!code highlight]
43
- ```
44
-
45
- **Returns:** `string` — The current deployment ID
46
-
47
- ### queue()
48
-
49
- Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
50
-
51
- ```typescript lineNumbers
52
- const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
53
- ```
54
-
55
- **Parameters:**
56
-
57
- | Parameter | Type | Description |
58
- |-----------|------|-------------|
59
- | `queueName` | `ValidQueueName` | The queue name (branded string) |
60
- | `message` | `QueuePayload` | Internal SDK payload |
61
- | `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
62
-
63
- **Returns:** `{ messageId: MessageId | null }`
64
-
65
- ### createQueueHandler()
66
-
67
- Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
68
-
69
- ```typescript lineNumbers
70
- const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
71
- ```
72
-
73
- **Parameters:**
74
-
75
- | Parameter | Type | Description |
76
- |-----------|------|-------------|
77
- | `prefix` | `QueuePrefix` | Queue name prefix to match |
78
- | `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
79
-
80
- **Returns:** `(req: Request) => Promise<Response>`
81
-
82
- ## Related
83
-
84
- - [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
85
- - [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
86
- - [Storage](/docs/api-reference/workflow-api/world/storage) — Create events that trigger queue dispatch
@@ -1,251 +0,0 @@
1
- ---
2
- title: Building a World
3
- description: Implement the World interface to run workflows on any custom infrastructure.
4
- type: guide
5
- summary: Build a custom World adapter to run workflows on your own infrastructure.
6
- prerequisites:
7
- - /docs/deploying
8
- - /docs/foundations/workflows-and-steps
9
- related:
10
- - /docs/deploying/world/local-world
11
- - /docs/deploying/world/postgres-world
12
- - /docs/deploying/world/vercel-world
13
- ---
14
-
15
- A **World** is the abstraction that allows workflows to run on any infrastructure. It handles workflow storage, step execution queuing, and data streaming. This guide explains the World interface and how to implement your own.
16
-
17
- <Callout>
18
- Before building a custom World, check the [Worlds Ecosystem](/worlds) page — there may already be a community implementation for your infrastructure.
19
- </Callout>
20
-
21
- <Callout type="info">
22
- **Reference Implementation:** The [Postgres World source code](https://github.com/vercel/workflow/tree/main/packages/world-postgres) is a production-ready example of how to implement the World interface with a database backend and graphile-worker for queuing.
23
- </Callout>
24
-
25
- ## What is a World?
26
-
27
- A World connects workflows to the infrastructure that powers them. The World interface abstracts three core responsibilities:
28
-
29
- 1. **Storage** — Persisting workflow runs, steps, hooks, and the event log
30
- 2. **Queue** — Enqueuing and processing workflow and step invocations
31
- 3. **Streamer** — Managing real-time data streams between workflows and clients
32
-
33
- {/* @skip-typecheck - interface definition, not runnable code */}
34
- ```typescript
35
- interface World extends Storage, Queue, Streamer {
36
- start?(): Promise<void>;
37
- close?(): Promise<void>;
38
- getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
39
- getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
40
- }
41
- ```
42
-
43
- The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
44
-
45
- ## The Event Log Model
46
-
47
- Workflow storage is built on an **append-only event log**. All state changes happen through events — you never modify runs, steps, or hooks directly. Instead, you create events that update the materialized state.
48
-
49
- Events fall into three categories: run lifecycle events, step lifecycle events, and hook lifecycle events. See the [Event Sourcing](/docs/how-it-works/event-sourcing) documentation for a complete list of event types and their semantics.
50
-
51
- ## Storage Interface
52
-
53
- The Storage interface provides read access to materialized entities and write access through events:
54
-
55
- {/* @skip-typecheck - interface definition, not runnable code */}
56
- ```typescript
57
- interface Storage {
58
- runs: {
59
- get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun>;
60
- list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun>>;
61
- };
62
-
63
- steps: {
64
- get(runId: string | undefined, stepId: string, params?: GetStepParams): Promise<Step>;
65
- list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step>>;
66
- };
67
-
68
- events: {
69
- // Create a new workflow run (runId may be client-provided or null for server generation)
70
- create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
71
-
72
- // Create an event for an existing run
73
- create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
74
-
75
- list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
76
- listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
77
- };
78
-
79
- hooks: {
80
- get(hookId: string, params?: GetHookParams): Promise<Hook>;
81
- getByToken(token: string, params?: GetHookParams): Promise<Hook>;
82
- list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
83
- };
84
- }
85
- ```
86
-
87
- ### Key Implementation Details
88
-
89
- **Event Creation:** When `events.create()` is called, your implementation must:
90
- 1. Persist the event to the event log
91
- 2. Atomically update the affected entity (run, step, or hook)
92
- 3. Return both the created event and the updated entity
93
-
94
- **Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
95
-
96
- **Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead and include the active hook owner's run ID as `eventData.conflictingRunId`.
97
-
98
- **Automatic Hook Disposal:** When a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`), automatically dispose of all associated hooks to release tokens for reuse.
99
-
100
- ## Queue Interface
101
-
102
- The Queue interface handles asynchronous execution of workflows and steps:
103
-
104
- {/* @skip-typecheck - interface definition, not runnable code */}
105
- ```typescript
106
- interface Queue {
107
- getDeploymentId(): Promise<string>;
108
-
109
- queue(
110
- queueName: ValidQueueName,
111
- message: QueuePayload,
112
- opts?: QueueOptions
113
- ): Promise<{ messageId: MessageId }>;
114
-
115
- createQueueHandler(
116
- queueNamePrefix: QueuePrefix,
117
- handler: (message: unknown, meta: { attempt: number; queueName: ValidQueueName; messageId: MessageId }) => Promise<void | { timeoutSeconds: number }>
118
- ): (req: Request) => Promise<Response>;
119
- }
120
- ```
121
-
122
- ### Queue Names
123
-
124
- Queue names follow a specific pattern:
125
- - `__wkf_workflow_<name>` — For workflow invocations
126
- - `__wkf_step_<name>` — For step invocations
127
-
128
- ### Message Payloads
129
-
130
- Two types of messages flow through queues:
131
-
132
- **Workflow Invocations:**
133
- {/* @skip-typecheck - interface definition, not runnable code */}
134
- ```typescript
135
- interface WorkflowInvokePayload {
136
- runId: string;
137
- traceCarrier?: Record<string, string>; // OpenTelemetry context
138
- requestedAt?: Date;
139
- }
140
- ```
141
-
142
- **Step Invocations:**
143
- {/* @skip-typecheck - interface definition, not runnable code */}
144
- ```typescript
145
- interface StepInvokePayload {
146
- workflowName: string;
147
- workflowRunId: string;
148
- workflowStartedAt: number;
149
- stepId: string;
150
- traceCarrier?: Record<string, string>;
151
- requestedAt?: Date;
152
- }
153
- ```
154
-
155
- ### Implementation Considerations
156
-
157
- - Messages must be delivered at-least-once
158
- - Support configurable retry policies
159
- - Track attempt counts for observability
160
- - Implement idempotency using the `idempotencyKey` option when provided
161
-
162
- ## Streamer Interface
163
-
164
- The Streamer interface enables real-time data streaming:
165
-
166
- {/* @skip-typecheck - interface definition, not runnable code */}
167
- ```typescript
168
- interface Streamer {
169
- streamFlushIntervalMs?: number;
170
-
171
- streams: {
172
- write(
173
- runId: string,
174
- name: string,
175
- chunk: string | Uint8Array
176
- ): Promise<void>;
177
-
178
- writeMulti?(
179
- runId: string,
180
- name: string,
181
- chunks: (string | Uint8Array)[]
182
- ): Promise<void>;
183
-
184
- close(runId: string, name: string): Promise<void>;
185
-
186
- get(
187
- runId: string,
188
- name: string,
189
- startIndex?: number
190
- ): Promise<ReadableStream<Uint8Array>>;
191
-
192
- list(runId: string): Promise<string[]>;
193
-
194
- /** Paginated snapshot of stream chunks. */
195
- getChunks(
196
- runId: string,
197
- name: string,
198
- options?: { limit?: number; cursor?: string }
199
- ): Promise<{
200
- data: { index: number; data: Uint8Array }[];
201
- cursor: string | null;
202
- hasMore: boolean;
203
- done: boolean;
204
- }>;
205
-
206
- /** Lightweight metadata: tail index and completion flag. */
207
- getInfo(
208
- runId: string,
209
- name: string
210
- ): Promise<{ tailIndex: number; done: boolean }>;
211
- };
212
- }
213
- ```
214
-
215
- Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
216
- `writeMulti()` is an optional optimization for batching multiple writes.
217
-
218
- `getChunks` returns a paginated snapshot of currently available chunks (unlike `get` which returns a live `ReadableStream` that waits for new chunks). `getInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
219
-
220
- ## Reference Implementations
221
-
222
- Study these implementations for guidance:
223
-
224
- - **[Local World](https://github.com/vercel/workflow/tree/main/packages/world-local)** — Filesystem-based, great for understanding the basics
225
- - **[Postgres World](https://github.com/vercel/workflow/tree/main/packages/world-postgres)** — Database-backed with graphile-worker for queuing
226
-
227
- ## Testing Your World
228
-
229
- Workflow SDK includes an E2E test suite that validates World implementations. Once your World is published to npm:
230
-
231
- 1. Add your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
232
- 2. Open a PR to the Workflow repository
233
- 3. CI will automatically run the E2E test suite against your implementation
234
-
235
- Your world will then appear on the [Worlds Ecosystem](/worlds) page with its compatibility status and performance benchmarks.
236
-
237
- ## Publishing Your World
238
-
239
- 1. **Package your World** — Export a default World instance from your package
240
- 2. **Publish to npm** — Publish your package to npm
241
- 3. **Add to the manifest** — Submit a PR adding your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
242
- 4. **Document configuration** — Clearly document any required environment variables
243
-
244
- ```json
245
- // worlds-manifest.json entry
246
- {
247
- "package": "your-world-package",
248
- "repository": "https://github.com/you/your-world",
249
- "docs": "https://github.com/you/your-world#readme"
250
- }
251
- ```
@@ -1,95 +0,0 @@
1
- ---
2
- title: Deploying
3
- icon: Rocket
4
- description: Deploy workflows locally, on Vercel, or anywhere using pluggable World adapters.
5
- type: overview
6
- summary: Learn how to deploy workflows to different environments using World adapters.
7
- related:
8
- - /docs/deploying/world/local-world
9
- - /docs/deploying/world/postgres-world
10
- - /docs/deploying/world/vercel-world
11
- - /docs/deploying/building-a-world
12
- ---
13
-
14
- Workflows are designed to be highly portable. The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds** — pluggable adapters that handle storage, queuing, and communication.
15
-
16
- ## Local Development
17
-
18
- During local development, workflows automatically use the **Local World** — no configuration required. The Local World stores workflow data in a `.workflow-data/` directory and processes steps synchronously, making it perfect for development and testing.
19
-
20
- ```bash
21
- # Just run your dev server - workflows work out of the box
22
- npm run dev
23
- ```
24
-
25
- You can inspect local workflow data using the CLI:
26
-
27
- ```bash
28
- npx workflow inspect runs
29
- ```
30
-
31
- <Callout>
32
- Learn more about the [Local World](/worlds/local) configuration and internals.
33
- </Callout>
34
-
35
- ## Deploying to Vercel
36
-
37
- The easiest way to deploy workflows to production is on Vercel. When you deploy to Vercel, workflows automatically use the **Vercel World** — again, with zero configuration.
38
-
39
- The Vercel World provides:
40
-
41
- - **Durable storage** - Workflow state persists across function invocations
42
- - **Managed queuing** - Steps are processed reliably with automatic retries
43
- - **Automatic scaling** - Workflows scale with your application
44
- - **Built-in observability** - View workflow runs in the Vercel dashboard
45
-
46
- Simply deploy your application:
47
-
48
- ```bash
49
- vercel deploy
50
- ```
51
-
52
- <FluidComputeCallout />
53
-
54
- <Callout>
55
- Learn more about the [Vercel World](/worlds/vercel) and its capabilities.
56
- </Callout>
57
-
58
- ## Self-Hosting & Other Providers
59
-
60
- For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own.
61
-
62
- <Cards>
63
- <Card title="Explore Worlds" href="/worlds">
64
- Browse official and community World implementations with compatibility status and performance benchmarks.
65
- </Card>
66
- <Card title="Build Your Own" href="/docs/deploying/building-a-world">
67
- Learn how to implement a custom World for your infrastructure.
68
- </Card>
69
- </Cards>
70
-
71
- ### Using a Third-Party World
72
-
73
- To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
74
-
75
- ```bash
76
- export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
77
- # Plus any world-specific configuration
78
- export DATABASE_URL=postgres://...
79
- ```
80
-
81
- Each World may have its own configuration requirements — refer to the specific World's documentation for details.
82
-
83
- ## Observability
84
-
85
- The [Observability tools](/docs/observability) work with any World backend. By default they connect to your local environment, but can be configured to inspect remote deployments:
86
-
87
- ```bash
88
- # Inspect local workflows
89
- npx workflow inspect runs
90
-
91
- # Inspect remote workflows
92
- npx workflow inspect runs --backend @workflow/world-postgres
93
- ```
94
-
95
- Learn more about [Observability](/docs/observability) tools.
@@ -1,4 +0,0 @@
1
- {
2
- "title": "Deploying",
3
- "pages": ["...deploying", "building-a-world"]
4
- }
@@ -1,84 +0,0 @@
1
- ---
2
- title: Local World
3
- description: Zero-config world bundled with Workflow for local development. No external services required.
4
- type: integration
5
- summary: Set up the Local World for zero-config workflow development on your machine.
6
- prerequisites:
7
- - /docs/deploying
8
- related:
9
- - /docs/deploying/world/postgres-world
10
- - /docs/deploying/world/vercel-world
11
- ---
12
-
13
- The Local World is bundled with `workflow` and used automatically during local development. No installation or configuration required.
14
-
15
- To explicitly use the local world in any environment, set the environment variable:
16
-
17
- ```bash
18
- WORKFLOW_TARGET_WORLD=local
19
- ```
20
-
21
- ## Observability
22
-
23
- The `workflow` CLI uses the local world by default. Running these commands inside your workflow project will show your local development workflows:
24
-
25
- ```bash
26
- # List recent workflow runs
27
- npx workflow inspect runs
28
-
29
- # Launch the web UI
30
- npx workflow web
31
- ```
32
-
33
- Learn more in the [Observability](/docs/observability) documentation.
34
-
35
- ## Testing & Compatibility
36
-
37
- <WorldTestingPerformance />
38
-
39
- ## Configuration
40
-
41
- The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createLocalWorld()`.
42
-
43
- ### `WORKFLOW_LOCAL_DATA_DIR`
44
-
45
- Directory for storing workflow data as JSON files. Default: `.workflow-data/`
46
-
47
- ### `PORT`
48
-
49
- The application dev server port. Used to enqueue steps and workflows. Default: auto-detected
50
-
51
- ### `WORKFLOW_LOCAL_BASE_URL`
52
-
53
- Full base URL override for HTTPS or custom hostnames. Default: `http://localhost:{port}`
54
-
55
- Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected
56
-
57
- ### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
58
-
59
- Maximum number of concurrent queue workers. Default: `100`
60
-
61
- ### Programmatic configuration
62
-
63
- {/* @skip-typecheck: incomplete code sample */}
64
- ```typescript title="workflow.config.ts" lineNumbers
65
- import { createLocalWorld } from "@workflow/world-local";
66
-
67
- const world = createLocalWorld({
68
- dataDir: "./custom-workflow-data",
69
- port: 5173,
70
- // baseUrl overrides port if set
71
- baseUrl: "https://local.example.com:3000",
72
- });
73
- ```
74
-
75
- ## Limitations
76
-
77
- The local world is designed for development, not production:
78
-
79
- - **In-memory queue** - Steps are queued in memory and do not persist across server restarts
80
- - **Filesystem storage** - Data is stored in local JSON files
81
- - **Single instance** - Cannot handle distributed deployments
82
- - **No authentication** - Suitable only for local development
83
-
84
- For production deployments, use the [Vercel World](/worlds/vercel) or [Postgres World](/worlds/postgres).
@@ -1,4 +0,0 @@
1
- {
2
- "title": "World",
3
- "pages": ["local-world", "vercel-world", "postgres-world"]
4
- }