Lazy relationship resolution for large bidirectional entity graphs

[jayseo5953]

Per @ntucker's suggestion in #3822, moving the lazy resolution discussion here.

Problem

With large bidirectional entity graphs (~20k entities, 4 types all referencing each other), eager denormalization traverses the entire graph. The depth limit from PR #3823 helps but:

• At 128: stack overflow is prevented but Chrome runs out of memory (Aw Snap, error code 5)
• At lower values (e.g. 32): fixes the crash but is a blunt instrument — it cuts off all deep paths including legitimate non-cyclic ones (e.g. a 40-level org hierarchy via parent/children)

Dataset and schema for reference: https://github.com/jayseo5953/dataclient-repro-3822

Lazy proposal from #3822

@ntucker proposed a lazy() schema wrapper + useQuery() for explicit resolution:

class Department extends Entity {
  static schema = {
    buildings: lazy([Building]), // stays as raw IDs during denormalization
  };
}

const dept = useSuspense(DepartmentResource.get, { id: '1' });
// dept.buildings = ['bldg-1', 'bldg-2']

const buildings = useQuery([Building], { id: dept.id });
// buildings: Building[]

The LazySchema implementation is minimal — denormalize is a no-op, normalize delegates to the inner schema.

Concern with this approach

The lazy() marker lives on the entity class, making it a global decision. A relationship marked lazy returns raw IDs everywhere — every component that previously did dept.buildings[0].name now gets a string instead of an Entity. This means:

• Consumers have to know which relationships are lazy and which are eager
• dept.buildings[0].name and dept.parent.name have different access patterns despite both being relationships
• Every access point for a lazy relationship needs a useQuery call added
• The performance concern (denormalization depth) leaks into the domain model and consumer API

Our motivation was to keep the API invisible and consistent — dept.buildings[0].name should always return a resolved Entity, regardless of whether it was resolved eagerly or lazily. The consumer shouldn't need to know or care about the resolution strategy.

Our approach: transparent lazy resolution via Entity.denormalize override

We overrode Entity.denormalize() in our base class to defer relationship resolution using ES5 getters. From the consumer's perspective, nothing changes — dept.buildings[0].name still works, but the resolution happens on first property access instead of during the denormalization pass:

function isEntityRelationship(schema: unknown): boolean {
  if (schema === null || schema === undefined) return false;
  if (typeof schema === 'function' && (schema as any).key) return true;
  if (Array.isArray(schema) && schema.length === 1
      && typeof schema[0] === 'function' && schema[0].key) return true;
  if (typeof schema === 'object' && !Array.isArray(schema)
      && (schema as any).schema) return true;
  return false;
}

class ApplicationEntity extends Entity {
  static denormalize(
    input: Record<string, unknown>,
    args: readonly unknown[],
    unvisit: (schema: unknown, value: unknown) => unknown,
  ): Record<string, unknown> {
    if (typeof input === 'symbol') return input;

    for (const key of Object.keys(this.schema)) {
      const schema = (this.schema as Record<string, unknown>)[key];

      // Transform functions (dates, enums) — run eagerly as before
      if (!isEntityRelationship(schema)) {
        const value = unvisit(schema, input[key]);
        input[key] = typeof value === 'symbol' ? undefined : value;
        continue;
      }

      // Entity relationships — defer resolution to first access
      const rawValue = input[key];
      Object.defineProperty(input, key, {
        get() {
          const resolved = unvisit(schema, rawValue);
          // Self-replacing getter — resolves once, then becomes a plain property
          Object.defineProperty(this, key, {
            value: typeof resolved === 'symbol' ? undefined : resolved,
            writable: true,
            configurable: true,
            enumerable: true,
          });
          return this[key];
        },
        set(value: unknown) {
          Object.defineProperty(this, key, {
            value,
            writable: true,
            configurable: true,
            enumerable: true,
          });
        },
        configurable: true,
        enumerable: true,
      });
    }
    return input;
  }
}

Results

• Crash eliminated — with ~20k bidirectional entities, only ~18% of relationships were actually resolved (the ones the UI accessed)
• Consistent API — dept.buildings[0].name works exactly as before, no consumer changes needed
• Full Entity instances — resolved values are the same Entity class instances, not POJOs

The problem: broken reactivity

unvisit has a dual role — it resolves entities AND registers dependencies for cache invalidation. The dependency list is finalized immediately after denormalize() returns:

MemoCache.denormalize() → getUnvisit() → unvisit():
  Entity.denormalize():
    define getter for buildings  ← NO unvisit call, NO dependency registered
  dependencies = [Department#1]  ← INCOMPLETE, missing Building#1, Building#2
  globalCache.set(dependencies, result)

Later (React render): dept.buildings → getter fires → unvisit(Building#1)
  → resolves correctly, but dependency list is already finalized

Later: Building#1 changes → NOT in dependency list → Department NOT invalidated → stale UI

The dependency collection and entity resolution are coupled by design — both happen during the same unvisit traversal. Our getter approach decoupled entity resolution (deferred) but inadvertently skipped dependency registration.

The gap

Approach	Consumer API	Crash fix	Reactivity	Consumer changes
Depth limit (32)	dept.buildings[0].name	✅ (blunt cutoff)	✅	None
lazy() + useQuery()	useQuery([Building], dept.buildings)	✅ (precise)	✅	Every lazy access point
Our getter override	dept.buildings[0].name	✅	❌ broken	None

The ideal solution would combine the transparency of our approach (no consumer changes, consistent API) with correct reactivity. This would require decoupling dependency registration from entity resolution — registering dependencies eagerly during the denormalization pass (shallow walk of schema fields to record referenced PKs) while deferring actual Entity construction to property access:

// During denormalization pass:
for (const [key, fieldSchema] of Object.entries(schema)) {
  if (isEntityRelationship(fieldSchema)) {
    registerDependencies(cache, fieldSchema, input[key]); // shallow — just record PKs
    defineGetter(input, key, () => unvisit(fieldSchema, input[key])); // defer resolution
  }
}

This would keep the dependency list complete (reactivity works) while avoiding the deep recursive Entity construction that causes the crash.

[ntucker]

In ReactJS, rendering is controlled by hooks, not opaque reactive props. If you disagree with this philosophy, you can use vue. However, in my experience this leads to at best degenerate performance problems and at worse common app freezes, bug whack a mole, state jank, and timing problems.

If a react component has no hooks, then it only renders if its parent renders.

So that means that by tying this super large structure together, you are then forcing any changes from these descendants to trigger renders of their entire ancestry, forcing your whole component tree to run when any little thing changes. This is the 'broken' part, because without wiring that together, it will not re-render the entire tree. At that point, you might as well just enable reactivity by force rendering the whole react tree - rather than thinking about using reactivity mechanisms. It will have the same performance for component, but you loose the complexity and performance overhead of tracking reactivity.

So yeah, you definitely want to be explicit about where you bind re-renders too.

The only value I see in this is if for whatever reason you have a huge initial payload with everything at once to normalize. This is why I bothered with #3829.

The only case you'll actually want true nested items is when they actually impact that top level render. The simplest example here is when you're sorting based on a nested entity in a top level table. In that case, mutating that entity does require re-rendering that top level table, so you definitely want those to be coupled. Other aggregates like groupby etc will all follow this pattern.

In conclusion, the most performant and scalable way to build apps is by only denormalizing when you actually want to re-render that top level object. Otherwise, by making it disjoint, then only components that actually need to re-render will actually have to run when there is a mutation.

[ntucker]

Recommended: Use Lazy + useQuery()

The recommended approach remains Lazy for relationship fields in bidirectional graphs. Eagerly denormalizing deep/wide entity graphs couples re-renders across the entire tree — any mutation to a nested entity forces every ancestor component to re-render, even if it doesn't display that data. Lazy keeps relationships decoupled so only the components that actually use the data re-render when it changes. This is fundamental to React's rendering model: hooks control what triggers a re-render, and binding everything together defeats that.

The getter-based transparent resolution described above has the same problem: even if you defer construction, once a component accesses dept.buildings[0].name, it's coupled to that building's data. And if it doesn't access it, the relationship didn't need to be resolved at all — which is exactly what Lazy gives you.

That said, migrating to Lazy + useQuery() across a large codebase is a significant refactor. If you need an interim solution while planning that migration, the patterns below let you control denormalization depth in user-land today, with zero library changes.

---

User-land depth control (interim, zero library changes)

These three utilities use unvisit function identity as a WeakMap key for per-call state tracking. Since unvisit is a fresh closure per denormalize() call, this gives isolated per-call counters that are GC'd automatically. None of these have pk, so isEntity() returns false — zero impact on the existing entity processing hot path.

1. DepthLimited — per-field relative depth

Controls how many levels a specific relationship field resolves. Each field gets its own independent counter.

import type { Schema } from '@data-client/endpoint';

type UnvisitFn = (schema: any, input: any) => any;

class DepthLimited<S extends Schema> {
  readonly schema: S;
  readonly maxDepth: number;
  private readonly _state = new WeakMap<UnvisitFn, { depth: number }>();

  constructor(schema: S, maxDepth: number) {
    this.schema = schema;
    this.maxDepth = maxDepth;
  }

  normalize(
    input: any, parent: any, key: any, args: any[],
    visit: (...args: any) => any, _delegate: any,
  ): any {
    return visit(this.schema, input, parent, key, args);
  }

  denormalize(input: {}, _args: readonly any[], unvisit: UnvisitFn): any {
    if (input == null || typeof input === 'symbol') return input;
    let cell = this._state.get(unvisit);
    if (!cell) { cell = { depth: 0 }; this._state.set(unvisit, cell); }
    cell.depth++;
    try {
      if (cell.depth > this.maxDepth) return input; // raw IDs, like Lazy
      return unvisit(this.schema as any, input);
    } finally { cell.depth--; }
  }

  queryKey(): undefined { return undefined; }
}

Usage — self-referential hierarchies:

class Department extends Entity {
  static schema = {
    children: new DepthLimited([Department], 3),  // 3 levels of children
    parent: new DepthLimited(Department, 1),      // 1 level of parent
  };
}

Dept A → children(depth 1) → Dept B → children(depth 2) → Dept C → children(depth 3) → Dept D → children(depth 4 > 3, return raw IDs). Always exactly 3 levels, regardless of where A sits in the overall tree.

2. CycleDetect + CycleTrackingEntity — type-based cycle detection

Stops when the same entity type appears twice in the ancestor path. No depth numbers to tune — adapts to any schema shape.

import { Entity } from '@data-client/endpoint';

type UnvisitFn = (schema: any, input: any) => any;

const _ancestors = new WeakMap<Function, Map<string, number>>();

function getAncestors(unvisit: Function): Map<string, number> {
  let m = _ancestors.get(unvisit);
  if (!m) { m = new Map(); _ancestors.set(unvisit, m); }
  return m;
}

function extractEntityKeys(schema: any, out = new Set<string>()): Set<string> {
  if (schema == null) return out;
  if (schema.pk !== undefined && schema.key) { out.add(schema.key); return out; }
  if (Array.isArray(schema) && schema.length === 1) {
    extractEntityKeys(schema[0], out); return out;
  }
  if (schema.schema !== undefined) extractEntityKeys(schema.schema, out);
  return out;
}

class CycleDetect<S> {
  readonly schema: S;
  constructor(schema: S) { this.schema = schema; }

  normalize(
    input: any, parent: any, key: any, args: any[],
    visit: (...args: any) => any, _delegate: any,
  ): any {
    return visit(this.schema as any, input, parent, key, args);
  }

  denormalize(input: {}, _args: readonly any[], unvisit: UnvisitFn): any {
    if (input == null || typeof input === 'symbol') return input;
    const path = getAncestors(unvisit);
    for (const key of extractEntityKeys(this.schema)) {
      if (path.has(key)) return input; // cycle detected — return raw IDs
    }
    return unvisit(this.schema as any, input);
  }

  queryKey(): undefined { return undefined; }
}

class CycleTrackingEntity extends Entity {
  static denormalize<T extends typeof CycleTrackingEntity>(
    this: T, input: any, args: any[],
    unvisit: (schema: any, input: any) => any,
  ): any {
    if (typeof input === 'symbol') return input;
    const path = getAncestors(unvisit);
    const k = this.key;
    const prev = path.get(k) ?? 0;
    path.set(k, prev + 1);
    try { return super.denormalize(input, args, unvisit); }
    finally {
      if (prev === 0) path.delete(k); else path.set(k, prev);
    }
  }
}

Usage — bidirectional relationships:

class Department extends CycleTrackingEntity {
  static schema = {
    buildings: new CycleDetect([Building]),  // stops Dept→Building→Dept→... cycle
  };
}

class Building extends CycleTrackingEntity {
  static schema = {
    departments: new CycleDetect([Department]),
  };
}

Dept A (ancestors: {Department:1}) → buildings → CycleDetect: Building not in ancestors → Building B (ancestors: {Department:1, Building:1}) → departments → CycleDetect: Department in ancestors → return raw IDs. Cycle stopped without depth numbers.

Combined — all three together

class Department extends CycleTrackingEntity {
  static schema = {
    buildings: new CycleDetect([Building]),       // cross-type: stop bidirectional cycle
    children: new DepthLimited([Department], 3),  // self-ref: 3 levels of children
    parent: new DepthLimited(Department, 1),      // self-ref: 1 level of parent
  };
}

class Building extends CycleTrackingEntity {
  static schema = {
    departments: new CycleDetect([Department]),
    rooms: new CycleDetect([Room]),
  };
}

How these work

• unvisit identity as key: Each denormalize() call creates a fresh unvisit closure. WeakMap<unvisit, state> gives per-call isolation; entries are GC'd when the call completes.
• No hot-path impact: These wrappers lack pk, so isEntity() returns false — they bypass the entity depth-tracking path entirely. Users who don't use them pay nothing.
• Normalization unchanged: Both wrappers delegate to visit(this.schema, ...) during normalize, identical to Lazy.
• At the limit: Returns raw normalized values (IDs/PKs). TypeScript still shows the denormalized type — same tradeoff as Lazy.

When to use what

Need	Solution
Long-term / new code	Lazy + useQuery() — best performance, correct re-render boundaries
Self-referential hierarchy (parent/children)	DepthLimited([Department], N) per field
Cross-type bidirectional (Dept ↔ Building)	CycleDetect + CycleTrackingEntity
Both on same entity	Combine as shown above