workflow 4.4.0 → 4.5.0

package/docs/v5/api-reference/workflow-vite/workflow.mdx

@@ -0,0 +1,48 @@
+---
+title: workflow
+description: Configure Vite and Nitro to transform workflow directives.
+type: reference
+summary: Add the workflow plugin to your Vite config to enable workflow directive transformation in Vite + Nitro apps.
+prerequisites:
+  - /docs/getting-started/vite
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and configure the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on the Nitro server. It is designed to be used alongside `nitro()` from `nitro/vite`, which provides the server framework for API routes and deployment.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `plugins` array of your Vite config, together with `nitro()`.
+
+```typescript title="vite.config.ts" lineNumbers
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [nitro(), workflow()], // [!code highlight]
+  nitro: {
+    serverDir: "./",
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ModuleOptions` | Optional. Forwarded to the `workflow/nitro` module as its module options. |
+
+#### ModuleOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). Only applies when deploying to Vercel. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config — Vite flattens nested plugin arrays automatically.

package/docs/v5/errors/index.mdx

@@ -40,6 +40,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow SDK*
     <Card href="/docs/errors/step-not-registered" title="step-not-registered">
         Resolve step not registered errors caused by deployment mismatches.
     </Card>
+    <Card href="/docs/errors/step-executed-multiple-times" title="Step executed multiple times">
+        Diagnose duplicate step_started events from function crashes, timeouts, or OOMs.
+    </Card>
     <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
         Resolve workflow not registered errors caused by deployment mismatches.
     </Card>

package/docs/v5/errors/step-executed-multiple-times.mdx

@@ -0,0 +1,23 @@
+---
+title: Step executed multiple times
+description: A step ran more than once because its function invocation crashed before it could report a result.
+type: troubleshooting
+summary: Diagnose duplicate step_started events caused by function timeouts, OOMs, or network issues.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/foundations/errors-and-retries
+---
+
+There may be cases where you see multiple `step_started` events for the same step in a workflow run. This happens if the function invocation executing the step crashes unexpectedly, and the step can not report the error. The step will be re-tried according to your retry policy in this case, but no error will be visible in the [Observability UI](/docs/observability).
+
+## Common Causes
+
+- **Function timeouts**: if your step code runs longer than the configured maximum function duration, it will be killed. Compare the gap between the `step_started` events to your configured function duration to be sure.
+- **Out of memory (OOM)**: if your step code loads enough data into memory, especially if the step is invoked concurrently, the function invocation might run out of memory. You can see your function's peak memory use by going to the [Observability Query page](https://vercel.com/docs/observability) and showing the **Function Invocation Peak Memory** metric, then filtering down the **Route** to `/.well-known/workflow` endpoints.
+- **Network issues**: persistent firewall, network stability, and related issues might prevent your function from reporting results or errors. This should be temporary.
+
+## Getting Help
+
+If you consistently see multiple `step_started` events and have ruled out function timeouts, OOMs, and firewall issues, please [contact support](https://vercel.com/help).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.9",
-    "@workflow/cli": "4.2.9",
-    "@workflow/core": "4.4.0",
+    "@workflow/astro": "4.0.10",
+    "@workflow/cli": "4.2.10",
+    "@workflow/core": "4.5.0",
     "@workflow/errors": "4.1.4",
     "@workflow/typescript-plugin": "4.0.3",
     "@workflow/utils": "4.1.3",
-    "@workflow/next": "4.0.10",
-    "@workflow/nest": "0.0.9",
-    "@workflow/nitro": "4.1.0",
-    "@workflow/nuxt": "4.0.10",
-    "@workflow/sveltekit": "4.0.9",
-    "@workflow/rollup": "4.0.9"
+    "@workflow/next": "4.0.11",
+    "@workflow/nest": "0.0.10",
+    "@workflow/nitro": "4.1.1",
+    "@workflow/nuxt": "4.0.11",
+    "@workflow/sveltekit": "4.0.10",
+    "@workflow/rollup": "4.0.10"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/docs/api-reference/workflow-api/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "World SDK",
-  "pages": ["storage", "streams", "queue", "observability"]
-}

package/docs/api-reference/workflow-api/world/observability.mdx

@@ -1,164 +0,0 @@
----
-title: Observability Utilities
-description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
-type: reference
-summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/storage
-keywords:
-  - workflow/observability
-  - hydrateResourceIO
-  - observabilityRevivers
-  - parseStepName
-  - parseWorkflowName
-  - parseClassName
-  - getEncryptionKeyForRun
-  - hydrateResourceIOWithKey
-  - data hydration
-  - devalue deserialization
-  - encryption decryption
-  - display name parsing
----
-
-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.
-
-## Import
-
-```typescript lineNumbers
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-  parseStepName, // [!code highlight]
-  parseWorkflowName, // [!code highlight]
-  parseClassName, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
-```
-
-## Data Hydration
-
-### hydrateResourceIO()
-
-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.
-
-```typescript lineNumbers
-import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
-
-const step = await world.steps.get(runId, stepId);
-const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-console.log(hydrated.input, hydrated.output);
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
-| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
-
-**Returns:** The resource with hydrated `input` and `output` fields.
-
-### observabilityRevivers
-
-A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
-
-## Name Parsing
-
-Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
-
-### parseStepName()
-
-```typescript lineNumbers
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
-// parsed?.shortName → "processPayment"
-// parsed?.moduleSpecifier → "./src/workflows/order"
-```
-
-### parseWorkflowName()
-
-```typescript lineNumbers
-import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
-// parsed?.shortName → "processOrder"
-```
-
-### parseClassName()
-
-```typescript lineNumbers
-import { parseClassName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
-// parsed?.shortName → "User"
-```
-
-## Encryption
-
-For workflows with encrypted step data, decrypt before hydrating.
-
-### getEncryptionKeyForRun()
-
-Retrieve the encryption key used for a specific workflow run.
-
-{/* @expect-error:2305 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-
-**Returns:** Encryption key for the run
-
-### hydrateResourceIOWithKey()
-
-Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
-
-{/* @expect-error:2305,2724 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
-| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
-
-**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
-
-## Examples
-
-### Parse Display Names for a Run's Steps
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const world = getWorld();
-const run = await world.runs.get(runId, { resolveData: "none" });
-console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
-
-const steps = await world.steps.list({ runId, resolveData: "none" });
-for (const step of steps.data) {
-  const parsed = parseStepName(step.stepName); // [!code highlight]
-  console.log(`  ${parsed?.shortName}: ${step.status}`); // [!code highlight]
-}
-```
-
-## Related
-
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
-- [Serialization](/docs/foundations/serialization) — How workflow data is serialized