aifsmjs 0.5.1 → 0.5.3

package/README.md

@@ -164,13 +164,34 @@ aifsmjs follows the XState v5 two-phase pattern (`setup().createMachine()`): the
 
 ```typescript
 function defineMachine<
-  Ctx,
-  Evt extends { type: string },
-  States extends string,
->(def: MachineDef<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
+  Ctx = Record<string, never>,
+  Evt extends { type: string } = { type: string },
+  States extends string = string,
+>(def: MachineConfig<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
 ```
 
-Pure data builder. Freezes the whole definition and validates that `initial` exists in the `states` map.
+Pure data builder. Validates that `initial` exists in the `states` map and returns the (normalized) definition.
+
+`context` is **optional** — omit it for stateless machines and it defaults to `{}` (the type parameter defaults to `Record<string, never>`). Existing definitions that pass `context` are unaffected.
+
+```typescript
+// No context needed — defaults to {}
+const toggle = defineMachine({
+  id: "toggle",
+  initial: "off",
+  states: {
+    off: { on: { TOGGLE: "on" } },   // string shorthand, see below
+    on:  { on: { TOGGLE: "off" } },
+  },
+});
+```
+
+**String-shorthand transitions.** A transition value may be either the full object form or a bare target-state string (à la XState). The string is normalized to `{ target }` before processing — it carries no guard or actions:
+
+```typescript
+on: { NEXT: "green" }                 // shorthand for { target: "green" }
+on: { NEXT: [{ target: "a", guard: "g" }, "b"] }  // mixes with the object form
+```
 
 ### `createRuntime(def, impl, opts?)`
 
@@ -207,7 +228,7 @@ function step<C, E, S>(
 ): { snapshot: Snapshot<C, S>; effects: readonly Effect[] };
 ```
 
-**Pure function**. The invariant keeper for the whole library. It never dispatches effects, never mutates the snapshot, and never throws — a failing guard or unmapped event simply returns the original snapshot.
+**Pure function**. The invariant keeper for the whole library. It never dispatches effects and never mutates the snapshot. A failing guard or unmapped event simply returns the original snapshot unchanged. It does throw on misuse (`UnknownGuardError`, `UnknownActionError`, `AsyncGuardError`) so guard/action wiring errors surface at development time rather than silently passing.
 
 ### `assign(updater)`
 
@@ -266,7 +287,7 @@ const runtime = createRuntime(def, impl, {
 });
 ```
 
-Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects }`, all `structuredClone`d and frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
+Koa-style `(ctx, next) => void` pipeline. `ctx` is `{ prev, next, event, effects, changed }`, all deep-frozen. **Cannot cancel a transition** — `next()` must be called; the return value carries no meaning.
 
 ### `aifsmjs/replay` — Pure event log replay
 
@@ -285,14 +306,25 @@ Never dispatches effects. For PBT, time-travel debugging, and incident reproduct
 
 ```typescript
 import fc from "fast-check";
-import { commandsFromMachine, properties } from "aifsmjs/pbt";
+import { createRuntime } from "aifsmjs";
+import { commandsFromMachine, initialModel, properties } from "aifsmjs/pbt";
+
+// Use one of the six built-in generic properties, or assertAll for all at once:
+properties.replayEqualsFold(def, impl, {
+  NEXT: fc.constant({ type: "NEXT" as const }),
+});
 
+// Or build a custom property using commandsFromMachine:
 fc.assert(
   fc.property(
     commandsFromMachine(def, impl, {
       NEXT: fc.constant({ type: "NEXT" as const }),
     }),
-    (cmds) => properties.runDeterministic(def, impl, cmds),
+    (cmds) => {
+      const real = createRuntime(def, impl, { dispatchEffects: false });
+      fc.modelRun(() => ({ model: initialModel(def), real }), cmds);
+      return true;
+    },
   ),
 );
 ```
@@ -406,6 +438,8 @@ aifsmjs ships a few opinionated calls that look different from the typical FSM l
 - **Guards and reducers are sync.** A non-deterministic guard would break the PBT determinism property (#1 in the generic suite). Move async predicates into events: send `FETCH_REQUEST`, then later `FETCH_DONE` with the resolved value as payload.
 - **Effects are descriptors, not inline callbacks.** Actions enqueue `{ type, payload }` via `enqueue.effect(...)`; the runtime collects them and the dispatcher invokes user handlers. This keeps machine definitions serializable (JSON round-trippable when no inline functions are used), enables `replay()` to fold an event log into the same snapshot, and lets `inspect/persist` middleware capture effects for audit logs.
 - **Two factory paths coexist.** `setup<Ctx, Evt>().defineMachine(...)` is the type-friendly form (States inferred from `keyof states`). `createMachine(def, impl, opts?)` is the spec-style single-factory shortcut from the ai*js ecosystem review. Plain `defineMachine<Ctx, Evt, States>(def)` remains for explicit generic control. Pick whichever reads best at the call site.
+- **Transitions accept a string shorthand.** `on: { EVENT: "targetState" }` is sugar for `on: { EVENT: { target: "targetState" } }`, normalized in the resolver before any guard/action processing. The shorthand has no guard or actions; reach for the object form when you need them. It composes inside the array form too, so guard-fallthrough lists can mix `{ target, guard }` objects with bare target strings. The full object form is unchanged — this is purely additive.
+- **`context` is optional.** Omit it for stateless machines and it defaults to `{}` (`Ctx` defaults to `Record<string, never>`). Definitions that already pass `context` keep their inferred type and behave identically.
 - **`subscribe(listener)` and `on(type, fn, { signal, once })` both exist.** The typed `on()` matches the platform `EventTarget` semantics (signal + once) and emits `'transition'`, `'error'`, `'dispose'`. The older `subscribe()` keeps the React `useSyncExternalStore` shape — pass it directly. They are not exclusive.
 
 ---

package/README_ZHTW.md

@@ -163,13 +163,34 @@ aifsmjs 走 XState v5 `setup().createMachine()` 雙階段路線：definition 用
 
 ```typescript
 function defineMachine<
