Defined in: packages/core/src/Machine.ts:407

Named Effect schedule for retrying an invocation while its node remains active.

When to use

Use for operational retries whose attempts do not need to become machine states. Model retries explicitly when their progress affects application behavior or accepted events.

Type Parameters

Policy

Policy extends Schedule.Schedule<unknown, Failure, unknown, unknown>

Properties

name

readonly name: string

Defined in: packages/core/src/Machine.ts:411

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:412

schedule

readonly schedule: Policy

Defined in: packages/core/src/Machine.ts:413

constructors

taggedUnion()

taggedUnion<Cases>(cases): TaggedUnion<Cases>

Defined in: packages/core/src/Machine.ts:81

Builds an Effect tagged union whose individual cases retain graphable metadata.

When to use

Use when state or event titles and descriptions should be available to graph and Studio tooling. A regular Schema.Union of tagged structs is also accepted by builder.

Type Parameters

Cases

Cases extends Readonly<Record<string, TaggedUnionCase<Fields>>>

builder()

builder<InputSchema, StateSchemaSource, EventSchemaSource>(schemaSources): object

Defined in: packages/core/src/Machine.ts:2035

Creates a schema-bound API for authoring a typed machine definition.

Details

The returned state, invoke, regions, child, and final constructors share the input, state, and event vocabulary. define accepts one exhaustive record keyed by state tag and validates targets, branch ordering, stable names, region topology, and declared work without executing authored callbacks.

Gotchas

Invalid topology throws MachineDefinitionDefect synchronously from define.

Example (Defining a counter)

import * as Schema from "effect/Schema"
import * as Machine from "effect-state-machine/Machine"

const State = Machine.taggedUnion({
  Active: { fields: { count: Schema.Number } },
})
const Event = Machine.taggedUnion({
  Increment: { fields: { amount: Schema.Number } },
})
const counter = Machine.builder({ input: Schema.Number, state: State, event: Event })

const definition = counter.define(
  {
    id: "counter",
    idempotencyKey: (count) => String(count),
    initial: (count) => ({ _tag: "Active", count }),
  },
  {
    Active: counter.state({
      Increment: {
        target: "Active",
        reduce: ({ state, event }) => ({ count: state.count + event.amount }),
      },
    }),
  },
)

Type Parameters

InputSchema

InputSchema extends Top

StateSchemaSource

StateSchemaSource extends TaggedSchemaSource

EventSchemaSource

EventSchemaSource extends TaggedSchemaSource

Parameters

schemaSources

Readonly<{ input: InputSchema; state: StateSchemaSource; event: EventSchemaSource; }>

Returns

child

child: <Current, Child>(config, on?) => ChildNodeConfig<State, Event, Current, Child>

Type Parameters

Current

Current extends string

Child

Child extends ChildDefinition

Parameters

config

Readonly<{ name: ...; description?: ...; definition: ...; input: ...; forward?: ...; onComplete: ...; }>

on?

Readonly<...>

Returns

ChildNodeConfig<State, Event, Current, Child>

define

define: <States>(config, states) => MachineDefinition<InputSchema, NormalizedTaggedSchema<...>, NormalizedTaggedSchema<...>, States>

Type Parameters

States

States extends Readonly<{ [Current in (...)]: (...) }>

Parameters

config

Readonly<{ id: ...; description?: ...; idempotencyKey: ...; version?: ...; migrations?: ...; initial: ...; }>

states

States

Returns

MachineDefinition<InputSchema, NormalizedTaggedSchema<...>, NormalizedTaggedSchema<...>, States>

final

final: (options?) => FinalNodeConfig

Parameters

options?

Readonly<...>

Returns

FinalNodeConfig

guard

guard: <Args>(config) => NamedGuard<Args> = namedGuard

Names synchronous decision logic and captures its declaration callsite for development tooling.

When to use

Use for a guarded transition whose decision should remain identifiable in graphs and inspection output. Guards must be deterministic and may not require Effect services.

Type Parameters

Args

Args

Parameters

config

Readonly<{ name: ...; description?: ...; guard: ...; }>

Returns

NamedGuard<Args>

Since

0.1.0

invoke

invoke: <Current, Success, AllowedFailure, Failure, Requirements, RetryError, RetryEnv>(config, on?, options?) => ... & ... & object

Type Declaration

all

all: <Current, Tasks>(config, on?, options?) => ... = invokeAll

Type Parameters

Current

Current extends ...

Tasks

Tasks extends ...

Parameters

config

...

on?

...

options?

...

Returns

...

race

race: <Current, Tasks>(config, on?, options?) => ... = invokeRace

Type Parameters

Current

Current extends ...

Tasks

Tasks extends ...

Parameters

config

...

on?

...

options?

...

Returns

...

region

region: object

region.invoke

invoke: <Current, Slot, RegionTag, Success, AllowedFailure, Failure, Requirements, RetryError, RetryEnv>(config, on?, options?) => Readonly<...> = invokeRegion

Type Parameters

Current

Current extends string

Slot

Slot extends Tagged

RegionTag

RegionTag extends string

Success

Success extends WorkSchema

AllowedFailure

AllowedFailure extends WorkSchema

