informa 3.1.0 → 4.0.0

package/src/quirks/basestatified.ts

@@ -1,163 +1,340 @@
+import { EnumerableWeakMap } from "../EnumerableWeakMap.js";
+import { EnumerableWeakSet } from "../EnumerableWeakSet.js";
 import {
   exitProxySymbol,
   getMetadataOf,
   getGlobalStateMode,
+  isStatified,
+  metadataMap,
   setMetadataOf,
   statifySealKey,
   type Statify,
 } from "../internals.js";
 import {
   emitDescendantPathEvents,
+  emitCollectionTransition,
   extract,
   hook,
+  registerPreExtractionHook,
   StateMetadata,
   unhook,
-  type ExitProxyValue,
   type StatifiableObj,
 } from "../low.js";
 
 type ClassType<T extends any[] = any[], U = object> = new (...args: T) => U;
-const classMapMemo = new WeakMap<ClassType, ClassType>();
 
-const blanketProtoMemo = new WeakMap<object, object>();
-const blanketProtoSet = new WeakSet<object>();
+// Classes whose instances have been constructed but not yet field-instrumented.
+const pendingAssemblies = new EnumerableWeakSet<object>();
+
+// Map from a still-pending child instance → list of (parentMetadata, prop) pairs
+// that need hook() called once the child is reconciled.
+const deferredHooks = new EnumerableWeakMap<object, { metadata: StateMetadata; prop: string | symbol }[]>();
+
+// One shim proxy per outermost constructor (new.target).
+const shimCache = new WeakMap<Function, object>();
+
+function getPrototypeChainDescriptor(
+  obj: object,
+  prop: string | symbol,
+): PropertyDescriptor | undefined {
+  let curr: object | null = obj;
+  while (curr !== null) {
+    const desc = Object.getOwnPropertyDescriptor(curr, prop);
+    if (desc) return desc;
+    curr = Object.getPrototypeOf(curr);
+  }
+  return undefined;
+}
 
