@praxisjs/fsm 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @praxisjs/fsm
 
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [fe39901]
+  - @praxisjs/core@0.4.1
+
 ## 0.2.1
 
 ### Patch Changes

package/dist/__tests__/decorators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decorators.test.d.ts.map

package/dist/__tests__/decorators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/decorators.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/decorators.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi } from "vitest";
+import { Transition, StateMachine } from "../decorators";
+import { createMachine } from "../machine";
+const TOGGLE_DEF = {
+    initial: "off",
+    states: {
+        off: { on: { toggle: "on" } },
+        on: { on: { toggle: "off" } },
+    },
+};
+// ── StateMachine ──────────────────────────────────────────────────────────────
+describe("StateMachine decorator", () => {
+    it("adds a machine property via prototype", () => {
+        class Light {
+        }
+        StateMachine(TOGGLE_DEF)(Light, {});
+        const instance = new Light();
+        expect(instance.machine).toBeDefined();
+        expect(instance.machine.state()).toBe("off");
+    });
+    it("returns a separate machine per instance", () => {
+        class Bulb {
+        }
+        StateMachine(TOGGLE_DEF)(Bulb, {});
+        const a = new Bulb();
+        const b = new Bulb();
+        a.machine.send("toggle");
+        expect(a.machine.state()).toBe("on");
+        expect(b.machine.state()).toBe("off");
+    });
+    it("uses a custom property key", () => {
+        class Widget {
+        }
+        StateMachine(TOGGLE_DEF, "fsm")(Widget, {});
+        const instance = new Widget();
+        expect(instance.fsm).toBeDefined();
+    });
+    it("returns the same instance on repeated access", () => {
+        class Btn {
+        }
+        StateMachine(TOGGLE_DEF)(Btn, {});
+        const instance = new Btn();
+        expect(instance.machine).toBe(instance.machine);
+    });
+});
+// ── Transition ────────────────────────────────────────────────────────────────
+describe("Transition decorator", () => {
+    it("calls the original method when send succeeds", () => {
+        const original = vi.fn(() => "ran");
+        const wrapped = Transition("machine", "toggle")(original, {});
+        const instance = {
+            machine: createMachine(TOGGLE_DEF),
+        };
+        wrapped.call(instance);
+        expect(original).toHaveBeenCalled();
+    });
+    it("returns without calling method when machine is missing", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const original = vi.fn();
+        const wrapped = Transition("machine", "toggle")(original, {});
+        wrapped.call({});
+        expect(original).not.toHaveBeenCalled();
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Transition]"));
+        warn.mockRestore();
+    });
+    it("does not call method when transition is invalid", () => {
+        const original = vi.fn();
+        const wrapped = Transition("machine", "toggle")(original, {});
+        const instance = {
+            machine: createMachine({ initial: "on", states: { on: {} } }),
+        };
+        // "toggle" is not a valid event from "on" state
+        wrapped.call(instance);
+        expect(original).not.toHaveBeenCalled();
+    });
+    it("passes through arguments to the original method", () => {
+        const original = vi.fn((_x) => undefined);
+        const wrapped = Transition("machine", "toggle")(original, {});
+        const instance = { machine: createMachine(TOGGLE_DEF) };
+        wrapped.call(instance, 42);
+        expect(original).toHaveBeenCalledWith(42);
+    });
+});
+//# sourceMappingURL=decorators.test.js.map

package/dist/__tests__/decorators.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.js","sourceRoot":"","sources":["../../src/__tests__/decorators.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/machine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=machine.test.d.ts.map

