State machine types

Read as Markdown

MachineEvent

Event object with a string type discriminator.

MachineEventRoutes

Maps event discriminators to typed transition handlers. Each handler receives its narrowed event.

MachineStatus

Actor lifecycle: not-started, active, stopped, or error. A game-over application state can remain active.

MachineSnapshot

Readonly state value, context, lifecycle status, error, and matches(state) predicate, published as one signal value.

MachineTaskCleanup

Synchronous cleanup function for callback work. Called once when its state exits or its actor stops.

MachineActionContext

Context, initiating event, immutable actor input, and queued send function supplied to synchronous actions.

MachineAction

Synchronous effect used in entry, exit, or a transition. Use assign for context updates.

MachineActions

One action or a readonly array of actions executed in order.

MachineTaskContext

Entry context, initiating event (undefined initially), actor input, abort signal, and send function supplied to owned work.

MachineTask

Cancelable state-owned function returning a cleanup, a promise, or no result. Promises select completion/error routes; cleanup functions remain owned until exit.

MachineTaskDoneEvent

Internal completion event carrying the task output. Observed by its invocation’s onDone handler.

MachineTaskErrorEvent

Internal failure event carrying the task error. Observed by its invocation’s onError handler.

MachineInvocation

Task with optional diagnostic id and onDone/onError transitions. A state may declare one or several invocations.

MachineTransitionConfig

Optional target, guard, ordered actions, and explicit same-state reentry flag.

MachineTransition

A destination name, configured transition, or ordered list of guarded alternatives.

MachineState

Flat state with optional entry/exit actions, owned invocations, and local event routes.

MachineDefinition

Reusable initial state, context factory/value, state table, and machine-level fallback routes.

CreateMachineOptions

Input captured by the actor at creation. Use { input: undefined } for machines without input.

MachineActor

Execution handle with a readonly snapshot signal and start, send, and terminal idempotent stop methods.

MachineAnimationOptions

Optional existing playback conflict policy and diagnostic name, imported from the animation adapter entry.

MachineAnimationProgramFactory

Builds one animation program per state entry from task context, imported from the animation adapter entry.

API details from source

CreateMachineOptions

Options used to create an explicitly owned actor.

interface CreateMachineOptions<Input>

Related API: CreateMachineOptions.

See also

MachineActor

View source — packages/core/src/features/machines/types.ts:172

Properties and methods

input

readonly input: Input

Immutable application input available to context factories, actions, and tasks.

View source — packages/core/src/features/machines/types.ts:174

MachineAction

A synchronous effect run during entry, exit, or a transition.

type MachineAction<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = {
  // Method bivariance lets a reusable event-specific action (such as assign()) run on an initial
  // entry as long as that action does not inspect an absent event.
  /** Executes one synchronous effect.
   * @param context - Current transition values.
   */
  action(context: MachineActionContext<Context, Event, Input, SentEvent>): void;
}['action']

Related API: MachineAction, MachineEvent, assign, MachineActionContext.

See also

MachineActionContext

View source — packages/core/src/features/machines/types.ts:57

MachineActionContext

Values given to state actions. Context reflects all preceding assign actions.

interface MachineActionContext<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent>

Related API: MachineActionContext, MachineEvent.

See also

MachineAction

View source — packages/core/src/features/machines/types.ts:43

Properties and methods

context

readonly context: Readonly<Context>

Context as it exists at this point in the transition.

View source — packages/core/src/features/machines/types.ts:45

event

readonly event: Event

Event which selected this transition.

View source — packages/core/src/features/machines/types.ts:47

input

readonly input: Input

Immutable actor input supplied at creation.

View source — packages/core/src/features/machines/types.ts:49

send

send: (event: SentEvent) => void

Queues an event after the current transition has completed.

Parameters

• event — Event to process after the active transition.

View source — packages/core/src/features/machines/types.ts:53

MachineActions

One action or actions run in source order.

type MachineActions<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = | MachineAction<Context, Event, Input, SentEvent>
  | readonly MachineAction<Context, Event, Input, SentEvent>[]

Related API: MachineActions, MachineEvent, MachineAction.

See also

MachineAction

View source — packages/core/src/features/machines/types.ts:67

MachineActor

Explicitly owned machine execution. Call start before sending events and stop to release it.

interface MachineActor<Context, Event extends MachineEvent, _Input, State extends string = string>

Related API: MachineActor, MachineEvent.

