workflow 5.0.0-beta.1 → 5.0.0-beta.3

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

@@ -0,0 +1,247 @@
+---
+title: Transactions & Rollbacks (Saga)
+description: Coordinate multi-step transactions with automatic rollback when a step fails.
+type: guide
+summary: Run a sequence of steps where each registers a compensation. If any step throws a FatalError, compensations execute in reverse order to restore consistency.
+---
+
+Use the saga pattern when a business transaction spans multiple services and you need automatic rollback if any step fails. Each forward step registers a compensation, and on failure the workflow unwinds them in reverse order.
+
+## When to use this
+
+- Multi-service transactions (reserve inventory, charge payment, provision access)
+- Any sequence where partial completion leaves the system in an inconsistent state
+- Operations that need "all or nothing" semantics across external APIs
+
+## How it works
+
+1. Each forward step does work and registers a compensation function.
+2. If any step throws `FatalError`, the catch block runs compensations in reverse (LIFO) order to restore consistency.
+3. Regular errors are retried automatically (up to 3x by default). Use `FatalError` only for permanent failures where retrying won't help.
+
+## Pattern
+
+Each step returns a result and pushes a compensation handler onto a stack. If a later step throws a `FatalError`, the workflow catches it and executes compensations in LIFO order.
+
+```typescript
+import { FatalError } from "workflow";
+
+declare function reserveSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function releaseSeats(accountId: string, reservationId: string): Promise<void>; // @setup
+declare function captureInvoice(accountId: string, seats: number): Promise<string>; // @setup
+declare function refundInvoice(accountId: string, invoiceId: string): Promise<void>; // @setup
+declare function provisionSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function deprovisionSeats(accountId: string, entitlementId: string): Promise<void>; // @setup
+declare function sendConfirmation(accountId: string, invoiceId: string, entitlementId: string): Promise<void>; // @setup
+
+export async function subscriptionUpgradeSaga(accountId: string, seats: number) {
+  "use workflow";
+
+  const compensations: Array<() => Promise<void>> = [];
+
+  try {
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push(() => releaseSeats(accountId, reservationId)); // [!code highlight]
+
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push(() => refundInvoice(accountId, invoiceId)); // [!code highlight]
+
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push(() => deprovisionSeats(accountId, entitlementId)); // [!code highlight]
+
+    // No compensation — notifications are fire-and-forget
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+
+    return { status: "completed" };
+  } catch (error) {
+    // Unwind compensations in reverse (LIFO) order
+    for (const compensate of compensations.reverse()) { // [!code highlight]
+      await compensate(); // [!code highlight]
+    }
+
+    return { status: "rolled_back" };
+  }
+}
+```
+
+### Step functions
+
+Each step is a `"use step"` function with full Node.js access (fetch, fs, npm packages). Forward steps do the work and throw `FatalError` on permanent failure; compensation steps undo it and must be idempotent — safe to call multiple times if the workflow restarts mid-rollback.
+
+```typescript
+import { FatalError } from "workflow";
+
+// Forward steps
+
+async function reserveSeats(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/seats/reserve`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Seat reservation failed"); // [!code highlight]
+  const { reservationId } = await res.json();
+  return reservationId;
+}
+
+async function captureInvoice(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/invoices`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Invoice capture failed"); // [!code highlight]
+  const { invoiceId } = await res.json();
+  return invoiceId;
+}
+
+async function provisionSeats(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/entitlements`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Provisioning failed"); // [!code highlight]
+  const { entitlementId } = await res.json();
+  return entitlementId;
+}
+
+async function sendConfirmation(
+  accountId: string,
+  invoiceId: string,
+  entitlementId: string
+): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/notifications`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, invoiceId, entitlementId, template: "upgrade-complete" }),
+  });
+}
+
+// Compensation steps — must be idempotent
+
+async function releaseSeats(accountId: string, reservationId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/seats/release`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, reservationId }),
+  });
+}
+
+async function refundInvoice(accountId: string, invoiceId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/invoices/${invoiceId}/refund`, {
+    method: "POST",
+    body: JSON.stringify({ accountId }),
+  });
+}
+
+async function deprovisionSeats(accountId: string, entitlementId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/entitlements/${entitlementId}`, {
+    method: "DELETE",
+    body: JSON.stringify({ accountId }),
+  });
+}
+```
+
+### Streaming step progress (optional)
+
+Use `getWritable()` to stream progress events to a UI so users can see each step execute in real time.
+
+```typescript
+import { FatalError } from "workflow";
+import { getWritable } from "workflow";
+
+type SagaEvent =
+  | { type: "step_start"; step: string }
+  | { type: "step_done"; step: string; detail: string }
+  | { type: "step_failed"; step: string; error: string }
+  | { type: "compensating"; step: string }
+  | { type: "compensated"; step: string }
+  | { type: "result"; status: "completed" | "rolled_back" };
+
+async function emit(event: SagaEvent) {
+  "use step";
+  const writer = getWritable<SagaEvent>().getWriter();
+  try {
+    await writer.write(event);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+declare function reserveSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function releaseSeats(accountId: string, reservationId: string): Promise<void>; // @setup
+declare function captureInvoice(accountId: string, seats: number): Promise<string>; // @setup
+declare function refundInvoice(accountId: string, invoiceId: string): Promise<void>; // @setup
+declare function provisionSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function deprovisionSeats(accountId: string, entitlementId: string): Promise<void>; // @setup
+declare function sendConfirmation(accountId: string, invoiceId: string, entitlementId: string): Promise<void>; // @setup
+
+export async function subscriptionUpgradeSaga(accountId: string, seats: number) {
+  "use workflow";
+
+  const compensations: Array<{ name: string; execute: () => Promise<void> }> = [];
+
+  try {
+    await emit({ type: "step_start", step: "Reserve Seats" });
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push({ name: "Release Seats", execute: () => releaseSeats(accountId, reservationId) });
+    await emit({ type: "step_done", step: "Reserve Seats", detail: reservationId });
+
+    await emit({ type: "step_start", step: "Capture Invoice" });
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push({ name: "Refund Invoice", execute: () => refundInvoice(accountId, invoiceId) });
+    await emit({ type: "step_done", step: "Capture Invoice", detail: invoiceId });
+
+    await emit({ type: "step_start", step: "Provision Seats" });
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push({ name: "Deprovision Seats", execute: () => deprovisionSeats(accountId, entitlementId) });
+    await emit({ type: "step_done", step: "Provision Seats", detail: entitlementId });
+
+    // No compensation — notifications are fire-and-forget
+    await emit({ type: "step_start", step: "Send Confirmation" });
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+    await emit({ type: "step_done", step: "Send Confirmation", detail: "sent" });
+
+    await emit({ type: "result", status: "completed" });
+    return { status: "completed" };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    await emit({ type: "step_failed", step: "failed", error: errorMessage });
+
+    // Unwind compensations in reverse (LIFO) order
+    for (const comp of compensations.reverse()) {
+      await emit({ type: "compensating", step: comp.name });
+      await comp.execute();
+      await emit({ type: "compensated", step: comp.name });
+    }
+
+    await emit({ type: "result", status: "rolled_back" });
+    return { status: "rolled_back" };
+  }
+}
+```
+
+## Adapting to your use case
+
+- Replace the step functions with real API calls. Each `"use step"` function has full Node.js access.
+- Add or remove steps as needed — the pattern scales to any number of steps.
+- Make compensations idempotent — they may be retried if the workflow restarts mid-rollback.
+- The `emit()` calls and `SagaEvent` type are optional — remove them if you don't need real-time UI progress.
+
+## Tips
+
+- **Use `FatalError` for permanent failures.** Regular errors trigger automatic retries (up to 3 by default). Throw `FatalError` when retrying won't help (e.g., insufficient funds, invalid input).
+- **Make compensations idempotent.** If a compensation step is retried, it should produce the same result. Check whether the resource was already released before releasing it again.
+- **Compensation steps are also `"use step"` functions.** This makes them durable — if the workflow restarts mid-rollback, it resumes where it left off.
+- **Capture values in closures carefully.** Use block-scoped variables or copy values before pushing compensations to avoid referencing stale state.
+- **Notifications don't need compensations.** Fire-and-forget steps like sending emails or Slack messages typically don't register a compensation.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) -- declares step functions with full Node.js access
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- non-retryable error that triggers compensation
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates

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

@@ -0,0 +1,125 @@
+---
+title: Sleep, Scheduling & Timed Workflows
+description: Use durable sleep to schedule actions minutes, hours, days, or weeks into the future.
+type: guide
+summary: Schedule future actions with durable sleep that survives cold starts, and race sleeps against hooks to let external events cancel the workflow early.
+---
+
+Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
+
+## When to use this
+
+- Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)
+- Waiting for a deadline but allowing early cancellation
+- Any pattern where "do X, wait N hours, then do Y" needs to be both reliable and interruptible
+
+## Drip campaign with cancellation
+
+A drip campaign sends emails at intervals, sleeping between each. Each sleep races against a cancellation hook — if an external event fires the hook (e.g. user converts, unsubscribes), the campaign stops immediately.
+
+```typescript
+import { defineHook, sleep } from "workflow";
+
+// Hook that any API route can fire to cancel the drip
+export const cancelDrip = defineHook<{ reason?: string }>(); // [!code highlight]
+
+async function sendEmail(email: string, template: string): Promise<void> {
+  "use step";
+  await fetch("https://api.sendgrid.com/v3/mail/send", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${process.env.SENDGRID_KEY}` },
+    body: JSON.stringify({ to: [{ email }], template_id: template }),
+  });
+}
+
+export async function emailSequence(email: string) {
+  "use workflow";
+
+  await sendEmail(email, "welcome");
+
+  // Race durable sleep against the cancellation hook
+  const hook = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled) return { status: "cancelled", email };
+
+  await sendEmail(email, "getting-started-tips");
+
+  // Create a fresh hook for the next sleep window
+  const hook2 = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled2 = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook2.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled2) return { status: "cancelled", email };
+
+  await sendEmail(email, "feature-highlights");
+
+  return { status: "drip-complete", email };
+}
+```
+
+### Cancelling from an API route
+
+Any server-side code can fire the hook by calling `.resume()` with the same token:
+
+```typescript
+import { cancelDrip } from "@/workflows/email-sequence";
+
+export async function POST(req: Request) {
+  const { email, reason } = await req.json();
+
+  if (!email) {
+    return Response.json({ error: "email is required" }, { status: 400 });
+  }
+
+  try {
+    await cancelDrip.resume(`cancel-drip:${email}`, { // [!code highlight]
+      reason: reason ?? "User completed action", // [!code highlight]
+    }); // [!code highlight]
+  } catch (error) {
+    const msg = error instanceof Error ? error.message.toLowerCase() : "";
+    if (msg.includes("not found") || msg.includes("expired")) {
+      return Response.json({
+        success: true,
+        email,
+        note: "No active drip found (already completed or cancelled)",
+      });
+    }
+    throw error;
+  }
+
+  return Response.json({ success: true, email });
+}
+```
+
+## How it works
+
+1. **Durable sleep** — `sleep("2d")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
+2. **Hook creation** — `cancelDrip.create({ token })` registers a hook that resolves when any external system calls `.resume()` with the same token.
+3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
+4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
+
+## Adapting to your use case
+
+- **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.
+- **Add more steps** — the pattern scales to any number of email-then-sleep pairs.
+- **Snooze instead of cancel** — resolve the hook with a `snooze` payload and sleep again: `sleep(new Date(Date.now() + payload.snoozeMs))`.
+- **Timeout any operation** — the same `Promise.race(sleep, work)` pattern works for adding deadlines to slow steps.
+- **Real providers** — swap the `sendEmail` step body for Resend, Postmark, or any HTTP API. The `"use step"` function has full Node.js access.
+
+## Tips
+
+- **`sleep()` accepts** duration strings (`"1d"`, `"2h"`, `"30s"`), milliseconds, or `Date` objects for sleeping until a specific time.
+- **Durable means durable.** A `sleep("7d")` workflow costs nothing while sleeping — no compute, no memory.
+- **Use `sleep()` in workflow context only.** Step functions cannot call `sleep()` directly. If a step needs a delay, use `setTimeout` inside the step.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions that run with full Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — creates a typed hook that external systems can fire
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — races sleep against hooks for interruptible waits

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