package/dist/__tests__/machine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/machine.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/machine.test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi } from "vitest";
+import { createMachine } from "../machine";
+function trafficLight() {
+    return createMachine({
+        initial: "red",
+        states: {
+            red: { on: { GO: "green" } },
+            green: { on: { SLOW: "yellow" } },
+            yellow: { on: { STOP: "red" } },
+        },
+    });
+}
+describe("createMachine", () => {
+    it("initializes in the given state", () => {
+        const m = trafficLight();
+        expect(m.state()).toBe("red");
+    });
+    it("transitions on a valid event", () => {
+        const m = trafficLight();
+        m.send("GO");
+        expect(m.state()).toBe("green");
+    });
+    it("returns true from send() on valid transition", () => {
+        const m = trafficLight();
+        expect(m.send("GO")).toBe(true);
+    });
+    it("returns false from send() on invalid event", () => {
+        const m = trafficLight();
+        expect(m.send("SLOW")).toBe(false); // SLOW is not valid in red
+    });
+    it("does not change state on invalid event", () => {
+        const m = trafficLight();
+        m.send("STOP"); // invalid in red
+        expect(m.state()).toBe("red");
+    });
+    it("can() returns true for valid events", () => {
+        const m = trafficLight();
+        expect(m.can("GO")).toBe(true);
+    });
+    it("can() returns false for invalid events", () => {
+        const m = trafficLight();
+        expect(m.can("SLOW")).toBe(false);
+    });
+    it("is() checks current state", () => {
+        const m = trafficLight();
+        expect(m.is("red")).toBe(true);
+        expect(m.is("green")).toBe(false);
+    });
+    it("tracks history of transitions", () => {
+        const m = trafficLight();
+        m.send("GO");
+        m.send("SLOW");
+        const h = m.history();
+        expect(h).toHaveLength(2);
+        expect(h[0]).toEqual({ from: "red", event: "GO", to: "green" });
+        expect(h[1]).toEqual({ from: "green", event: "SLOW", to: "yellow" });
+    });
+    it("resets to initial state and clears history", () => {
+        const m = trafficLight();
+        m.send("GO");
+        m.send("SLOW");
+        m.reset();
+        expect(m.state()).toBe("red");
+        expect(m.history()).toHaveLength(0);
+    });
+    it("calls onEnter on entering a state", () => {
+        const onEnter = vi.fn();
+        const m = createMachine({
+            initial: "idle",
+            states: {
+                idle: { on: { START: "active" } },
+                active: { onEnter },
+            },
+        });
+        m.send("START");
+        expect(onEnter).toHaveBeenCalledOnce();
+    });
+    it("calls onExit on leaving a state", () => {
+        const onExit = vi.fn();
+        const m = createMachine({
+            initial: "idle",
+            states: {
+                idle: { on: { START: "active" }, onExit },
+                active: {},
+            },
+        });
+        m.send("START");
+        expect(onExit).toHaveBeenCalledOnce();
+    });
+    it("calls onTransition callback", () => {
+        const onTransition = vi.fn();
+        const m = createMachine({
+            initial: "a",
+            states: {
+                a: { on: { NEXT: "b" } },
+                b: {},
+            },
+            onTransition,
+        });
+        m.send("NEXT");
+        expect(onTransition).toHaveBeenCalledWith("a", "NEXT", "b");
+    });
+});
+//# sourceMappingURL=machine.test.js.map

package/dist/__tests__/machine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.test.js","sourceRoot":"","sources":["../../src/__tests__/machine.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/fsm",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,7 +14,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@praxisjs/core": "0.4.0",
+    "@praxisjs/core": "0.4.1",
     "@praxisjs/shared": "0.2.0"
   },
   "scripts": {

package/src/__tests__/decorators.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { Transition, StateMachine } from "../decorators";
+import { createMachine } from "../machine";
+
+const TOGGLE_DEF = {
+  initial: "off" as const,
+  states: {
+    off: { on: { toggle: "on" as const } },
+    on: { on: { toggle: "off" as const } },
+  },
+} as const;
+
+// ── StateMachine ──────────────────────────────────────────────────────────────
+
+describe("StateMachine decorator", () => {
+  it("adds a machine property via prototype", () => {
+    class Light {}
+    StateMachine(TOGGLE_DEF)(Light, {} as ClassDecoratorContext);
+    const instance = new Light() as Record<string, unknown>;
+    expect(instance.machine).toBeDefined();
+    expect((instance.machine as ReturnType<typeof createMachine>).state()).toBe("off");
+  });
+
+  it("returns a separate machine per instance", () => {
+    class Bulb {}
+    StateMachine(TOGGLE_DEF)(Bulb, {} as ClassDecoratorContext);
+    const a = new Bulb() as Record<string, unknown>;
+    const b = new Bulb() as Record<string, unknown>;
+    (a.machine as ReturnType<typeof createMachine>).send("toggle");
+    expect((a.machine as ReturnType<typeof createMachine>).state()).toBe("on");
+    expect((b.machine as ReturnType<typeof createMachine>).state()).toBe("off");
+  });
+
+  it("uses a custom property key", () => {
+    class Widget {}
+    StateMachine(TOGGLE_DEF, "fsm")(Widget, {} as ClassDecoratorContext);
+    const instance = new Widget() as Record<string, unknown>;
+    expect(instance.fsm).toBeDefined();
+  });
+
+  it("returns the same instance on repeated access", () => {
+    class Btn {}
+    StateMachine(TOGGLE_DEF)(Btn, {} as ClassDecoratorContext);
+    const instance = new Btn() as Record<string, unknown>;
+    expect(instance.machine).toBe(instance.machine);
+  });
+});
+
+// ── Transition ────────────────────────────────────────────────────────────────
+
+describe("Transition decorator", () => {
+  it("calls the original method when send succeeds", () => {
+    const original = vi.fn(() => "ran");
+    const wrapped = Transition("machine", "toggle")(
+      original,
+      {} as ClassMethodDecoratorContext,
+    );
+    const instance = {
+      machine: createMachine(TOGGLE_DEF),
+    } as Record<string, unknown>;
+    wrapped.call(instance);
+    expect(original).toHaveBeenCalled();
+  });
+
+  it("returns without calling method when machine is missing", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const original = vi.fn();
+    const wrapped = Transition("machine", "toggle")(
+      original,
+      {} as ClassMethodDecoratorContext,
+    );
+    wrapped.call({} as Record<string, unknown>);
+    expect(original).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Transition]"));
+    warn.mockRestore();
+  });
+
+  it("does not call method when transition is invalid", () => {
+    const original = vi.fn();
+    const wrapped = Transition("machine", "toggle")(
+      original,
+      {} as ClassMethodDecoratorContext,
+    );
+    const instance = {
+      machine: createMachine({ initial: "on" as const, states: { on: {} } }),
+    } as Record<string, unknown>;
+    // "toggle" is not a valid event from "on" state
+    wrapped.call(instance);
+    expect(original).not.toHaveBeenCalled();
+  });
+
+  it("passes through arguments to the original method", () => {
+    const original = vi.fn((_x: unknown) => undefined);
+    const wrapped = Transition("machine", "toggle")(
+      original,
+      {} as ClassMethodDecoratorContext,
+    );
+    const instance = { machine: createMachine(TOGGLE_DEF) } as Record<string, unknown>;
+    wrapped.call(instance, 42);
+    expect(original).toHaveBeenCalledWith(42);
+  });
+});

