Skip to main content

State

Handler-facing API available inside state class methods (this / this.hsm).

Extends Base with context access, transitions, async sleep, explicit unhandled signaling, and postNow hi-priority re-dispatch. Only code running inside an active handler should call transition, unhandled, or postNow.

Extends​

  • Base<Context, Protocol>

Type Parameters​

Context​

Context

Protocol​

Protocol extends { } | undefined

Properties​

currentState​

readonly currentState: StateClass<Context, Protocol>

Constructor (Function) of the leaf state class currently executing.

Compare with topState, which is always the root composite passed to makeHsm. After a transition, this updates to the new leaf's constructor.

Inherited from​

Base.currentState

currentStateName​

readonly currentStateName: string

Human-readable name of currentState.

Sourced from defineStateName / registerStateNames when registered; otherwise Class.name (unreliable under minification — register names in browser builds).

Inherited from​

Base.currentStateName

topState​

readonly topState: StateClass<Context, Protocol>

Constructor of the root state class supplied to makeHsm.

Constant for the lifetime of the instance unless you replace the entire machine.

Inherited from​

Base.topState

topStateName​

readonly topStateName: string

Display name of topState (same naming rules as currentStateName).

Inherited from​

Base.topStateName

ctxTypeName​

readonly ctxTypeName: string

Runtime label derived from ctx constructor name, used as the first segment of traceHeader in verbose traces.

Inherited from​

Base.ctxTypeName

traceHeader​

readonly traceHeader: string

Prefix for nested trace domains, built from internal dispatch stack frames.

Empty at the top level; grows like domain|subdomain| during nested operations. Handlers rarely need to read this directly — it is prepended automatically by the default TraceWriter.

Inherited from​

Base.traceHeader

eventName​

readonly eventName: string

Name of the event or service currently being dispatched.

Matches the string passed to Base.post, Hsm.call, or State.postNow. Empty string when no handler is running.

Inherited from​

Base.eventName

eventPayload​

readonly eventPayload: any[]

Arguments passed with the current dispatch, excluding injected resolve / reject for Hsm.call services.

Empty array when idle. Typed as any[] at runtime; correlate with EventPayload / ServiceRequest at compile time on the client.

Inherited from​

Base.eventPayload

traceLevel​

traceLevel: TraceLevel

Active trace verbosity; changing this swaps dispatch tracing behavior immediately.

See​

TraceLevel

Inherited from​

Base.traceLevel

traceWriter​

traceWriter: TraceWriter

Destination for runtime and handler-initiated trace lines.

Replaceable at any time (e.g. swap in a test double before post/call).

Inherited from​

Base.traceWriter

dispatchErrorCallback​

dispatchErrorCallback: DispatchErrorCallback<Context, Protocol>

Last-resort error hook when StateEvents.onError / StateEvents.onUnhandled do not recover.

See​

DispatchErrorCallback

Inherited from​

Base.dispatchErrorCallback

ctx​

readonly ctx: Context

Mutable domain data object shared across all states of this machine instance.

Passed as the second argument to makeHsm; survives transitions unless replaced by Hsm.restore. Update fields freely for internal transitions (no transition()).

Remarks​

Context is not the active state name — state is which class prototype is active; context is arbitrary application data (counters, buffers, IDs, flags).

Methods​

post()​

post<EventName>(eventName, ...eventPayload): void

Enqueue a normal-priority event for later dispatch on the active state.

Returns immediately; the handler runs asynchronously when the mailbox reaches this job. Dispatch walks the prototype chain from the current leaf upward until a method named eventName is found.

Type Parameters​

EventName​

EventName extends string | number | symbol

Literal key of Protocol being posted

Parameters​

eventName​

PostedEvent<Protocol, EventName>

Event or service name. Must be keyof Protocol and must not collide with reserved State method names (transition, post, ctx, …)

eventPayload​

...EventPayload<Protocol, EventName>

Arguments tuple inferred from Protocol[eventName] handler parameters. For events, pass every parameter except resolve / reject. For fire-and-forget events, the handler return type must be void or Promise<void>

Returns​

void

Remarks​

Client usage: door.post('open') then await door.sync() to wait for completion.

Handler usage: this.post('tick') schedules work after the current handler returns and after any State.transition it requested. Normal-priority posts run after all State.postNow hi-priority jobs drained for the current turn.

Ordering: FIFO among normal-priority jobs. Multiple posts before one sync() are processed in submission order.

Typing: With Protocol extends undefined, accepts any string and any[] (legacy mode).

Examples​

door.post('open');
await door.sync(); // handler + transition complete
approve(): void {
  this.ctx.approved = true;
  this.post('notify'); // runs after this handler finishes
}

Inherited from​

Base.post

deferredPost()​

