workflow 5.0.0-beta.1 → 5.0.0-beta.2

package/docs/cookbook/common-patterns/content-router.mdx

@@ -0,0 +1,207 @@
+---
+title: Conditional Routing
+description: Inspect a payload and route it to different step handlers based on its content.
+type: guide
+summary: Classify incoming messages and branch to specialized handlers using standard if/else logic in the workflow function.
+---
+
+Use conditional routing when incoming messages need different processing paths depending on their content. A support ticket about billing goes to the billing handler; a bug report goes to engineering. The workflow inspects the payload and branches with standard JavaScript control flow.
+
+## When to use this
+
+- Support ticket routing by category
+- Order processing with different flows per product type
+- Event handling where different event types need different logic
+- Any message-driven system where the handler depends on the content
+
+## Pattern: Content-based router
+
+The workflow classifies the input, then branches with `if`/`else` to call the appropriate step:
+
+```typescript
+declare function classifyTicket(ticketId: string, subject: string): Promise<{ ticketType: string }>; // @setup
+declare function handleBilling(ticketId: string): Promise<void>; // @setup
+declare function handleTechnical(ticketId: string): Promise<void>; // @setup
+declare function handleAccount(ticketId: string): Promise<void>; // @setup
+declare function handleFeedback(ticketId: string): Promise<void>; // @setup
+
+export async function routeTicket(ticketId: string, subject: string) {
+  "use workflow";
+
+  const { ticketType } = await classifyTicket(ticketId, subject); // [!code highlight]
+
+  if (ticketType === "billing") { // [!code highlight]
+    await handleBilling(ticketId);
+  } else if (ticketType === "technical") {
+    await handleTechnical(ticketId);
+  } else if (ticketType === "account") {
+    await handleAccount(ticketId);
+  } else {
+    await handleFeedback(ticketId);
+  }
+
+  return { ticketId, routedTo: ticketType };
+}
+```
+
+### Step functions
+
+Each handler is a separate `"use step"` function. The classification step can use an LLM, keyword matching, or any logic you need:
+
+```typescript
+async function classifyTicket(
+  ticketId: string,
+  subject: string
+): Promise<{ ticketType: string }> {
+  "use step";
+
+  // Example: simple keyword classification
+  // In production, this could call an LLM or ML model
+  const lower = subject.toLowerCase();
+  if (lower.includes("invoice") || lower.includes("charge") || lower.includes("refund")) {
+    return { ticketType: "billing" };
+  }
+  if (lower.includes("error") || lower.includes("bug") || lower.includes("crash")) {
+    return { ticketType: "technical" };
+  }
+  if (lower.includes("password") || lower.includes("login") || lower.includes("access")) {
+    return { ticketType: "account" };
+  }
+  return { ticketType: "feedback" };
+}
+
+async function handleBilling(ticketId: string): Promise<void> {
+  "use step";
+  // Look up billing records, process refund, etc.
+}
+
+async function handleTechnical(ticketId: string): Promise<void> {
+  "use step";
+  // Create bug report, notify engineering, etc.
+}
+
+async function handleAccount(ticketId: string): Promise<void> {
+  "use step";
+  // Reset password, update permissions, etc.
+}
+
+async function handleFeedback(ticketId: string): Promise<void> {
+  "use step";
+  // Log feedback, notify product team, etc.
+}
+```
+
+## Pattern: Enrichment before routing
+
+When downstream handlers need more context than the raw input provides, enrich the message in parallel before routing:
+
+```typescript
+export async function enrichAndRoute(email: string) {
+  "use workflow";
+
+  // Step 1: Look up base data
+  const contact = await lookupContact(email);
+
+  // Step 2: Enrich from multiple sources in parallel
+  const [crm, social] = await Promise.allSettled([ // [!code highlight]
+    fetchCrmData(contact),
+    fetchSocialData(contact),
+  ]);
+
+  const enriched = {
+    ...contact,
+    crm: crm.status === "fulfilled" ? crm.value : null,
+    social: social.status === "fulfilled" ? social.value : null,
+  };
+
+  // Step 3: Route based on enriched data
+  if (enriched.crm?.segment === "enterprise") { // [!code highlight]
+    await routeToEnterpriseSales(enriched);
+  } else {
+    await routeToSelfServe(enriched);
+  }
+
+  return { email, segment: enriched.crm?.segment ?? "self-serve" };
+}
+
+async function lookupContact(email: string): Promise<{ email: string; domain: string }> {
+  "use step";
+  return { email, domain: email.split("@")[1] ?? "unknown" };
+}
+
+async function fetchCrmData(contact: { email: string }): Promise<{ segment: string }> {
+  "use step";
+  const res = await fetch(`https://crm.example.com/lookup?email=${contact.email}`);
+  return res.json();
+}
+
+async function fetchSocialData(contact: { email: string }): Promise<{ followers: number }> {
+  "use step";
+  const res = await fetch(`https://social.example.com/lookup?email=${contact.email}`);
+  return res.json();
+}
+
+async function routeToEnterpriseSales(enriched: unknown): Promise<void> {
+  "use step";
+  // Assign to enterprise sales team
+}
+
+async function routeToSelfServe(enriched: unknown): Promise<void> {
+  "use step";
+  // Add to self-serve onboarding flow
+}
+```
+
+## Pattern: Multiple event sources
+
+When a workflow must wait for signals from different systems before proceeding, create one hook per source and use `Promise.all` with a deadline:
+
+```typescript
+import { defineHook, sleep } from "workflow";
+
+export const orderSignal = defineHook<{ ok: true }>();
+
+const SIGNALS = ["payment", "inventory", "fraud"] as const;
+
+export async function waitForAllSignals(orderId: string) {
+  "use workflow";
+
+  const hooks = SIGNALS.map((kind) =>
+    orderSignal.create({ token: `${kind}:${orderId}` }) // [!code highlight]
+  );
+
+  const outcome = await Promise.race([ // [!code highlight]
+    Promise.all(hooks).then(() => ({ type: "ready" as const })), // [!code highlight]
+    sleep("5m").then(() => ({ type: "timeout" as const })), // [!code highlight]
+  ]);
+
+  if (outcome.type === "timeout") {
+    return { orderId, status: "timeout" };
+  }
+
+  await shipOrder(orderId);
+  return { orderId, status: "shipped" };
+}
+
+async function shipOrder(orderId: string): Promise<void> {
+  "use step";
+  await fetch(`https://shipping.example.com/ship`, {
+    method: "POST",
+    body: JSON.stringify({ orderId }),
+  });
+}
+```
+
+## Tips
+
+- **Workflow functions use standard JavaScript.** `if`/`else`, `switch`, ternaries -- any branching logic works. No special routing DSL needed.
+- **Each handler is an independent step.** This means each gets its own retries, its own error handling, and its own entry in the event log.
+- **Combine with enrichment** when downstream handlers need data from multiple sources. Fan out enrichment with `Promise.allSettled`, then route on the merged result.
+- **Use `defineHook` for event gateways** when the routing decision depends on external signals arriving asynchronously.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- marks the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) -- marks each handler as a durable step
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- creates hooks for event gateway patterns
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable deadline for event gateways

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

@@ -0,0 +1,208 @@
+---
+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/cookbook/common-patterns/idempotency.mdx

@@ -0,0 +1,107 @@
+---
+title: Idempotency
+description: Ensure external side effects happen exactly once, even when steps are retried or workflows are replayed.
+type: guide
+summary: Use step IDs as idempotency keys for external APIs like Stripe so that retries and replays don't create duplicate charges.
+---
+
+Workflow steps can be retried (on failure) and replayed (on cold start). If a step calls an external API that isn't idempotent, retries could create duplicate charges, send duplicate emails, or double-process records. Use idempotency keys to make these operations safe.
+
+## When to use this
+
+- Charging a payment (Stripe, PayPal)
+- Sending transactional emails or SMS
+- Creating records in external systems where duplicates are harmful
+- Any step that has side effects in systems you don't control
+
+## Pattern: Step ID as idempotency key
+
+Every step has a unique, deterministic `stepId` available via `getStepMetadata()`. Pass this as the idempotency key to external APIs:
+
+```typescript
+import { getStepMetadata } from "workflow";
+
+declare function createCharge(customerId: string, amount: number): Promise<{ id: string }>; // @setup
+declare function sendReceipt(customerId: string, chargeId: string): Promise<void>; // @setup
+
+export async function chargeCustomer(customerId: string, amount: number) {
+  "use workflow";
+
+  const charge = await createCharge(customerId, amount);
+  await sendReceipt(customerId, charge.id);
+
+  return { customerId, chargeId: charge.id, status: "completed" };
+}
+```
+
+### Step function with idempotency key
+
+```typescript
+import { getStepMetadata } from "workflow";
+
+async function createCharge(
+  customerId: string,
+  amount: number
+): Promise<{ id: string }> {
+  "use step";
+
+  const { stepId } = getStepMetadata(); // [!code highlight]
+
+  // Stripe uses the idempotency key to deduplicate requests.
+  // If this step is retried, Stripe returns the same charge.
+  const charge = await fetch("https://api.stripe.com/v1/charges", {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+      "Idempotency-Key": stepId, // [!code highlight]
+    },
+    body: new URLSearchParams({
+      amount: String(amount),
+      currency: "usd",
+      customer: customerId,
+    }),
+  });
+
+  if (!charge.ok) {
+    const error = await charge.json();
+    throw new Error(`Charge failed: ${error.message}`);
+  }
+
+  return charge.json();
+}
+
+async function sendReceipt(customerId: string, chargeId: string): Promise<void> {
+  "use step";
+
+  const { stepId } = getStepMetadata();
+
+  await fetch("https://api.example.com/receipts", {
+    method: "POST",
+    headers: { "Idempotency-Key": stepId },
+    body: JSON.stringify({ customerId, chargeId }),
+  });
+}
+```
+
+## Race condition caveats
+
+Workflow does not currently provide distributed locking or true exactly-once delivery across concurrent runs. If two workflow runs could process the same entity concurrently:
+
+- **Rely on the external API's idempotency** (like Stripe's `Idempotency-Key`) rather than checking a local flag.
+- **Don't use check-then-act patterns** like "read a flag, then write if not set" -- another run could read the same flag between your read and write.
+
+If your external API doesn't support idempotency keys natively, consider adding a deduplication layer (e.g., a database unique constraint on the operation ID).
+
+## Tips
+
+- **`stepId` is deterministic.** It's the same value across retries and replays of the same step, making it a reliable idempotency key.
+- **Always provide idempotency keys for non-idempotent external calls.** Even if you think a step won't be retried, cold-start replay will re-execute it.
+- **Handle 409/conflict as success.** If an external API returns "already processed," treat that as a successful result, not an error.
+- **Make your own APIs idempotent** where possible. Accept an idempotency key and return the cached result on duplicate requests.
+
+## 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
+- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run

package/docs/cookbook/common-patterns/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Common Patterns",
+  "defaultOpen": true,
+  "pages": [
+    "saga",
+    "batching",
+    "rate-limiting",
+    "fan-out",
+    "scheduling",
+    "idempotency",
+    "webhooks",
+    "content-router",
+    "child-workflows"
+  ]
+}