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

package/docs/cookbook/common-patterns/fan-out.mdx

@@ -1,208 +0,0 @@
----
-title: Fan-Out & Parallel Delivery
-description: Send a message to multiple channels or recipients in parallel with independent failure handling.
-type: guide
-summary: Fan out an incident alert to Slack, email, SMS, and PagerDuty simultaneously using Promise.allSettled, so a failure in one channel does not block the others.
----
-
-Use fan-out when one event needs to trigger multiple independent actions in parallel. Each action runs as its own step, so failures are isolated -- a Slack outage doesn't prevent the email from sending.
-
-## When to use this
-
-- Incident alerting across multiple channels (Slack, email, SMS, PagerDuty)
-- Notifying a list of recipients determined at runtime
-- Any "broadcast" where each delivery is independent
-
-## Pattern: Static fan-out
-
-Define one step per channel and launch them all with `Promise.allSettled()`:
-
-```typescript
-declare function sendSlackAlert(incidentId: string, message: string): Promise<any>; // @setup
-declare function sendEmailAlert(incidentId: string, message: string): Promise<any>; // @setup
-declare function sendSmsAlert(incidentId: string, message: string): Promise<any>; // @setup
-declare function sendPagerDutyAlert(incidentId: string, message: string): Promise<any>; // @setup
-
-export async function incidentFanOut(incidentId: string, message: string) {
-  "use workflow";
-
-  const settled = await Promise.allSettled([ // [!code highlight]
-    sendSlackAlert(incidentId, message),
-    sendEmailAlert(incidentId, message),
-    sendSmsAlert(incidentId, message),
-    sendPagerDutyAlert(incidentId, message),
-  ]); // [!code highlight]
-
-  const ok = settled.filter((r) => r.status === "fulfilled").length;
-  return { incidentId, delivered: ok, failed: settled.length - ok };
-}
-```
-
-### Step functions
-
-Each channel is a separate `"use step"` function. Steps have full Node.js access and retry automatically on transient failures.
-
-```typescript
-async function sendSlackAlert(incidentId: string, message: string) {
-  "use step";
-  await fetch("https://hooks.slack.com/services/T.../B.../xxx", {
-    method: "POST",
-    body: JSON.stringify({ text: `[${incidentId}] ${message}` }),
-  });
-  return { channel: "slack" };
-}
-
-async function sendEmailAlert(incidentId: string, message: string) {
-  "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: "oncall@example.com" }],
-      subject: `Incident ${incidentId}`,
-      content: [{ type: "text/plain", value: message }],
-    }),
-  });
-  return { channel: "email" };
-}
-
-async function sendSmsAlert(incidentId: string, message: string) {
-  "use step";
-  // Call Twilio or similar SMS provider
-  return { channel: "sms" };
-}
-
-async function sendPagerDutyAlert(incidentId: string, message: string) {
-  "use step";
-  // Call PagerDuty Events API
-  return { channel: "pagerduty" };
-}
-```
-
-## Pattern: Dynamic recipient list
-
-When recipients are determined at runtime (e.g., severity-based routing), build the list dynamically:
-
-```typescript
-type Severity = "info" | "warning" | "critical";
-
-const RULES = [
-  { channel: "slack", match: () => true },
-  { channel: "email", match: (s: Severity) => s === "warning" || s === "critical" },
-  { channel: "pagerduty", match: (s: Severity) => s === "critical" },
-];
-
-export async function alertByRecipientList(
-  alertId: string,
-  message: string,
-  severity: Severity
-) {
-  "use workflow";
-
-  const matched = RULES.filter((r) => r.match(severity)).map((r) => r.channel);
-
-  const settled = await Promise.allSettled( // [!code highlight]
-    matched.map((channel) => deliverToChannel(channel, alertId, message))
-  ); // [!code highlight]
-
-  const delivered = settled.filter((r) => r.status === "fulfilled").length;
-  return { alertId, severity, matched, delivered, failed: matched.length - delivered };
-}
-
-async function deliverToChannel(
-  channel: string,
-  alertId: string,
-  message: string
-): Promise<void> {
-  "use step";
-  // Route to the appropriate API based on channel name
-  await fetch(`https://notifications.example.com/${channel}`, {
-    method: "POST",
-    body: JSON.stringify({ alertId, message }),
-  });
-}
-```
-
-## Pattern: Publish-subscribe
-
-When subscribers are managed in a registry and filtered by topic:
-
-```typescript
-type Subscriber = { id: string; name: string; topics: string[] };
-
-export async function publishEvent(topic: string, payload: string) {
-  "use workflow";
-
-  const subscribers = await loadSubscribers();
-  const matched = subscribers.filter((sub) => sub.topics.includes(topic));
-
-  await Promise.allSettled( // [!code highlight]
-    matched.map((sub) => deliverToSubscriber(sub.id, topic, payload))
-  ); // [!code highlight]
-
-  return { topic, delivered: matched.length, total: subscribers.length };
-}
-
-async function loadSubscribers(): Promise<Subscriber[]> {
-  "use step";
-  // Load from database or configuration service
-  return [
-    { id: "sub-1", name: "Order Service", topics: ["orders", "inventory"] },
-    { id: "sub-2", name: "Email Notifier", topics: ["orders", "shipping"] },
-    { id: "sub-3", name: "Analytics", topics: ["orders", "inventory", "shipping"] },
-  ];
-}
-
-async function deliverToSubscriber(
-  subscriberId: string,
-  topic: string,
-  payload: string
-): Promise<void> {
-  "use step";
-  await fetch(`https://subscribers.example.com/${subscriberId}/deliver`, {
-    method: "POST",
-    body: JSON.stringify({ topic, payload }),
-  });
-}
-```
-
-## Deferred await (background steps)
-
-You don't have to await a step immediately. Start a step, do other work, and collect the result later. This is different from `Promise.all` -- you interleave sequential and parallel work instead of waiting for everything at once.
-
-```typescript
-declare function generateReport(data: Record<string, string>): Promise<any>; // @setup
-declare function sendNotification(userId: string, message: string): Promise<void>; // @setup
-declare function updateDashboard(userId: string): Promise<void>; // @setup
-
-export async function onboardUser(userId: string, data: Record<string, string>) {
-  "use workflow";
-
-  // Start report generation in the background
-  const reportPromise = generateReport(data); // [!code highlight]
-
-  // Do other work while the report generates
-  await sendNotification(userId, "Processing started");
-  await updateDashboard(userId);
-
-  // Now await the report when we actually need it
-  const report = await reportPromise; // [!code highlight]
-  return { userId, report };
-}
-```
-
-The workflow runtime tracks the background step like any other. If the workflow replays, the already-completed step returns its cached result instantly.
-
-## Tips
-
-- **Use `Promise.allSettled` over `Promise.all`.** `allSettled` lets you know which channels failed without aborting the others.
-- **Each delivery is an independent step.** Transient failures (e.g., Slack 503) trigger automatic retries without affecting other channels.
-- **Use `FatalError` for permanent failures** (e.g., PagerDuty not configured) to stop retries on that channel while letting others continue.
-- **Dynamic recipient lists** decouple routing from delivery -- adding a new channel is a configuration change, not a code change.
-
-## 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
-- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- fans out to all targets, isolating failures
-- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- prevents automatic retry for permanent failures

package/docs/foundations/common-patterns.mdx

@@ -1,265 +0,0 @@
----
-title: Common Patterns
-description: Implement distributed patterns using familiar async/await syntax with no new APIs to learn.
-type: guide
-summary: Apply sequential, parallel, timeout, and composition patterns in workflows.
-prerequisites:
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/foundations/errors-and-retries
-  - /docs/foundations/hooks
----
-
-Common distributed patterns are simple to implement in workflows and require learning no new syntax. You can just use familiar async/await patterns.
-
-## Sequential Execution
-
-The simplest way to orchestrate steps is to execute them one after another, where each step can be dependent on the previous step.
-
-```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 Execution
-
-When you need to execute multiple steps in parallel, you can use `Promise.all` to run them all at the same time.
-
-```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 };
-}
-```
-
-This not only applies to steps - since [`sleep()`](/docs/api-reference/workflow/sleep) and [`webhook`](/docs/api-reference/workflow/create-webhook) are also just promises, we can await those in parallel too.
-We can also use `Promise.race` instead of `Promise.all` to stop executing promises after the first one completes.
-
-```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); // Send the webhook somewhere
-
-  // Wait for the external webhook to be hit, with a timeout of 1 day,
-  // whichever comes first
-  await Promise.race([ // [!code highlight]
-    webhook, // [!code highlight]
-    sleep("1 day"), // [!code highlight]
-  ]); // [!code highlight]
-
-  console.log("Done")
-}
-```
-
-## A Full Example
-
-Here's a simplified example taken from the [birthday card generator demo](https://github.com/vercel/workflow-examples/tree/main/birthday-card-generator), to illustrate how sequential and parallel execution can be combined.
-
-```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
-
-async function birthdayWorkflow(
-    prompt: string,
-    email: string,
-    friends: string[],
-    birthday: Date
-) {
-    "use workflow";
-
-    // Generate a birthday card with sequential steps
-    const text = await makeCardText(prompt)
-    const image = await makeCardImage(text)
-
-    // Create webhooks for each friend who's invited to the birthday party
-    const webhooks = friends.map(_ => createWebhook())
-
-    // Send out all the RSVP invites in parallel steps
-    await Promise.all(
-        friends.map(
-            (friend, i) => sendRSVPEmail(friend, webhooks[i])
-        )
-    )
-
-    // Collect RSVPs as they are made without blocking the workflow
-    let rsvps = []
-    webhooks.map(
-        webhook => webhook
-            .then(req => req.json())
-            .then(( { rsvp } ) => rsvps.push(rsvp))
-    )
-
-    // Wait until the birthday
-    await sleep(birthday)
-
-    // Send birthday card with as many rsvps were collected
-    await sendBirthdayCard(text, image, rsvps, email)
-
-    return { text, image, status: "Sent" }
-}
-```
-
-## Timeout Pattern
-
-A common requirement is adding timeouts to operations that might take too long. Use `Promise.race` with `sleep()` to implement this pattern.
-
-```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") {
-    // In workflows, any thrown error exits the workflow (FatalError is for steps)
-    throw new Error("Processing timed out after 30 seconds");
-  }
-
-  return result;
-}
-```
-
-This pattern works with any promise-returning operation including steps, hooks, and webhooks. For example, you can add a timeout to a webhook that waits for external input:
-
-```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;
-}
-```
-
-## Workflow Composition
-
-Workflows can call other workflows, enabling you to break complex processes into reusable building blocks. There are two approaches depending on your needs.
-
-### Direct Await (Flattening)
-
-Call a child workflow directly using `await`. This "flattens" the child workflow into the parent - the child's steps execute inline within the parent workflow's context.
-
-```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 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" };
-}
-```
-
-With direct await, the parent workflow waits for the child to complete before continuing. The child's steps appear in the parent's event log as if they were called directly from the parent.
-
-### Background Execution via Step
-
-To run a child workflow independently without blocking the parent, use a step that calls [`start()`](/docs/api-reference/workflow-api/start). This launches the child workflow in the background.
-
-```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
-
-// Step that starts a workflow in the background
-async function triggerReportGeneration(reportId: string) {
-  "use step";
-
-  const run = await start(generateReport, [reportId]); // [!code highlight]
-  return run.runId;
-}
-
-// Parent workflow
-export async function processOrder(orderId: string) {
-  "use workflow";
-
-  const order = await fulfillOrder(orderId);
-
-  // Fire off report generation without waiting
-  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
-
-  // Continue immediately - report generates in background
-  await sendConfirmation(orderId);
-
-  return { orderId, reportRunId };
-}
-```
-
-With background execution, the parent workflow continues immediately after starting the child. The child workflow runs independently with its own event log and can be monitored separately using the returned `runId`.
-
-<Callout type="info">
-If you want the child workflow to run on the latest deployment rather than the current one, you can 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>
-
-**Choose direct await when:**
-- The parent needs the child's result before continuing
-- You want a single, unified event log
-
-**Choose background execution when:**
-- The parent doesn't need to wait for the result
-- You want separate workflow runs for observability