deferredPost<EventName>(millis, eventName, ...eventPayload): void

Schedule a normal-priority post after a wall-clock delay.

Uses setTimeout internally; when the timer fires, the event is enqueued like an ordinary post. Timers are not cancelled if the machine transitions or the scheduling handler throws.

Type Parameters​

EventName​

EventName extends string | number | symbol

Literal key of Protocol being scheduled

Parameters​

millis​

number

Delay in milliseconds before enqueueing (≥ 0). Subject to event-loop timer granularity

eventName​

PostedEvent<Protocol, EventName>

Event name (same constraints as post)

eventPayload​

...EventPayload<Protocol, EventName>

Handler arguments tuple (same as post)

Returns​

void

Remarks​

Available on State and Hsm. Typical pattern: handler schedules reminder, client waits with await sleep(millis); await hsm.sync().

Does not block the calling handler — returns as soon as the timer is registered.

Example​

scheduleReminder(text: string): void {
  this.deferredPost(50, 'deliver', text);
}
deliver(text: string): void {
  this.ctx.message = text;
}

Inherited from​

Base.deferredPost

transition()​

transition(nextState): void

Schedule an external transition to nextState after the current handler completes.

Does not run exit/entry immediately. When the handler returns successfully (including after awaiting an async handler's Promise), the runtime:

  1. Computes the lowest common ancestor (LCA) on the class prototype chain
  2. Runs onExit() from the current leaf up to (but not including) the LCA
  3. Switches the instance prototype to nextState (descending @InitialState chains for composites)
  4. Runs onEntry() down from the LCA to the target leaf

Parameters​

nextState​

StateClass<Context, Protocol>

Destination state class constructor (not an instance)

Returns​

void

Throws​

TransitionError when onExit or onEntry throws along the path (may transition to FatalErrorState)

Throws​

EventHandlerError when the triggering handler threw before transition phase

Remarks​

  • Self-transition to the same leaf with unchanged initial descent: optimized to skip exit/entry
  • Internal transition: omit transition() — active class unchanged, no exit/entry
  • transition() inside onEntry/onExit: scheduled transition is cleared when that lifecycle dispatch ends — use post from onEntry for follow-up work
  • Transition paths are cached per From=>To pair for hot loops
  • Only the last transition() call wins if invoked multiple times in one handler

Example​

open(): void {
  this.ctx.openCount += 1;
  this.transition(Open);
}

unhandled()​

unhandled(): never

Declare that the current event has no handler on this state (explicit super-call pattern).

Throws UnhandledEventError unless an ancestor's StateEvents.onUnhandled catches it. Prefer omitting the method entirely when a state should inherit a parent's handler — only call unhandled() when you intentionally defer to the error model.

Returns​

never

never — always throws or redirects via onUnhandled

Throws​

UnhandledEventError by default

Remarks​

Runtime dispatch already throws when no method exists on the prototype chain; unhandled() is for handlers that exist but choose not to handle the event.

sleep()​

sleep(millis): Promise<void>

Pause the current handler without blocking the JavaScript event loop.

Returns a Promise resolved after millis milliseconds via setTimeout. The mailbox remains locked to this handler until the Promise settles — other post/call jobs queue but do not run.

Parameters​

millis​

number

Sleep duration in milliseconds (≥ 0)

Returns​

Promise<void>

Promise that resolves (never rejects) when the delay elapses

Remarks​

Use for simple delays inside handlers. For calendar-time deferral of new events, prefer deferredPost. Composable with async handlers: await this.sleep(100).

Example​

async pulse(): Promise<void> {
  await this.sleep(50);
  this.ctx.pulses += 1;
}

postNow()​

postNow<EventName>(eventName, ...eventPayload): void

Enqueue a hi-priority event processed before normal post jobs from the same turn.

Only valid inside a running handler (this.postNow). Clients must use post. Hi-priority jobs drain immediately after the current handler and its transition complete, before any normal-priority posts the handler enqueued (including chained this.post).

Type Parameters​

EventName​

EventName extends string | number | symbol

Literal key of Protocol

Parameters​

eventName​

PostedEvent<Protocol, EventName>

Event name (same typing rules as post)

eventPayload​

...EventPayload<Protocol, EventName>

Handler arguments (same tuple as post)

Returns​

void

Remarks​

Models extended transitions: multiple internal steps (lock, capture, validate) that must complete before deferred side effects. See tutorial 17-post-now.

Multiple postNow calls run in FIFO order within the hi-priority queue. You may need an extra Hsm.sync after the first to drain postNow follow-ups.

Example​

confirm(): void {
  this.post('cancel');           // normal — runs last
  this.postNow('lockInventory'); // hi — runs first among follow-ups
  this.postNow('capturePayment');
  this.transition(Confirmed);
}