Ryte

Appearance

core/src ​

Classes ​

DomainErrorSignal ​

Defined in: packages/core/src/types.ts:181

Thrown internally when a handler calls ctx.error(). Caught by the router and returned as a domain error in DispatchResult.

Param ​

The error code string

Param ​

The error data payload

Extends ​

  • Error

Constructors ​

Constructor ​

new DomainErrorSignal(code, data): DomainErrorSignal

Defined in: packages/core/src/types.ts:182

Parameters ​
code ​

string

data ​

unknown

Returns ​

DomainErrorSignal

Overrides ​

Error.constructor

Properties ​

cause? ​

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from ​

Error.cause

code ​

readonly code: string

Defined in: packages/core/src/types.ts:183

data ​

readonly data: unknown

Defined in: packages/core/src/types.ts:184

message ​

message: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from ​

Error.message

name ​

name: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.name

stack? ​

optional stack?: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from ​

Error.stack

MigrationError ​

Defined in: packages/core/src/migration.ts:55

Error thrown when a migration step fails.

Extends ​

  • Error

Constructors ​

Constructor ​

new MigrationError(fromVersion, toVersion, cause): MigrationError

Defined in: packages/core/src/migration.ts:61

Parameters ​
fromVersion ​

number

The schema version the migration started from

toVersion ​

number

The schema version the migration was attempting to reach

cause ​

unknown

The underlying error that caused the failure

Returns ​

MigrationError

Overrides ​

Error.constructor

Properties ​

cause ​

readonly cause: unknown

Defined in: packages/core/src/migration.ts:64

The underlying error that caused the failure

Inherited from ​

Error.cause

fromVersion ​

readonly fromVersion: number

Defined in: packages/core/src/migration.ts:62

The schema version the migration started from

message ​

message: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from ​

Error.message

name ​

name: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.name

stack? ​

optional stack?: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from ​

Error.stack

toVersion ​

readonly toVersion: number

Defined in: packages/core/src/migration.ts:63

The schema version the migration was attempting to reach

ValidationError ​

Defined in: packages/core/src/types.ts:164

Thrown internally when Zod validation fails during dispatch. Caught by the router and returned as a validation error in DispatchResult.

Param ​

Which validation stage failed

Param ​

Array of Zod validation issues

Extends ​

  • Error

Constructors ​

Constructor ​

new ValidationError(source, issues): ValidationError

Defined in: packages/core/src/types.ts:165

Parameters ​
source ​

"command" | "state" | "event" | "transition" | "restore"

issues ​

$ZodIssue[]

Returns ​

ValidationError

Overrides ​

Error.constructor

Properties ​

cause? ​

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from ​

Error.cause

issues ​

readonly issues: $ZodIssue[]

Defined in: packages/core/src/types.ts:167

message ​

message: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from ​

Error.message

name ​

name: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from ​

Error.name

source ​

readonly source: "command" | "state" | "event" | "transition" | "restore"

Defined in: packages/core/src/types.ts:166

stack? ​

optional stack?: string

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from ​

Error.stack

WorkflowRouter ​

Defined in: packages/core/src/router.ts:90

Routes commands to handlers based on workflow state.

Supports global middleware, state-scoped middleware, inline middleware, wildcard handlers, and multi-state handlers.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps = { }

Constructors ​

Constructor ​

new WorkflowRouter<TConfig, TDeps>(definition, deps?, options?): WorkflowRouter<TConfig, TDeps>

Defined in: packages/core/src/router.ts:106

Parameters ​
definition ​

WorkflowDefinition<TConfig>

The workflow definition describing states, commands, events, and errors

deps? ​

TDeps = ...

Dependencies injected into every handler context

options? ​

RouterOptions = {}

Router configuration options

Returns ​

WorkflowRouter<TConfig, TDeps>

Properties ​

definition ​

readonly definition: WorkflowDefinition<TConfig>

Defined in: packages/core/src/router.ts:107

The workflow definition describing states, commands, events, and errors

Methods ​

dispatch() ​

dispatch<C>(workflow, command): Promise<DispatchResult<TConfig>>

Defined in: packages/core/src/router.ts:327

Dispatches a command to the appropriate handler and returns the result.

Type Parameters ​
C ​

C extends string

Parameters ​
workflow ​

Workflow<TConfig>

The current workflow instance to dispatch against

command ​

The command with its type and payload

payload ​

{ [K in string | number | symbol]: TConfig["_resolved"]["commands"][C][K] }

type ​

C

Returns ​

Promise<DispatchResult<TConfig>>

