@pyreon/machine 0.11.3 → 0.11.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/machine",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Reactive state machines for Pyreon — constrained signals with type-safe transitions",
   "license": "MIT",
   "repository": {
@@ -41,11 +41,11 @@
     "lint": "biome check ."
   },
   "peerDependencies": {
-    "@pyreon/reactivity": "^0.11.3"
+    "@pyreon/reactivity": "^0.11.4"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.3",
-    "@pyreon/reactivity": "^0.11.3",
+    "@pyreon/reactivity": "^0.11.4",
     "@vitus-labs/tools-lint": "^1.11.0"
   }
 }

package/src/tests/api.test.ts

@@ -0,0 +1,362 @@
+import { computed, effect } from "@pyreon/reactivity"
+import { describe, expect, it, vi } from "vitest"
+import { createMachine } from "../index"
+
+describe("createMachine — nextEvents()", () => {
+  it("returns valid events from current state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { FETCH: "loading", RESET: "idle" } },
+        loading: { on: { SUCCESS: "done", ERROR: "error" } },
+        done: {},
+        error: {},
+      },
+    })
+    expect(m.nextEvents()).toEqual(expect.arrayContaining(["FETCH", "RESET"]))
+    expect(m.nextEvents()).toHaveLength(2)
+  })
+
+  it("returns empty array for final states (no transitions)", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { DONE: "finished" } },
+        finished: {},
+      },
+    })
+    m.send("DONE")
+    expect(m.nextEvents()).toEqual([])
+  })
+
+  it("updates after transition", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle", PAUSE: "paused" } },
+        paused: { on: { RESUME: "running" } },
+      },
+    })
+
+    expect(m.nextEvents()).toEqual(["START"])
+
+    m.send("START")
+    expect(m.nextEvents()).toEqual(expect.arrayContaining(["STOP", "PAUSE"]))
+
+    m.send("PAUSE")
+    expect(m.nextEvents()).toEqual(["RESUME"])
+  })
+
+  it("is reactive in effects", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: { on: { STOP: "idle", PAUSE: "paused" } },
+        paused: {},
+      },
+    })
+    const results: string[][] = []
+
+    effect(() => {
+      results.push(m.nextEvents())
+    })
+
+    m.send("GO")
+    expect(results).toHaveLength(2)
+    expect(results[0]).toEqual(["GO"])
+    expect(results[1]).toEqual(expect.arrayContaining(["STOP", "PAUSE"]))
+  })
+
+  it("includes guarded event names", () => {
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: {
+            SUBMIT: { target: "submitting", guard: () => false },
+            CANCEL: "cancelled",
+          },
+        },
+        submitting: {},
+        cancelled: {},
+      },
+    })
+    // nextEvents returns all event keys, even guarded ones
+    expect(m.nextEvents()).toEqual(expect.arrayContaining(["SUBMIT", "CANCEL"]))
+  })
+})
+
+describe("createMachine — can()", () => {
+  it("returns true for valid events from current state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle" } },
+      },
+    })
+    expect(m.can("START")).toBe(true)
+  })
+
+  it("returns false for events not in current state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle" } },
+      },
+    })
+    expect(m.can("STOP")).toBe(false)
+  })
+
+  it("returns false for completely unknown events", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: {},
+      },
+    })
+    expect(m.can("NONEXISTENT" as any)).toBe(false)
+  })
+
+  it("returns false when in a final state (no transitions)", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { DONE: "finished" } },
+        finished: {},
+      },
+    })
+    m.send("DONE")
+    expect(m.can("DONE")).toBe(false)
+    expect(m.can("START" as any)).toBe(false)
+  })
+
+  it("returns true for guarded transitions (guard not evaluated by can())", () => {
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: { SUBMIT: { target: "submitting", guard: () => false } },
+        },
+        submitting: {},
+      },
+    })
+    // can() checks existence only, not guard
+    expect(m.can("SUBMIT")).toBe(true)
+  })
+
+  it("is reactive — updates when state changes", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle" } },
+      },
+    })
+    const canStop: boolean[] = []
+
+    effect(() => {
+      canStop.push(m.can("STOP"))
+    })
+
+    expect(canStop).toEqual([false])
+
+    m.send("START")
+    expect(canStop).toEqual([false, true])
+
+    m.send("STOP")
+    expect(canStop).toEqual([false, true, false])
+  })
+
+  it("works in computed", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle" } },
+      },
+    })
+
+    const canStart = computed(() => m.can("START"))
+    expect(canStart()).toBe(true)
+
+    m.send("START")
+    expect(canStart()).toBe(false)
+  })
+})
+
+describe("createMachine — reset()", () => {
+  it("returns to initial state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: { on: { STOP: "idle" } },
+      },
+    })
+    m.send("START")
+    expect(m()).toBe("running")
+
+    m.reset()
+    expect(m()).toBe("idle")
+  })
+
+  it("reset from deeply nested state", () => {
+    const m = createMachine({
+      initial: "step1",
+      states: {
+        step1: { on: { NEXT: "step2" } },
+        step2: { on: { NEXT: "step3" } },
+        step3: { on: { NEXT: "step4" } },
+        step4: {},
+      },
+    })
+    m.send("NEXT")
+    m.send("NEXT")
+    m.send("NEXT")
+    expect(m()).toBe("step4")
+
+    m.reset()
+    expect(m()).toBe("step1")
+  })
+
+  it("reset is reactive", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+      },
+    })
+    const states: string[] = []
+
+    effect(() => {
+      states.push(m())
+    })
+
+    m.send("GO")
+    m.reset()
+
+    expect(states).toEqual(["idle", "active", "idle"])
+  })
+
+  it("reset does not fire onEnter for initial state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: { on: { BACK: "idle" } },
+      },
+    })
+    const fn = vi.fn()
+    m.onEnter("idle", fn)
+
+    m.send("GO")
+    m.reset() // Sets state directly, does not go through send()
+    // reset() uses current.set() directly, not send(), so no enter callback
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("after reset, transitions work from initial state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: { on: { DONE: "finished" } },
+        finished: {},
+      },
+    })
+    m.send("GO")
+    m.send("DONE")
+    expect(m()).toBe("finished")
+
+    m.reset()
+    expect(m()).toBe("idle")
+
+    m.send("GO")
+    expect(m()).toBe("active")
+  })
+
+  it("reset from initial state is a no-op (same value)", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+      },
+    })
+
+    m.reset()
+    expect(m()).toBe("idle")
+  })
+})
+
+describe("createMachine — dispose()", () => {
+  it("removes all onEnter listeners", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: { on: { GO: "a" } },
+      },
+    })
+    const fn = vi.fn()
+    m.onEnter("b", fn)
+
+    m.dispose()
+
+    m.send("GO")
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("removes all onTransition listeners", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: {},
+      },
+    })
+    const fn = vi.fn()
+    m.onTransition(fn)
+
+    m.dispose()
+
+    m.send("GO")
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("machine still transitions after dispose (only listeners removed)", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: {},
+      },
+    })
+    m.onEnter("b", vi.fn())
+    m.onTransition(vi.fn())
+
+    m.dispose()
+
+    m.send("GO")
+    expect(m()).toBe("b") // transitions still work
+  })
+
+  it("dispose is idempotent", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: {},
+      },
+    })
+    m.dispose()
+    m.dispose() // should not throw
+    expect(m()).toBe("a")
+  })
+})

