@ue-too/being / index / TemplateStateMachine

Class: TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Concrete implementation of a finite state machine.

Remarks

This class provides a complete, ready-to-use state machine implementation. It's generic enough to handle most use cases without requiring custom extensions.

Features

Type-safe events: Events and their payloads are fully typed via the EventPayloadMapping
State transitions: Automatic state transitions based on event handlers
Event outputs: Handlers can return values that are included in the result
Lifecycle hooks: States can define uponEnter and beforeExit callbacks
State change listeners: Subscribe to state transitions
Shared context: All states access the same context object for persistent data

Usage Pattern

Define your event payload mapping type
Define your states as a string union type
Create state classes extending TemplateState
Instantiate TemplateStateMachine with your states and initial state

Example

Basic vending machine state machine

typescript

type Events = {
  insertCoin: { amount: number };
  selectItem: { itemId: string };
  cancel: {};
};

type States = "IDLE" | "PAYMENT" | "DISPENSING";

interface VendingContext extends BaseContext {
  balance: number;
  setup() { this.balance = 0; }
  cleanup() {}
}

const context: VendingContext = {
  balance: 0,
  setup() { this.balance = 0; },
  cleanup() {}
};

const machine = new TemplateStateMachine<Events, VendingContext, States>(
  {
    IDLE: new IdleState(),
    PAYMENT: new PaymentState(),
    DISPENSING: new DispensingState()
  },
  "IDLE",
  context
);

// Trigger events
machine.happens("insertCoin", { amount: 100 });
machine.happens("selectItem", { itemId: "A1" });

See

TemplateState for creating state implementations
StateMachine for the interface definition

Type Parameters

EventPayloadMapping

EventPayloadMapping

Object mapping event names to their payload types

Context

Context extends BaseContext

Context type shared across all states

States

States extends string = "IDLE"

Union of all possible state names (string literals)

EventOutputMapping

EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>

Optional mapping of events to their output types

Implements

StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Constructors

Constructor

new TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>(states, initialState, context, autoStart): TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Defined in: interface.ts:701

Parameters

states

Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>

initialState

States

context

Context

autoStart

boolean = true

Returns

TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Properties

_context

protected _context: Context

Defined in: interface.ts:683

_currentState

protected _currentState: "INITIAL" | "TERMINAL" | States

Defined in: interface.ts:678

_eventResultCallbacks

protected _eventResultCallbacks: EventResultCallback<EventPayloadMapping, Context, States>[]

Defined in: interface.ts:693

_happensCallbacks

protected _happensCallbacks: (args, context) => void[]

Defined in: interface.ts:686

Parameters

args

EventArgs<EventPayloadMapping, string> | EventArgs<EventPayloadMapping, keyof EventPayloadMapping>

context

Context

Returns

void

_initialState

protected _initialState: States

Defined in: interface.ts:699

_stateChangeCallbacks

protected _stateChangeCallbacks: StateChangeCallback<States>[]

Defined in: interface.ts:685

_states

protected _states: Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>

Defined in: interface.ts:679

_statesArray

protected _statesArray: States[]

Defined in: interface.ts:684

_timeouts

protected _timeouts: number | undefined = undefined

Defined in: interface.ts:698

Accessors

context

Get Signature

get context(): Context

Defined in: interface.ts:874

Read-only access to the machine's live context object. Optional so existing StateMachine implementations remain valid; TemplateStateMachine always provides it. Intended for tooling/introspection (e.g. visualizers evaluating guards against the current context) — mutate state through events, not through this reference.

Returns

Context

Implementation of

StateMachine.context

currentState

Get Signature

get currentState(): "INITIAL" | "TERMINAL" | States

Defined in: interface.ts:866

Returns

"INITIAL" | "TERMINAL" | States

Implementation of

StateMachine.currentState

possibleStates

Get Signature

get possibleStates(): States[]

Defined in: interface.ts:878

Returns

States[]

Implementation of

StateMachine.possibleStates

states

Get Signature

get states(): Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>

Defined in: interface.ts:882

Returns

Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>

Implementation of

StateMachine.states

Methods

happens()

Call Signature

happens<K>(...args): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K<K>] : void>

Defined in: interface.ts:763

Type Parameters

K

K extends string | number | symbol

Parameters

args

...EventArgs<EventPayloadMapping, K>

Returns

EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K<K>] : void>

Implementation of

StateMachine.happens

Call Signature

happens<K>(...args): EventResult<States, unknown>

Defined in: interface.ts:769

Type Parameters

K

K extends string

