@arcane-engine/runtime 0.1.0

package/src/state/store.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { createStore } from "./store.ts";
+import { set, update, push } from "./transaction.ts";
+import { lt } from "./query.ts";
+
+type GameState = {
+  turn: number;
+  party: { id: string; hp: number; role: string }[];
+  score: number;
+};
+
+const initial: GameState = {
+  turn: 1,
+  party: [
+    { id: "alice", hp: 20, role: "fighter" },
+    { id: "bob", hp: 15, role: "mage" },
+  ],
+  score: 0,
+};
+
+describe("createStore", () => {
+  it("returns a store with the initial state", () => {
+    const store = createStore(initial);
+    assert.deepEqual(store.getState(), initial);
+  });
+});
+
+describe("dispatch", () => {
+  it("applies mutations and updates state", () => {
+    const store = createStore(initial);
+    const result = store.dispatch([
+      set<GameState>("turn", 2),
+      set<GameState>("score", 100),
+    ]);
+
+    assert.equal(result.valid, true);
+    assert.equal(store.getState().turn, 2);
+    assert.equal(store.getState().score, 100);
+  });
+
+  it("returns the transaction result with diff", () => {
+    const store = createStore(initial);
+    const result = store.dispatch([set<GameState>("turn", 2)]);
+
+    assert.equal(result.valid, true);
+    const turnEntry = result.diff.entries.find((e) => e.path === "turn");
+    assert.notEqual(turnEntry, undefined);
+    assert.equal(turnEntry!.from, 1);
+    assert.equal(turnEntry!.to, 2);
+  });
+
+  it("does not update state on invalid transaction", () => {
+    const store = createStore(initial);
+    const result = store.dispatch([
+      set<GameState>("turn", 2),
+      push<GameState>("turn", "invalid"), // turn is number, not array
+    ]);
+
+    assert.equal(result.valid, false);
+    assert.equal(store.getState().turn, 1); // unchanged
+  });
+
+  it("records transaction in history", () => {
+    const store = createStore(initial);
+    assert.equal(store.getHistory().length, 0);
+
+    store.dispatch([set<GameState>("turn", 2)]);
+    assert.equal(store.getHistory().length, 1);
+
+    store.dispatch([set<GameState>("turn", 3)]);
+    assert.equal(store.getHistory().length, 2);
+  });
+
+  it("does not record failed transactions", () => {
+    const store = createStore(initial);
+    store.dispatch([push<GameState>("turn", "invalid")]);
+    assert.equal(store.getHistory().length, 0);
+  });
+});
+
+describe("observe via store", () => {
+  it("notifies observers after dispatch", () => {
+    const store = createStore(initial);
+    const observed: { newVal: unknown; oldVal: unknown }[] = [];
+
+    store.observe("turn", (newVal, oldVal) => {
+      observed.push({ newVal, oldVal });
+    });
+
+    store.dispatch([set<GameState>("turn", 2)]);
+
+    assert.equal(observed.length, 1);
+    assert.equal(observed[0].newVal, 2);
+    assert.equal(observed[0].oldVal, 1);
+  });
+
+  it("does not notify on failed dispatch", () => {
+    const store = createStore(initial);
+    let notified = false;
+
+    store.observe("turn", () => {
+      notified = true;
+    });
+
+    store.dispatch([
+      set<GameState>("turn", 2),
+      push<GameState>("turn", "invalid"),
+    ]);
+
+    assert.equal(notified, false);
+  });
+
+  it("supports unsubscribe", () => {
+    const store = createStore(initial);
+    let count = 0;
+
+    const unsub = store.observe("turn", () => count++);
+    store.dispatch([set<GameState>("turn", 2)]);
+    assert.equal(count, 1);
+
+    unsub();
+    store.dispatch([set<GameState>("turn", 3)]);
+    assert.equal(count, 1);
+  });
+});
+
+describe("query/get/has via store", () => {
+  it("queries current state", () => {
+    const store = createStore(initial);
+    const fighters = store.query("party", { role: "fighter" });
+    assert.equal(fighters.length, 1);
+  });
+
+  it("gets a value from current state", () => {
+    const store = createStore(initial);
+    assert.equal(store.get("turn"), 1);
+    assert.equal(store.get("party.0.id"), "alice");
+  });
+
+  it("checks existence in current state", () => {
+    const store = createStore(initial);
+    assert.equal(store.has("turn"), true);
+    assert.equal(store.has("nonexistent"), false);
+  });
+
+  it("queries reflect dispatched changes", () => {
+    const store = createStore(initial);
+    store.dispatch([set<GameState>("party.0.hp", 5)]);
+
+    const wounded = store.query("party", { hp: lt(10) });
+    assert.equal(wounded.length, 1);
+  });
+});
+
+describe("replaceState", () => {
+  it("replaces the entire state", () => {
+    const store = createStore(initial);
+    const newState: GameState = {
+      turn: 10,
+      party: [],
+      score: 999,
+    };
+
+    store.replaceState(newState);
+    assert.deepEqual(store.getState(), newState);
+  });
+
+  it("enables undo/redo (time travel)", () => {
+    const store = createStore(initial);
+    const snapshot = store.getState();
+
+    store.dispatch([set<GameState>("turn", 2)]);
+    store.dispatch([set<GameState>("turn", 3)]);
+    assert.equal(store.getState().turn, 3);
+
+    // Undo to the original state
+    store.replaceState(snapshot as GameState);
+    assert.equal(store.getState().turn, 1);
+  });
+});
+
+describe("integration: full dispatch → observe → query cycle", () => {
+  it("works end-to-end", () => {
+    const store = createStore(initial);
+    const hpChanges: { who: string; from: number; to: number }[] = [];
+
+    store.observe("party.*.hp", (newVal, oldVal, ctx) => {
+      const index = ctx.path.split(".")[1];
+      const member = store.get<{ id: string }>(`party.${index}`);
+      hpChanges.push({
+        who: member!.id,
+        from: oldVal as number,
+        to: newVal as number,
+      });
+    });
+
+    store.dispatch([
+      update<GameState>("party.0.hp", (hp) => (hp as number) - 5),
+      update<GameState>("party.1.hp", (hp) => (hp as number) - 3),
+      update<GameState>("turn", (t) => (t as number) + 1),
+    ]);
+
+    assert.equal(hpChanges.length, 2);
+    assert.deepEqual(hpChanges[0], { who: "alice", from: 20, to: 15 });
+    assert.deepEqual(hpChanges[1], { who: "bob", from: 15, to: 12 });
+
+    assert.equal(store.getState().turn, 2);
+    assert.equal(store.get("party.0.hp"), 15);
+    assert.equal(store.get("party.1.hp"), 12);
+  });
+});