Failure

Failure extends unknown

Requirements

Requirements

RetryError

RetryError extends unknown = never

RetryEnv

RetryEnv = never

Parameters

config

Readonly<...>

on?

... | ...

options?

... | ...

Returns

Readonly<...>

regions

regions: <Current, RegionTrees>(regionTrees, on?, options?) => Readonly<...> & Readonly<...>

Type Parameters

Current

Current extends string

RegionTrees

RegionTrees extends Readonly<{ [RegionKey in (...)]?: (...) }>

Parameters

regionTrees

RegionTrees

on?

Readonly<...>

options?

Readonly<...>

Returns

Readonly<...> & Readonly<...>

state

state: <Current>(on, options?) => AtomicNodeConfig<State, Event, Current>

Type Parameters

Current

Current extends string

Parameters

on

EventHandlers<State, Event, Current>

options?

Readonly<...>

Returns

AtomicNodeConfig<State, Event, Current>

schemas

schemas: Readonly<{ input: InputSchema; state: NormalizedTaggedSchema; event: NormalizedTaggedSchema; }>

Since

0.1.0

converting

workSchemaMetadata()

workSchemaMetadata(schema): WorkSchemaMetadata | undefined

Defined in: packages/core/src/Machine.ts:1207

Projects safe tooling metadata from an Effect Schema value.

When to use

Use when rendering or inspecting invoked-work definitions without retaining executable Schema objects. Non-Schema inputs return undefined.

Details

The projection includes the AST kind and resolved string-valued identifier, title, and description annotations. It does not expose transformations, refinements, or executable hooks.

Parameters

schema

unknown

Returns

WorkSchemaMetadata | undefined

See

WorkSchemaMetadata for the projected shape.

Since

0.2.0

definitionNodes()

definitionNodes(definition): readonly DefinitionNode[]

Defined in: packages/core/src/Machine.ts:1399

Returns the homogeneous tooling view of a definition's canonical keyed states.

This is the single deliberate type-erasure boundary shared by the interpreter and tooling. Authoring and public utility types continue to use the exact keyed states record.

Parameters

definition

DefinitionMetadata

Returns

readonly DefinitionNode[]

Since

0.2.0

decoding

decodeInput()

decodeInput<InputSchema>(definition, input): Effect<InputSchema["Type"], SchemaError, InputSchema["DecodingServices"]>

Defined in: packages/core/src/Machine.ts:1927

Decodes unknown input with a machine definition's input Schema.

Type Parameters

InputSchema

InputSchema extends Top

Parameters

definition

DefinitionWithSchema<"input", InputSchema>

input

unknown

Returns

Effect<InputSchema["Type"], SchemaError, InputSchema["DecodingServices"]>

Since

0.1.0

decodeState()

decodeState<StateSchema>(definition, input): Effect<StateSchema["Type"], SchemaError, StateSchema["DecodingServices"]>

Defined in: packages/core/src/Machine.ts:1949

Decodes unknown state with a machine definition's state Schema.

Type Parameters

StateSchema

StateSchema extends Top

Parameters

definition

DefinitionWithSchema<"state", StateSchema>

input

unknown

Returns

Effect<StateSchema["Type"], SchemaError, StateSchema["DecodingServices"]>

Since

0.1.0

decodeEvent()

decodeEvent<EventSchema>(definition, input): Effect<EventSchema["Type"], SchemaError, EventSchema["DecodingServices"]>

Defined in: packages/core/src/Machine.ts:1971

Decodes an unknown event with a machine definition's event Schema.

Type Parameters

EventSchema

EventSchema extends Top

Parameters

definition

DefinitionWithSchema<"event", EventSchema>

input

unknown

Returns

Effect<EventSchema["Type"], SchemaError, EventSchema["DecodingServices"]>

Since

0.1.0

encoding

encodeInput()

encodeInput<InputSchema>(definition, input): Effect<InputSchema["Encoded"], SchemaError, InputSchema["EncodingServices"]>

Defined in: packages/core/src/Machine.ts:1938

Encodes a decoded machine input with the definition's input Schema.

Type Parameters

InputSchema

InputSchema extends Top

Parameters

definition

DefinitionWithSchema<"input", InputSchema>

input

Type<InputSchema>

Returns

Effect<InputSchema["Encoded"], SchemaError, InputSchema["EncodingServices"]>

Since

0.1.0

encodeState()

encodeState<StateSchema>(definition, input): Effect<StateSchema["Encoded"], SchemaError, StateSchema["EncodingServices"]>

Defined in: packages/core/src/Machine.ts:1960

Encodes a decoded machine state with the definition's state Schema.

Type Parameters

StateSchema

StateSchema extends Top

Parameters

definition

DefinitionWithSchema<"state", StateSchema>

input

Type<StateSchema>

Returns

Effect<StateSchema["Encoded"], SchemaError, StateSchema["EncodingServices"]>

Since

0.1.0

encodeEvent()

encodeEvent<EventSchema>(definition, input): Effect<EventSchema["Encoded"], SchemaError, EventSchema["EncodingServices"]>

Defined in: packages/core/src/Machine.ts:1982

