workflow 4.2.0-beta.70 → 4.2.0-beta.72

package/docs/api-reference/workflow-errors/entity-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: EntityConflictError
+description: Thrown when a storage operation conflicts with the current entity state.
+type: reference
+summary: Catch EntityConflictError when a world operation conflicts with entity state (e.g. duplicate events or runs).
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/run-expired-error
+---
+
+`EntityConflictError` is thrown by world implementations when a storage operation conflicts with the current entity state. This includes cases like creating a run that already exists or writing an event that has already been persisted.
+
+It corresponds to HTTP 409 Conflict semantics.
+
+<Callout>
+The Workflow runtime handles this error automatically during replay and event deduplication. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { EntityConflictError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (EntityConflictError.is(error)) { // [!code highlight]
+    // Event already exists — safe to ignore during replay
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface EntityConflictError {
+  /** The error message. */
+  message: string;
+}
+export default EntityConflictError;`}
+/>
+
+### Static Methods
+
+#### `EntityConflictError.is(value)`
+
+Type-safe check for `EntityConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { EntityConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (EntityConflictError.is(error)) {
+  // error is typed as EntityConflictError
+}
+```

package/docs/api-reference/workflow-errors/hook-not-found-error.mdx

@@ -0,0 +1,90 @@
+---
+title: HookNotFoundError
+description: Thrown when resuming a hook that does not exist.
+type: reference
+summary: Catch HookNotFoundError when calling resumeHook() or resumeWebhook() with a token that doesn't match any active hook.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/api-reference/workflow/define-hook
+---
+
+`HookNotFoundError` is thrown when calling `resumeHook()` or `resumeWebhook()` with a token that does not match any active hook. This typically happens when:
+
+- The hook has expired (past its TTL)
+- The hook was already consumed and disposed
+- The workflow has not started yet, so the hook does not exist
+
+```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors"
+declare function resumeHook(token: string, payload: any): Promise<any>; // @setup
+declare const token: string; // @setup
+declare const payload: any; // @setup
+
+try {
+  await resumeHook(token, payload);
+} catch (error) {
+  if (HookNotFoundError.is(error)) { // [!code highlight]
+    console.error("Hook not found:", error.token);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookNotFoundError {
+  /** The hook token that was not found. */
+  token: string;
+  /** The error message. */
+  message: string;
+}
+export default HookNotFoundError;`}
+/>
+
+### Static Methods
+
+#### `HookNotFoundError.is(value)`
+
+Type-safe check for `HookNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { HookNotFoundError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookNotFoundError.is(error)) {
+  // error is typed as HookNotFoundError
+}
+```
+
+## Examples
+
+### Resume hook or start workflow
+
+A common pattern for idempotent workflows is to try resuming a hook, and if it doesn't exist yet, start a new workflow run with the input data.
+
+<Callout>
+This "resume or start" pattern is not atomic — there is a small window where a race condition is possible. A better native approach is being worked on, but this pattern works well for many use cases.
+</Callout>
+
+```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors"
+declare function resumeHook(token: string, data: unknown): Promise<any>; // @setup
+declare function startWorkflow(name: string, data: unknown): Promise<any>; // @setup
+
+async function handleIncomingEvent(token: string, data: unknown) {
+  try {
+    // Try to resume an existing hook
+    await resumeHook(token, data);
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      // Hook doesn't exist yet — start a new workflow run
+      await startWorkflow("processEvent", data); // [!code highlight]
+    } else {
+      throw error;
+    }
+  }
+}
+```

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

@@ -0,0 +1,16 @@
+{
+  "title": "workflow/errors",
+  "pages": [
+    "hook-not-found-error",
+    "step-not-registered-error",
+    "workflow-not-registered-error",
+    "workflow-run-not-found-error",
+    "workflow-run-failed-error",
+    "workflow-run-cancelled-error",
+    "workflow-world-error",
+    "throttle-error",
+    "entity-conflict-error",
+    "run-expired-error",
+    "too-early-error"
+  ]
+}

package/docs/api-reference/workflow-errors/run-expired-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunExpiredError
+description: Thrown when a workflow run has expired and can no longer be operated on.
+type: reference
+summary: Catch RunExpiredError when a workflow run has expired and can no longer accept operations.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/entity-conflict-error
+---
+
+`RunExpiredError` is thrown by world implementations when a workflow run has expired and can no longer be operated on. It corresponds to HTTP 410 Gone semantics.
+
+<Callout>
+The Workflow runtime handles this error automatically. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { RunExpiredError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (RunExpiredError.is(error)) { // [!code highlight]
+    console.log("Run has expired and can no longer accept events");
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunExpiredError {
+  /** The error message. */
+  message: string;
+}
+export default RunExpiredError;`}
+/>
+
+### Static Methods
+
+#### `RunExpiredError.is(value)`
+
+Type-safe check for `RunExpiredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { RunExpiredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunExpiredError.is(error)) {
+  // error is typed as RunExpiredError
+}
+```

package/docs/api-reference/workflow-errors/step-not-registered-error.mdx

@@ -0,0 +1,56 @@
+---
+title: StepNotRegisteredError
+description: Thrown when a step function is not registered in the current deployment.
+type: reference
+summary: Catch StepNotRegisteredError when a step function cannot be found during execution.
+related:
+  - /docs/errors/step-not-registered
+  - /docs/api-reference/workflow-errors/workflow-not-registered-error
+---
+
+`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
+
+When this error occurs, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can handle the failure gracefully.
+
+```typescript lineNumbers
+import { StepNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (StepNotRegisteredError.is(error)) { // [!code highlight]
+  console.error("Step not registered:", error.stepName);
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface StepNotRegisteredError {
+  /** The name of the step function that was not found. */
+  stepName: string;
+  /** The error message. */
+  message: string;
+}
+export default StepNotRegisteredError;`}
+/>
+
+### Static Methods
+
+#### `StepNotRegisteredError.is(value)`
+
+Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout>
+The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances — use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
+</Callout>
+
+```typescript
+import { StepNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (StepNotRegisteredError.is(error)) {
+  // error is typed as StepNotRegisteredError
+}
+```

package/docs/api-reference/workflow-errors/throttle-error.mdx

@@ -0,0 +1,62 @@
+---
+title: ThrottleError
+description: Thrown when a request is rate-limited by the workflow backend.
+type: reference
+summary: Catch ThrottleError when a workflow storage operation is rate-limited (HTTP 429).
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/too-early-error
+---
+
+`ThrottleError` is thrown when a request to the workflow backend is rate-limited. It corresponds to HTTP 429 Too Many Requests semantics.
+
+The `retryAfter` property contains the number of seconds to wait before retrying.
+
+<Callout>
+The Workflow runtime handles this error automatically by backing off and retrying. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { ThrottleError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (ThrottleError.is(error)) { // [!code highlight]
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface ThrottleError {
+  /** The number of seconds to wait before retrying. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default ThrottleError;`}
+/>
+
+### Static Methods
+
+#### `ThrottleError.is(value)`
+
+Type-safe check for `ThrottleError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { ThrottleError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (ThrottleError.is(error)) {
+  // error is typed as ThrottleError
+}
+```

package/docs/api-reference/workflow-errors/too-early-error.mdx

@@ -0,0 +1,62 @@
+---
+title: TooEarlyError
+description: Thrown when a request is made before the system is ready to process it.
+type: reference
+summary: Catch TooEarlyError when a world operation is attempted before the system is ready.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/throttle-error
+---
+
+`TooEarlyError` is thrown by world implementations when a request is made before the system is ready to process it. It corresponds to HTTP 425 Too Early semantics.
+
+The `retryAfter` property contains the number of seconds to wait before retrying.
+
+<Callout>
+The Workflow runtime handles this error automatically by retrying after the specified delay. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { TooEarlyError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (TooEarlyError.is(error)) { // [!code highlight]
+    console.log(`Retry after ${error.retryAfter} seconds`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface TooEarlyError {
+  /** Delay in seconds before the operation can be retried. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default TooEarlyError;`}
+/>
+
+### Static Methods
+
+#### `TooEarlyError.is(value)`
+
+Type-safe check for `TooEarlyError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { TooEarlyError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (TooEarlyError.is(error)) {
+  // error is typed as TooEarlyError
+}
+```

package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx

@@ -0,0 +1,57 @@
+---
+title: WorkflowNotRegisteredError
+description: Thrown when a workflow function is not registered in the current deployment.
+type: reference
+summary: Catch WorkflowNotRegisteredError when a workflow function cannot be found during execution.
+related:
+  - /docs/errors/workflow-not-registered
+  - /docs/api-reference/workflow-errors/step-not-registered-error
+---
+
+`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
+
+When this error occurs, the run fails with a `RUNTIME_ERROR` error code.
+
+```typescript lineNumbers
+import { WorkflowNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowNotRegisteredError.is(error)) { // [!code highlight]
+  console.error("Workflow not registered:", error.workflowName);
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowNotRegisteredError {
+  /** The name of the workflow function that was not found. */
+  workflowName: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowNotRegisteredError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowNotRegisteredError.is(value)`
+
+Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout>
+The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause` — the underlying error is deserialized from the event log.
+</Callout>
+
+```typescript
+import { WorkflowNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowNotRegisteredError.is(error)) {
+  // error is typed as WorkflowNotRegisteredError
+}
+```
+

package/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx

@@ -0,0 +1,56 @@
+---
+title: WorkflowRunCancelledError
+description: Thrown when awaiting the return value of a cancelled workflow run.
+type: reference
+summary: Catch WorkflowRunCancelledError when awaiting run.returnValue on a run that was cancelled.
+related:
+  - /docs/api-reference/workflow-errors/workflow-run-failed-error
+  - /docs/api-reference/workflow-errors/workflow-run-not-found-error
+---
+
+`WorkflowRunCancelledError` is thrown when awaiting `run.returnValue` on a workflow run that was explicitly cancelled via `run.cancel()`. Cancelled runs do not produce a return value.
+
+You can check for cancellation before awaiting by inspecting `run.status`.
+
+```typescript lineNumbers
+import { WorkflowRunCancelledError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const result = await run.returnValue;
+} catch (error) {
+  if (WorkflowRunCancelledError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} was cancelled`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunCancelledError {
+  /** The ID of the cancelled run. */
+  runId: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunCancelledError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunCancelledError.is(value)`
+
+Type-safe check for `WorkflowRunCancelledError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunCancelledError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunCancelledError.is(error)) {
+  // error is typed as WorkflowRunCancelledError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx

@@ -0,0 +1,62 @@
+---
+title: WorkflowRunFailedError
+description: Thrown when awaiting the return value of a failed workflow run.
+type: reference
+summary: Catch WorkflowRunFailedError when awaiting run.returnValue on a run that encountered a fatal error.
+related:
+  - /docs/api-reference/workflow/fatal-error
+  - /docs/api-reference/workflow-errors/workflow-run-cancelled-error
+  - /docs/api-reference/workflow-errors/workflow-run-not-found-error
+---
+
+`WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.
+
+The `cause` property contains the underlying error with its message, stack trace, and optional error code.
+
+```typescript lineNumbers
+import { WorkflowRunFailedError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const result = await run.returnValue;
+} catch (error) {
+  if (WorkflowRunFailedError.is(error)) { // [!code highlight]
+    console.error(`Run ${error.runId} failed:`, error.cause.message);
+    if (error.cause.code) {
+      console.error("Error code:", error.cause.code);
+    }
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunFailedError {
+  /** The ID of the failed run. */
+  runId: string;
+  /** The underlying error that caused the failure. */
+  cause: Error & { code?: string };
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunFailedError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunFailedError.is(value)`
+
+Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunFailedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunFailedError.is(error)) {
+  // error is typed as WorkflowRunFailedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx

@@ -0,0 +1,56 @@
+---
+title: WorkflowRunNotFoundError
+description: Thrown when operating on a workflow run that does not exist.
+type: reference
+summary: Catch WorkflowRunNotFoundError when performing operations on a non-existent workflow run.
+related:
+  - /docs/api-reference/workflow-errors/workflow-run-failed-error
+  - /docs/api-reference/workflow-errors/workflow-run-cancelled-error
+---
+
+`WorkflowRunNotFoundError` is thrown when performing operations on a workflow run that does not exist. This includes calling methods like `run.status`, `run.cancel()`, or awaiting `run.returnValue` on a run whose ID does not match any known workflow run.
+
+Note that `getRun(id)` itself is synchronous and will not throw — the error is raised when subsequent operations on the run object discover the run is missing.
+
+```typescript lineNumbers
+import { WorkflowRunNotFoundError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const status = await run.status;
+} catch (error) {
+  if (WorkflowRunNotFoundError.is(error)) { // [!code highlight]
+    console.error(`Run ${error.runId} does not exist`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotFoundError {
+  /** The ID of the run that was not found. */
+  runId: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotFoundError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunNotFoundError.is(value)`
+
+Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunNotFoundError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotFoundError.is(error)) {
+  // error is typed as WorkflowRunNotFoundError
+}
+```