-function getBlanketPrototype(actualProto: object) {
-  const maybeMemoed = blanketProtoMemo.get(actualProto);
-  if (maybeMemoed) return maybeMemoed;
+const shimHandler: ProxyHandler<object> = {
+  get(target, prop, recv) {
+    // Always signal that this object is statified.
+    if (prop === statifySealKey) return true;
 
-  const storage = Object.create(actualProto) as {
-    [statifySealKey]: true;
-    [exitProxySymbol]: ExitProxyValue;
-  };
-  // storage[statifySealKey] = true;
+    if (getGlobalStateMode() === "extract-proxy-path") {
+      // Root-level exit: this instance IS the stateRoot.
+      if (prop === exitProxySymbol) {
+        return { path: [], stateRoot: recv as Statify<StatifiableObj> };
+      }
 
-  const blanket = new Proxy(storage, {
-    get(target, prop, recv) {
-      if (prop === statifySealKey) return true;
+      // Safety net: reconcile if somehow still pending at extraction time.
+      if (pendingAssemblies.has(recv as object)) {
+        reconcileInstance(recv as object);
+      }
 
-      if (getGlobalStateMode() === "extract-proxy-path") {
-        if (prop === exitProxySymbol) {
-          return { path: [], stateRoot: recv as Statify<StatifiableObj> };
-        }
+      // Forward to extract() so the path is captured.
+      // Own accessor properties on recv are already handling extract-proxy-path
+      // themselves; the shim is only reached for prototype-level props.
+      return extract(
+        Reflect.get(target, prop, recv),
+        recv as Statify<StatifiableObj>,
+        [prop],
+      );
+    }
 
-        return extract(undefined, recv as Statify<StatifiableObj>, [prop]);
-      }
+    return Reflect.get(target, prop, recv);
+  },
+
+  set(target, prop, newVal, recv) {
+    // This trap fires only when `prop` is NOT an own property of `recv`.
+    // That covers:
+    //   (a) Pre-reconciliation field initializer writes → create own data prop.
+    //   (b) Prototype accessor writes (e.g. `get state()` / `set state()`).
+    //   (c) Genuinely new dynamic property additions.
+    //
+    // Own accessor properties installed by reconcileInstance are handled
+    // by their own setters and never reach here.
 
-      return Reflect.get(target, prop, recv);
-    },
+    // Check for a prototype-level accessor setter BEFORE calling Reflect.set.
+    const protoDesc = getPrototypeChainDescriptor(target, prop);
 
-    set(target, prop, newVal, recv) {
+    // Delegate the actual assignment.
+    const result = Reflect.set(target, prop, newVal, recv);
+
+    // If this was a prototype accessor write and the instance has metadata,
+    // emit replacement events so subscribers fire.
+    if (result && protoDesc?.set && metadataMap.has(recv as Statify<StatifiableObj>)) {
       const stateMetadata = getMetadataOf(recv as Statify<StatifiableObj>);
+      stateMetadata.emit("replaceProp", newVal, prop);
+      const ee = stateMetadata.eventEmitterAtPathMaybe([prop]);
+      if (ee) {
+        ee.emit("replace", newVal);
+        emitDescendantPathEvents(stateMetadata, [prop], newVal, true);
+      }
+    }
 
-      const had = Reflect.has(recv, prop);
-      const oldVal = Reflect.get(recv, prop) as unknown;
+    return result;
+  },
+
+  has(target, prop) {
+    if (prop === statifySealKey || prop === exitProxySymbol) return true;
+    return Reflect.has(target, prop);
+  },
+};
+
+function getOrCreateShim(ctor: Function): object {
+  const cached = shimCache.get(ctor);
+  if (cached) return cached;
+
+  // shimTarget's [[Prototype]] = ctor.prototype, so the full chain is:
+  //   instance → shim → shimTarget → ctor.prototype → … → Superclass.prototype
+  // This preserves instanceof for all classes in the chain.
+  const shimTarget = Object.create((ctor as ClassType).prototype) as object;
+  const shim = new Proxy(shimTarget, shimHandler);
+  shimCache.set(ctor, shim);
+  return shim;
+}
 
-      const result = Reflect.set(target, prop, newVal, recv);
+/**
+ * Converts all enumerable, configurable own data properties of `instance` into
+ * accessor-backed reactive properties connected to `instance`'s StateMetadata.
+ *
+ * Idempotent: returns immediately if the instance is not in pendingAssemblies.
+ */
+function reconcileInstance(instance: object): void {
+  if (!pendingAssemblies.has(instance)) return;
+  pendingAssemblies.delete(instance);
+
+  // Drain any deferred hooks where this instance was the pending child.
+  const deferred = deferredHooks.get(instance);
+  if (deferred) {
+    deferredHooks.delete(instance);
+    const childMetadata = getMetadataOf(instance as Statify<StatifiableObj>);
+    for (const { metadata: parentMetadata, prop } of deferred) {
+      hook(parentMetadata, prop, childMetadata);
+    }
+  }
+
+  // Metadata was installed eagerly in ExtractionShimBase's constructor.
+  const metadata = getMetadataOf(instance as Statify<StatifiableObj>);
+
+  const isArray = Array.isArray(instance);
+
+  const props: (string | symbol)[] = [
+    ...Object.getOwnPropertyNames(instance),
+    ...Object.getOwnPropertySymbols(instance),
+  ];
+
+  for (const prop of props) {
+    // Skip Informa internal symbols.
+    if (prop === statifySealKey || prop === exitProxySymbol) continue;
+
+    // Skip array numeric indices — managed by the array's own push/pop/splice overrides.
+    if (isArray && typeof prop === "string" && Number.isInteger(Number(prop))) continue;
+
+    const desc = Object.getOwnPropertyDescriptor(instance, prop)!;
+
+    // Non-configurable: cannot be redefined; leave non-reactive.
+    // Note: these properties retain their value but won't participate in the
+    // observable graph. This is intentional and tested.
+    if (!desc.configurable) continue;
+
+    // Existing accessor (get/set): do not double-wrap.
+    if ("get" in desc || "set" in desc) continue;
+
+    // ---- Instrument this configurable data property ----
+    let value: unknown = desc.value;
+
+    // Hook the initial value if it is itself statified.
+    if (
+      value != null &&
+      typeof value === "object" &&
+      isStatified(value as StatifiableObj)
+    ) {
+      if (pendingAssemblies.has(value as object)) {
+        // The nested value is itself pending (constructed during this constructor
+        // but not yet reconciled — its metadata doesn't exist yet). Defer the
+        // hook: it will be wired once reconcileInstance runs for that child.
+        deferredHooks.getOrInsertComputed(value as object, () => []).push({ metadata, prop });
+      } else {
+        hook(metadata, prop, getMetadataOf(value as Statify<StatifiableObj>));
+      }
+    }
 
-      try {
-        if (result) {
+    Object.defineProperty(instance, prop, {
+      get(this: object) {
+        if (getGlobalStateMode() === "extract-proxy-path") {
+          return extract(value, this as Statify<StatifiableObj>, [prop]);
+        }
+        return value;
+      },
+
+      set(this: object, next: unknown) {
+        const old = value;
+        value = next;
+
+        if (old !== next) {
           if (
-            typeof newVal === "object"
-            && newVal != null
-            && (newVal as any)[statifySealKey]
+            old != null &&
+            typeof old === "object" &&
+            isStatified(old as StatifiableObj)
           ) {
-            hook(
-              stateMetadata,
-              prop,
-              getMetadataOf(newVal as Statify<StatifiableObj>),
-            );
+            unhook(metadata, prop, getMetadataOf(old as Statify<StatifiableObj>));
           }
 
-          if (had) {
-            if (
-              oldVal !== newVal
-              && typeof oldVal === "object"
-              && oldVal != null
-              && (oldVal as any)[statifySealKey]
-            ) {
-              unhook(
-                stateMetadata,
-                prop,
-                getMetadataOf(oldVal as Statify<StatifiableObj>),
-              );
-            }
-
-            stateMetadata.emit("replaceProp", newVal, prop);
+          if (
+            next != null &&
+            typeof next === "object" &&
+            isStatified(next as StatifiableObj)
+          ) {
+            hook(metadata, prop, getMetadataOf(next as Statify<StatifiableObj>));
           }
 
-          stateMetadata.emit("setProp", newVal, prop);
-
-          const maybeEventEmitterAtPath = stateMetadata.eventEmitterAtPathMaybe([prop]);
-          if (maybeEventEmitterAtPath) {
-            if (had) {
-              maybeEventEmitterAtPath.emit("replace", newVal);
-            }
-
-            maybeEventEmitterAtPath.emit("set", newVal);
-
-            emitDescendantPathEvents(
-              stateMetadata,
-              [prop],
-              newVal,
-              had,
-            );
-          }
+          emitCollectionTransition(old, next);
         }
-      } finally {
-        return result;
-      }
-    },
-
-    has(target, prop) {
-      if (getGlobalStateMode() === "extract-proxy-path" && prop === exitProxySymbol) {
-        return true;
-      }
-
-      return Reflect.has(target, prop);
-    },
-  });
 
-  blanketProtoMemo.set(actualProto, blanket);
-  blanketProtoSet.add(blanket);
+        // Enter the existing replacement machinery — same path as statifyObject's
+        // set trap in low.ts. "listen → replace → fire" is preserved because this
+        // accessor is installed before any external mutation can reach the field.
+        metadata.emit("replaceProp", next, prop);
 
-  return blanket;
+        const ee = metadata.eventEmitterAtPathMaybe([prop]);
+        if (ee) {
+          ee.emit("replace", next);
+          emitDescendantPathEvents(metadata, [prop], next, true);
+        }
+      },
+
+      enumerable: desc.enumerable ?? true,
+      configurable: true,
+    });
+  }
+
+  // Selector/stateRoot identity: verified correct. Every on*()/off*() call goes
+  // through selectorToRootAndPath(), which fires preExtractionHooks() before
+  // entering extract-proxy-path mode. The preExtractionHook registered below
+  // reconciles all pending instances first — so by the time the selector function
+  // runs, every pending `this.x` field is already an accessor that returns
+  // extract(value, this, ['x']). Path chains like `() => this.a.b.c` are therefore
+  // built up correctly, and stateRoot is the raw instance, which is the same object
+  // keyed in metadataMap. No re-mapping needed.
 }
 
-export function makeStatified<
-  V extends ClassType<T, U>,
-  T extends any[],
-  U extends object,
+// Before selectorToRootAndPath enters extract-proxy-path mode it calls all
+// registered hooks. This hook reconciles every pending instance so that their
+// own data properties are already accessor-backed when the selector runs.
+
+registerPreExtractionHook(() => {
+  // Snapshot: reconcileInstance removes from pendingAssemblies, which mutates
+  // the set during iteration — take a copy first.
+  const snapshot = [...pendingAssemblies];
+  for (const instance of snapshot) {
+    reconcileInstance(instance);
+  }
+});
+
+/**
+ * Wraps a user-defined class factory in the Informa observable lifecycle.
+ *
+ * Usage:
+ * ```ts
+ * const MyClass = statifyClass(
+ *   (Base) => class MyClass extends Base {
+ *     name = "default";
+ *     constructor(name: string) { super(); this.name = name; }
+ *   },
+ *   Object,
+ * );
+ * ```
+ *
+ * Construction lifecycle:
+ *   1. ExtractionShimBase constructor runs → metadata installed, shim set as prototype.
+ *   2. UserSubclass field initializers run → own data properties created on instance.
+ *   3. UserSubclass constructor body runs.
+ *   4. Instance is in pendingAssemblies (field instrumentation deferred).
+ *   5. On first `on()`/`off()` call → registerPreExtractionHook fires → reconcileInstance
+ *      converts own data properties to reactive accessor-backed properties.
+ */
+export function statifyClass<
+  SubclassType extends ClassType<ArgsSub, OutSub>,
+  ArgsSub extends any[],
+  OutSub extends object,
+  SuperclassType extends ClassType<ArgsSuper, OutSuper>,
+  ArgsSuper extends any[],
+  OutSuper extends object,
 >(
-  OriginalClass: V,
-): V {
-  const maybeMemoed = classMapMemo.get(OriginalClass);
-  if (maybeMemoed) return maybeMemoed as V;
-
-  // @ts-ignore - ts-2545 "A mixin class must have a constructor with a single rest parameter of type 'any[]'."
-  class Statified extends OriginalClass {
-    constructor(...args: T) {
-      super(...args);
-
-      const ctor = new.target ?? Statified;
-      const inst = Reflect.construct(OriginalClass, args, ctor) as Statify<U>;
-
-      setMetadataOf(inst, new StateMetadata());
-
-      const actualProto = ctor.prototype;
-      const finalProto = blanketProtoSet.has(actualProto)
-        ? actualProto
-        : getBlanketPrototype(actualProto);
-
-      Reflect.setPrototypeOf(inst, finalProto);
+  makeSubclass: (SuperclassIn: SuperclassType) => SubclassType,
+  Superclass: SuperclassType,
+): SubclassType & ClassType<ArgsSub, Statify<OutSub>> {
+
+  // ExtractionShimBase sits between Superclass and the user's class.
+  // Its constructor:
+  //   - Installs StateMetadata on the instance eagerly (so subclasses like
+  //     StatifiedArray can call getMetadataOf() from their constructor bodies).
+  //   - Marks the instance as pending for lazy field instrumentation.
+  //   - Inserts the shim proxy as the instance's [[Prototype]], enabling
+  //     statifySealKey / exitProxySymbol / extract-proxy-path handling.
+  //
+  // Guard: in nested statifyClass chains (e.g. statifyClass(..., A) where A
+  // was itself produced by statifyClass), multiple ExtractionShimBase
+  // constructors run. The guard ensures setup happens exactly once — at the
+  // innermost (deepest) ExtractionShimBase call.
+  class ExtractionShimBase extends (Superclass as unknown as typeof Object) {
+    constructor(...args: any[]) {
+      super(...(args as []));
+
+      if (!pendingAssemblies.has(this)) {
+        setMetadataOf(
+          this as unknown as Statify<StatifiableObj>,
+          new StateMetadata(),
+        );
+        pendingAssemblies.add(this);
+      }
 
-      return inst;
+      // Always update the shim to match the outermost constructor (new.target).
+      // In nested chains the innermost ExtractionShimBase sets the shim first;
+      // subsequent (shallower) ones overwrite it with the same value since
+      // new.target propagates as the outermost class throughout the chain.
+      const ctor = (new.target ?? ExtractionShimBase) as Function;
+      Reflect.setPrototypeOf(this, getOrCreateShim(ctor));
     }
-  };
-
-  classMapMemo.set(OriginalClass, Statified);
-
-  return Statified;
+  }
+
+  // Invoke the user's factory with the shim base, then return the result.
+  // No outer Statified wrapper is needed: field instrumentation is lazy,
+  // triggered by registerPreExtractionHook before any selectorToRootAndPath call.
+  return makeSubclass(
+    ExtractionShimBase as unknown as SuperclassType,
+  ) as unknown as SubclassType & ClassType<ArgsSub, Statify<OutSub>>;
 }
 
-export const BaseStatified = makeStatified(Object);

package/src/quirks/map.ts

@@ -1,4 +1,4 @@
-import { exitProxySymbol, getGlobalStateMode, setMetadataOf, Statify, statifySealKey } from "../internals.js";
+import { exitProxySymbol, getGlobalStateMode, isStatifiedMapKey, setMetadataOf, Statify, statifySealKey } from "../internals.js";
 import { ExitProxyValue, StateMetadata, StatifiableObj } from "../low.js";
 
 export class StatifiedMap<K, V> extends Map<K, V> implements Statify<Map<K, V>> {
@@ -58,3 +58,5 @@ export class StatifiedMap<K, V> extends Map<K, V> implements Statify<Map<K, V>>
     return this;
   }
 }
+
+(StatifiedMap.prototype as any)[isStatifiedMapKey] = true;

package/src/quirks/set.ts

@@ -1,4 +1,4 @@
-import { exitProxySymbol, getGlobalStateMode, setMetadataOf, statifySealKey, type Statify } from "../internals.js";
+import { exitProxySymbol, getGlobalStateMode, isStatifiedSetKey, setMetadataOf, statifySealKey, type Statify } from "../internals.js";
 import { StateMetadata, StatifiableObj, type ExitProxyValue, type StatifiableProp } from "../low.js";
 
 export class StatifiedSet<T extends StatifiableProp> extends Set<T> implements Statify<Set<T>> {
@@ -51,3 +51,5 @@ export class StatifiedSet<T extends StatifiableProp> extends Set<T> implements S
     return false;
   }
 }
+
+(StatifiedSet.prototype as any)[isStatifiedSetKey] = true;

package/src/test.ts

@@ -1,5 +1,4 @@
 import $ from "./high.js";
-import { BaseStatified } from "./quirks/basestatified.js";
 import { StatifiedSet } from "./quirks/set.js";
 
 const stateful = $.state<{ a: ({ d: number })[], b?: { c?: { d?: Set<number> } } }>({ a: [] });
@@ -27,20 +26,19 @@ const asdf2 = $.state({ c: asdf });
 // const aassddff = $.state(new Set());
 stateful.b = asdf2;
 
-class Wayland extends BaseStatified {
-  displays = new StatifiedSet();
-
-  #state = 0;
-  get state() { return this.#state; }
-  set state(v: number) {
-    console.log("set", v)
-    this.#state = v;
-  }
-
-  constructor() {
-    super();
-  }
-}
+const Wayland = $.statifyClass(
+  (Base) => class Wayland extends Base {
+    displays = new StatifiedSet();
+
+    #state = 0;
+    get state() { return this.#state; }
+    set state(v: number) {
+      console.log("set", v);
+      this.#state = v;
+    }
+  },
+  Object,
+);
 
 const w = new Wayland();
 $.onSet(() => w.state, (v) => console.log("asdf awawa!!", v));