@praxisjs/decorators 1.6.1 → 1.7.0

package/src/__tests__/deep-state.test.ts

@@ -183,3 +183,83 @@ describe("@DeepState decorator", () => {
     expect(log).toEqual([0, 42]);
   });
 });
+
+describe("@DeepState — proxy identity and notifications", () => {
+  function setup(initial: unknown) {
+    const { ctx, run } = fieldCtx("data");
+    DeepState()(undefined, ctx);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).data = initial;
+    run(instance);
+    const inst = instance as unknown as { data: any };
+    let runs = 0;
+    effect(() => {
+      void inst.data;
+      runs++;
+    });
+    runs = 0;
+    return { inst, runs: () => runs };
+  }
+
+  it("returns the same proxy for the same nested object", () => {
+    const { inst } = setup({ nested: { a: 1 } });
+    expect(inst.data.nested).toBe(inst.data.nested);
+  });
+
+  it("keeps identity across reads after an unrelated mutation", () => {
+    const { inst } = setup({ nested: { a: 1 }, other: 0 });
+    const before = inst.data.nested;
+    inst.data.other = 1;
+    expect(inst.data.nested).toBe(before);
+  });
+
+  it("returns a fresh proxy once the root is replaced", () => {
+    const { inst } = setup({ nested: { a: 1 } });
+    const before = inst.data;
+    inst.data = { nested: { a: 1 } };
+    expect(inst.data).not.toBe(before);
+  });
+
+  it("does not notify when a property is set to the value it already has", () => {
+    const { inst, runs } = setup({ a: 1 });
+    inst.data.a = 1;
+    expect(runs()).toBe(0);
+  });
+
+  it("notifies when a property changes or a new key is added", () => {
+    const { inst, runs } = setup({ a: 1 });
+    inst.data.a = 2;
+    expect(runs()).toBe(1);
+    inst.data.b = 3;
+    expect(runs()).toBe(2);
+  });
+
+  it("notifies once for an array push", () => {
+    const { inst, runs } = setup({ list: [1] });
+    inst.data.list.push(2);
+    expect(runs()).toBe(1);
+    expect(inst.data.list.length).toBe(2);
+  });
+
+  it("notifies on delete only when the key existed", () => {
+    const { inst, runs } = setup({ a: 1 });
+    delete inst.data.missing;
+    expect(runs()).toBe(0);
+    delete inst.data.a;
+    expect(runs()).toBe(1);
+  });
+
+  it("assigning a primitive root and null roots still works", () => {
+    const { ctx, run } = fieldCtx("n");
+    DeepState()(undefined, ctx);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).n = null;
+    run(instance);
+    const inst = instance as unknown as { n: unknown };
+    expect(inst.n).toBeNull();
+    inst.n = 5;
+    expect(inst.n).toBe(5);
+    inst.n = { x: 1 };
+    expect((inst.n as { x: number }).x).toBe(1);
+  });
+});

package/src/__tests__/memo.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
 
