@arcane-engine/runtime 0.1.0

package/src/state/index.ts

@@ -0,0 +1,70 @@
+// Foundational types
+export type { EntityId, Vec2, DeepReadonly } from "./types.ts";
+export { entityId, generateId } from "./types.ts";
+
+// Error types
+export type { ArcaneError } from "./error.ts";
+export { createError } from "./error.ts";
+
+// PRNG
+export type { PRNGState, DiceNotation, DiceSpec } from "./prng.ts";
+export {
+  seed,
+  parseDice,
+  rollDice,
+  randomInt,
+  randomFloat,
+  randomPick,
+  shuffle,
+} from "./prng.ts";
+
+// Transactions
+export type {
+  Mutation,
+  DiffEntry,
+  Diff,
+  Effect,
+  TransactionResult,
+} from "./transaction.ts";
+export {
+  set,
+  update,
+  push,
+  removeWhere,
+  removeKey,
+  transaction,
+  computeDiff,
+} from "./transaction.ts";
+
+// Queries
+export type { Predicate } from "./query.ts";
+export {
+  query,
+  get,
+  has,
+  lt,
+  gt,
+  lte,
+  gte,
+  eq,
+  neq,
+  oneOf,
+  within,
+  allOf,
+  anyOf,
+  not,
+} from "./query.ts";
+
+// Observers
+export type {
+  ObserverCallback,
+  ObserverContext,
+  Unsubscribe,
+  PathPattern,
+  ObserverRegistry,
+} from "./observe.ts";
+export { createObserverRegistry } from "./observe.ts";
+
+// Store
+export type { GameStore, TransactionRecord } from "./store.ts";
+export { createStore } from "./store.ts";

package/src/state/observe.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import { createObserverRegistry } from "./observe.ts";
+import { computeDiff } from "./transaction.ts";
+import type { Diff } from "./transaction.ts";
+
+type State = {
+  party: { id: string; hp: number }[];
+  turn: number;
+};
+
+const before: State = {
+  party: [
+    { id: "alice", hp: 20 },
+    { id: "bob", hp: 15 },
+  ],
+  turn: 1,
+};
+
+describe("createObserverRegistry", () => {
+  it("creates a registry with observe, notify, and clear", () => {
+    const reg = createObserverRegistry<State>();
+    assert.equal(typeof reg.observe, "function");
+    assert.equal(typeof reg.notify, "function");
+    assert.equal(typeof reg.clear, "function");
+  });
+});
+
+describe("observe + notify", () => {
+  it("fires callback when path matches a diff entry", () => {
+    const reg = createObserverRegistry<State>();
+    const calls: { newVal: unknown; oldVal: unknown; path: string }[] = [];
+
+    reg.observe("turn", (newVal, oldVal, ctx) => {
+      calls.push({ newVal, oldVal, path: ctx.path });
+    });
+
+    const after = { ...before, turn: 2 };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].newVal, 2);
+    assert.equal(calls[0].oldVal, 1);
+    assert.equal(calls[0].path, "turn");
+  });
+
+  it("does not fire when path does not match", () => {
+    const reg = createObserverRegistry<State>();
+    let fired = false;
+
+    reg.observe("turn", () => {
+      fired = true;
+    });
+
+    // Change party, not turn
+    const after = {
+      ...before,
+      party: [{ id: "alice", hp: 18 }, before.party[1]],
+    };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.equal(fired, false);
+  });
+
+  it("supports wildcard patterns", () => {
+    const reg = createObserverRegistry<State>();
+    const changedPaths: string[] = [];
+
+    reg.observe("party.*.hp", (_newVal, _oldVal, ctx) => {
+      changedPaths.push(ctx.path);
+    });
+
+    const after: State = {
+      ...before,
+      party: [
+        { id: "alice", hp: 18 },
+        { id: "bob", hp: 10 },
+      ],
+    };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.deepEqual(changedPaths.sort(), ["party.0.hp", "party.1.hp"]);
+  });
+
+  it("wildcard matches only at the right depth", () => {
+    const reg = createObserverRegistry<State>();
+    let fired = false;
+
+    // This pattern expects 3 segments: party.*.hp
+    reg.observe("party.*.hp", () => {
+      fired = true;
+    });
+
+    // Change at "turn" (1 segment) — should not match
+    const after = { ...before, turn: 5 };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.equal(fired, false);
+  });
+
+  it("supports multiple observers on the same pattern", () => {
+    const reg = createObserverRegistry<State>();
+    let count = 0;
+
+    reg.observe("turn", () => count++);
+    reg.observe("turn", () => count++);
+
+    const after = { ...before, turn: 2 };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.equal(count, 2);
+  });
+
+  it("provides the full diff in context", () => {
+    const reg = createObserverRegistry<State>();
+    let receivedDiff: Diff | undefined;
+
+    reg.observe("turn", (_n, _o, ctx) => {
+      receivedDiff = ctx.diff;
+    });
+
+    const after = { ...before, turn: 2 };
+    const diff = computeDiff(before, after);
+    reg.notify(before, after, diff);
+
+    assert.notEqual(receivedDiff, undefined);
+    assert.equal(receivedDiff!.entries.length, 1);
+  });
+});
+
+describe("unsubscribe", () => {
+  it("stops receiving notifications after unsubscribe", () => {
+    const reg = createObserverRegistry<State>();
+    let count = 0;
+
+    const unsub = reg.observe("turn", () => count++);
+
+    const after1 = { ...before, turn: 2 };
+    reg.notify(before, after1, computeDiff(before, after1));
+    assert.equal(count, 1);
+
+    unsub();
+
+    const after2 = { ...after1, turn: 3 };
+    reg.notify(after1, after2, computeDiff(after1, after2));
+    assert.equal(count, 1); // no change
+  });
+});
+
+describe("clear", () => {
+  it("removes all observers", () => {
+    const reg = createObserverRegistry<State>();
+    let count = 0;
+
+    reg.observe("turn", () => count++);
+    reg.observe("party.*.hp", () => count++);
+
+    reg.clear();
+
+    const after = {
+      ...before,
+      turn: 5,
+      party: [{ id: "alice", hp: 0 }, before.party[1]],
+    };
+    reg.notify(before, after, computeDiff(before, after));
+
+    assert.equal(count, 0);
+  });
+});

