@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/lib/index.cjs +2377 -849
  2. package/lib/index.js +2354 -846
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +5 -1
  5. package/lib/src/agent/AgentClient.js +48 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/index.d.ts +0 -1
  8. package/lib/src/index.js +0 -1
  9. package/lib/src/language/Language.d.ts +26 -176
  10. package/lib/src/language/Language.js +28 -2
  11. package/lib/src/model/Ad4mModel.d.ts +52 -28
  12. package/lib/src/model/Ad4mModel.js +255 -118
  13. package/lib/src/model/Ad4mModel.test.js +1727 -537
  14. package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
  15. package/lib/src/model/ModelQueryBuilder.js +208 -79
  16. package/lib/src/model/Subject.js +6 -6
  17. package/lib/src/model/decorators.d.ts +14 -8
  18. package/lib/src/model/decorators.js +41 -14
  19. package/lib/src/model/hydration-batch.d.ts +34 -0
  20. package/lib/src/model/hydration-batch.js +147 -0
  21. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  22. package/lib/src/model/hydration-batching.test.js +456 -0
  23. package/lib/src/model/hydration.d.ts +4 -3
  24. package/lib/src/model/hydration.js +365 -86
  25. package/lib/src/model/index.d.ts +4 -1
  26. package/lib/src/model/index.js +4 -1
  27. package/lib/src/model/json-schema.js +2 -2
  28. package/lib/src/model/query-cache.d.ts +30 -0
  29. package/lib/src/model/query-cache.js +66 -0
  30. package/lib/src/model/query-cache.test.d.ts +1 -0
  31. package/lib/src/model/query-cache.test.js +43 -0
  32. package/lib/src/model/query-common.d.ts +1 -1
  33. package/lib/src/model/query-common.js +1 -1
  34. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  35. package/lib/src/model/query-sparql-batch.js +260 -0
  36. package/lib/src/model/query-sparql.d.ts +124 -0
  37. package/lib/src/model/query-sparql.js +767 -0
  38. package/lib/src/model/query-sparql.test.d.ts +1 -0
  39. package/lib/src/model/query-sparql.test.js +495 -0
  40. package/lib/src/model/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
  41. package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
  42. package/lib/src/model/relation-filtering.test.js +15 -15
  43. package/lib/src/model/sdna.js +1 -1
  44. package/lib/src/model/shacl-gen.js +42 -18
  45. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  46. package/lib/src/model/subscription-delta.test.js +180 -0
  47. package/lib/src/model/subscription-pool.d.ts +39 -0
  48. package/lib/src/model/subscription-pool.js +165 -0
  49. package/lib/src/model/types.d.ts +52 -4
  50. package/lib/src/model/types.js +1 -1
  51. package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
  52. package/lib/src/perspectives/PerspectiveClient.js +42 -66
  53. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  54. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  55. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -30
  56. package/lib/src/perspectives/PerspectiveProxy.js +239 -177
  57. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  58. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  59. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  60. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  61. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  62. package/lib/src/runtime/RuntimeResolver.js +56 -0
  63. package/lib/src/schema.gql +11 -1
  64. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  65. package/lib/src/shacl/SHACLFlow.js +9 -9
  66. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  67. package/lib/src/shacl/SHACLShape.js +38 -38
  68. package/lib/src/typeDefs.js +11 -1
  69. package/lib/src/utils.d.ts +6 -6
  70. package/lib/src/utils.js +6 -6
  71. package/package.json +1 -1
  72. package/src/Ad4mClient.test.ts +56 -1
  73. package/src/Literal.test.ts +10 -5
  74. package/src/Literal.ts +6 -5
  75. package/src/agent/AgentClient.ts +53 -1
  76. package/src/expression/ExpressionRef.ts +2 -2
  77. package/src/index.ts +0 -1
  78. package/src/language/Language.ts +55 -231
  79. package/src/model/Ad4mModel.test.ts +1709 -572
  80. package/src/model/Ad4mModel.ts +274 -120
  81. package/src/model/ModelQueryBuilder.ts +234 -87
  82. package/src/model/Subject.ts +6 -6
  83. package/src/model/decorators.ts +51 -22
  84. package/src/model/hydration-batch.ts +205 -0
  85. package/src/model/hydration-batching.test.ts +563 -0
  86. package/src/model/hydration.ts +349 -84
  87. package/src/model/index.ts +4 -1
  88. package/src/model/json-schema.ts +2 -2
  89. package/src/model/query-cache.test.ts +54 -0
  90. package/src/model/query-cache.ts +79 -0
  91. package/src/model/query-common.ts +1 -1
  92. package/src/model/query-sparql-batch.ts +301 -0
  93. package/src/model/query-sparql.test.ts +568 -0
  94. package/src/model/query-sparql.ts +820 -0
  95. package/src/model/{surreal-utils.ts → query-utils.ts} +44 -27
  96. package/src/model/relation-filtering.test.ts +15 -15
  97. package/src/model/sdna.ts +1 -1
  98. package/src/model/shacl-gen.ts +42 -17
  99. package/src/model/subscription-delta.test.ts +207 -0
  100. package/src/model/subscription-pool.ts +211 -0
  101. package/src/model/types.ts +53 -4
  102. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  103. package/src/perspectives/PerspectiveClient.ts +41 -68
  104. package/src/perspectives/PerspectiveProxy.ts +244 -181
  105. package/src/perspectives/PerspectiveResolver.ts +0 -8
  106. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  107. package/src/runtime/RuntimeResolver.ts +43 -0
  108. package/src/shacl/SHACLFlow.ts +9 -9
  109. package/src/shacl/SHACLShape.ts +39 -39
  110. package/src/utils.ts +6 -6
  111. package/lib/src/model/query-surreal.d.ts +0 -44
  112. package/lib/src/model/query-surreal.js +0 -249
  113. package/src/language/LanguageContext.ts +0 -37
  114. package/src/model/query-surreal.ts +0 -280
  115. package/tsconfig-browser.json +0 -82
