State machine functions
Import from @pibbl/core/machines or pibbl/machines. Standalone actors have no
renderer or animation dependency. See the guide
and types.
defineMachine
Section titled “defineMachine”defineMachine<Context, Event, Input>(definition) validates and normalizes a
reusable flat machine. Input defaults to undefined. Supply initial, context
(an initial value or a per-actor input factory), and states. Optional machine-level
on handlers provide fallback behavior. Unknown state targets reject at definition
time. Creating a definition starts no tasks, timers, or animation.
createMachine
Section titled “createMachine”createMachine(definition, { input }) returns an actor with snapshot, start,
send, and stop. It begins as not-started. start() enters the initial state;
send(event) processes serially while active. Nested sends queue. stop() is
terminal and idempotent, canceling all state-owned tasks. Sends before start or
after stop do nothing. Retain the actor and stop it when its owner ends.
Snapshots carry state value, context, status, error, and matches(state). Read
with .get() or derive a computed signal. Never send while rendering or computing.
Use useMachine for component ownership.
assign
Section titled “assign”assign(({ context, event, input, send }) => patch) creates an action which
shallowly merges a context patch. Earlier assignments are visible to later actions
in the same transition. Treat nested context objects as immutable. An event’s
transition publishes state and context together; assignments do not individually
publish intermediate snapshots.
fromCallback
Section titled “fromCallback”fromCallback(callback) adapts subscription-style work for invoke.task. The
callback receives context, event, input, signal, and send. It can return a cleanup
function, called once on state exit or stop. Returning cleanup does not complete
an invocation. Use promise tasks for finite results and onDone/onError.
Cancellation aborts the task signal. Stale task results are ignored even if external
work failed to honor cancellation. Unexpected action/guard errors terminate the
actor; invocation errors may take their declared onError route.
Related types: MachineDefinition, MachineActor, MachineSnapshot, MachineTask.
API details from source
Section titled “API details from source”
assign
Section titled “assign”Creates an action that shallowly merges a context patch. Earlier assignments in the same transition are visible to later actions. Context itself remains application-owned data.
assign: <Context extends object, Event extends MachineEvent, Input>(update: (context: MachineActionContext<Context, Event, Input>) => Partial<Context>) => MachineAction<Context, Event, Input>Related API: assign, MachineEvent, MachineActionContext, MachineAction.
Examples
Section titled “Examples”const collect = assign(({ context }) => ({ coins: context.coins + 1 }));Parameters
Section titled “Parameters”update— Produces the shallow context patch for this transition.
Returns
Section titled “Returns”An action accepted by state entry, exit, and transition action lists.
See also
Section titled “See also”View source — packages/core/src/features/machines/assign.ts:22
fromCallback
Section titled “fromCallback”Marks callback-style cancelable work as a machine task. The callback may return a cleanup; its cleanup runs exactly once when the owning state exits or the actor stops.
fromCallback: <Context, Event extends MachineEvent, Input>(callback: MachineTask<Context, Event, Input>) => MachineTask<Context, Event, Input>Related API: fromCallback, MachineEvent, MachineTask.
Parameters
Section titled “Parameters”callback— Callback task to retain as state-owned work.
Returns
Section titled “Returns”The same callback, typed for an invocation’s task field.
See also
Section titled “See also”View source — packages/core/src/features/machines/callback.ts:10
createMachine
Section titled “createMachine”Creates an explicitly owned, initially idle machine actor. Call start() when ownership begins
and stop() when it ends. The actor has no renderer, scheduler, or animation dependency.
createMachine: <Context, Event extends MachineEvent, Input, State extends string = string>(definition: MachineDefinition<Context, Event, Input, State>, options: CreateMachineOptions<Input>) => MachineActor<Context, Event, Input, State>Related API: createMachine, MachineEvent, MachineDefinition, CreateMachineOptions, MachineActor.
Parameters
Section titled “Parameters”-
definition— Reusable behavior previously authored with defineMachine. -
options— Immutable input supplied to this actor.
Returns
Section titled “Returns”An idle actor that owns no task until it starts.
See also
Section titled “See also”View source — packages/core/src/features/machines/runtime.ts:55
defineMachine
Section titled “defineMachine”Validates and records a reusable flat machine definition. Calling this function performs no
work and creates no actor; use createMachine or useMachine to execute it.
defineMachine: <Context, Event extends MachineEvent, Input = undefined, State extends string = string>(definition: MachineDefinition<Context, Event, Input, State>) => MachineDefinition<Context, Event, Input, State>Related API: defineMachine, MachineEvent, MachineDefinition.
Parameters
Section titled “Parameters”definition— Reusable machine behavior to validate and normalize.
Returns
Section titled “Returns”The supplied definition, suitable for actor creation.
See also
Section titled “See also”View source — packages/core/src/features/machines/runtime.ts:40
Implementation guidance for agents
Section titled “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
Section titled “Complete minimal examples”- Cancelable machine tasks: Run a state-owned task, observe completion, and release actors and listeners. Plain source
Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.