A DispatchResult indicating success or failure with the updated workflow and events

on() ​
Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:222

Registers a lifecycle hook callback.

Parameters ​
event ​

"dispatch:start"

The lifecycle event name

callback ​

(workflow, command) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:226

Registers a lifecycle hook callback.

Parameters ​
event ​

"dispatch:end"

The lifecycle event name

callback ​

(workflow, command, result) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:234

Registers a lifecycle hook callback.

Parameters ​
event ​

"pipeline:start"

The lifecycle event name

callback ​

(ctx) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:238

Registers a lifecycle hook callback.

Parameters ​
event ​

"pipeline:end"

The lifecycle event name

callback ​

(ctx, result) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:245

Registers a lifecycle hook callback.

Parameters ​
event ​

"transition"

The lifecycle event name

callback ​

(from, to, workflow) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:253

Registers a lifecycle hook callback.

Parameters ​
event ​

"error"

The lifecycle event name

callback ​

(error, ctx) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on(event, callback): this

Defined in: packages/core/src/router.ts:260

Registers a lifecycle hook callback.

Parameters ​
event ​

"event"

The lifecycle event name

callback ​

(event, workflow) => void | Promise<void>

The callback to invoke when the event fires

Returns ​

this

Call Signature ​

on<C>(state, command, handler): this

Defined in: packages/core/src/router.ts:273

Registers a wildcard handler that matches any state.

Type Parameters ​
C ​

C extends string

Parameters ​
state ​

"*"

Must be "*" to match all states

command ​

C

The command name to handle

handler ​

(ctx) => void | Promise<void>

The terminal handler

Returns ​

this

Call Signature ​

on<C>(state, command, ...fns): this

Defined in: packages/core/src/router.ts:284

Registers a wildcard handler that matches any state, with inline middleware.

Type Parameters ​
C ​

C extends string

Parameters ​
state ​

"*"

Must be "*" to match all states

command ​

C

The command name to handle

fns ​

...[...AnyMiddleware[], (ctx) => void | Promise<void>]

Inline middleware followed by the terminal handler

Returns ​

this

state() ​

state<P>(name, setup): this

Defined in: packages/core/src/router.ts:190

Registers handlers for one or more states.

Type Parameters ​
P ​

P extends string | readonly StateNames<TConfig>[]

Parameters ​
name ​

P

A state name or array of state names to register handlers for

setup ​

(state) => void

Callback that receives a state builder to register commands and middleware

Returns ​

this

use() ​

use(arg): this

Defined in: packages/core/src/router.ts:119

Adds global middleware, merges another router, or applies a plugin.

Parameters ​
arg ​

WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps> | GenericPlugin | ((ctx, next) => Promise<void>)

A middleware function, another WorkflowRouter to merge, or a Plugin

Returns ​

this

Interfaces ​

ClientWorkflowDefinition ​

Defined in: packages/core/src/definition.ts:111

A client-safe projection of a workflow definition. State schemas have server-only fields removed. Returned by WorkflowDefinition.forClient.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Properties ​

config ​

readonly config: TConfig

Defined in: packages/core/src/definition.ts:113

The raw Zod schema configuration.

name ​

readonly name: string

Defined in: packages/core/src/definition.ts:114

Methods ​

deserialize() ​

deserialize(snapshot): { ok: true; workflow: ClientWorkflow<TConfig>; } | { error: ValidationError; ok: false; }

Defined in: packages/core/src/definition.ts:117

Parameters ​
snapshot ​

WorkflowSnapshot<TConfig>

Returns ​

{ ok: true; workflow: ClientWorkflow<TConfig>; } | { error: ValidationError; ok: false; }

getStateSchema() ​

getStateSchema(stateName): ZodType

Defined in: packages/core/src/definition.ts:115

Parameters ​
stateName ​

string

Returns ​

ZodType

hasState() ​

hasState(stateName): boolean

Defined in: packages/core/src/definition.ts:116

Parameters ​
stateName ​

string

Returns ​

boolean

ClientWorkflowOf ​

Defined in: packages/core/src/types.ts:65

Client-side workflow narrowed to a specific known state.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

S ​

S extends StateNames<TConfig>

Properties ​

createdAt ​

readonly createdAt: Date

Defined in: packages/core/src/types.ts:70

data ​

readonly data: { [K in string | number | symbol]: TConfig["_clientResolved"]["states"][S][K] }

Defined in: packages/core/src/types.ts:69

definitionName ​

readonly definitionName: string

Defined in: packages/core/src/types.ts:67

