ihsm 0.0.23 → 0.1.1

package/README.md

@@ -6,11 +6,11 @@
 
 # ihsm
 
-**Class-based hierarchical state machines and run-to-completion actors for TypeScript, explicitly designed for [Deterministic Simulation Testing](https://filasieno.github.io/ihsm/testing) (DST)** — typed `post`/`call`, **zero** production dependencies, **~4.6 KB gzip** in the browser. → [Documentation](https://filasieno.github.io/ihsm/)
+**Class-based hierarchical state machines and run-to-completion actors for TypeScript, explicitly designed for [Deterministic Simulation Testing](https://filasieno.github.io/ihsm/testing) (DST)** — nominal **`Config`**, generated handles, promise **services**, **zero** production dependencies, **~4.6 KB gzip** in the browser. → [Documentation](https://filasieno.github.io/ihsm/) · [Tutorial 00 — Config](examples/00-config/README.md)
 
 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 serialized, run-to-completion dispatch.
 
-> **Built for Deterministic Simulation Testing.** Determinism is not an add-on here — it is the design center. Every source of nondeterminism is pushed behind one seam: **serialized run-to-completion dispatch** (each handler runs to completion and never interleaves; `await sync()` drains to a barrier), a single **`Port`** boundary for *all* I/O (sockets, clocks, the filesystem), and a compiler-enforced **public/internal protocol split**. Swap the port for a mock, replace the clock with one you advance by hand, and the same inputs always produce the same outputs — so a failure **replays exactly**. The dedicated [`ihsm/testing`](#entry-points) entry point ships `makeTestActor`, `@mock`/`makeTestPort`, and a `TestPort` virtual clock for this, and never bloats your production bundle. See the [Deterministic Testing chapter](https://filasieno.github.io/ihsm/testing).
+> **Built for Deterministic Simulation Testing.** Determinism is not an add-on here — it is the design center. Every source of nondeterminism is pushed behind one seam: **serialized run-to-completion dispatch** (each handler runs to completion and never interleaves; `await actor.hsm.sync()` drains to a barrier), a single **`Port`** boundary for *all* I/O (sockets, clocks, the filesystem), and a compiler-enforced **public/internal protocol split**. Swap the port for a mock, replace the clock with one you advance by hand, and the same inputs always produce the same outputs — so a failure **replays exactly**. The dedicated [`ihsm/testing`](#entry-points) entry point ships `makeTestActor`, `@mock`/`makeTestPort`, and a `TestPort` virtual clock for this, and never bloats your production bundle. See the [Deterministic Testing chapter](https://filasieno.github.io/ihsm/testing).
 
 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.
 
@@ -20,11 +20,9 @@ It uses event-driven programming, class-based hierarchical statecharts, and the
 
 📖 [Read the documentation](https://filasieno.github.io/ihsm/)
 
-📑 [API reference](https://filasieno.github.io/ihsm/api)
-
 📖 [Reference](https://filasieno.github.io/ihsm/reference)
 
-🧪 [Deterministic Testing chapter](https://filasieno.github.io/ihsm/testing)
+🧪 [Deterministic Testing](https://filasieno.github.io/ihsm/testing)
 
 💬 [Open an issue](https://github.com/filasieno/ihsm/issues)
 
@@ -53,116 +51,114 @@ npm install ihsm
 ```
 
 ```ts
-import { InitialState, makeHsm, TopState } from 'ihsm';
+import { InitialState, makeActor, Port, TopState } from 'ihsm';
 
 interface DoorCtx {
   openCount: number;
 }
 
-// All possible signals are enumerated in a formal protocol
-interface DoorProtocol {
-  open(): void;
-  close(): void;
+interface DoorConfig {
+  context: DoorCtx;
+  notifications: {
+    open(): void;
+    close(): void;
+  };
 }
 
-class DoorTop extends TopState<DoorCtx, DoorProtocol> {}
+
+class DoorTop extends TopState<DoorConfig> {
+}
 
 @InitialState
 class Closed extends DoorTop {
   open(): void {
     this.ctx.openCount += 1;
-    this.transition(Open);
+    this.hsm.transition(Open);
   }
 }
 
 class Open extends DoorTop {
   close(): void {
-    this.transition(Closed);
+    this.hsm.transition(Closed);
   }
 }
 
-const door = makeHsm(DoorTop, { openCount: 0 });
-await door.sync(); // wait for initialization
+const door = makeActor(DoorTop, { openCount: 0 }, new Port());
+await door.hsm.sync();
 
-door.post('open');
-await door.sync();
+door.notify.open();
+await door.hsm.sync();
 
-console.log(door.currentStateName); // 'Open'
-console.log(door.ctx.openCount);    // 1
+console.log(door.hsm.currentStateName); // 'Open'
+console.log(door.ctx.openCount);        // 1
 ```
 
----
+See **[examples/00-config/](examples/00-config/README.md)** for the full protocol tour.
 
-## 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`.
+## Typed services (promise-returning)
 
-Define the service once on your `Protocol`. Implement it on a state class. Call it from anywhere that holds the `Hsm` handle.
+Services are declared on the protocol's `services` bucket. The generated client method **always** returns `Promise<Reply>` — callers must `await`, so RTC ordering is explicit.
 
 ```ts
-import {
-  InitialState,
-  makeHsm,
-  RejectCallback,
-  ResolveCallback,
-  TopState,
-} from 'ihsm';
+import { InitialState, makeActor, Port, 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;
+interface WalletConfig {
+  notifications: { deposit(amount: number): void };
+  services: {
+    getBalance(): Promise<number>;
+    withdraw(amount: number): Promise<number>;
+  };
+  context: WalletCtx;
 }
 
-class WalletTop extends TopState<WalletCtx, WalletProtocol> {
+
+class WalletTop extends TopState<WalletConfig> {
+
   deposit(amount: number): void {
     this.ctx.balance += amount;
   }
 
-  getBalance(resolve: ResolveCallback<number>): void {
-    resolve(this.ctx.balance);
+  getBalance(): number {
+    return this.ctx.balance;
   }
 
-  withdraw(resolve: ResolveCallback<number>, reject: RejectCallback, amount: number): void {
+  withdraw(amount: number): number {
     if (amount > this.ctx.balance) {
-      reject(new Error('insufficient funds'));
-      return;
+      throw new Error('insufficient funds');
     }
     this.ctx.balance -= amount;
-    resolve(this.ctx.balance);
+    return this.ctx.balance;
   }
 }
 
 @InitialState
 class Open extends WalletTop {}
 
-const wallet = makeHsm(WalletTop, { balance: 100 });
-await wallet.sync();
+const wallet = makeActor(WalletTop, { balance: 100 }, new Port());
+await wallet.hsm.sync();
 
-wallet.post('deposit', 50);
+wallet.notify.deposit(50);
 
-const balance = await wallet.call('getBalance'); // Promise<number> — no extra sync()
+const balance = await wallet.call.getBalance();
 
 try {
-  await wallet.call('withdraw', 200);
-} catch (err) {
-  // reject() from the handler becomes a thrown Error here
+  await wallet.call.withdraw(200);
+} catch {
+  // handler throw → rejected Promise
 }
 
-const left = await wallet.call('getBalance'); // 150
+const left = await wallet.call.getBalance(); // 150
 ```
 
-**Events** (`void` handlers) → `post('deposit', 50)`. **Services** (`resolve` / `reject` handlers) → `await call('getBalance')`. Same run-to-completion dispatch, same serialization guarantees, full TypeScript inference on names, payloads, and return types.
+**Notifications** → `wallet.notify.deposit(50)` (void). **Services** → `await wallet.call.getBalance()` (Promise). The split is **nominal** via `Config.notifications` vs `Config.services`.
 
-The split is enforced **at compile time**: the protocol is partitioned into event keys and service keys, so `post('getBalance')` (a service) and `call('deposit', 50)` (an event) are both type errors — you can only `post` events and `call` services.
-
-See [Call services](https://filasieno.github.io/ihsm/reference#_4-messaging-post-call-sync) in the reference.
+See [Tutorial 00 — Config](examples/00-config/README.md) and the [reference](https://filasieno.github.io/ihsm/reference).
 
 ---
 
@@ -174,36 +170,37 @@ 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';
+import { InitialState, makeActor, Port, TopState } from 'ihsm';
 
 interface PlayerCtx {
   track: string;
 }
 
-interface PlayerProtocol {
-  play(): void;
-  pause(): void;
-  stop(): void;
+interface PlayerConfig {
+  context: PlayerCtx;
+  notifications: { play(): void; pause(): void; stop(): void };
 }
 
-class PlayerTop extends TopState<PlayerCtx, PlayerProtocol> {}
+
+class PlayerTop extends TopState<PlayerConfig> {
+}
 
 class Active extends PlayerTop {
   stop(): void {
-    this.transition(Stopped);
+    this.hsm.transition(Stopped);
   }
 }
 
 @InitialState
 class Playing extends Active {
   pause(): void {
-    this.transition(Paused);
+    this.hsm.transition(Paused);
   }
 }
 
 class Paused extends Active {
   play(): void {
-    this.transition(Playing);
+    this.hsm.transition(Playing);
   }
 }
 
@@ -211,15 +208,15 @@ class Paused extends Active {
 class Stopped extends PlayerTop {
   play(): void {
     this.ctx.track = 'demo.mp3';
-    this.transition(Playing);
+    this.hsm.transition(Playing);
   }
 }
 
-const player = makeHsm(PlayerTop, { track: '' });
-await player.sync();
+const player = makeActor(PlayerTop, { track: '' }, new Port());
+await player.hsm.sync();
 
-player.post('play');
-await player.sync();
+player.notify.play();
+await player.hsm.sync();
 // active leaf: Playing — inherits stop() from Active
 ```
 
@@ -227,27 +224,28 @@ See [Hierarchy & transitions](https://filasieno.github.io/ihsm/reference#_5-tran
 
 ---
 
-## Messaging: `post`, `sync`, and `call`
+## Messaging: notifications, services, and sync
 
 Every machine is an actor with **single-threaded, run-to-completion dispatch**. While a handler runs to completion, new messages queue — no re-entrancy.
 
 | 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>` |
+| `actor.notify.event(…)` | Fire-and-forget notification | `void` (use `hsm.sync()` to wait) |
+| `actor.notifyNow.event(…)` | Hi-priority notification | `void` |
+| `await actor.call.service(…)` | Typed request/response | `Promise<T>` |
+| `this.hsm.port.defer(ms).event(…)` | Timer then self-notification | handler-only |
+| `await actor.hsm.sync()` | Drain queue up to marker | `Promise<void>` |
 
 ```ts
-door.post('open');
-await door.sync(); // handler + transition finished
+door.notify.open();
+await door.hsm.sync();
 
-const id = await account.call('lookup', 'user-42'); // await the service directly
+const id = await account.call.lookup('user-42');
 ```
 
-Inside handlers you also get `transition()`, `sleep()`, and `postNow()` for hi-priority follow-up steps within the same dispatch turn.
+Inside handlers use `this.hsm.transition()`, `this.notify`, and `this.notifyNow`. For delays, `await new Promise(r => this.hsm.port.setTimeout(r, ms))`; for timer-driven self-notifications, `this.hsm.port.defer(ms).event(…)`.
 
-See [Post & sync](https://filasieno.github.io/ihsm/reference#_4-messaging-post-call-sync) in the reference.
+See [Messaging](https://filasieno.github.io/ihsm/reference#_4-messaging-notifications-services-sync) in the reference.
 
 ---
 
@@ -262,7 +260,7 @@ class Idle extends FileTop {
   async transfer(from: string, to: string): Promise<void> {
     const data = await readFile(from);
     await writeFile(to, data);
-    this.transition(Done);
+    this.hsm.transition(Done);
   }
 }
 ```
@@ -275,11 +273,11 @@ See [Async handlers](https://filasieno.github.io/ihsm/reference#_9-async-handler
 
 Production code imports `ihsm`; tests import `ihsm/testing`. Every source of nondeterminism lives behind a **`Port`** — sockets, clocks, randomness, the filesystem. Tests swap in a **`TestPort`** (virtual clock, scripted random, recorded message log) or an **`@mock`** port stub, then drive the machine with **`makeTestActor`** (merged public + internal protocol, `subscribe()` for golden traces).
 
-Two rules: **never perform I/O outside a port**, and **never `sleep()` on wall-clock time in a test** — advance virtual time and `await sync()` instead.
+Two rules: **never perform I/O outside a port**, and **never `sleep()` on wall-clock time in a test** — advance virtual time and `await actor.hsm.sync()` instead.
 
 ### Virtual clock — simulate days of timers in microseconds
 
-`deferredPost` arms timers through the port. Replace the real clock with `TestPort` and call `advance(ms)` by hand:
+`this.hsm.port.defer(ms).onTick()` arms timers through the port. Replace the real clock with `TestPort` and call `advance(ms)` by hand:
 
 ```ts
 import { InitialState, TopState } from 'ihsm';
@@ -287,41 +285,36 @@ import { makeTestActor, TestPort } from 'ihsm/testing';
 
 const HOUR_MS = 60 * 60 * 1000;
 
-class HeartbeatCtx {
-  ticks = 0;
+interface HeartbeatConfig {
+  context: { ticks: number };
+  notifications: { start(): void };
+  internalNotifications: { onTick(): void };
 }
 
-interface HeartbeatPublic {
-  start(): void;
+class HeartbeatTop extends TopState<HeartbeatConfig> {
 }
 
-interface HeartbeatInternal {
-  onTick(): void;
-}
-
-class HeartbeatTop extends TopState<HeartbeatCtx, HeartbeatPublic, HeartbeatInternal> {}
-
 @InitialState
 class Running extends HeartbeatTop {
   start(): void {
-    this.deferredPost(HOUR_MS, 'onTick');
+    this.hsm.port.defer(HOUR_MS).onTick();
   }
   onTick(): void {
     this.ctx.ticks += 1;
-    this.deferredPost(HOUR_MS, 'onTick');
+    this.hsm.port.defer(HOUR_MS).onTick();
   }
 }
 
-const clock = new TestPort<HeartbeatTop>();
+const clock = new TestPort<typeof HeartbeatTop>();
 const test = makeTestActor(HeartbeatTop, new HeartbeatCtx(), clock);
-await test.sync();
+await test.hsm.sync();
 
-test.post('start');
-await test.sync();
+test.start();
+await test.hsm.sync();
 
 for (let hour = 0; hour < 48; hour++) {
   clock.advance(HOUR_MS); // fire the due tick — no real waiting
-  await test.sync();
+  await test.hsm.sync();
 }
 
 // test.ctx.ticks === 48
@@ -337,7 +330,7 @@ Put `fetch()` behind a port. The mock records outbound calls but does **not** au
 import { mock, makeTestActor, makeTestPort, TestPort } from 'ihsm/testing';
 
 @mock
-abstract class MockFetchPort extends TestPort<FetchTop> {
+abstract class MockFetchPort extends TestPort<typeof FetchTop> {
   abstract request(url: string): { value: number; subscription: { dispose(): void } };
 }
 
@@ -348,14 +341,14 @@ port.request.default(() => ({
 }));
 
 const fetcher = makeTestActor(FetchTop, freshCtx(), port);
-await fetcher.sync();
+await fetcher.hsm.sync();
 
-fetcher.post('fetch', 'https://example.com');
-await fetcher.sync();
+fetcher.fetch('https://example.com');
+await fetcher.hsm.sync();
 // fetcher.currentState === Fetching — in-flight, still timer-free
 
 port.send('onResponse', 200, 'ok'); // you decide when the "network" replies
-await fetcher.sync();
+await fetcher.hsm.sync();
 // fetcher.currentState === Done
 // port.trace === ['request:https://example.com', 'onResponse:200,ok']
 ```
@@ -365,12 +358,12 @@ await fetcher.sync();
 Wire `subscribe` to the port message log for a byte-identical transcript across runs:
 
 ```ts
-const port = new TestPort<HeartbeatTop>();
+const port = new TestPort<typeof HeartbeatTop>();
 const test = makeTestActor(HeartbeatTop, new HeartbeatCtx(), port);
 const sub = test.subscribe(m => port.record(m.event, ...m.payload));
 
-test.post('start');
-await test.sync();
+test.start();
+await test.hsm.sync();
 // port.events === ['start']
 
 sub.dispose();
@@ -395,11 +388,11 @@ version:
 
 | Import | Contents | Ships in production? |
 | ------ | -------- | -------------------- |
-| `ihsm` | The runtime: `makeHsm` / `makeActor`, `TopState`, ports, tracing | **yes** |
+| `ihsm` | The runtime: `makeActor` / `makeActor`, `TopState`, ports, tracing | **yes** |
 | `ihsm/testing` or `@ihsm/core/testing` | Deterministic-testing utilities: `makeTestActor`, `@mock` / `makeTestPort`, `TestPort` (re-exports the core API too) | **no** — test-only |
 
 ```ts
-import { makeHsm, TopState } from 'ihsm';                 // production code
+import { makeActor, TopState } from 'ihsm';                 // production code
 import { makeTestActor, mock, TestPort } from 'ihsm/testing'; // tests only
 ```
 
@@ -421,7 +414,7 @@ ihsm ships modern **ES2022** ESM and CommonJS. Supported runtimes:
 
 ### Size and dependencies
 
-Measured with `esbuild` bundling `lib/esm/index.js` for the browser (full runtime — run-to-completion dispatch, transitions, tracing, typed `call`):
+Measured with `esbuild` bundling `lib/esm/index.js` for the browser (full runtime — run-to-completion dispatch, transitions, tracing, promise services):
 
 | | |
 | --- | --- |
@@ -429,7 +422,7 @@ Measured with `esbuild` bundling `lib/esm/index.js` for the browser (full runtim
 | **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`) |
+| **Tree-shaking** | `"sideEffects": false` — runtime is one cohesive module (~22 KB even when importing only `makeActor`) |
 
 Node loads the unminified `lib/` files directly (~18 KB entry, ~62 KB total); minify numbers apply to browser bundles.
 
@@ -461,12 +454,11 @@ Inspired by Harel statecharts and the SCXML family of notations.
 | **Documentation site** | [filasieno.github.io/ihsm](https://filasieno.github.io/ihsm/) |
 | Deterministic Simulation Testing | [/testing](https://filasieno.github.io/ihsm/testing) |
 | Reference (concepts + interactive examples) | [/reference](https://filasieno.github.io/ihsm/reference) |
-| API reference (TSDoc) | [/api](https://filasieno.github.io/ihsm/api) |
 | Source: DST chapter | [reference/TESTING.md](./reference/TESTING.md) |
 | 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.
+The reference page combines the manual with embedded playgrounds. The testing chapter runs five DST examples first, then the full technique.
 
 ---