uē-tôo

Appearance

@ue-too/being / TemplateState

Abstract Class: TemplateState<EventPayloadMapping, Context, States, EventOutputMapping> ​

Defined in: interface.ts:825

Abstract base class for state machine states.

Remarks ​

This abstract class provides the foundation for implementing individual states in a state machine. Each state defines how it responds to events through the eventReactions object.

Key Concepts ​

  • Event Reactions: Define handlers for events this state cares about. Unhandled events are ignored.
  • Guards: Conditional logic that determines which state to transition to based on context
  • Lifecycle Hooks: uponEnter and beforeExit callbacks for state transition side effects
  • Selective Handling: Only define reactions for events relevant to this state

Implementation Pattern ​

  1. Extend this class for each state in your state machine
  2. Implement the eventReactions property with handlers for relevant events
  3. Optionally override uponEnter and beforeExit for lifecycle logic
  4. Optionally define guards and eventGuards for conditional transitions

Examples ​

Simple state implementation

typescript
class IdleState extends TemplateState<MyEvents, MyContext, MyStates> {
  eventReactions = {
    start: {
      action: (context, event) => {
        console.log('Starting...');
        context.startTime = Date.now();
      },
      defaultTargetState: "ACTIVE"
    },
    reset: {
      action: (context, event) => {
        context.counter = 0;
      }
      // No state transition - stays in IDLE
    }
  };

  uponEnter(context, stateMachine, fromState) {
    console.log(`Entered IDLE from ${fromState}`);
  }
}

State with guards for conditional transitions

typescript
class PaymentState extends TemplateState<Events, VendingContext, States> {
  guards = {
    hasEnoughMoney: (context) => context.balance >= context.itemPrice,
    needsChange: (context) => context.balance > context.itemPrice
  };

  eventReactions = {
    selectItem: {
      action: (context, event) => {
        context.selectedItem = event.itemId;
        context.itemPrice = getPrice(event.itemId);
      },
      defaultTargetState: "IDLE" // Fallback if no guard matches
    }
  };

  eventGuards = {
    selectItem: [
      { guard: 'hasEnoughMoney', target: 'DISPENSING' },
      // If hasEnoughMoney is false, uses defaultTargetState (IDLE)
    ]
  };
}

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 ​

  • State<EventPayloadMapping, Context, States, EventOutputMapping>

Constructors ​

Constructor ​

new TemplateState<EventPayloadMapping, Context, States, EventOutputMapping>(): TemplateState<EventPayloadMapping, Context, States, EventOutputMapping>

Returns ​

TemplateState<EventPayloadMapping, Context, States, EventOutputMapping>

Properties ​

_defer ​

protected _defer: Defer<Context, EventPayloadMapping, States, EventOutputMapping> | undefined = undefined

Defined in: interface.ts:854

_delay ​

protected _delay: Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined = undefined

Defined in: interface.ts:850

_eventGuards ​

protected _eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>

Defined in: interface.ts:845

_eventReactions ​

protected _eventReactions: EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>

Defined in: interface.ts:833

_guards ​

protected _guards: Guard<Context>

Defined in: interface.ts:844

Accessors ​

delay ​

Get Signature ​

get delay(): Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined

Defined in: interface.ts:883

Returns ​

Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined

Implementation of ​

State.delay

eventGuards ​

Get Signature ​

get eventGuards(): Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>

Defined in: interface.ts:868

Returns ​

Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>

Implementation of ​

State.eventGuards

eventReactions ​

Get Signature ​

get eventReactions(): EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>

Defined in: interface.ts:874

Returns ​

EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>

Implementation of ​

State.eventReactions

guards ​

Get Signature ​

get guards(): Guard<Context>

Defined in: interface.ts:864

Returns ​

Guard<Context>

Implementation of ​

State.guards

handlingEvents ​

Get Signature ​

get handlingEvents(): keyof EventPayloadMapping[]

Defined in: interface.ts:858

Returns ​

keyof EventPayloadMapping[]

Methods ​

beforeExit() ​

beforeExit(context, stateMachine, to): void

Defined in: interface.ts:902

Parameters ​

context ​

Context

stateMachine ​

StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

to ​

"TERMINAL" | States

Returns ​

void

Implementation of ​

State.beforeExit

handles() ​

handles<K>(args, context, stateMachine): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K<K>] : void>

Defined in: interface.ts:915

Type Parameters ​

K ​

K extends string | number | symbol

Parameters ​

args ​

EventArgs<EventPayloadMapping, K>

context ​

Context

stateMachine ​

StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

Returns ​

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

Implementation of ​

State.handles

uponEnter() ​

uponEnter(context, stateMachine, from): void

Defined in: interface.ts:889

Parameters ​

context ​

Context

stateMachine ​

StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

from ​

"INITIAL" | States

Returns ​

void

Implementation of ​

State.uponEnter