id ​

readonly id: string

Defined in: packages/core/src/types.ts:66

state ​

readonly state: S

Defined in: packages/core/src/types.ts:68

updatedAt ​

readonly updatedAt: Date

Defined in: packages/core/src/types.ts:71

Context ​

Defined in: packages/core/src/context.ts:20

Mutable context flowing through the middleware pipeline during dispatch.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

TState ​

TState extends StateNames<TConfig> = StateNames<TConfig>

TCommand ​

TCommand extends CommandNames<TConfig> = CommandNames<TConfig>

Properties ​

command ​

readonly command: object

Defined in: packages/core/src/context.ts:27

The command being dispatched, with type and validated payload.

payload ​

readonly payload: { [K in string | number | symbol]: TConfig["_resolved"]["commands"][TCommand][K] }

type ​

readonly type: TCommand

data ​

readonly data: { [K in string | number | symbol]: TConfig["_resolved"]["states"][TState][K] }

Defined in: packages/core/src/context.ts:37

Current state data (reflects mutations from update).

deps ​

readonly deps: TDeps

Defined in: packages/core/src/context.ts:34

Dependencies injected via the router constructor.

events ​

readonly events: readonly object[]

Defined in: packages/core/src/context.ts:60

Accumulated events emitted during this dispatch.

workflow ​

readonly workflow: WorkflowOf<TConfig, TState>

Defined in: packages/core/src/context.ts:32

The original workflow before any mutations.

Methods ​

emit() ​

emit<E>(event): void

Defined in: packages/core/src/context.ts:58

Emits a domain event. Validates event data against the event's Zod schema.

Type Parameters ​
E ​

E extends string

Parameters ​
event ​

Event with type and data

data ​

{ [K in string | number | symbol]: TConfig["_resolved"]["events"][E][K] }

type ​

E

Returns ​

void

error() ​

error<C>(err): never

Defined in: packages/core/src/context.ts:66

Signals a domain error. Validates error data and throws internally (caught by the router).

Type Parameters ​
C ​

C extends string

Parameters ​
err ​

Error with code and data

code ​

C

data ​

{ [K in string | number | symbol]: TConfig["_resolved"]["errors"][C][K] }

Returns ​

never

get() ​

get<T>(key): T

Defined in: packages/core/src/context.ts:78

Retrieves a value from context-scoped middleware state. Throws if not set.

Type Parameters ​
T ​

T

Parameters ​
key ​

ContextKey<T>

A ContextKey created via createKey

Returns ​

T

getOrNull() ​

getOrNull<T>(key): T | undefined

Defined in: packages/core/src/context.ts:83

Retrieves a value from context-scoped middleware state, or undefined if not set.

Type Parameters ​
T ​

T

Parameters ​
key ​

ContextKey<T>

A ContextKey created via createKey

Returns ​

T | undefined

getWorkflowSnapshot() ​

getWorkflowSnapshot(): Workflow<TConfig>

Defined in: packages/core/src/context.ts:86

Internal

— not part of the handler API

Returns ​

Workflow<TConfig>

set() ​

set<T>(key, value): void

Defined in: packages/core/src/context.ts:73

Stores a value in context-scoped middleware state.

Type Parameters ​
T ​

T

Parameters ​
key ​

ContextKey<T>

A ContextKey created via createKey

value ​

T

The value to store

Returns ​

void

transition() ​

transition<Target>(target, data): void

Defined in: packages/core/src/context.ts:49

Transitions the workflow to a new state with new data. Validates against the target state's Zod schema.

Type Parameters ​
Target ​

Target extends string

Parameters ​
target ​

Target

Target state name

data ​

{ [K in string | number | symbol]: TConfig["_resolved"]["states"][Target][K] }

Data for the target state

Returns ​

void

update() ​

update(data): void

Defined in: packages/core/src/context.ts:42

Merges partial data into the current state. Validates against the state's Zod schema.

Parameters ​
data ​

Partial<StateData<TConfig, TState>>

Partial state data to merge

Returns ​

void

ContextKey ​

Defined in: packages/core/src/key.ts:2

A phantom-typed key for type-safe middleware state storage via Context.set and Context.get.

Type Parameters ​

T ​

T

Properties ​

_phantom ​

readonly _phantom: T

Defined in: packages/core/src/key.ts:4

Internal

Phantom type brand — not used at runtime.

id ​

readonly id: symbol

Defined in: packages/core/src/key.ts:6

Internal symbol providing uniqueness.

MigrateOptions ​

