workflow 5.0.0-beta.4 → 5.0.0-beta.6

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -50,7 +50,7 @@ Migration removes infrastructure and collapses indirection. Business logic stays
 | Signal | `createHook()` or `createWebhook()` | Use hooks for typed resume signals; webhooks for HTTP callbacks. |
 | Query | `getWritable({ namespace: 'status' })` stream | Durably stream status updates from the workflow. Clients read from the stream instead of polling a database. |
 | Update | `createHook()` + `resumeHook()` (one-way) | Temporal Updates return a value to the caller; hooks do not. If the Update returns data, either write the result to a named stream via `getWritable()` and have the caller read from it, or keep an HTTP read route that fetches the workflow's current state. |
-| Child Workflow | `"use step"` wrappers around `start()` / `getRun()` | Spawn from a step and return the `Run` object so observability can deep-link into child runs. |
+| Child Workflow | `start()` plus a `"use step"` wrapper around `getRun()` | Spawn a child run and return the `Run` object so observability can deep-link into child runs. |
 | Activity retry policy | Step retries, `RetryableError`, `FatalError`, `maxRetries` | Retries live at the step boundary. |
 | Event History | Workflow event log / run timeline | Same durable replay; built-in observability UI replaces Temporal Web. Search attributes and visibility APIs have no direct equivalent — filter by run status and timestamps instead. |
 
@@ -173,19 +173,14 @@ Temporal Queries expose in-memory workflow state on demand. In the Workflow SDK,
 
 ### Minimal translation
 
-`start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
+In v5, call `start()` directly from the workflow to spawn a child run. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to await the child result. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
 
 ```typescript title="workflow/workflows/parent.ts"
 import { start } from 'workflow/api';
 
-async function spawnChild(item: string) {
-  'use step'; // [!code highlight]
-  return start(childWorkflow, [item]); // [!code highlight]
-}
-
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item); // [!code highlight]
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return { childRunId: child.runId };
 }
 ```
@@ -204,7 +199,7 @@ async function collectResult(runId: string) {
 }
 ```
 
-Call both steps from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls.
+Call `start()` and then `collectResult()` from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `start()` inside a loop, then `Promise.all` the `collectResult` calls.
 
 <Callout type="warn">
 Activity retry policy moves to the step boundary. Use `maxRetries`, `RetryableError`, and `FatalError` on each step instead of a single workflow-wide retry block.
@@ -308,7 +303,7 @@ Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server
 - Convert each Activity into a `"use step"` function.
 - Remove Worker and Task Queue code. Start workflows from the app with `start()`.
 - Replace Signals with `createHook()` or `createWebhook()` for HTTP callers.
-- Wrap `start()` and `getRun()` in `"use step"` functions for child workflows. Return the `Run` object from `start()` so observability can deep-link into child runs.
+- Use `start()` directly for child workflows, and wrap `getRun()` in a `"use step"` function when collecting results. Return the `Run` object from `start()` so observability can deep-link into child runs.
 - Set retry policy per step with `maxRetries`, `RetryableError`, and `FatalError`.
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.
 - Stream status and progress from steps with `getWritable({ namespace: 'status' })`, and have clients read from the stream instead of polling.

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -48,7 +48,7 @@ Migration collapses the task abstraction into plain async functions. Business lo
 | `logger` / `metadata.set` | `console` + `getWritable({ namespace: 'status' })` | Logs flow through the run timeline. Status writes go on a named stream. |
 | `wait.for({ seconds \| minutes \| hours \| days })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
 | `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
-| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Wrap both in `"use step"` functions. |
+| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Call `start()` directly; wrap `getRun()` collection in a `"use step"` function. |
 | `batch.triggerAndWait()` | `Promise.all(runIds.map(collectResult))` | Fan out via standard concurrency. |
 | `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
 | `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry count lives on the step via `myStep.maxRetries = N` (default 3). Control delay between attempts by throwing `new RetryableError(msg, { retryAfter: '5s' })` — there is no built-in exponential helper; compute the delay yourself based on `getStepMetadata().attempt` if you need one. |
@@ -180,23 +180,14 @@ A hook is an inbound write channel. The caller that knows the token resumes the
 
 ## Spawn a child workflow
 
-`triggerAndWait()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the full `Run` object from `spawnChild` so observability tooling can deep-link to the child run.
+`triggerAndWait()` splits into spawn and collect. In v5, call `start()` directly from the workflow to spawn the child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to collect the result.
 
 You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler). The runtime serializes `Run` to its `runId` in the event log either way.
 
-```typescript title="workflow/workflows/parent.ts"
-import { start } from 'workflow/api';
-
-async function spawnChild(item: string) {
-  'use step';
-  return start(childWorkflow, [item]); // [!code highlight]
-}
-```
-
-Await the result in a second step, then orchestrate both from the parent:
+Await the result in a step, then orchestrate both from the parent:
 
 ```typescript title="workflow/workflows/parent.ts"
-import { getRun } from 'workflow/api';
+import { getRun, start } from 'workflow/api';
 
 async function collectResult(runId: string) {
   'use step';
@@ -206,12 +197,12 @@ async function collectResult(runId: string) {
 
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item);
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return await collectResult(child.runId);
 }
 ```
 
-To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
+To fan out, call `start()` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
 
 `Promise.all` rejects on first failure; use `Promise.allSettled` if you need batch-mode error tolerance similar to trigger.dev's `{ ok, output, error }` per-run result.
 
@@ -273,7 +264,7 @@ async function loadOrder(id: string) {
 - `wait.for({ seconds | minutes | hours | days })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
 - `wait.forToken(token)` → `createHook({ token })` + `await`. Complete it with `resumeHook(token, payload)` from an API route.
 - `wait.forToken({ timeout })` → `Promise.race([hook, sleep(timeout)])`.
-- `triggerAndWait(payload)` → wrap `start(child, [payload])` in a `"use step"` function and return the `Run` object, then read the result with a second step that calls `getRun(runId).returnValue`.
+- `triggerAndWait(payload)` → call `start(child, [payload])` from the workflow and return the `Run` object, then read the result with a step that calls `getRun(runId).returnValue`.
 
 ### Step 5: Start runs from the app
 
@@ -324,7 +315,7 @@ Throw `new RetryableError(msg, { retryAfter: '5s' })` to control delay between a
 - Swap `wait.for` / `wait.until` for `sleep()` from `workflow`.
 - Swap `wait.forToken` for `createHook()` (internal) or `createWebhook()` (HTTP).
 - Model `wait.forToken` timeouts as `Promise.race()` between the hook and `sleep()`.
-- Replace `triggerAndWait()` with `"use step"` wrappers around `start()` and `getRun()`.
+- Replace `triggerAndWait()` with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
 - Replace `batch.triggerAndWait()` with `Promise.all` over the collected child `Run` handles.
 - Move `schemaTask` validation to the call site; pass typed arguments into the workflow.
 - Replace `AbortTaskRunError` with `FatalError`; model retries per step with `RetryableError` and `maxRetries`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.4",
+  "version": "5.0.0-beta.6",
   "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.6",
+    "@workflow/cli": "5.0.0-beta.6",
+    "@workflow/core": "5.0.0-beta.6",
+    "@workflow/errors": "5.0.0-beta.3",
     "@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.6",
+    "@workflow/nest": "5.0.0-beta.6",
+    "@workflow/nitro": "5.0.0-beta.6",
+    "@workflow/nuxt": "5.0.0-beta.6",
+    "@workflow/sveltekit": "5.0.0-beta.6",
+    "@workflow/rollup": "5.0.0-beta.6"
   },
   "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