Encodes a decoded machine event with the definition's event Schema.

Type Parameters

EventSchema

EventSchema extends Top

Parameters

definition

DefinitionWithSchema<"event", EventSchema>

input

Type<EventSchema>

Returns

Effect<EventSchema["Encoded"], SchemaError, EventSchema["EncodingServices"]>

Since

0.1.0

errors

ActorDispatchError

Defined in: packages/core/src/Machine.ts:1476

Expected failure while routing an event to an actor in a machine tree.

Since

0.2.0

Extends

YieldableError<this> & object & Readonly<{ actorId: ...; reason: ...; }>

Constructors

Constructor

new ActorDispatchError(args): ActorDispatchError

Defined in: node_modules/.pnpm/effect@4.0.0-rc.110/node_modules/effect/dist/Data.d.ts:966

Parameters

args

actorId

ActorId

reason

"unknown" | "ended" | "unaccepted"

Returns

ActorDispatchError

Inherited from

Data.TaggedError("ActorDispatchError")<{ readonly actorId: ActorId readonly reason: "unknown" | "ended" | "unaccepted" }>.constructor

Properties

actorId

readonly actorId: ActorId

Defined in: packages/core/src/Machine.ts:1477

Inherited from

Data.TaggedError("ActorDispatchError").actorId

reason

readonly reason: "unknown" | "ended" | "unaccepted"

Defined in: packages/core/src/Machine.ts:1478

Inherited from

Data.TaggedError("ActorDispatchError").reason

MachineDefinitionDefect

Defined in: packages/core/src/Machine.ts:1700

Defect raised when an authored machine definition violates a structural invariant.

Gotchas

Instances are thrown synchronously by builder().define. Failures discovered only while starting an instance, such as an initializer returning an undeclared state, use the typed execution error channel instead.

Since

0.1.0

Extends

Error

Constructors

Constructor

new MachineDefinitionDefect(message?): MachineDefinitionDefect

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1080

Parameters

message?

string

Returns

MachineDefinitionDefect

Inherited from

Error.constructor

Constructor

new MachineDefinitionDefect(message?, options?): MachineDefinitionDefect

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1080

Parameters

message?

string

options?

ErrorOptions

Returns

MachineDefinitionDefect

Inherited from

Error.constructor

Properties

name

readonly name: "MachineDefinitionDefect" = "MachineDefinitionDefect"

Defined in: packages/core/src/Machine.ts:1701

Overrides

Error.name

ProtocolDefect

Defined in: packages/core/src/Machine.ts:1715

Defect raised when a known machine event is not accepted by the live state.

Gotchas

Sending such an event terminates the machine instance. Call MachineHandle.can first when the sender cannot guarantee that the event is currently accepted.

Since

0.1.0

Extends

Error

Constructors

Constructor

new ProtocolDefect(machineId, stateTag, eventTag): ProtocolDefect

Defined in: packages/core/src/Machine.ts:1718

Parameters

machineId

string

stateTag

string

eventTag

string

Returns

ProtocolDefect

Overrides

Error.constructor

Properties

name

readonly name: "ProtocolDefect" = "ProtocolDefect"

Defined in: packages/core/src/Machine.ts:1716

Overrides

Error.name

machineId

readonly machineId: string

Defined in: packages/core/src/Machine.ts:1719

stateTag

readonly stateTag: string

Defined in: packages/core/src/Machine.ts:1720

eventTag

readonly eventTag: string

Defined in: packages/core/src/Machine.ts:1721

guards

NamedGuard

Defined in: packages/core/src/Machine.ts:1895

Named synchronous decision used by guarded transitions and graph tooling.

Since

0.1.0

Type Parameters

Args

Args

Properties

name

readonly name: string

Defined in: packages/core/src/Machine.ts:1896

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:1897

guard

readonly guard: (args) => boolean

Defined in: packages/core/src/Machine.ts:1898

Parameters

args

Args

Returns

boolean

source

readonly source: Reference

Defined in: packages/core/src/Machine.ts:1899

namedGuard()

namedGuard<Args>(config): NamedGuard<Args>

Defined in: packages/core/src/Machine.ts:1913

Names synchronous decision logic and captures its declaration callsite for development tooling.

When to use

Use for a guarded transition whose decision should remain identifiable in graphs and inspection output. Guards must be deterministic and may not require Effect services.

Type Parameters

Args

Args

Parameters

config

Readonly<{ name: string; description?: string; guard: (args) => boolean; }>

Returns

NamedGuard<Args>

Since

0.1.0

models

TaggedUnionCase

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

Definition of one case accepted by taggedUnion.

Since

0.1.0

Type Parameters

Fields

Fields extends Schema.Struct.Fields = Schema.Struct.Fields

Properties

fields

readonly fields: Fields

Defined in: packages/core/src/Machine.ts:52

title?

readonly optional title?: string

Defined in: packages/core/src/Machine.ts:53

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:54

Transition

Transition<State, Event, Current, EventTag, Target> = Target extends TagOf<State> ? Readonly<{ target: Target; description?: string; reduce: (args) => ...; }> : never

Defined in: packages/core/src/Machine.ts:127

An event transition that derives a target-state value from the current state and event.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Target