Defined in: packages/core/src/migration.ts:33

Options for migrate.

Properties ​

onError? ​

optional onError?: (error) => void

Defined in: packages/core/src/migration.ts:51

Called when a migration step fails.

Parameters ​
error ​

MigrationError

The MigrationError describing the failure

Returns ​

void

onStep? ​

optional onStep?: (fromVersion, toVersion, snapshot, description?) => void

Defined in: packages/core/src/migration.ts:41

Called after each successful migration step.

Parameters ​
fromVersion ​

number

The version before this step

toVersion ​

number

The version after this step

snapshot ​

WorkflowSnapshot

The snapshot after this step

description? ​

string

Optional description from the migration entry

Returns ​

void

MigrationPipeline ​

Defined in: packages/core/src/migration.ts:18

A validated migration pipeline ready to transform snapshots.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Properties ​

definition ​

readonly definition: WorkflowDefinition<TConfig>

Defined in: packages/core/src/migration.ts:20

The workflow definition this pipeline belongs to.

migrations ​

readonly migrations: ReadonlyMap<number, NormalizedMigration>

Defined in: packages/core/src/migration.ts:24

Map of version number to normalized migration step.

targetVersion ​

readonly targetVersion: number

Defined in: packages/core/src/migration.ts:22

The target schema version to migrate snapshots to.

RouterOptions ​

Defined in: packages/core/src/router.ts:34

Options for the WorkflowRouter constructor.

Properties ​

onHookError? ​

optional onHookError?: (error) => void

Defined in: packages/core/src/router.ts:36

Callback invoked when a lifecycle hook throws. Defaults to console.error.

Parameters ​
error ​

unknown

Returns ​

void

wrapDeps? ​

optional wrapDeps?: boolean

Defined in: packages/core/src/router.ts:38

Wrap deps in a Proxy to catch dependency errors. Defaults to true.

WorkflowConfig ​

Defined in: packages/core/src/types.ts:29

Workflow configuration with pre-resolved types for IDE completion.

Extends WorkflowConfigInput with a _resolved phantom type that caches z.infer results. This exists because Zod v4's z.infer uses conditional types that TypeScript defers in deep generic chains, breaking IDE autocomplete. The _resolved property is never set at runtime — it is populated at the type level by defineWorkflow's return type.

Extends ​

  • WorkflowConfigInput

Properties ​

_clientResolved ​

_clientResolved: object

Defined in: packages/core/src/types.ts:36

states ​

states: Record<string, unknown>

_resolved ​

_resolved: object

Defined in: packages/core/src/types.ts:30

commands ​

commands: Record<string, unknown>

errors ​

errors: Record<string, unknown>

events ​

events: Record<string, unknown>

states ​

states: Record<string, unknown>

commands ​

commands: Record<string, ZodType>

Defined in: packages/core/src/types.ts:13

Record of command names to Zod schemas defining their payload shape.

Inherited from ​

WorkflowConfigInput.commands

errors ​

errors: Record<string, ZodType>

Defined in: packages/core/src/types.ts:17

Record of error codes to Zod schemas defining their data shape.

Inherited from ​

WorkflowConfigInput.errors

events ​

events: Record<string, ZodType>

Defined in: packages/core/src/types.ts:15

Record of event names to Zod schemas defining their data shape.

Inherited from ​

WorkflowConfigInput.events

modelVersion? ​

optional modelVersion?: number

Defined in: packages/core/src/types.ts:9

Optional version number for schema migrations. Defaults to 1.

Inherited from ​

WorkflowConfigInput.modelVersion

states ​

states: Record<string, ZodType>

Defined in: packages/core/src/types.ts:11

Record of state names to Zod schemas defining their data shape.

Inherited from ​

WorkflowConfigInput.states

WorkflowDefinition ​

Defined in: packages/core/src/definition.ts:19

The result of defineWorkflow — holds schemas and creates workflow instances.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Properties ​

config ​

readonly config: TConfig

Defined in: packages/core/src/definition.ts:21

The raw Zod schema configuration.

name ​

readonly name: string

Defined in: packages/core/src/definition.ts:23

The workflow definition name.

Methods ​

createWorkflow() ​

createWorkflow<S>(id, config): WorkflowOf<TConfig, S>

Defined in: packages/core/src/definition.ts:31

Creates a new workflow instance in a given initial state.

Type Parameters ​
S ​

S extends string

Parameters ​
id ​

string

Unique identifier for this workflow instance

config ​

Object containing initialState and the corresponding data

data ​

