@praxisjs/fsm 2.1.7 → 2.2.1

package/src/__tests__/decorators.test.ts

@@ -1,219 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-
-import { Transition, StateMachine } from "../decorators";
-import { createMachine } from "../machine";
-import type { Machine } from "../machine";
-
-const TOGGLE_DEF = {
-  initial: "off" as const,
-  states: {
-    off: { on: { toggle: "on" as const } },
-    on:  { on: { toggle: "off" as const } },
-  },
-} as const;
-
-// Helper to simulate TC39 field decorator context
-function fieldCtx(name: string) {
-  const initializers: Array<(this: object) => void> = [];
-  return {
-    ctx: {
-      name,
-      kind: "field" as const,
-      addInitializer(fn: (this: object) => void) { initializers.push(fn); },
-    } as ClassFieldDecoratorContext,
-    run(instance: object) {
-      initializers.forEach((fn) => { fn.call(instance); });
-    },
-  };
-}
-
-// Helper to simulate TC39 method decorator context
-function mockMethodContext(name: string) {
-  const initializers: Array<(this: object) => void> = [];
-  return {
-    name,
-    kind: "method" as const,
-    addInitializer(fn: (this: object) => void) { initializers.push(fn); },
-    runInitializers(instance: object) {
-      initializers.forEach((fn) => { fn.call(instance); });
-    },
-  };
-}
-
-// ── StateMachine ──────────────────────────────────────────────────────────────
-
-describe("StateMachine decorator", () => {
-  it("injects a machine via field decorator", () => {
-    const { ctx, run } = fieldCtx("machine");
-    StateMachine(TOGGLE_DEF)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    expect(instance.machine).toBeDefined();
-    expect((instance.machine as Machine<string, string>).state()).toBe("off");
-  });
-
-  it("returns a separate machine per instance", () => {
-    const { ctx, run } = fieldCtx("machine");
-    StateMachine(TOGGLE_DEF)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const a: Record<string, unknown> = {};
-    const b: Record<string, unknown> = {};
-    run(a);
-    run(b);
-    (a.machine as Machine<string, string>).send("toggle");
-    expect((a.machine as Machine<string, string>).state()).toBe("on");
-    expect((b.machine as Machine<string, string>).state()).toBe("off");
-  });
-
-  it("supports a custom field name", () => {
-    const { ctx, run } = fieldCtx("fsm");
-    StateMachine(TOGGLE_DEF)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    expect(instance.fsm).toBeDefined();
-    expect((instance.fsm as Machine<string, string>).state()).toBe("off");
-  });
-
-  it("returns the same machine instance on repeated access", () => {
-    const { ctx, run } = fieldCtx("machine");
-    StateMachine(TOGGLE_DEF)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    expect(instance.machine).toBe(instance.machine);
-  });
-
-  it("setter is a no-op — assigning to the field does not replace the machine", () => {
-    const { ctx, run } = fieldCtx("machine");
-    StateMachine(TOGGLE_DEF)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    const original = instance.machine;
-    instance.machine = "overwrite-attempt"; // triggers set(): void {} (no-op)
-    expect(instance.machine).toBe(original);
-  });
-
-  it("accepts a factory function — machine created with instance as this", () => {
-    const { ctx, run } = fieldCtx("machine");
-    const instances: object[] = [];
-    const factory = function (this: object) {
-      instances.push(this);
-      return TOGGLE_DEF;
-    };
-    StateMachine(factory)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"off"|"on","toggle">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    // Access triggers lazy creation
-    const m = instance.machine as Machine<string, string>;
-    expect(m.state()).toBe("off");
-    expect(instances).toHaveLength(1);
-    expect(instances[0]).toBe(instance);
-  });
-
-  it("factory receives correct instance — guard can close over instance state", () => {
-    const { ctx, run } = fieldCtx("machine");
-    let allow = false;
-
-    const factory = function (this: object) {
-      return {
-        initial: "a" as const,
-        states: {
-          a: { on: { NEXT: { target: "b" as const, guard: () => allow } } },
-          b: {},
-        },
-      };
-    };
-    StateMachine(factory)(undefined, ctx as ClassFieldDecoratorContext<object, Machine<"a"|"b","NEXT">>);
-
-    const instance: Record<string, unknown> = {};
-    run(instance);
-    const m = instance.machine as Machine<string, string>;
-
-    expect(m.send("NEXT")).toBe(false);
-    allow = true;
-    expect(m.send("NEXT")).toBe(true);
-    expect(m.state()).toBe("b");
-  });
-});
-
-// ── Transition ────────────────────────────────────────────────────────────────
-
-describe("Transition decorator", () => {
-  it("calls the original method when send succeeds", () => {
-    const original = vi.fn(() => "ran");
-    const ctx = mockMethodContext("doTransition");
-    Transition("machine", "toggle")(original, ctx as unknown as ClassMethodDecoratorContext);
-
-    const instance = { machine: createMachine(TOGGLE_DEF) } as Record<string, unknown>;
-    ctx.runInitializers(instance);
-    const method = (instance as Record<string, () => unknown>).doTransition;
-
-    method();
-    expect(original).toHaveBeenCalled();
-  });
-
-  it("returns without calling method when machine is missing", () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const original = vi.fn();
-    const ctx = mockMethodContext("doTransition");
-    Transition("machine", "toggle")(original, ctx as unknown as ClassMethodDecoratorContext);
-
-    const instance = {} as Record<string, unknown>;
-    ctx.runInitializers(instance);
-    const method = (instance as Record<string, () => unknown>).doTransition;
-
-    method();
-    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 ctx = mockMethodContext("doTransition");
-    Transition("machine", "toggle")(original, ctx as unknown as ClassMethodDecoratorContext);
-
-    const instance = {
-      machine: createMachine({ initial: "on" as const, states: { on: {} } }),
-    } as Record<string, unknown>;
-    ctx.runInitializers(instance);
-    const method = (instance as Record<string, () => unknown>).doTransition;
-
-    method();
-    expect(original).not.toHaveBeenCalled();
-  });
-
-  it("passes through arguments to the original method", () => {
-    const original = vi.fn((_x: unknown) => undefined);
-    const ctx = mockMethodContext("doTransition");
-    Transition("machine", "toggle")(original, ctx as unknown as ClassMethodDecoratorContext);
-
-    const instance = { machine: createMachine(TOGGLE_DEF) } as Record<string, unknown>;
-    ctx.runInitializers(instance);
-    const method = (instance as Record<string, (...a: unknown[]) => unknown>).doTransition;
-
-    method(42);
-    expect(original).toHaveBeenCalledWith(42);
-  });
-
-  it("@Transition on method without @StateMachine — warns and returns undefined", () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const original = vi.fn(() => "ran");
-    const ctx = mockMethodContext("doTransition");
-    Transition("machine", "toggle")(original, ctx as unknown as ClassMethodDecoratorContext);
-
-    const instance = {} as Record<string, unknown>;
-    ctx.runInitializers(instance);
-    const method = (instance as Record<string, () => unknown>).doTransition;
-
-    const result = method();
-    expect(result).toBeUndefined();
-    expect(original).not.toHaveBeenCalled();
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Transition]"));
-    warn.mockRestore();
-  });
-});

