workflow 5.0.0-beta.2 → 5.0.0-beta.4

package/docs/cookbook/common-patterns/sequential-and-parallel.mdx

@@ -0,0 +1,155 @@
+---
+title: Sequential & Parallel Execution
+description: Compose steps with familiar async/await patterns — sequential await, Promise.all, and Promise.race.
+type: guide
+summary: Workflows are just async functions, so all the standard composition primitives (await, Promise.all, Promise.race) apply unchanged — including racing webhooks against durable sleeps.
+related:
+  - /docs/foundations/workflows-and-steps
+  - /cookbook/common-patterns/timeouts
+  - /cookbook/common-patterns/scheduling
+---
+
+Workflows are written in plain async/await — there's no new control-flow API to learn. Sequential awaits chain steps that depend on each other, `Promise.all` runs independent steps in parallel, and `Promise.race` returns whichever finishes first. These compose with workflow primitives like [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) since those are also just promises.
+
+## When to use this
+
+- **Pipelines** — each step depends on the previous step's output (validate → process → store)
+- **Independent fan-out** — fetch multiple resources or perform multiple actions that don't depend on each other
+- **Race conditions** — return as soon as one of N operations completes (timeout, first-responder, deadline)
+- **Mixing primitives** — running steps, sleeps, and webhooks side-by-side in the same control-flow expression
+
+## Pattern
+
+### Sequential
+
+The simplest way to orchestrate steps is to execute them one after another, where each step depends on the previous step's output.
+
+```typescript lineNumbers
+declare function validateData(data: unknown): Promise<string>; // @setup
+declare function processData(data: string): Promise<string>; // @setup
+declare function storeData(data: string): Promise<string>; // @setup
+
+export async function dataPipelineWorkflow(data: unknown) {
+  "use workflow";
+
+  const validated = await validateData(data);
+  const processed = await processData(validated);
+  const stored = await storeData(processed);
+
+  return stored;
+}
+```
+
+### Parallel with `Promise.all`
+
+When steps don't depend on each other, run them concurrently with `Promise.all`. The workflow waits until all of them resolve.
+
+```typescript lineNumbers
+declare function fetchUser(userId: string): Promise<{ name: string }>; // @setup
+declare function fetchOrders(userId: string): Promise<{ items: string[] }>; // @setup
+declare function fetchPreferences(userId: string): Promise<{ theme: string }>; // @setup
+
+export async function fetchUserData(userId: string) {
+  "use workflow";
+
+  const [user, orders, preferences] = await Promise.all([ // [!code highlight]
+    fetchUser(userId), // [!code highlight]
+    fetchOrders(userId), // [!code highlight]
+    fetchPreferences(userId), // [!code highlight]
+  ]); // [!code highlight]
+
+  return { user, orders, preferences };
+}
+```
+
+### Race with `Promise.race`
+
+`Promise.race` resolves as soon as the first promise settles. Since [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) return promises, they compose naturally — for example, waiting for a webhook callback with a deadline:
+
+```typescript lineNumbers
+import { sleep, createWebhook } from "workflow";
+
+declare function executeExternalTask(webhookUrl: string): Promise<void>; // @setup
+
+export async function runExternalTask(userId: string) {
+  "use workflow";
+
+  const webhook = createWebhook();
+  await executeExternalTask(webhook.url);
+
+  await Promise.race([ // [!code highlight]
+    webhook, // [!code highlight]
+    sleep("1 day"), // [!code highlight]
+  ]); // [!code highlight]
+
+  console.log("Done");
+}
+```
+
+For racing operations against deadlines specifically (timeouts), see the dedicated [Timeouts](/cookbook/common-patterns/timeouts) recipe — it covers result discrimination, `FatalError` semantics, and the "loser keeps running" caveat.
+
+### Combining sequential, parallel, and durable primitives
+
+Most real workflows combine all three. Here's a simplified version of the [birthday card generator demo](https://github.com/vercel/workflow-examples/tree/main/birthday-card-generator) — sequential card generation, parallel RSVP fan-out, non-blocking webhook collection, and a durable sleep until the birthday:
+
+```typescript lineNumbers
+import { createWebhook, sleep, type Webhook } from "workflow";
+
+declare function makeCardText(prompt: string): Promise<string>; // @setup
+declare function makeCardImage(text: string): Promise<string>; // @setup
+declare function sendRSVPEmail(friend: string, webhook: Webhook): Promise<void>; // @setup
+declare function sendBirthdayCard(text: string, image: string, rsvps: unknown[], email: string): Promise<void>; // @setup
+
+export async function birthdayWorkflow(
+  prompt: string,
+  email: string,
+  friends: string[],
+  birthday: Date
+) {
+  "use workflow";
+
+  const text = await makeCardText(prompt); // [!code highlight]
+  const image = await makeCardImage(text); // [!code highlight]
+
+  const webhooks = friends.map(() => createWebhook());
+
+  await Promise.all( // [!code highlight]
+    friends.map((friend, i) => sendRSVPEmail(friend, webhooks[i])) // [!code highlight]
+  ); // [!code highlight]
+
+  const rsvps: unknown[] = [];
+  webhooks.map((webhook) =>
+    webhook.then((req) => req.json()).then(({ rsvp }) => rsvps.push(rsvp))
+  );
+
+  await sleep(birthday); // [!code highlight]
+
+  await sendBirthdayCard(text, image, rsvps, email);
+
+  return { text, image, status: "Sent" };
+}
+```
+
+## How it works
+
+1. **`await` is durable.** When the workflow awaits a step, the runtime persists the step's input, suspends the workflow, runs the step, and replays the workflow with the step's result on resume. The same applies to `sleep()` and `createWebhook()`.
+2. **`Promise.all` runs steps concurrently.** Each promise in the array is suspended on its own and the workflow resumes only when all have settled. Failures propagate — if any promise rejects, the whole `Promise.all` rejects.
+3. **`Promise.race` resolves on the first settle.** The losing promises keep running in the background but their results are discarded by the workflow.
+4. **All primitives are promises.** `sleep("1 day")` and `createWebhook()` return promises, so they compose with `Promise.all` / `Promise.race` exactly like steps do — this is what makes patterns like "race a webhook against a 24-hour deadline" a one-liner.
+
+## Adapting to your use case
+
+- **Replace `Promise.all` with `Promise.allSettled`** when partial failures should not abort the rest. You'll get an array of `{ status, value | reason }` instead of throwing on the first rejection.
+- **Bound the parallelism** — `Promise.all` over 1000 items will fan out 1000 concurrent steps. If your downstream APIs can't handle that, batch the array into chunks (see [Batching](/cookbook/common-patterns/batching)).
+- **Add a deadline to any race** — pair the operation with `sleep("30s").then(() => "timeout" as const)` and check the discriminated result. See [Timeouts](/cookbook/common-patterns/timeouts).
+- **Mix steps and hooks in a race** — wait for an external signal *or* a deadline *or* a step result, all in the same `Promise.race`. The first one to resolve wins.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable sleep that survives restarts
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — webhook URL the workflow can race against
+- [`Promise.all()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) — wait for all promises
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — wait for the first to settle
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) — wait for all, including failures

package/docs/cookbook/common-patterns/timeouts.mdx

@@ -0,0 +1,99 @@
+---
+title: Timeouts
+description: Add deadlines to slow operations by racing them against a durable sleep.
+type: guide
+summary: Use `Promise.race` with `sleep()` to bound the time any step, hook, or webhook is allowed to take — and recover gracefully when the deadline fires first.
+related:
+  - /docs/api-reference/workflow/sleep
+  - /docs/foundations/hooks
+  - /cookbook/common-patterns/scheduling
+  - /cookbook/common-patterns/webhooks
+---
+
+A common requirement is bounding how long a workflow waits for something to finish — a slow step, an external webhook, a human approval. Race the operation against a durable `sleep()` with `Promise.race()` — whichever finishes first wins, and the loser keeps running but its result is ignored.
+
+## When to use this
+
+- **Slow steps** — bound the time spent waiting on third-party APIs, model calls, or expensive computation
+- **External callbacks** — give webhooks a deadline so the workflow doesn't hang forever waiting for an event that may never arrive
+- **Human approvals** — auto-decline or escalate when a hook isn't resumed within a window
+- **Polling loops** — give an outer poll-until-ready loop an overall budget
+
+## Pattern
+
+### Timeout on a slow step
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+declare function processData(data: string): Promise<string>; // @setup
+
+export async function processWithTimeout(data: string) {
+  "use workflow";
+
+  const result = await Promise.race([ // [!code highlight]
+    processData(data), // [!code highlight]
+    sleep("30s").then(() => "timeout" as const), // [!code highlight]
+  ]); // [!code highlight]
+
+  if (result === "timeout") {
+    throw new Error("Processing timed out after 30 seconds");
+  }
+
+  return result;
+}
+```
+
+### Timeout on a webhook
+
+The same pattern works for any promise — including hooks and webhooks. Here a webhook waits for an external service to call back, with a hard deadline of 7 days:
+
+```typescript lineNumbers
+import { sleep, createWebhook } from "workflow";
+
+declare function sendApprovalRequest(requestId: string, webhookUrl: string): Promise<void>; // @setup
+
+export async function waitForApproval(requestId: string) {
+  "use workflow";
+
+  const webhook = createWebhook<{ approved: boolean }>();
+  await sendApprovalRequest(requestId, webhook.url);
+
+  const result = await Promise.race([ // [!code highlight]
+    webhook.then((req) => req.json()), // [!code highlight]
+    sleep("7 days").then(() => ({ timedOut: true }) as const), // [!code highlight]
+  ]); // [!code highlight]
+
+  if ("timedOut" in result) {
+    throw new Error("Approval request expired after 7 days");
+  }
+
+  return result.approved;
+}
+```
+
+## How it works
+
+1. **Durable sleep** — `sleep("30s")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
+2. **Race** — `Promise.race([work, sleep(...)])` returns the value of whichever promise resolves first. The loser keeps running in the background but its result is ignored by the workflow.
+3. **Discriminated result** — tagging the sleep branch with a sentinel value (`"timeout" as const`, `{ timedOut: true }`) lets TypeScript narrow the result and pick the right branch.
+4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
+
+<Callout type="warn">
+**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. For hard cancellation across processes, see [Distributed Abort Controller](/cookbook/advanced/distributed-abort-controller).
+</Callout>
+
+## Adapting to your use case
+
+- **Different durations** — `sleep()` accepts duration strings (`"30s"`, `"5m"`, `"7 days"`), milliseconds, or `Date` objects for absolute deadlines.
+- **Soft timeout (retry)** — instead of throwing, loop and retry with a fresh `Promise.race` and a backoff.
+- **Soft timeout (fallback)** — return a default value when the timer wins instead of throwing: `if (result === "timeout") return cachedFallback`.
+- **Combine with cancellation** — race three promises: the operation, a deadline `sleep()`, and a cancellation hook. See the [Scheduling cookbook](/cookbook/common-patterns/scheduling) for the cancellation half of this pattern.
+- **Per-step deadlines** — wrap each step in its own `Promise.race` for independent budgets, or use a single outer race for an overall workflow deadline.
+
+## Key APIs
+
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — create a webhook URL the workflow can race against
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — typed hook for in-process cancellation
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — race operations against deadlines

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -0,0 +1,118 @@
+---
+title: Workflow Composition
+description: Call workflows from other workflows by direct await (flatten into the parent) or background spawn via start() (separate run).
+type: guide
+summary: Compose workflows two ways — direct await flattens the child into the parent's event log, while background spawn via start() runs the child as an independent run.
+related:
+  - /cookbook/advanced/child-workflows
+  - /docs/api-reference/workflow-api/start
+  - /docs/api-reference/workflow-api/get-run
+---
+
+Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with polling and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).
+
+## When to use this
+
+- **Direct await** — the parent needs the child's result before continuing, and you want a single unified event log
+- **Background spawn** — the parent doesn't need to wait, and you want the child to be observable as a separate run with its own `runId`
+
+## Pattern
+
+### Direct await (flattening)
+
+Call a child workflow with `await` and the child's steps execute inline within the parent — they appear in the parent's event log as if you'd called them directly.
+
+```typescript lineNumbers
+declare function sendEmail(userId: string): Promise<void>; // @setup
+declare function sendPushNotification(userId: string): Promise<void>; // @setup
+declare function createAccount(userId: string): Promise<void>; // @setup
+declare function setupPreferences(userId: string): Promise<void>; // @setup
+
+// Child workflow
+export async function sendNotifications(userId: string) {
+  "use workflow";
+
+  await sendEmail(userId);
+  await sendPushNotification(userId);
+  return { notified: true };
+}
+
+// Parent workflow calls the child directly
+export async function onboardUser(userId: string) {
+  "use workflow";
+
+  await createAccount(userId);
+  await sendNotifications(userId); // [!code highlight]
+  await setupPreferences(userId);
+
+  return { userId, status: "onboarded" };
+}
+```
+
+The parent waits for the child to finish before continuing. Both functions share a single workflow run, a single retry boundary, and a single event log.
+
+### Background spawn via `start()`
+
+To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+
+declare function generateReport(reportId: string): Promise<void>; // @setup
+declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
+declare function sendConfirmation(orderId: string): Promise<void>; // @setup
+
+async function triggerReportGeneration(reportId: string) {
+  "use step"; // [!code highlight]
+
+  const run = await start(generateReport, [reportId]); // [!code highlight]
+  return run.runId;
+}
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const order = await fulfillOrder(orderId);
+
+  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
+
+  await sendConfirmation(orderId);
+
+  return { orderId, reportRunId };
+}
+```
+
+The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).
+
+<Callout type="info">
+If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+</Callout>
+
+## How it works
+
+1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
+2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
+3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.
+
+## Choosing between the two modes
+
+| | Direct await | Background spawn (`start()`) |
+| --- | --- | --- |
+| Parent waits for child | Yes | No |
+| Has its own `runId` | No (shares parent's) | Yes |
+| Has its own event log | No | Yes |
+| Has its own retry boundary | No | Yes |
+| Best for | Sequential composition, helper workflows | Independent work, fire-and-forget, fan-out |
+
+## Adapting to your use case
+
+- **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
+- **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
+- **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
+- [`start()`](/docs/api-reference/workflow-api/start) — spawn a child workflow as a separate run
+- [`getRun()`](/docs/api-reference/workflow-api/get-run) — retrieve a workflow run's status and return value

package/docs/cookbook/index.mdx

@@ -6,36 +6,33 @@ type: overview
 
 A curated collection of workflow patterns with clean, copy-paste code examples for real use cases.
 
+## Agent Patterns
+
+- [**Durable Agent**](/cookbook/agent-patterns/durable-agent) — Replace a stateless AI agent with one that survives crashes and retries tool calls
+- [**Human-in-the-Loop**](/cookbook/agent-patterns/human-in-the-loop) — Pause an agent for human approval, then resume based on the decision
+- [**Agent Cancellation**](/cookbook/agent-patterns/agent-cancellation) — Stop a running agent immediately via `run.cancel()` or gracefully via a hook + `Promise.race`
+
 ## Common Patterns
 
+- [**Sequential & Parallel Execution**](/cookbook/common-patterns/sequential-and-parallel) — Compose steps with `await`, `Promise.all`, and `Promise.race` against durable sleeps and webhooks
+- [**Workflow Composition**](/cookbook/common-patterns/workflow-composition) — Call workflows from other workflows by direct await or background spawn via `start()`
 - [**Saga**](/cookbook/common-patterns/saga) — Coordinate multi-step transactions with automatic rollback when a step fails
 - [**Batching**](/cookbook/common-patterns/batching) — Process large collections in parallel batches with failure isolation
 - [**Rate Limiting**](/cookbook/common-patterns/rate-limiting) — Handle 429 responses and transient failures with RetryableError and backoff
-- [**Fan-Out**](/cookbook/common-patterns/fan-out) — Send to multiple channels in parallel with independent failure handling
 - [**Scheduling**](/cookbook/common-patterns/scheduling) — Use durable sleep to schedule actions minutes, hours, or weeks ahead
+- [**Timeouts**](/cookbook/common-patterns/timeouts) — Add deadlines to slow steps, hooks, and webhooks by racing them against a durable sleep
 - [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects happen exactly once, even when steps retry
 - [**Webhooks**](/cookbook/common-patterns/webhooks) — Receive HTTP callbacks from external services and process them durably
-- [**Conditional Routing**](/cookbook/common-patterns/content-router) — Route payloads to different step handlers based on content
-- [**Child Workflows**](/cookbook/common-patterns/child-workflows) — Spawn and orchestrate child workflows from a parent
-
-## Agent Patterns
-
-- [**Durable Agent**](/cookbook/agent-patterns/durable-agent) — Replace a stateless AI agent with one that survives crashes and retries tool calls
-- [**Tool Streaming**](/cookbook/agent-patterns/tool-streaming) — Stream real-time progress updates from tools to the UI
-- [**Human-in-the-Loop**](/cookbook/agent-patterns/human-in-the-loop) — Pause an agent for human approval, then resume based on the decision
-- [**Tool Orchestration**](/cookbook/agent-patterns/tool-orchestration) — Choose between step-level and workflow-level tools, or combine both
-- [**Stop Workflow**](/cookbook/agent-patterns/stop-workflow) — Gracefully cancel a running agent workflow using a hook signal
 
 ## Integrations
 
-- [**AI SDK**](/cookbook/integrations/ai-sdk) — Use AI SDK model providers, tool calling, and streaming inside durable workflows
+- [**AI SDK**](/cookbook/integrations/ai-sdk) — Use streamText() directly inside a workflow for lower-level control over model calls and tool execution
 - [**Chat SDK**](/cookbook/integrations/chat-sdk) — Build durable chat sessions with workflow persistence and AI SDK chat primitives
 - [**Sandbox**](/cookbook/integrations/sandbox) — Orchestrate Vercel Sandbox lifecycle inside durable workflows
 
 ## Advanced
 
-- [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable objects so they cross the workflow boundary
-- [**Durable Objects**](/cookbook/advanced/durable-objects) — Model long-lived stateful entities as workflows
-- [**Isomorphic Packages**](/cookbook/advanced/isomorphic-packages) — Publish packages that work inside and outside the workflow runtime
-- [**Custom Serialization**](/cookbook/advanced/custom-serialization) — Make custom classes survive workflow serialization
+- [**Child Workflows**](/cookbook/advanced/child-workflows) — Spawn and orchestrate child workflows from a parent
+- [**Distributed Abort Controller**](/cookbook/advanced/distributed-abort-controller) — Build a cross-process abort controller using workflow streams and hooks
+- [**Serializable Steps**](/cookbook/advanced/serializable-steps) — Wrap non-serializable third-party objects so they cross the workflow boundary
 - [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions