@mantaq/core 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @mantaq/core
 
-State machine library. Small API surface — cook the primitives, not the framework.
+State machine library. Small API surface. Cook the primitives, not the framework.
 
 ## Install
 
@@ -10,19 +10,19 @@ npm install @mantaq/core
 
 ## Quick Reference
 
-| Pattern         | Correct                                       | Anti-pattern                          |
-| --------------- | --------------------------------------------- | ------------------------------------- |
-| Type context    | `context: {} as MyContext`                    | casting in every handler              |
-| Write context   | `context.set({ ...context.get() })`           | mutate without `set()`                |
-| Type events     | `event("ID")<Payload>()`                      | `event("ID")()` without generic       |
-| Send events     | `actor.send(signInEvent.create(data))`        | raw `{ type: "ID", payload }` objects |
-| Effect data     | Use state payload                             | Depend on `event` in effect           |
-| Error handling  | Emit internal event                           | Throw in effect or transition         |
-| Internal events | Declare in `internal: [...]`                  | Put user events in internal           |
-| Signal check    | `if (signal.aborted) return`                  | Skip abort check in async work        |
-| Regions         | Child outputs in parent `internal`            | Forget to declare child outputs       |
-| Snapshot        | `snapshot()` carries path + context + payload | Re-serialize context by hand          |
-| Any handler     | Universal events only (CANCEL)                | State-specific logic in `onAny`       |
+| Pattern         | Correct                                            | Anti-pattern                          |
+| --------------- | -------------------------------------------------- | ------------------------------------- |
+| Type context    | `context: {} as MyContext`                         | casting in every handler              |
+| Write context   | `const s = context.get(); s.x = y; context.set(s)` | mutate without `set()`                |
+| Type events     | `event("ID")<Payload>()`                           | `event("ID")()` without generic       |
+| Send events     | `actor.send(signInEvent.create(data))`             | raw `{ type: "ID", payload }` objects |
+| Effect data     | Use state payload                                  | Depend on `event` in effect           |
+| Error handling  | Emit internal event                                | Throw in effect or transition         |
+| Internal events | Declare in `internal: [...]`                       | Put user events in internal           |
+| Signal check    | `if (signal.aborted) return`                       | Skip abort check in async work        |
+| Regions         | Child outputs in parent `internal`                 | Forget to declare child outputs       |
+| Snapshot        | `snapshot()` carries path + context + payload      | Re-serialize context by hand          |
+| Any handler     | Universal events only (CANCEL)                     | State-specific logic in `onAny`       |
 
 ## Contents
 
@@ -81,7 +81,7 @@ See [anderscan.github.io/mantaq](https://anderscan.github.io/mantaq) for full do
 
 ### Typed Actor Context
 
-Cast the context type once at the constructor level. Handlers receive the typed context automatically — no casting needed per-handler.
+Cast the context type once at the constructor level. Handlers receive the typed context automatically. No casting needed per-handler.
 
 ```ts
 interface AuthContext {
@@ -97,33 +97,39 @@ const actor = new Actor({
   setup: (m) => {
     m.on(idleState, signInEvent, (event, opts) => {
       // ✅ typed — context.get()/set() flow the constructor type
-      opts!.context.set({ ...opts!.context.get(), phoneNumber: event.payload.phoneNumber });
+      const s = opts!.context.get();
+      s.phoneNumber = event.payload.phoneNumber;
+      opts!.context.set(s);
       return { state: signingInState };
     });
   },
 });
 ```
 
-`set()` is the write signal — always call it to write, even when the new value is the same reference. Any `set()` triggers `change`. Spread the current value:
+Context is user land. Mutate it freely. `set()` is the write signal: any `set()` triggers `change`, even with the same reference. Call it after you mutate:
 
 ```ts
-opts.context.set({ ...opts.context.get(), phoneNumber: event.payload.phoneNumber });
+const s = opts.context.get();
+s.phoneNumber = event.payload.phoneNumber;
+opts.context.set(s);
 ```
 
-**Never mutate in place:**
+**Never mutate without `set()`:**
 
 ```ts
 // ❌ mutation without set() — never signals; subscribers and persistence stay silent
 opts!.context.phoneNumber = event.payload.phoneNumber;
 ```
 
-**Anti-pattern — casting in every handler:**
+**Anti-pattern. Casting in every handler:**
 
 ```ts
 setup: (m) => {
   m.on(idleState, signInEvent, (event, opts) => {
     const c = opts!.context as AuthContext; // ❌ unnecessary — already typed
-    c.set({ ...c.get(), phoneNumber: event.payload.phoneNumber });
+    const s = c.get();
+    s.phoneNumber = event.payload.phoneNumber;
+    c.set(s);
     return { state: signingInState };
   });
 },
@@ -154,7 +160,7 @@ setup: (m) => {
 },
 ```
 
-**Anti-pattern — skipping the generic parameter:**
+**Anti-pattern. Skipping the generic parameter:**
 
 ```ts
 // ❌ payload is `unknown`, no type safety
@@ -164,7 +170,7 @@ const badEvent = event("SIGN_IN")();
 const goodEvent = event("SIGN_IN")<{ phoneNumber: string }>();
 ```
 
-**Anti-pattern — sending raw objects instead of using `.create()`:**
+**Anti-pattern. Sending raw objects instead of using `.create()`:**
 
 ```ts
 // ✅ typed
@@ -176,7 +182,7 @@ actor.send({ type: "SIGN_IN", payload: { phoneNumber: "+1234567890" } });
 
 ### Effects and Event Typing
 
-Effects run when entering a state. The `event` parameter in effects is typed `InternalEvent` — `{ type, payload? }` with `payload: unknown` — not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
+Effects run when entering a state. The `event` parameter in effects is typed `InternalEvent`, `{ type, payload? }` with `payload: unknown`, not the specific event that triggered the transition. This is by design: effects live on states, not transitions. Multiple transitions can lead to the same state, so the effect cannot know which event caused entry.
 
 **Pass data to effects via state payload.** Set the payload in the transition return, read it from `state.payload` in the effect.
 
@@ -192,12 +198,15 @@ const actor = new Actor({
   states: [idleState, loadingState, loadedState],
   initial: idleState,
   setup: (m) => {
-    m.effect(loadingState, ({ state, emit, clock }) => {
-      // state.payload is typed to the state's declared payload: { url: string }
-      const url = state.payload.url;
-      clock.setTimeout(1000, () => {
-        emit(doneEvent.create());
-      });
+    m.effect(loadingState, {
+      name: "fetchUrl",
+      fn: ({ state, emit, clock }) => {
+        // state.payload is typed to the state's declared payload: { url: string }
+        const url = state.payload.url;
+        clock.setTimeout(1000, () => {
+          emit(doneEvent.create());
+        });
+      },
     });
     m.on(idleState, fetchEvent, (event) => {
       return { state: loadingState.create({ url: event.payload.url }) };
@@ -207,23 +216,28 @@ const actor = new Actor({
 });
 ```
 
-**Context is also possible but less precise.** Context is shared across all states — writing to context in one state leaks into others. Prefer state payload for data that belongs to a specific state entry.
+**Context is also possible but less precise.** Context is shared across all states. Writing to context in one state leaks into others. Prefer state payload for data that belongs to a specific state entry.
 
 ```ts
 // ✅ state payload — scoped to this state entry
 return { state: loadingState.create({ url: event.payload.url }) };
 
 // ⚠️ context — works but shared across all states
-opts!.context.set({ ...opts!.context.get(), url: event.payload.url });
+const s = opts!.context.get();
+s.url = event.payload.url;
+opts!.context.set(s);
 return { state: loadingState };
 ```
 
-**Anti-pattern — depending on `event` in effects:**
+**Anti-pattern. Depending on `event` in effects:**
 
 ```ts
-m.effect(loadingState, ({ event, emit }) => {
-  // ❌ event is InternalEvent — payload is unknown, not the triggering event's payload
-  emit(doneEvent.create()); // fine — but event.payload.url would be a type error
+m.effect(loadingState, {
+  name: "fetchUrl",
+  fn: ({ event, emit }) => {
+    // ❌ event is InternalEvent — payload is unknown, not the triggering event's payload
+    emit(doneEvent.create()); // fine — but event.payload.url would be a type error
+  },
 });
 ```
 
@@ -233,9 +247,9 @@ The `event` parameter exists for convenience (e.g., logging), not for business l
 
 Mantaq uses two event queues: **external** (user-sent) and **internal** (effect-emitted). Understanding the difference prevents subtle bugs.
 
-**External events** are sent via `actor.send()` — they trigger transitions on the current state.
+**External events** are sent via `actor.send()`. They trigger transitions on the current state.
 
-**Internal events** are emitted from effects via `emit()` — they are queued and processed after the current transition completes.
+**Internal events** are emitted from effects via `emit()`. They are queued and processed after the current transition completes.
 
 ```ts
 const tickEvent = event("TICK")();
@@ -247,10 +261,13 @@ const actor = new Actor({
   states: [idleState, connectedState],
   initial: idleState,
   setup: (m) => {
-    m.effect(idleState, ({ emit, clock }) => {
-      clock.setTimeout(1000, () => {
-        emit(tickEvent.create()); // goes to internal queue
-      });
+    m.effect(idleState, {
+      name: "scheduleTick",
+      fn: ({ emit, clock }) => {
+        clock.setTimeout(1000, () => {
+          emit(tickEvent.create()); // goes to internal queue
+        });
+      },
     });
     m.on(idleState, connectEvent, () => ({ state: connectedState })); // external handler
     m.on(idleState, tickEvent, () => ({})); // internal handler
@@ -258,9 +275,9 @@ const actor = new Actor({
 });
 ```
 
-**Ordering:** External events process one at a time. Internal events emitted during a transition process depth-first after that transition. Internal events from effects process after the effect completes — this is a common source of bugs. If an effect emits an internal event and the actor is in a different state by the time that event processes, the handler may not exist or may behave unexpectedly.
+**Ordering:** External events process one at a time. Internal events emitted during a transition process depth-first after that transition. Internal events from effects process after the effect completes. This is a common source of bugs. If an effect emits an internal event and the actor is in a different state by the time that event processes, the handler may not exist or may behave unexpectedly.
 
-**Anti-pattern — mixing internal/external incorrectly:**
+**Anti-pattern. Mixing internal/external incorrectly:**
 
 ```ts
 // ❌ declaring a user-sent event as internal
@@ -272,7 +289,7 @@ inputs: [connectEvent],
 
 ### Effect Pattern
 
-Effects run on state entry. They receive typed context, an AbortSignal, and an emit function.
+Effects run on state entry. They receive typed context, an AbortSignal, and an emit function. Each effect carries a required camelCase `name` describing what it does — tests can assert on it (`harness.assertEffectRan(stateName, effectName)`) and executed effects appear in history as `{ stateName, effectName }`.
 
 ```ts
 type MyContext = { retryCount: number; maxRetries: number };
@@ -289,25 +306,27 @@ function createActor() {
     initial: idleState,
     context: { retryCount: 0, maxRetries: 3 } as MyContext,
     setup: (m) => {
-      m.effect(workingState, ({ signal, context, emit, clock }) => {
-        // context is MyContext — typed from the constructor generic
-        if (context.retryCount >= context.maxRetries) {
-          emit(failedEvent.create({ error: "Max retries exceeded" }));
-          return;
-        }
-
-        clock.setTimeout(2000, () => {
-          if (signal.aborted) return; // ✅ check signal before emitting
-          emit(doneEvent.create());
-        });
+      m.effect(workingState, {
+        name: "attemptWork",
+        fn: ({ signal, context, emit, clock }) => {
+          // context is MyContext — typed from the constructor generic
+          if (context.retryCount >= context.maxRetries) {
+            emit(failedEvent.create({ error: "Max retries exceeded" }));
+            return;
+          }
+
+          clock.setTimeout(2000, () => {
+            if (signal.aborted) return; // ✅ check signal before emitting
+            emit(doneEvent.create());
+          });
+        },
       });
       m.on(idleState, startEvent, () => ({ state: workingState }));
       m.on(workingState, doneEvent, () => ({ state: doneState }));
       m.on(workingState, failedEvent, (_event, opts) => {
-        opts!.context.set({
-          ...opts!.context.get(),
-          retryCount: opts!.context.get().retryCount + 1,
-        });
+        const s = opts!.context.get();
+        s.retryCount += 1;
+        opts!.context.set(s);
         return { state: errorState };
       });
     },
@@ -315,30 +334,36 @@ function createActor() {
 }
 ```
 
-**Anti-pattern — not checking `signal.aborted`:**
+**Anti-pattern. Not checking `signal.aborted`:**
 
 ```ts
-m.effect(workingState, ({ signal, emit, clock }) => {
-  // ❌ if state changes before timeout, this still fires
-  clock.setTimeout(2000, () => {
-    emit(doneEvent.create());
-  });
+m.effect(workingState, {
+  name: "attemptWork",
+  fn: ({ signal, emit, clock }) => {
+    // ❌ if state changes before timeout, this still fires
+    clock.setTimeout(2000, () => {
+      emit(doneEvent.create());
+    });
+  },
 });
 ```
 
 ```ts
-m.effect(workingState, ({ signal, emit, clock }) => {
-  // ✅ guard with abort check
-  clock.setTimeout(2000, () => {
-    if (signal.aborted) return;
-    emit(doneEvent.create());
-  });
+m.effect(workingState, {
+  name: "attemptWork",
+  fn: ({ signal, emit, clock }) => {
+    // ✅ guard with abort check
+    clock.setTimeout(2000, () => {
+      if (signal.aborted) return;
+      emit(doneEvent.create());
+    });
+  },
 });
 ```
 
 ### Snapshot & Restore
 
-`actor.snapshot()` returns a `Snapshot` — `{ path, context, payload?, regions, done?, error? }`. Context is included; `payload` is the payload the current state was entered with (present only when the transition carried one). Use it to save/restore actor state across sessions.
+`actor.snapshot()` returns a `Snapshot`: `{ path, context, payload?, regions, done?, error? }`. Context is included; `payload` is the payload the current state was entered with (present only when the transition carried one). Use it to save/restore actor state across sessions.
 
 ```ts
 // Snapshot carries path, context, and regions — serialize it directly
@@ -352,7 +377,7 @@ if (raw) {
 }
 ```
 
-**Anti-pattern — re-serializing context by hand:**
+**Anti-pattern. Re-serializing context by hand:**
 
 ```ts
 // ❌ snapshot() already includes context — no manual step needed
@@ -403,7 +428,7 @@ const manager = new Actor({
 matches(manager, "connected.health.healthy"); // ✅
 ```
 
-**Anti-pattern — child outputs not declared as parent internal events:**
+**Anti-pattern. Child outputs not declared as parent internal events:**
 
 ```ts
 const child = new Actor({
@@ -426,7 +451,7 @@ const parent = new Actor({
 
 ### Error Handling
 
-Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. If user code throws anyway, the machine does **not** misbehave silently: it dies into a built-in terminal `__error` state, records `snapshot().error` (the thrown value, the state/context at the point of failure, the bad event), drops remaining events, and ignores later `send`s. Errors never escape `send()` and the machine stays deterministic — same inputs, same trace.
+Never throw from effects or transitions. Emit an error as an internal event and let a transition handle it. If user code throws anyway, the machine does **not** misbehave silently: it dies into a built-in terminal `__error` state, records `snapshot().error` (the thrown value, the state/context at the point of failure, the bad event), drops remaining events, and ignores later `send`s. Errors never escape `send()` and the machine stays deterministic. Same inputs, same trace.
 
 ```ts
 const snap = actor.snapshot();
@@ -439,10 +464,10 @@ if (snap.error) {
 
 Two deliberate exceptions to "every failure is loud":
 
-- **Subscribers only watch.** They read snapshots and never change the machine, so a throwing `on("change")`/`on("done")`/`on("transition")` callback is swallowed — the machine and its callers are unaffected.
+- **Subscribers only watch.** They read snapshots and never change the machine, so a throwing `on("change")`/`on("done")`/`on("transition")`/`on("error")` callback is swallowed. The machine and its callers are unaffected.
 - **Unhandled external events are ignored.** An event with no handler in the current state is dropped by design (broadcast fan-out, cross-state sends). An **internal** event with no handler, however, is a machine-authoring bug and routes to the error state (`reason: "unhandled"`).
 
-A dead machine can be manually resumed with `actor.recover({ state, context })` — an explicit, **inherently dangerous** escape hatch (the caller injects state and context, so determinism no longer holds). Effects are not re-run and timers are not re-armed; processing resumes on the next event. Prefer fixing the root cause and recreating the actor.
+A dead machine can be manually resumed with `actor.recover({ state, context })`. An explicit, **inherently dangerous** escape hatch (the caller injects state and context, so determinism no longer holds). Effects are not re-run and timers are not re-armed; processing resumes on the next event. Prefer fixing the root cause and recreating the actor.
 
 Catch errors inside effects and emit recovery events:
 
@@ -451,17 +476,20 @@ const doneEvent = event("WORK_DONE")();
 const failedEvent = event("WORK_FAILED")<{ error: string }>();
 
 setup: (m) => {
-  m.effect(workingState, ({ signal, emit, clock }) => {
-    clock.setTimeout(100, () => {
-      if (signal.aborted) return;
-      try {
-        const result = riskyOperation();
-        emit(doneEvent.create());
-      } catch (err) {
-        // ✅ emit error as internal event — lets transition handle it
-        emit(failedEvent.create({ error: String(err) }));
-      }
-    });
+  m.effect(workingState, {
+    name: "runRiskyOperation",
+    fn: ({ signal, emit, clock }) => {
+      clock.setTimeout(100, () => {
+        if (signal.aborted) return;
+        try {
+          const result = riskyOperation();
+          emit(doneEvent.create());
+        } catch (err) {
+          // ✅ emit error as internal event — lets transition handle it
+          emit(failedEvent.create({ error: String(err) }));
+        }
+      });
+    },
   });
   m.on(workingState, doneEvent, () => ({ state: doneState }));
   m.on(workingState, failedEvent, (event) => {
@@ -471,7 +499,7 @@ setup: (m) => {
 },
 ```
 
-**Anti-pattern — re-throwing in effects:**
+**Anti-pattern. Re-throwing in effects:**
 
 ```ts
 try {
@@ -482,7 +510,7 @@ try {
 }
 ```
 
-**Anti-pattern — throwing in transition handlers:**
+**Anti-pattern. Throwing in transition handlers:**
 
 ```ts
 m.on(idleState, submitEvent, (event) => {
@@ -496,7 +524,9 @@ Prefer storing the error in context and transitioning to an error state:
 ```ts
 m.on(idleState, submitEvent, (event, opts) => {
   if (!event.payload.data) {
-    opts!.context.set({ ...opts!.context.get(), error: "missing data" });
+    const s = opts!.context.get();
+    s.error = "missing data";
+    opts!.context.set(s);
     return { state: errorState };
   }
   return { state: doneState };
@@ -505,13 +535,15 @@ m.on(idleState, submitEvent, (event, opts) => {
 
 ### Any Handler
 
-Use `onAny` to intercept events across all states — useful for universal error handling, cleanup, or logging.
+Use `onAny` to intercept events across all states. Useful for universal error handling, cleanup, or logging.
 
 ```ts
 setup: (m) => {
   // CANCEL works from any state
   m.onAny(cancelEvent, (_event, opts) => {
-    opts!.context.set({ ...opts!.context.get(), cancelled: true });
+    const s = opts!.context.get();
+    s.cancelled = true;
+    opts!.context.set(s);
     return { state: cancelledState };
   });
   // State-specific handlers still run for their state
@@ -519,19 +551,23 @@ setup: (m) => {
 },
 ```
 
-**Anti-pattern — using `onAny` for everything:**
+**Anti-pattern. Using `onAny` for everything:**
 
 ```ts
 setup: (m) => {
   // ❌ state-specific logic in onAny defeats the purpose
   m.onAny(submitBasicInfoEvent, (event, opts) => {
-    opts!.context.set({ ...opts!.context.get(), basicInfo: event }); // wrong — only makes sense in basicInfo state
+    const s = opts!.context.get();
+    s.basicInfo = event; // wrong — only makes sense in basicInfo state
+    opts!.context.set(s);
     return { state: shippingAddressState };
   });
 
   // ✅ keep state-specific logic in state handlers
   m.on(basicInfoState, submitBasicInfoEvent, (event, opts) => {
-    opts!.context.set({ ...opts!.context.get(), basicInfo: event });
+    const s = opts!.context.get();
+    s.basicInfo = event;
+    opts!.context.set(s);
     return { state: shippingAddressState };
   });
 },
@@ -559,8 +595,11 @@ const actor = new Actor({
   initial: idle,
   clock,
   setup: (m) => {
-    m.effect(idle, ({ emit, clock }) => {
-      clock.setTimeout(5000, () => emit(timer.create()));
+    m.effect(idle, {
+      name: "armIdleTimeout",
+      fn: ({ emit, clock }) => {
+        clock.setTimeout(5000, () => emit(timer.create()));
+      },
     });
     m.on(idle, timer, () => ({ state: timedOut }));
   },
@@ -573,7 +612,7 @@ expect(actor.state.name).toBe("timedOut");
 expect(clock.hasPending()).toBe(false);
 ```
 
-**Anti-pattern — using `new Date()` or `setTimeout` directly:**
+**Anti-pattern. Using `new Date()` or `setTimeout` directly:**
 
 ```ts
 // ❌ real timers — slow, flaky, non-deterministic
@@ -603,11 +642,14 @@ const actor = new Actor({
   initial: loading,
   clock,
   setup: (m) => {
-    m.effect(loading, ({ signal, clock }) => {
-      const id = clock.setTimeout(5000, () => {
-        /* ... */
-      });
-      signal.addEventListener("abort", () => clock.clearTimeout(id));
+    m.effect(loading, {
+      name: "scheduleWork",
+      fn: ({ signal, clock }) => {
+        const id = clock.setTimeout(5000, () => {
+          /* ... */
+        });
+        signal.addEventListener("abort", () => clock.clearTimeout(id));
+      },
     });
     m.on(loading, cancel, () => ({ state: success }));
   },
@@ -636,8 +678,11 @@ const actor = new Actor({
   initial: active,
   clock,
   setup: (m) => {
-    m.effect(active, ({ emit, clock }) => {
-      clock.setInterval(1000, () => emit(tick.create()));
+    m.effect(active, {
+      name: "startTicker",
+      fn: ({ emit, clock }) => {
+        clock.setInterval(1000, () => emit(tick.create()));
+      },
     });
     m.on(active, tick, () => {
       count++;
@@ -650,7 +695,7 @@ clock.advance(3500);
 expect(count).toBe(3); // fired at 1000, 2000, 3000
 ```
 
-**Anti-pattern — expecting single `advance` to fire interval once:**
+**Anti-pattern. Expecting single `advance` to fire interval once:**
 
 ```ts
 // ❌ advance(5000) fires interval at 1000, 2000, 3000, 4000, 5000
@@ -682,12 +727,12 @@ vp run mutation:core   # mutation score must stay ≥ 90
 
 **Test contract.** Behavior is pinned by four kinds of tests, split by filename:
 
-- `*.test.ts` — features and happy paths, hand-maintained.
-- `*.error.test.ts` — failure paths: warnings, budgets, abort, unregistered, the `__error` state.
-- `*.property.test.ts` — property-based invariants against a reference model (fast-check, replayable via `MANTAQ_SEED`).
-- `*.mutation.test.ts` — directed tests that kill specific mutants; regenerable and thrown away between stryker runs.
+- `*.test.ts`. Features and happy paths, hand-maintained.
+- `*.error.test.ts`. Failure paths: warnings, budgets, abort, unregistered, the `__error` state.
+- `*.property.test.ts`. Property-based invariants against a reference model (fast-check, replayable via `MANTAQ_SEED`).
+- `*.mutation.test.ts`. Directed tests that kill specific mutants. Regenerable and thrown away between stryker runs.
 
-Coverage is analyzed per test (stryker `perTest` coverage analysis) so every mutant is attributed to the test that pins it. The mutation break threshold is 90 — a change that drops the score below 90 fails the build.
+Coverage is analyzed per test (stryker `perTest` coverage analysis) so every mutant is attributed to the test that pins it. The mutation break threshold is 90. A change that drops the score below 90 fails the build.
 
 ## License