workflow 4.2.0-beta.73 → 4.2.0-beta.75

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 (56) hide show
  1. package/README.md +6 -6
  2. package/docs/ai/defining-tools.mdx +2 -2
  3. package/docs/ai/human-in-the-loop.mdx +1 -1
  4. package/docs/ai/index.mdx +8 -8
  5. package/docs/ai/resumable-streams.mdx +1 -1
  6. package/docs/ai/sleep-and-delays.mdx +2 -2
  7. package/docs/ai/streaming-updates-from-tools.mdx +1 -1
  8. package/docs/api-reference/index.mdx +9 -3
  9. package/docs/api-reference/meta.json +10 -1
  10. package/docs/api-reference/workflow/create-webhook.mdx +4 -0
  11. package/docs/api-reference/workflow/index.mdx +2 -2
  12. package/docs/api-reference/workflow-ai/durable-agent.mdx +1 -1
  13. package/docs/api-reference/workflow-api/get-world.mdx +33 -157
  14. package/docs/api-reference/workflow-api/index.mdx +3 -0
  15. package/docs/api-reference/workflow-api/world/events.mdx +227 -0
  16. package/docs/api-reference/workflow-api/world/hooks.mdx +181 -0
  17. package/docs/api-reference/workflow-api/world/index.mdx +67 -0
  18. package/docs/api-reference/workflow-api/world/meta.json +12 -0
  19. package/docs/api-reference/workflow-api/world/observability.mdx +289 -0
  20. package/docs/api-reference/workflow-api/world/queue.mdx +127 -0
  21. package/docs/api-reference/workflow-api/world/runs.mdx +223 -0
  22. package/docs/api-reference/workflow-api/world/steps.mdx +216 -0
  23. package/docs/api-reference/workflow-api/world/streams.mdx +152 -0
  24. package/docs/api-reference/workflow-globals.mdx +102 -0
  25. package/docs/api-reference/workflow-next/index.mdx +1 -1
  26. package/docs/api-reference/workflow-serde/index.mdx +2 -2
  27. package/docs/changelog/index.mdx +2 -2
  28. package/docs/deploying/building-a-world.mdx +1 -1
  29. package/docs/deploying/world/vercel-world.mdx +20 -13
  30. package/docs/errors/index.mdx +1 -1
  31. package/docs/errors/node-js-module-in-workflow.mdx +1 -1
  32. package/docs/errors/serialization-failed.mdx +1 -1
  33. package/docs/errors/start-invalid-workflow-function.mdx +3 -3
  34. package/docs/foundations/errors-and-retries.mdx +1 -1
  35. package/docs/foundations/hooks.mdx +5 -1
  36. package/docs/foundations/serialization.mdx +2 -2
  37. package/docs/foundations/streaming.mdx +3 -2
  38. package/docs/foundations/workflows-and-steps.mdx +2 -2
  39. package/docs/getting-started/astro.mdx +5 -5
  40. package/docs/getting-started/express.mdx +5 -5
  41. package/docs/getting-started/fastify.mdx +5 -5
  42. package/docs/getting-started/hono.mdx +5 -5
  43. package/docs/getting-started/nestjs.mdx +5 -5
  44. package/docs/getting-started/next.mdx +5 -5
  45. package/docs/getting-started/nitro.mdx +5 -5
  46. package/docs/getting-started/nuxt.mdx +5 -5
  47. package/docs/getting-started/sveltekit.mdx +5 -5
  48. package/docs/getting-started/vite.mdx +5 -5
  49. package/docs/how-it-works/code-transform.mdx +6 -6
  50. package/docs/how-it-works/encryption.mdx +3 -3
  51. package/docs/how-it-works/event-sourcing.mdx +5 -5
  52. package/docs/how-it-works/framework-integrations.mdx +9 -9
  53. package/docs/how-it-works/understanding-directives.mdx +11 -11
  54. package/docs/observability/index.mdx +5 -5
  55. package/docs/testing/index.mdx +4 -4
  56. package/package.json +12 -12
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  title: Framework Integrations
3
- description: Guide for framework authors to integrate Workflow DevKit with custom frameworks or runtimes.
3
+ description: Guide for framework authors to integrate Workflow SDK with custom frameworks or runtimes.
4
4
  type: guide