{ [K in string | number | symbol]: TConfig["_resolved"]["states"][S][K] }

initialState ​

S

Returns ​

WorkflowOf<TConfig, S>

A WorkflowOf narrowed to the initial state

deserialize() ​

deserialize(snapshot): { ok: true; workflow: Workflow<TConfig>; } | { error: ValidationError; ok: false; }

Defined in: packages/core/src/definition.ts:90

Deserializes a workflow instance from a plain snapshot, validating the state data.

Parameters ​
snapshot ​

WorkflowSnapshot<TConfig>

The snapshot to deserialize from

Returns ​

{ ok: true; workflow: Workflow<TConfig>; } | { error: ValidationError; ok: false; }

A result object: { ok: true, workflow } or { ok: false, error }

forClient() ​

forClient(): ClientWorkflowDefinition<TConfig>

Defined in: packages/core/src/definition.ts:104

Returns a client-safe projection of this definition. Memoized — returns the same instance on repeated calls.

Returns ​

ClientWorkflowDefinition<TConfig>

getCommandSchema() ​

getCommandSchema(commandName): ZodType

Defined in: packages/core/src/definition.ts:48

Returns the Zod schema for a given command name.

Parameters ​
commandName ​

string

The command name to look up

Returns ​

ZodType

Throws ​

If the command name is not found in the config

getErrorSchema() ​

getErrorSchema(errorCode): ZodType

Defined in: packages/core/src/definition.ts:62

Returns the Zod schema for a given error code.

Parameters ​
errorCode ​

string

The error code to look up

Returns ​

ZodType

Throws ​

If the error code is not found in the config

getEventSchema() ​

getEventSchema(eventName): ZodType

Defined in: packages/core/src/definition.ts:55

Returns the Zod schema for a given event name.

Parameters ​
eventName ​

string

The event name to look up

Returns ​

ZodType

Throws ​

If the event name is not found in the config

getStateSchema() ​

getStateSchema(stateName): ZodType

Defined in: packages/core/src/definition.ts:41

Returns the Zod schema for a given state name.

Parameters ​
stateName ​

string

The state name to look up

Returns ​

ZodType

Throws ​

If the state name is not found in the config

hasCommand() ​

hasCommand(commandName): boolean

Defined in: packages/core/src/definition.ts:72

Returns true if the given command name exists in the config.

Parameters ​
commandName ​

string

Returns ​

boolean

hasEvent() ​

hasEvent(eventName): boolean

Defined in: packages/core/src/definition.ts:76

Returns true if the given event name exists in the config.

Parameters ​
eventName ​

string

Returns ​

boolean

hasState() ​

hasState(stateName): boolean

Defined in: packages/core/src/definition.ts:68

Returns true if the given state name exists in the config.

Parameters ​
stateName ​

string

The state name to check

Returns ​

boolean

serialize() ​

serialize(workflow): WorkflowSnapshot<TConfig>

Defined in: packages/core/src/definition.ts:83

Serializes a workflow instance into a plain, JSON-safe snapshot.

Parameters ​
workflow ​

Workflow<TConfig>

The workflow instance to serialize

Returns ​

WorkflowSnapshot<TConfig>

A WorkflowSnapshot representing the current state

serializeForClient() ​

serializeForClient(workflow): WorkflowSnapshot<TConfig>

Defined in: packages/core/src/definition.ts:99

Serializes a workflow into a client-safe snapshot with server-only fields stripped.

Parameters ​
workflow ​

Workflow<TConfig>

The workflow instance to serialize

Returns ​

WorkflowSnapshot<TConfig>

A WorkflowSnapshot with server-only fields removed from data

WorkflowOf ​

Defined in: packages/core/src/types.ts:95

Workflow narrowed to a specific known state.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

S ​

S extends StateNames<TConfig>

Properties ​

createdAt ​

readonly createdAt: Date

Defined in: packages/core/src/types.ts:105

Timestamp of workflow creation.

data ​

readonly data: { [K in string | number | symbol]: TConfig["_resolved"]["states"][S][K] }

Defined in: packages/core/src/types.ts:103

State data, typed according to the state's Zod schema.

definitionName ​

readonly definitionName: string

Defined in: packages/core/src/types.ts:99

Name of the workflow definition this instance belongs to.

id ​

readonly id: string

Defined in: packages/core/src/types.ts:97

Unique workflow instance identifier.

state ​

readonly state: S

Defined in: packages/core/src/types.ts:101

Current state name.

updatedAt ​

readonly updatedAt: Date

Defined in: packages/core/src/types.ts:107

