workflow 5.0.0-beta.1 → 5.0.0-beta.2

package/docs/cookbook/advanced/durable-objects.mdx

@@ -0,0 +1,148 @@
+---
+title: Durable Objects
+description: Model long-lived stateful entities as workflows that persist state across requests.
+type: guide
+summary: Build a durable counter or session object whose state survives restarts by using a workflow's event log as the persistence layer.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Idea
+
+A workflow's event log already records every step result and replays them to reconstruct state. This is the same property that makes an "object" durable — its fields survive cold starts, crashes, and redeployments. Instead of using a workflow to model a *process*, you can use one to model an *entity* with methods.
+
+Each "method call" is a hook that the object's workflow loop awaits. External callers resume the hook with a payload describing the operation. The workflow applies the operation, updates its internal state, and waits for the next call.
+
+## Pattern: Durable Counter
+
+A counter that persists its value without a database. Each increment/decrement is recorded in the event log.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { z } from "zod";
+
+const counterAction = defineHook({ // [!code highlight]
+  schema: z.object({
+    type: z.enum(["increment", "decrement", "get"]),
+    amount: z.number().default(1),
+  }),
+});
+
+export async function durableCounter() {
+  "use workflow";
+
+  let count = 0;
+  const { workflowRunId } = getWorkflowMetadata();
+
+  while (true) {
+    const hook = counterAction.create({ token: `counter:${workflowRunId}` });
+    const action = await hook; // [!code highlight]
+
+    switch (action.type) {
+      case "increment":
+        count += action.amount;
+        await recordState(count);
+        break;
+      case "decrement":
+        count -= action.amount;
+        await recordState(count);
+        break;
+      case "get":
+        await emitValue(count);
+        break;
+    }
+  }
+}
+
+async function recordState(count: number) {
+  "use step";
+  // Step records the state transition in the event log.
+  // On replay, the step result restores `count` without re-executing.
+  return count;
+}
+
+async function emitValue(count: number) {
+  "use step";
+  return { count };
+}
+```
+
+### Calling the Object
+
+From an API route, resume the hook to "invoke a method" on the durable object:
+
+```typescript lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { runId, type, amount } = await request.json();
+  await resumeHook(`counter:${runId}`, { type, amount }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Pattern: Durable Session
+
+A chat session where conversation history is the durable state. Each user message is a hook event; the workflow accumulates messages and generates responses.
+
+```typescript lineNumbers
+import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
+import { DurableAgent } from "@workflow/ai/agent";
+import { anthropic } from "@workflow/ai/anthropic";
+import { z } from "zod";
+import type { UIMessageChunk, ModelMessage } from "ai";
+
+const messageHook = defineHook({ // [!code highlight]
+  schema: z.object({
+    role: z.literal("user"),
+    content: z.string(),
+  }),
+});
+
+export async function durableSession() {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+  const { workflowRunId: runId } = getWorkflowMetadata();
+  const messages: ModelMessage[] = [];
+
+  const agent = new DurableAgent({
+    model: anthropic("claude-sonnet-4-20250514"),
+    instructions: "You are a helpful assistant.",
+  });
+
+  while (true) {
+    const hook = messageHook.create({ token: `session:${runId}` });
+    const userMessage = await hook; // [!code highlight]
+
+    messages.push({
+      role: userMessage.role,
+      content: userMessage.content,
+    });
+
+    await agent.stream({ messages, writable });
+  }
+}
+```
+
+## When to Use This
+
+- **Entity-per-workflow**: Each user, document, or device gets its own workflow run. The run ID is the entity ID.
+- **No external database needed**: State lives in the event log. Reads replay from the log; writes append to it.
+- **Automatic consistency**: Only one execution runs at a time per workflow run, so there are no race conditions on the entity's state.
+
+## Trade-offs
+
+- **Read latency**: Accessing current state requires replaying the event log (or caching the last known state in a step result).
+- **Not a replacement for databases**: If you need to query across entities (e.g., "all counters above 100"), you still need a database. Durable objects are for single-entity state.
+- **Log growth**: Long-lived objects accumulate large event logs. Consider periodic "snapshot" steps that checkpoint the full state.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`defineHook`](/docs/api-reference/workflow/define-hook) — type-safe hook for receiving external method calls
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
+- [`resumeHook`](/docs/api-reference/workflow-api/resume-hook) — invoke a method on the durable object from an API route