5
- summary: Build a custom framework integration using the Workflow DevKit compiler and runtime.
5
+ summary: Build a custom framework integration using the Workflow SDK compiler and runtime.
6
6
  prerequisites:
7
7
  - /docs/foundations/workflows-and-steps
8
8
  related:
@@ -10,13 +10,13 @@ related:
10
10
  ---
11
11
 
12
12
  <Callout>
13
- **For users:** If you just want to use Workflow DevKit with an existing framework, check out the [Getting Started](/docs/getting-started) guide instead. This page is for framework authors who want to integrate Workflow DevKit with their framework or runtime.
13
+ **For users:** If you just want to use Workflow SDK with an existing framework, check out the [Getting Started](/docs/getting-started) guide instead. This page is for framework authors who want to integrate Workflow SDK with their framework or runtime.
14
14
  </Callout>
15
15
 
16
- This guide walks you through building a framework integration for Workflow DevKit using Bun as a concrete example. The same principles apply to any JavaScript runtime (Node.js, Deno, Cloudflare Workers, etc.).
16
+ This guide walks you through building a framework integration for Workflow SDK using Bun as a concrete example. The same principles apply to any JavaScript runtime (Node.js, Deno, Cloudflare Workers, etc.).
17
17
 
18
18
  <Callout type="info">
19
- **Prerequisites:** Before building a framework integration, we recommend reading [How the Directives Work](/docs/how-it-works/code-transform) to understand the transformation system that powers Workflow DevKit.
19
+ **Prerequisites:** Before building a framework integration, we recommend reading [How the Directives Work](/docs/how-it-works/code-transform) to understand the transformation system that powers Workflow SDK.
20
20
  </Callout>
21
21
 
22
22
  ## What You'll Build
@@ -46,7 +46,7 @@ flowchart TD
46
46
  style J fill:#a78bfa,stroke:#8b5cf6,color:#000
47
47
  ```
48
48
 
49
- The purple boxes are what you implement—everything else is provided by Workflow DevKit.
49
+ The purple boxes are what you implement—everything else is provided by Workflow SDK.
50
50
 
51
51
  ## Example: Bun Integration
52
52
 
@@ -259,7 +259,7 @@ class MyFrameworkBuilder extends BaseBuilder {
259
259
  }
260
260
  ```
261
261
 
262
- If your framework supports virtual server routes and dev mode watching, make sure to adapt accordingly. Please open a PR to the Workflow DevKit if the base builder class is missing necessary functionality.
262
+ If your framework supports virtual server routes and dev mode watching, make sure to adapt accordingly. Please open a PR to the Workflow SDK if the base builder class is missing necessary functionality.
263
263
 
264
264
  Hook into your framework's build:
265
265
 
