workflow 5.0.0-beta.5 → 5.0.0-beta.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.5",
+  "version": "5.0.0-beta.51",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -49,6 +49,8 @@
     "./astro": "./dist/astro.js",
     "./vite": "./dist/vite.js",
     "./nest": "./dist/nest.js",
+    "./nest/builder": "./dist/nest-builder.js",
+    "./nest/vercel-builder": "./dist/nest-vercel-builder.js",
     "./runtime": "./dist/runtime.js",
     "./observability": {
       "types": "./dist/observability.d.ts",
@@ -56,24 +58,25 @@
     }
   },
   "dependencies": {
+    "@workflow/astro": "5.0.0-beta.51",
+    "@workflow/cli": "5.0.0-beta.51",
+    "@workflow/core": "5.0.0-beta.51",
+    "@workflow/errors": "5.0.0-beta.21",
+    "@workflow/typescript-plugin": "5.0.0-beta.5",
+    "@workflow/utils": "5.0.0-beta.10",
     "ms": "2.1.3",
-    "@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.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"
+    "@workflow/next": "5.0.0-beta.51",
+    "@workflow/nest": "5.0.0-beta.51",
+    "@workflow/nitro": "5.0.0-beta.51",
+    "@workflow/nuxt": "5.0.0-beta.51",
+    "@workflow/sveltekit": "5.0.0-beta.51",
+    "@workflow/rollup": "5.0.0-beta.51"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",
     "@types/node": "22.19.0",
-    "@workflow/tsconfig": "5.0.0-beta.0"
+    "@workflow/tsconfig": "5.0.0-beta.0",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "1"

package/docs/api-reference/workflow-api/world/index.mdx

@@ -1,58 +0,0 @@
----
-title: World SDK
-description: Low-level API for inspecting and managing workflow runs, steps, events, hooks, streams, and queues.
-type: overview
-summary: Access workflow infrastructure via await getWorld() for building observability dashboards, admin tools, and custom integrations.
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-keywords:
-  - getWorld
-  - World SDK
-  - workflow runtime
-  - observability dashboard
-  - admin panel
-  - workflow management
----
-
-The World SDK provides direct access to workflow infrastructure — runs, steps, events, hooks, streams, and queues. Use it to build observability dashboards, admin panels, debugging tools, and custom workflow management logic.
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = await getWorld(); // [!code highlight]
-```
-
-## Interfaces
-
-<Cards>
-    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
-        Query runs, steps, hooks, and the underlying event log.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
-        Read, write, and manage real-time data streams for workflow runs.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
-        Low-level queue dispatch (internal SDK infrastructure).
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
-        Hydrate step I/O, parse display names, and decrypt workflow data.
-    </Card>
-</Cards>
-
-<Callout type="info">
-  The World SDK is the low-level foundation that higher-level functions like [`getRun()`](/docs/api-reference/workflow-api/get-run) and [`start()`](/docs/api-reference/workflow-api/start) are built on. Use it when you need capabilities beyond what those functions provide.
-</Callout>
-
-## Data Hydration
-
-Step input/output data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. To display this data in your UI, use the hydration utilities from `workflow/observability`:
-
-```typescript lineNumbers
-import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
-
-const step = await world.steps.get(runId, stepId);
-const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-console.log(hydrated.input, hydrated.output);
-```
-
-See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full API.

package/docs/api-reference/workflow-api/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "World SDK",
-  "pages": ["storage", "streams", "queue", "observability"]
-}

package/docs/api-reference/workflow-api/world/observability.mdx

@@ -1,164 +0,0 @@
----
-title: Observability Utilities
-description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
-type: reference
-summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/storage
-keywords:
-  - workflow/observability
-  - hydrateResourceIO
-  - observabilityRevivers
-  - parseStepName
-  - parseWorkflowName
-  - parseClassName
-  - getEncryptionKeyForRun
-  - hydrateResourceIOWithKey
-  - data hydration
-  - devalue deserialization
-  - encryption decryption
-  - display name parsing
----
-
-The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
-
-## Import
-
-```typescript lineNumbers
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-  parseStepName, // [!code highlight]
-  parseWorkflowName, // [!code highlight]
-  parseClassName, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
-```
-
-## Data Hydration
-
-### hydrateResourceIO()
-
-Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Required to display step input/output in your UI.
-
-```typescript lineNumbers
-import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
-
-const step = await world.steps.get(runId, stepId);
-const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-console.log(hydrated.input, hydrated.output);
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
-| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
-
-**Returns:** The resource with hydrated `input` and `output` fields.
-
-### observabilityRevivers
-
-A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
-
-## Name Parsing
-
-Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
-
-### parseStepName()
-
-```typescript lineNumbers
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
-// parsed?.shortName → "processPayment"
-// parsed?.moduleSpecifier → "./src/workflows/order"
-```
-
-### parseWorkflowName()
-
-```typescript lineNumbers
-import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
-// parsed?.shortName → "processOrder"
-```
-
-### parseClassName()
-
-```typescript lineNumbers
-import { parseClassName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
-// parsed?.shortName → "User"
-```
-
-## Encryption
-
-For workflows with encrypted step data, decrypt before hydrating.
-
-### getEncryptionKeyForRun()
-
-Retrieve the encryption key used for a specific workflow run.
-
-{/* @expect-error:2305 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-
-**Returns:** Encryption key for the run
-
-### hydrateResourceIOWithKey()
-
-Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
-
-{/* @expect-error:2305,2724 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
-| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
-
-**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
-
-## Examples
-
-### Parse Display Names for a Run's Steps
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const world = await getWorld();
-const run = await world.runs.get(runId, { resolveData: "none" });
-console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
-
-const steps = await world.steps.list({ runId, resolveData: "none" });
-for (const step of steps.data) {
-  const parsed = parseStepName(step.stepName); // [!code highlight]
-  console.log(`  ${parsed?.shortName}: ${step.status}`); // [!code highlight]
-}
-```
-
-## Related
-
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
-- [Serialization](/docs/foundations/serialization) — How workflow data is serialized

package/docs/api-reference/workflow-api/world/queue.mdx

@@ -1,86 +0,0 @@
----
-title: Queue
-description: Low-level queue interface for dispatching workflow and step invocations.
-type: reference
-summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/start
-  - /docs/foundations/starting-workflows
-keywords:
-  - world.queue
-  - getDeploymentId
-  - queue
-  - createQueueHandler
-  - ValidQueueName
-  - queue dispatch
----
-
-Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
-
-<Callout type="warn">
-  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
-</Callout>
-
-## Import
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-const world = await getWorld(); // [!code highlight]
-// Queue methods are called directly on world — e.g. world.queue()
-```
-
-## Methods
-
-### getDeploymentId()
-
-Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
-
-```typescript lineNumbers
-const deploymentId = await world.getDeploymentId(); // [!code highlight]
-```
-
-**Returns:** `string` — The current deployment ID
-
-### queue()
-
-Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
-
-```typescript lineNumbers
-const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `queueName` | `ValidQueueName` | The queue name (branded string) |
-| `message` | `QueuePayload` | Internal SDK payload |
-| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
-
-**Returns:** `{ messageId: MessageId | null }`
-
-### createQueueHandler()
-
-Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
-
-```typescript lineNumbers
-const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `prefix` | `QueuePrefix` | Queue name prefix to match |
-| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
-
-**Returns:** `(req: Request) => Promise<Response>`
-
-## Related
-
-- [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
-- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Create events that trigger queue dispatch

package/docs/deploying/building-a-world.mdx

@@ -1,251 +0,0 @@
----
-title: Building a World
-description: Implement the World interface to run workflows on any custom infrastructure.
-type: guide
-summary: Build a custom World adapter to run workflows on your own infrastructure.
-prerequisites:
-  - /docs/deploying
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
----
-
-A **World** is the abstraction that allows workflows to run on any infrastructure. It handles workflow storage, step execution queuing, and data streaming. This guide explains the World interface and how to implement your own.
-
-<Callout>
-  Before building a custom World, check the [Worlds Ecosystem](/worlds) page — there may already be a community implementation for your infrastructure.
-</Callout>
-
-<Callout type="info">
-  **Reference Implementation:** The [Postgres World source code](https://github.com/vercel/workflow/tree/main/packages/world-postgres) is a production-ready example of how to implement the World interface with a database backend and graphile-worker for queuing.
-</Callout>
-
-## What is a World?
-
-A World connects workflows to the infrastructure that powers them. The World interface abstracts three core responsibilities:
-
-1. **Storage** — Persisting workflow runs, steps, hooks, and the event log
-2. **Queue** — Enqueuing and processing workflow and step invocations
-3. **Streamer** — Managing real-time data streams between workflows and clients
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface World extends Storage, Queue, Streamer {
-  start?(): Promise<void>;
-  close?(): Promise<void>;
-  getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
-  getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
-}
-```
-
-The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
-
-## The Event Log Model
-
-Workflow storage is built on an **append-only event log**. All state changes happen through events — you never modify runs, steps, or hooks directly. Instead, you create events that update the materialized state.
-
-Events fall into three categories: run lifecycle events, step lifecycle events, and hook lifecycle events. See the [Event Sourcing](/docs/how-it-works/event-sourcing) documentation for a complete list of event types and their semantics.
-
-## Storage Interface
-
-The Storage interface provides read access to materialized entities and write access through events:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Storage {
-  runs: {
-    get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun>;
-    list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun>>;
-  };
-
-  steps: {
-    get(runId: string | undefined, stepId: string, params?: GetStepParams): Promise<Step>;
-    list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step>>;
-  };
-
-  events: {
-    // Create a new workflow run (runId may be client-provided or null for server generation)
-    create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
-    
-    // Create an event for an existing run
-    create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
-    
-    list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
-    listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
-  };
-
-  hooks: {
-    get(hookId: string, params?: GetHookParams): Promise<Hook>;
-    getByToken(token: string, params?: GetHookParams): Promise<Hook>;
-    list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
-  };
-}
-```
-
-### Key Implementation Details
-
-**Event Creation:** When `events.create()` is called, your implementation must:
-1. Persist the event to the event log
-2. Atomically update the affected entity (run, step, or hook)
-3. Return both the created event and the updated entity
-
-**Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
-
-**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.
-
-**Automatic Hook Disposal:** When a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`), automatically dispose of all associated hooks to release tokens for reuse.
-
-## Queue Interface
-
-The Queue interface handles asynchronous execution of workflows and steps:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Queue {
-  getDeploymentId(): Promise<string>;
-
-  queue(
-    queueName: ValidQueueName,
-    message: QueuePayload,
-    opts?: QueueOptions
-  ): Promise<{ messageId: MessageId }>;
-
-  createQueueHandler(
-    queueNamePrefix: QueuePrefix,
-    handler: (message: unknown, meta: { attempt: number; queueName: ValidQueueName; messageId: MessageId }) => Promise<void | { timeoutSeconds: number }>
-  ): (req: Request) => Promise<Response>;
-}
-```
-
-### Queue Names
-
-Queue names follow a specific pattern:
-- `__wkf_workflow_<name>` — For workflow invocations
-- `__wkf_step_<name>` — For step invocations
-
-### Message Payloads
-
-Two types of messages flow through queues:
-
-**Workflow Invocations:**
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface WorkflowInvokePayload {
-  runId: string;
-  traceCarrier?: Record<string, string>;  // OpenTelemetry context
-  requestedAt?: Date;
-}
-```
-
-**Step Invocations:**
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface StepInvokePayload {
-  workflowName: string;
-  workflowRunId: string;
-  workflowStartedAt: number;
-  stepId: string;
-  traceCarrier?: Record<string, string>;
-  requestedAt?: Date;
-}
-```
-
-### Implementation Considerations
-
-- Messages must be delivered at-least-once
-- Support configurable retry policies
-- Track attempt counts for observability
-- Implement idempotency using the `idempotencyKey` option when provided
-
-## Streamer Interface
-
-The Streamer interface enables real-time data streaming:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Streamer {
-  streamFlushIntervalMs?: number;
-
-  streams: {
-    write(
-      runId: string,
-      name: string,
-      chunk: string | Uint8Array
-    ): Promise<void>;
-
-    writeMulti?(
-      runId: string,
-      name: string,
-      chunks: (string | Uint8Array)[]
-    ): Promise<void>;
-
-    close(runId: string, name: string): Promise<void>;
-
-    get(
-      runId: string,
-      name: string,
-      startIndex?: number
-    ): Promise<ReadableStream<Uint8Array>>;
-
-    list(runId: string): Promise<string[]>;
-
-    /** Paginated snapshot of stream chunks. */
-    getChunks(
-      runId: string,
-      name: string,
-      options?: { limit?: number; cursor?: string }
-    ): Promise<{
-      data: { index: number; data: Uint8Array }[];
-      cursor: string | null;
-      hasMore: boolean;
-      done: boolean;
-    }>;
-
-    /** Lightweight metadata: tail index and completion flag. */
-    getInfo(
-      runId: string,
-      name: string
-    ): Promise<{ tailIndex: number; done: boolean }>;
-  };
-}
-```
-
-Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
-`writeMulti()` is an optional optimization for batching multiple writes.
-
-`getChunks` returns a paginated snapshot of currently available chunks (unlike `get` which returns a live `ReadableStream` that waits for new chunks). `getInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
-
-## Reference Implementations
-
-Study these implementations for guidance:
-
-- **[Local World](https://github.com/vercel/workflow/tree/main/packages/world-local)** — Filesystem-based, great for understanding the basics
-- **[Postgres World](https://github.com/vercel/workflow/tree/main/packages/world-postgres)** — Database-backed with graphile-worker for queuing
-
-## Testing Your World
-
-Workflow SDK includes an E2E test suite that validates World implementations. Once your World is published to npm:
-
-1. Add your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
-2. Open a PR to the Workflow repository
-3. CI will automatically run the E2E test suite against your implementation
-
-Your world will then appear on the [Worlds Ecosystem](/worlds) page with its compatibility status and performance benchmarks.
-
-## Publishing Your World
-
-1. **Package your World** — Export a default World instance from your package
-2. **Publish to npm** — Publish your package to npm
-3. **Add to the manifest** — Submit a PR adding your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
-4. **Document configuration** — Clearly document any required environment variables
-
-```json
-// worlds-manifest.json entry
-{
-  "package": "your-world-package",
-  "repository": "https://github.com/you/your-world",
-  "docs": "https://github.com/you/your-world#readme"
-}
-```