package/docs/cookbook/advanced/isomorphic-packages.mdx

@@ -0,0 +1,145 @@
+---
+title: Isomorphic Packages
+description: Publish reusable workflow packages that work both inside and outside the workflow runtime.
+type: guide
+summary: Use try/catch around getWorkflowMetadata, dynamic imports, and optional peer dependencies to build libraries that run in workflows and in plain Node.js.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Challenge
+
+If you're a library author publishing a package that integrates with workflow, your code needs to handle two environments:
+
+1. **Inside a workflow run** — `getWorkflowMetadata()` works, `"use step"` directives are transformed, and the full workflow runtime is available.
+2. **Outside a workflow** — your package is imported in a regular Node.js process, a test suite, or a project that doesn't use workflow at all.
+
+A hard dependency on `workflow` will crash at import time for users who don't have it installed.
+
+## Pattern 1: Feature-Detect with `getWorkflowMetadata`
+
+Use a try/catch to detect whether you're running inside a workflow. This lets you add durable behavior when available and fall back to standard execution otherwise.
+
+```typescript lineNumbers
+import { getWorkflowMetadata } from "workflow";
+
+export async function processPayment(amount: number, currency: string) {
+  "use workflow";
+
+  let runId: string | undefined;
+  try {
+    const metadata = getWorkflowMetadata(); // [!code highlight]
+    runId = metadata.workflowRunId;
+  } catch {
+    // Not running inside a workflow — proceed without durability
+    runId = undefined;
+  }
+
+  if (runId) {
+    // Inside a workflow: use the run ID as an idempotency key
+    return await chargeWithIdempotency(amount, currency, runId); // [!code highlight]
+  } else {
+    // Outside a workflow: standard charge
+    return await chargeStandard(amount, currency);
+  }
+}
+
+async function chargeWithIdempotency(amount: number, currency: string, idempotencyKey: string) {
+  "use step";
+  // Stripe charge with idempotency key from workflow run ID
+  return { charged: true, amount, currency, idempotencyKey };
+}
+
+async function chargeStandard(amount: number, currency: string) {
+  "use step";
+  return { charged: true, amount, currency };
+}
+```
+
+## Pattern 2: Dynamic Imports
+
+Avoid importing `workflow` at the top level. Use dynamic `import()` so the module is only loaded when actually needed.
+
+```typescript lineNumbers
+export async function createDurableTask(name: string, payload: unknown) {
+  "use workflow";
+
+  let sleep: ((duration: string) => Promise<void>) | undefined;
+
+  try {
+    const wf = await import("workflow"); // [!code highlight]
+    sleep = wf.sleep;
+  } catch {
+    // workflow not installed — use setTimeout fallback
+    sleep = undefined;
+  }
+
+  await executeTask(name, payload);
+
+  if (sleep) {
+    // Inside workflow: durable sleep that survives restarts
+    await sleep("5m"); // [!code highlight]
+  } else {
+    // Outside workflow: plain timer (not durable)
+    await new Promise((resolve) => setTimeout(resolve, 5 * 60 * 1000));
+  }
+
+  await sendNotification(name);
+}
+
+async function executeTask(name: string, payload: unknown) {
+  "use step";
+  return { executed: true, name, payload };
+}
+
+async function sendNotification(name: string) {
+  "use step";
+  return { notified: true, name };
+}
+```
+
+## Pattern 3: Optional Peer Dependencies
+
+In your `package.json`, declare `workflow` as an optional peer dependency. This signals to package managers that your library *can* use workflow but doesn't require it.
+
+```json
+{
+  "name": "@acme/payments",
+  "peerDependencies": {
+    "workflow": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "workflow": {
+      "optional": true
+    }
+  }
+}
+```
+
+Then guard all workflow imports with dynamic `import()` and try/catch as shown above.
+
+## Real-World Examples
+
+### Mux AI
+
+The Mux team published a reusable workflow package for video processing. Their library detects the workflow runtime and falls back to standard async processing when workflow isn't available.
+
+### World ID
+
+World ID's identity verification library uses `getWorkflowMetadata()` to attach run IDs to their human-in-the-loop verification hooks, but the same library works in non-workflow environments for simple verification flows.
+
+## Guidelines for Library Authors
+
+1. **Never hard-import `workflow` at the top level** if your package should work without it.
+2. **Use `getWorkflowMetadata()` in a try/catch** as the canonical runtime detection pattern.
+3. **Mark `workflow` as an optional peer dependency** in `package.json`.
+4. **Test both paths**: run your test suite with and without the workflow runtime to catch import errors.
+5. **Document the dual behavior**: make it clear in your README which features require workflow and which work standalone.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/advanced/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "serializable-steps",
+    "durable-objects",
+    "isomorphic-packages",
+    "custom-serialization",
+    "publishing-libraries"
+  ]
+}

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -0,0 +1,279 @@
+---
+title: Publishing Libraries
+description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
+type: guide
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+---
+
+<Callout>
+This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
+</Callout>
+
+## Package Structure
+
+A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
+
+```
+my-media-lib/
+├── src/
+│   ├── index.ts              # Package entry point
+│   ├── types.ts              # Shared types
+│   ├── workflows/
+│   │   ├── index.ts          # Re-exports all workflows
+│   │   ├── transcode.ts      # Workflow: transcode a video
+│   │   └── generate-thumbnails.ts
+│   └── lib/
+│       └── api-client.ts     # Internal helpers (NOT steps)
+├── test-server/
+│   └── workflows.ts          # Re-export for integration tests
+├── tsup.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### Entry Points and Exports
+
+Use the `exports` field in `package.json` to expose separate entry points for the main API and the raw workflow functions:
+
+```json
+{
+  "name": "@acme/media",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": { "import": "./dist/index.d.ts" },
+      "import": "./dist/index.js"
+    },
+    "./workflows": {
+      "types": { "import": "./dist/workflows/index.d.ts" },
+      "import": "./dist/workflows/index.js"
+    }
+  },
+  "files": ["dist"]
+}
+```
+
+The main entry point (`@acme/media`) exports types, utilities, and convenience wrappers. The `./workflows` entry point (`@acme/media/workflows`) exports the raw workflow functions that consumers need for the build system.
+
+### Source Files
+
+The package entry re-exports workflows alongside any utilities:
+
+```typescript lineNumbers
+// src/index.ts
+export * from "./types";
+export * as workflows from "./workflows";
+```
+
+The workflows barrel file re-exports each workflow:
+
+```typescript lineNumbers
+// src/workflows/index.ts
+export * from "./transcode";
+export * from "./generate-thumbnails";
+```
+
+### Build Configuration
+
+Use a bundler like `tsup` with separate entry points for each export. Mark `workflow` as external so it's resolved from the consumer's project:
+
+```typescript lineNumbers
+// tsup.config.ts
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: [
+    "src/index.ts",
+    "src/workflows/index.ts",
+  ],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: ["workflow"], // [!code highlight]
+});
+```
+
+## Re-Exporting for Workflow ID Stability
+
+Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+
+### Consumer Setup
+
+```typescript lineNumbers
+// workflows/media.ts (in the consumer's project)
+// Re-export library workflows so the build system assigns stable IDs
+export * from "@acme/media/workflows"; // [!code highlight]
+```
+
+This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+
+### Why This Is Necessary
+
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+
+The re-export pattern ensures:
+
+1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
+2. **Replay safety** — IDs persist across deployments and cold starts
+3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+
+## Keeping Step I/O Clean
+
+When you publish a workflow library, every step function's inputs and outputs are recorded in the event log. This has two implications:
+
+### 1. Everything Must Be Serializable
+
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/cookbook/advanced/custom-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+
+- Functions or closures
+- `WeakRef`, `WeakMap`, or `WeakSet`
+
+If your library works with complex objects that don't implement custom class serialization, pass serializable configuration into steps and reconstruct the objects inside the step body.
+
+{/* @skip-typecheck - good/bad comparison with duplicate function names */}
+```typescript lineNumbers
+// Good: pass serializable config, construct inside the step
+async function callExternalApi(endpoint: string, params: Record<string, string>) {
+  "use step";
+  const client = createApiClient(process.env.API_KEY!);
+  return await client.request(endpoint, params);
+}
+
+// Bad: pass a pre-constructed client object
+async function callExternalApi(client: ApiClient, params: Record<string, string>) {
+  "use step";
+  // ApiClient is not serializable — this will fail on replay
+  return await client.request(params);
+}
+```
+
+See [Serializable Steps](/docs/cookbook/advanced/serializable-steps) for the step-as-factory pattern.
+
+### 2. Credentials
+
+With workflow encryption enabled, credentials passed as step arguments are encrypted in the event log, so either approach is valid:
+
+{/* @skip-typecheck - good/bad comparison with duplicate function names */}
+```typescript lineNumbers
+// Option A: resolve credentials from environment inside the step
+async function fetchData(query: string) {
+  "use step";
+  const client = createClient(process.env.API_KEY!);
+  return await client.fetch(query);
+}
+
+// Option B: pass credentials as step arguments (encrypted in the event log)
+async function fetchData(apiKey: string, query: string) {
+  "use step";
+  const client = createClient(apiKey);
+  return await client.fetch(query);
+}
+```
+
+The choice is a matter of library API design preference. Resolving from environment variables keeps the step signature simpler, while passing credentials explicitly makes dependencies visible and can be easier to test.
+
+## Testing Workflow Libraries
+
+Library authors need integration tests that exercise workflows through the full Workflow SDK runtime — not just unit tests of individual functions.
+
+### Test Server Pattern
+
+Create a minimal test server that re-exports your library's workflows, just like a consumer would:
+
+```typescript lineNumbers
+// test-server/workflows.ts
+export * from "@acme/media/workflows"; // [!code highlight]
+```
+
+This test server acts as a stand-in consumer app. Point your test runner at it to exercise the full workflow lifecycle: start, replay, and completion.
+
+### Vitest Configuration
+
+Use a dedicated Vitest config for integration tests that run against the Workflow SDK runtime:
+
+```typescript lineNumbers
+// vitest.workflowsdk.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/integration/**/*.workflowsdk.test.ts"],
+    testTimeout: 120_000, // Workflows may take time to complete
+    setupFiles: ["./tests/setup.ts"],
+  },
+});
+```
+
+Run these tests separately from your unit tests:
+
+```bash
+# Unit tests (fast, no workflow runtime)
+pnpm vitest run tests/unit
+
+# Integration tests (requires workflow runtime)
+pnpm vitest run --config vitest.workflowsdk.config.ts
+```
+
+### What to Test
+
+- **Happy path**: workflow starts, all steps execute, and the final result is correct
+- **Serialization round-trip**: inputs and outputs survive the event log
+- **Replay**: kill and restart a workflow mid-execution to verify deterministic replay
+- **Error handling**: verify that step failures produce the expected errors
+
+## Working With and Without Workflow Installed
+
+If your library should work both as a standalone package and inside Workflow SDK, declare `workflow` as an optional peer dependency:
+
+```json
+{
+  "peerDependencies": {
+    "workflow": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "workflow": {
+      "optional": true
+    }
+  }
+}
+```
+
+Use dynamic imports and runtime detection so your library gracefully degrades when workflow is not installed:
+
+```typescript lineNumbers
+async function isWorkflowRuntime(): Promise<boolean> {
+  try {
+    const wf = await import("workflow");
+    if (typeof wf.getWorkflowMetadata !== "function") return false;
+    wf.getWorkflowMetadata(); // [!code highlight]
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+See [Isomorphic Packages](/docs/cookbook/advanced/isomorphic-packages) for the full pattern including feature detection, dynamic imports, and dual-path execution.
+
+## Checklist
+
+Before publishing a workflow library:
+
+- [ ] `workflow` is listed as an **optional** peer dependency
+- [ ] Separate `./workflows` export in `package.json` for the raw workflow functions
+- [ ] `workflow` is marked as **external** in your bundler config
+- [ ] Documentation tells consumers to re-export from `@your-lib/workflows`
+- [ ] Credentials are either resolved from environment variables or passed explicitly (both are safe with encryption enabled)
+- [ ] All step I/O uses [supported serializable types](/docs/foundations/serialization)
+- [ ] Integration tests use a test server with re-exported workflows
+- [ ] Both with-workflow and without-workflow code paths are tested
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access