package/src/__tests__/machine.test.ts

@@ -1,433 +0,0 @@
-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("onExit throwing prevents the state change and keeps history clean", () => {
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: {
-          on: { START: "active" },
-          onExit: () => { throw new Error("exit failed"); },
-        },
-        active: {},
-      },
-    });
-    expect(() => m.send("START")).toThrow("exit failed");
-    expect(m.state()).toBe("idle");
-    expect(m.history()).toHaveLength(0);
-  });
-
-  it("onEnter throwing after state change leaves machine in the new state", () => {
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: { on: { START: "active" } },
-        active: { onEnter: () => { throw new Error("enter failed"); } },
-      },
-    });
-    expect(() => m.send("START")).toThrow("enter failed");
-    // State was already committed before onEnter ran
-    expect(m.state()).toBe("active");
-    expect(m.history()).toHaveLength(1);
-  });
-
-  it("reset() calls onEnter of the initial state", () => {
-    const onEnter = vi.fn();
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: { on: { START: "active" }, onEnter },
-        active: {},
-      },
-    });
-    m.send("START");
-    m.reset();
-    expect(onEnter).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");
-  });
-
-  it("state with on:{} — can() returns false for all events", () => {
-    const m = createMachine<"idle", "START" | "STOP">({
-      initial: "idle",
-      states: {
-        idle: { on: {} },
-      },
-    });
-    expect(m.can("START")).toBe(false);
-    expect(m.can("STOP")).toBe(false);
-  });
-
-  it("circular transition A→B→A — history contains correct entries", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: "b" } },
-        b: { on: { NEXT: "a" } },
-      },
-    });
-    m.send("NEXT"); // a→b
-    m.send("NEXT"); // b→a
-    const h = m.history();
-    expect(h).toHaveLength(2);
-    expect(h[0]).toEqual({ from: "a", event: "NEXT", to: "b" });
-    expect(h[1]).toEqual({ from: "b", event: "NEXT", to: "a" });
-  });
-
-  it("send() with undefined event — does not crash, returns false", () => {
-    const m = trafficLight();
-    // Cast to bypass TypeScript — runtime guard should handle it gracefully
-    expect(m.send(undefined as unknown as TrafficEvent)).toBe(false);
-  });
-
-  it("onEnter callback is called AFTER the state has changed", () => {
-    let stateAtOnEnter: string | undefined;
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: { on: { START: "active" } },
-        active: {
-          onEnter() {
-            stateAtOnEnter = m.state();
-          },
-        },
-      },
-    });
-    m.send("START");
-    expect(stateAtOnEnter).toBe("active");
-  });
-
-  it("history not polluted by failed transitions (onExit throws)", () => {
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: {
-          on: { START: "active" },
-          onExit: () => { throw new Error("blocked"); },
-        },
-        active: {},
-      },
-    });
-    expect(() => m.send("START")).toThrow("blocked");
-    expect(m.history()).toHaveLength(0);
-    expect(m.state()).toBe("idle");
-  });
-
-  // ── Guards ──────────────────────────────────────────────────────────────────
-
-  it("guard returning true allows the transition", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => true } } },
-        b: {},
-      },
-    });
-    expect(m.send("NEXT")).toBe(true);
-    expect(m.state()).toBe("b");
-  });
-
-  it("guard returning false blocks the transition — send returns false", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => false } } },
-        b: {},
-      },
-    });
-    expect(m.send("NEXT")).toBe(false);
-    expect(m.state()).toBe("a");
-  });
-
-  it("guard returning false — history not updated", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => false } } },
-        b: {},
-      },
-    });
-    m.send("NEXT");
-    expect(m.history()).toHaveLength(0);
-  });
-
-  it("guard returning false — onExit is NOT called", () => {
-    const onExit = vi.fn();
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => false } }, onExit },
-        b: {},
-      },
-    });
-    m.send("NEXT");
-    expect(onExit).not.toHaveBeenCalled();
-  });
-
-  it("can() returns false when guard returns false", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => false } } },
-        b: {},
-      },
-    });
-    expect(m.can("NEXT")).toBe(false);
-  });
-
-  it("can() returns true when guard returns true", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => true } } },
-        b: {},
-      },
-    });
-    expect(m.can("NEXT")).toBe(true);
-  });
-
-  it("guard is evaluated at transition time, not at definition time", () => {
-    let allow = false;
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => allow } } },
-        b: {},
-      },
-    });
-    expect(m.send("NEXT")).toBe(false);
-    allow = true;
-    expect(m.send("NEXT")).toBe(true);
-    expect(m.state()).toBe("b");
-  });
-
-  it("transition without guard behaves as before (plain string target)", () => {
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: "b" } },
-        b: {},
-      },
-    });
-    expect(m.can("NEXT")).toBe(true);
-    expect(m.send("NEXT")).toBe(true);
-    expect(m.state()).toBe("b");
-  });
-
-  // ── Per-transition action ───────────────────────────────────────────────────
-
-  it("action is called on successful transition", () => {
-    const action = vi.fn();
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", action } } },
-        b: {},
-      },
-    });
-    m.send("NEXT");
-    expect(action).toHaveBeenCalledOnce();
-  });
-
-  it("action is NOT called when guard blocks the transition", () => {
-    const action = vi.fn();
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", guard: () => false, action } } },
-        b: {},
-      },
-    });
-    m.send("NEXT");
-    expect(action).not.toHaveBeenCalled();
-  });
-
-  it("action runs after onTransition and before onEnter", () => {
-    const order: string[] = [];
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: { target: "b", action: () => { order.push("action"); } } } },
-        b: { onEnter: () => { order.push("onEnter"); } },
-      },
-      onTransition: () => { order.push("onTransition"); },
-    });
-    m.send("NEXT");
-    expect(order).toEqual(["onTransition", "action", "onEnter"]);
-  });
-
-  // ── onEnter / onExit context ────────────────────────────────────────────────
-
-  it("onEnter receives event and from-state in context", () => {
-    let ctx: { event: string; from: string } | undefined;
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: "b" } },
-        b: { onEnter: (c) => { ctx = c; } },
-      },
-    });
-    m.send("NEXT");
-    expect(ctx).toEqual({ event: "NEXT", from: "a" });
-  });
-
-  it("onExit receives event and to-state in context", () => {
-    let ctx: { event: string; to: string } | undefined;
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: "b" }, onExit: (c) => { ctx = c; } },
-        b: {},
-      },
-    });
-    m.send("NEXT");
-    expect(ctx).toEqual({ event: "NEXT", to: "b" });
-  });
-
-  it("onEnter and onExit called without context on reset()", () => {
-    const onEnter = vi.fn();
-    const onExit = vi.fn();
-    const m = createMachine<"idle" | "active", "START">({
-      initial: "idle",
-      states: {
-        idle: { on: { START: "active" }, onEnter },
-        active: { onExit },
-      },
-    });
-    m.send("START");
-    m.reset();
-    expect(onExit).toHaveBeenCalledWith(undefined);
-    expect(onEnter).toHaveBeenCalledWith(undefined);
-  });
-
-  it("zero-argument onEnter/onExit still work with context (backward compat)", () => {
-    const onEnter = vi.fn();
-    const onExit = vi.fn();
-    const m = createMachine<"a" | "b", "NEXT">({
-      initial: "a",
-      states: {
-        a: { on: { NEXT: "b" }, onExit },
-        b: { onEnter },
-      },
-    });
-    m.send("NEXT");
-    expect(onExit).toHaveBeenCalledOnce();
-    expect(onEnter).toHaveBeenCalledOnce();
-  });
-});

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src"]
-}