workflow 5.0.0-beta.4 → 5.0.0-beta.5

package/docs/internal/serializable-abort-controller.mdx

@@ -0,0 +1,148 @@
+---
+title: Serializable AbortController and AbortSignal
+description: AbortController and AbortSignal now work across workflow and step boundaries using the standard Web API.
+type: overview
+---
+
+# Serializable AbortController and AbortSignal
+
+<span className="text-sm text-fd-muted-foreground">March 12, 2026</span>
+
+`AbortController` and `AbortSignal` now work natively in workflow functions. Create a controller, pass its signal to steps, and call `abort()` — no special imports or wrapper functions needed.
+
+## What's new
+
+- **Standard API, zero boilerplate.** `new AbortController()` works inside `"use workflow"` functions. The controller and its signal are automatically serialized across workflow and step boundaries.
+- **Dual hook + stream backing for durability.** Under the hood, each controller is backed by a durable [hook](/docs/foundations/hooks) (for replay correctness) and a [stream](/docs/foundations/streaming) (for real-time propagation to running steps). This means aborts survive cold starts, replays, and scale events.
+- **Cooperative cancellation.** Steps receive the abort in real time and can respond by checking `signal.aborted`, calling `signal.throwIfAborted()`, or passing the signal to APIs like `fetch`.
+- **Abort errors skip retries.** When a step throws due to an abort (e.g., `fetch` throws `AbortError`), the error is automatically wrapped in `FatalError` so it skips retries and bubbles up immediately.
+- **`AbortSignal.timeout()` blocked in workflow VM.** Because it relies on real-time timers that break deterministic replay, `AbortSignal.timeout()` throws a helpful error pointing to the `sleep()` + `AbortController` pattern instead.
+- **`Request.signal` preserved when it carries abort state.** A `Request`'s `.signal` is serialized when it's already aborted (so the cancellation that happened pre-serialization is preserved) or when it's a workflow-managed signal (so its hook + stream backing carries through). Plain non-aborted native signals — including the auto-generated signal on `new Request(url)` — are dropped to avoid minting stream infrastructure for every `Request`. To get cross-boundary cancellation through a `Request`, build it with the signal from a workflow-context `AbortController`.
+- **Pending queue items drain on completion.** If you call `abort()` (or `dispose` a hook, or kick off a `void sleep('1d')`, or fire a `void someStep()`) without a suspension point between that call and the workflow's return, the runtime now treats end-of-run as a final suspension and commits all pending operations before the run is marked terminal. This matches normal JS semantics — `setTimeout` etc. continue running after the surrounding function returns. The most important case: `controller.abort()` called as the last statement of a workflow now actually propagates to in-flight steps on other compute instances.
+
+## Timeout with cancellation
+
+Race a step against a durable `sleep()`, and cancel the step if the timeout wins:
+
+```typescript
+import { sleep } from "workflow";
+
+export async function fetchWithTimeout(url: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race([
+    fetchUrl(url, controller.signal),
+    sleep("10s").then(() => null),
+  ]);
+
+  if (result === null) {
+    controller.abort();
+    throw new Error(`Request to ${url} timed out after 10s`);
+  }
+
+  return result;
+}
+
+async function fetchUrl(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return response.json();
+}
+```
+
+## Cancelling parallel work
+
+When racing multiple steps, cancel the losers:
+
+```typescript
+declare function fetchUrl(url: string, signal: AbortSignal): Promise<{ url: string; data: unknown }>; // @setup
+
+export async function firstResponder(urls: string[]) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race(
+    urls.map((url) => fetchUrl(url, controller.signal))
+  );
+
+  controller.abort(); // Cancel remaining fetches
+
+  return result;
+}
+```
+
+## User-triggered cancellation with hooks
+
+Combine hooks with abort controllers to let users cancel work from an external API:
+
+```typescript
+declare function doExpensiveWork(signal: AbortSignal): Promise<unknown>; // @setup
+import { createHook } from "workflow";
+
+export async function userCancellableWorkflow(jobId: string) {
+  "use workflow";
+
+  using cancelHook = createHook<{ reason: string }>({
+    token: `cancel:${jobId}`,
+  });
+
+  const controller = new AbortController();
+  const workPromise = doExpensiveWork(controller.signal);
+
+  const result = await Promise.race([
+    workPromise.then((data) => ({ status: "completed", data })),
+    cancelHook.then((payload) => {
+      controller.abort();
+      return { status: "cancelled", reason: payload.reason };
+    }),
+  ]);
+
+  return result;
+}
+```
+
+## Step-initiated abort
+
+A step can receive the full `AbortController` and call `abort()` to cancel parallel work — useful for watchdog patterns like quota monitoring:
+
+```typescript
+declare function processData(url: string, signal: AbortSignal): Promise<{ processed: boolean }>; // @setup
+
+export async function processWithQuotaCheck(userId: string, dataUrl: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const [result] = await Promise.all([
+    processData(dataUrl, controller.signal),
+    monitorQuota(userId, controller),
+  ]);
+
+  return result;
+}
+
+async function monitorQuota(userId: string, controller: AbortController) {
+  "use step";
+
+  while (!controller.signal.aborted) {
+    const quota = await fetch(`https://api.example.com/quota/${userId}`);
+    const { exceeded } = await quota.json();
+
+    if (exceeded) {
+      controller.abort("Quota exceeded"); // Cancels processData
+      return;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+}
+```
+
+## Learn more
+
+- [Cancellation](/docs/foundations/cancellation) — Full guide with all usage patterns
+- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream internals
+- [AbortSignal.timeout() in Workflow](/docs/errors/abort-signal-timeout-in-workflow) — Why `AbortSignal.timeout()` is blocked and what to use instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.5",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -29,6 +29,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "workflow": "./dist/workflow.js",
+      "node": "./dist/index.js",
       "require": "./dist/typescript-plugin.cjs",
       "default": "./dist/index.js"
     },
@@ -56,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.4",
-    "@workflow/cli": "5.0.0-beta.4",
-    "@workflow/core": "5.0.0-beta.4",
-    "@workflow/errors": "5.0.0-beta.1",
+    "@workflow/astro": "5.0.0-beta.5",
+    "@workflow/cli": "5.0.0-beta.5",
+    "@workflow/core": "5.0.0-beta.5",
+    "@workflow/errors": "5.0.0-beta.2",
     "@workflow/typescript-plugin": "5.0.0-beta.3",
-    "@workflow/utils": "5.0.0-beta.1",
-    "@workflow/next": "5.0.0-beta.4",
-    "@workflow/nest": "5.0.0-beta.4",
-    "@workflow/nuxt": "5.0.0-beta.4",
-    "@workflow/sveltekit": "5.0.0-beta.4",
-    "@workflow/rollup": "5.0.0-beta.4",
-    "@workflow/nitro": "5.0.0-beta.4"
+    "@workflow/utils": "5.0.0-beta.2",
+    "@workflow/next": "5.0.0-beta.5",
+    "@workflow/nest": "5.0.0-beta.5",
+    "@workflow/nitro": "5.0.0-beta.5",
+    "@workflow/nuxt": "5.0.0-beta.5",
+    "@workflow/sveltekit": "5.0.0-beta.5",
+    "@workflow/rollup": "5.0.0-beta.5"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/docs/cookbook/advanced/distributed-abort-controller.mdx

@@ -1,318 +0,0 @@
----
-title: Distributed Abort Controller
-description: A distributed AbortController that uses durable workflows for cross-process cancellation signaling.
-type: guide
-summary: Build a distributed abort controller that uses workflow streams and hooks to propagate cancellation signals across process boundaries.
----
-
-Use this pattern when you need an `AbortController`-like interface that works across distributed systems. The controller uses a durable workflow to coordinate cancellation — calling `.abort()` on one machine triggers the `.signal` on any other machine.
-
-## When to use this
-
-- **Cross-process cancellation** — Cancel a long-running operation from a different server, worker, or edge function
-- **Durable cancellation** — The abort signal persists even if the process that created it crashes
-- **UI stop buttons** — Let users cancel operations running on the server from the browser
-- **Timeout coordination** — The built-in TTL auto-expires stale controllers
-
-## Pattern
-
-The `DistributedAbortController` class encapsulates a workflow that:
-1. Accepts a user-provided unique ID (like a chat ID or task ID)
-2. Creates or reconnects to an existing workflow using that ID
-3. Waits for a hook signal OR TTL expiration
-4. Writes a cancellation message to the run's stream when triggered
-
-### Core Implementation
-
-```typescript lineNumbers
-import { defineHook, getWritable, sleep } from "workflow";
-import { start, getRun, getHookByToken } from "workflow/api";
-
-// Default TTL: 24 hours
-const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
-// Default grace period: 1 hour (keeps hook alive after abort for late subscribers)
-const DEFAULT_GRACE_MS = 60 * 60 * 1000;
-
-// Hook to trigger the abort signal
-export const abortHook = defineHook<{ reason?: string }>();
-
-// The abort message written to the stream
-export type AbortMessage = {
-  type: "abort";
-  reason?: string;
-  expired?: boolean;
-};
-
-// Helper to create a consistent hook token from the user ID
-function getAbortToken(id: string): string {
-  return `abort:${id}`;
-}
-
-// Step function that writes the abort message to the stream
-async function writeAbortSignal(reason?: string, expired?: boolean) {
-  "use step";
-
-  const writable = getWritable<AbortMessage>();
-  const writer = writable.getWriter();
-  try {
-    await writer.write({ type: "abort", reason, expired });
-  } finally {
-    writer.releaseLock();
-  }
-  await writable.close();
-}
-
-// Workflow that waits for abort or TTL expiration
-export async function abortControllerWorkflow(
-  id: string,
-  ttlMs: number,
-  graceMs: number
-) {
-  "use workflow";
-
-  const startTime = Date.now();
-  const hook = abortHook.create({ token: getAbortToken(id) });
-
-  // Race: manual abort OR TTL expiration // [!code highlight]
-  const result = await Promise.race([
-    hook.then((payload) => ({
-      reason: payload.reason,
-      expired: false,
-    })),
-    sleep(`${ttlMs}ms`).then(() => ({
-      reason: "Controller expired",
-      expired: true,
-    })),
-  ]);
-
-  await writeAbortSignal(result.reason, result.expired);
-
-  // Only sleep through grace period on TTL expiration (keeps hook alive for late subscribers). // [!code highlight]
-  // Manual aborts complete immediately.
-  if (result.expired) {
-    const elapsed = Date.now() - startTime;
-    const remainingTime = graceMs - (elapsed - ttlMs);
-    if (remainingTime > 0) {
-      await sleep(`${remainingTime}ms`); // [!code highlight]
-    }
-  }
-
-  return { aborted: true, reason: result.reason, expired: result.expired };
-}
-
-/**
- * A distributed abort controller that works across process boundaries.
- * Uses a semantically meaningful ID (like a chat ID or task ID) to coordinate.
- */
-export class DistributedAbortController {
-  private id: string;
-  readonly runId: string;
-
-  private constructor(id: string, runId: string) {
-    this.id = id;
-    this.runId = runId;
-  }
-
-  /**
-   * Creates or reconnects to a distributed abort controller.
-   * If a controller with this ID already exists, reconnects to it.
-   * Otherwise, starts a new workflow.
-   *
-   * @param id - A unique, semantically meaningful ID (e.g., "chat:123")
-   * @param options.ttlMs - Time-to-live in ms (default: 24 hours)
-   * @param options.graceMs - Grace period after abort (default: 1 hour)
-   */
-  static async create( // [!code highlight]
-    id: string,
-    options: { ttlMs?: number; graceMs?: number } = {}
-  ): Promise<DistributedAbortController> {
-    const { ttlMs = DEFAULT_TTL_MS, graceMs = DEFAULT_GRACE_MS } = options;
-    const token = getAbortToken(id);
-
-    // Try to find an existing run with this hook token
-    const existingHook = await getHookByToken(token).catch(() => null); // [!code highlight]
-
-    if (existingHook) {
-      // Reconnect to existing controller
-      return new DistributedAbortController(id, existingHook.runId);
-    }
-
-    // Create a new workflow
-    const run = await start(abortControllerWorkflow, [id, ttlMs, graceMs]); // [!code highlight]
-    return new DistributedAbortController(id, run.runId);
-  }
-
-  /**
-   * Triggers the abort signal.
-   * Idempotent: safe to call multiple times or after the workflow has completed.
-   */
-  async abort(reason?: string): Promise<void> { // [!code highlight]
-    try {
-      await abortHook.resume(getAbortToken(this.id), { reason });
-    } catch (error) {
-      const msg = error instanceof Error ? error.message.toLowerCase() : '';
-      if (msg.includes('not found') || msg.includes('expired')) {
-        return;
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Returns an AbortSignal that fires when abort() is called or TTL expires.
-   * The signal fires with a reason indicating what triggered it.
-   */
-  get signal(): AbortSignal { // [!code highlight]
-    const run = getRun<{ aborted: boolean; reason?: string; expired?: boolean }>(this.runId);
-    const controller = new AbortController();
-    const readable = run.getReadable<AbortMessage>();
-
-    (async () => {
-      const reader = readable.getReader();
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          if (value.type === "abort") {
-            const reason = value.expired
-              ? `${value.reason} (expired)`
-              : value.reason;
-            controller.abort(reason);
-            break;
-          }
-        }
-      } catch (error) {
-        if (!controller.signal.aborted) {
-          controller.abort(
-            error instanceof Error ? error.message : "Stream read failed"
-          );
-        }
-      } finally {
-        reader.releaseLock();
-      }
-    })();
-
-    return controller.signal;
-  }
-}
-```
-
-### Usage: Single Process
-
-```typescript lineNumbers
-import { DistributedAbortController } from "./distributed-abort-controller";
-
-// Create a controller with a meaningful ID
-const controller = await DistributedAbortController.create("chat:user-123");
-
-// Get the signal and use it with fetch
-const signal = controller.signal;
-const response = await fetch("https://api.example.com/long-operation", {
-  signal,
-});
-
-// Later: abort the operation
-await controller.abort("User cancelled");
-```
-
-### Usage: Cross-Process Coordination
-
-```typescript lineNumbers
-import { DistributedAbortController } from "./distributed-abort-controller";
-
-// Process A: Create the controller
-const controller = await DistributedAbortController.create("task:build-123");
-// start long operation using controller.signal...
-
-// Process B: Reconnect and abort (no run ID sharing needed!)
-const sameController = await DistributedAbortController.create("task:build-123"); // [!code highlight]
-await sameController.abort("Cancelled by admin");
-
-// Process C: Reconnect and listen
-const anotherRef = await DistributedAbortController.create("task:build-123");
-anotherRef.signal.addEventListener("abort", (e) => {
-  console.log("Task was cancelled:", (e.target as AbortSignal).reason);
-});
-```
-
-### Custom TTL
-
-```typescript lineNumbers
-import { DistributedAbortController } from "./distributed-abort-controller";
-
-// Short-lived controller for a quick operation (5 minutes)
-const shortLived = await DistributedAbortController.create("quick-task", {
-  ttlMs: 5 * 60 * 1000,
-});
-
-// Long-lived controller for batch jobs (7 days)
-const longLived = await DistributedAbortController.create("batch-job", {
-  ttlMs: 7 * 24 * 60 * 60 * 1000,
-});
-
-// When TTL expires, the signal fires with expired reason
-shortLived.signal.addEventListener("abort", (e) => {
-  const reason = (e.target as AbortSignal).reason;
-  if (reason?.includes("expired")) {
-    console.log("Controller expired, cleaning up...");
-  }
-});
-```
-
-### API Route for Remote Abort
-
-```typescript lineNumbers
-import { DistributedAbortController } from "@/lib/distributed-abort-controller";
-
-export async function POST(
-  request: Request,
-  { params }: { params: Promise<{ id: string }> }
-) {
-  const { id } = await params;
-  const { reason } = await request.json();
-
-  const controller = await DistributedAbortController.create(id);
-  await controller.abort(reason || "Cancelled via API");
-
-  return Response.json({ success: true });
-}
-```
-
-### Client Cancel Button
-
-```tsx lineNumbers
-"use client";
-
-export function CancelButton({ taskId }: { taskId: string }) {
-  const handleCancel = async () => {
-    await fetch(`/api/abort/${taskId}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ reason: "User clicked cancel" }),
-    });
-  };
-
-  return (
-    <button type="button" onClick={handleCancel}>
-      Cancel Operation
-    </button>
-  );
-}
-```
-
-## Tips
-
-- **Use semantic IDs** — Use meaningful IDs like `chat:123` or `task:abc` instead of random UUIDs
-- **Create is idempotent** — Calling `create()` with the same ID reconnects to the existing controller
-- **TTL auto-cleanup** — Workflows self-terminate after TTL expires; no manual cleanup needed
-- **Signal is a getter** — Each access to `.signal` creates a new listener; cache it if needed
-- **One-shot** — Once aborted or expired, the workflow completes; create a new controller for new operations
-
-## Key APIs
-
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook for the abort trigger
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — write abort messages to the stream
-- [`sleep()`](/docs/api-reference/workflow/sleep) — TTL timer for auto-expiration
-- [`start()`](/docs/api-reference/workflow-api/start) — start the abort controller workflow
-- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) — find existing run by hook token
-- [`getRun()`](/docs/api-reference/workflow-api/get-run) — reconnect to the workflow's readable stream