package/src/state/observe.ts

@@ -0,0 +1,110 @@
+import type { Diff } from "./transaction.ts";
+
+/** Observer callback — receives new value, old value, and context */
+export type ObserverCallback<T = unknown> = (
+  newValue: T,
+  oldValue: T,
+  context: ObserverContext,
+) => void;
+
+/** Context provided to observer callbacks */
+export type ObserverContext = Readonly<{
+  path: string;
+  diff: Diff;
+}>;
+
+/** Unsubscribe function */
+export type Unsubscribe = () => void;
+
+/** Pattern for path matching (supports * wildcards) */
+export type PathPattern = string;
+
+/** Observer registry — manages subscriptions and dispatches notifications */
+export type ObserverRegistry<S> = Readonly<{
+  /** Subscribe to changes at a path pattern */
+  observe: <T = unknown>(
+    pattern: PathPattern,
+    callback: ObserverCallback<T>,
+  ) => Unsubscribe;
+
+  /** Notify all matching observers after a transaction commits */
+  notify: (oldState: S, newState: S, diff: Diff) => void;
+
+  /** Remove all observers */
+  clear: () => void;
+}>;
+
+type Subscription = {
+  pattern: PathPattern;
+  callback: ObserverCallback;
+};
+
+/** Create a new observer registry */
+export function createObserverRegistry<S>(): ObserverRegistry<S> {
+  const subscriptions = new Set<Subscription>();
+
+  return {
+    observe<T = unknown>(
+      pattern: PathPattern,
+      callback: ObserverCallback<T>,
+    ): Unsubscribe {
+      const sub: Subscription = {
+        pattern,
+        callback: callback as ObserverCallback,
+      };
+      subscriptions.add(sub);
+      return () => {
+        subscriptions.delete(sub);
+      };
+    },
+
+    notify(oldState: S, newState: S, diff: Diff): void {
+      for (const entry of diff.entries) {
+        for (const sub of subscriptions) {
+          if (pathMatches(sub.pattern, entry.path)) {
+            sub.callback(
+              getByPath(newState, entry.path),
+              getByPath(oldState, entry.path),
+              { path: entry.path, diff },
+            );
+          }
+        }
+      }
+    },
+
+    clear(): void {
+      subscriptions.clear();
+    },
+  };
+}
+
+// --- Internal: path pattern matching ---
+
+/** Check if a concrete path matches a pattern with * wildcards */
+function pathMatches(pattern: string, path: string): boolean {
+  const patternParts = pattern.split(".");
+  const pathParts = path.split(".");
+
+  if (patternParts.length !== pathParts.length) return false;
+
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i] === "*") continue;
+    if (patternParts[i] !== pathParts[i]) return false;
+  }
+
+  return true;
+}
+
+/** Traverse an object by dot-separated path */
+function getByPath(obj: unknown, path: string): unknown {
+  const segments = path.split(".");
+  let current: unknown = obj;
+
+  for (const segment of segments) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+
+  return current;
+}

