@ue-too/being / index / TemplateStateMachine

類別: TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

定義於: interface.ts:665

Concrete implementation of a finite state machine.

備註

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

範例

Basic vending machine state machine

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" });

參閱

• TemplateState for creating state implementations
• StateMachine for the interface definition

Extended by

• HierarchicalStateMachine

型別參數

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

實作

• StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

建構函式

建構函式

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

定義於: interface.ts:701

參數

states

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

initialState

States

context

Context

autoStart

boolean = true

回傳

TemplateStateMachine<EventPayloadMapping, Context, States, EventOutputMapping>

屬性

_context

protected _context: Context

定義於: interface.ts:683

---

_currentState

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

定義於: interface.ts:678

---

_eventResultCallbacks

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

定義於: interface.ts:693

---

_happensCallbacks

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

定義於: interface.ts:686

參數

args

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

context

Context

回傳

void

---

_initialState

protected _initialState: States

定義於: interface.ts:699

---

_stateChangeCallbacks

protected _stateChangeCallbacks: StateChangeCallback<States>[]

定義於: interface.ts:685

---

_states

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

定義於: interface.ts:679

---

_statesArray

protected _statesArray: States[]

定義於: interface.ts:684

---

_timeouts

protected _timeouts: number | undefined = undefined

定義於: interface.ts:698

存取器

context

Getter 簽章

get context(): Context

定義於: 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.

回傳

Context

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.

實作了

StateMachine.context

---

currentState

Getter 簽章

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

定義於: interface.ts:866

回傳

"INITIAL" | "TERMINAL" | States

實作了

StateMachine.currentState

---

possibleStates

Getter 簽章

get possibleStates(): States[]

定義於: interface.ts:878

回傳

States[]

實作了

StateMachine.possibleStates

---

states

Getter 簽章

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

定義於: interface.ts:882

回傳

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

實作了

StateMachine.states

方法

happens()

呼叫簽章

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

定義於: interface.ts:763

型別參數

K

K extends string | number | symbol

參數

args

...EventArgs<EventPayloadMapping, K>

回傳

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

實作了

StateMachine.happens

呼叫簽章

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

定義於: interface.ts:769

型別參數

K

K extends string

參數

args

...EventArgs<EventPayloadMapping, K>

回傳

EventResult<States, unknown>

實作了

StateMachine.happens

---

onEventResult()

onEventResult(callback): () => void

定義於: 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.

參數

callback

EventResultCallback<EventPayloadMapping, Context, States>

回傳

(): void

回傳

void

實作了

StateMachine.onEventResult

---

onHappens()

onHappens(callback): () => void

定義於: 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.

參數

callback

(args, context) => void

回傳

(): void

回傳

void

實作了

StateMachine.onHappens

---

onStateChange()

onStateChange(callback): () => void

定義於: 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.

參數

callback

StateChangeCallback<States>

回傳

(): void

回傳

void

實作了

StateMachine.onStateChange

---

reset()

reset(): void

定義於: interface.ts:723

回傳

void

實作了

StateMachine.reset

---

setContext()

setContext(context): void

定義於: interface.ts:870

參數

context

Context

回傳

void

實作了

StateMachine.setContext

---

start()

start(): void

定義於: interface.ts:729

回傳

void

實作了

StateMachine.start

---

switchTo()

switchTo(state): void

定義於: interface.ts:758

參數

state

"INITIAL" | "TERMINAL" | States

回傳

void

實作了

StateMachine.switchTo

---

wrapup()

wrapup(): void

定義於: interface.ts:742

回傳

void

實作了

StateMachine.wrapup