Parameters

args

...EventArgs<EventPayloadMapping, K>

Returns

EventResult<States, unknown>

Implementation of

StateMachine.happens

onEventResult()

onEventResult(callback): () => void

Defined in: interface.ts:854

Subscribe to every event result. Optional so existing StateMachine implementations remain valid; TemplateStateMachine always provides it. Returns a disposer on implementations that support one. Disposing during a dispatch takes effect starting with the next dispatch, not the one in progress — see EventResultCallback for the exact snapshot-iteration semantics.

Parameters

callback

EventResultCallback<EventPayloadMapping, Context, States>

Returns

(): void

Returns

void

Implementation of

StateMachine.onEventResult

onHappens()

onHappens(callback): () => void

Defined in: interface.ts:836

Subscribe to every happens() call, before the state handles it. Returns a disposer on implementations that support one. Disposing during a dispatch takes effect starting with the next dispatch, not the one in progress — see EventResultCallback for the exact snapshot-iteration semantics.

Parameters

callback

(args, context) => void

Returns

(): void

Returns

void

Implementation of

StateMachine.onHappens

onStateChange()

onStateChange(callback): () => void

Defined in: interface.ts:826

Subscribe to state changes. Returns a disposer on implementations that support one. Disposing during a dispatch takes effect starting with the next dispatch, not the one in progress — see EventResultCallback for the exact snapshot-iteration semantics.

Parameters

callback

StateChangeCallback<States>

Returns

(): void

Returns

void

Implementation of

StateMachine.onStateChange

reset()

reset(): void

Defined in: interface.ts:723

Returns

void

Implementation of

StateMachine.reset

setContext()

setContext(context): void

Defined in: interface.ts:870

Parameters

context

Context

Returns

void

Implementation of

StateMachine.setContext

start()

start(): void

Defined in: interface.ts:729

Returns

void

Implementation of

StateMachine.start

switchTo()

switchTo(state): void

Defined in: interface.ts:758

Parameters

state

"INITIAL" | "TERMINAL" | States

Returns

void

Implementation of

StateMachine.switchTo

wrapup()

wrapup(): void

Defined in: interface.ts:742

Returns

void

Implementation of

StateMachine.wrapup

Class: TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping> ​

Remarks ​

Features ​

Usage Pattern ​

Example ​

See ​

Type Parameters ​

EventPayloadMapping ​

Context ​

States ​

EventOutputMapping ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

states ​

initialState ​

context ​

autoStart ​

Returns ​

Properties ​

_context ​

_currentState ​

_eventResultCallbacks ​

_happensCallbacks ​

Parameters ​

args ​

context ​

Returns ​

_initialState ​

_stateChangeCallbacks ​

_states ​

_statesArray ​

_timeouts ​

Accessors ​

context ​

Get Signature ​

Returns ​

Implementation of ​

currentState ​

Get Signature ​

Returns ​

Implementation of ​

possibleStates ​

Get Signature ​

Returns ​

Implementation of ​

states ​

Get Signature ​

Returns ​

Implementation of ​

Methods ​

happens() ​

Call Signature ​

Type Parameters ​

K ​

Parameters ​

args ​

Returns ​

Implementation of ​

Call Signature ​

Type Parameters ​

K ​

Parameters ​

args ​

Returns ​

Implementation of ​

onEventResult() ​

Parameters ​

callback ​

Returns ​

Returns ​

Implementation of ​

onHappens() ​

Parameters ​

callback ​

Returns ​

Returns ​

Implementation of ​

onStateChange() ​

Class: TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Remarks

Features

Usage Pattern

Example

See

Type Parameters

EventPayloadMapping

Context

States

EventOutputMapping

Implements

Constructors

Constructor

Parameters

states

initialState

context

autoStart

Returns

Properties

_context

_currentState

_eventResultCallbacks

_happensCallbacks

Parameters

args

context

Returns

_initialState

_stateChangeCallbacks

_states

_statesArray

_timeouts

Accessors

context

Get Signature

Returns

Implementation of

currentState

Get Signature

Returns

Implementation of

possibleStates

Get Signature

Returns

Implementation of

states

Get Signature

Returns

Implementation of

Methods

happens()

Call Signature

Type Parameters

K

Parameters

args

Returns

Implementation of

Call Signature

Type Parameters

K

Parameters

args

Returns

Implementation of

onEventResult()

Parameters

callback

Returns

Returns

Implementation of

onHappens()

Parameters

callback

Returns

Returns

Implementation of

onStateChange()