@excom/kit-utils 0.1.0

package/support/tests/loop-guard.test.ts

@@ -0,0 +1,225 @@
+import { LoopGuard, type LoopGuardTrip } from "../../loop-guard";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+describe("LoopGuard", () => {
+  let trips: LoopGuardTrip[];
+  let logs: string[];
+  let off: () => void;
+
+  beforeEach(() => {
+    LoopGuard.reset();
+    trips = [];
+    logs = [];
+    LoopGuard.configure({ log: (message) => logs.push(message) });
+    off = LoopGuard.onTrip((trip) => trips.push(trip));
+  });
+
+  afterEach(() => {
+    off();
+    LoopGuard.reset();
+    document.body.innerHTML = "";
+  });
+
+  describe("contexts", () => {
+    it("is at depth 0 outside any context", () => {
+      expect(LoopGuard.current()).toBe(0);
+    });
+
+    it("opens a context at max(current, inherited) and restores it after", () => {
+      const seen: number[] = [];
+      LoopGuard.run(3, () => {
+        seen.push(LoopGuard.current());
+        LoopGuard.run(1, () => seen.push(LoopGuard.current()));
+        LoopGuard.run(7, () => seen.push(LoopGuard.current()));
+        seen.push(LoopGuard.current());
+      });
+      expect(seen).toEqual([3, 3, 7, 3]);
+      expect(LoopGuard.current()).toBe(0);
+    });
+
+    it("pops the context when fn throws", () => {
+      expect(() =>
+        LoopGuard.run(2, () => {
+          throw new Error("boom");
+        })
+      ).toThrow("boom");
+      expect(LoopGuard.current()).toBe(0);
+    });
+
+    it("returns fn's result", () => {
+      expect(LoopGuard.run(1, () => "value")).toBe("value");
+    });
+  });
+
+  describe("stamps", () => {
+    it("write() stamps (target, name) one deeper than the current context", () => {
+      const target = {};
+      LoopGuard.write(target, "x", () => {});
+      expect(LoopGuard.depthOf(target, "x")).toBe(1);
+      LoopGuard.run(4, () => LoopGuard.write(target, "y", () => {}));
+      expect(LoopGuard.depthOf(target, "y")).toBe(5);
+      expect(LoopGuard.depthOf(target, "never")).toBe(0);
+      expect(LoopGuard.depthOf({}, "x")).toBe(0);
+    });
+
+    it("stamp() records a depth without applying the limit", () => {
+      LoopGuard.configure({ limit: 2 });
+      const target = {};
+      LoopGuard.run(10, () => LoopGuard.stamp(target, "x"));
+      expect(LoopGuard.depthOf(target, "x")).toBe(11);
+      LoopGuard.stamp(target, "y", 99);
+      expect(LoopGuard.depthOf(target, "y")).toBe(99);
+      expect(trips).toEqual([]);
+    });
+
+    it("stamps expire on the next macrotask, not within the task's microtasks", async () => {
+      const target = {};
+      LoopGuard.run(5, () => LoopGuard.write(target, "x", () => {}));
+      expect(LoopGuard.depthOf(target, "x")).toBe(6);
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(LoopGuard.depthOf(target, "x")).toBe(6);
+      await wait(0);
+      expect(LoopGuard.depthOf(target, "x")).toBe(0);
+    });
+
+    it("a write in a later task starts a fresh chain even on a previously stamped address", async () => {
+      const target = {};
+      LoopGuard.run(20, () => LoopGuard.write(target, "x", () => {}));
+      await wait(0);
+      // an external writer (no context) does not inherit the old depth
+      LoopGuard.write(target, "x", () => {});
+      expect(LoopGuard.depthOf(target, "x")).toBe(1);
+    });
+
+    it("write() runs fn and returns its result", () => {
+      const fn = vi.fn(() => 42);
+      expect(LoopGuard.write({}, "x", fn)).toBe(42);
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("the limit", () => {
+    it("defaults to 50 and is configurable", () => {
+      expect(LoopGuard.limit).toBe(50);
+      LoopGuard.configure({ limit: 7 });
+      expect(LoopGuard.limit).toBe(7);
+      LoopGuard.configure({ limit: 0 });
+      expect(LoopGuard.limit).toBe(7);
+      LoopGuard.configure({ limit: 3.9 });
+      expect(LoopGuard.limit).toBe(3);
+      LoopGuard.reset();
+      expect(LoopGuard.limit).toBe(50);
+    });
+
+    it("drops a write past the limit, reports it and returns false", () => {
+      LoopGuard.configure({ limit: 3 });
+      const target = document.createElement("div");
+      const fn = vi.fn();
+      // depth 3 is still allowed …
+      expect(LoopGuard.run(2, () => LoopGuard.write(target, "x", fn))).not.toBe(
+        false
+      );
+      expect(fn).toHaveBeenCalledTimes(1);
+      // … depth 4 is not
+      expect(LoopGuard.run(3, () => LoopGuard.write(target, "y", fn))).toBe(
+        false
+      );
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(LoopGuard.depthOf(target, "y")).toBe(0);
+      expect(trips).toHaveLength(1);
+      expect(trips[0]).toMatchObject({
+        kind: "depth",
+        target,
+        name: "y",
+        depth: 4,
+        limit: 3,
+      });
+      expect(trips[0].message).toContain('"y"');
+      expect(trips[0].message).toContain("<div>");
+    });
+
+    it("chains climb one hop at a time through inherited stamps", () => {
+      LoopGuard.configure({ limit: 5 });
+      const target = {};
+      // simulate engine hops: each reaction inherits the stamp it reacts to
+      let hops = 0;
+      const hop = (name: string) =>
+        LoopGuard.run(LoopGuard.depthOf(target, name), () => {
+          const next = name === "a" ? "b" : "a";
+          if (LoopGuard.write(target, next, () => hops++) !== false) hop(next);
+        });
+      hop("a");
+      expect(hops).toBe(5);
+      expect(trips).toHaveLength(1);
+      expect(trips[0].depth).toBe(6);
+    });
+  });
+
+  describe("reporting", () => {
+    it("logs once per name per task but notifies listeners every time", () => {
+      LoopGuard.configure({ limit: 1 });
+      const target = {};
+      LoopGuard.run(1, () => {
+        LoopGuard.write(target, "x", () => {});
+        LoopGuard.write(target, "x", () => {});
+        LoopGuard.write(target, "z", () => {});
+      });
+      expect(trips).toHaveLength(3);
+      expect(logs).toHaveLength(2);
+      expect(logs[0]).toContain("Loop guard");
+    });
+
+    it("logs again in a later task", async () => {
+      LoopGuard.configure({ limit: 1 });
+      const target = {};
+      LoopGuard.run(1, () => LoopGuard.write(target, "x", () => {}));
+      await wait(0);
+      LoopGuard.run(1, () => LoopGuard.write(target, "x", () => {}));
+      expect(logs).toHaveLength(2);
+    });
+
+    it("logs to console.error by default", () => {
+      LoopGuard.reset();
+      const error = vi.spyOn(console, "error").mockImplementation(() => {});
+      LoopGuard.report({
+        kind: "depth",
+        target: {},
+        name: "x",
+        depth: 51,
+        limit: 50,
+        message: "custom message",
+      });
+      expect(error).toHaveBeenCalledWith("custom message");
+    });
+
+    it("unsubscribes listeners", () => {
+      off();
+      LoopGuard.configure({ limit: 1 });
+      LoopGuard.run(1, () => LoopGuard.write({}, "x", () => {}));
+      expect(trips).toEqual([]);
+      off = () => {};
+    });
+
+    it("reset() keeps listeners but clears contexts, stamps and configuration", () => {
+      const target = {};
+      LoopGuard.configure({ limit: 2 });
+      LoopGuard.stamp(target, "x", 9);
+      LoopGuard.reset();
+      expect(LoopGuard.depthOf(target, "x")).toBe(0);
+      expect(LoopGuard.current()).toBe(0);
+      expect(LoopGuard.limit).toBe(50);
+      LoopGuard.configure({ log: () => {} });
+      LoopGuard.run(50, () => LoopGuard.write(target, "x", () => {}));
+      expect(trips).toHaveLength(1);
+    });
+  });
+});

package/support/tests/property.test.ts

@@ -0,0 +1,355 @@
+import {
+  defineObservableProperty,
+  isObservedProperty,
+  observeProperty,
+} from "../../property";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+describe("observeProperty", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("observes an own data property and keeps its value", () => {
+    const obj: { n: number } = { n: 1 };
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "n", seen);
+    expect(obj.n).toBe(1);
+    obj.n = 2;
+    expect(obj.n).toBe(2);
+    expect(seen).toHaveBeenCalledWith(2, 1);
+    obj.n = 2;
+    expect(seen).toHaveBeenCalledTimes(1);
+    stop();
+  });
+
+  it("restores a data property when the last observer leaves", () => {
+    const obj: { n: number } = { n: 1 };
+    const stop = observeProperty(obj, "n", () => {});
+    obj.n = 5;
+    expect(Object.getOwnPropertyDescriptor(obj, "n")?.get).toBeTypeOf(
+      "function",
+    );
+    stop();
+    const restored = Object.getOwnPropertyDescriptor(obj, "n");
+    expect(restored?.value).toBe(5);
+    expect(restored?.writable).toBe(true);
+    expect(isObservedProperty(obj, "n")).toBe(false);
+  });
+
+  it("shadows an inherited accessor and still runs its setter", () => {
+    class Box {
+      #v = "a";
+      calls = 0;
+      get v() {
+        return this.#v;
+      }
+      set v(next: string) {
+        this.calls++;
+        this.#v = next;
+      }
+    }
+    const box = new Box();
+    const seen = vi.fn();
+    const stop = observeProperty(box, "v", seen);
+    box.v = "b";
+    expect(box.v).toBe("b");
+    expect(box.calls).toBe(1);
+    expect(seen).toHaveBeenCalledWith("b", "a");
+    stop();
+    expect(Object.getOwnPropertyDescriptor(box, "v")).toBeUndefined();
+    box.v = "c";
+    expect(box.calls).toBe(2);
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it("observes a native element property set from JS", () => {
+    const input = document.createElement("input");
+    document.body.append(input);
+    const seen = vi.fn();
+    const stop = observeProperty(input, "value", seen);
+    input.value = "typed";
+    expect(input.value).toBe("typed");
+    expect(seen).toHaveBeenCalledWith("typed", "");
+    // the wrapper delegates to the platform accessor: attribute untouched
+    expect(input.getAttribute("value")).toBeNull();
+    stop();
+    expect(Object.getOwnPropertyDescriptor(input, "value")).toBeUndefined();
+  });
+
+  it("shares one wrapper between observers", () => {
+    const obj: { n: number } = { n: 0 };
+    const a = vi.fn();
+    const b = vi.fn();
+    const stopA = observeProperty(obj, "n", a);
+    const stopB = observeProperty(obj, "n", b);
+    obj.n = 1;
+    expect(a).toHaveBeenCalledTimes(1);
+    expect(b).toHaveBeenCalledTimes(1);
+    stopA();
+    obj.n = 2;
+    expect(a).toHaveBeenCalledTimes(1);
+    expect(b).toHaveBeenCalledTimes(2);
+    expect(isObservedProperty(obj, "n")).toBe(true);
+    stopB();
+    expect(isObservedProperty(obj, "n")).toBe(false);
+    expect(obj.n).toBe(2);
+  });
+
+  it("does nothing for read-only properties", () => {
+    const obj = Object.freeze({ n: 1 });
+    const stop = observeProperty(obj, "n", () => {});
+    expect(obj.n).toBe(1);
+    expect(isObservedProperty(obj, "n")).toBe(false);
+    stop();
+    const getterOnly = {
+      get g() {
+        return 1;
+      },
+    };
+    expect(isObservedProperty(getterOnly, "g")).toBe(false);
+    observeProperty(getterOnly, "g", () => {})();
+    expect(getterOnly.g).toBe(1);
+  });
+
+  it("observes a property that does not exist yet", () => {
+    const obj: Record<string, unknown> = {};
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "later", seen);
+    expect(obj.later).toBeUndefined();
+    obj.later = { a: 1 };
+    expect(seen).toHaveBeenCalledWith({ a: 1 }, undefined);
+    stop();
+    expect(obj.later).toEqual({ a: 1 });
+  });
+});
+
+describe("defineObservableProperty", () => {
+  it("defines a storage-owning accessor when nothing observes", () => {
+    const obj: { n?: number } = {};
+    let store = 0;
+    defineObservableProperty(obj, "n", {
+      get: () => store,
+      set: (v) => {
+        store = (v as number) * 10;
+      },
+    });
+    obj.n = 2;
+    expect(obj.n).toBe(20);
+    expect(Object.getOwnPropertyDescriptor(obj, "n")?.enumerable).toBe(false);
+  });
+
+  it("keeps an installed observer when the base is defined afterwards (upgrade)", () => {
+    // pre-upgrade: a plain data property with a value
+    const el = document.createElement("div") as HTMLElement & {
+      provision?: unknown;
+    };
+    el.provision = { early: true };
+    const seen = vi.fn();
+    const stop = observeProperty(el, "provision", seen);
+    // upgrade: the element class takes over storage
+    let store: unknown = null;
+    defineObservableProperty(el, "provision", {
+      get: () => store,
+      set: (v) => {
+        store = v;
+      },
+    });
+    el.provision = { late: true };
+    expect(store).toEqual({ late: true });
+    expect(el.provision).toEqual({ late: true });
+    expect(seen).toHaveBeenLastCalledWith({ late: true }, null);
+    stop();
+    // the base accessor is what remains
+    el.provision = { after: true };
+    expect(store).toEqual({ after: true });
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it("notifies after the base setter finished", () => {
+    const obj: { n?: number } = {};
+    const order: string[] = [];
+    let store = 0;
+    defineObservableProperty(obj, "n", {
+      get: () => store,
+      set: (v) => {
+        order.push("base");
+        store = v as number;
+      },
+    });
+    observeProperty(obj, "n", () => order.push("observer"));
+    obj.n = 1;
+    expect(order).toEqual(["base", "observer"]);
+  });
+
+  it("falls through to a plain define when the wrapper was replaced", () => {
+    const obj: Record<string, unknown> = { n: 1 };
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "n", seen);
+    // something redefines the property over the wrapper
+    Object.defineProperty(obj, "n", {
+      value: 5,
+      writable: true,
+      configurable: true,
+      enumerable: true,
+    });
+    let store = 0;
+    defineObservableProperty(obj, "n", {
+      get: () => store,
+      set: (v) => {
+        store = v as number;
+      },
+      enumerable: true,
+    });
+    obj.n = 7;
+    expect(store).toBe(7);
+    expect(obj.n).toBe(7);
+    expect(seen).not.toHaveBeenCalled();
+    expect(Object.getOwnPropertyDescriptor(obj, "n")?.enumerable).toBe(true);
+    stop();
+    expect(obj.n).toBe(7);
+  });
+
+  it("installs the observer over an existing own accessor and restores it", () => {
+    const obj: Record<string, unknown> = {};
+    let store = "a";
+    defineObservableProperty(obj, "v", {
+      get: () => store,
+      set: (next) => {
+        store = next as string;
+      },
+      enumerable: true,
+    });
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "v", seen);
+    obj.v = "b";
+    expect(seen).toHaveBeenCalledWith("b", "a");
+    stop();
+    const restored = Object.getOwnPropertyDescriptor(obj, "v");
+    expect(restored?.get).toBeTypeOf("function");
+    expect(restored?.enumerable).toBe(true);
+    obj.v = "c";
+    expect(store).toBe("c");
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("observeProperty edge cases", () => {
+  it("observes an inherited data property through an own shadow", () => {
+    const proto = { n: 1 };
+    const obj = Object.create(proto) as { n: number };
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "n", seen);
+    expect(obj.n).toBe(1);
+    obj.n = 2;
+    expect(seen).toHaveBeenCalledWith(2, 1);
+    expect(proto.n).toBe(1);
+    stop();
+    // the shadow is removed; reads fall back to the prototype
+    expect(Object.getOwnPropertyDescriptor(obj, "n")).toBeUndefined();
+    expect(obj.n).toBe(1);
+  });
+
+  it("leaves a non-configurable own accessor alone", () => {
+    const obj = {} as { x: number };
+    let store = 1;
+    Object.defineProperty(obj, "x", {
+      get: () => store,
+      set: (v: number) => {
+        store = v;
+      },
+      configurable: false,
+    });
+    const seen = vi.fn();
+    const stop = observeProperty(obj, "x", seen);
+    obj.x = 2;
+    expect(store).toBe(2);
+    expect(seen).not.toHaveBeenCalled();
+    expect(isObservedProperty(obj, "x")).toBe(false);
+    stop();
+  });
+
+  it("does not restore when something redefined the property meanwhile", () => {
+    const obj: Record<string, unknown> = { n: 1 };
+    const stop = observeProperty(obj, "n", () => {});
+    Object.defineProperty(obj, "n", {
+      value: "redefined",
+      writable: false,
+      configurable: true,
+    });
+    stop();
+    expect(isObservedProperty(obj, "n")).toBe(false);
+    const descriptor = Object.getOwnPropertyDescriptor(obj, "n");
+    expect(descriptor?.value).toBe("redefined");
+    expect(descriptor?.writable).toBe(false);
+  });
+
+  it("unsubscribing twice is harmless", () => {
+    const obj: { n: number } = { n: 1 };
+    const a = vi.fn();
+    const b = vi.fn();
+    const stopA = observeProperty(obj, "n", a);
+    const stopB = observeProperty(obj, "n", b);
+    stopA();
+    stopA();
+    expect(isObservedProperty(obj, "n")).toBe(true);
+    obj.n = 2;
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalledWith(2, 1);
+    stopB();
+    expect(isObservedProperty(obj, "n")).toBe(false);
+    expect(Object.getOwnPropertyDescriptor(obj, "n")?.value).toBe(2);
+  });
+
+  it("chains a reflected native accessor so the attribute still updates", () => {
+    const el = document.createElement("div");
+    document.body.append(el);
+    const seen = vi.fn();
+    const stop = observeProperty(el, "title", seen);
+    el.title = "hint";
+    expect(el.getAttribute("title")).toBe("hint");
+    expect(seen).toHaveBeenCalledWith("hint", "");
+    el.setAttribute("title", "changed");
+    // attribute writes bypass the setter: no notification, but reads are live
+    expect(el.title).toBe("changed");
+    expect(seen).toHaveBeenCalledTimes(1);
+    stop();
+    expect(Object.getOwnPropertyDescriptor(el, "title")).toBeUndefined();
+    el.title = "after";
+    expect(el.getAttribute("title")).toBe("after");
+    expect(seen).toHaveBeenCalledTimes(1);
+  });
+
+  it("observes a property set only later on a class instance accessor", () => {
+    class Widget {
+      #count = 0;
+      get count() {
+        return this.#count;
+      }
+      set count(v: number) {
+        this.#count = v;
+      }
+    }
+    const w = new Widget();
+    const seen = vi.fn();
+    const stop = observeProperty(w, "count", seen);
+    // the wrapper is an own property; the class accessor stays on the prototype
+    expect(Object.getOwnPropertyDescriptor(w, "count")?.get).toBeTypeOf(
+      "function",
+    );
+    w.count = 3;
+    expect(w.count).toBe(3);
+    expect(seen).toHaveBeenCalledWith(3, 0);
+    w.count = 3;
+    expect(seen).toHaveBeenCalledTimes(1);
+    stop();
+    expect(Object.getOwnPropertyDescriptor(w, "count")).toBeUndefined();
+    expect(w.count).toBe(3);
+  });
+});