-  Ctx,
-  Evt extends { type: string },
-  States extends string,
->(def: MachineDef<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
+  Ctx = Record<string, never>,
+  Evt extends { type: string } = { type: string },
+  States extends string = string,
+>(def: MachineConfig<Ctx, Evt, States>): MachineDef<Ctx, Evt, States>;
 ```
 
-純資料 builder。會 freeze 整個 def 並驗證 `initial` 在 `states` 集合內。
+純資料 builder。會驗證 `initial` 在 `states` 集合內並回傳（正規化後的）def。
+
+`context` 為**選填**——無狀態機器可省略，會預設為 `{}`（型別參數預設為 `Record<string, never>`）。原本就有傳 `context` 的定義完全不受影響。
+
+```typescript
+// 不需要 context——預設為 {}
+const toggle = defineMachine({
+  id: "toggle",
+  initial: "off",
+  states: {
+    off: { on: { TOGGLE: "on" } },   // 字串簡寫，見下
+    on:  { on: { TOGGLE: "off" } },
+  },
+});
+```
+
+**字串簡寫 transition。** transition 的值可以是完整物件形式，也可以是單純的目標 state 字串（仿 XState）。字串會在進入任何 guard/action 處理前被正規化成 `{ target }`——它不帶 guard 或 actions：
+
+```typescript
+on: { NEXT: "green" }                 // 等同 { target: "green" }
+on: { NEXT: [{ target: "a", guard: "g" }, "b"] }  // 可與物件形式混用
+```
 
 ### `createRuntime(def, impl, opts?)`
 
@@ -206,7 +227,7 @@ function step<C, E, S>(
 ): { snapshot: Snapshot<C, S>; effects: readonly Effect[] };
 ```
 
-**Pure function**。整個 library 的 invariant 守護者。不會 dispatch effects、不會 mutate snapshot、不會丟錯——guard 沒過或 event 沒對應 transition 就回原 snapshot。
+**Pure function**。整個 library 的 invariant 守護者。不會 dispatch effects、不會 mutate snapshot。Guard 沒過或 event 沒對應 transition 就回原 snapshot（不改變）。誤用（`UnknownGuardError`、`UnknownActionError`、`AsyncGuardError`）才會丟錯，讓配接錯誤在開發期間立即浮現、不被靜默略過。
 
 ### `assign(updater)`
 
@@ -265,7 +286,7 @@ const runtime = createRuntime(def, impl, {
 });
 ```
 
-Koa-style `(ctx, next) => void` pipeline。`ctx` 是 `{ prev, next, event, effects }`，全部 `structuredClone + freeze`。**不能中止 transition**——`next()` 必呼叫，回傳值無語意。
+Koa-style `(ctx, next) => void` pipeline。`ctx` 是 `{ prev, next, event, effects, changed }`，全部 deep-frozen。**不能中止 transition**——`next()` 必呼叫，回傳值無語意。
 
 ### `aifsmjs/replay` — Pure event log replay
 
@@ -284,14 +305,25 @@ const finalSnap = replay(initialSnapshot, eventLog, def, impl);
 
 ```typescript
 import fc from "fast-check";
-import { commandsFromMachine, properties } from "aifsmjs/pbt";
+import { createRuntime } from "aifsmjs";
+import { commandsFromMachine, initialModel, properties } from "aifsmjs/pbt";
+
+// 用任一內建 generic property，或 assertAll 一次跑全部：
+properties.replayEqualsFold(def, impl, {
+  NEXT: fc.constant({ type: "NEXT" as const }),
+});
 
+// 或用 commandsFromMachine 自訂 property：
 fc.assert(
   fc.property(
     commandsFromMachine(def, impl, {
       NEXT: fc.constant({ type: "NEXT" as const }),
     }),
-    (cmds) => properties.runDeterministic(def, impl, cmds),
+    (cmds) => {
+      const real = createRuntime(def, impl, { dispatchEffects: false });
+      fc.modelRun(() => ({ model: initialModel(def), real }), cmds);
+      return true;
+    },
   ),
 );
 ```
@@ -398,8 +430,10 @@ aifsmjs 在幾個常見議題上做了刻意取捨，跟主流 FSM library 寫
 
 - **`send()` 是同步、回傳 `Snapshot` 而非 `Promise<Snapshot>`**。Pure `step()` 設計上就是 sync，`replay(initial, log)` 與 PBT shrinking 才能單純。Effect handler 仍可 async；runtime 觸發後忽略結果，async rejection 走 `'error'` event channel。要 await effect 完成的人可自己包一層 `Promise.all`。
 - **Guards / reducers 只能 sync**。非確定性 guard 會破壞 PBT determinism property (#1)。把 async 改寫成 event：先送 `FETCH_REQUEST`，handler 完成後送 `FETCH_DONE`，payload 帶結果。
-- **Effects 是描述子，不是 inline callback**。Action 透過 `enqueue.effect({ type, payload })` 排隊；runtime 收集後 dispatcher 才執行 user handler。好處：machine definition 可序列化（沒 inline fn 時 JSON round-trip）、`replay()` 可把 event log 摺成同樣 snapshot、`inspect/persist` middleware 抓得到 effects 做 audit log。
+- **Effects 是描述子，不是 inline callback**。Action 透過 `enqueue.effect(type, payload?)` 排隊；runtime 收集後 dispatcher 才執行 user handler。好處：machine definition 可序列化（沒 inline fn 時 JSON round-trip）、`replay()` 可把 event log 摺成同樣 snapshot、`inspect/persist` middleware 抓得到 effects 做 audit log。
 - **兩種 factory 並存**。`setup<Ctx, Evt>().defineMachine(...)` 是型別友善版（States 從 `keyof states` 推導）。`createMachine(def, impl, opts?)` 是來自 ai*js 生態 spec 的 single-factory 捷徑。顯式 `defineMachine<Ctx, Evt, States>(def)` 仍保留作完全顯式控制。看 call site 哪個讀起來順手就用哪個。
+- **transition 支援字串簡寫**。`on: { EVENT: "targetState" }` 是 `on: { EVENT: { target: "targetState" } }` 的語法糖，在 resolver 於任何 guard/action 處理前正規化。簡寫不帶 guard 或 actions；需要時改用物件形式。它也能在陣列形式中混用，所以 guard-fallthrough 清單可以同時放 `{ target, guard }` 物件與單純的目標字串。完整物件形式不變——此為純加法。
+- **`context` 為選填**。無狀態機器可省略，預設為 `{}`（`Ctx` 預設為 `Record<string, never>`）。原本就傳 `context` 的定義型別推導與行為完全相同。
 - **`subscribe(listener)` 與 `on(type, fn, { signal, once })` 並存**。Typed `on()` 對齊平台 `EventTarget` 語意（signal + once），emit `'transition'`、`'error'`、`'dispose'`。原本的 `subscribe()` 保留 React `useSyncExternalStore` shape，可直接傳。兩者不互斥。
 
 ---

package/dist/effects/index.d.cts

@@ -1,4 +1,4 @@
-import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-CGKk6Rur.cjs';
+import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-DIM7QTtf.cjs';
 
 /**
  * Build a closure-based Enqueuer that pushes effects into the supplied sink.

package/dist/effects/index.d.ts

@@ -1,4 +1,4 @@
-import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-CGKk6Rur.js';
+import { c as Enqueuer, E as Effect, b as EffectHandler } from '../types-DIM7QTtf.js';
 
 /**
  * Build a closure-based Enqueuer that pushes effects into the supplied sink.

package/dist/guards/index.d.cts

@@ -1,4 +1,4 @@
-import { e as GuardRef, G as Guard } from '../types-CGKk6Rur.cjs';
+import { e as GuardRef, G as Guard } from '../types-DIM7QTtf.cjs';
 
 /** Logical AND over guards. Short-circuits on the first `false`. */
 declare function and<Ctx, Evt>(items: readonly GuardRef<Ctx, Evt>[]): Guard<Ctx, Evt>;

package/dist/guards/index.d.ts

@@ -1,4 +1,4 @@
-import { e as GuardRef, G as Guard } from '../types-CGKk6Rur.js';
+import { e as GuardRef, G as Guard } from '../types-DIM7QTtf.js';
 
 /** Logical AND over guards. Short-circuits on the first `false`. */
 declare function and<Ctx, Evt>(items: readonly GuardRef<Ctx, Evt>[]): Guard<Ctx, Evt>;

package/dist/index.cjs

@@ -52,6 +52,23 @@ function evalGuard(ref, context, event, impl, value) {
   return result;
 }
 
+// src/fsm/resolver.ts
+function normalizeTransition(entry) {
+  return typeof entry === "string" ? { target: entry } : entry;
+}
+function normalizeTransitions(entry) {
+  if (entry === void 0) return [];
+  if (Array.isArray(entry)) {
+    return entry.some((t) => typeof t === "string") ? entry.map((t) => normalizeTransition(t)) : entry;
+  }
+  return [normalizeTransition(entry)];
+}
+function resolveTransitions(def, stateValue, eventType) {
+  const state = def.states[stateValue];
+  if (!state || !state.on) return [];
+  return normalizeTransitions(state.on[eventType]);
+}
+
 // src/effects/enqueuer.ts
 function createEnqueuer(sink) {
   return Object.freeze({
@@ -154,8 +171,7 @@ function step(def, snapshot, event, impl) {
   if (!state) {
     return Object.freeze({ snapshot, effects: [], changed: false });
   }
-  const candidates = state.on?.[event.type];
-  const candidateList = candidates ? Array.isArray(candidates) ? candidates : [candidates] : [];
+  const candidateList = normalizeTransitions(state.on?.[event.type]);
   const chosen = pickTransition(candidateList, snapshot.context, event, impl, snapshot.value);
   if (!chosen) {
     return Object.freeze({ snapshot, effects: [], changed: false });
@@ -282,9 +298,8 @@ function createRuntime(def, impl, opts = {}) {
   function findChosenIsExternal(value, event, context) {
     const state = def.states[value];
     if (!state?.on) return false;
-    const candidates = state.on[event.type];
-    if (!candidates) return false;
-    const list = Array.isArray(candidates) ? candidates : [candidates];
+    const list = normalizeTransitions(state.on[event.type]);
+    if (list.length === 0) return false;
     for (const t of list) {
       if (!t.guard || evalGuard(t.guard, context, event, impl, value)) {
         return t.target !== void 0;
@@ -385,9 +400,8 @@ function createRuntime(def, impl, opts = {}) {
     if (disposed || snapshot.status === "final") return false;
     const state = def.states[snapshot.value];
     if (!state) return false;
-    const candidates = state.on?.[event.type];
-    if (!candidates) return false;
-    const list = Array.isArray(candidates) ? candidates : [candidates];
+    const list = normalizeTransitions(state.on?.[event.type]);
+    if (list.length === 0) return false;
     for (const t of list) {
       if (!t.guard) return true;
       if (evalGuard(t.guard, snapshot.context, event, impl, snapshot.value)) return true;
@@ -514,7 +528,7 @@ function validateDefinition(def) {
     }
     if (!stateDef.on) continue;
     for (const [evtType, entry] of Object.entries(stateDef.on)) {
-      const transitions = Array.isArray(entry) ? entry : [entry];
+      const transitions = normalizeTransitions(entry);
       for (const t of transitions) {
         if (t.target !== void 0 && !stateKeys.includes(t.target)) {
           throw new InvalidDefinitionError(
@@ -531,13 +545,14 @@ function validateDefinition(def) {
   }
 }
 function defineMachine(def) {
-  validateDefinition(def);
-  return def;
+  const normalized = !("context" in def) ? { ...def, context: {} } : def;
+  validateDefinition(normalized);
+  return normalized;
 }
 function setup() {
   return {
     defineMachine: (def) => {
-      const cast = def;
+      const cast = !("context" in def) ? { ...def, context: {} } : def;
       validateDefinition(cast);
       return cast;
     }
@@ -555,15 +570,6 @@ function createMachine(def, impl, opts) {
   return createRuntime(defineMachine(def), impl, opts ?? {});
 }
 
-// src/fsm/resolver.ts
-function resolveTransitions(def, stateValue, eventType) {
-  const state = def.states[stateValue];
-  if (!state || !state.on) return [];
-  const entry = state.on[eventType];
-  if (!entry) return [];
-  return Array.isArray(entry) ? entry : [entry];
-}
-
 exports.AsyncGuardError = AsyncGuardError;
 exports.InvalidDefinitionError = InvalidDefinitionError;
 exports.RESET_EVENT_TYPE = RESET_EVENT_TYPE;
@@ -582,6 +588,8 @@ exports.freezeSnapshot = freezeSnapshot;
 exports.initialSnapshot = initialSnapshot;
 exports.isAsyncGuardFn = isAsyncGuardFn;
 exports.mergeContext = mergeContext;
+exports.normalizeTransition = normalizeTransition;
+exports.normalizeTransitions = normalizeTransitions;
 exports.resolveGuard = resolveGuard;
 exports.resolveTransitions = resolveTransitions;
 exports.setup = setup;