Target extends TagOf<State> = TagOf<State>

Since

0.1.0

WhenBranch

WhenBranch<State, Event, Current, EventTag, Target> = Target extends TagOf<State> ? Readonly<{ when: Readonly<...>; target: Target; description?: string; reduce: (args) => ...; }> : never

Defined in: packages/core/src/Machine.ts:150

A named guard branch in a guarded event transition.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Target

Target extends TagOf<State> = TagOf<State>

Since

0.1.0

OtherwiseBranch

OtherwiseBranch<State, Event, Current, EventTag, Target> = Target extends TagOf<State> ? Readonly<{ otherwise: true; target: Target; description?: string; reduce: (args) => ...; }> : never

Defined in: packages/core/src/Machine.ts:179

The final fallback branch in a guarded event transition.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Target

Target extends TagOf<State> = TagOf<State>

Since

0.1.0

GuardedTransition

GuardedTransition<State, Event, Current, EventTag> = Readonly<{ branches: readonly ... | readonly ...; }>

Defined in: packages/core/src/Machine.ts:208

An ordered, first-match-wins collection of guarded event transitions.

Gotchas

A fallback, when present, must be the last branch. If no guard matches and no fallback exists, the running machine terminates with a ProtocolDefect.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Since

0.1.0

IgnoredTransition

Defined in: packages/core/src/Machine.ts:232

An explicit instruction to accept an event without changing state.

Since

0.1.0

Properties

ignore

readonly ignore: Readonly<{ description?: string; }>

Defined in: packages/core/src/Machine.ts:233

StayUpdate

Defined in: packages/core/src/Machine.ts:244

Updates the current state variant without exiting or re-entering its node.

Since

0.2.0

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Properties

stay

readonly stay: (args) => FieldsOf<ByTag<State, Current>>

Defined in: packages/core/src/Machine.ts:250

Parameters

args

TransitionArgs<State, Event, Current, EventTag>

Returns

FieldsOf<ByTag<State, Current>>

EventHandler

EventHandler<State, Event, Current, EventTag> = Transition<State, Event, Current, EventTag> | GuardedTransition<State, Event, Current, EventTag> | IgnoredTransition | StayUpdate<State, Event, Current, EventTag>

Defined in: packages/core/src/Machine.ts:261

Handling policy for one event in one machine state.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

EventTag

EventTag extends TagOf<Event>

Since

0.1.0

EventHandlers

EventHandlers<State, Event, Current> = Readonly<{ [EventTag in TagOf<Event>]?: EventHandler<State, Event, Current, EventTag> }>

Defined in: packages/core/src/Machine.ts:278

State-specific event handlers keyed by event tag.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

Since

0.1.0

SuccessTransition

SuccessTransition<State, Current, Value> = OutcomeHandler<State, Current, Value, "value">

Defined in: packages/core/src/Machine.ts:378

Transition selected from the successful output of invoked work or a child machine.

Type Parameters

State

State extends Tagged

Current

Current extends TagOf<State>

Value

Value

Since

0.1.0

FailureTransition

FailureTransition<State, Current, Error> = OutcomeHandler<State, Current, Error, "error">

Defined in: packages/core/src/Machine.ts:390

Transition selected from an expected failure of invoked work or its retry policy.

Type Parameters

State

State extends Tagged

Current

Current extends TagOf<State>

Error

Error

Since

0.1.0

WorkExecution

Defined in: packages/core/src/Machine.ts:524

Stable execution identity supplied to every invoked-work callback.

When to use

Pass id to an idempotent API, queue, or Workflow integration when work crosses into another durability domain.

Details

The same machine entry and lane keep one execution ID across lease loss and at-least-once redelivery. deliveryAttempt increases for each claim; explicit state re-entry creates a new entry identity and execution ID. The runtime always supplies this argument, including when the engine uses an in-memory store.

Gotchas

The ID makes an external idempotency strategy possible; it does not make an arbitrary side effect exactly once. Callbacks may ignore this argument, but callbacks that reference it never need an undefined branch.

Since

0.2.0

Properties

id

readonly id: ExecutionId

Defined in: packages/core/src/Machine.ts:525

instanceId

readonly instanceId: MachineInstanceId

Defined in: packages/core/src/Machine.ts:526

entryId

readonly entryId: EntryId

Defined in: packages/core/src/Machine.ts:527

ownerPath

readonly ownerPath: string

Defined in: packages/core/src/Machine.ts:528

invocationName

readonly invocationName: string

Defined in: packages/core/src/Machine.ts:529

laneName?

readonly optional laneName?: string

Defined in: packages/core/src/Machine.ts:530

deliveryAttempt

readonly deliveryAttempt: number

Defined in: packages/core/src/Machine.ts:531

ChildDefinition

Defined in: packages/core/src/Machine.ts:684

Minimum public shape required to invoke another machine as a child.

Since

0.1.0

Properties

id

readonly id: string

Defined in: packages/core/src/Machine.ts:685

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:686

schemas

readonly schemas: Readonly<{ input: Schema.Top; state: TaggedSchema; event: TaggedSchema; }>

Defined in: packages/core/src/Machine.ts:687

states

