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

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

@@ -0,0 +1,105 @@
+---
+title: Batching & Parallel Processing
+description: Process large collections in parallel batches with failure isolation between groups.
+type: guide
+summary: Split items into fixed-size batches, process each batch concurrently with Promise.allSettled, and pace batches with sleep to avoid overloading downstream services.
+---
+
+Use batching when you need to process a large list of items in parallel while controlling concurrency. Items are split into fixed-size batches, each batch runs concurrently, and failures in one batch don't affect others.
+
+## When to use this
+
+- Bulk data imports (contacts, orders, products from a CSV)
+- Processing hundreds or thousands of items against external APIs
+- Calling rate-limited APIs where you need to control concurrency
+- Any fan-out where you want failure isolation between groups
+
+## How it works
+
+1. Records are split into fixed-size batches.
+2. Each batch runs in parallel via `Promise.allSettled` — failures in one record don't affect others.
+3. A `sleep()` between batches paces requests to avoid overloading downstream services.
+4. After all batches, a summary is returned with succeeded/failed counts.
+
+## Pattern
+
+The workflow splits records into chunks, processes each chunk concurrently, tracks results per batch, and returns a final tally.
+
+```typescript
+import { sleep } from "workflow";
+
+type Record = { name: string; email: string; role: string };
+
+declare function processRecord(record: Record): Promise<string>; // @setup
+
+export async function batchImport(records: Record[], batchSize: number) {
+  "use workflow";
+
+  let totalSucceeded = 0;
+  let totalFailed = 0;
+
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+
+    // Run batch in parallel — failures are isolated per record
+    const outcomes = await Promise.allSettled( // [!code highlight]
+      batch.map((record) => processRecord(record))
+    );
+
+    for (let j = 0; j < outcomes.length; j++) {
+      if (outcomes[j].status === "fulfilled") {
+        totalSucceeded++;
+      } else {
+        totalFailed++;
+      }
+    }
+
+    // Pace between batches to avoid overloading downstream
+    if (i + batchSize < records.length) {
+      await sleep("1s"); // [!code highlight]
+    }
+  }
+
+  return { total: records.length, succeeded: totalSucceeded, failed: totalFailed };
+}
+```
+
+### Step function
+
+Each record is processed in its own step with full Node.js access and automatic retries.
+
+```typescript
+type Record = { name: string; email: string; role: string };
+
+async function processRecord(record: Record): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/contacts`, {
+    method: "POST",
+    body: JSON.stringify(record),
+  });
+  if (!res.ok) throw new Error(`Failed to import ${record.email}`);
+  const { id } = await res.json();
+  return id;
+}
+```
+
+## Adapting to your use case
+
+- Replace the `Record` type with your actual data shape (orders, images, products, etc.).
+- Replace `processRecord()` with your real import logic — DB upserts, API calls, file processing.
+- Tune `batchSize` and the `sleep()` duration to match your downstream rate limits.
+- Add or remove tracking as needed — the pattern works with any item type.
+
+## Tips
+
+- **Use `Promise.allSettled` over `Promise.all`** when you want to continue even if some items fail. `Promise.all` rejects on the first failure; `allSettled` waits for everything and tells you what failed.
+- **Tune batch size to your downstream API limits.** If the API allows 10 concurrent requests, use `batchSize: 10`.
+- **Add pacing with `sleep()`** between batches to respect rate limits. The sleep is durable — it survives cold starts.
+- **Each `processRecord` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+
+## 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) -- pacing delay between batches
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- runs items in parallel, isolating 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": [
+    "sequential-and-parallel",
+    "workflow-composition",
+    "saga",
+    "batching",
+    "rate-limiting",
+    "scheduling",
+    "timeouts",
+    "idempotency",
+    "webhooks"
+  ]
+}

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -0,0 +1,228 @@
+---
+title: Rate Limiting & Retries
+description: Handle 429 responses and transient failures with RetryableError and exponential backoff.
+type: guide
+summary: When an external API returns 429, throw RetryableError with the Retry-After value so the workflow runtime automatically reschedules the step after the specified delay.
+---
+
+Use this pattern when calling external APIs that enforce rate limits. Instead of writing manual retry loops, throw `RetryableError` with a `retryAfter` value and let the workflow runtime handle rescheduling.
+
+## When to use this
+
+- Calling APIs that return 429 (Too Many Requests) with `Retry-After` headers
+- Any step that hits transient failures and needs backoff
+- Syncing data with third-party services (Stripe, CRMs, scrapers)
+
+## Pattern: RetryableError with Retry-After
+
+A step function calls an external API. On 429, it reads the `Retry-After` header and throws `RetryableError`. The runtime reschedules the step automatically.
+
+```typescript
+import { RetryableError } from "workflow";
+
+declare function fetchFromCrm(contactId: string): Promise<unknown>; // @setup
+declare function upsertToWarehouse(contactId: string, contact: unknown): Promise<void>; // @setup
+
+export async function syncContact(contactId: string) {
+  "use workflow";
+
+  const contact = await fetchFromCrm(contactId);
+  await upsertToWarehouse(contactId, contact);
+
+  return { contactId, status: "synced" };
+}
+```
+
+### Step function with rate limit handling
+
+```typescript
+import { RetryableError } from "workflow";
+
+async function fetchFromCrm(contactId: string) {
+  "use step";
+
+  const res = await fetch(`https://crm.example.com/contacts/${contactId}`);
+
+  if (res.status === 429) { // [!code highlight]
+    const retryAfter = res.headers.get("Retry-After");
+    throw new RetryableError("Rate limited by CRM", { // [!code highlight]
+      retryAfter: retryAfter ? parseInt(retryAfter) * 1000 : "1m",
+    });
+  }
+
+  if (!res.ok) throw new Error(`CRM returned ${res.status}`);
+  return res.json();
+}
+
+async function upsertToWarehouse(contactId: string, contact: unknown) {
+  "use step";
+  await fetch(`https://warehouse.example.com/contacts/${contactId}`, {
+    method: "PUT",
+    body: JSON.stringify(contact),
+  });
+}
+```
+
+## Pattern: Exponential backoff
+
+Use `getStepMetadata()` to access the current attempt number and calculate increasing delays:
+
+```typescript
+import { RetryableError, getStepMetadata } from "workflow";
+
+async function callFlakeyApi(endpoint: string) {
+  "use step";
+
+  const { attempt } = getStepMetadata(); // [!code highlight]
+  const res = await fetch(endpoint);
+
+  if (res.status === 429 || res.status >= 500) {
+    throw new RetryableError(`Request failed (${res.status})`, { // [!code highlight]
+      retryAfter: (attempt ** 2) * 1000, // 1s, 4s, 9s... // [!code highlight]
+    });
+  }
+
+  return res.json();
+}
+```
+
+## Pattern: Circuit breaker with sleep
+
+When a dependency is completely down, stop hitting it for a cooldown period using `sleep()`, then probe with a single test request:
+
+```typescript
+import { sleep } from "workflow";
+
+export async function circuitBreaker(maxRequests: number = 10) {
+  "use workflow";
+
+  let state: "closed" | "open" | "half-open" = "closed";
+  let consecutiveFailures = 0;
+  const FAILURE_THRESHOLD = 3;
+
+  for (let i = 1; i <= maxRequests; i++) {
+    if (state === "open") {
+      await sleep("30s"); // Durable cooldown // [!code highlight]
+      state = "half-open";
+    }
+
+    const success = await callService(i);
+
+    if (success) {
+      consecutiveFailures = 0;
+      if (state === "half-open") state = "closed";
+    } else {
+      consecutiveFailures++;
+      if (consecutiveFailures >= FAILURE_THRESHOLD) {
+        state = "open";
+        consecutiveFailures = 0;
+      }
+    }
+  }
+
+  return { status: state === "closed" ? "recovered" : "failed" };
+}
+
+async function callService(requestNum: number): Promise<boolean> {
+  "use step";
+  try {
+    const res = await fetch("https://payment-gateway.example.com/charge");
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Pattern: Custom max retries
+
+Override the default retry count (3) for steps that need more or fewer attempts:
+
+```typescript
+async function fetchWithRetries(url: string) {
+  "use step";
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed: ${res.status}`);
+  return res.json();
+}
+
+// Allow up to 10 retry attempts
+fetchWithRetries.maxRetries = 10; // [!code highlight]
+```
+
+## Application-level retry
+
+Sometimes you need retry logic at the workflow level -- wrapping a step call with your own backoff instead of relying on the framework's built-in `RetryableError`. This is useful when you want full control over retry conditions, delays, and error filtering.
+
+```typescript
+interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const { maxRetries = 3, baseDelay = 2000, maxDelay = 10000, shouldRetry } = options;
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      const isLastAttempt = attempt === maxRetries;
+      if (isLastAttempt || (shouldRetry && !shouldRetry(lastError, attempt + 1))) {
+        throw lastError;
+      }
+      // Exponential backoff with jitter
+      const delay = Math.min(baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5), maxDelay);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+```
+
+Use it in a workflow to wrap step calls:
+
+```typescript
+declare function withRetry<T>(fn: () => Promise<T>, options?: { maxRetries?: number; shouldRetry?: (error: Error) => boolean }): Promise<T>; // @setup
+declare function downloadFile(url: string): Promise<any>; // @setup
+
+export async function downloadWithRetry(url: string) {
+  "use workflow";
+
+  const result = await withRetry(() => downloadFile(url), { // [!code highlight]
+    maxRetries: 5,
+    shouldRetry: (error) => error.message.includes("Timeout"),
+  });
+
+  return result;
+}
+```
+
+**When to use this vs `RetryableError`/`FatalError`:**
+- **`RetryableError`** runs inside a step -- the framework reschedules the step after the delay. Use it for transient HTTP errors (429, 503) where the runtime should handle backoff.
+- **Application-level retry** wraps the step call from the workflow. Use it when you need custom retry conditions, want to retry across different steps, or when you're building a library and prefer not to depend on workflow-specific error classes.
+
+## Tips
+
+- **`RetryableError` is for transient failures.** Use it when the request might succeed on a later attempt (429, 503, network timeout).
+- **`FatalError` is for permanent failures.** Use it when retrying won't help (404, 401, invalid input). This skips all remaining retries.
+- **The `retryAfter` option accepts** a millisecond number, a duration string (`"1m"`, `"30s"`), or a `Date` object.
+- **Steps retry up to 3 times by default.** Set `fn.maxRetries = N` to change this per step function.
+- **Don't write manual sleep-retry loops.** The runtime handles scheduling natively with `RetryableError` -- it's more efficient and survives cold starts.
+
+## 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
+- [`RetryableError`](/docs/api-reference/workflow/retryable-error) -- signals the runtime to retry after a delay
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- signals a permanent failure, skipping retries
+- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the current attempt number and step ID
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable pause for circuit breaker cooldowns