Timestamp of last state change.

WorkflowSnapshot ​

Defined in: packages/core/src/snapshot.ts:4

A plain, JSON-safe representation of a workflow's state for serialization and storage.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Properties ​

createdAt ​

readonly createdAt: string

Defined in: packages/core/src/snapshot.ts:14

ISO 8601 timestamp of workflow creation.

data ​

readonly data: unknown

Defined in: packages/core/src/snapshot.ts:12

State data (untyped — validated on WorkflowDefinition.deserialize).

definitionName ​

readonly definitionName: string

Defined in: packages/core/src/snapshot.ts:8

Name of the workflow definition.

id ​

readonly id: string

Defined in: packages/core/src/snapshot.ts:6

Unique workflow instance identifier.

modelVersion ​

readonly modelVersion: number

Defined in: packages/core/src/snapshot.ts:18

Schema version number for migration support.

state ​

readonly state: StateNames<TConfig>

Defined in: packages/core/src/snapshot.ts:10

Current state name.

updatedAt ​

readonly updatedAt: string

Defined in: packages/core/src/snapshot.ts:16

ISO 8601 timestamp of last state change.

version ​

readonly version: number

Defined in: packages/core/src/snapshot.ts:20

Optimistic concurrency version. Starts at 1, increments on each successful save.

Type Aliases ​

ClientStateData ​

ClientStateData<T, S> = Prettify<T["_clientResolved"]["states"][S]>

Defined in: packages/core/src/types.ts:60

Resolves the client-safe data type for a given state (server fields stripped).

Type Parameters ​

T ​

T extends WorkflowConfig

S ​

S extends StateNames<T>

ClientWorkflow ​

ClientWorkflow<TConfig> = { [S in StateNames<TConfig>]: ClientWorkflowOf<TConfig, S> }[StateNames<TConfig>]

Defined in: packages/core/src/types.ts:75

Discriminated union of all possible client-side workflow states.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Command ​

Command<T> = { [C in CommandNames<T>]: { payload: CommandPayload<T, C>; type: C } }[CommandNames<T>]

Defined in: packages/core/src/types.ts:50

Discriminated union of all commands with typed payloads — narrows payload when checking type.

Type Parameters ​

T ​

T extends WorkflowConfig

CommandNames ​

CommandNames<T> = keyof T["commands"] & string

Defined in: packages/core/src/types.ts:42

Type Parameters ​

T ​

T extends WorkflowConfig

CommandPayload ​

CommandPayload<T, C> = Prettify<T["_resolved"]["commands"][C]>

Defined in: packages/core/src/types.ts:80

Resolves the payload type for a given command from pre-computed types.

Type Parameters ​

T ​

T extends WorkflowConfig

C ​

C extends CommandNames<T>

ConfigOf ​

ConfigOf<R> = R extends object ? C : never

Defined in: packages/core/src/types.ts:199

Extracts the WorkflowConfig type from a WorkflowRouter instance.

Type Parameters ​

R ​

R

DispatchResult ​

DispatchResult<TConfig> = { events: object[]; ok: true; workflow: Workflow<TConfig>; } | { error: PipelineError<TConfig>; ok: false; }

Defined in: packages/core/src/types.ts:146

Return type of WorkflowRouter.dispatch. Discriminated union on ok.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

ErrorCodes ​

ErrorCodes<T> = keyof T["errors"] & string

Defined in: packages/core/src/types.ts:44

Type Parameters ​

T ​

T extends WorkflowConfig

ErrorData ​

ErrorData<T, C> = Prettify<T["_resolved"]["errors"][C]>

Defined in: packages/core/src/types.ts:90

Resolves the data type for a given error code from pre-computed types.

Type Parameters ​

T ​

T extends WorkflowConfig

C ​

C extends ErrorCodes<T>

EventData ​

EventData<T, E> = Prettify<T["_resolved"]["events"][E]>

Defined in: packages/core/src/types.ts:85

Resolves the data type for a given event from pre-computed types.

Type Parameters ​

T ​

T extends WorkflowConfig

E ​

E extends EventNames<T>

EventNames ​

EventNames<T> = keyof T["events"] & string

Defined in: packages/core/src/types.ts:43

Type Parameters ​

T ​

T extends WorkflowConfig

GenericPlugin ​

GenericPlugin = Plugin<any, any>

Defined in: packages/core/src/plugin.ts:33

A plugin that works with any router, regardless of config or deps.

Handler ​

Handler<TConfig, TDeps, TState, TCommand> = (ctx) => void | Promise<void>