package/src/tests/guards.test.ts

@@ -0,0 +1,189 @@
+import { signal } from "@pyreon/reactivity"
+import { describe, expect, it, vi } from "vitest"
+import { createMachine } from "../index"
+
+describe("createMachine — guard conditions", () => {
+  it("transitions when guard returns true", () => {
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: { SUBMIT: { target: "submitting", guard: () => true } },
+        },
+        submitting: {},
+      },
+    })
+    m.send("SUBMIT")
+    expect(m()).toBe("submitting")
+  })
+
+  it("blocks transition when guard returns false", () => {
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: { SUBMIT: { target: "submitting", guard: () => false } },
+        },
+        submitting: {},
+      },
+    })
+    m.send("SUBMIT")
+    expect(m()).toBe("editing")
+  })
+
+  it("guard receives event payload", () => {
+    const guardFn = vi.fn((payload?: unknown) => {
+      return (payload as any)?.amount > 0
+    })
+
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: {
+          on: { PAY: { target: "processing", guard: guardFn } },
+        },
+        processing: {},
+      },
+    })
+
+    m.send("PAY", { amount: 0 })
+    expect(m()).toBe("idle")
+    expect(guardFn).toHaveBeenCalledWith({ amount: 0 })
+
+    m.send("PAY", { amount: 100 })
+    expect(m()).toBe("processing")
+    expect(guardFn).toHaveBeenCalledWith({ amount: 100 })
+  })
+
+  it("guard without payload receives undefined", () => {
+    const guardFn = vi.fn(() => true)
+
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: {
+          on: { GO: { target: "active", guard: guardFn } },
+        },
+        active: {},
+      },
+    })
+
+    m.send("GO")
+    expect(guardFn).toHaveBeenCalledWith(undefined)
+  })
+
+  it("guard with reactive signal dependency", () => {
+    const isValid = signal(false)
+
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: {
+            SUBMIT: { target: "submitting", guard: () => isValid.peek() },
+          },
+        },
+        submitting: {},
+      },
+    })
+
+    m.send("SUBMIT")
+    expect(m()).toBe("editing") // guard blocks
+
+    isValid.set(true)
+    m.send("SUBMIT")
+    expect(m()).toBe("submitting") // guard passes
+  })
+
+  it("guard can check multiple conditions", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: {
+          on: {
+            START: {
+              target: "running",
+              guard: (payload?: unknown) => {
+                const p = payload as { ready: boolean; count: number } | undefined
+                return p !== undefined && p.ready && p.count > 0
+              },
+            },
+          },
+        },
+        running: {},
+      },
+    })
+
+    m.send("START", { ready: false, count: 5 })
+    expect(m()).toBe("idle")
+
+    m.send("START", { ready: true, count: 0 })
+    expect(m()).toBe("idle")
+
+    m.send("START", { ready: true, count: 5 })
+    expect(m()).toBe("running")
+  })
+
+  it("different events on same state can have different guards", () => {
+    const m = createMachine({
+      initial: "editing",
+      states: {
+        editing: {
+          on: {
+            SAVE: { target: "saved", guard: () => true },
+            PUBLISH: { target: "published", guard: () => false },
+          },
+        },
+        saved: {},
+        published: {},
+      },
+    })
+
+    m.send("PUBLISH")
+    expect(m()).toBe("editing") // guard blocks
+
+    m.send("SAVE")
+    expect(m()).toBe("saved") // guard passes
+  })
+
+  it("guard blocks do not fire onEnter or onTransition", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: { target: "b", guard: () => false } } },
+        b: {},
+      },
+    })
+
+    const enterFn = vi.fn()
+    const transitionFn = vi.fn()
+    m.onEnter("b", enterFn)
+    m.onTransition(transitionFn)
+
+    m.send("GO")
+    expect(enterFn).not.toHaveBeenCalled()
+    expect(transitionFn).not.toHaveBeenCalled()
+  })
+
+  it("mixing guarded and non-guarded transitions", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: {
+          on: {
+            FETCH: "loading", // no guard
+            ADMIN: { target: "admin", guard: () => false }, // guarded
+          },
+        },
+        loading: {},
+        admin: {},
+      },
+    })
+
+    m.send("ADMIN")
+    expect(m()).toBe("idle") // blocked
+
+    m.send("FETCH")
+    expect(m()).toBe("loading") // no guard, passes
+  })
+})

