@ue-too/being / index / TemplateState

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

Defined in: interface.ts:973

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

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

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

• TemplateStateMachine for the state machine implementation
• EventReactions for defining event handlers

Extended by

• DelegatingState

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

---

_delay

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

Defined in: interface.ts:1003

---

_eventGuards

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

Defined in: interface.ts:993

---

_eventPreconditions

protected _eventPreconditions: Partial<EventPreconditions<EventPayloadMapping, Context, Guard<Context>>>

Defined in: interface.ts:998

---

_eventReactions

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

Defined in: interface.ts:981

---

_guards

protected _guards: Guard<Context>

Defined in: interface.ts:992

Accessors

delay

Get Signature

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

Defined in: interface.ts:1042

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

Returns

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

Implementation of

State.eventGuards

---

eventPreconditions

Get Signature

get eventPreconditions(): Partial<EventPreconditions<EventPayloadMapping, Context, Guard<Context>>>

Defined in: interface.ts:1027

Pre-action vetoes: named guards that must all pass before this state handles an event. Optional so existing State implementations remain valid; TemplateState always provides it.

Returns

Partial<EventPreconditions<EventPayloadMapping, Context, Guard<Context>>>

Pre-action vetoes: named guards that must all pass before this state handles an event. Optional so existing State implementations remain valid; TemplateState always provides it.

Implementation of

State.eventPreconditions

---

eventReactions

Get Signature

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

Defined in: interface.ts:1033

Returns

EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>

Implementation of

State.eventReactions

---

guards

Get Signature

get guards(): Guard<Context>

Defined in: interface.ts:1017

Returns

Guard<Context>

Implementation of

State.guards

---

handlingEvents

Get Signature

get handlingEvents(): keyof EventPayloadMapping[]

Defined in: interface.ts:1011

Returns

keyof EventPayloadMapping[]

Methods

beforeExit()

beforeExit(context, stateMachine, to): void

Defined in: interface.ts:1061

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

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

Parameters

context

Context

stateMachine

StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

from

"INITIAL" | States

Returns

void

Implementation of

State.uponEnter