ihsm 0.0.13 → 0.0.19

package/README.md

@@ -1,9 +1,193 @@
-```ts
-/*             (_) | |__    ___   _ __ ___                    */ 
-/*             | | | '_ \  / __| | '_ ` _ \                   */
-/*             | | | | | | \__ \ | | | | | |                  */
-/*             |_| |_| |_| |___/ |_| |_| |_|                  */
+[![CI](https://img.shields.io/github/actions/workflow/status/filasieno/ihsm/ci.yml?label=CI)](https://github.com/filasieno/ihsm/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/github/actions/workflow/status/filasieno/ihsm/docs.yml?label=docs)](https://github.com/filasieno/ihsm/actions/workflows/docs.yml)
+[![Coverage](https://img.shields.io/coverallsCoverage/github/filasieno/ihsm)](https://coveralls.io/github/filasieno/ihsm)
+[![License: MIT](https://img.shields.io/github/license/filasieno/ihsm)](https://github.com/filasieno/ihsm/blob/HEAD/LICENSE)
+[![npm version](https://img.shields.io/npm/v/ihsm)](https://www.npmjs.com/package/ihsm)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js)](https://github.com/filasieno/ihsm/blob/HEAD/package.json)
+
+# ihsm
+
+An idiomatic hierarchical state machine package for TypeScript — **Samek/QP-style** class hierarchy with
+**cached LCA transitions**, **zero production dependencies**, and **100% code coverage** on the runtime.
+
+## Quality
+
+| Metric | Value |
+|--------|-------|
+| **Statements** | 100% |
+| **Branches** | 100% |
+| **Functions** | 100% |
+| **Lines** | 100% |
+
+CI enforces full coverage on every push (`nix flake check`).
+
+## Features
+
+- User-defined event payloads (typed `Protocol`)
+- User-defined state context (`ctx`)
+- Hierarchically nested states (class inheritance)
+- Orthogonal regions (nest multiple machines; compose via `post`/`call`)
+- Internal transitions (handle event without calling `transition()`)
+- Explicit transitions with cached entry/exit sequences
+- Guards (inline `if` in handlers)
+- History (`ctx` + `restore()`)
+- Entry / exit actions (`onEntry`, `onExit`)
+- Async and sync handlers
+- **`call()` — typed request/response through the actor mailbox** (unique)
+- **`then()` — decision pseudo-states with automatic follow-up transitions**
+- **`postNow()` — hi-priority extended transitions within the same dispatch**
+- Actor-style messaging (`post`, `deferredPost`, serialized queue)
+- Structured errors and trace levels
+
+## Documentation
+
+| Resource | Link |
+|----------|------|
+| **Documentation site** | [filasieno.github.io/ihsm](https://filasieno.github.io/ihsm/) — reference manual + interactive tutorials |
+| Reference (source) | [reference/REFERENCE.md](./reference/REFERENCE.md) |
+| Tutorials (source) | [tutorials/](./tutorials/) |
+| Examples | [`src/spec/`](./src/spec/) |
+| Code of conduct | [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) |
+| Security | [SECURITY.md](./SECURITY.md) |
+
+Each tutorial page on the documentation site combines prose, code samples, and an embedded playground
+(sender/message forms, live trace, reset). The same machines are verified headlessly by Mocha specs under
+`tutorials/*/tutorial.spec.ts`.
+
+## Install
+
+```shell
+npm install ihsm@latest
+```
+
+### Runtime support
+
+ihsm ships modern **ES2022** ESM and CommonJS — no transpiled legacy (ES5/ES2015)
+output and no polyfills. Supported runtimes:
+
+| Runtime | Minimum |
+| ------- | ------- |
+| Node.js | **22+** |
+| Chrome / Edge | **94+** |
+| Firefox | **93+** |
+| Safari (macOS / iOS) | **15.4+** |
+
+Older browsers and JavaScript engines are intentionally **not** supported. If you
+must target them, transpile `ihsm` yourself with your bundler (the published
+`browserslist` field declares this baseline for downstream tooling).
+
+## Requirements
+
+**[Nix](https://nixos.org/download/)** with flakes enabled — the only prerequisite to build and test
+from source.
+
+## Building
+
+```shell
+git clone https://github.com/filasieno/ihsm.git
+cd ihsm
+```
+
+### Development environment
+
+**Always use the Nix dev shell** before running npm scripts. It provides Node 22,
+PlantUML, Graphviz, and a store-pinned `node_modules` symlink (same lockfile as CI).
+
+```shell
+nix develop
+# or: direnv allow    # .envrc → use flake; auto-enters the shell in supported terminals
+```
+
+Run npm commands **inside** that shell, or prefix each one with `nix develop --command`:
+
+```shell
+nix develop --command npm test
 ```
 
-# Idiomatic hierarchical state machine
+If you see `remove local node_modules/ to use Nix store deps`, delete a plain
+`npm install` tree: `rm -rf node_modules` and enter `nix develop` again.
+
+### Nix commands (CI parity)
+
+| Command | Purpose |
+| ------- | ------- |
+| `nix flake check` | Full CI gate: library compile, unit + tutorial tests, lint, docs site |
+| `nix build` | Compile library and run tests → `result/lib/` |
+| `nix build .#lint` | TypeScript (full solution), ESLint, Prettier |
+| `nix build .#docs` | Production documentation site → `result/share/doc/ihsm/` |
+
+Full check before opening a PR:
+
+```shell
+nix flake check
+```
+
+After `nix build .#docs`, copy artifacts from `result/share/doc/ihsm/` or run
+`bash scripts/verify-docs-site.sh result/share/doc/ihsm`.
+
+### npm scripts
+
+All commands below assume **`nix develop`** (interactive shell) or
+**`nix develop --command …`** (one-shot). See [website/README.md](./website/README.md)
+for docs-site layout and generated output.
+
+#### Build
+
+| Command | Purpose |
+| ------- | ------- |
+| `npm run build` | Compile the publishable library → `lib/cjs/` (CommonJS) and `lib/esm/` (ESM), then finalize |
+| `npm run build-cjs` | Compile the CommonJS tree only → `lib/cjs/` |
+| `npm run build-esm` | Compile the ESM tree only → `lib/esm/` |
+| `npm run clean` | Remove generated artifacts (`lib/`, `.tsc/`, coverage, `docs-build/`, `website/docs/`, …) |
+| `npm run dist` | Clean, then build library and documentation site (maintainer bundle) |
+
+#### Test
+
+| Command | Purpose |
+| ------- | ------- |
+| `npm test` | Unit tests in Node (`src/spec/`) with NYC coverage, then the same specs minified in headless Chromium |
+| `npm run test:node` | Node-only unit tests (with coverage) |
+| `npm run test:browser` | Minified browser bundles for unit + tutorial specs (Playwright + esbuild) |
+| `npm run test:tutorials` | Tutorial specs in Node, then minified in the browser |
+| `npm run test:all` | `npm test` + `npm run test:tutorials` (both environments) |
+| `npm run coverage` | Print an LCOV coverage report from the last `npm run test:node` run |
+
+First-time browser setup: `npx playwright install chromium`.
+
+#### Quality
+
+| Command | Purpose |
+| ------- | ------- |
+| `npm run typecheck` | Type-check the full project graph (CJS lib, ESM lib, tutorials, website); runs `sync:docs` first |
+| `npm run lint` | Typecheck, then ESLint and Prettier check |
+| `npm run prettier` | Auto-format TypeScript sources (`src/`, `tutorials/`, `website/`) |
+| `npm run verify:source` | Fail if generated output (compiled `.js`/`.d.ts`, docs) appears in the source tree |
+| `npm run release:check` | Local release gate: `test:all`, lint, build, doc, and `verify:doc` |
+
+#### Documentation
+
+| Command | Purpose |
+| ------- | ------- |
+| `npm run sync:docs` | Generate gitignored site inputs: `website/docs/`, `website/sidebars.ts`, PlantUML SVGs |
+| `npm run doc` | `sync:docs`, then production Docusaurus build (website workspace) |
+| `npm run doc:preview` | `sync:docs`, then Docusaurus dev server at [localhost:3010/ihsm/](http://localhost:3010/ihsm/) |
+| `npm run doc:site` | `sync:docs`, then static site → `docs-build/` |
+| `npm run verify:doc` | Sanity-check `docs-build/` (links, assets, tutorial pages) |
+
+Release process: [RELEASING.md](./RELEASING.md).
+
+## Contributing
+
+Contributions are welcome — bug reports, docs, and code.
+
+- Bug reports → [issue template](https://github.com/filasieno/ihsm/issues/new?template=bug_report.yml)
+- Features → [issue template](https://github.com/filasieno/ihsm/issues/new?template=feature_request.yml)
+- Security → [GitHub Security Advisories](https://github.com/filasieno/ihsm/security/advisories/new) (not public issues)
+
+Please follow [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). New behavior needs tests in `src/spec/`; tutorial changes need matching specs under `tutorials/`.
+
+**Generated output is never committed** — only sources (`src/`, `tutorials/`, `reference/`, `website/docs-src/`). CI runs `scripts/verify-no-generated-in-source.sh`. Build artifacts (`lib/`, `website/docs/`, `docs-build/`, …) are gitignored and produced by Nix/npm.
+
+## License
 
+[MIT](./LICENSE) © Fabio N. Filasieno, Roberto Boati

package/lib/cjs/index.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Default context and protocol map when a machine is created without explicit typing.
+ * @category Factory
+ */
+export type Any = Record<string, any>;
+/**
+ * Rejects an async {@link Hsm.call} service with an error.
+ * @category Event handler
+ */
+export type RejectCallback = (error: Error) => void;
+/**
+ * Resolves an async {@link Hsm.call} service with a typed reply.
+ * @category Event handler
+ */
+export type ResolveCallback<Reply> = (result: Reply) => void;
+/**
+ * Called when event dispatch fails and the runtime does not recover via `onError`.
+ * @category Factory
+ */
+export interface DispatchErrorCallback<Context, Protocol extends {} | undefined> {
+    (hsm: Base<Context, Protocol>, err: Error): void;
+}
+/**
+ * Trace verbosity for dispatch logging.
+ * @category Factory
+ */
+export declare enum TraceLevel {
+    PRODUCTION = 0,
+    DEBUG = 1,
+    VERBOSE_DEBUG = 2
+}
+/**
+ * Receives trace lines from the runtime and from handlers via `this.traceWriter.write`.
+ * @category Factory
+ */
+export interface TraceWriter {
+    write<Context, Protocol extends {} | undefined>(hsm: Properties<Context, Protocol>, msg: any): void;
+}
+/**
+ * @category State machine
+ */
+export interface Properties<Context, Protocol extends {} | undefined> {
+    readonly currentState: StateClass<Context, Protocol>;
+    readonly currentStateName: string;
+    readonly topState: StateClass<Context, Protocol>;
+    readonly topStateName: string;
+    readonly ctxTypeName: string;
+    readonly traceHeader: string;
+    readonly eventName: string;
+    readonly eventPayload: any[];
+    traceLevel: TraceLevel;
+    traceWriter: TraceWriter;
+    dispatchErrorCallback: DispatchErrorCallback<Context, Protocol>;
+}
+/**
+ * @category State machine
+ */
+export interface Base<Context, Protocol extends {} | undefined> extends Properties<Context, Protocol> {
+    post<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+    deferredPost<EventName extends keyof Protocol>(millis: number, eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+}
+/**
+ * @category State machine
+ */
+export interface State<Context, Protocol extends {} | undefined> extends Base<Context, Protocol> {
+    readonly ctx: Context;
+    transition(nextState: StateClass<Context, Protocol>): void;
+    unhandled(): never;
+    sleep(millis: number): Promise<void>;
+    /** Handler-only: queue an event on the internal high-priority mailbox (before normal `post`). */
+    postNow<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+}
+/**
+ * Actor handle returned by {@link makeHsm} — client API (`post`, `call`, `sync`, `restore`).
+ * @category State machine
+ */
+export interface Hsm<Context = Any, Protocol extends {} | undefined = undefined> extends Base<Context, Protocol> {
+    readonly ctx: Context;
+    sync(): Promise<void>;
+    restore(state: StateClass<Context, Protocol>, ctx: Context): void;
+    call<EventName extends keyof Protocol>(eventName: ServiceName<Protocol, EventName>, ...eventPayload: ServiceRequest<Protocol, EventName>): Promise<ServiceResponse<Protocol, EventName>>;
+}
+/**
+ * @category Event handler
+ */
+export type PostedEvent<Protocol extends {} | undefined, EventName extends keyof Protocol> = Protocol extends undefined ? string : EventName extends keyof State<any, any> ? never : EventName;
+/**
+ * @category Event handler
+ */
+export type EventPayload<Protocol extends {} | undefined, EventName extends keyof Protocol> = Protocol extends undefined ? any[] : Protocol[EventName] extends (...payload: infer Payload) => Promise<void> | void ? (Payload extends any[] ? Payload : never) : never;
+/**
+ * Constructor type for a state class in the machine hierarchy.
+ * @category State machine
+ */
+export type StateClass<Context = Any, Protocol extends {} | undefined = undefined> = Function & {
+    prototype: TopState<Context, Protocol>;
+};
+/**
+ *
+ */
+export type ServiceRequest<Protocol, EventName extends keyof Protocol> = Protocol extends undefined ? any[] : Protocol[EventName] extends (resolve: (result: infer Reply) => void, reject: (error: infer Error) => void, ...payload: infer Payload) => Promise<void> | void ? (Payload extends any[] ? Payload : never) : never;
+/**
+ *
+ */
+export type ServiceResponse<Protocol, EventName extends keyof Protocol> = Protocol extends undefined ? any : Protocol[EventName] extends (resolve: infer Reply, reject: infer Error, ...payload: infer Payload) => Promise<void> | void ? Reply : never;
+/**
+ *
+ */
+export type ServiceName<Protocol, EventName> = Protocol extends undefined ? string : EventName extends keyof State<any, any> ? never : EventName;
+/**
+ * Optional lifecycle hooks implemented by state classes (`onEntry`, `onExit`, …).
+ * @category State machine
+ */
+export interface StateEvents<Context, Protocol extends {} | undefined> {
+    onExit(): Promise<void> | void;
+    onEntry(): Promise<void> | void;
+    onError<EventName extends keyof Protocol>(error: RuntimeError<Context, Protocol, EventName>): Promise<void> | void;
+    onUnhandled<EventName extends keyof Protocol>(error: UnhandledEventError<Context, Protocol, EventName>): Promise<void> | void;
+}
+/**
+ * Root of the state class hierarchy; hosts mailbox machinery. Subclass or pass to {@link makeHsm}.
+ * @category State machine
+ */
+export declare abstract class TopState<Context = Any, Protocol extends {} | undefined = undefined> implements State<Context, Protocol>, StateEvents<Context, Protocol> {
+    readonly ctx: Context;
+    readonly hsm: State<Context, Protocol>;
+    constructor();
+    get eventName(): string;
+    get eventPayload(): any[];
+    get traceHeader(): string;
+    get topState(): StateClass<Context, Protocol>;
+    get currentStateName(): string;
+    get currentState(): StateClass<Context, Protocol>;
+    get ctxTypeName(): string;
+    set traceLevel(value: TraceLevel);
+    get traceLevel(): TraceLevel;
+    get topStateName(): string;
+    get traceWriter(): TraceWriter;
+    set traceWriter(value: TraceWriter);
+    get dispatchErrorCallback(): DispatchErrorCallback<Context, Protocol>;
+    set dispatchErrorCallback(value: DispatchErrorCallback<Context, Protocol>);
+    transition(nextState: StateClass<Context, Protocol>): void;
+    unhandled(): never;
+    sleep(millis: number): Promise<void>;
+    post<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+    deferredPost<EventName extends keyof Protocol>(millis: number, eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+    postNow<EventName extends keyof Protocol>(eventName: PostedEvent<Protocol, EventName>, ...eventPayload: EventPayload<Protocol, EventName>): void;
+    onExit(): Promise<void> | void;
+    onEntry(): Promise<void> | void;
+    onError<EventName extends keyof Protocol>(error: RuntimeError<Context, Protocol, EventName>): Promise<void> | void;
+    onUnhandled<EventName extends keyof Protocol>(error: UnhandledEventError<Context, Protocol, EventName>): Promise<void> | void;
+}
+/**
+ * @category Error
+ */
+export declare abstract class HsmError<Context, Protocol extends {} | undefined> extends Error {
+    name: string;
+    topStateName: string;
+    stateName: string;
+    context: Context;
+    cause?: Error;
+    protected constructor(name: string, hsm: State<Context, Protocol>, message: string, cause?: Error);
+}
+/**
+ * @category Error
+ */
+export declare abstract class RuntimeError<Context, Protocol extends {} | undefined, EventName extends keyof Protocol> extends HsmError<Context, Protocol> {
+    eventName: PostedEvent<Protocol, EventName>;
+    eventPayload: EventPayload<Protocol, EventName>;
+    protected constructor(errorName: string, hsm: State<Context, Protocol>, message: string, cause?: Error);
+}
+/**
+ * @category Error
+ */
+export declare class TransitionError<Context, Protocol extends {} | undefined, EventName extends keyof Protocol> extends RuntimeError<Context, Protocol, EventName> {
+    failedStateName: string;
+    failedCallback: 'onExit' | 'onEntry';
+    fromStateName: string;
+    toStateName: string;
+    constructor(hsm: State<Context, Protocol>, cause: Error, failedStateName: string, failedCallback: 'onExit' | 'onEntry', fromStateName: string, toStateName: string);
+}
+/**
+ * @category Error
+ */
+export declare class EventHandlerError<Context, Protocol extends {} | undefined, EventName extends keyof Protocol> extends RuntimeError<Context, Protocol, EventName> {
+    constructor(hsm: State<Context, Protocol>, cause: Error);
+}
+/**
+ * @category Error
+ */
+export declare class UnhandledEventError<Context, Protocol extends {} | undefined, EventName extends keyof Protocol> extends RuntimeError<Context, Protocol, EventName> {
+    constructor(hsm: State<Context, Protocol>);
+}
+/**
+ * @category Error
+ */
+export declare class InitialStateError<Context, Protocol extends {} | undefined> extends Error {
+    targetStateName: string;
+    constructor(targetState: StateClass<Context, Protocol>);
+}
+/**
+ * @category Error
+ */
+export declare class FatalError<Context, Protocol extends {} | undefined, EventName extends keyof Protocol> extends RuntimeError<Context, Protocol, EventName> {
+    constructor(hsm: State<Context, Protocol>, cause: Error);
+}
+/**
+ * @category Error
+ */
+export declare class InitializationError<Context, Protocol extends {} | undefined> extends HsmError<Context, Protocol> {
+    failedState: StateClass<Context, Protocol>;
+    constructor(hsm: State<Context, Protocol>, failedState: StateClass<Context, Protocol>, cause: Error);
+}
+/**
+ * Terminal error state class used when the machine cannot recover.
+ * @category State machine
+ */
+export declare class FatalErrorState<Context, Protocol extends {} | undefined> extends TopState<Context, Protocol> {
+}
+/**
+ * Marks `TargetState` as the initial substate of its parent composite state.
+ * @category Factory
+ */
+export declare function InitialState<Context, Protocol extends {} | undefined>(TargetState: StateClass<Context, Protocol>): void;
+/**
+ * Assigns a stable display name to a state class.
+ *
+ * Minifiers (and browser production bundles) rewrite class names, so the
+ * built-in `Class.name` is unreliable in optimized builds. Registering an
+ * explicit name keeps {@link Properties.currentStateName},
+ * {@link Properties.topStateName}, trace output, and error messages stable in
+ * every environment (Node and minified browsers alike).
+ *
+ * The name is stored as a non-enumerable, non-inherited own property, so it is
+ * never accidentally shared with subclasses through the prototype chain.
+ *
+ * @example
+ * ```ts
+ * class Door extends TopState {}
+ * defineStateName(Door, 'Door');
+ * ```
+ * @category State machine
+ */
+export declare function defineStateName<Context, Protocol extends {} | undefined>(state: StateClass<Context, Protocol>, name: string): void;
+/**
+ * Registers stable display names for every state class found in an exports map,
+ * using the export key as the display name.
+ *
+ * This is the convenient way to make a whole machine module minification-safe:
+ * pass the module namespace (or an object literal of the state classes) and
+ * each state class gets its export key as its display name. Non state-class
+ * values (factory functions, interfaces compiled away, constants) are ignored.
+ *
+ * @example
+ * ```ts
+ * // machine.ts
+ * export class DoorTop extends TopState {}
+ * export class Open extends DoorTop {}
+ * export class Closed extends DoorTop {}
+ * registerStateNames({ DoorTop, Open, Closed });
+ * ```
+ * @example
+ * ```ts
+ * // from another module
+ * import * as machine from './machine';
+ * registerStateNames(machine);
+ * ```
+ * @category State machine
+ */
+export declare function registerStateNames(exports: Record<string, unknown>): void;
+/**
+ * Creates a state machine instance bound to the given context object.
+ *
+ * @param topState - Root state class
+ * @param ctx - Mutable domain context
+ * @param initialize - When `true`, walk `@InitialState` chain and run `onEntry` on the path to the initial leaf (default `true`)
+ * @param traceLevel - Trace verbosity (default {@link TraceLevel.DEBUG})
+ * @param traceWriter - Trace sink (default console logger)
+ * @param dispatchErrorCallback - Hook when dispatch throws and is not recovered (default: log and rethrow)
+ * @category Factory
+ */
+export declare function makeHsm<Context, Protocol extends undefined | {}>(topState: StateClass<Context, Protocol>, ctx: Context, initialize?: boolean, traceLevel?: TraceLevel, traceWriter?: TraceWriter, dispatchErrorCallback?: DispatchErrorCallback<Context, Protocol>): Hsm<Context, Protocol>;