readonly states: Readonly<Record<string, unknown>>

Defined in: packages/core/src/Machine.ts:692

ChildForwarders

ChildForwarders<State, Event, Current, ChildEvent> = Readonly<{ [ParentEventTag in TagOf<Event>]?: ChildForward<State, Event, Current, ParentEventTag, ChildEvent> }>

Defined in: packages/core/src/Machine.ts:719

Parent-event mappings forwarded to a child while its node is active.

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Current

Current extends TagOf<State>

ChildEvent

ChildEvent extends Tagged

Since

0.1.0

MachineDefinition

Defined in: packages/core/src/Machine.ts:1127

Immutable, synchronously inspectable definition of a machine's schemas and behavior.

Details

Definitions expose run for execution and are also shared with codec helpers and graph tooling. Inspecting a definition never executes its initializer, reducers, guards, or Effects.

Since

0.1.0

Type Parameters

InputSchema

InputSchema extends Schema.Top

StateSchema

StateSchema extends TaggedSchema

EventSchema

EventSchema extends TaggedSchema

States

States extends StatesConfig<Schema.Schema.Type<StateSchema>, Schema.Schema.Type<EventSchema>>

Properties

id

readonly id: string

Defined in: packages/core/src/Machine.ts:1133

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:1134

idempotencyKey

readonly idempotencyKey: (input) => string

Defined in: packages/core/src/Machine.ts:1135

Parameters

input

Type<InputSchema>

Returns

string

version

readonly version: string

Defined in: packages/core/src/Machine.ts:1136

migrations

readonly migrations: readonly Migration[]

Defined in: packages/core/src/Machine.ts:1137

schemas

readonly schemas: Readonly<{ input: InputSchema; state: StateSchema; event: EventSchema; }>

Defined in: packages/core/src/Machine.ts:1138

initial

readonly initial: (input) => Type<StateSchema>

Defined in: packages/core/src/Machine.ts:1143

Parameters

input

Type<InputSchema>

Returns

Type<StateSchema>

states

readonly states: States

Defined in: packages/core/src/Machine.ts:1144

instanceId

readonly instanceId: (input) => MachineInstanceId

Defined in: packages/core/src/Machine.ts:1145

Parameters

input

Type<InputSchema>

Returns

MachineInstanceId

run

readonly run: (input) => RunEffect<StateSchema, EventSchema, States>

Defined in: packages/core/src/Machine.ts:1146

Parameters

input

Type<InputSchema>

Returns

RunEffect<StateSchema, EventSchema, States>

open

readonly open: (input) => RunEffect<StateSchema, EventSchema, States>

Defined in: packages/core/src/Machine.ts:1149

Parameters

input

Type<InputSchema>

Returns

RunEffect<StateSchema, EventSchema, States>

DefinitionMetadata

Defined in: packages/core/src/Machine.ts:1165

Type-erased machine definition metadata consumed by development tooling.

When to use

Use when inspecting topology without depending on a definition's application-specific types. Prefer the full MachineDefinition when executing a machine.

Since

0.1.0

Properties

id

readonly id: string

Defined in: packages/core/src/Machine.ts:1166

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:1167

version

readonly version: string

Defined in: packages/core/src/Machine.ts:1168

migrations

readonly migrations: readonly Migration[]

Defined in: packages/core/src/Machine.ts:1169

schemas

readonly schemas: Readonly<{ state: TaggedSchema; event: TaggedSchema; }>

Defined in: packages/core/src/Machine.ts:1170

states

readonly states: Readonly<Record<string, unknown>>

Defined in: packages/core/src/Machine.ts:1174

WorkSchemaMetadata

Defined in: packages/core/src/Machine.ts:1183

Safe, serializable annotations projected from an invoked-work outcome Schema.

Since

0.2.0

Properties

kind

readonly kind: string

Defined in: packages/core/src/Machine.ts:1184

identifier?

readonly optional identifier?: string

Defined in: packages/core/src/Machine.ts:1185

title?

readonly optional title?: string

Defined in: packages/core/src/Machine.ts:1186

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:1187

DefinitionNode

DefinitionNode = Readonly<{ kind: "state"; tag: string; source: Source.Reference; description?: string; after?: AfterTransitionMetadata; on: Readonly<...>; }> | Readonly<{ kind: "final"; tag: string; source: Source.Reference; description?: string; }> | Readonly<{ kind: "invoke"; tag: string; name: string; description?: string; source: Source.Reference; workKind?: ... | ... | ...; tasks?: Readonly<...>; successSchema?: WorkSchemaMetadata; errorSchema?: WorkSchemaMetadata; taskSchemas?: Readonly<...>; concurrency?: ... | ...; after?: AfterTransitionMetadata; retry?: Readonly<...>; on: Readonly<...>; onSuccess: ... | ...; onFailure: ... | ...; }> | Readonly<{ kind: "child"; tag: string; name: string; description?: string; source: Source.Reference; definition: DefinitionMetadata; forward: Readonly<...>; on: Readonly<...>; onComplete: ... | ...; }> | Readonly<{ kind: "regions"; tag: string; source: Source.Reference; description?: string; regions: Readonly<...>; on: Readonly<...>; onComplete?: TransitionMetadata; }>