package/src/tests/listeners.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, it, vi } from "vitest"
+import { createMachine } from "../index"
+
+describe("createMachine — onEnter callbacks", () => {
+  it("fires callback when entering the specified state", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { LOAD: "loading" } },
+        loading: { on: { DONE: "idle" } },
+      },
+    })
+    const entered: string[] = []
+
+    m.onEnter("loading", (event) => {
+      entered.push(event.type)
+    })
+
+    m.send("LOAD")
+    expect(entered).toEqual(["LOAD"])
+  })
+
+  it("does not fire for other state entries", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: { on: { GO: "c" } },
+        c: {},
+      },
+    })
+    const fn = vi.fn()
+    m.onEnter("c", fn)
+
+    m.send("GO") // a -> b
+    expect(fn).not.toHaveBeenCalled()
+
+    m.send("GO") // b -> c
+    expect(fn).toHaveBeenCalledOnce()
+  })
+
+  it("receives event payload", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { SELECT: "selected" } },
+        selected: {},
+      },
+    })
+    let received: unknown = null
+
+    m.onEnter("selected", (event) => {
+      received = event.payload
+    })
+
+    m.send("SELECT", { id: 42, name: "item" })
+    expect(received).toEqual({ id: 42, name: "item" })
+  })
+
+  it("fires on self-transitions", () => {
+    const m = createMachine({
+      initial: "counting",
+      states: {
+        counting: { on: { INC: "counting" } },
+      },
+    })
+    const fn = vi.fn()
+    m.onEnter("counting", fn)
+
+    m.send("INC")
+    m.send("INC")
+    m.send("INC")
+
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it("unsubscribe function stops future callbacks", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: { on: { GO: "a" } },
+      },
+    })
+    const fn = vi.fn()
+    const unsub = m.onEnter("b", fn)
+
+    m.send("GO") // a -> b
+    expect(fn).toHaveBeenCalledOnce()
+
+    unsub()
+
+    m.send("GO") // b -> a
+    m.send("GO") // a -> b again
+    expect(fn).toHaveBeenCalledOnce() // not called again
+  })
+
+  it("multiple listeners for same state all fire", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+      },
+    })
+    const fn1 = vi.fn()
+    const fn2 = vi.fn()
+    const fn3 = vi.fn()
+
+    m.onEnter("active", fn1)
+    m.onEnter("active", fn2)
+    m.onEnter("active", fn3)
+
+    m.send("GO")
+    expect(fn1).toHaveBeenCalledOnce()
+    expect(fn2).toHaveBeenCalledOnce()
+    expect(fn3).toHaveBeenCalledOnce()
+  })
+
+  it("onEnter for a state that is never entered is never called", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+        unreachable: {},
+      },
+    })
+    const fn = vi.fn()
+    m.onEnter("unreachable", fn)
+
+    m.send("GO")
+    expect(fn).not.toHaveBeenCalled()
+  })
+})
+
+describe("createMachine — onTransition callbacks", () => {
+  it("fires on every state transition", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { NEXT: "b" } },
+        b: { on: { NEXT: "c" } },
+        c: {},
+      },
+    })
+    const transitions: [string, string, string][] = []
+
+    m.onTransition((from, to, event) => {
+      transitions.push([from, to, event.type])
+    })
+
+    m.send("NEXT") // a -> b
+    m.send("NEXT") // b -> c
+
+    expect(transitions).toEqual([
+      ["a", "b", "NEXT"],
+      ["b", "c", "NEXT"],
+    ])
+  })
+
+  it("does not fire when event is ignored (no valid transition)", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "running" } },
+        running: {},
+      },
+    })
+    const fn = vi.fn()
+    m.onTransition(fn)
+
+    m.send("STOP" as any) // invalid
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("does not fire when guard blocks transition", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: {
+          on: { GO: { target: "active", guard: () => false } },
+        },
+        active: {},
+      },
+    })
+    const fn = vi.fn()
+    m.onTransition(fn)
+
+    m.send("GO")
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it("receives event payload", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { LOAD: "loading" } },
+        loading: {},
+      },
+    })
+    let receivedPayload: unknown = null
+
+    m.onTransition((_from, _to, event) => {
+      receivedPayload = event.payload
+    })
+
+    m.send("LOAD", { url: "/api/data" })
+    expect(receivedPayload).toEqual({ url: "/api/data" })
+  })
+
+  it("fires on self-transitions", () => {
+    const m = createMachine({
+      initial: "counting",
+      states: {
+        counting: { on: { INC: "counting" } },
+      },
+    })
+    const fn = vi.fn()
+    m.onTransition(fn)
+
+    m.send("INC")
+    m.send("INC")
+
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(fn).toHaveBeenCalledWith(
+      "counting",
+      "counting",
+      expect.objectContaining({ type: "INC" }),
+    )
+  })
+
+  it("unsubscribe stops future callbacks", () => {
+    const m = createMachine({
+      initial: "a",
+      states: {
+        a: { on: { GO: "b" } },
+        b: { on: { GO: "a" } },
+      },
+    })
+    const fn = vi.fn()
+    const unsub = m.onTransition(fn)
+
+    m.send("GO")
+    expect(fn).toHaveBeenCalledOnce()
+
+    unsub()
+    m.send("GO")
+    m.send("GO")
+    expect(fn).toHaveBeenCalledOnce()
+  })
+
+  it("multiple transition listeners all fire", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+      },
+    })
+    const fn1 = vi.fn()
+    const fn2 = vi.fn()
+
+    m.onTransition(fn1)
+    m.onTransition(fn2)
+
+    m.send("GO")
+    expect(fn1).toHaveBeenCalledOnce()
+    expect(fn2).toHaveBeenCalledOnce()
+  })
+
+  it("onTransition fires before onEnter", () => {
+    const m = createMachine({
+      initial: "idle",
+      states: {
+        idle: { on: { GO: "active" } },
+        active: {},
+      },
+    })
+    const order: string[] = []
+
+    m.onTransition(() => order.push("transition"))
+    m.onEnter("active", () => order.push("enter"))
+
+    m.send("GO")
+    expect(order).toEqual(["transition", "enter"])
+  })
+})