Workflow API

Every block below is compared character by character with the source files named above. If they drift apart, the documentation build fails.

Verified source excerpts

export function defineWorkflow<
  Variables extends Record<string, JSONValue> = Record<string, JSONValue>,
  Result extends Serializable<Result> = Serializable<unknown>,
  Params extends Serializable<Params> = Serializable<unknown>,
>(
  options: DefineWorkflowOptions<Params>,
  execute: ExecuteWorkflow<Params, Result, WorkflowInstanceVariables & Variables>,
): ExportedWorkflowDefinition<Params, Result, WorkflowInstanceVariables & Variables> {

export interface DefineWorkflowOptions<

export interface WorkflowDefinitionOptions {

export * from '@identity-flow/api';

Definition shape

defineWorkflow(options, execute). options is DefineWorkflowOptions, which adds the name and an optional Standard Schema input on top of WorkflowDefinitionOptions. Whatever execute(flow) returns is the result of the completed run.

Core flow members

These are the members you get on flow. The generic parameters matter more than the one-line signatures suggest — read the surrounding types in the source before depending on a return shape.

readonly definition: WorkflowDefinition;
readonly instance: ActiveWorkflowInstance;
readonly params: Params;
vars: Partial<Variables>;
readonly use: UseAPI;
do<T extends Serializable<T> = Serializable<unknown>>(
sleep(name: string, until: SleepOptions['until'] | SleepOptions): Promise<void>;
dialog<
request<Result extends Serializable<Result> = Serializable<unknown>>(
start<

export type TaskOptions = StepConfig;
export interface RetryStrategy {
readonly retries?: Optional<false | number | DurationString | RetryStrategy>;
export class NonRetryableError extends WorkflowError {
export class ValidationError extends WorkflowError {

Retry and error contracts

flow.do and the other activity APIs take TaskOptions (an alias for StepConfig). retries accepts false, a number, a duration string, or a RetryStrategy with limit, delay, and backoff.

NonRetryableError means don’t try again. ValidationError is not retried unless you pass retryable: true explicitly — the default assumes invalid input stays invalid.

The blocks above are the exact names and shapes for this release. See Errors and Retries for how to use them.

Identity and observation

Dialog recipients always carry a provider. Observing an instance returns its current state, steps, and events — it is a read, and it does not authorize anything on its own.