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.
- package/README.md +6 -6
- package/docs/ai/defining-tools.mdx +2 -2
- package/docs/ai/human-in-the-loop.mdx +1 -1
- package/docs/ai/index.mdx +8 -8
- package/docs/ai/resumable-streams.mdx +1 -1
- package/docs/ai/sleep-and-delays.mdx +2 -2
- package/docs/ai/streaming-updates-from-tools.mdx +1 -1
- package/docs/api-reference/index.mdx +9 -3
- package/docs/api-reference/meta.json +10 -1
- package/docs/api-reference/workflow/create-webhook.mdx +4 -0
- package/docs/api-reference/workflow/index.mdx +2 -2
- package/docs/api-reference/workflow-ai/durable-agent.mdx +1 -1
- package/docs/api-reference/workflow-api/get-world.mdx +33 -157
- package/docs/api-reference/workflow-api/index.mdx +3 -0
- package/docs/api-reference/workflow-api/world/events.mdx +227 -0
- package/docs/api-reference/workflow-api/world/hooks.mdx +181 -0
- package/docs/api-reference/workflow-api/world/index.mdx +67 -0
- package/docs/api-reference/workflow-api/world/meta.json +12 -0
- package/docs/api-reference/workflow-api/world/observability.mdx +289 -0
- package/docs/api-reference/workflow-api/world/queue.mdx +127 -0
- package/docs/api-reference/workflow-api/world/runs.mdx +223 -0
- package/docs/api-reference/workflow-api/world/steps.mdx +216 -0
- package/docs/api-reference/workflow-api/world/streams.mdx +152 -0
- package/docs/api-reference/workflow-globals.mdx +102 -0
- package/docs/api-reference/workflow-next/index.mdx +1 -1
- package/docs/api-reference/workflow-serde/index.mdx +2 -2
- package/docs/changelog/index.mdx +2 -2
- package/docs/deploying/building-a-world.mdx +1 -1
- package/docs/deploying/world/vercel-world.mdx +20 -13
- package/docs/errors/index.mdx +1 -1
- package/docs/errors/node-js-module-in-workflow.mdx +1 -1
- package/docs/errors/serialization-failed.mdx +1 -1
- package/docs/errors/start-invalid-workflow-function.mdx +3 -3
- package/docs/foundations/errors-and-retries.mdx +1 -1
- package/docs/foundations/hooks.mdx +5 -1
- package/docs/foundations/serialization.mdx +2 -2
- package/docs/foundations/streaming.mdx +3 -2
- package/docs/foundations/workflows-and-steps.mdx +2 -2
- package/docs/getting-started/astro.mdx +5 -5
- package/docs/getting-started/express.mdx +5 -5
- package/docs/getting-started/fastify.mdx +5 -5
- package/docs/getting-started/hono.mdx +5 -5
- package/docs/getting-started/nestjs.mdx +5 -5
- package/docs/getting-started/next.mdx +5 -5
- package/docs/getting-started/nitro.mdx +5 -5
- package/docs/getting-started/nuxt.mdx +5 -5
- package/docs/getting-started/sveltekit.mdx +5 -5
- package/docs/getting-started/vite.mdx +5 -5
- package/docs/how-it-works/code-transform.mdx +6 -6
- package/docs/how-it-works/encryption.mdx +3 -3
- package/docs/how-it-works/event-sourcing.mdx +5 -5
- package/docs/how-it-works/framework-integrations.mdx +9 -9
- package/docs/how-it-works/understanding-directives.mdx +11 -11
- package/docs/observability/index.mdx +5 -5
- package/docs/testing/index.mdx +4 -4
- 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
345
|
-
In the future, the Workflow
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-

|
|
44
44
|
|
|
45
45
|
## Backends
|
|
46
46
|
|
|
47
|
-
The Workflow
|
|
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`.
|
package/docs/testing/index.mdx
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-

|
|
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
|
|
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.
|
|
4
|
-
"description": "Workflow
|
|
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.
|
|
61
|
-
"@workflow/cli": "4.2.0-beta.
|
|
62
|
-
"@workflow/core": "4.2.0-beta.
|
|
63
|
-
"@workflow/errors": "4.1.0-beta.
|
|
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.
|
|
67
|
-
"@workflow/nest": "0.0.0-beta.
|
|
68
|
-
"@workflow/nitro": "4.0.1-beta.
|
|
69
|
-
"@workflow/nuxt": "4.0.1-beta.
|
|
70
|
-
"@workflow/sveltekit": "4.0.0-beta.
|
|
71
|
-
"@workflow/rollup": "4.0.0-beta.
|
|
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",
|