package/src/__tests__/machine.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { createMachine } from "../machine";
+
+type TrafficState = "red" | "green" | "yellow";
+type TrafficEvent = "GO" | "SLOW" | "STOP";
+
+function trafficLight() {
+  return createMachine<TrafficState, TrafficEvent>({
+    initial: "red",
+    states: {
+      red: { on: { GO: "green" } },
+      green: { on: { SLOW: "yellow" } },
+      yellow: { on: { STOP: "red" } },
+    },
+  });
+}
+
+describe("createMachine", () => {
+  it("initializes in the given state", () => {
+    const m = trafficLight();
+    expect(m.state()).toBe("red");
+  });
+
+  it("transitions on a valid event", () => {
+    const m = trafficLight();
+    m.send("GO");
+    expect(m.state()).toBe("green");
+  });
+
+  it("returns true from send() on valid transition", () => {
+    const m = trafficLight();
+    expect(m.send("GO")).toBe(true);
+  });
+
+  it("returns false from send() on invalid event", () => {
+    const m = trafficLight();
+    expect(m.send("SLOW")).toBe(false); // SLOW is not valid in red
+  });
+
+  it("does not change state on invalid event", () => {
+    const m = trafficLight();
+    m.send("STOP"); // invalid in red
+    expect(m.state()).toBe("red");
+  });
+
+  it("can() returns true for valid events", () => {
+    const m = trafficLight();
+    expect(m.can("GO")).toBe(true);
+  });
+
+  it("can() returns false for invalid events", () => {
+    const m = trafficLight();
+    expect(m.can("SLOW")).toBe(false);
+  });
+
+  it("is() checks current state", () => {
+    const m = trafficLight();
+    expect(m.is("red")).toBe(true);
+    expect(m.is("green")).toBe(false);
+  });
+
+  it("tracks history of transitions", () => {
+    const m = trafficLight();
+    m.send("GO");
+    m.send("SLOW");
+    const h = m.history();
+    expect(h).toHaveLength(2);
+    expect(h[0]).toEqual({ from: "red", event: "GO", to: "green" });
+    expect(h[1]).toEqual({ from: "green", event: "SLOW", to: "yellow" });
+  });
+
+  it("resets to initial state and clears history", () => {
+    const m = trafficLight();
+    m.send("GO");
+    m.send("SLOW");
+    m.reset();
+    expect(m.state()).toBe("red");
+    expect(m.history()).toHaveLength(0);
+  });
+
+  it("calls onEnter on entering a state", () => {
+    const onEnter = vi.fn();
+    const m = createMachine<"idle" | "active", "START">({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "active" } },
+        active: { onEnter },
+      },
+    });
+    m.send("START");
+    expect(onEnter).toHaveBeenCalledOnce();
+  });
+
+  it("calls onExit on leaving a state", () => {
+    const onExit = vi.fn();
+    const m = createMachine<"idle" | "active", "START">({
+      initial: "idle",
+      states: {
+        idle: { on: { START: "active" }, onExit },
+        active: {},
+      },
+    });
+    m.send("START");
+    expect(onExit).toHaveBeenCalledOnce();
+  });
+
+  it("calls onTransition callback", () => {
+    const onTransition = vi.fn();
+    const m = createMachine<"a" | "b", "NEXT">({
+      initial: "a",
+      states: {
+        a: { on: { NEXT: "b" } },
+        b: {},
+      },
+      onTransition,
+    });
+    m.send("NEXT");
+    expect(onTransition).toHaveBeenCalledWith("a", "NEXT", "b");
+  });
+});