@@ -2,7 +2,7 @@ import { capitalize } from "./util";
2
2
  import type { Where } from "./types";
3
3
  import { buildSDNA } from "./sdna";
4
4
  import { buildSHACL } from "./shacl-gen";
5
- import { escapeSurrealString } from "../utils";
5
+ import { escapeQueryString } from "../utils";
6
6
  import type { ConformanceCondition } from "../shacl/SHACLShape";
7
7
 
8
8
  // ============================================================================
@@ -32,7 +32,7 @@ export interface RelationMetadataEntry {
32
32
  maxCount?: number;
33
33
  local?: boolean;
34
34
  /**
35
- * Custom SurrealQL getter to resolve the relation values.
35
+ * Custom getter to resolve the relation values.
36
36
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
37
37
  */
38
38
  getter?: string;
@@ -56,12 +56,24 @@ const propertyRegistry = new WeakMap<Function, Record<string, PropertyMetadataEn
56
56
  /** Registry of relation metadata keyed by constructor → { propName → metadata } */
57
57
  const relationRegistry = new WeakMap<Function, Record<string, RelationMetadataEntry>>();
58
58
 
59
+ /** Memoisation cache for getPropertiesMetadata — avoids repeated prototype-chain walks */
60
+ const propertiesMetadataCache = new WeakMap<Function, Record<string, PropertyMetadataEntry>>();
61
+
62
+ /** Memoisation cache for getRelationsMetadata — avoids repeated prototype-chain walks */
63
+ const relationsMetadataCache = new WeakMap<Function, Record<string, RelationMetadataEntry>>();
64
+
65
+ /** Memoisation cache for generateSHACL — avoids recomputing SHACL shapes */
66
+ const shaclCache = new WeakMap<Function, any>();
59
67
 
60
68
  /**
61
69
  * Retrieve property metadata for a given class constructor.
62
70
  * Walks the prototype chain so subclass decorators compose with parent decorators.
71
+ * Results are memoised per class constructor.
63
72
  */
64
73
  export function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry> {
74
+ const cached = propertiesMetadataCache.get(ctor);
75
+ if (cached) return cached;
76
+
65
77
  const result: Record<string, PropertyMetadataEntry> = {};
66
78
  const chain: Function[] = [];
67
79
  let current = ctor;
@@ -73,14 +85,19 @@ export function getPropertiesMetadata(ctor: Function): Record<string, PropertyMe
73
85
  const meta = propertyRegistry.get(c);
74
86
  if (meta) Object.assign(result, meta);
75
87
  }
88
+ propertiesMetadataCache.set(ctor, result);
76
89
  return result;
77
90
  }
