workflow 5.0.0-beta.2 → 5.0.0-beta.20

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 = await 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

package/docs/cookbook/advanced/custom-serialization.mdx

@@ -1,168 +0,0 @@
----
-title: Custom Serialization
-description: Make class instances serializable across workflow boundaries using the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol.
-type: guide
-summary: Implement the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol on classes so instances survive serialization when passed between workflow and step functions.
----
-
-<Callout>
-This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
-</Callout>
-
-## The Problem
-
-Workflow functions run inside a sandboxed VM. Every value that crosses a function boundary — step arguments, step return values, workflow inputs — must be [serializable](/docs/foundations/serialization). Plain objects, strings, numbers, and many built-in types (`Date`, `Map`, `Set`, `RegExp`, etc.) work automatically, but **class instances** that don't implement the custom class serialization protocol will throw a serialization error.
-
-```typescript lineNumbers
-class StorageClient {
-  constructor(private region: string) {}
-
-  async upload(key: string, body: Uint8Array) {
-    // ... uses this.region internally
-  }
-}
-
-export async function processFile(client: StorageClient) {
-  "use workflow";
-
-  // client fails to serialize — StorageClient doesn't implement custom class serialization
-  // The runtime throws a serialization error
-  await uploadStep(client, "output.json", data);
-}
-```
-
-Custom class serialization solves this by teaching the runtime how to convert your class instances to plain data and back.
-
-## The WORKFLOW_SERIALIZE / WORKFLOW_DESERIALIZE Protocol
-
-The `@workflow/serde` package exports two symbols that act as a custom class serialization protocol. When the workflow runtime encounters a class instance with these symbols, it knows how to convert it to plain data and back.
-
-{/* @skip-typecheck - @workflow/serde is not mapped in the type-checker */}
-```typescript lineNumbers
-import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
-
-class Point {
-  constructor(public x: number, public y: number) {}
-
-  distanceTo(other: Point): number {
-    return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2);
-  }
-
-  static [WORKFLOW_SERIALIZE](instance: Point) { // [!code highlight]
-    return { x: instance.x, y: instance.y };
-  }
-
-  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) { // [!code highlight]
-    return new Point(data.x, data.y);
-  }
-}
-```
-
-Both methods must be **static**. `WORKFLOW_SERIALIZE` receives an instance and returns plain serializable data. `WORKFLOW_DESERIALIZE` receives that same data and reconstructs a new instance.
-
-<Callout type="warn">
-Both serialization methods run inside the workflow VM. They must not use Node.js APIs, non-deterministic operations, or network calls. Keep them focused on extracting and reconstructing data.
-</Callout>
-
-## Automatic Class Registration
-
-For the runtime to deserialize a class, the class must be registered in a global registry with a stable `classId`. The SWC compiler plugin handles this automatically — when it detects a class with both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` static methods, it generates registration code at build time.
-
-This means you only need to implement the two symbol methods. The compiler assigns a deterministic `classId` based on the file path and class name, and registers it in the global `Symbol.for("workflow-class-registry")` registry.
-
-<Callout type="info">
-No manual registration is required for classes defined in your workflow files. The SWC plugin detects the serialization symbols and generates the registration automatically at build time.
-</Callout>
-
-## Full Example: A Workflow-Safe Storage Client
-
-Here's a complete example of a storage client class that survives serialization across workflow boundaries. This pattern is useful when you need an object with methods to be passed as a workflow input or returned from a step.
-
-```typescript lineNumbers
-import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
-
-interface StorageClientOptions {
-  region: string;
-  bucket: string;
-  accessKeyId?: string;
-  secretAccessKey?: string;
-}
-
-export class WorkflowStorageClient {
-  private readonly region: string;
-  private readonly bucket: string;
-  private readonly accessKeyId?: string;
-  private readonly secretAccessKey?: string;
-
-  constructor(options: StorageClientOptions) {
-    this.region = options.region;
-    this.bucket = options.bucket;
-    this.accessKeyId = options.accessKeyId;
-    this.secretAccessKey = options.secretAccessKey;
-  }
-
-  async upload(key: string, body: Uint8Array) {
-    "use step";
-    const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
-    const client = new S3Client({
-      region: this.region,
-      credentials: this.accessKeyId
-        ? { accessKeyId: this.accessKeyId, secretAccessKey: this.secretAccessKey! }
-        : undefined,
-    });
-    await client.send(
-      new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body })
-    );
-  }
-
-  async getSignedUrl(key: string): Promise<string> {
-    "use step";
-    const { S3Client, GetObjectCommand } = await import("@aws-sdk/client-s3");
-    const { getSignedUrl } = await import("@aws-sdk/s3-request-presigner");
-    const client = new S3Client({ region: this.region });
-    return getSignedUrl(client, new GetObjectCommand({ Bucket: this.bucket, Key: key }));
-  }
-
-  // --- Serialization protocol ---
-
-  static [WORKFLOW_SERIALIZE](instance: WorkflowStorageClient): StorageClientOptions { // [!code highlight]
-    return {
-      region: instance.region,
-      bucket: instance.bucket,
-      accessKeyId: instance.accessKeyId,
-      secretAccessKey: instance.secretAccessKey,
-    };
-  }
-
-  static [WORKFLOW_DESERIALIZE]( // [!code highlight]
-    data: StorageClientOptions
-  ): WorkflowStorageClient {
-    return new WorkflowStorageClient(data);
-  }
-}
-```
-
-Now this client can be passed into a workflow and used directly:
-
-```typescript lineNumbers
-import { WorkflowStorageClient } from "./storage-client";
-
-export async function processUpload(
-  client: WorkflowStorageClient,
-  data: Uint8Array
-) {
-  "use workflow";
-
-  // client is a real WorkflowStorageClient with working methods
-  await client.upload("output/result.json", data); // [!code highlight]
-  const url = await client.getSignedUrl("output/result.json"); // [!code highlight]
-  return { url };
-}
-```
-
-## Key APIs
-
-- [`WORKFLOW_SERIALIZE`](/docs/api-reference/workflow-serde/workflow-serialize) — symbol for the static serialization method
-- [`WORKFLOW_DESERIALIZE`](/docs/api-reference/workflow-serde/workflow-deserialize) — symbol for the static deserialization method
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function

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

@@ -1,148 +0,0 @@
----
-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

@@ -1,145 +0,0 @@
----
-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