uē-tôo

Appearance

@ue-too/being / TemplateStateMachine

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

Defined in: interface.ts:560

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 ​

  1. Define your event payload mapping type
  2. Define your states as a string union type
  3. Create state classes extending TemplateState
  4. 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 ​

Extended by ​

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:591

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:578

_currentState ​

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

Defined in: interface.ts:573

_happensCallbacks ​

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

Defined in: interface.ts:581

Parameters ​

args ​

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

context ​

Context

Returns ​

void

_initialState ​

protected _initialState: States

Defined in: interface.ts:589

_stateChangeCallbacks ​

protected _stateChangeCallbacks: StateChangeCallback<States>[]

Defined in: interface.ts:580

_states ​

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

Defined in: interface.ts:574

_statesArray ​

protected _statesArray: States[]

Defined in: interface.ts:579

_timeouts ​

protected _timeouts: number | undefined = undefined

Defined in: interface.ts:588

Accessors ​

currentState ​

Get Signature ​

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

Defined in: interface.ts:722

Returns ​

"INITIAL" | "TERMINAL" | States

possibleStates ​

Get Signature ​

get possibleStates(): States[]

Defined in: interface.ts:730

Returns ​

States[]

Implementation of ​

StateMachine.possibleStates

states ​

Get Signature ​

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

Defined in: interface.ts:734

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:652

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:658

Type Parameters ​
K ​

K extends string

Parameters ​
args ​

...EventArgs<EventPayloadMapping, K>

Returns ​

EventResult<States, unknown>

Implementation of ​

StateMachine.happens

onHappens() ​

onHappens(callback): void

Defined in: interface.ts:710

Parameters ​

callback ​

(args, context) => void

Returns ​

void

Implementation of ​

StateMachine.onHappens

onStateChange() ​

onStateChange(callback): void

Defined in: interface.ts:706

Parameters ​

callback ​

StateChangeCallback<States>

Returns ​

void

Implementation of ​

StateMachine.onStateChange

reset() ​

reset(): void

Defined in: interface.ts:612

Returns ​

void

Implementation of ​

StateMachine.reset

setContext() ​

setContext(context): void

Defined in: interface.ts:726

Parameters ​

context ​

Context

Returns ​

void

Implementation of ​

StateMachine.setContext

start() ​

start(): void

Defined in: interface.ts:618

Returns ​

void

Implementation of ​

StateMachine.start

switchTo() ​

switchTo(state): void

Defined in: interface.ts:647

Parameters ​

state ​

"INITIAL" | "TERMINAL" | States

Returns ​

void

Implementation of ​

StateMachine.switchTo

wrapup() ​

wrapup(): void

Defined in: interface.ts:631

Returns ​

void

Implementation of ​

StateMachine.wrapup