78
91
 
79
92
  /**
80
93
  * Retrieve relation metadata for a given class constructor.
81
94
  * Walks the prototype chain so subclass decorators compose with parent decorators.
95
+ * Results are memoised per class constructor.
82
96
  */
83
97
  export function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry> {
98
+ const cached = relationsMetadataCache.get(ctor);
99
+ if (cached) return cached;
100
+
84
101
  const result: Record<string, RelationMetadataEntry> = {};
85
102
  const chain: Function[] = [];
86
103
  let current = ctor;
@@ -92,6 +109,18 @@ export function getRelationsMetadata(ctor: Function): Record<string, RelationMet
92
109
  const meta = relationRegistry.get(c);
93
110
  if (meta) Object.assign(result, meta);
94
111
  }
112
+ relationsMetadataCache.set(ctor, result);
113
+ return result;
114
+ }
115
+
116
+ /**
117
+ * Get or compute memoised SHACL for a class. Used by @Model decorator.
118
+ */
119
+ export function getMemoizedSHACL(target: Function, compute: () => any): any {
120
+ const cached = shaclCache.get(target);
121
+ if (cached) return cached;
122
+ const result = compute();
123
+ shaclCache.set(target, result);
95
124
  return result;
96
125
  }
97
126
 
@@ -137,7 +166,7 @@ export interface Ad4mModelLike {
137
166
  *
138
167
  * Inspects the target class's property metadata to derive:
139
168
  * - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
140
- * - `getter`: Pre-computed SurrealQL expression that traverses outgoing links and filters
169
+ * - `getter`: Pre-computed graph traversal expression that traverses outgoing links and filters
141
170
  * target nodes to only those conforming to the target shape.
142
171
  *
143
172
  * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
@@ -151,7 +180,8 @@ export function buildConformanceFilter(
151
180
  try {
152
181
  const targetProps = getPropertiesMetadata(targetClass);
153
182
  const conditions: ConformanceCondition[] = [];
154
- const surrealConditions: string[] = [];
183
+ const sparqlConditions: string[] = [];
184
+ let varIdx = 0;
155
185
 
156
186
  // 1. Flags — check predicate + value
157
187
  for (const [_propName, propMeta] of Object.entries(targetProps)) {
@@ -161,8 +191,8 @@ export function buildConformanceFilter(
161
191
  predicate: propMeta.through,
162
192
  value: propMeta.initial,
163
193
  });
164
- surrealConditions.push(
165
- `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.through)}' AND out.uri = '${escapeSurrealString(propMeta.initial)}']) > 0`
194
+ sparqlConditions.push(
195
+ `?target <${escapeQueryString(propMeta.through)}> <${escapeQueryString(propMeta.initial)}> .`
166
196
  );
167
197
  }
168
198
  }
@@ -175,8 +205,8 @@ export function buildConformanceFilter(
175
205
  type: 'required',
176
206
  predicate: propMeta.through,
177
207
  });
178
- surrealConditions.push(
179
- `count(->link[WHERE predicate = '${escapeSurrealString(propMeta.through)}']) > 0`
208
+ sparqlConditions.push(
209
+ `?target <${escapeQueryString(propMeta.through)}> ?_v${varIdx++} .`
180
210
  );
181
211
  }
182
212
  }
@@ -185,8 +215,7 @@ export function buildConformanceFilter(
185
215
  return undefined;
186
216
  }
187
217
 
