workflow 5.0.0-beta.2 → 5.0.0-beta.21

package/docs/cookbook/common-patterns/child-workflows.mdx

@@ -1,372 +0,0 @@
----
-title: Child Workflows
-description: Spawn child workflows from a parent and poll their progress for batch processing, report generation, and other multi-workflow orchestration scenarios.
-type: guide
-summary: Orchestrate independent child workflows from a parent workflow using start(), sleep(), and getRun() to fan out work with isolated failure boundaries.
----
-
-Use child workflows when a single workflow needs to orchestrate many independent units of work. Each child runs as its own workflow with a separate event log, retry boundary, and failure scope -- if one child fails, it doesn't take down the parent or siblings.
-
-## When to use child workflows
-
-Child workflows are the right choice when:
-
-- **Work units are independent.** Each child can run without knowing about the others (e.g., processing individual documents, generating separate reports).
-- **You need isolated failure boundaries.** A failing child should not abort unrelated work. The parent decides how to handle failures.
-- **You want massive fan-out.** Spawning 50 or 500 children is practical because each runs on its own infrastructure.
-- **You need per-item observability.** Each child workflow has its own run ID, status, and event log for monitoring.
-
-For simpler cases where steps share a single event log, use [direct await composition](/docs/foundations/common-patterns#direct-await-flattening) instead.
-
-## Basic pattern: spawn and poll
-
-The core pattern has three parts:
-
-1. A **step** that calls `start()` to spawn a child workflow and returns the run ID
-2. A **polling loop** in the parent workflow that checks child status with `getRun()`
-3. A **step** that retrieves the child's return value once it completes
-
-```typescript
-import { sleep } from "workflow";
-import { getRun, start } from "workflow/api";
-
-declare function pollUntilComplete(runIds: string[]): Promise<void>; // @setup
-declare function collectResults(runIds: string[]): Promise<Array<{ documentId: string; summary: string }>>; // @setup
-
-// Child workflow -- processes a single document
-export async function processDocument(documentId: string) {
-  "use workflow";
-
-  const content = await fetchDocument(documentId);
-  const analysis = await analyzeContent(content);
-  const summary = await generateSummary(analysis);
-
-  return { documentId, summary };
-}
-
-async function fetchDocument(documentId: string): Promise<string> {
-  "use step";
-  const res = await fetch(`https://docs.example.com/api/${documentId}`);
-  return res.text();
-}
-
-async function analyzeContent(content: string): Promise<string> {
-  "use step";
-  // Call analysis API
-  return `analysis of ${content.length} chars`;
-}
-
-async function generateSummary(analysis: string): Promise<string> {
-  "use step";
-  // Generate summary from analysis
-  return `Summary: ${analysis}`;
-}
-
-// Parent workflow -- orchestrates document processing
-export async function processDocumentBatch(documentIds: string[]) {
-  "use workflow";
-
-  // Spawn a child workflow for each document
-  const runIds = await spawnChildren(documentIds);
-
-  // Poll until all children complete
-  await pollUntilComplete(runIds);
-
-  // Collect results
-  const results = await collectResults(runIds);
-
-  return { processed: results.length, results };
-}
-
-async function spawnChildren(
-  documentIds: string[]
-): Promise<string[]> {
-  "use step"; // [!code highlight]
-
-  const runIds: string[] = [];
-  for (const docId of documentIds) {
-    const run = await start(processDocument, [docId]); // [!code highlight]
-    runIds.push(run.runId);
-  }
-  return runIds;
-}
-```
-
-### Polling loop
-
-The parent workflow polls child statuses in a loop, sleeping between checks. This is durable -- if the parent replays, the sleep and status checks replay from the event log.
-
-```typescript
-import { sleep } from "workflow";
-import { getRun } from "workflow/api";
-
-const POLL_INTERVAL = "30s";
-const MAX_POLL_ITERATIONS = 120; // 60 minutes at 30s intervals
-
-async function pollUntilComplete(runIds: string[]): Promise<void> {
-  let iteration = 0;
-
-  while (iteration < MAX_POLL_ITERATIONS) {
-    const status = await checkStatuses(runIds); // [!code highlight]
-
-    if (status.running === 0) {
-      if (status.failed > 0) {
-        throw new Error(
-          `${status.failed} of ${runIds.length} children failed`
-        );
-      }
-      return; // All completed successfully
-    }
-
-    iteration += 1;
-    await sleep(POLL_INTERVAL); // [!code highlight]
-  }
-
-  throw new Error("Timed out waiting for children to complete");
-}
-
-async function checkStatuses(
-  runIds: string[]
-): Promise<{ running: number; completed: number; failed: number }> {
-  "use step"; // [!code highlight]
-
-  let running = 0;
-  let completed = 0;
-  let failed = 0;
-
-  for (const runId of runIds) {
-    const run = getRun(runId); // [!code highlight]
-    const status = await run.status; // [!code highlight]
-
-    if (status === "completed") completed += 1;
-    else if (status === "failed" || status === "cancelled") failed += 1;
-    else running += 1; // pending, running
-  }
-
-  return { running, completed, failed };
-}
-
-async function collectResults(
-  runIds: string[]
-): Promise<Array<{ documentId: string; summary: string }>> {
-  "use step";
-
-  const results = [];
-  for (const runId of runIds) {
-    const run = getRun(runId);
-    const value = await run.returnValue;
-    results.push(value as { documentId: string; summary: string });
-  }
-  return results;
-}
-```
-
-## Fan-out pattern: chunked spawning
-
-When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Use multiple spawn steps, each launching a chunk of children.
-
-```typescript
-import { start } from "workflow/api";
-
-declare function pollUntilComplete(runIds: string[]): Promise<void>; // @setup
-
-const CHUNK_SIZE = 10;
-
-export async function largeReportBatch(reportConfigs: Array<{ id: string; query: string }>) {
-  "use workflow";
-
-  // Spawn children in chunks
-  const allRunIds: string[] = [];
-  for (let i = 0; i < reportConfigs.length; i += CHUNK_SIZE) {
-    const chunk = reportConfigs.slice(i, i + CHUNK_SIZE);
-    const runIds = await spawnReportChunk(chunk); // [!code highlight]
-    allRunIds.push(...runIds);
-  }
-
-  // Poll until all complete
-  await pollUntilComplete(allRunIds);
-
-  const results = await collectReportResults(allRunIds);
-  return { total: results.length, results };
-}
-
-async function spawnReportChunk(
-  configs: Array<{ id: string; query: string }>
-): Promise<string[]> {
-  "use step";
-
-  const runIds: string[] = [];
-  for (const config of configs) {
-    const run = await start(generateReport, [config.id, config.query]);
-    runIds.push(run.runId);
-  }
-  return runIds;
-}
-
-async function generateReport(reportId: string, query: string) {
-  "use workflow";
-
-  const data = await queryDatabase(reportId, query);
-  const formatted = await formatReport(reportId, data);
-  return { reportId, formatted };
-}
-
-declare function queryDatabase(reportId: string, query: string): Promise<string>; // @setup
-declare function formatReport(reportId: string, data: string): Promise<string>; // @setup
-
-declare function collectReportResults(
-  runIds: string[]
-): Promise<Array<{ reportId: string; formatted: string }>>; // @setup
-```
-
-## Error handling
-
-### Tolerating partial failures
-
-Not every batch requires 100% success. Use `allowFailures` logic to let the parent continue when some children fail, while still surfacing the failures.
-
-```typescript
-import { sleep } from "workflow";
-import { getRun } from "workflow/api";
-
-const POLL_INTERVAL = "30s";
-const MAX_POLL_ITERATIONS = 120;
-
-async function pollWithPartialFailures(
-  runIds: string[],
-  maxFailureRate: number
-): Promise<{ completed: string[]; failed: string[] }> {
-  let iteration = 0;
-  const completedIds: string[] = [];
-  const failedIds: string[] = [];
-
-  while (iteration < MAX_POLL_ITERATIONS) {
-    const status = await checkDetailedStatuses(runIds);
-
-    completedIds.length = 0;
-    failedIds.length = 0;
-
-    for (const entry of status) {
-      if (entry.status === "completed") completedIds.push(entry.runId);
-      else if (entry.status === "failed" || entry.status === "cancelled")
-        failedIds.push(entry.runId);
-    }
-
-    const active = runIds.length - completedIds.length - failedIds.length;
-
-    // Check if failure rate exceeds threshold
-    const failureRate = failedIds.length / Math.max(1, runIds.length); // [!code highlight]
-    if (failureRate > maxFailureRate) { // [!code highlight]
-      throw new Error( // [!code highlight]
-        `Failure rate ${(failureRate * 100).toFixed(1)}% exceeds ` + // [!code highlight]
-        `threshold of ${(maxFailureRate * 100).toFixed(1)}%` // [!code highlight]
-      ); // [!code highlight]
-    } // [!code highlight]
-
-    if (active === 0) {
-      return { completed: completedIds, failed: failedIds };
-    }
-
-    iteration += 1;
-    await sleep(POLL_INTERVAL);
-  }
-
-  throw new Error("Timed out waiting for children");
-}
-
-async function checkDetailedStatuses(
-  runIds: string[]
-): Promise<Array<{ runId: string; status: string }>> {
-  "use step";
-
-  const statuses = [];
-  for (const runId of runIds) {
-    const run = getRun(runId);
-    const status = await run.status;
-    statuses.push({ runId, status });
-  }
-  return statuses;
-}
-```
-
-### Retrying failed children
-
-When a child fails, the parent can spawn a replacement and continue polling. Track restart counts to prevent infinite retry loops.
-
-```typescript
-import { sleep } from "workflow";
-
-declare function checkDetailedStatuses(runIds: string[]): Promise<Array<{ runId: string; status: string }>>; // @setup
-
-const POLL_INTERVAL = "30s";
-const MAX_POLL_ITERATIONS = 120;
-
-async function pollWithRetries(
-  initialRunIds: string[],
-  maxRestartsPerChild: number,
-  spawnReplacement: (index: number) => Promise<string>
-): Promise<void> {
-  const activeRuns = new Map<number, string>();
-  const restartCounts = new Map<number, number>();
-
-  initialRunIds.forEach((runId, index) => activeRuns.set(index, runId));
-
-  let iteration = 0;
-
-  while (iteration < MAX_POLL_ITERATIONS) {
-    const statuses = await checkDetailedStatuses(
-      Array.from(activeRuns.values())
-    );
-    const statusByRunId = new Map(
-      statuses.map((s) => [s.runId, s.status])
-    );
-
-    for (const [index, runId] of activeRuns.entries()) {
-      const status = statusByRunId.get(runId) ?? "running";
-
-      if (status === "completed") {
-        activeRuns.delete(index);
-        continue;
-      }
-
-      if (status === "failed" || status === "cancelled") {
-        const restarts = (restartCounts.get(index) ?? 0) + 1; // [!code highlight]
-        restartCounts.set(index, restarts); // [!code highlight]
-
-        if (restarts > maxRestartsPerChild) { // [!code highlight]
-          throw new Error( // [!code highlight]
-            `Child ${index} exceeded restart limit (${maxRestartsPerChild})` // [!code highlight]
-          ); // [!code highlight]
-        } // [!code highlight]
-
-        const newRunId = await spawnReplacement(index); // [!code highlight]
-        activeRuns.set(index, newRunId); // [!code highlight]
-      }
-    }
-
-    if (activeRuns.size === 0) return;
-
-    iteration += 1;
-    await sleep(POLL_INTERVAL);
-  }
-
-  throw new Error("Timed out waiting for children");
-}
-```
-
-## Tips
-
-- **`start()` must be called from a step**, not directly from a workflow function. Wrap it in a `"use step"` function.
-- **`getRun()` must also be called from a step.** The polling loop lives in the workflow, but the actual status check is a step.
-- **Set a max iteration count on polling loops** to prevent runaway workflows. Calculate the count from your expected max duration and poll interval.
-- **Use chunked spawning for large batches.** Spawning 500 children in a single step can time out. Break it into chunks of 10-50.
-- **Each child has its own retry semantics.** Steps inside child workflows retry independently. The parent only sees the child's final status.
-- **Use `deploymentId: "latest"`** if children should run on the most recent deployment. See the [`start()` API reference](/docs/api-reference/workflow-api/start#using-deploymentid-latest) for compatibility considerations.
-
-## Key APIs
-
-- [`start()`](/docs/api-reference/workflow-api/start) -- spawn a new workflow run and get its run ID
-- [`getRun()`](/docs/api-reference/workflow-api/get-run) -- retrieve a workflow run's status and return value
-- [`sleep()`](/docs/api-reference/workflow/sleep) -- durably pause between polling iterations
-- [`"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

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

@@ -1,207 +0,0 @@
----
-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