See also

MachineDefinition

View source — packages/core/src/features/machines/types.ts:178

Properties and methods

snapshot

readonly snapshot: Signal<MachineSnapshot<Context, State>>

Related API: Signal, MachineSnapshot.

Readonly, synchronous signal for the current state and context.

View source — packages/core/src/features/machines/types.ts:180

start

start: () => void

Starts the initial state once. Starting an active or stopped actor does nothing.

View source — packages/core/src/features/machines/types.ts:182

send

send: (event: Event) => void

Queues an event. Events sent during actions run after the current transition.

Parameters

• event — Event accepted by this actor.

View source — packages/core/src/features/machines/types.ts:186

stop

stop: () => void

Terminal, idempotent cleanup. Cancels every task owned by the active state.

View source — packages/core/src/features/machines/types.ts:188

MachineDefinition

Declarative, reusable machine definition. Definitions create no actor or scheduled work.

interface MachineDefinition<Context, Event extends MachineEvent, Input = undefined, State extends string = string>

Related API: MachineDefinition, MachineEvent.

See also

MachineActor

View source — packages/core/src/features/machines/types.ts:157

Properties and methods

initial

readonly initial: State

State entered when an actor starts.

View source — packages/core/src/features/machines/types.ts:159

context

readonly context: Context | ((context: Readonly<{ input: Input; }>) => Context)

Initial context or a factory evaluated once for every actor.

Parameters

• context — Input used to create this actor’s context.

Returns

Initial context for the new actor.

View source — packages/core/src/features/machines/types.ts:164

states

readonly states: Readonly<Record<State, MachineState<Context, Event, Input, State>>>

Related API: MachineState.

State table. This initial implementation supports flat states only.

View source — packages/core/src/features/machines/types.ts:166

on (optional)

readonly on?: MachineEventRoutes<Context, Event, Input, State> | undefined

Related API: MachineEventRoutes.

Fallback routes for events not declared by the active state.

View source — packages/core/src/features/machines/types.ts:168

MachineEvent

An event accepted by a machine. The type selects the active state’s handler.

interface MachineEvent

Related API: MachineEvent.

See also

MachineDefinition

View source — packages/core/src/features/machines/types.ts:4

Properties and methods

type

readonly type: string

Stable event discriminator.

View source — packages/core/src/features/machines/types.ts:6

MachineEventRoutes

Maps each event discriminator to its narrowed event shape.

type MachineEventRoutes<Context, Event extends MachineEvent, Input, State extends string> = {
  /** Handler selected for the corresponding event discriminator. */
  [type in Event['type']]?: MachineTransition<Context, Extract<Event, { /** Discriminator used to select this event variant. */ readonly type: type }>, Input, State, Event>;
}

Related API: MachineEventRoutes, MachineEvent, MachineTransition.

See also

MachineTransition

View source — packages/core/src/features/machines/types.ts:14

MachineInvocation

State-owned task and optional completion transitions.

interface MachineInvocation<Context, Event extends MachineEvent, Input, State extends string>

Related API: MachineInvocation, MachineEvent.

See also

MachineTask

View source — packages/core/src/features/machines/types.ts:112

Properties and methods

id (optional)

readonly id?: string | undefined

Optional diagnostic identity; IDs are local to one state entry.

View source — packages/core/src/features/machines/types.ts:114

task

readonly task: MachineTask<Context, Event, Input, unknown>

Related API: MachineTask.

Work started after this state’s snapshot publishes.

View source — packages/core/src/features/machines/types.ts:116

onDone (optional)

readonly onDone?: MachineTransition<Context, MachineTaskDoneEvent<unknown>, Input, State, Event> | undefined

Related API: MachineTransition, MachineTaskDoneEvent.

Transition selected if a promise resolves before cancellation.

View source — packages/core/src/features/machines/types.ts:118

onError (optional)

readonly onError?: MachineTransition<Context, MachineTaskErrorEvent, Input, State, Event> | undefined

Related API: MachineTransition, MachineTaskErrorEvent.

Transition selected if a task throws or a promise rejects before cancellation.

View source — packages/core/src/features/machines/types.ts:120

MachineSnapshot

Immutable state published by a running machine actor.

interface MachineSnapshot<Context, State extends string = string>

Related API: MachineSnapshot.

See also

MachineActor

View source — packages/core/src/features/machines/types.ts:23

Properties and methods

value

