ihsm 0.0.19 → 0.0.20

package/README.md

@@ -1,192 +1,333 @@
 [![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
+**Class-based hierarchical state machines and actor mailboxes for TypeScript** — typed `post`/`call`, **zero** production dependencies, **~4.6 KB gzip** in the browser. → [Documentation](https://filasieno.github.io/ihsm/)
 
-## Documentation
+ihsm is state management and orchestration for backends, session actors, protocol handlers, and embedded tooling: states are **classes**, events are **methods**, hierarchy is **inheritance**, and each machine is an **actor** with a serialized mailbox and run-to-completion dispatch.
 
-| 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`.
+Requires **Node.js 22+** (or a modern browser). Class names in traces and errors come from `Class.name` — no extra registration step in a typical npm/Node project.
 
-## Install
+It uses event-driven programming, class-based hierarchical statecharts, and the actor model to handle complex logic in predictable, robust ways. States are **classes**, events are **methods**, hierarchy is **inheritance**, and each machine is an **actor** with a serialized mailbox with RTC guarantees.
+
+---
+
+📖 [Read the documentation](https://filasieno.github.io/ihsm/)
+
+📑 [API reference](https://filasieno.github.io/ihsm/api)
+
+📖 [Reference](https://filasieno.github.io/ihsm/reference)
+
+💬 [Open an issue](https://github.com/filasieno/ihsm/issues)
+
+---
+
+## Super quick start
 
-```shell
-npm install ihsm@latest
+```bash
+npm install ihsm
 ```
 
-### Runtime support
+```ts
+import { InitialState, makeHsm, TopState } from 'ihsm';
 
-ihsm ships modern **ES2022** ESM and CommonJS — no transpiled legacy (ES5/ES2015)
-output and no polyfills. Supported runtimes:
+interface DoorCtx {
+  openCount: number;
+}
 
-| Runtime | Minimum |
-| ------- | ------- |
-| Node.js | **22+** |
-| Chrome / Edge | **94+** |
-| Firefox | **93+** |
-| Safari (macOS / iOS) | **15.4+** |
+// All possible signals are enumerated in a formal protocol
+interface DoorProtocol {
+  open(): void;
+  close(): void;
+}
+
+class DoorTop extends TopState<DoorCtx, DoorProtocol> {}
 
-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).
+@InitialState
+class Closed extends DoorTop {
+  open(): void {
+    this.ctx.openCount += 1;
+    this.transition(Open);
+  }
+}
 
-## Requirements
+class Open extends DoorTop {
+  close(): void {
+    this.transition(Closed);
+  }
+}
 
-**[Nix](https://nixos.org/download/)** with flakes enabled — the only prerequisite to build and test
-from source.
+const door = makeHsm(DoorTop, { openCount: 0 });
+await door.sync(); // wait for initialization
 
-## Building
+door.post('open');
+await door.sync();
 
-```shell
-git clone https://github.com/filasieno/ihsm.git
-cd ihsm
+console.log(door.currentStateName); // 'Open'
+console.log(door.ctx.openCount);    // 1
 ```
 
-### Development environment
+---
+
+## Typed services with `call()`
+
+Most state-machine libraries make you reach for snapshots, child actors, or ad hoc callbacks to ask the machine a question. ihsm treats **services** as ordinary protocol methods — the runtime injects `resolve` / `reject`, and the client gets a typed `Promise`.
 
-**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).
+Define the service once on your `Protocol`. Implement it on a state class. Call it from anywhere that holds the `Hsm` handle.
 
-```shell
-nix develop
-# or: direnv allow    # .envrc → use flake; auto-enters the shell in supported terminals
+```ts
+import {
+  InitialState,
+  makeHsm,
+  RejectCallback,
+  ResolveCallback,
+  TopState,
+} from 'ihsm';
+
+interface WalletCtx {
+  balance: number;
+}
+
+// note the `getBalance` and `withdraw`.
+// since they have a *resolve* and *reject* the are services allowing State Machines to serve requests **AND** transition at the same time if required. 
+interface WalletProtocol {
+  deposit(amount: number): void;
+  getBalance(resolve: ResolveCallback<number>, reject: RejectCallback): void;
+  withdraw(resolve: ResolveCallback<number>, reject: RejectCallback, amount: number): void;
+}
+
+class WalletTop extends TopState<WalletCtx, WalletProtocol> implements WalletProtocol {
+  deposit(amount: number): void {
+    this.ctx.balance += amount;
+  }
+
+  getBalance(resolve: ResolveCallback<number>): void {
+    resolve(this.ctx.balance);
+  }
+
+  withdraw(resolve: ResolveCallback<number>, reject: RejectCallback, amount: number): void {
+    if (amount > this.ctx.balance) {
+      reject(new Error('insufficient funds'));
+      return;
+    }
+    this.ctx.balance -= amount;
+    resolve(this.ctx.balance);
+  }
+}
+
+@InitialState
+class Open extends WalletTop {}
+
+const wallet = makeHsm(WalletTop, { balance: 100 });
+await wallet.sync();
+
+wallet.post('deposit', 50);
+
+const balance = await wallet.call('getBalance'); // Promise<number> — no extra sync()
+
+try {
+  await wallet.call('withdraw', 200);
+} catch (err) {
+  // reject() from the handler becomes a thrown Error here
+}
+
+const left = await wallet.call('getBalance'); // 150
 ```
 
-Run npm commands **inside** that shell, or prefix each one with `nix develop --command`:
+**Events** (`void` handlers) → `post('deposit', 50)`. **Services** (`resolve` / `reject` handlers) → `await call('getBalance')`. Same mailbox, same serialization guarantees, full TypeScript inference on names, payloads, and return types.
+
+See [Call services](https://filasieno.github.io/ihsm/reference#_4-messaging-post-call-sync) in the reference.
+
+---
+
+## Hierarchical (nested) state machines
+
+Child states extend parent states. The prototype chain is the state tree; entering a composite runs `onEntry` from outer to inner initial leaf, exiting walks the lowest common ancestor path.
+Hierarchical state machines are extreamly easy to write just a extend a class.
+Also not that all states are stateless classes.
+All state is stored in the actor context available at `this.ctx`.
+
+```ts
+import { InitialState, makeHsm, TopState } from 'ihsm';
+
+interface PlayerCtx {
+  track: string;
+}
+
+interface PlayerProtocol {
+  play(): void;
+  pause(): void;
+  stop(): void;
+}
+
+class PlayerTop extends TopState<PlayerCtx, PlayerProtocol> {}
+
+class Active extends PlayerTop {
+  stop(): void {
+    this.transition(Stopped);
+  }
+}
 
-```shell
-nix develop --command npm test
+@InitialState
+class Playing extends Active {
+  pause(): void {
+    this.transition(Paused);
+  }
+}
+
+class Paused extends Active {
+  play(): void {
+    this.transition(Playing);
+  }
+}
+
+@InitialState
+class Stopped extends PlayerTop {
+  play(): void {
+    this.ctx.track = 'demo.mp3';
+    this.transition(Playing);
+  }
+}
+
+const player = makeHsm(PlayerTop, { track: '' });
+await player.sync();
+
+player.post('play');
+await player.sync();
+// active leaf: Playing — inherits stop() from Active
 ```
 
-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.
+See [Hierarchy & transitions](https://filasieno.github.io/ihsm/reference#_5-transitions) in the reference.
 
-### 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/` |
+## Messaging: `post`, `sync`, and `call`
 
-Full check before opening a PR:
+Every machine is an actor with a **single-threaded mailbox**. While a handler runs, new messages queue — no re-entrancy.
 
-```shell
-nix flake check
+| API | Role | Returns |
+| --- | ---- | ------- |
+| `post(event, …args)` | Fire-and-forget event | `void` (use `sync()` to wait) |
+| `call(service, …args)` | Typed request/response | `Promise<T>` |
+| `deferredPost(ms, event, …args)` | Timer then `post` | `void` |
+| `sync()` | Drain queue up to marker | `Promise<void>` |
+
+```ts
+door.post('open');
+await door.sync(); // handler + transition finished
+
+const id = await account.call('lookup', 'user-42'); // await the service directly
 ```
 
-After `nix build .#docs`, copy artifacts from `result/share/doc/ihsm/` or run
-`bash scripts/verify-docs-site.sh result/share/doc/ihsm`.
+Inside handlers you also get `transition()`, `sleep()`, and `postNow()` for hi-priority follow-up steps within the same dispatch turn.
 
-### npm scripts
+See [Post & sync](https://filasieno.github.io/ihsm/reference#_4-messaging-post-call-sync) in the reference.
 
-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
+## Async handlers
 
-| 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) |
+Handlers may be `async`. The runtime awaits the returned `Promise` before applying a scheduled `transition()` — so you can run an entire I/O pipeline inside one handler while staying in the same state.
+This is important to minimize states and exploit RTC semantics.
 
-#### Test
+```ts
+@InitialState
+class Idle extends FileTop {
+  async transfer(from: string, to: string): Promise<void> {
+    const data = await readFile(from);
+    await writeFile(to, data);
+    this.transition(Done);
+  }
+}
+```
 
-| 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 |
+See [Async handlers](https://filasieno.github.io/ihsm/reference#_9-async-handlers) in the reference.
 
-First-time browser setup: `npx playwright install chromium`.
+---
 
-#### Quality
+## Install
 
-| 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` |
+Requires [Node.js](https://nodejs.org/) **22+**.
+
+```bash
+npm install ihsm
+```
+
+### Runtime support
 
-#### Documentation
+ihsm ships modern **ES2022** ESM and CommonJS. Supported runtimes:
 
-| Command | Purpose |
+| Runtime | Minimum |
 | ------- | ------- |
-| `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) |
+| Node.js | **22+** |
+| Chrome / Edge | **94+** |
+| Firefox | **93+** |
+| Safari (macOS / iOS) | **15.4+** |
+
+### Size and dependencies
+
+Measured with `esbuild` bundling `lib/esm/index.js` for the browser (full runtime — mailbox, transitions, tracing, typed `call`):
+
+| | |
+| --- | --- |
+| **Production dependencies** | **0** |
+| **Published package** | `lib/` only (~46 KB npm tarball) |
+| **Minified bundle** | **~22 KB** (21.7 KiB; single-file ESM/IIFE) |
+| **Gzip** | **~4.6 KB** (typical CDN / HTTP transfer size) |
+| **Tree-shaking** | `"sideEffects": false` — runtime is one cohesive module (~22 KB even when importing only `makeHsm`) |
+
+Node loads the unminified `lib/` files directly (~18 KB entry, ~62 KB total); minify numbers apply to browser bundles.
+
+No React, no RxJS, no interpreter plugins — just the runtime you import.
+
+---
+
+## Why?
+
+Hierarchical statecharts are a formalism for modeling stateful, reactive systems. ihsm encodes them the **Samek/QP way**: class hierarchy, explicit transitions, cached LCA paths, and actor mailboxes — with compile-time safety from a single `Protocol` interface.
+
+Good fit when you want:
+
+- Typed events and services from one protocol definition
+- Backend / session actors without a heavy framework
+- Zero-dependency supply chain and a small browser bundle
+- Class-based states that read like ordinary TypeScript
+
+For visual editors and declarative chart JSON, libraries like [XState](https://github.com/statelyai/xstate) may fit better. See [Comparison with XState](https://filasieno.github.io/ihsm/reference#_13-comparison-with-xstate) in the reference.
+
+Inspired by Harel statecharts and the SCXML family of notations.
+
+---
+
+## Documentation
+
+| Resource | Link |
+| -------- | ---- |
+| **Documentation site** | [filasieno.github.io/ihsm](https://filasieno.github.io/ihsm/) |
+| Reference (concepts + interactive examples) | [/reference](https://filasieno.github.io/ihsm/reference) |
+| API reference (TSDoc) | [/api](https://filasieno.github.io/ihsm/api) |
+| Source: reference | [reference/REFERENCE.md](./reference/REFERENCE.md) |
+| Source: example machines | [examples/](./examples/) |
+
+The reference page combines the full manual with embedded playgrounds; the API is generated from TSDoc.
 
-Release process: [RELEASING.md](./RELEASING.md).
+---
 
 ## Contributing
 
-Contributions are welcome — bug reports, docs, and code.
+Contributions are welcome — bug reports, docs, and code. See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the development environment, build commands, and PR guidelines.
 
 - 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)
+- Security → [GitHub Security Advisories](https://github.com/filasieno/ihsm/security/advisories/new)
 
-Please follow [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). New behavior needs tests in `src/spec/`; tutorial changes need matching specs under `tutorials/`.
+Please follow [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 
-**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