@workflow/core 4.0.1-beta.9 → 4.1.0-beta.52

package/docs/foundations/serialization.mdx

@@ -0,0 +1,158 @@
+---
+title: Serialization
+description: Understand how workflow data is serialized and persisted across suspensions and resumptions.
+---
+
+All function arguments and return values passed between workflow and step functions must be serializable. Workflow DevKit uses a custom serialization system built on top of [devalue](https://github.com/sveltejs/devalue). This system supports standard JSON types, as well as a few additional popular Web API types.
+
+<Callout type="info">
+The serialization system ensures that all data persists correctly across workflow suspensions and resumptions, enabling durable execution.
+</Callout>
+
+## Supported Serializable Types
+
+The following types can be serialized and passed through workflow functions:
+
+**Standard JSON Types:**
+
+- `string`
+- `number`
+- `boolean`
+- `null`
+- Arrays of serializable values
+- Objects with string keys and serializable values
+
+**Extended Types:**
+
+- `undefined`
+- `bigint`
+- `ArrayBuffer`
+- `BigInt64Array`, `BigUint64Array`
+- `Date`
+- `Float32Array`, `Float64Array`
+- `Int8Array`, `Int16Array`, `Int32Array`
+- `Map<Serializable, Serializable>`
+- `RegExp`
+- `Set<Serializable>`
+- `URL`
+- `URLSearchParams`
+- `Uint8Array`, `Uint8ClampedArray`, `Uint16Array`, `Uint32Array`
+
+**Notable:**
+
+<Callout type="info">
+These types have special handling and are explained in detail in the sections below.
+</Callout>
+
+- `Headers`
+- `Request`
+- `Response`
+- `ReadableStream<Serializable>`
+- `WritableStream<Serializable>`
+
+## Streaming
+
+`ReadableStream` and `WritableStream` are supported as serializable types with special handling. These streams can be passed between workflow and step functions while maintaining their streaming capabilities.
+
+For complete information about using streams in workflows, including patterns for AI streaming, file processing, and progress updates, see the [Streaming Guide](/docs/foundations/streaming).
+
+## Request & Response
+
+The Web API [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) APIs are supported by the serialization system,
+and can be passed around between workflow and step functions similarly to other data types.
+
+As a convenience, these two APIs are treated slightly differently when used
+within a workflow function: calling the `text()` / `json()` / `arrayBuffer()` instance
+methods is automatically treated as a step function invocation. This allows you to consume
+the body directly in the workflow context while maintaining proper serialization and caching.
+
+For example, consider how receiving a webhook request provides the entire `Request`
+instance into the workflow context. You may consume the body of that request directly
+in the workflow, which will be cached as a step result for future resumptions of the workflow:
+
+```typescript title="workflows/webhook.ts" lineNumbers
+import { createWebhook } from "workflow";
+
+export async function handleWebhookWorkflow() {
+  "use workflow";
+
+  const webhook = createWebhook();
+  const request = await webhook;
+
+  // The body of the request will only be consumed once // [!code highlight]
+  const body = await request.json(); // [!code highlight]
+
+  // …
+}
+```
+
+### Using `fetch` in Workflows
+
+Because `Request` and `Response` are serializable, Workflow DevKit provides a `fetch` function that can be used directly in workflow functions:
+
+```typescript title="workflows/api-call.ts" lineNumbers
+import { fetch } from "workflow"; // [!code highlight]
+
+export async function apiWorkflow() {
+  "use workflow";
+
+  // fetch can be called directly in workflows // [!code highlight]
+  const response = await fetch("https://api.example.com/data"); // [!code highlight]
+  const data = await response.json();
+
+  return data;
+}
+```
+
+The implementation is straightforward - `fetch` from workflow is a step function that wraps the standard `fetch`:
+
+```typescript title="Implementation" lineNumbers
+export async function fetch(...args: Parameters<typeof globalThis.fetch>) {
+  "use step";
+  return globalThis.fetch(...args);
+}
+```
+
+This allows you to make HTTP requests directly in workflow functions while maintaining deterministic replay behavior through automatic caching.
+
+## Pass-by-Value Semantics
+
+**Parameters are passed by value, not by reference.** Steps receive deserialized copies of data. Mutations inside a step won't affect the original in the workflow.
+
+**Incorrect:**
+
+```typescript title="workflows/incorrect-mutation.ts" lineNumbers
+export async function updateUserWorkflow(userId: string) {
+  "use workflow";
+
+  let user = { id: userId, name: "John", email: "john@example.com" };
+  await updateUserStep(user);
+
+  // user.email is still "john@example.com" // [!code highlight]
+  console.log(user.email); // [!code highlight]
+}
+
+async function updateUserStep(user: { id: string; name: string; email: string }) {
+  "use step";
+  user.email = "newemail@example.com"; // Changes are lost // [!code highlight]
+}
+```
+
+**Correct - return the modified data:**
+
+```typescript title="workflows/correct-mutation.ts" lineNumbers
+export async function updateUserWorkflow(userId: string) {
+  "use workflow";
+
+  let user = { id: userId, name: "John", email: "john@example.com" };
+  user = await updateUserStep(user); // Reassign the return value // [!code highlight]
+
+  console.log(user.email); // "newemail@example.com"
+}
+
+async function updateUserStep(user: { id: string; name: string; email: string }) {
+  "use step";
+  user.email = "newemail@example.com";
+  return user; // [!code highlight]
+}
+```

package/docs/foundations/starting-workflows.mdx

@@ -0,0 +1,212 @@
+---
+title: Starting Workflows
+description: Trigger workflow execution with the start() function and track progress with Run objects.
+---
+
+Once you've defined your workflow functions, you need to trigger them to begin execution. This is done using the `start()` function from `workflow/api`, which enqueues a new workflow run and returns a `Run` object that you can use to track its progress.
+
+## The `start()` Function
+
+The [`start()`](/docs/api-reference/workflow-api/start) function is used to programmatically trigger workflow executions from runtime contexts like API routes, Server Actions, or any server-side code.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { handleUserSignup } from "./workflows/user-signup";
+
+export async function POST(request: Request) {
+  const { email } = await request.json();
+
+  // Start the workflow
+  const run = await start(handleUserSignup, [email]); // [!code highlight]
+
+  return Response.json({
+    message: "Workflow started",
+    runId: run.runId
+  });
+}
+```
+
+**Key Points:**
+
+- `start()` returns immediately after enqueuing the workflow - it doesn't wait for completion
+- The first argument is your workflow function
+- The second argument is an array of arguments to pass to the workflow (optional if the workflow takes no arguments)
+- All arguments must be [serializable](/docs/foundations/serialization)
+
+**Learn more**: [`start()` API Reference](/docs/api-reference/workflow-api/start)
+
+## The `Run` Object
+
+When you call `start()`, it returns a [`Run`](/docs/api-reference/workflow-api/start#returns) object that provides access to the workflow's status and results.
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { processOrder } from "./workflows/process-order";
+
+const run = await start(processOrder, [/* orderId */]);
+
+// The run object has properties you can await
+console.log("Run ID:", run.runId);
+
+// Check the workflow status
+const status = await run.status; // "running" | "completed" | "failed"
+
+// Get the workflow's return value (blocks until completion)
+const result = await run.returnValue;
+```
+
+**Key Properties:**
+
+- `runId` - Unique identifier for this workflow run
+- `status` - Current status of the workflow (async)
+- `returnValue` - The value returned by the workflow function (async, blocks until completion)
+- `readable` - ReadableStream for streaming updates from the workflow
+
+<Callout type="info">
+Most `Run` properties are async getters that return promises. You need to `await` them to get their values. For a complete list of properties and methods, see the API reference below.
+</Callout>
+
+**Learn more**: [`Run` API Reference](/docs/api-reference/workflow-api/start#returns)
+
+## Common Patterns
+
+### Fire and Forget
+
+The most common pattern is to start a workflow and immediately return, letting it execute in the background:
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { sendNotifications } from "./workflows/notifications";
+
+export async function POST(request: Request) {
+  // Start workflow and don't wait for it
+  const run = await start(sendNotifications, [userId]);
+
+  // Return immediately
+  return Response.json({
+    message: "Notifications queued",
+    runId: run.runId
+  });
+}
+```
+
+### Wait for Completion
+
+If you need to wait for the workflow to complete before responding:
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { generateReport } from "./workflows/reports";
+
+export async function POST(request: Request) {
+  const run = await start(generateReport, [reportId]);
+
+  // Wait for the workflow to complete
+  const report = await run.returnValue; // [!code highlight]
+
+  return Response.json({ report });
+}
+```
+
+<Callout type="warn">
+Be cautious when waiting for `returnValue` - if your workflow takes a long time, your API route may timeout.
+</Callout>
+
+### Stream Updates to Client
+
+Stream real-time updates from your workflow as it executes, without waiting for completion:
+
+```typescript lineNumbers
+import { start } from "workflow/api";
+import { generateAIContent } from "./workflows/ai-generation";
+
+export async function POST(request: Request) {
+  const { prompt } = await request.json();
+
+  // Start the workflow
+  const run = await start(generateAIContent, [prompt]);
+
+  // Get the readable stream (can also use run.readable as shorthand)
+  const stream = run.getReadable(); // [!code highlight]
+
+  // Return the stream immediately
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "application/octet-stream",
+    },
+  });
+}
+```
+
+Your workflow can write to the stream using [`getWritable()`](/docs/api-reference/workflow/get-writable):
+
+```typescript lineNumbers
+import { getWritable } from "workflow";
+
+export async function generateAIContent(prompt: string) {
+  "use workflow";
+
+  const writable = getWritable(); // [!code highlight]
+
+  await streamContentToClient(writable, prompt);
+
+  return { status: "complete" };
+}
+
+async function streamContentToClient(
+  writable: WritableStream,
+  prompt: string
+) {
+  "use step";
+
+  const writer = writable.getWriter();
+
+  // Stream updates as they become available
+  for (let i = 0; i < 10; i++) {
+    const chunk = new TextEncoder().encode(`Update ${i}\n`);
+    await writer.write(chunk);
+  }
+
+  writer.releaseLock();
+}
+```
+
+<Callout type="info">
+Streams are particularly useful for AI workflows where you want to show progress to users in real-time, or for long-running processes that produce intermediate results.
+</Callout>
+
+**Learn more**: [Streaming in Workflows](/docs/foundations/serialization#streaming)
+
+### Check Status Later
+
+You can retrieve a workflow run later using its `runId` with [`getRun()`](/docs/api-reference/workflow-api/get-run):
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const runId = url.searchParams.get("runId");
+
+  // Retrieve the existing run
+  const run = getRun(runId); // [!code highlight]
+
+  // Check its status
+  const status = await run.status;
+
+  if (status === "completed") {
+    const result = await run.returnValue;
+    return Response.json({ result });
+  }
+
+  return Response.json({ status });
+}
+```
+
+## Next Steps
+
+Now that you understand how to start workflows and track their execution:
+
+- Learn about [Common Patterns](/docs/foundations/common-patterns) for organizing complex workflows
+- Explore [Errors & Retrying](/docs/foundations/errors-and-retries) to handle failures gracefully
+- Check the [`start()` API Reference](/docs/api-reference/workflow-api/start) for complete details