readonly value: State

Active flat state name.

View source — packages/core/src/features/machines/types.ts:25

context

readonly context: Readonly<Context>

Application-owned immutable context for the active state.

View source — packages/core/src/features/machines/types.ts:27

status

readonly status: MachineStatus

Related API: MachineStatus.

Whether the actor may receive events.

View source — packages/core/src/features/machines/types.ts:29

error

readonly error: unknown

Unexpected failure that stopped this actor, if any.

View source — packages/core/src/features/machines/types.ts:31

matches

matches: (state: State) => boolean

Tests whether this flat machine currently occupies state.

Parameters

• state — State name to compare with the active value.

Returns

True when this is the active state.

View source — packages/core/src/features/machines/types.ts:36

MachineState

One flat state definition. Local event handlers shadow machine-level handlers.

interface MachineState<Context, Event extends MachineEvent, Input, State extends string>

Related API: MachineState, MachineEvent.

See also

MachineDefinition

View source — packages/core/src/features/machines/types.ts:145

Properties and methods

entry (optional)

readonly entry?: MachineActions<Context, Event | undefined, Input, Event> | undefined

Related API: MachineActions.

Effects run whenever this state is entered. The initial entry receives undefined as event.

View source — packages/core/src/features/machines/types.ts:147

exit (optional)

readonly exit?: MachineActions<Context, Event, Input, Event> | undefined

Related API: MachineActions.

Effects run whenever this state is exited.

View source — packages/core/src/features/machines/types.ts:149

invoke (optional)

readonly invoke?: MachineInvocation<Context, Event, Input, State> | readonly MachineInvocation<Context, Event, Input, State>[] | undefined

Related API: MachineInvocation.

State-owned work, canceled before exit effects.

View source — packages/core/src/features/machines/types.ts:151

on (optional)

readonly on?: MachineEventRoutes<Context, Event, Input, State> | undefined

Related API: MachineEventRoutes.

Event routes local to this state. Declaring an event consumes machine-level handling.

View source — packages/core/src/features/machines/types.ts:153

MachineStatus

Lifecycle state of a machine actor.

type MachineStatus = 'not-started' | 'active' | 'stopped' | 'error'

Related API: MachineStatus.

See also

MachineActor

View source — packages/core/src/features/machines/types.ts:20

MachineTask

Cancelable work owned by a state entry. Return a cleanup for subscriptions or a promise for finite work. A task is never started until its entry snapshot has been published.

type MachineTask<Context, Event extends MachineEvent, Input, Output = unknown> = (
  context: MachineTaskContext<Context, Event, Input>,
) => void | MachineTaskCleanup | Promise<Output>

Related API: MachineTask, MachineEvent, MachineTaskContext, MachineTaskCleanup.

Parameters

• context — State-entry values and cancellation signal.

Returns

Optional cleanup or a promise for finite work.

See also

MachineInvocation

View source — packages/core/src/features/machines/types.ts:94

MachineTaskCleanup

Cleanup called when a callback task’s owning state exits or its actor stops.

type MachineTaskCleanup = () => void

Related API: MachineTaskCleanup.

See also

MachineTask

View source — packages/core/src/features/machines/types.ts:40

MachineTaskContext

Values supplied to a state-owned task when that state is entered.

interface MachineTaskContext<Context, Event extends MachineEvent, Input>

Related API: MachineTaskContext, MachineEvent.

See also

MachineTask

View source — packages/core/src/features/machines/types.ts:72

Properties and methods

context

readonly context: Readonly<Context>

Context captured when this particular task starts.

View source — packages/core/src/features/machines/types.ts:74

event

readonly event: Event | undefined

Event that entered this state, or undefined for the initial state.

View source — packages/core/src/features/machines/types.ts:76

input

readonly input: Input

Immutable actor input supplied at creation.

View source — packages/core/src/features/machines/types.ts:78

signal

readonly signal: AbortSignal

Related API: signal.

Aborted synchronously when the owning state exits.

View source — packages/core/src/features/machines/types.ts:80

send

send: (event: Event) => void

Queues an event after the current transition, without re-entering the actor.

Parameters

• event — Event accepted by the owning actor.

View source — packages/core/src/features/machines/types.ts:84

MachineTaskDoneEvent

Completion data supplied to an invocation’s onDone transition.

interface MachineTaskDoneEvent<Output = unknown> extends MachineEvent