-import { signal } from "@praxisjs/core/internal";
+import { effect, signal } from "@praxisjs/core/internal";
 import { Memo } from "../functions/memo";
 
 function mockCtx(name: string) {
@@ -206,3 +206,88 @@ describe("Memo", () => {
     expect(fn).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("Memo({ max })", () => {
+  function setup(max: number) {
+    const fn = vi.fn((x: unknown) => (x as number) * 2);
+    const ctx = mockCtx("dbl");
+    Memo({ max })(fn, ctx);
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).dbl;
+    return { fn, method };
+  }
+
+  it("keeps at most max entries, evicting the oldest first", () => {
+    const { fn, method } = setup(2);
+    method(1);
+    method(2);
+    method(3); // evicts 1
+    expect(fn).toHaveBeenCalledTimes(3);
+    method(2);
+    method(3);
+    expect(fn).toHaveBeenCalledTimes(3);
+    method(1); // recomputed
+    expect(fn).toHaveBeenCalledTimes(4);
+  });
+
+  it("a cache hit refreshes recency so the used entry survives", () => {
+    const { fn, method } = setup(2);
+    method(1);
+    method(2);
+    method(1); // 1 is now the most recent
+    method(3); // evicts 2
+    fn.mockClear();
+    method(1);
+    expect(fn).not.toHaveBeenCalled();
+    method(2);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps 100 combinations by default and drops the oldest beyond that", () => {
+    const fn = vi.fn((x: unknown) => x);
+    const ctx = mockCtx("id");
+    Memo()(fn, ctx);
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).id;
+    for (let i = 0; i < 101; i++) method(i);
+    fn.mockClear();
+    method(100);
+    expect(fn).not.toHaveBeenCalled();
+    method(0);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("max: Infinity keeps every combination", () => {
+    const fn = vi.fn((x: unknown) => x);
+    const ctx = mockCtx("id");
+    Memo({ max: Infinity })(fn, ctx);
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).id;
+    for (let i = 0; i < 200; i++) method(i);
+    fn.mockClear();
+    for (let i = 0; i < 200; i++) method(i);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("an evicted entry that a binding still uses keeps updating", async () => {
+    const s = signal(1);
+    const fn = vi.fn((x: unknown) => (x as number) * s());
+    const ctx = mockCtx("scaled");
+    Memo({ max: 1 })(fn, ctx);
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).scaled;
+
+    let seen: unknown;
+    effect(() => {
+      seen = method(10);
+    });
+    method(20); // evicts the entry the effect reads
+    s.set(2);
+    await Promise.resolve();
+    expect(seen).toBe(20);
+  });
+});

package/src/__tests__/properties-browser.test.ts

@@ -232,3 +232,57 @@ describe("initSlots / getSlot", () => {
     expect(getSlot(instance, "nonexistent")).toEqual([]);
   });
 });
+
+describe("Persisted decorator — unmount cleanup", () => {
+  function mountPersisted(name: string, key: string) {
+    const { ctx, run } = fieldCtx(name);
+    Persisted<string>(key)(undefined, ctx);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>)[name] = "initial";
+    run(instance);
+    return instance as unknown as Record<string, unknown> & { onUnmount?: () => void };
+  }
+
+  function storageEvent(key: string, newValue: string) {
+    window.dispatchEvent(new StorageEvent("storage", { key, newValue, storageArea: localStorage }));
+  }
+
+  it("keeps syncing other tabs while mounted", () => {
+    const instance = mountPersisted("a", "sync-key");
+    storageEvent("sync-key", '"remote"');
+    expect(instance.a).toBe("remote");
+  });
+
+  it("stops listening for storage events after unmount", () => {
+    const instance = mountPersisted("a", "gone-key");
+    instance.onUnmount?.();
+    storageEvent("gone-key", '"remote"');
+    expect(instance.a).toBe("initial");
+  });
+
+  it("repeated mount/unmount cycles do not accumulate window listeners", () => {
+    const add = vi.spyOn(window, "addEventListener");
+    const remove = vi.spyOn(window, "removeEventListener");
+    for (let i = 0; i < 5; i++) mountPersisted("a", "cycle-key").onUnmount?.();
+    const added = add.mock.calls.filter(([type]) => type === "storage").length;
+    const removed = remove.mock.calls.filter(([type]) => type === "storage").length;
+    expect(added).toBe(5);
+    expect(removed).toBe(5);
+    add.mockRestore();
+    remove.mockRestore();
+  });
+
+  it("two fields sharing a key on one instance share one signal", () => {
+    const first = fieldCtx("a");
+    const second = fieldCtx("b");
+    Persisted<string>("shared-key")(undefined, first.ctx);
+    Persisted<string>("shared-key")(undefined, second.ctx);
+    const instance = new TestComponent() as unknown as Record<string, unknown>;
+    instance.a = "x";
+    instance.b = "y";
+    first.run(instance);
+    second.run(instance);
+    instance.a = "changed";
+    expect(instance.b).toBe("changed");
+  });
+});

package/src/__tests__/properties.test.ts

