Skip to main content

Base

Fire-and-forget event posting API available on both Hsm (clients) and State (handlers).

Events enqueue on the machine mailbox and run one at a time — no re-entrancy while a handler is active.

Extends​

Extended by​

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​

Properties.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​

Properties.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​

Properties.topState

topStateName​

readonly topStateName: string

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

Inherited from​

Properties.topStateName

ctxTypeName​

readonly ctxTypeName: string

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

Inherited from​

Properties.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​

Properties.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​

Properties.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​

Properties.eventPayload

traceLevel​

traceLevel: TraceLevel

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

See​

TraceLevel

Inherited from​

Properties.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​

Properties.traceWriter

dispatchErrorCallback​

dispatchErrorCallback: DispatchErrorCallback<Context, Protocol>

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

See​

DispatchErrorCallback

Inherited from​

Properties.dispatchErrorCallback

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
}

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