package/src/state/store.ts

@@ -0,0 +1,109 @@
+import type { DeepReadonly } from "./types.ts";
+import type { Mutation, Diff, TransactionResult } from "./transaction.ts";
+import { transaction } from "./transaction.ts";
+import type { Predicate } from "./query.ts";
+import { query, get, has } from "./query.ts";
+import type { PathPattern, ObserverCallback, Unsubscribe } from "./observe.ts";
+import { createObserverRegistry } from "./observe.ts";
+
+/** The game store: ties state + transactions + observers together */
+export type GameStore<S> = Readonly<{
+  /** Current state (readonly snapshot) */
+  getState: () => DeepReadonly<S>;
+
+  /** Apply mutations as a transaction, update state, notify observers */
+  dispatch: (mutations: readonly Mutation<S>[]) => TransactionResult<S>;
+
+  /** Subscribe to state changes at a path pattern */
+  observe: <T = unknown>(
+    pattern: PathPattern,
+    callback: ObserverCallback<T>,
+  ) => Unsubscribe;
+
+  /** Query current state */
+  query: <R = unknown>(
+    path: string,
+    filter?: Predicate<R> | Record<string, unknown>,
+  ) => readonly R[];
+
+  /** Get a value from current state */
+  get: <R = unknown>(path: string) => R | undefined;
+
+  /** Check existence in current state */
+  has: (path: string, predicate?: Predicate<unknown>) => boolean;
+
+  /** Replace the entire state (for deserialization / time travel) */
+  replaceState: (state: S) => void;
+
+  /** Get the transaction history (for recording/replay) */
+  getHistory: () => readonly TransactionRecord<S>[];
+}>;
+
+/** A recorded transaction for replay */
+export type TransactionRecord<S> = Readonly<{
+  timestamp: number;
+  mutations: readonly Mutation<S>[];
+  diff: Diff;
+}>;
+
+/** Create a game store with initial state */
+export function createStore<S>(initialState: S): GameStore<S> {
+  let state: S = initialState;
+  const observers = createObserverRegistry<S>();
+  const history: TransactionRecord<S>[] = [];
+
+  return {
+    getState(): DeepReadonly<S> {
+      return state as DeepReadonly<S>;
+    },
+
+    dispatch(mutations: readonly Mutation<S>[]): TransactionResult<S> {
+      const oldState = state;
+      const result = transaction(state, mutations);
+
+      if (result.valid) {
+        state = result.state;
+
+        history.push({
+          timestamp: Date.now(),
+          mutations,
+          diff: result.diff,
+        });
+
+        observers.notify(oldState, state, result.diff);
+      }
+
+      return result;
+    },
+
+    observe<T = unknown>(
+      pattern: PathPattern,
+      callback: ObserverCallback<T>,
+    ): Unsubscribe {
+      return observers.observe(pattern, callback);
+    },
+
+    query<R = unknown>(
+      path: string,
+      filter?: Predicate<R> | Record<string, unknown>,
+    ): readonly R[] {
+      return query(state, path, filter);
+    },
+
+    get<R = unknown>(path: string): R | undefined {
+      return get(state, path);
+    },
+
+    has(path: string, predicate?: Predicate<unknown>): boolean {
+      return has(state, path, predicate);
+    },
+
+    replaceState(newState: S): void {
+      state = newState;
+    },
+
+    getHistory(): readonly TransactionRecord<S>[] {
+      return history;
+    },
+  };
+}