Defined in: packages/core/src/handler.ts:5

Terminal handler function — receives fully typed context with state and command narrowing.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

TState ​

TState extends StateNames<TConfig>

TCommand ​

TCommand extends CommandNames<TConfig>

Parameters ​

ctx ​

Context<TConfig, TDeps, TState, TCommand>

Returns ​

void | Promise<void>

HookEvent ​

HookEvent = "dispatch:start" | "dispatch:end" | "pipeline:start" | "pipeline:end" | "transition" | "error" | "event"

Defined in: packages/core/src/hooks.ts:2

The lifecycle hook event names.

Middleware ​

Middleware<TConfig, TDeps, TState, TCommand> = (ctx, next) => Promise<void>

Defined in: packages/core/src/middleware.ts:11

Koa-style middleware function with full context narrowing via defaults.

  • Global middleware: Middleware<TConfig, TDeps> — union of all states/commands
  • State-scoped: Middleware<TConfig, TDeps, "draft"> — narrowed to state
  • Inline: Middleware<TConfig, TDeps, "draft", "publish"> — fully narrowed

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

TState ​

TState extends StateNames<TConfig> = StateNames<TConfig>

TCommand ​

TCommand extends CommandNames<TConfig> = CommandNames<TConfig>

Parameters ​

ctx ​

Context<TConfig, TDeps, TState, TCommand>

next ​

() => Promise<void>

Returns ​

Promise<void>

MigrateResult ​

MigrateResult = { ok: true; snapshot: WorkflowSnapshot; } | { error: MigrationError; ok: false; }

Defined in: packages/core/src/migration.ts:28

Result of migrate.

MigrationEntry ​

MigrationEntry = MigrationFn | { description: string; up: MigrationFn; }

Defined in: packages/core/src/migration.ts:9

A migration entry — either a bare MigrationFn or an object with a description.

MigrationFn ​

MigrationFn = (snapshot) => WorkflowSnapshot

Defined in: packages/core/src/migration.ts:6

A function that transforms a snapshot's data from one version to the next.

Parameters ​

snapshot ​

WorkflowSnapshot

Returns ​

WorkflowSnapshot

PipelineError ​

PipelineError<TConfig> = { category: "validation"; issues: z.core.$ZodIssue[]; message: string; source: "command" | "state" | "event" | "transition" | "restore"; } | { category: "domain"; code: ErrorCodes<TConfig>; data: ErrorData<TConfig, ErrorCodes<TConfig>>; } | { category: "router"; code: "NO_HANDLER" | "UNKNOWN_STATE"; message: string; } | { category: "unexpected"; error: unknown; message: string; } | { category: "dependency"; error: unknown; message: string; name: string; }

Defined in: packages/core/src/types.ts:116

Discriminated union of all pipeline error types on category.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Plugin ​

Plugin<TConfig, TDeps> = (router) => void & object

Defined in: packages/core/src/plugin.ts:7

A branded plugin function that can be passed to WorkflowRouter.use.

Type Declaration ​

[PLUGIN_SYMBOL] ​

readonly [PLUGIN_SYMBOL]: true

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

ReadonlyContext ​

ReadonlyContext<TConfig, TDeps, TState, TCommand> = Omit<Context<TConfig, TDeps, TState, TCommand>, "update" | "transition" | "emit" | "error" | "getWorkflowSnapshot">

Defined in: packages/core/src/readonly-context.ts:8

Read-only subset of Context for hook callbacks. Includes context-key access (set/get) but excludes dispatch mutation methods.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

TState ​

TState extends StateNames<TConfig> = StateNames<TConfig>

TCommand ​

TCommand extends CommandNames<TConfig> = CommandNames<TConfig>

Server ​

Server<T> = T & object

Defined in: packages/core/src/server.ts:7

Brands a Zod schema type as server-only at the TypeScript level.

Type Declaration ​

[SERVER_BRAND] ​

readonly [SERVER_BRAND]: true

Type Parameters ​

T ​

T extends ZodType

StateData ​

StateData<T, S> = Prettify<T["_resolved"]["states"][S]>

Defined in: packages/core/src/types.ts:55

Resolves the data type for a given state from pre-computed types.

Type Parameters ​

T ​

T extends WorkflowConfig

S ​

S extends StateNames<T>

StateNames ​

StateNames<T> = keyof T["states"] & string

Defined in: packages/core/src/types.ts:41

Type Parameters ​

T ​

T extends WorkflowConfig

Workflow ​