Defined in: packages/core/src/Machine.ts:1234

Homogeneous tooling view of one definition state, keyed by its authored tag.

Since

0.2.0

MachineHandle

Defined in: packages/core/src/Machine.ts:1511

Effect-native interface to one scoped running machine instance.

Details

snapshot reads the current state, changes includes the initial state and later commits, send waits until the event is processed, and completion waits for a final state or defect. The payload-free inspection stream is safe for general tooling; inspect opts into projecting event details.

Gotchas

The handle is valid only inside the Scope required by definition.run. Releasing that Scope interrupts active work and ends the instance.

Since

0.1.0

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Completion

Completion extends State = never

Error

Error = never

Properties

instanceId

readonly instanceId: MachineInstanceId

Defined in: packages/core/src/Machine.ts:1517

actorId

readonly actorId: ActorId

Defined in: packages/core/src/Machine.ts:1518

definitionPath

readonly definitionPath: DefinitionPath

Defined in: packages/core/src/Machine.ts:1519

tree

readonly tree: MachineTreeHandle

Defined in: packages/core/src/Machine.ts:1520

snapshot

readonly snapshot: Effect<State, Error>

Defined in: packages/core/src/Machine.ts:1521

changes

readonly changes: Stream<State, Error>

Defined in: packages/core/src/Machine.ts:1522

inspection

readonly inspection: Stream<InspectionEvent>

Defined in: packages/core/src/Machine.ts:1523

completion

readonly completion: Effect<Completion, Error>

Defined in: packages/core/src/Machine.ts:1527

send

readonly send: (event, options?) => Effect<void, Error>

Defined in: packages/core/src/Machine.ts:1528

Parameters

event

Event

options?

Readonly<{ idempotencyKey?: ...; }>

Returns

Effect<void, Error>

can

readonly can: (event) => Effect<boolean, Error>

Defined in: packages/core/src/Machine.ts:1532

Parameters

event

Event

Returns

Effect<boolean, Error>

status

readonly status: Effect<"running" | "completed" | "defected", Error>

Defined in: packages/core/src/Machine.ts:1533

Methods

inspect()

inspect<EventDetails>(projectEvent): Stream<ProjectedInspectionEvent<EventDetails>>

Defined in: packages/core/src/Machine.ts:1524

Type Parameters

EventDetails

EventDetails

Parameters

projectEvent

(event) => EventDetails

Returns

Stream<ProjectedInspectionEvent<EventDetails>>

observability

ActorId

ActorId: object

Defined in: packages/core/src/Machine.ts:1411

Type Declaration

make

readonly make: (value) => ActorId

Parameters

value

string

Returns

ActorId

Since

0.2.0

ActorId

ActorId = string & Readonly<{ [ActorIdTypeId]: "ActorId"; }>

Defined in: packages/core/src/Machine.ts:1411

Runtime identity of one machine instance within a root execution tree.

Since

0.2.0

DefinitionPath

DefinitionPath: object

Defined in: packages/core/src/Machine.ts:1424

Constructors for the canonical structural paths shared by runtime actors and development tools.

Gotchas

Child components normalize unpaired UTF-16 surrogates to U+FFFD before encoding. Existing well-formed paths are unchanged; malformed spellings may normalize to the same path.

Type Declaration

root

readonly root: DefinitionPath = rootDefinitionPath

child

readonly child: (parent, ownerStateTag, invocation) => DefinitionPath = childDefinitionPath

Parameters

parent

DefinitionPath

ownerStateTag

string

invocation

string

Returns

DefinitionPath

make

readonly make: (value) => DefinitionPath

Parameters

value

string

Returns

DefinitionPath

Since

0.2.0

DefinitionPath

DefinitionPath = string & Readonly<{ [DefinitionPathTypeId]: "DefinitionPath"; }>

Defined in: packages/core/src/Machine.ts:1424

Static location of a machine definition within its root definition tree.

Since

0.2.0

TreeRecordBody

TreeRecordBody = Readonly<{ _tag: "ActorStarted"; machineId: string; parentActorId?: ActorId; ownerStateTag?: string; invocation?: string; instanceId?: string; }> | Readonly<{ _tag: "Inspection"; metadata: InspectionEvent; event?: Schema.Schema.Type<...>; }> | Readonly<{ _tag: "StateSnapshot"; state: Schema.Schema.Type<...>; }> | Readonly<{ _tag: "ActorTerminated"; status: ... | ... | ...; }>

Defined in: packages/core/src/Machine.ts:1432

Lifecycle and machine facts retained by a root execution tree.

Since

0.2.0

TreeRecord

Defined in: packages/core/src/Machine.ts:1463

One globally ordered fact produced by a machine execution tree.

Since

0.2.0

Properties

sequence

readonly sequence: number

Defined in: packages/core/src/Machine.ts:1464

actorId

readonly actorId: ActorId

Defined in: packages/core/src/Machine.ts:1465

definitionPath

readonly definitionPath: DefinitionPath

Defined in: packages/core/src/Machine.ts:1466

body

readonly body: TreeRecordBody

Defined in: packages/core/src/Machine.ts:1467