Related API: MachineTaskDoneEvent, MachineEvent.

See also

MachineInvocation

View source — packages/core/src/features/machines/types.ts:99

Properties and methods

type

readonly type: "@pibbl/machine.done"

Related API: pibbl.

Internal completion discriminator.

View source — packages/core/src/features/machines/types.ts:100

output

readonly output: Output

Value resolved by the task promise.

View source — packages/core/src/features/machines/types.ts:101

MachineTaskErrorEvent

Failure data supplied to an invocation’s onError transition.

interface MachineTaskErrorEvent extends MachineEvent

Related API: MachineTaskErrorEvent, MachineEvent.

See also

MachineInvocation

View source — packages/core/src/features/machines/types.ts:105

Properties and methods

type

readonly type: "@pibbl/machine.error"

Related API: pibbl.

Internal failure discriminator.

View source — packages/core/src/features/machines/types.ts:106

error

readonly error: unknown

Thrown or rejected task value.

View source — packages/core/src/features/machines/types.ts:107

MachineTransition

Shorthand state target, a configured route, or ordered guarded alternatives.

type MachineTransition<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event> = | State
  | MachineTransitionConfig<Context, Event, Input, State, SentEvent>
  | readonly MachineTransitionConfig<Context, Event, Input, State, SentEvent>[]

Related API: MachineTransition, MachineEvent, MachineTransitionConfig.

See also

MachineTransitionConfig

View source — packages/core/src/features/machines/types.ts:139

MachineTransitionConfig

A conditional route considered in list order.

interface MachineTransitionConfig<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event>

Related API: MachineTransitionConfig, MachineEvent.

See also

MachineTransition

View source — packages/core/src/features/machines/types.ts:124

Properties and methods

target (optional)

readonly target?: State | undefined

Destination state. Omit to run actions without leaving the current state.

View source — packages/core/src/features/machines/types.ts:126

guard (optional)

readonly guard?: ((context: MachineActionContext<Context, Event, Input, SentEvent>) => boolean) | undefined

Related API: MachineActionContext.

Only select this route when it returns true.

Parameters

• context — Current transition values.

Returns

Whether this route may be selected.

View source — packages/core/src/features/machines/types.ts:131

actions (optional)

readonly actions?: MachineActions<Context, Event, Input, SentEvent> | undefined

Related API: MachineActions.

Effects run after exit and before entry.

View source — packages/core/src/features/machines/types.ts:133

reenter (optional)

readonly reenter?: boolean | undefined

Restarts entry work when targeting the already active state.

View source — packages/core/src/features/machines/types.ts:135

MachineAnimationOptions

Playback options owned by a machine animation task.

Lifecycle callbacks are deliberately omitted: task completion and failure become the invocation’s onDone and onError transitions instead.

interface MachineAnimationOptions

Related API: MachineAnimationOptions.

See also

playAnimation

View source — packages/core/src/features/machines/animation.ts:23

Properties and methods

conflict (optional)

readonly conflict?: "error" | "replace" | undefined

Selects the existing writer-conflict policy for this state-owned playback. Defaults to the animation runtime’s explicit-error policy.

View source — packages/core/src/features/machines/animation.ts:28

debugName (optional)

readonly debugName?: string | undefined

Optional label included in animation scheduler diagnostics.

View source — packages/core/src/features/machines/animation.ts:30

MachineAnimationProgramFactory

Builds the animation program for one state entry.

The callback runs once when the invocation starts. It receives the entry’s immutable context and event, the machine input, the cancellation signal, and send for application-defined machine events.

type MachineAnimationProgramFactory<Context, Event extends MachineEvent, Input> = (
  context: MachineTaskContext<Context, Event, Input>,
) => PibblAnimationProgram

Related API: MachineAnimationProgramFactory, MachineEvent, MachineTaskContext, PibblAnimationProgram.

Type parameters

• Context — Context captured when this state entry began.

• Event — Event type accepted by the owning machine.

• Input — Input captured by the owning machine actor.

Parameters

• context — Immutable state-entry values used to create this program.

Returns

The program that the machine invocation owns until it finishes or is cancelled.

See also

MachineTaskContext

View source — packages/core/src/features/machines/animation.ts:47

Implementation guidance for agents

Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

• Cancelable machine tasks: Run a state-owned task, observe completion, and release actors and listeners. Plain source
• State-owned animation: Move a circle with a machine-owned animation task that completes into the next state. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.