bench: add LargeRoot retained-memory benchmark with heap snapshots; opt: clear referenceCache after read-only instantiation (toggle via MQT_KEEP_REF_CACHE); make resolveIdentifier robust without cache

Co-Authored-By: Harry Brundage <[email protected]>

Author: devin-ai-integration[bot]

Benchmarking.md

@@ -74,3 +74,24 @@ You can also use the profiler built into VSCode for executing scripts and profil
 pnpm build
 pnpm deoptigate dist/bench/create-many-model-class.js
 ```
+
+## Memory benchmarking
+
+A memory benchmark for retained heap usage of LargeRoot instantiation is available.
+
+Run it with:
+
+```sh
+# default N=10 instances
+pnpm x bench/memory-large-root.benchmark.ts
+
+# with GC exposed for cleaner readings
+node --expose-gc -r ts-node/register/transpile-only bench/memory-large-root.benchmark.ts
+
+# control number of instances retained
+MQT_MEMORY_N=20 pnpm x bench/memory-large-root.benchmark.ts
+```
+
+Artifacts are written to the repo root:
+- bench-LargeRoot-<timestamp>.json with before, after, and delta heap usage
+- bench-LargeRoot-<timestamp>.heapsnapshot for analysis in Chrome DevTools (Memory tab)

bench/memory-large-root.benchmark.ts

@@ -0,0 +1,63 @@
+import findRoot from "find-root";
+import fs from "fs";
+import { LargeRoot } from "../spec/fixtures/LargeRoot";
+import { benchmarker, newInspectorSession } from "./benchmark";
+
+const snapshot = JSON.parse(fs.readFileSync(findRoot(__dirname) + "/spec/fixtures/large-root-snapshot.json", "utf8"));
+
+const roots: any[] = [];
+const key = Date.now();
+
+export default benchmarker(
+  async (suite) => {
+    const N = Number(process.env.MQT_MEMORY_N || 10);
+
+    suite.add(`instantiate and retain LargeRoot (N=${N})`, function () {
+      try {
+        if ((globalThis as any).gc) (globalThis as any).gc();
+        const before = process.memoryUsage().heapUsed;
+
+        for (let i = 0; i < N; i++) {
+          roots.push(LargeRoot.createReadOnly(snapshot));
+        }
+
+        if ((globalThis as any).gc) (globalThis as any).gc();
+        const after = process.memoryUsage().heapUsed;
+
+        const jsonPath = `./bench-LargeRoot-${key}.json`;
+        fs.writeFileSync(
+          jsonPath,
+          JSON.stringify({ N, before, after, delta: after - before }, null, 2),
+          "utf8"
+        );
+        console.log(`Wrote ${jsonPath}`);
+
+        try {
+          const { session, post } = newInspectorSession();
+          const chunks: string[] = [];
+          session.on("HeapProfiler.addHeapSnapshotChunk", (m: any) => chunks.push(m.params.chunk));
+          post("HeapProfiler.enable")
+            .then(() => post("HeapProfiler.takeHeapSnapshot", { reportProgress: false }))
+            .then(() => {
+              const hsPath = `./bench-LargeRoot-${key}.heapsnapshot`;
+              fs.writeFileSync(hsPath, chunks.join(""), "utf8");
+              console.log(`Wrote ${hsPath}`);
+            })
+            .finally(() => {
+              void post("HeapProfiler.disable").catch(() => {});
+            })
+            .catch((e: any) => {
+              console.error("Heap snapshot error", e?.message || e);
+            });
+        } catch (e: any) {
+          console.error("Inspector session error", e?.message || e);
+        }
+      } catch (e: any) {
+        console.error("Memory benchmark task error", e?.message || e);
+      }
+    });
+
+    return suite;
+  },
+  { iterations: 1, warmupIterations: 0, warmupTime: 0, time: 0 }
+);

src/api.ts

@@ -27,7 +27,7 @@ import {
 } from "mobx-state-tree";
 import type { FlowReturn } from "mobx-state-tree/dist/internal";
 import { CantRunActionError } from "./errors";
-import { $context, $parent, $quickType, $readOnly, $type } from "./symbols";
+import { $context, $parent, $quickType, $readOnly, $type, $identifier } from "./symbols";
 import type {
   CreateTypes,
   IAnyComplexType,
@@ -236,7 +236,57 @@ export function resolveIdentifier<T extends IAnyModelType>(
   if (!context) {
     throw new Error("can't resolve references in a readonly tree with no context");
   }
-  return context.referenceCache.get(identifier) as Instance<T> | undefined;
+  const cache = (context as any).referenceCache;
+  if (cache && typeof cache.get === "function") {
+    return cache.get(identifier) as Instance<T> | undefined;
+  }
+  const root: any = getRoot<IAnyType>(target);
+  const visited = new Set<any>();
+  const isTargetType = (node: any): boolean => {
+    try {
+      return (isType(type) ? type : (type as any)).is(node);
+    } catch {
+      return false;
+    }
+  };
+  const stack: any[] = [root];
+  while (stack.length) {
+    const node = stack.pop();
+    if (!node || typeof node !== "object" || visited.has(node)) continue;
+    visited.add(node);
+    if ($readOnly in node) {
+      const id = node[$identifier];
+      if (id === identifier && isTargetType(node)) {
+        return node as Instance<T>;
+      }
+      for (const key of Object.keys(node)) {
+        const val = node[key];
+        if (val && typeof val === "object") {
+          stack.push(val);
+        }
+      }
+      if (Array.isArray(node)) {
+        for (const val of node) stack.push(val);
+      }
+      if (node instanceof Map) {
+        for (const val of node.values()) stack.push(val);
+      }
+    } else {
+      for (const key of Object.keys(node)) {
+        const val = node[key];
+        if (val && typeof val === "object") {
+          stack.push(val);
+        }
+      }
+      if (Array.isArray(node)) {
+        for (const val of node) stack.push(val);
+      }
+      if (node instanceof Map) {
+        for (const val of node.values()) stack.push(val);
+      }
+    }
+  }
+  return undefined as Instance<T> | undefined;
 }
 
 export const applySnapshot = <T extends IAnyType>(target: IStateTreeNode<T>, snapshot: SnapshotIn<T>): void => {

src/fast-instantiator.ts

@@ -114,6 +114,12 @@ export class InstantiatorBuilder<T extends IClassModelType<Record<string, IAnyTy
           }
 
           context.referencesToResolve = null; // cleanup the list of references to resolve, no need to retain them past construction
+          if (!(process && process.env && process.env.MQT_KEEP_REF_CACHE)) {
+            if (context.referenceCache && typeof context.referenceCache.clear === "function") {
+              context.referenceCache.clear();
+            }
+            context.referenceCache = null;
+          }
 
           return instance;
         };

src/reference.ts

@@ -32,10 +32,11 @@ export class ReferenceType<TargetType extends IAnyComplexType> extends BaseType<
   }
 
   instantiate(snapshot: this["InputType"] | undefined, context: TreeContext, _parent: IStateTreeNode | null): this["InstanceType"] {
-    if (!snapshot || !context.referenceCache.has(snapshot)) {
+    const cache = context.referenceCache;
+    if (!snapshot || !cache || !cache.has(snapshot)) {
       throw new Error(`can't resolve reference ${snapshot}`);
     }
-    return context.referenceCache.get(snapshot);
+    return cache.get(snapshot);
   }
 
   is(value: any): value is this["InstanceType"];
@@ -61,10 +62,11 @@ export class SafeReferenceType<TargetType extends IAnyComplexType> extends BaseT
   }
 
   instantiate(snapshot: string | undefined, context: TreeContext, _parent: IStateTreeNode | null): this["InstanceType"] {
-    if (!snapshot || !context.referenceCache.has(snapshot)) {
+    const cache = context.referenceCache;
+    if (!snapshot || !cache || !cache.has(snapshot)) {
       return undefined as this["InstanceType"];
     }
-    return context.referenceCache.get(snapshot);
+    return cache.get(snapshot);
   }
 
   is(value: any): value is this["InstanceType"];