feat(normalizr): Add configurable maxEntityDepth on Entity

Allow per-Entity configuration of the denormalization depth limit via
`static maxEntityDepth`. This lets users lower the limit (default 128)
on entities that participate in deep bidirectional relationships,
without requiring any provider or controller configuration.

The depth check in `getUnvisit()` now reads `schema.maxEntityDepth`
with a fallback to the existing 128 default.

Made-with: Cursor

Author: ntucker

.changeset/fix-denorm-depth-limit.md

@@ -1,13 +1,22 @@
 ---
 '@data-client/normalizr': patch
+'@data-client/endpoint': patch
 '@data-client/core': patch
 '@data-client/react': patch
 '@data-client/vue': patch
 ---
 
 Fix stack overflow during denormalization of large bidirectional entity graphs.
 
-Add entity depth limit (128) to prevent `RangeError: Maximum call stack size exceeded`
+Add entity depth limit (64) to prevent `RangeError: Maximum call stack size exceeded`
 when denormalizing cross-type chains with thousands of unique entities
 (e.g., Department → Building → Department → ...). Entities beyond the depth limit
 are returned with unresolved ids instead of fully denormalized nested objects.
+
+The limit can be configured per-Entity with [`static maxEntityDepth`](/rest/api/Entity#maxEntityDepth):
+
+```ts
+class Department extends Entity {
+  static maxEntityDepth = 16;
+}
+```

docs/rest/api/Entity.md

@@ -418,6 +418,41 @@ Nested below:
 const price = useQuery(LatestPrice, { symbol: 'BTC' });
 ```
 
+### static maxEntityDepth?: number {#maxEntityDepth}
+
+Limits entity nesting depth during denormalization to prevent stack overflow
+in large bidirectional entity graphs. **Default: 128**
+
+When bidirectional relationships create chains with many unique entities
+(e.g., `Department → Building → Department → ...`), denormalization can recurse
+thousands of levels deep. `maxEntityDepth` truncates resolution at the specified
+depth — entities beyond the limit are returned with nested foreign keys left as
+unresolved ids rather than fully denormalized objects.
+
+```typescript
+class Department extends Entity {
+  id = '';
+  name = '';
+  buildings: Building[] = [];
+
+  pk() { return this.id; }
+  static key = 'Department';
+  // highlight-next-line
+  static maxEntityDepth = 16;
+
+  static schema = {
+    buildings: [Building],
+  };
+}
+```
+
+:::tip
+
+Set this on entities that participate in deep or wide bidirectional relationships.
+Normal entity graphs (depth < 10) never approach the default limit.
+
+:::
+
 ## Lifecycle
 
 import Lifecycle from '../diagrams/\_entity_lifecycle.mdx';

packages/endpoint/src/schemas/EntityMixin.ts

@@ -80,6 +80,13 @@ export default function EntityMixin<TBase extends Constructor>(
     /** Defines indexes to enable lookup by */
     declare static indexes?: readonly string[];
 
+    /** Maximum entity nesting depth for denormalization (default: 128)
+     *
+     * Set a lower value to truncate deep bidirectional entity graphs earlier.
+     * @see https://dataclient.io/rest/api/Entity#maxEntityDepth
+     */
+    declare static maxEntityDepth?: number;
+
     /**
      * A unique identifier for each Entity
      *

packages/endpoint/src/schemas/EntityTypes.ts

@@ -30,6 +30,12 @@ export interface IEntityClass<TBase extends Constructor = any> {
    * @see https://dataclient.io/rest/api/Entity#indexes
    */
   indexes?: readonly string[] | undefined;
+  /** Maximum entity nesting depth for denormalization (default: 128)
+   *
+   * Set a lower value to truncate deep bidirectional entity graphs earlier.
+   * @see https://dataclient.io/rest/api/Entity#maxEntityDepth
+   */
+  maxEntityDepth?: number | undefined;
   /**
    * A unique identifier for each Entity
    *

packages/endpoint/src/schemas/__tests__/Entity.test.ts

@@ -1132,6 +1132,73 @@ describe(`${Entity.name} denormalization`, () => {
       consoleSpy.mockRestore();
     });
 
+    test('maxEntityDepth on Entity lowers the limit', () => {
+      class LimitedDept extends IDEntity {
+        readonly name: string = '';
+        readonly buildings: LimitedBldg[] = [];
+        static maxEntityDepth = 10;
+      }
+      class LimitedBldg extends IDEntity {
+        readonly name: string = '';
+        readonly departments: LimitedDept[] = [];
+
+        static schema = {
+          departments: [LimitedDept],
+        };
+
+        static maxEntityDepth = 10;
+      }
+      LimitedDept.schema = {
+        buildings: new schema.Array(LimitedBldg),
+      };
+
+      const deptEntities: Record<string, any> = {};
+      const bldgEntities: Record<string, any> = {};
+      for (let i = 0; i < 50; i++) {
+        deptEntities[`dept-${i}`] = {
+          id: `dept-${i}`,
+          name: `Department ${i}`,
+          buildings: [`bldg-${i}`],
+        };
+        bldgEntities[`bldg-${i}`] = {
+          id: `bldg-${i}`,
+          name: `Building ${i}`,
+          departments: i < 49 ? [`dept-${i + 1}`] : [],
+        };
+      }
+
+      const consoleSpy = jest
+        .spyOn(console, 'error')
+        .mockImplementation(() => {});
+
+      const result = plainDenormalize(LimitedDept, 'dept-0', {
+        LimitedDept: deptEntities,
+        LimitedBldg: bldgEntities,
+      });
+
+      expect(result).not.toEqual(expect.any(Symbol));
+      if (typeof result === 'symbol') return;
+      expect(result).toBeDefined();
+      if (!result) return;
+
+      // depth 10 means 5 full hops (dept→bldg = 2 entity levels per hop)
+      // walk 4 hops safely
+      let node: any = result;
+      for (let i = 0; i < 4; i++) {
+        expect(node.buildings).toBeDefined();
+        expect(node.buildings.length).toBe(1);
+        node = node.buildings[0].departments[0];
+      }
+      expect(node).toBeInstanceOf(LimitedDept);
+
+      expect(consoleSpy).toHaveBeenCalledTimes(1);
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Entity depth limit of 10'),
+      );
+
+      consoleSpy.mockRestore();
+    });
+
     test('depth limit with MemoCache does not cache truncated results', () => {
       const entities = buildChain(1500);
       const consoleSpy = jest

packages/normalizr/src/denormalize/unvisit.ts

@@ -97,7 +97,7 @@ function noCacheGetEntity(
   return localCacheKey.get('');
 }
 
-const MAX_ENTITY_DEPTH = 128;
+const MAX_ENTITY_DEPTH = 64;
 
 const getUnvisit = (
   getEntity: DenormGetEntity,
@@ -129,14 +129,18 @@ const getUnvisit = (
       }
     } else {
       if (isEntity(schema)) {
-        if (depth >= MAX_ENTITY_DEPTH) {
+        if (depth >= (schema.maxEntityDepth ?? MAX_ENTITY_DEPTH)) {
           /* istanbul ignore if */
           if (process.env.NODE_ENV !== 'production' && !depthLimitHit) {
             depthLimitHit = true;
+            const limit = schema.maxEntityDepth ?? MAX_ENTITY_DEPTH;
             console.error(
-              `Entity depth limit of ${MAX_ENTITY_DEPTH} reached for "${schema.key}" entity. ` +
+              `Entity depth limit of ${limit} reached for "${schema.key}" entity. ` +
                 `This usually means your schema has very deep or wide bidirectional relationships. ` +
-                `Nested entities beyond this depth are returned with unresolved ids.`,
+                `Nested entities beyond this depth are returned with unresolved ids.` +
+                (schema.maxEntityDepth === undefined ?
+                  ` Set static maxEntityDepth on your Entity to configure this limit.`
+                : ''),
             );
           }
           return depthLimitEntity(getEntity, schema, input);

packages/normalizr/src/interface.ts

@@ -63,6 +63,7 @@ export interface EntityInterface<T = any> extends SchemaSimple {
   schema: Record<string, Schema>;
   prototype: T;
   cacheWith?: object;
+  maxEntityDepth?: number;
 }
 
 export interface Mergeable {