package/src/state/transaction.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  set,
+  update,
+  push,
+  removeWhere,
+  removeKey,
+  transaction,
+  computeDiff,
+} from "./transaction.ts";
+
+type TestState = {
+  hp: number;
+  name: string;
+  items: string[];
+  party: { id: string; hp: number }[];
+  nested: { a: { b: { c: number } } };
+};
+
+const initial: TestState = {
+  hp: 10,
+  name: "hero",
+  items: ["sword", "shield", "potion"],
+  party: [
+    { id: "alice", hp: 20 },
+    { id: "bob", hp: 15 },
+  ],
+  nested: { a: { b: { c: 42 } } },
+};
+
+describe("set", () => {
+  it("sets a top-level value", () => {
+    const m = set<TestState>("hp", 5);
+    const result = m.apply(initial);
+    assert.equal(result.hp, 5);
+    assert.equal(initial.hp, 10); // original unchanged
+  });
+
+  it("sets a nested value", () => {
+    const m = set<TestState>("nested.a.b.c", 99);
+    const result = m.apply(initial);
+    assert.equal(result.nested.a.b.c, 99);
+  });
+
+  it("sets a value inside an array element", () => {
+    const m = set<TestState>("party.0.hp", 0);
+    const result = m.apply(initial);
+    assert.equal(result.party[0].hp, 0);
+    assert.equal(result.party[1].hp, 15); // untouched
+  });
+
+  it("has correct metadata", () => {
+    const m = set<TestState>("hp", 5);
+    assert.equal(m.type, "set");
+    assert.equal(m.path, "hp");
+    assert.ok(m.description.includes("hp"));
+  });
+});
+
+describe("update", () => {
+  it("updates a value with a function", () => {
+    const m = update<TestState>("hp", (hp) => (hp as number) - 3);
+    const result = m.apply(initial);
+    assert.equal(result.hp, 7);
+  });
+
+  it("updates a nested value", () => {
+    const m = update<TestState>("nested.a.b.c", (c) => (c as number) * 2);
+    const result = m.apply(initial);
+    assert.equal(result.nested.a.b.c, 84);
+  });
+});
+
+describe("push", () => {
+  it("pushes an item onto an array", () => {
+    const m = push<TestState>("items", "bow");
+    const result = m.apply(initial);
+    assert.deepEqual(result.items, ["sword", "shield", "potion", "bow"]);
+    assert.equal(initial.items.length, 3); // original unchanged
+  });
+
+  it("throws when target is not an array", () => {
+    const m = push<TestState>("hp", "invalid");
+    assert.throws(() => m.apply(initial), /Expected array/);
+  });
+});
+
+describe("removeWhere", () => {
+  it("removes matching items from an array", () => {
+    const m = removeWhere<TestState>("items", (item) => item === "shield");
+    const result = m.apply(initial);
+    assert.deepEqual(result.items, ["sword", "potion"]);
+  });
+
+  it("removes nothing when no match", () => {
+    const m = removeWhere<TestState>("items", (item) => item === "axe");
+    const result = m.apply(initial);
+    assert.deepEqual(result.items, initial.items);
+  });
+
+  it("can remove by predicate on objects", () => {
+    const m = removeWhere<TestState>(
+      "party",
+      (member: any) => member.hp < 18,
+    );
+    const result = m.apply(initial);
+    assert.equal(result.party.length, 1);
+    assert.equal(result.party[0].id, "alice");
+  });
+});
+
+describe("removeKey", () => {
+  it("removes a key from a nested object", () => {
+    const m = removeKey<TestState>("nested.a.b");
+    const result = m.apply(initial);
+    assert.deepEqual(result.nested.a, {});
+  });
+});
+
+describe("transaction", () => {
+  it("applies multiple mutations atomically", () => {
+    const result = transaction(initial, [
+      set<TestState>("hp", 5),
+      push<TestState>("items", "bow"),
+      set<TestState>("party.0.hp", 18),
+    ]);
+
+    assert.equal(result.valid, true);
+    assert.equal(result.state.hp, 5);
+    assert.deepEqual(result.state.items, ["sword", "shield", "potion", "bow"]);
+    assert.equal(result.state.party[0].hp, 18);
+    assert.equal(result.error, undefined);
+  });
+
+  it("rolls back all changes on failure", () => {
+    const result = transaction(initial, [
+      set<TestState>("hp", 0),
+      push<TestState>("hp", "invalid"), // hp is a number, not array — will throw
+    ]);
+
+    assert.equal(result.valid, false);
+    assert.equal(result.state, initial); // original state returned
+    assert.notEqual(result.error, undefined);
+    assert.equal(result.error!.code, "TRANSACTION_FAILED");
+  });
+
+  it("produces a diff", () => {
+    const result = transaction(initial, [
+      set<TestState>("hp", 5),
+      set<TestState>("name", "villain"),
+    ]);
+
+    assert.equal(result.valid, true);
+    const hpEntry = result.diff.entries.find((e) => e.path === "hp");
+    assert.notEqual(hpEntry, undefined);
+    assert.equal(hpEntry!.from, 10);
+    assert.equal(hpEntry!.to, 5);
+
+    const nameEntry = result.diff.entries.find((e) => e.path === "name");
+    assert.notEqual(nameEntry, undefined);
+    assert.equal(nameEntry!.from, "hero");
+    assert.equal(nameEntry!.to, "villain");
+  });
+
+  it("produces empty diff when nothing changes", () => {
+    const result = transaction(initial, [set<TestState>("hp", 10)]);
+    assert.equal(result.valid, true);
+    assert.equal(result.diff.entries.length, 0);
+  });
+
+  it("does not mutate the original state", () => {
+    const frozen = JSON.parse(JSON.stringify(initial));
+    transaction(initial, [
+      set<TestState>("hp", 0),
+      push<TestState>("items", "new_item"),
+    ]);
+    assert.deepEqual(initial, frozen);
+  });
+});
+
+describe("computeDiff", () => {
+  it("detects simple value changes", () => {
+    const before = { x: 1, y: 2 };
+    const after = { x: 1, y: 3 };
+    const diff = computeDiff(before, after);
+    assert.equal(diff.entries.length, 1);
+    assert.equal(diff.entries[0].path, "y");
+    assert.equal(diff.entries[0].from, 2);
+    assert.equal(diff.entries[0].to, 3);
+  });
+
+  it("detects nested changes", () => {
+    const before = { a: { b: 1 } };
+    const after = { a: { b: 2 } };
+    const diff = computeDiff(before, after);
+    assert.equal(diff.entries.length, 1);
+    assert.equal(diff.entries[0].path, "a.b");
+  });
+
+  it("detects added keys", () => {
+    const before = { x: 1 } as any;
+    const after = { x: 1, y: 2 };
+    const diff = computeDiff(before, after);
+    const yEntry = diff.entries.find((e) => e.path === "y");
+    assert.notEqual(yEntry, undefined);
+    assert.equal(yEntry!.from, undefined);
+    assert.equal(yEntry!.to, 2);
+  });
+
+  it("detects removed keys", () => {
+    const before = { x: 1, y: 2 };
+    const after = { x: 1 } as any;
+    const diff = computeDiff(before, after);
+    const yEntry = diff.entries.find((e) => e.path === "y");
+    assert.notEqual(yEntry, undefined);
+    assert.equal(yEntry!.from, 2);
+    assert.equal(yEntry!.to, undefined);
+  });
+
+  it("detects array changes", () => {
+    const before = { items: ["a", "b"] };
+    const after = { items: ["a", "c"] };
+    const diff = computeDiff(before, after);
+    const entry = diff.entries.find((e) => e.path === "items.1");
+    assert.notEqual(entry, undefined);
+    assert.equal(entry!.from, "b");
+    assert.equal(entry!.to, "c");
+  });
+
+  it("returns empty diff for identical objects", () => {
+    const obj = { a: 1, b: { c: 2 } };
+    const diff = computeDiff(obj, obj);
+    assert.equal(diff.entries.length, 0);
+  });
+});