188
- const escapedPredicate = escapeSurrealString(relationPredicate);
189
- const getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${surrealConditions.join(' AND ')}].uri)`;
218
+ const getter = `SELECT ?target WHERE { <Base> <${escapeQueryString(relationPredicate)}> ?target . ${sparqlConditions.join(' ')} }`;
190
219
 
191
220
  return { getter, conformanceConditions: conditions };
192
221
  } catch (e) {
@@ -233,9 +262,9 @@ export interface PropertyOptions {
233
262
  prologSetter?: string;
234
263
 
235
264
  /**
236
- * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
265
+ * Custom getter to resolve the property value. Use this for custom graph traversals.
237
266
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
238
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)[0]"
267
+ * Example: "SELECT ?target WHERE { <Base> <flux://has_reply> ?target . } LIMIT 1"
239
268
  */
240
269
  getter?: string;
241
270
 
@@ -268,8 +297,8 @@ function applyPropertyMetadata(opts: PropertyOptions) {
268
297
  throw new Error("SubjectProperty requires an 'initial' option if 'required' is true");
269
298
  }
270
299
 
271
- if (!opts.through && !opts.prologGetter) {
272
- throw new Error("SubjectProperty requires either 'through' or 'prologGetter' option")
300
+ if (!opts.through && !opts.prologGetter && !opts.getter) {
301
+ throw new Error("SubjectProperty requires either 'through' or 'prologGetter' or 'getter' option")
273
302
  }
274
303
 
275
304
  // Write to WeakMap registry (keyed by constructor)
@@ -492,13 +521,13 @@ export function Model(opts: ModelConfig) {
492
521
  }
493
522
 
494
523
  target.generateSHACL = function() {
495
- return buildSHACL(
524
+ return getMemoizedSHACL(target, () => buildSHACL(
496
525
  opts.name,
497
526
  target,
498
527
  getPropertiesMetadata(target),
499
528
  getRelationsMetadata(target),
500
529
  buildConformanceFilter,
501
- );
530
+ ));
502
531
  }
503
532
 
504
533
  Object.defineProperty(target, 'type', {configurable: true});
@@ -523,7 +552,7 @@ export function Model(opts: ModelConfig) {
523
552
  * Properties are optional by default. When a model instance is created without
524
553
  * providing a value for an optional property, no link is added to the graph.
525
554
  * Set `required: true` explicitly when a property must always be present (this
526
- * also adds a `"literal://string:uninitialized"` sentinel as the initial value
555
+ * also adds a `"literal:string:uninitialized"` sentinel as the initial value
527
556
  * so that the SDNA constructor creates a placeholder link).
528
557
  *
529
558
  * @example
@@ -562,7 +591,7 @@ export function Model(opts: ModelConfig) {
562
591
  * @param {PropertyOptions} opts - Property configuration
563
592
  * @param {string} opts.through - The predicate URI for the property
564
593
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
565
- * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized" when required)
594
+ * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
566
595
  * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
567
596
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
568
597
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
@@ -575,7 +604,7 @@ export function Property(opts: PropertyOptions) {
575
604
  required,
576
605
  readOnly: opts.readOnly ?? false,
577
606
  resolveLanguage: opts.resolveLanguage ?? "literal",
578
- initial: opts.initial ?? (required ? "literal://string:uninitialized" : undefined),
607
+ initial: opts.initial ?? (required ? "literal:string:uninitialized" : undefined),
579
608
  });
580
609
  }
581
610
 
@@ -659,9 +688,9 @@ export interface RelationOptions {
659
688
  * Cannot be combined with `getter`. */
660
689
  target?: () => Ad4mModelLike;
661
690
  /**
662
- * Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
691
+ * Custom getter to resolve the relation values. Use this for custom graph traversals.
663
692
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
664
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
693
+ * Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
665
694
  *
666
695
  * Mutually exclusive with `through` and `target`. When `getter` is provided the
667
696
  * relation is read-only (no adder/remover actions are generated).
@@ -750,7 +779,7 @@ function resolveRelationArgs(
750
779
  if (opts.where) {
751
780
  throw new Error(
752
781
  'Relation decorator: `where` and `getter` are mutually exclusive. ' +
753
- 'Use `where` for DSL-based filtering, or `getter` for raw SurrealQL.'
782
+ 'Use `where` for DSL-based filtering, or `getter` for raw getter expression.'
754
783
  );
755
784
  }
756
785
  return opts;
@@ -0,0 +1,205 @@
1
+ /**
2
+ * Batch hydration for SPARQL batch query results.
3
+ *
4
+ * Takes the flat rows returned by `buildBatchSPARQLQuery()` (each tagged
5
+ * with ?depth, ?parentBase, ?relationName) and reconstructs a tree of
6
+ * model instances.
7
+ *
8
+ * @module
9
+ */
10
+
11
+ import { hydrateFromLinks, evaluateCustomGettersForInstance } from "./hydration";
12
+ import { getRelationsMetadata } from "./decorators";
13
+ import type { IncludeMap, ModelMetadata } from "./types";
14
+
15
+ /**
16
+ * A row returned by the batch SPARQL query.
17
+ */
18
+ interface BatchRow {
19
+ depth: string;
20
+ parentBase: string;
21
+ relationName: string;
22
+ source: string;
23
+ predicate: string;
24
+ target: string;
25
+ author: string;
26
+ timestamp: string;
27
+ }
28
+
29
+ /**
30
+ * Grouped link data for one instance (same shape as SPARQL grouped result).
31
+ */
32
+ interface GroupedInstance {
33
+ source_uri: string;
34
+ parentBase: string;
35
+ relationName: string;
36
+ links: Array<{ predicate: string; target: string; author: string; timestamp: string }>;
37
+ }
38
+
39
+ /**
40
+ * Group batch rows by (depth, source) → array of links, preserving parentBase/relationName.
41
+ */
42
+ function groupBatchRows(rows: BatchRow[]): Map<number, GroupedInstance[]> {
43
+ const byDepth = new Map<number, Map<string, GroupedInstance>>();
44
+
45
+ for (const row of rows) {
46
+ const depth = parseInt(row.depth, 10);
47
+ if (!byDepth.has(depth)) byDepth.set(depth, new Map());
48
+ const depthMap = byDepth.get(depth)!;
49
+
50
+ const key = row.source;
51
+ if (!depthMap.has(key)) {
52
+ depthMap.set(key, {
53
+ source_uri: key,
54
+ parentBase: row.parentBase,
55
+ relationName: row.relationName,
56
+ links: [],
57
+ });
58
+ }
59
+ depthMap.get(key)!.links.push({
60
+ predicate: row.predicate,
61
+ target: row.target,
62
+ author: row.author,
63
+ timestamp: row.timestamp,
64
+ });
65
+ }
66
+
67
+ const result = new Map<number, GroupedInstance[]>();
68
+ for (const [depth, map] of byDepth) {
69
+ result.set(depth, Array.from(map.values()));
70
+ }
71
+ return result;
72
+ }
73
+
74
+ /**
75
+ * Hydrate batch SPARQL results into a tree of model instances.
76
+ *
77
+ * @param rows - Flat rows from the batch SPARQL query
78
+ * @param rootClass - The root model class (extends Ad4mModel)
79
+ * @param includeMap - The include specification from the query
80
+ * @param perspective - The PerspectiveProxy for creating instances
81
+ * @returns Array of hydrated root instances with relations populated
82
+ */
83
+ export async function hydrateBatchResult<T>(
84
+ rows: BatchRow[],
85
+ rootClass: any,
86
+ includeMap: IncludeMap,
87
+ perspective: any,
88
+ ): Promise<T[]> {
89
+ if (!rows || rows.length === 0) return [];
90
+
91
+ const grouped = groupBatchRows(rows);
92
+
93
+ // Hydrate root instances (depth 0)
94
+ const rootInstances = grouped.get(0) || [];
95
+ const metadata: ModelMetadata = rootClass.getModelMetadata();
96
+ const instances: T[] = [];
97
+ const instanceMap = new Map<string, T>();
98
+
99
+ for (const group of rootInstances) {
100
+ const instance = new rootClass(perspective, group.source_uri) as any;
101
+ await hydrateFromLinks(instance, group.links, metadata, perspective);
102
+ await evaluateCustomGettersForInstance(instance, perspective, metadata);
103
+ instances.push(instance);
104
+ instanceMap.set(group.source_uri, instance);
105
+ }
106
+
107
+ // Hydrate each depth level and wire to parents
108
+ const relMeta = getRelationsMetadata(rootClass);
109
+ const maxDepth = Math.max(...Array.from(grouped.keys()), 0);
110
+
111
+ // Build a map of depth → (class, relMetadata, parentInstanceMap)
112
+ // For depth 1, parents are root instances; for deeper depths, we need
113
+ // the instances from the previous level.
114
+ const depthInstanceMaps = new Map<number, Map<string, any>>();
115
+ depthInstanceMaps.set(0, instanceMap);
116
+
117
+ // Build depth→class mapping from include tree
118
+ const depthClassMap = new Map<number, { targetClass: any; includeMap?: IncludeMap }>();
119
+ buildDepthClassMap(rootClass, includeMap, 0, { value: 1 }, depthClassMap);
120
+
121
+ for (let depth = 1; depth <= maxDepth; depth++) {
122
+ const depthGroups = grouped.get(depth) || [];
123
+ if (depthGroups.length === 0) continue;
124
+
125
+ const depthInfo = depthClassMap.get(depth);
126
+ if (!depthInfo) continue;
127
+
128
+ const TargetClass = depthInfo.targetClass;
129
+ const targetMetadata: ModelMetadata = TargetClass.getModelMetadata
130
+ ? TargetClass.getModelMetadata()
131
+ : { className: "Unknown", properties: {}, relations: {} };
132
+
133
+ const currentDepthInstances = new Map<string, any>();
134
+
135
+ // Group by parentBase to wire children to parents
136
+ for (const group of depthGroups) {
137
+ const instance = new TargetClass(perspective, group.source_uri) as any;
138
+ await hydrateFromLinks(instance, group.links, targetMetadata, perspective);
139
+ await evaluateCustomGettersForInstance(instance, perspective, targetMetadata);
140
+ currentDepthInstances.set(group.source_uri, instance);
141
+
142
+ // Wire to parent
143
+ // Find the parent depth's instance map
144
+ // The parentBase should exist in one of the prior depth maps
145
+ for (let pd = depth - 1; pd >= 0; pd--) {
146
+ const parentMap = depthInstanceMaps.get(pd);
147
+ if (parentMap && parentMap.has(group.parentBase)) {
148
+ const parent = parentMap.get(group.parentBase)!;
149
+ const relName = group.relationName;
150
+
151
+ // Determine relation metadata to know if it's an array or single
152
+ const parentRelMeta = getRelationsMetadata(pd === 0 ? rootClass : (depthClassMap.get(pd)?.targetClass || rootClass));
153
+ const rel = parentRelMeta[relName];
154
+
155
+ if (rel) {
156
+ if (rel.kind === 'hasMany' || rel.kind === 'belongsToMany') {
157
+ if (!Array.isArray(parent[relName])) {
158
+ parent[relName] = [];
159
+ }
160
+ parent[relName].push(instance);
161
+ } else {
162
+ parent[relName] = instance;
163
+ }
164
+ }
165
+ break;
166
+ }
167
+ }
168
+ }
169
+
170
+ depthInstanceMaps.set(depth, currentDepthInstances);
171
+ }
172
+
173
+ return instances;
174
+ }
175
+
176
+ /**
177
+ * Build a mapping from depth number to target class info.
178
+ */
179
+ function buildDepthClassMap(
180
+ parentClass: any,
181
+ includeMap: IncludeMap,
182
+ _parentDepth: number,
183
+ nextDepth: { value: number },
184
+ result: Map<number, { targetClass: any; includeMap?: IncludeMap }>,
185
+ ): void {
186
+ const relMeta = getRelationsMetadata(parentClass);
187
+
188
+ for (const [relName, includeValue] of Object.entries(includeMap)) {
189
+ const meta = relMeta[relName];
190
+ if (!meta || !meta.target) continue;
191
+
192
+ const TargetClass = meta.target();
193
+ const depth = nextDepth.value++;
194
+
195
+ const nestedInclude = typeof includeValue === 'object' && includeValue !== null
196
+ ? (includeValue as any).include
197
+ : undefined;
198
+
199
+ result.set(depth, { targetClass: TargetClass, includeMap: nestedInclude });
200
+
201
+ if (nestedInclude) {
202
+ buildDepthClassMap(TargetClass, nestedInclude, depth, nextDepth, result);
203
+ }
204
+ }
205
+ }