Workflow<TConfig> = { [S in StateNames<TConfig>]: WorkflowOf<TConfig, S> }[StateNames<TConfig>]

Defined in: packages/core/src/types.ts:111

Discriminated union of all possible workflow states — checking .state narrows .data.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig = WorkflowConfig

Functions ​

createKey() ​

createKey<T>(name): ContextKey<T>

Defined in: packages/core/src/key.ts:15

Creates a unique typed key for storing and retrieving values in context.

Type Parameters ​

T ​

T

Parameters ​

name ​

string

Debug label (uniqueness comes from an internal Symbol)

Returns ​

ContextKey<T>

A ContextKey for use with ctx.set(), ctx.get(), and ctx.getOrNull()

defineGenericPlugin() ​

defineGenericPlugin(fn): GenericPlugin

Defined in: packages/core/src/plugin.ts:43

Creates a plugin that works with any router without requiring explicit type parameters. Use this for cross-cutting concerns (logging, tracing, delay) that don't reference specific states, commands, or events.

Parameters ​

fn ​

(router) => void

A function that configures a router (adds hooks, middleware)

Returns ​

GenericPlugin

A branded GenericPlugin function

defineMigrations() ​

defineMigrations<TConfig>(definition, migrationMap): MigrationPipeline<TConfig>

Defined in: packages/core/src/migration.ts:82

Creates a validated migration pipeline from a definition and version-keyed transform functions. Each key is the target version — the function transforms from (key - 1) to key.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

Parameters ​

definition ​

WorkflowDefinition<TConfig>

The workflow definition the migrations belong to

migrationMap ​

Record<number, MigrationEntry>

A record mapping target version numbers to MigrationEntry values

Returns ​

MigrationPipeline<TConfig>

A validated MigrationPipeline ready for use with migrate

Throws ​

If migration keys are not sequential from 2 to the definition's modelVersion, or if the highest key does not match modelVersion

definePlugin() ​

definePlugin<TConfig, TDeps>(fn): Plugin<TConfig, TDeps>

Defined in: packages/core/src/plugin.ts:17

Brands a function as a Ryte plugin for use with WorkflowRouter.use.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

TDeps ​

TDeps

Parameters ​

fn ​

(router) => void

A function that configures a router (adds handlers, middleware, hooks)

Returns ​

Plugin<TConfig, TDeps>

A branded Plugin function

defineWorkflow() ​

defineWorkflow<TConfig>(name, config): WorkflowDefinition<TConfig & object>

Defined in: packages/core/src/definition.ts:133

Creates a workflow definition from a name and Zod schema configuration.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfigInput

Parameters ​

name ​

string

Unique name for this workflow type

config ​

TConfig

Object with states, commands, events, errors — each a record of Zod schemas

Returns ​

WorkflowDefinition<TConfig & object>

A WorkflowDefinition with methods for creating instances and accessing schemas

isPlugin() ​

isPlugin(value): value is Plugin<WorkflowConfig, unknown>

Defined in: packages/core/src/plugin.ts:56

Checks whether a value is a branded Ryte plugin.

Parameters ​

value ​

unknown

The value to check

Returns ​

value is Plugin<WorkflowConfig, unknown>

true if the value is a Plugin

isServerField() ​

isServerField(schema): boolean

Defined in: packages/core/src/server.ts:24

Returns true if the schema was wrapped with server().

Parameters ​

schema ​

ZodType

Returns ​

boolean

migrate() ​

migrate<TConfig>(pipeline, snapshot, options?): MigrateResult

Defined in: packages/core/src/migration.ts:135

Runs the migration chain from the snapshot's modelVersion to the pipeline's targetVersion. Returns a Result. Auto-stamps modelVersion after each step.

Type Parameters ​

TConfig ​

TConfig extends WorkflowConfig

Parameters ​

pipeline ​

MigrationPipeline<TConfig>

The MigrationPipeline created by defineMigrations

snapshot ​

WorkflowSnapshot

The workflow snapshot to migrate

options? ​

MigrateOptions

Optional callbacks for step progress and error reporting

Returns ​

MigrateResult

A MigrateResult with the migrated snapshot on success, or a MigrationError on failure

server() ​

server<T>(schema): Server<T>

Defined in: packages/core/src/server.ts:16

Marks a Zod schema as server-only. Fields wrapped in server() are stripped from client snapshots and excluded from client TypeScript types.

Returns a new schema reference — the original is not mutated, so shared schemas can safely be used in both server and non-server positions.

Type Parameters ​

T ​

T extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

Parameters ​

schema ​

T

Returns ​

Server<T>