@@ -1524,3 +1524,33 @@ describe("createAccessorDecorator — init", () => {
     expect(result.init!.call(instance, "hello")).toBe("hello");
   });
 });
+
+describe("History decorator — unmount cleanup", () => {
+  function mountHistory() {
+    const { ctx, run } = fieldCtx("scoreHistory");
+    History("score")(undefined, ctx);
+    const s = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "score", {
+      get: () => s(),
+      set: (v: number) => { s.set(v); },
+      configurable: true,
+    });
+    run(instance);
+    return { s, instance: instance as unknown as { scoreHistory: { values: () => number[] }; onUnmount?: () => void } };
+  }
+
+  it("stops recording once the component unmounts", () => {
+    const { s, instance } = mountHistory();
+    expect(instance.scoreHistory.values()).toEqual([0]);
+    s.set(1);
+    instance.onUnmount?.();
+    s.set(2);
+    expect(instance.scoreHistory.values()).toEqual([0, 1]);
+  });
+
+  it("unmounting before the history was ever read is a no-op", () => {
+    const { instance } = mountHistory();
+    expect(() => { instance.onUnmount?.(); }).not.toThrow();
+  });
+});

package/src/functions/index.ts

@@ -1,4 +1,4 @@
-export { Memo } from "./memo";
+export { Memo, type MemoOptions } from "./memo";
 export { Bind } from "./bind";
 export { Log } from "./log";
 export { Once } from "./once";

package/src/functions/memo.ts

@@ -30,16 +30,40 @@ function serializeArgs(args: unknown[]) {
     .join("|");
 }
 
