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

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

@@ -13,6 +13,12 @@ Use the saga pattern when a business transaction spans multiple services and you
 - Any sequence where partial completion leaves the system in an inconsistent state
 - Operations that need "all or nothing" semantics across external APIs
 
+## How it works
+
+1. Each forward step does work and registers a compensation function.
+2. If any step throws `FatalError`, the catch block runs compensations in reverse (LIFO) order to restore consistency.
+3. Regular errors are retried automatically (up to 3x by default). Use `FatalError` only for permanent failures where retrying won't help.
+
 ## 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.
@@ -34,23 +40,21 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
   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
+    // No compensation — notifications are fire-and-forget
     await sendConfirmation(accountId, invoiceId, entitlementId);
+
     return { status: "completed" };
   } catch (error) {
-    // Unwind compensations in reverse order
+    // Unwind compensations in reverse (LIFO) order
     for (const compensate of compensations.reverse()) { // [!code highlight]
       await compensate(); // [!code highlight]
     }
@@ -62,11 +66,13 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
 
 ### Step functions
 
-Each step is a `"use step"` function with full Node.js access. Forward steps do the work; compensation steps undo it.
+Each step is a `"use step"` function with full Node.js access (fetch, fs, npm packages). Forward steps do the work and throw `FatalError` on permanent failure; compensation steps undo it and must be idempotent — safe to call multiple times if the workflow restarts mid-rollback.
 
 ```typescript
 import { FatalError } from "workflow";
 
+// Forward steps
+
 async function reserveSeats(accountId: string, seats: number): Promise<string> {
   "use step";
   const res = await fetch(`https://api.example.com/seats/reserve`, {
@@ -78,15 +84,6 @@ async function reserveSeats(accountId: string, seats: number): Promise<string> {
   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`, {
@@ -98,14 +95,6 @@ async function captureInvoice(accountId: string, seats: number): Promise<string>
   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`, {
@@ -117,14 +106,6 @@ async function provisionSeats(accountId: string, seats: number): Promise<string>
   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,
@@ -136,17 +117,131 @@ async function sendConfirmation(
     body: JSON.stringify({ accountId, invoiceId, entitlementId, template: "upgrade-complete" }),
   });
 }
+
+// Compensation steps — must be idempotent
+
+async function releaseSeats(accountId: string, reservationId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/seats/release`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, reservationId }),
+  });
+}
+
+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 deprovisionSeats(accountId: string, entitlementId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/entitlements/${entitlementId}`, {
+    method: "DELETE",
+    body: JSON.stringify({ accountId }),
+  });
+}
+```
+
+### Streaming step progress (optional)
+
+Use `getWritable()` to stream progress events to a UI so users can see each step execute in real time.
+
+```typescript
+import { FatalError } from "workflow";
+import { getWritable } from "workflow";
+
+type SagaEvent =
+  | { type: "step_start"; step: string }
+  | { type: "step_done"; step: string; detail: string }
+  | { type: "step_failed"; step: string; error: string }
+  | { type: "compensating"; step: string }
+  | { type: "compensated"; step: string }
+  | { type: "result"; status: "completed" | "rolled_back" };
+
+async function emit(event: SagaEvent) {
+  "use step";
+  const writer = getWritable<SagaEvent>().getWriter();
+  try {
+    await writer.write(event);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+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<{ name: string; execute: () => Promise<void> }> = [];
+
+  try {
+    await emit({ type: "step_start", step: "Reserve Seats" });
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push({ name: "Release Seats", execute: () => releaseSeats(accountId, reservationId) });
+    await emit({ type: "step_done", step: "Reserve Seats", detail: reservationId });
+
+    await emit({ type: "step_start", step: "Capture Invoice" });
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push({ name: "Refund Invoice", execute: () => refundInvoice(accountId, invoiceId) });
+    await emit({ type: "step_done", step: "Capture Invoice", detail: invoiceId });
+
+    await emit({ type: "step_start", step: "Provision Seats" });
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push({ name: "Deprovision Seats", execute: () => deprovisionSeats(accountId, entitlementId) });
+    await emit({ type: "step_done", step: "Provision Seats", detail: entitlementId });
+
+    // No compensation — notifications are fire-and-forget
+    await emit({ type: "step_start", step: "Send Confirmation" });
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+    await emit({ type: "step_done", step: "Send Confirmation", detail: "sent" });
+
+    await emit({ type: "result", status: "completed" });
+    return { status: "completed" };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    await emit({ type: "step_failed", step: "failed", error: errorMessage });
+
+    // Unwind compensations in reverse (LIFO) order
+    for (const comp of compensations.reverse()) {
+      await emit({ type: "compensating", step: comp.name });
+      await comp.execute();
+      await emit({ type: "compensated", step: comp.name });
+    }
+
+    await emit({ type: "result", status: "rolled_back" });
+    return { status: "rolled_back" };
+  }
+}
 ```
 
+## Adapting to your use case
+
+- Replace the step functions with real API calls. Each `"use step"` function has full Node.js access.
+- Add or remove steps as needed — the pattern scales to any number of steps.
+- Make compensations idempotent — they may be retried if the workflow restarts mid-rollback.
+- The `emit()` calls and `SagaEvent` type are optional — remove them if you don't need real-time UI progress.
+
 ## 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.
+- **Notifications don't need compensations.** Fire-and-forget steps like sending emails or Slack messages typically don't register a compensation.
 
 ## 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
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates

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

@@ -2,248 +2,124 @@
 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.
+summary: Schedule future actions with durable sleep that survives cold starts, and race sleeps against hooks to let external events cancel 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.
+Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
 ## 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
+- Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)
+- Waiting for a deadline but allowing early cancellation
+- Any pattern where "do X, wait N hours, then do Y" needs to be both reliable and interruptible
 
-## Pattern: Drip campaign
+## Drip campaign with cancellation
 
-Send emails at scheduled intervals using `sleep()` between steps. The workflow runs for days or weeks, sleeping between each email.
+A drip campaign sends emails at intervals, sleeping between each. Each sleep races against a cancellation hook — if an external event fires the hook (e.g. user converts, unsubscribes), the campaign stops immediately.
 
 ```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");
+import { defineHook, sleep } from "workflow";
 
-  await sleep("4d"); // [!code highlight]
-  await sendEmail(email, "follow-up");
-
-  return { email, status: "completed", totalDays: 7 };
-}
+// Hook that any API route can fire to cancel the drip
+export const cancelDrip = defineHook<{ reason?: string }>(); // [!code highlight]
 
 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,