package/src/state/prng.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, assert } from "../testing/harness.ts";
+import {
+  seed,
+  parseDice,
+  rollDice,
+  randomInt,
+  randomFloat,
+  randomPick,
+  shuffle,
+} from "./prng.ts";
+
+describe("seed", () => {
+  it("creates a PRNGState from a number", () => {
+    const rng = seed(42);
+    assert.equal(rng.__brand, "PRNGState");
+    assert.equal(rng.seed, 42);
+    assert.equal(typeof rng.s0, "number");
+    assert.equal(typeof rng.s1, "number");
+    assert.equal(typeof rng.s2, "number");
+    assert.equal(typeof rng.s3, "number");
+  });
+
+  it("produces different internal state for different seeds", () => {
+    const a = seed(1);
+    const b = seed(2);
+    assert.notDeepEqual(
+      [a.s0, a.s1, a.s2, a.s3],
+      [b.s0, b.s1, b.s2, b.s3],
+    );
+  });
+});
+
+describe("determinism", () => {
+  it("same seed produces same sequence of floats", () => {
+    let rng1 = seed(42);
+    let rng2 = seed(42);
+    const seq1: number[] = [];
+    const seq2: number[] = [];
+
+    for (let i = 0; i < 20; i++) {
+      const [v1, next1] = randomFloat(rng1);
+      const [v2, next2] = randomFloat(rng2);
+      seq1.push(v1);
+      seq2.push(v2);
+      rng1 = next1;
+      rng2 = next2;
+    }
+
+    assert.deepEqual(seq1, seq2);
+  });
+
+  it("same seed produces same dice rolls", () => {
+    let rng1 = seed(123);
+    let rng2 = seed(123);
+
+    for (let i = 0; i < 10; i++) {
+      const [roll1, next1] = rollDice(rng1, "2d6+3");
+      const [roll2, next2] = rollDice(rng2, "2d6+3");
+      assert.equal(roll1, roll2);
+      rng1 = next1;
+      rng2 = next2;
+    }
+  });
+
+  it("different seeds produce different sequences", () => {
+    let rng1 = seed(1);
+    let rng2 = seed(2);
+    const seq1: number[] = [];
+    const seq2: number[] = [];
+
+    for (let i = 0; i < 10; i++) {
+      const [v1, next1] = randomFloat(rng1);
+      const [v2, next2] = randomFloat(rng2);
+      seq1.push(v1);
+      seq2.push(v2);
+      rng1 = next1;
+      rng2 = next2;
+    }
+
+    assert.notDeepEqual(seq1, seq2);
+  });
+});
+
+describe("parseDice", () => {
+  it("parses basic notation", () => {
+    assert.deepEqual(parseDice("2d6"), { count: 2, sides: 6, modifier: 0 });
+  });
+
+  it("parses positive modifier", () => {
+    assert.deepEqual(parseDice("1d20+5"), { count: 1, sides: 20, modifier: 5 });
+  });
+
+  it("parses negative modifier", () => {
+    assert.deepEqual(parseDice("3d8-2"), { count: 3, sides: 8, modifier: -2 });
+  });
+
+  it("throws on invalid notation", () => {
+    assert.throws(() => parseDice("bad"), /Invalid dice notation/);
+    assert.throws(() => parseDice("d6"), /Invalid dice notation/);
+    assert.throws(() => parseDice("2d"), /Invalid dice notation/);
+  });
+});
+
+describe("rollDice", () => {
+  it("returns a result within expected range", () => {
+    let rng = seed(42);
+    for (let i = 0; i < 100; i++) {
+      const [result, next] = rollDice(rng, "2d6+3");
+      assert.ok(result >= 5, `2d6+3 minimum is 5, got ${result}`);
+      assert.ok(result <= 15, `2d6+3 maximum is 15, got ${result}`);
+      rng = next;
+    }
+  });
+
+  it("accepts DiceSpec directly", () => {
+    const spec = parseDice("1d20");
+    let rng = seed(99);
+    const [result, _] = rollDice(rng, spec);
+    assert.ok(result >= 1 && result <= 20);
+  });
+
+  it("accepts string notation", () => {
+    const rng = seed(99);
+    const [result, _] = rollDice(rng, "1d20");
+    assert.ok(result >= 1 && result <= 20);
+  });
+});
+
+describe("randomInt", () => {
+  it("returns values within [min, max] inclusive", () => {
+    let rng = seed(42);
+    for (let i = 0; i < 200; i++) {
+      const [value, next] = randomInt(rng, 1, 6);
+      assert.ok(value >= 1, `Expected >= 1, got ${value}`);
+      assert.ok(value <= 6, `Expected <= 6, got ${value}`);
+      rng = next;
+    }
+  });
+
+  it("covers the full range", () => {
+    let rng = seed(42);
+    const seen = new Set<number>();
+    for (let i = 0; i < 500; i++) {
+      const [value, next] = randomInt(rng, 1, 6);
+      seen.add(value);
+      rng = next;
+    }
+    assert.deepEqual([...seen].sort(), [1, 2, 3, 4, 5, 6]);
+  });
+});
+
+describe("randomFloat", () => {
+  it("returns values in [0, 1)", () => {
+    let rng = seed(42);
+    for (let i = 0; i < 200; i++) {
+      const [value, next] = randomFloat(rng);
+      assert.ok(value >= 0, `Expected >= 0, got ${value}`);
+      assert.ok(value < 1, `Expected < 1, got ${value}`);
+      rng = next;
+    }
+  });
+});
+
+describe("randomPick", () => {
+  it("picks an element from the array", () => {
+    const items = ["sword", "shield", "potion"];
+    let rng = seed(42);
+    for (let i = 0; i < 50; i++) {
+      const [item, next] = randomPick(rng, items);
+      assert.ok(items.includes(item), `Picked unknown item: ${item}`);
+      rng = next;
+    }
+  });
+
+  it("covers all elements given enough picks", () => {
+    const items = ["a", "b", "c"];
+    let rng = seed(42);
+    const seen = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      const [item, next] = randomPick(rng, items);
+      seen.add(item);
+      rng = next;
+    }
+    assert.equal(seen.size, 3);
+  });
+});
+
+describe("shuffle", () => {
+  it("returns an array of the same length", () => {
+    const items = [1, 2, 3, 4, 5];
+    const [result, _] = shuffle(seed(42), items);
+    assert.equal(result.length, items.length);
+  });
+
+  it("contains the same elements", () => {
+    const items = [1, 2, 3, 4, 5];
+    const [result, _] = shuffle(seed(42), items);
+    assert.deepEqual([...result].sort(), [...items].sort());
+  });
+
+  it("does not mutate the original array", () => {
+    const items = [1, 2, 3, 4, 5];
+    const copy = [...items];
+    shuffle(seed(42), items);
+    assert.deepEqual(items, copy);
+  });
+
+  it("is deterministic", () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    const [r1, _] = shuffle(seed(42), items);
+    const [r2, __] = shuffle(seed(42), items);
+    assert.deepEqual(r1, r2);
+  });
+
+  it("actually shuffles (not identity)", () => {
+    const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+    const [result, _] = shuffle(seed(42), items);
+    // With 10 elements, the probability of no change is astronomically low
+    assert.notDeepEqual(result, items);
+  });
+});