-export function Memo() {
+export interface MemoOptions {
+  /**
+   * Maximum number of cached argument combinations. When exceeded, the least recently used entry
+   * is dropped. Defaults to 100; pass `Infinity` to keep every combination.
+   */
+  max?: number;
+}
+
+const DEFAULT_MAX = 100;
+
+type Disposable = Computed<unknown> & { dispose(): void };
+
+export function Memo(options: MemoOptions = {}) {
+  const { max = DEFAULT_MAX } = options;
+
   return createMethodDecorator({
     wrap(original, instance, _name) {
       const cache = new Map<string, Computed<unknown>>();
       return (...args: unknown[]) => {
         const key = serializeArgs(args);
         let memoized = cache.get(key);
-        if (!memoized) {
+        if (memoized) {
+          // Re-insert so Map order tracks recency.
+          cache.delete(key);
+          cache.set(key, memoized);
+        } else {
           memoized = computed(() => original.apply(instance, args) as unknown);
           cache.set(key, memoized);
+          if (cache.size > max) {
+            const [oldestKey, oldest] = cache.entries().next().value as [string, Computed<unknown>];
+            cache.delete(oldestKey);
+            // Releases the entry's hold on the signals it read; a no-op if a binding still uses it.
+            (oldest as Disposable).dispose();
+          }
         }
         return memoized();
       };

package/src/index.ts

@@ -1,6 +1,7 @@
 export { Component, Lazy } from "./component";
 export {
   Memo,
+  type MemoOptions,
   Bind,
   Log,
   Once,

package/src/properties/deep-state.ts

@@ -4,37 +4,51 @@ import { createFieldDecorator } from "../create-field-decorator";
 
 import type { ReactiveHost } from "../reactive-host";
 
-function deepProxy<T extends object>(target: T, notify: () => void): T {
-  return new Proxy(target, {
+// One proxy per raw object: repeated reads return the same reference (so `a.b === a.b` and
+// identity comparisons in effects hold) and don't allocate a new Proxy on every access.
+function deepProxy<T extends object>(
+  target: T,
+  notify: () => void,
+  cache: WeakMap<object, object>,
+): T {
+  const existing = cache.get(target);
+  if (existing) return existing as T;
+
+  const proxy = new Proxy(target, {
     get(obj, key, receiver) {
       const val: unknown = Reflect.get(obj, key, receiver);
       if (val !== null && typeof val === "object") {
-        return deepProxy(val, notify);
+        return deepProxy(val, notify, cache);
       }
       return val;
     },
     set(obj, key, value) {
+      const had = Object.hasOwn(obj, key);
+      const prev: unknown = Reflect.get(obj, key);
       const result = Reflect.set(obj, key, value);
-      notify();
+      if (!had || !Object.is(prev, value)) notify();
       return result;
     },
     deleteProperty(obj, key) {
+      const had = Object.hasOwn(obj, key);
       const result = Reflect.deleteProperty(obj, key);
-      notify();
+      if (had) notify();
       return result;
     },
   });
+  cache.set(target, proxy);
+  return proxy;
 }
 
 export function DeepState() {
   return createFieldDecorator<ReactiveHost>({
     bind(instance, _name, initialValue) {
       const version = signal(0);
-      let current = initialValue;
+      const cache = new WeakMap<object, object>();
       let proxy =
-        current !== null && typeof current === "object"
-          ? deepProxy(current, notify)
-          : current;
+        initialValue !== null && typeof initialValue === "object"
+          ? deepProxy(initialValue, notify, cache)
+          : initialValue;
 
       function notify() {
         markStateDirty(instance);
@@ -48,10 +62,9 @@ export function DeepState() {
             return proxy;
           },
           set(value: unknown) {
-            current = value;
             proxy =
               value !== null && typeof value === "object"
-                ? deepProxy(value, notify)
+                ? deepProxy(value, notify, cache)
                 : value;
             notify();
           },

package/src/properties/history.ts

@@ -37,6 +37,8 @@ export function History(fieldName: string, limit = 50) {
           },
           enumerable: false,
         },
+        // The tracking effect would otherwise keep recording a source that outlives the component.
+        onUnmount() { h?.destroy(); },
       };
     },
   });

package/src/properties/persisted.ts

@@ -1,25 +1,30 @@
-import { persistedSignal, type PersistedSignalOptions } from "@praxisjs/core/internal";
-import type { Signal } from "@praxisjs/shared";
+import {
+  persistedSignal,
+  type PersistedSignal,
+  type PersistedSignalOptions,
+} from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
-const signalMap = new WeakMap<object, Map<string, Signal<unknown>>>();
+const signalMap = new WeakMap<object, Map<string, PersistedSignal<unknown>>>();
 
 function getOrCreateSignal<T>(
   instance: object,
   storageKey: string,
   initialValue: T,
   options: PersistedSignalOptions<T>,
-): Signal<T> {
-  if (!signalMap.has(instance)) signalMap.set(instance, new Map());
-  const map = signalMap.get(instance) as Map<string, Signal<unknown>>;
-  if (!map.has(storageKey)) {
-    map.set(
-      storageKey,
-      persistedSignal(storageKey, initialValue, options) as Signal<unknown>,
-    );
+): PersistedSignal<T> {
+  let map = signalMap.get(instance);
+  if (!map) {
+    map = new Map();
+    signalMap.set(instance, map);
   }
-  return map.get(storageKey) as Signal<T>;
+  let sig = map.get(storageKey);
+  if (!sig) {
+    sig = persistedSignal(storageKey, initialValue, options) as PersistedSignal<unknown>;
+    map.set(storageKey, sig);
+  }
+  return sig as PersistedSignal<T>;
 }
 
 export function Persisted<T>(
@@ -28,15 +33,14 @@ export function Persisted<T>(
 ) {
   return createFieldDecorator({
     bind(instance, name, initialValue) {
-      const storageKey = key ?? name;
-      getOrCreateSignal(instance, storageKey, initialValue as T, options);
+      const sig = getOrCreateSignal(instance, key ?? name, initialValue as T, options);
       return {
         descriptor: {
-          get: () =>
-            getOrCreateSignal(instance, storageKey, undefined as T, options)(),
-          set: (value: T) =>
-            { getOrCreateSignal(instance, storageKey, undefined as T, options).set(value); },
+          get: () => sig(),
+          set: (value: T) => { sig.set(value); },
         },
+        // Without this every mounted instance would leave a window "storage" listener behind.
+        onUnmount() { sig.close(); },
       };
     },
   });