-    }),
+    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) {
+export async function emailSequence(email: string) {
   "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 sendEmail(email, "welcome");
 
-  await sendReminderEmail(userId);
-  return { userId, status: "sent" };
-}
+  // Race durable sleep against the cancellation hook
+  const hook = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled) return { status: "cancelled", email };
 
-async function sendReminderEmail(userId: string): Promise<void> {
-  "use step";
-  await fetch("https://api.example.com/reminders/send", {
-    method: "POST",
-    body: JSON.stringify({ userId }),
-  });
-}
-```
+  await sendEmail(email, "getting-started-tips");
 
-To wake the reminder early from an API route:
+  // Create a fresh hook for the next sleep window
+  const hook2 = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled2 = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook2.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled2) return { status: "cancelled", email };
 
-```typescript
-import { resumeHook } from "workflow/api";
+  await sendEmail(email, "feature-highlights");
 
-// 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 });
+  return { status: "drip-complete", email };
 }
 ```
 
-## Pattern: Timed collection window (digest)
+### Cancelling from an API route
 
-Open a collection window using `sleep()` and accumulate events from a hook until the window closes:
+Any server-side code can fire the hook by calling `.resume()` with the same token:
 
 ```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";
+import { cancelDrip } from "@/workflows/email-sequence";
 
-  const hook = digestEvent.create({ token: `digest:${digestId}` });
-  const windowClosed = sleep(`${windowMs}ms`).then(() => ({
-    kind: "window_closed" as const,
-  }));
-  const events: EventPayload[] = [];
+export async function POST(req: Request) {
+  const { email, reason } = await req.json();
 
-  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);
+  if (!email) {
+    return Response.json({ error: "email is required" }, { status: 400 });
   }
 
-  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" };
+  try {
+    await cancelDrip.resume(`cancel-drip:${email}`, { // [!code highlight]
+      reason: reason ?? "User completed action", // [!code highlight]
+    }); // [!code highlight]
+  } catch (error) {
+    const msg = error instanceof Error ? error.message.toLowerCase() : "";
+    if (msg.includes("not found") || msg.includes("expired")) {
+      return Response.json({
+        success: true,
+        email,
+        note: "No active drip found (already completed or cancelled)",
+      });
+    }
+    throw error;
   }
 
-  return { jobId, status: "completed", result };
-}
-
-async function processData(jobId: string): Promise<string> {
-  "use step";
-  // Long-running computation
-  return `result-for-${jobId}`;
+  return Response.json({ success: true, email });
 }
 ```
 
-## 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";
+## How it works
 
-  let status = "processing";
-  let attempts = 0;
-  const maxAttempts = 36; // ~3 minutes at 5s intervals
+1. **Durable sleep** — `sleep("2d")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
+2. **Hook creation** — `cancelDrip.create({ token })` registers a hook that resolves when any external system calls `.resume()` with the same token.
+3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
+4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
 
-  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();
-}
-```
+## Adapting to your use case
 
-**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.
+- **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.
+- **Add more steps** — the pattern scales to any number of email-then-sleep pairs.
+- **Snooze instead of cancel** — resolve the hook with a `snooze` payload and sleep again: `sleep(new Date(Date.now() + payload.snoozeMs))`.
+- **Timeout any operation** — the same `Promise.race(sleep, work)` pattern works for adding deadlines to slow steps.
+- **Real providers** — swap the `sendEmail` step body for Resend, Postmark, or any HTTP API. The `"use step"` function has full Node.js access.
 
 ## 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.
+- **Durable means durable.** A `sleep("7d")` workflow costs nothing while sleeping — no compute, no memory.
+- **Use `sleep()` in workflow context only.** Step functions cannot call `sleep()` directly. If a step needs a delay, use `setTimeout` inside the step.
 
 ## 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
+- [`"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)
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — creates a typed hook that external systems can fire
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — races sleep against hooks for interruptible waits