MachineTreeHandle

Defined in: packages/core/src/Machine.ts:1487

Type-erased inspection and dispatch surface shared by every actor under a root machine.

Since

0.2.0

Properties

rootActorId

readonly rootActorId: ActorId

Defined in: packages/core/src/Machine.ts:1488

records

readonly records: Stream<TreeRecord>

Defined in: packages/core/src/Machine.ts:1489

dispatch

readonly dispatch: (actorId, event) => Effect<void, ActorDispatchError>

Defined in: packages/core/src/Machine.ts:1490

Parameters

actorId

ActorId

event

unknown

Returns

Effect<void, ActorDispatchError>

ProjectedInspectionEvent

ProjectedInspectionEvent<EventDetails> = Exclude<InspectionEvent, Readonly<{ _tag: ...; }>> | Extract<..., ...> & Readonly<...>

Defined in: packages/core/src/Machine.ts:1542

Inspection event union whose received events include caller-projected details.

Type Parameters

EventDetails

EventDetails

Since

0.1.0

InspectionEvent

InspectionEvent = Readonly<{ _tag: "MachineStarted"; machineId: string; initialStateTag: string; }> | Readonly<{ _tag: "EventReceived"; machineId: string; stateTag: string; eventTag: string; }> | Readonly<{ _tag: "TransitionSelected"; machineId: string; sourceStateTag: string; targetStateTag: string; eventTag: string; branch?: SelectedBranch; ownerPath?: string; macrostep?: number; }> | Readonly<{ _tag: "InvocationRetryScheduled"; machineId: string; stateTag: string; invocation: string; generation: number; policy: string; attempt: number; delayMillis: number; ownerPath?: string; workKind?: ... | ... | ...; lanes?: ReadonlyArray<...>; }> | Readonly<{ _tag: "ChildStarted"; machineId: string; stateTag: string; invocation: string; instanceId: string; childDefinitionId: string; generation: number; }> | Readonly<{ _tag: "ChildEventForwarded"; machineId: string; stateTag: string; invocation: string; instanceId: string; parentEventTag: string; childEventTag: string; generation: number; }> | Readonly<{ _tag: "ChildCompleted"; machineId: string; stateTag: string; invocation: string; instanceId: string; generation: number; branch?: SelectedBranch; }> | Readonly<{ _tag: ... | ...; machineId: string; stateTag: string; invocation: string; instanceId: string; generation: number; }> | Readonly<{ _tag: "StateChanged"; machineId: string; previousStateTag: string; nextStateTag: string; }> | Readonly<{ _tag: "MachineDefected"; machineId: string; stateTag: string; eventTag: string; defect: "ProtocolDefect"; }> | Readonly<{ _tag: "MachineCompleted"; machineId: string; finalStateTag: string; }> | Readonly<{ _tag: "EventIgnored"; machineId: string; stateTag: string; eventTag: string; }> | Readonly<{ _tag: ... | ... | ...; machineId: string; stateTag: string; timer: string; generation: number; ownerPath: string; durationMillis: number; }> | Readonly<{ _tag: "StaleOutcomeIgnored"; machineId: string; stateTag: string; ownerPath: string; generation: number; currentGeneration: number; outcome: ... | ... | ... | ... | ...; }> | Readonly<{ _tag: ... | ... | ... | ... | ...; machineId: string; stateTag: string; invocation: string; generation: number; branch?: SelectedBranch; ownerPath?: string; workKind?: ... | ... | ...; lanes?: ReadonlyArray<...>; }>

Defined in: packages/core/src/Machine.ts:1558

Metadata-only record of a meaningful interpreter decision or lifecycle change.

Details

Application state, event payloads, invocation values, and failures are intentionally omitted. Use MachineHandle.inspect to opt into event details with an explicit projection.

Since

0.1.0

SelectedBranch

SelectedBranch = Readonly<{ kind: "guard"; index: number; name: string; }> | Readonly<{ kind: "otherwise"; index: number; }>

Defined in: packages/core/src/Machine.ts:2572

Guard or fallback branch selected while processing a transition.

Since

0.1.0

Other

Tagged

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

Properties

_tag

readonly _tag: string

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

TaggedSchemaSource

TaggedSchemaSource = TaggedSchema | Schema.Union<ReadonlyArray<TaggedUnionMember>>

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

NormalizedTaggedSchema

NormalizedTaggedSchema<Source> = Source extends TaggedSchema ? Source : Source extends Schema.Union<infer Members> ? Schema.toTaggedUnion<"_tag", Members> : never

Defined in: packages/core/src/Machine.ts:39

Type Parameters

Source

Source extends TaggedSchemaSource

TagOf

TagOf<Value> = Value["_tag"]

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

Type Parameters

Value

Value extends Tagged

ByTag

ByTag<Value, Tag> = Extract<Value, { _tag: Tag; }>

Defined in: packages/core/src/Machine.ts:108

Type Parameters

Value

Value extends Tagged

Tag

Tag extends string

FieldsOf

FieldsOf<Value> = Omit<Value, "_tag">

Defined in: packages/core/src/Machine.ts:109

Type Parameters

Value

Value

