workflow 5.0.0-beta.0 → 5.0.0-beta.2

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

@@ -0,0 +1,152 @@
+---
+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
+
+## 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 {
+    // Step 1: Reserve seats
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push(() => releaseSeats(accountId, reservationId)); // [!code highlight]
+
+    // Step 2: Capture payment
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push(() => refundInvoice(accountId, invoiceId)); // [!code highlight]
+
+    // Step 3: Provision access
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push(() => deprovisionSeats(accountId, entitlementId)); // [!code highlight]
+
+    // Step 4: Notify
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+    return { status: "completed" };
+  } catch (error) {
+    // Unwind compensations in reverse 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. Forward steps do the work; compensation steps undo it.
+
+```typescript
+import { FatalError } from "workflow";
+
+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 releaseSeats(accountId: string, reservationId: string): Promise<void> {
+  "use step";
+  // Compensations should be idempotent — safe to call twice
+  await fetch(`https://api.example.com/seats/release`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, 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 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 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 deprovisionSeats(accountId: string, entitlementId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/entitlements/${entitlementId}`, {
+    method: "DELETE",
+    body: JSON.stringify({ accountId }),
+  });
+}
+
+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" }),
+  });
+}
+```
+
+## 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.
+
+## 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

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

@@ -0,0 +1,249 @@
+---
+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 wake the workflow early.
+---
+
+Workflow's `sleep()` is durable -- it survives cold starts, restarts, and deployments. This makes it the foundation for scheduled actions, drip campaigns, reminders, and any pattern that needs to wait for real-world time to pass.
+
+## When to use this
+
+- Sending emails on a schedule (drip campaigns, reminders, digests)
+- Waiting for a deadline before taking action
+- Any pattern where "do X, wait N hours, then do Y" needs to be reliable
+
+## Pattern: Drip campaign
+
+Send emails at scheduled intervals using `sleep()` between steps. The workflow runs for days or weeks, sleeping between each email.
+
+```typescript
+import { sleep } from "workflow";
+
+export async function onboardingDrip(email: string) {
+  "use workflow";
+
+  await sendEmail(email, "welcome");
+
+  await sleep("1d"); // [!code highlight]
+  await sendEmail(email, "getting-started-tips");
+
+  await sleep("2d"); // [!code highlight]
+  await sendEmail(email, "feature-highlights");
+
+  await sleep("4d"); // [!code highlight]
+  await sendEmail(email, "follow-up");
+
+  return { email, status: "completed", totalDays: 7 };
+}
+
+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,
+    }),
+  });
+}
+```
+
+## Pattern: Interruptible reminder (sleep vs hook)
+
+Race a `sleep()` against a `defineHook` so external events can cancel, snooze, or send early:
+
+```typescript
+import { defineHook, sleep } from "workflow";
+
+type ReminderAction =
+  | { type: "cancel" }
+  | { type: "send_now" }
+  | { type: "snooze"; seconds: number };
+
+export const reminderActionHook = defineHook<ReminderAction>();
+
+export async function scheduleReminder(userId: string, delayMs: number) {
+  "use workflow";
+
+  let sendAt = new Date(Date.now() + delayMs);
+  const action = reminderActionHook.create({ token: `reminder:${userId}` });
+
+  const outcome = await Promise.race([ // [!code highlight]
+    sleep(sendAt).then(() => ({ kind: "time" as const })), // [!code highlight]
+    action.then((payload) => ({ kind: "action" as const, payload })), // [!code highlight]
+  ]);
+
+  if (outcome.kind === "action") {
+    if (outcome.payload.type === "cancel") {
+      return { userId, status: "cancelled" };
+    }
+    if (outcome.payload.type === "snooze") {
+      sendAt = new Date(Date.now() + outcome.payload.seconds * 1000);
+      await sleep(sendAt);
+    }
+    // "send_now" falls through to send immediately
+  }
+
+  await sendReminderEmail(userId);
+  return { userId, status: "sent" };
+}
+
+async function sendReminderEmail(userId: string): Promise<void> {
+  "use step";
+  await fetch("https://api.example.com/reminders/send", {
+    method: "POST",
+    body: JSON.stringify({ userId }),
+  });
+}
+```
+
+To wake the reminder early from an API route:
+
+```typescript
+import { resumeHook } from "workflow/api";
+
+// POST /api/reminder/cancel
+export async function POST(request: Request) {
+  const { userId } = await request.json();
+  await resumeHook(`reminder:${userId}`, { type: "cancel" }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Pattern: Timed collection window (digest)
+
+Open a collection window using `sleep()` and accumulate events from a hook until the window closes:
+
+```typescript
+import { sleep, defineHook } from "workflow";
+
+type EventPayload = { type: string; message: string };
+
+export const digestEvent = defineHook<EventPayload>();
+
+export async function collectAndSendDigest(
+  digestId: string,
+  userId: string,
+  windowMs: number = 3_600_000
+) {
+  "use workflow";
+
+  const hook = digestEvent.create({ token: `digest:${digestId}` });
+  const windowClosed = sleep(`${windowMs}ms`).then(() => ({
+    kind: "window_closed" as const,
+  }));
+  const events: EventPayload[] = [];
+
+  while (true) {
+    const outcome = await Promise.race([ // [!code highlight]
+      hook.then((payload) => ({ kind: "event" as const, payload })),
+      windowClosed,
+    ]);
+
+    if (outcome.kind === "window_closed") break; // [!code highlight]
+    events.push(outcome.payload);
+  }
+
+  if (events.length > 0) {
+    await sendDigestEmail(userId, events);
+  }
+
+  return { digestId, status: events.length > 0 ? "sent" : "empty", eventCount: events.length };
+}
+
+async function sendDigestEmail(userId: string, events: EventPayload[]): Promise<void> {
+  "use step";
+  await fetch("https://api.example.com/digest/send", {
+    method: "POST",
+    body: JSON.stringify({ userId, events }),
+  });
+}
+```
+
+## Pattern: Timeout
+
+Add a timeout to any operation by racing it against `sleep()`:
+
+```typescript
+import { sleep, FatalError } from "workflow";
+
+export async function processWithTimeout(jobId: string) {
+  "use workflow";
+
+  const result = await Promise.race([ // [!code highlight]
+    processData(jobId),
+    sleep("30s").then(() => "timeout" as const), // [!code highlight]
+  ]);
+
+  if (result === "timeout") {
+    return { jobId, status: "timed_out" };
+  }
+
+  return { jobId, status: "completed", result };
+}
+
+async function processData(jobId: string): Promise<string> {
+  "use step";
+  // Long-running computation
+  return `result-for-${jobId}`;
+}
+```
+
+## Polling external services
+
+When you need to poll an external service until a job completes, define your own `sleep` as a step function and use it in a polling loop. Each iteration becomes a separate step in the event log, making the entire loop durable.
+
+```typescript
+async function sleep(ms: number): Promise<void> {
+  "use step";
+  await new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function waitForTranscription(jobId: string) {
+  "use workflow";
+
+  let status = "processing";
+  let attempts = 0;
+  const maxAttempts = 36; // ~3 minutes at 5s intervals
+
+  while (status === "processing" && attempts < maxAttempts) {
+    await sleep(5000); // [!code highlight]
+    attempts++;
+    const result = await checkJobStatus(jobId); // [!code highlight]
+    status = result.status;
+  }
+
+  if (status !== "completed") {
+    return { jobId, status: "timed_out", attempts };
+  }
+
+  return { jobId, status: "completed", attempts };
+}
+
+async function checkJobStatus(jobId: string): Promise<{ status: string }> {
+  "use step";
+  const res = await fetch(`https://api.example.com/jobs/${jobId}`);
+  return res.json();
+}
+```
+
+**When to use this vs `sleep()` from `workflow`:**
+- Use `sleep()` from `workflow` for fixed, known delays (drip campaigns, reminders, cooldowns).
+- Use a custom sleep-as-step for polling loops where you need to check a condition between sleeps. The custom step version also works in libraries that don't want to import from the `workflow` module directly.
+
+## 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. It resumes precisely when the timer fires.
+- **Race `sleep` against `defineHook`** for interruptible waits. This is the standard pattern for reminders, approvals with deadlines, and timed collection windows.
+- **Use `sleep()` in workflow context only.** Step functions cannot call `sleep()` directly. If a step needs a delay, use a standard `setTimeout` or return control to the workflow.
+
+## 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 while sleeping)
+- [`defineHook`](/docs/api-reference/workflow/define-hook) -- creates a hook that external systems can trigger
+- [`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/webhooks.mdx

@@ -0,0 +1,185 @@
+---
+title: Webhooks & External Callbacks
+description: Receive HTTP callbacks from external services, process them durably, and respond inline.
+type: guide
+summary: Create webhook endpoints that your workflow can await, process incoming requests in steps, and respond to the caller — all within durable workflow context.
+---
+
+Use webhooks when external services push events to your application via HTTP callbacks. The workflow creates a webhook URL, suspends with zero compute cost, and resumes when a request arrives.
+
+## When to use this
+
+- Accepting callbacks from payment processors (Stripe, PayPal)
+- Waiting for third-party verification or processing results
+- Any integration where an external system calls you back asynchronously
+
+## Pattern: Processing webhook events
+
+Create a webhook with manual response control, then iterate over incoming requests:
+
+```typescript
+import { createWebhook, type RequestWithResponse } from "workflow";
+
+declare function processEvent(request: RequestWithResponse): Promise<{ type: string }>; // @setup
+
+export async function paymentWebhook(orderId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" }); // [!code highlight]
+  // webhook.url is the URL to give to the external service
+
+  const ledger: { type: string }[] = [];
+
+  for await (const request of webhook) { // [!code highlight]
+    const entry = await processEvent(request);
+    ledger.push(entry);
+
+    // Break when we've received a terminal event
+    if (entry.type === "payment.succeeded" || entry.type === "refund.created") {
+      break;
+    }
+  }
+
+  return { orderId, webhookUrl: webhook.url, ledger, status: "settled" };
+}
+```
+
+### Step function for processing
+
+Each webhook request is processed in its own step, giving you full Node.js access for validation, database writes, and responding to the caller:
+
+```typescript
+import { type RequestWithResponse } from "workflow";
+
+async function processEvent(
+  request: RequestWithResponse
+): Promise<{ type: string }> {
+  "use step";
+
+  const body = await request.json().catch(() => ({}));
+  const type = body?.type ?? "unknown";
+
+  // Validate, process, and respond inline
+  if (type === "payment.succeeded") {
+    // Record the payment in your database
+    await request.respondWith(Response.json({ ack: true, action: "captured" })); // [!code highlight]
+  } else if (type === "payment.failed") {
+    await request.respondWith(Response.json({ ack: true, action: "flagged" }));
+  } else {
+    await request.respondWith(Response.json({ ack: true, action: "ignored" }));
+  }
+
+  return { type };
+}
+```
+
+## Pattern: Async request-reply with timeout
+
+Submit a request to an external service, pass it your webhook URL, then race the callback against a deadline:
+
+```typescript
+import { createWebhook, sleep, FatalError, type RequestWithResponse } from "workflow";
+
+export async function asyncVerification(documentId: string) {
+  "use workflow";
+
+  const webhook = createWebhook({ respondWith: "manual" });
+
+  // Submit to vendor, passing our webhook URL for the callback
+  await submitToVendor(documentId, webhook.url);
+
+  // Race: wait for callback OR timeout after 30 seconds
+  const result = await Promise.race([ // [!code highlight]
+    (async () => {
+      for await (const request of webhook) {
+        const body = await processCallback(request);
+        return body;
+      }
+      throw new FatalError("Webhook closed without callback");
+    })(),
+    sleep("30s").then(() => ({ status: "timed_out" as const })), // [!code highlight]
+  ]);
+
+  return { documentId, ...result };
+}
+
+async function submitToVendor(documentId: string, callbackUrl: string): Promise<void> {
+  "use step";
+  await fetch("https://vendor.example.com/verify", {
+    method: "POST",
+    body: JSON.stringify({ documentId, callbackUrl }),
+  });
+}
+
+async function processCallback(
+  request: RequestWithResponse
+): Promise<{ status: string; details: string }> {
+  "use step";
+  const body = await request.json();
+  await request.respondWith(Response.json({ ack: true }));
+  return {
+    status: body.approved ? "verified" : "rejected",
+    details: body.details ?? body.reason ?? "",
+  };
+}
+```
+
+## Pattern: Large payload by reference
+
+When payloads are too large to serialize into the event log, pass a lightweight reference (a "claim check") instead. Use a hook to signal when the data is ready:
+
+```typescript
+import { defineHook } from "workflow";
+
+export const blobReady = defineHook<{ blobToken: string }>(); // [!code highlight]
+
+export async function importLargeFile(importId: string) {
+  "use workflow";
+
+  // Suspend until the external system signals the blob is uploaded
+  const { blobToken } = await blobReady.create({ token: `upload:${importId}` }); // [!code highlight]
+
+  // Process by reference -- the full payload never enters the event log
+  await processBlob(blobToken);
+
+  return { importId, blobToken, status: "indexed" };
+}
+
+async function processBlob(blobToken: string): Promise<void> {
+  "use step";
+  // Fetch the blob using the token, process it
+  const res = await fetch(`https://storage.example.com/blobs/${blobToken}`);
+  const data = await res.arrayBuffer();
+  // Index, transform, or store the data
+}
+```
+
+Resume from an API route when the upload completes:
+
+```typescript
+import { resumeHook } from "workflow/api";
+
+// POST /api/upload-complete
+export async function POST(request: Request) {
+  const { importId, blobToken } = await request.json();
+  await resumeHook(`upload:${importId}`, { blobToken }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Tips
+
+- **`respondWith: "manual"`** gives you control over the HTTP response from inside a step. Use this when you need to validate the request before responding.
+- **`for await` on a webhook** lets you process multiple events from the same URL. Use `break` to stop listening after a terminal event.
+- **Webhooks auto-generate URLs** at `/.well-known/workflow/v1/webhook/:token`. Pass this URL to external services.
+- **Race webhooks against `sleep()`** for deadlines. If the callback doesn't arrive in time, the workflow can take a fallback action.
+- **For large payloads**, use a hook + reference token instead of passing the data through the workflow. The event log serializes all step inputs/outputs, so large payloads hurt performance.
+
+## 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
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) -- creates an HTTP endpoint the workflow can await
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- creates a typed hook for signal-based patterns
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable timer for deadlines
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- prevents retry on permanent failures

package/docs/cookbook/index.mdx

@@ -0,0 +1,41 @@
+---
+title: Cookbook
+description: Best-practice workflow patterns with copy-paste code examples.
+type: overview
+---
+
+A curated collection of workflow patterns with clean, copy-paste code examples for real use cases.
+
+## Common Patterns
+
+- [**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
+- [**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
+- [**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
+- [**Publishing Libraries**](/cookbook/advanced/publishing-libraries) — Ship npm packages that export reusable workflow functions