@@ -341,8 +341,8 @@ const server = Bun.serve({
341
341
  ```
342
342
 
343
343
  Production framework integrations should handle this routing in the plugin instead of leaving it to the user, and this depends on each framework's unique implementaiton.
344
- Check the Workflow DevKit source code for examples of production framework implementations.
345
- In the future, the Workflow DevKit will emit more routes under the `.well-known/workflow` namespace.
344
+ Check the Workflow SDK source code for examples of production framework implementations.
345
+ In the future, the Workflow SDK will emit more routes under the `.well-known/workflow` namespace.
346
346
 
347
347
  ## Security
348
348
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Understanding Directives
3
- description: Explore how JavaScript directives enable the Workflow DevKit's durable execution model.
3
+ description: Explore how JavaScript directives enable the Workflow SDK's durable execution model.
4
4
  type: conceptual
5
5
  summary: Explore the design decisions behind "use workflow" and "use step" directives.
6
6
  prerequisites:
@@ -12,18 +12,18 @@ related:
12
12
  import { File, Folder, Files } from "fumadocs-ui/components/files";
13
13
 
14
14
  <Callout>
15
- This guide explores how JavaScript directives enable the Workflow DevKit's execution model. For getting started with workflows, see the [getting started](/docs/getting-started) guides for your framework.
15
+ This guide explores how JavaScript directives enable the Workflow SDK's execution model. For getting started with workflows, see the [getting started](/docs/getting-started) guides for your framework.
16
16
  </Callout>
17
17
 
18
18
  The Workflow Development Kit uses JavaScript directives (`"use workflow"` and `"use step"`) as the foundation for its durable execution model. Directives provide the compile-time semantic boundary necessary for workflows to suspend, resume, and maintain deterministic behavior across replays.
19
19
 
20
20
  This page explores how directives enable this execution model and the design principles that led us here.
21
21
 
22
- To understand how directives work, let's first understand what workflows and steps are in the Workflow DevKit.
22
+ To understand how directives work, let's first understand what workflows and steps are in the Workflow SDK.
23
23
 
24
24
  ## Workflows and Steps Primer
25
25
 
26
- The Workflow DevKit has two types of functions:
26
+ The Workflow SDK has two types of functions:
27
27
 
28
28
  **Step functions** are side-effecting operations with full Node.js runtime access. Think of them like named RPC calls - they run once, their result is persisted, and they can be [retried on failure](/docs/foundations/errors-and-retries):
29
29
 
@@ -60,7 +60,7 @@ export async function onboardUser(userId: string) {
60
60
  - **If already executed:** Returns the cached result immediately from the event log
61
61
  - **If not yet executed:** Suspends the workflow, enqueues the step for background execution, and resumes later with the result
62
62
 
63
- This replay mechanism requires deterministic code. If `Math.random()` weren't seeded, the first execution might return `0.7` (sending the email) but replay might return `0.3` (skipping it), thus breaking resumption. The Workflow DevKit sandbox provides seeded `Math.random()` and `Date` to ensure consistent behavior across replays.
63
+ This replay mechanism requires deterministic code. If `Math.random()` weren't seeded, the first execution might return `0.7` (sending the email) but replay might return `0.3` (skipping it), thus breaking resumption. The Workflow SDK sandbox provides seeded `Math.random()` and `Date` to ensure consistent behavior across replays.
64
64
 
65
65
  <Callout>
66
66
  For a deeper dive into workflows and steps, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
@@ -85,11 +85,11 @@ JavaScript directives have precedent for changing execution semantics within a d
85
85
 
86
86
  - `"use strict"` (introduced in ECMAScript 5 in 2009, TC39-standardized) changes language rules to make the runtime faster, safer, and more predictable.
87
87
  - `"use client"` and `"use server"` (introduced by [React Server Components](https://react.dev/reference/rsc/server-components)) define an explicit boundary of "where" code gets executed - client-side browser JavaScript vs server-side Node.js.
88
- - `"use workflow"` (introduced by the Workflow DevKit) defines both "where" code runs (in a deterministic sandbox environment) and "how" it runs (deterministic, resumable, sandboxed execution semantics).
88
+ - `"use workflow"` (introduced by the Workflow SDK) defines both "where" code runs (in a deterministic sandbox environment) and "how" it runs (deterministic, resumable, sandboxed execution semantics).
89
89
 
90
90
  Directives provide a build-time contract.
91
91
 
92
- When the Workflow DevKit sees `"use workflow"`, it:
92
+ When the Workflow SDK sees `"use workflow"`, it:
93
93
 
94
94
  - Bundles the workflow and its dependencies into code that can be run in a sandbox
95
95
  - Restricts access to Node.js APIs in that sandbox
@@ -99,7 +99,7 @@ When the Workflow DevKit sees `"use workflow"`, it:
99
99
  In addition to being important to the compiler, `"use workflow"` explicitly signals to the developer that you are entering a different execution mode.
100
100
 
101
101
  <Callout type="info">
102
- The `"use workflow"` directive is also used by the Language Server Plugin shipped with Workflow DevKit to provide IntelliSense to your IDE. Check the [getting started instructions](/docs/getting-started) for your framework for details on setting up the Language Server Plugin.
102
+ The `"use workflow"` directive is also used by the Language Server Plugin shipped with Workflow SDK to provide IntelliSense to your IDE. Check the [getting started instructions](/docs/getting-started) for your framework for details on setting up the Language Server Plugin.
103
103
  </Callout>
104
104
 
105
105
  But we didn't get here immediately. This took some discovery to arrive at:
@@ -298,7 +298,7 @@ Different frameworks and developers have strong opinions about project structure
298
298
 
299
299
  **2. No support for publishable, reusable functions**
300
300
 
301
- We want developers to be able to publish libraries to npm that include step and workflow directives. Ideally, logic that is isomorphic so it could be used with and without Workflow DevKit. File system conventions made this impossible.
301
+ We want developers to be able to publish libraries to npm that include step and workflow directives. Ideally, logic that is isomorphic so it could be used with and without Workflow SDK. File system conventions made this impossible.
302
302
 
303
303
  **3. Migration and code reuse became difficult**
304
304
 
@@ -375,7 +375,7 @@ class MyWorkflow {
375
375
  }
376
376
  ```
377
377
 
378
- The compiler could transform both to be equivalent to WDK's directive approach:
378
+ The compiler could transform both to be equivalent to Workflow SDK's directive approach:
379
379
 
380
380
  ```typescript lineNumbers
381
381
  export const processOrder = async (orderId: string) => {
@@ -461,7 +461,7 @@ export async function badWorkflow() {
461
461
  }
462
462
  ```
463
463
 
464
- In fact, Workflow DevKit will throw an error that links to this error page: [Node.js module in workflow](/docs/errors/node-js-module-in-workflow)
464
+ In fact, Workflow SDK will throw an error that links to this error page: [Node.js module in workflow](/docs/errors/node-js-module-in-workflow)
465
465
 
466
466
  **3. No closure ambiguity**
467
467
 
@@ -10,7 +10,7 @@ related:
10
10
  - /docs/how-it-works/encryption
11
11
  ---
12
12
 
13
- Workflow DevKit provides powerful tools to inspect, monitor, and debug your workflows through the CLI and Web UI. These tools allow you to inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
13
+ Workflow SDK provides powerful tools to inspect, monitor, and debug your workflows through the CLI and Web UI. These tools allow you to inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
14
14
 
15
15
  ## Quick Start
16
16
 
@@ -18,7 +18,7 @@ Workflow DevKit provides powerful tools to inspect, monitor, and debug your work
18
18
  npx workflow
19
19
  ```
20
20
 
21
- The CLI comes pre-installed with the Workflow DevKit and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will install it globally, or use the local installed version if available.
21
+ The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will install it globally, or use the local installed version if available.
22
22
 
23
23
  Get started inspecting your local workflows:
24
24
 
@@ -32,7 +32,7 @@ npx workflow inspect runs
32
32
 
33
33
  ## Web UI
34
34
 
35
- Workflow DevKit ships with a local web UI for inspecting your workflows. The CLI
35
+ Workflow SDK ships with a local web UI for inspecting your workflows. The CLI
36
36
  will locally serve the Web UI when using the `--web` flag.
37
37
 
38
38
  ```bash
@@ -40,11 +40,11 @@ will locally serve the Web UI when using the `--web` flag.
40
40
  npx workflow inspect runs --web
41
41
  ```
42
42
 
43
- ![Workflow DevKit Web UI](/o11y-ui.png)
43
+ ![Workflow SDK Web UI](/o11y-ui.png)
44
44
 
45
45
  ## Backends
46
46
 
47
- The Workflow DevKit CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
47
+ The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
48
48
  CLI will find the data in your `.next/workflow-data/` directory.
49
49
 
50
50
  If you're deploying workflows to a production environment, but want to inspect the data by using the CLI, you can specify the world you are using by setting the `--backend` flag to your world's name or package name, e.g. `vercel`.
@@ -3,7 +3,7 @@ title: Testing
3
3
  description: Unit test individual steps and integration test entire workflows using Vitest.
4
4
  ---
5
5
 
6
- Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow DevKit also provides a Vitest plugin that runs full workflows in-process — no running server required.
6
+ Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow SDK also provides a Vitest plugin that runs full workflows in-process — no running server required.
7
7
 
8
8
  This guide covers two approaches:
9
9
 
@@ -356,7 +356,7 @@ For advanced setups that require a running server (e.g. testing against your act
356
356
 
357
357
  ## Debugging Test Runs
358
358
 
359
- When integration tests fail, the [Workflow DevKit CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you would use in development.
359
+ When integration tests fail, the [Workflow SDK CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you would use in development.
360
360
 
361
361
  Launch the Web UI to visually explore your test workflow runs:
362
362
 
@@ -376,7 +376,7 @@ npx workflow inspect runs <run-id>
376
376
 
377
377
  The Web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. This is especially useful for diagnosing issues with hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
378
378
 
379
- ![Workflow DevKit Web UI](/o11y-ui.png)
379
+ ![Workflow SDK Web UI](/o11y-ui.png)
380
380
 
381
381
  <Callout type="info">
382
382
  See the [Observability](/docs/observability) docs for the full set of CLI commands and Web UI features.
@@ -418,5 +418,5 @@ Integration tests are the right place to verify that your workflows handle error
418
418
  ---
419
419
 
420
420
  <Callout type="info">
421
- This guide was inspired by the testing approach described in Mux's article [*Launching durable AI workflows for video with @mux/ai*](https://www.mux.com/blog/launching-durable-ai-workflows-for-video-with-mux-ai#testing), which demonstrates how Mux uses the `workflow/vite` plugin with Vitest to integration test their durable AI video workflows built on Workflow DevKit.
421
+ This guide was inspired by the testing approach described in Mux's article [*Launching durable AI workflows for video with @mux/ai*](https://www.mux.com/blog/launching-durable-ai-workflows-for-video-with-mux-ai#testing), which demonstrates how Mux uses the `workflow/vite` plugin with Vitest to integration test their durable AI video workflows built on Workflow SDK.
422
422
  </Callout>
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "workflow",
3
- "version": "4.2.0-beta.73",
4
- "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
3
+ "version": "4.2.0-beta.75",
4
+ "description": "Workflow SDK - Build durable, resilient, and observable workflows",
5
5
  "main": "dist/typescript-plugin.cjs",
6
6
  "type": "module",
7
7
  "bin": {
@@ -57,18 +57,18 @@
57
57
  },
58
58
  "dependencies": {
59
59
  "ms": "2.1.3",
60
- "@workflow/astro": "4.0.0-beta.47",
61
- "@workflow/cli": "4.2.0-beta.73",
62
- "@workflow/core": "4.2.0-beta.73",
63
- "@workflow/errors": "4.1.0-beta.19",
60
+ "@workflow/astro": "4.0.0-beta.49",
61
+ "@workflow/cli": "4.2.0-beta.75",
62
+ "@workflow/core": "4.2.0-beta.75",
63
+ "@workflow/errors": "4.1.0-beta.20",
64
64
  "@workflow/typescript-plugin": "4.0.1-beta.5",
65
65
  "@workflow/utils": "4.1.0-beta.13",
66
- "@workflow/next": "4.0.1-beta.69",
67
- "@workflow/nest": "0.0.0-beta.22",
68
- "@workflow/nitro": "4.0.1-beta.68",
69
- "@workflow/nuxt": "4.0.1-beta.57",
70
- "@workflow/sveltekit": "4.0.0-beta.62",
71
- "@workflow/rollup": "4.0.0-beta.30"
66
+ "@workflow/next": "4.0.1-beta.71",
67
+ "@workflow/nest": "0.0.0-beta.24",
68
+ "@workflow/nitro": "4.0.1-beta.70",
69
+ "@workflow/nuxt": "4.0.1-beta.59",
70
+ "@workflow/sveltekit": "4.0.0-beta.64",
71
+ "@workflow/rollup": "4.0.0-beta.32"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@types/ms": "2.1.0",