NamedDuration

Defined in: packages/core/src/Machine.ts:417

Named synchronous logic that computes one timer duration when a node entry starts.

Type Parameters

State

State

Properties

name

readonly name: string

Defined in: packages/core/src/Machine.ts:418

description?

readonly optional description?: string

Defined in: packages/core/src/Machine.ts:419

compute

readonly compute: (state) => Input

Defined in: packages/core/src/Machine.ts:420

Parameters

state

State

Returns

Input

AfterTransition

AfterTransition<State, Current> = Readonly<{ duration: ... | ...; description?: string; }> & SingleAfterTransition<..., ...> | GuardedAfterTransition<..., ...>

Defined in: packages/core/src/Machine.ts:483

A transition owned by one node entry's timer.

Type Parameters

State

State extends Tagged

Current

Current extends TagOf<State>

InvokeSpecBase

Defined in: packages/core/src/Machine.ts:490

Common statically inspectable shape of invoked work.

Extended by

InvokeSpec

Properties

kind

readonly kind: "all" | "race" | "effect"

Defined in: packages/core/src/Machine.ts:491

name

readonly name: string

Defined in: packages/core/src/Machine.ts:492

InvokeSpec

Defined in: packages/core/src/Machine.ts:496

Carries inferred requirements without adding runtime data.

Extends

InvokeSpecBase

Type Parameters

Requirements

Requirements

Properties

kind

readonly kind: "all" | "race" | "effect"

Defined in: packages/core/src/Machine.ts:491

Inherited from

InvokeSpecBase.kind

name

readonly name: string

Defined in: packages/core/src/Machine.ts:492

Inherited from

InvokeSpecBase.name

_Requirements?

readonly optional _Requirements?: Requirements

Defined in: packages/core/src/Machine.ts:497

WorkSchema

WorkSchema = Schema.Codec<unknown, unknown, unknown, unknown>

Defined in: packages/core/src/Machine.ts:534

StatesConfig

StatesConfig<State, Event> = Readonly<{ [Current in TagOf<State>]: StateConfig<State, Event, Current> }>

Defined in: packages/core/src/Machine.ts:1112

Type Parameters

State

State extends Tagged

Event

Event extends Tagged

Builder

Builder<InputSchema, StateSchemaSource, EventSchemaSource> = ReturnType<typeof builder>

Defined in: packages/core/src/Machine.ts:2560

Fully inferred schema-bound builder returned by builder.

Type Parameters

InputSchema

InputSchema extends Schema.Top

StateSchemaSource

StateSchemaSource extends TaggedSchemaSource

EventSchemaSource

EventSchemaSource extends TaggedSchemaSource

RunEffect

RunEffect<StateSchema, EventSchema, States> = Effect.Effect<MachineHandle<Schema.Schema.Type<StateSchema>, Schema.Schema.Type<EventSchema>, Extract<Schema.Schema.Type<...>, { _tag: ...; }>, MachineError>, MachineError, MachineEngine | Scope.Scope | Exclude<RequirementsFromStates<...>, undefined> | StateSchema["EncodingServices"] | StateSchema["DecodingServices"] | EventSchema["EncodingServices"] | EventSchema["DecodingServices"]>

Defined in: packages/core/src/Machine.ts:2610

Effect returned by definition-level and data-first machine execution operations.

TaggedSchema = Schema.Top & Readonly<{ Type: Tagged; cases: Readonly<...>; }>

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

Schema for a _tag-discriminated union whose cases remain available for machine tooling.

Details

The cases record lets the builder, graph projection, and codecs inspect each state or event variant without executing machine behavior.

Since

0.1.0

TaggedUnion

TaggedUnion<Cases> = Schema.TaggedUnion<TaggedUnionCases<Cases>>

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

Tagged-union schema inferred from a record of case definitions.

MachineInput<Definition> = Definition extends Readonly<{ schemas: Readonly<...>; }> ? Schema.Schema.Type<InputSchema> : never

Defined in: packages/core/src/Machine.ts:1733

Decoded input type inferred from a machine definition.

MachineState<Definition> = Definition extends Readonly<{ schemas: Readonly<...>; }> ? Schema.Schema.Type<StateSchema> : never

Defined in: packages/core/src/Machine.ts:1746

Decoded state union inferred from a machine definition.

MachineEvent<Definition> = Definition extends Readonly<{ schemas: Readonly<...>; }> ? Schema.Schema.Type<EventSchema> : never

Defined in: packages/core/src/Machine.ts:1759

Decoded event union inferred from a machine definition.

MachineCompletion<Definition> = Definition extends Readonly<{ schemas: Readonly<...>; states: infer States; }> ? Extract<Schema.Schema.Type<StateSchema>, { _tag: FinalTags<...>; }> : never

Defined in: packages/core/src/Machine.ts:1780

Union of final-state values inferred from a machine definition.

Details

Definitions without final nodes produce never.

MachineRequirements<Definition> = Definition extends Readonly<{ states: infer States; }> ? Exclude<RequirementsFromStates<States>, undefined> : never

Defined in: packages/core/src/Machine.ts:1832

Effect requirements collected from a definition's invocations and child machines.

Machine API