@coasys/ad4m 0.12.0-rc1-dev.4 → 0.12.0-rc2

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 (166) hide show
  1. package/lib/index.cjs +5052 -4446
  2. package/lib/index.js +5019 -4442
  3. package/lib/src/agent/AgentClient.d.ts +4 -0
  4. package/lib/src/agent/AgentClient.js +34 -0
  5. package/lib/src/index.d.ts +2 -3
  6. package/lib/src/index.js +2 -3
  7. package/lib/src/model/Ad4mModel.d.ts +8 -782
  8. package/lib/src/model/Ad4mModel.js +160 -2354
  9. package/lib/src/model/ModelQueryBuilder.d.ts +370 -0
  10. package/lib/src/model/ModelQueryBuilder.js +556 -0
  11. package/lib/src/model/decorators.d.ts +71 -23
  12. package/lib/src/model/decorators.js +133 -384
  13. package/lib/src/model/hydration.d.ts +102 -0
  14. package/lib/src/model/hydration.js +709 -0
  15. package/lib/src/model/index.d.ts +20 -0
  16. package/lib/src/model/index.js +20 -0
  17. package/lib/src/model/{schema/fromJSONSchema.d.ts → json-schema.d.ts} +45 -12
  18. package/lib/src/model/json-schema.js +326 -0
  19. package/lib/src/model/prolog-facts.d.ts +37 -0
  20. package/lib/src/model/{prolog/generatePrologFacts.js → prolog-facts.js} +47 -52
  21. package/lib/src/model/query-common.d.ts +14 -0
  22. package/lib/src/model/query-common.js +36 -0
  23. package/lib/src/model/query-prolog.d.ts +15 -0
  24. package/lib/src/model/query-prolog.js +140 -0
  25. package/lib/src/model/query-surreal.d.ts +44 -0
  26. package/lib/src/model/query-surreal.js +249 -0
  27. package/lib/src/model/relation-filtering.test.js +838 -0
  28. package/lib/src/model/sdna.d.ts +14 -0
  29. package/lib/src/model/sdna.js +141 -0
  30. package/lib/src/model/shacl-gen.d.ts +31 -0
  31. package/lib/src/model/shacl-gen.js +246 -0
  32. package/lib/src/model/surreal-utils.d.ts +42 -0
  33. package/lib/src/model/surreal-utils.js +128 -0
  34. package/lib/src/model/types.d.ts +75 -96
  35. package/lib/src/model/types.js +4 -4
  36. package/lib/src/model/util.d.ts +4 -5
  37. package/lib/src/model/util.js +12 -32
  38. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  39. package/lib/src/perspectives/PerspectiveProxy.d.ts +1 -1
  40. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +79 -0
  41. package/lib/src/perspectives/WakerSubscriptionManager.js +196 -0
  42. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  43. package/lib/src/runtime/RuntimeResolver.js +73 -0
  44. package/lib/src/schema.gql +14 -0
  45. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  46. package/lib/src/shacl/SHACLShape.js +45 -0
  47. package/lib/src/typeDefs.js +14 -0
  48. package/package.json +13 -8
  49. package/src/agent/AgentClient.ts +45 -0
  50. package/src/index.ts +2 -3
  51. package/src/model/Ad4mModel.ts +1089 -3686
  52. package/src/model/ModelQueryBuilder.ts +617 -0
  53. package/src/model/Subject.ts +1 -1
  54. package/src/model/decorators.ts +218 -453
  55. package/src/model/hydration.ts +796 -0
  56. package/src/model/index.ts +21 -0
  57. package/src/model/json-schema.ts +424 -0
  58. package/src/model/prolog-facts.ts +145 -0
  59. package/src/model/query-common.ts +48 -0
  60. package/src/model/query-prolog.ts +148 -0
  61. package/src/model/query-surreal.ts +280 -0
  62. package/src/model/relation-filtering.test.ts +803 -0
  63. package/src/model/sdna.ts +170 -0
  64. package/src/model/shacl-gen.ts +292 -0
  65. package/src/model/surreal-utils.ts +147 -0
  66. package/src/model/types.ts +182 -0
  67. package/src/model/util.ts +13 -36
  68. package/src/perspectives/PerspectiveClient.ts +1 -1
  69. package/src/perspectives/PerspectiveProxy.ts +1 -1
  70. package/src/perspectives/WakerSubscriptionManager.ts +292 -0
  71. package/src/runtime/RuntimeResolver.ts +53 -0
  72. package/src/shacl/SHACLShape.ts +83 -0
  73. package/lib/src/Ad4mClient.test.js +0 -1204
  74. package/lib/src/Literal.test.d.ts +0 -1
  75. package/lib/src/Literal.test.js +0 -41
  76. package/lib/src/model/mutation.d.ts +0 -81
  77. package/lib/src/model/mutation.js +0 -317
  78. package/lib/src/model/parentUtils.d.ts +0 -32
  79. package/lib/src/model/parentUtils.js +0 -64
  80. package/lib/src/model/prolog/generatePrologFacts.d.ts +0 -36
  81. package/lib/src/model/prolog/index.d.ts +0 -1
  82. package/lib/src/model/prolog/index.js +0 -1
  83. package/lib/src/model/query/ModelQueryBuilder.d.ts +0 -82
  84. package/lib/src/model/query/ModelQueryBuilder.js +0 -115
  85. package/lib/src/model/query/QueryBuilder.d.ts +0 -101
  86. package/lib/src/model/query/QueryBuilder.js +0 -193
  87. package/lib/src/model/query/SurrealQueryBuilder.d.ts +0 -48
  88. package/lib/src/model/query/SurrealQueryBuilder.js +0 -371
  89. package/lib/src/model/query/fetchInstance.d.ts +0 -24
  90. package/lib/src/model/query/fetchInstance.js +0 -144
  91. package/lib/src/model/query/hydration.d.ts +0 -54
  92. package/lib/src/model/query/hydration.js +0 -214
  93. package/lib/src/model/query/operations.d.ts +0 -59
  94. package/lib/src/model/query/operations.js +0 -384
  95. package/lib/src/model/query/snapshot.d.ts +0 -59
  96. package/lib/src/model/query/snapshot.js +0 -106
  97. package/lib/src/model/query/surrealCompiler.d.ts +0 -42
  98. package/lib/src/model/query/surrealCompiler.js +0 -304
  99. package/lib/src/model/schema/fromJSONSchema.js +0 -264
  100. package/lib/src/model/schema/metadata.d.ts +0 -15
  101. package/lib/src/model/schema/metadata.js +0 -112
  102. package/lib/src/model/subscription.d.ts +0 -47
  103. package/lib/src/model/subscription.js +0 -231
  104. package/lib/src/model/transaction.d.ts +0 -27
  105. package/lib/src/model/transaction.js +0 -32
  106. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  107. package/lib/src/shims/type-graphql.d.ts +0 -32
  108. package/lib/src/src/Ad4mClient.d.ts +0 -28
  109. package/lib/src/src/Address.d.ts +0 -1
  110. package/lib/src/src/DID.d.ts +0 -1
  111. package/lib/src/src/Exception.d.ts +0 -7
  112. package/lib/src/src/Literal.d.ts +0 -7
  113. package/lib/src/src/PubSub.d.ts +0 -17
  114. package/lib/src/src/SmartLiteral.d.ts +0 -12
  115. package/lib/src/src/agent/Agent.d.ts +0 -110
  116. package/lib/src/src/agent/AgentClient.d.ts +0 -62
  117. package/lib/src/src/agent/AgentResolver.d.ts +0 -30
  118. package/lib/src/src/agent/AgentStatus.d.ts +0 -8
  119. package/lib/src/src/ai/AIClient.d.ts +0 -32
  120. package/lib/src/src/ai/AIResolver.d.ts +0 -75
  121. package/lib/src/src/ai/Tasks.d.ts +0 -37
  122. package/lib/src/src/buildSchema.d.ts +0 -1
  123. package/lib/src/src/expression/Expression.d.ts +0 -28
  124. package/lib/src/src/expression/ExpressionClient.d.ts +0 -13
  125. package/lib/src/src/expression/ExpressionRef.d.ts +0 -9
  126. package/lib/src/src/expression/ExpressionResolver.d.ts +0 -10
  127. package/lib/src/src/index.d.ts +0 -35
  128. package/lib/src/src/jestSetup.d.ts +0 -1
  129. package/lib/src/src/language/Icon.d.ts +0 -4
  130. package/lib/src/src/language/Language.d.ts +0 -206
  131. package/lib/src/src/language/LanguageClient.d.ts +0 -17
  132. package/lib/src/src/language/LanguageContext.d.ts +0 -37
  133. package/lib/src/src/language/LanguageHandle.d.ts +0 -9
  134. package/lib/src/src/language/LanguageMeta.d.ts +0 -35
  135. package/lib/src/src/language/LanguageRef.d.ts +0 -6
  136. package/lib/src/src/language/LanguageResolver.d.ts +0 -19
  137. package/lib/src/src/links/Links.d.ts +0 -39
  138. package/lib/src/src/links/Links.test.d.ts +0 -1
  139. package/lib/src/src/model/Ad4mModel.d.ts +0 -1438
  140. package/lib/src/src/model/Ad4mModel.test.d.ts +0 -1
  141. package/lib/src/src/model/Subject.d.ts +0 -25
  142. package/lib/src/src/model/decorators.d.ts +0 -545
  143. package/lib/src/src/model/util.d.ts +0 -12
  144. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +0 -10
  145. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +0 -25
  146. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +0 -19
  147. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +0 -1
  148. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +0 -24
  149. package/lib/src/src/perspectives/LinkQuery.d.ts +0 -11
  150. package/lib/src/src/perspectives/Perspective.d.ts +0 -38
  151. package/lib/src/src/perspectives/Perspective.test.d.ts +0 -1
  152. package/lib/src/src/perspectives/PerspectiveClient.d.ts +0 -97
  153. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +0 -9
  154. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +0 -18
  155. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +0 -865
  156. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +0 -57
  157. package/lib/src/src/runtime/RuntimeClient.d.ts +0 -56
  158. package/lib/src/src/runtime/RuntimeResolver.d.ts +0 -132
  159. package/lib/src/src/shacl/SHACLFlow.d.ts +0 -171
  160. package/lib/src/src/shacl/SHACLFlow.test.d.ts +0 -1
  161. package/lib/src/src/shacl/SHACLShape.d.ts +0 -117
  162. package/lib/src/src/shacl/SHACLShape.test.d.ts +0 -1
  163. package/lib/src/src/typeDefs.d.ts +0 -1
  164. package/lib/src/src/unwrapApolloResult.d.ts +0 -2
  165. package/lib/src/src/utils.d.ts +0 -25
  166. /package/lib/src/{Ad4mClient.test.d.ts → model/relation-filtering.test.d.ts} +0 -0
@@ -0,0 +1,803 @@
1
+ /**
2
+ * Tests for relation filtering via conformance getters stored in SHACL shapes.
3
+ *
4
+ * Validates that:
5
+ * - buildConformanceFilter() correctly derives conditions from target model metadata
6
+ * - SHACL shapes serialize & deserialize getter + conformanceConditions through
7
+ * all serialization paths (toLinks/fromLinks, toJSON/fromJSON)
8
+ * - generateSHACL() populates getter on relation shapes when target has flags/required
9
+ * - filter:false and explicit getter options are respected
10
+ */
11
+ import { Ad4mModel } from "./Ad4mModel";
12
+ import {
13
+ Model,
14
+ Property,
15
+ Flag,
16
+ HasMany,
17
+ Optional,
18
+ buildConformanceFilter,
19
+ } from "./decorators";
20
+ import {
21
+ SHACLShape,
22
+ SHACLPropertyShape,
23
+ ConformanceCondition,
24
+ } from "../shacl/SHACLShape";
25
+ import { compileWhereClause } from "./surreal-utils";
26
+
27
+ // ============================================================================
28
+ // Test models
29
+ // ============================================================================
30
+
31
+ @Model({ name: "FlaggedTarget" })
32
+ class FlaggedTarget extends Ad4mModel {
33
+ @Flag({ through: "test://type", value: "test://flagged_type" })
34
+ type: string = "";
35
+
36
+ @Property({ through: "test://name", required: true })
37
+ name: string = "";
38
+ }
39
+
40
+ @Model({ name: "MinimalTarget" })
41
+ class MinimalTarget extends Ad4mModel {
42
+ @Optional({ through: "test://optionalProp" })
43
+ optionalProp: string = "";
44
+ }
45
+
46
+ @Model({ name: "ParentWithRelations" })
47
+ class ParentWithRelations extends Ad4mModel {
48
+ @HasMany({
49
+ through: "test://has_flagged",
50
+ target: () => FlaggedTarget,
51
+ })
52
+ flaggedItems: string[] = [];
53
+
54
+ @HasMany({
55
+ through: "test://has_minimal",
56
+ target: () => MinimalTarget,
57
+ })
58
+ minimalItems: string[] = [];
59
+
60
+ @HasMany({
61
+ through: "test://has_unfiltered",
62
+ target: () => FlaggedTarget,
63
+ filter: false,
64
+ })
65
+ unfilteredItems: string[] = [];
66
+
67
+ @HasMany({
68
+ getter: "(<-link[WHERE predicate = 'test://custom'].in.uri)",
69
+ })
70
+ customItems: string[] = [];
71
+ }
72
+
73
+ // ============================================================================
74
+ // buildConformanceFilter tests
75
+ // ============================================================================
76
+
77
+ describe("buildConformanceFilter()", () => {
78
+ it("should derive flag + required conditions from target model", () => {
79
+ const result = buildConformanceFilter("test://has_flagged", FlaggedTarget);
80
+
81
+ expect(result).toBeDefined();
82
+ expect(result!.conformanceConditions).toHaveLength(2);
83
+
84
+ // Flag condition
85
+ const flagCond = result!.conformanceConditions.find(c => c.type === "flag");
86
+ expect(flagCond).toBeDefined();
87
+ expect(flagCond!.predicate).toBe("test://type");
88
+ expect(flagCond!.value).toBe("test://flagged_type");
89
+
90
+ // Required condition
91
+ const reqCond = result!.conformanceConditions.find(c => c.type === "required");
92
+ expect(reqCond).toBeDefined();
93
+ expect(reqCond!.predicate).toBe("test://name");
94
+ expect(reqCond!.value).toBeUndefined();
95
+
96
+ // Getter string should be a SurrealQL expression
97
+ expect(result!.getter).toContain("->link[WHERE predicate =");
98
+ expect(result!.getter).toContain("test://has_flagged");
99
+ expect(result!.getter).toContain("test://type");
100
+ expect(result!.getter).toContain("test://flagged_type");
101
+ expect(result!.getter).toContain("test://name");
102
+ });
103
+
104
+ it("should return undefined for a target with no conformance conditions", () => {
105
+ const result = buildConformanceFilter("test://has_minimal", MinimalTarget);
106
+ expect(result).toBeUndefined();
107
+ });
108
+
109
+ it("should handle class with only flags (no required properties)", () => {
110
+ @Model({ name: "FlagOnly" })
111
+ class FlagOnly extends Ad4mModel {
112
+ @Flag({ through: "test://kind", value: "test://special" })
113
+ kind: string = "";
114
+ }
115
+
116
+ const result = buildConformanceFilter("test://pred", FlagOnly);
117
+ expect(result).toBeDefined();
118
+ expect(result!.conformanceConditions).toHaveLength(1);
119
+ expect(result!.conformanceConditions[0].type).toBe("flag");
120
+ expect(result!.conformanceConditions[0].predicate).toBe("test://kind");
121
+ expect(result!.conformanceConditions[0].value).toBe("test://special");
122
+ });
123
+
124
+ it("should skip properties with custom getters in required check", () => {
125
+ @Model({ name: "CustomGetterTarget" })
126
+ class CustomGetterTarget extends Ad4mModel {
127
+ @Flag({ through: "test://type", value: "test://cgt" })
128
+ type: string = "";
129
+
130
+ @Property({
131
+ through: "test://computed",
132
+ required: true,
133
+ getter: "(<-link[WHERE predicate = 'test://custom'].in.uri)[0]",
134
+ })
135
+ computed: string = "";
136
+ }
137
+
138
+ const result = buildConformanceFilter("test://pred", CustomGetterTarget);
139
+ expect(result).toBeDefined();
140
+ // Should have flag condition but NOT required condition for 'computed' (has custom getter)
141
+ expect(result!.conformanceConditions).toHaveLength(1);
142
+ expect(result!.conformanceConditions[0].type).toBe("flag");
143
+ });
144
+ });
145
+
146
+ // ============================================================================
147
+ // SHACL serialization round-trip tests
148
+ // ============================================================================
149
+
150
+ describe("SHACL shape getter serialization", () => {
151
+ const testGetter = "(->link[WHERE predicate = 'test://pred'].out[WHERE count(->link[WHERE predicate = 'test://type' AND out.uri = 'test://flag']) > 0].uri)";
152
+ const testConditions: ConformanceCondition[] = [
153
+ { type: "flag", predicate: "test://type", value: "test://flag" },
154
+ { type: "required", predicate: "test://name" },
155
+ ];
156
+
157
+ it("should round-trip getter + conditions through toLinks/fromLinks", () => {
158
+ const shape = new SHACLShape("test://Parent");
159
+ const prop: SHACLPropertyShape = {
160
+ name: "items",
161
+ path: "test://has_items",
162
+ nodeKind: "IRI",
163
+ getter: testGetter,
164
+ conformanceConditions: testConditions,
165
+ };
166
+ shape.addProperty(prop);
167
+
168
+ const links = shape.toLinks();
169
+
170
+ // Verify getter link exists
171
+ const getterLink = links.find(l => l.predicate === "ad4m://getter");
172
+ expect(getterLink).toBeDefined();
173
+ expect(getterLink!.target).toBe(`literal://string:${testGetter}`);
174
+
175
+ // Verify conditions link exists
176
+ const conditionsLink = links.find(l => l.predicate === "ad4m://conformanceConditions");
177
+ expect(conditionsLink).toBeDefined();
178
+
179
+ // Reconstruct from links
180
+ const shapeUri = shape.nodeShapeUri;
181
+ const linkObjs = links.map(l => ({
182
+ source: l.source,
183
+ predicate: l.predicate,
184
+ target: l.target,
185
+ }));
186
+ const reconstructed = SHACLShape.fromLinks(linkObjs as any, shapeUri);
187
+
188
+ expect(reconstructed.properties).toHaveLength(1);
189
+ expect(reconstructed.properties[0].getter).toBe(testGetter);
190
+ expect(reconstructed.properties[0].conformanceConditions).toEqual(testConditions);
191
+ });
192
+
193
+ it("should round-trip getter + conditions through toJSON/fromJSON", () => {
194
+ const shape = new SHACLShape("test://Parent");
195
+ const prop: SHACLPropertyShape = {
196
+ name: "items",
197
+ path: "test://has_items",
198
+ getter: testGetter,
199
+ conformanceConditions: testConditions,
200
+ };
201
+ shape.addProperty(prop);
202
+
203
+ const json = shape.toJSON();
204
+ const reconstructed = SHACLShape.fromJSON(json);
205
+
206
+ expect(reconstructed.properties).toHaveLength(1);
207
+ expect(reconstructed.properties[0].getter).toBe(testGetter);
208
+ expect(reconstructed.properties[0].conformanceConditions).toEqual(testConditions);
209
+ });
210
+
211
+ it("should omit getter/conditions links when not set", () => {
212
+ const shape = new SHACLShape("test://Basic");
213
+ const prop: SHACLPropertyShape = {
214
+ name: "simple",
215
+ path: "test://simple",
216
+ };
217
+ shape.addProperty(prop);
218
+
219
+ const links = shape.toLinks();
220
+ expect(links.find(l => l.predicate === "ad4m://getter")).toBeUndefined();
221
+ expect(links.find(l => l.predicate === "ad4m://conformanceConditions")).toBeUndefined();
222
+ });
223
+ });
224
+
225
+ // ============================================================================
226
+ // generateSHACL integration tests
227
+ // ============================================================================
228
+
229
+ describe("generateSHACL() relation getter population", () => {
230
+ it("should populate getter on relation with flagged target", () => {
231
+ const { shape } = (ParentWithRelations as any).generateSHACL();
232
+
233
+ // Find the flaggedItems property shape
234
+ const flaggedProp = shape.properties.find(
235
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
236
+ );
237
+ expect(flaggedProp).toBeDefined();
238
+ expect(flaggedProp!.getter).toBeDefined();
239
+ expect(flaggedProp!.getter).toContain("test://has_flagged");
240
+ expect(flaggedProp!.getter).toContain("test://type");
241
+ expect(flaggedProp!.getter).toContain("test://flagged_type");
242
+ expect(flaggedProp!.conformanceConditions).toBeDefined();
243
+ expect(flaggedProp!.conformanceConditions!.length).toBeGreaterThan(0);
244
+ });
245
+
246
+ it("should NOT populate getter when target has no conformance conditions", () => {
247
+ const { shape } = (ParentWithRelations as any).generateSHACL();
248
+
249
+ const minimalProp = shape.properties.find(
250
+ (p: SHACLPropertyShape) => p.name === "minimalItems"
251
+ );
252
+ expect(minimalProp).toBeDefined();
253
+ // MinimalTarget has only optional property — no flags/required — no getter
254
+ expect(minimalProp!.getter).toBeUndefined();
255
+ expect(minimalProp!.conformanceConditions).toBeUndefined();
256
+ });
257
+
258
+ it("should NOT populate getter when filter is false", () => {
259
+ const { shape } = (ParentWithRelations as any).generateSHACL();
260
+
261
+ const unfilteredProp = shape.properties.find(
262
+ (p: SHACLPropertyShape) => p.name === "unfilteredItems"
263
+ );
264
+ expect(unfilteredProp).toBeDefined();
265
+ // filter: false → no auto-generated getter even though target has flags
266
+ expect(unfilteredProp!.getter).toBeUndefined();
267
+ expect(unfilteredProp!.conformanceConditions).toBeUndefined();
268
+ });
269
+
270
+ it("should use explicit getter when provided (ignoring auto-generation)", () => {
271
+ const { shape } = (ParentWithRelations as any).generateSHACL();
272
+
273
+ // Getter-only relations have no predicate and are excluded from SHACL shapes
274
+ const customProp = shape.properties.find(
275
+ (p: SHACLPropertyShape) => p.name === "customItems"
276
+ );
277
+ expect(customProp).toBeUndefined();
278
+ });
279
+
280
+ it("should survive full round-trip: generateSHACL → toLinks → fromLinks", () => {
281
+ const { shape } = (ParentWithRelations as any).generateSHACL();
282
+ const links = shape.toLinks();
283
+ const reconstructed = SHACLShape.fromLinks(
284
+ links.map((l: any) => ({
285
+ source: l.source,
286
+ predicate: l.predicate,
287
+ target: l.target,
288
+ })),
289
+ shape.nodeShapeUri
290
+ );
291
+
292
+ // Find the flaggedItems property in reconstructed shape
293
+ const flaggedProp = reconstructed.properties.find(
294
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
295
+ );
296
+ expect(flaggedProp).toBeDefined();
297
+ expect(flaggedProp!.getter).toBeDefined();
298
+ expect(flaggedProp!.getter).toContain("test://has_flagged");
299
+ expect(flaggedProp!.conformanceConditions).toBeDefined();
300
+ expect(flaggedProp!.conformanceConditions!.length).toBeGreaterThan(0);
301
+
302
+ // The custom getter-only relation should NOT be in the SHACL shape
303
+ const customProp = reconstructed.properties.find(
304
+ (p: SHACLPropertyShape) => p.name === "customItems"
305
+ );
306
+ expect(customProp).toBeUndefined();
307
+ });
308
+ });
309
+
310
+ // ============================================================================
311
+ // Ad4mModel API tests — getModelMetadata() relation fields
312
+ // ============================================================================
313
+
314
+ describe("Ad4mModel.getModelMetadata() relation filtering fields", () => {
315
+ it("should expose target thunk on relations with target", () => {
316
+ const metadata = ParentWithRelations.getModelMetadata();
317
+
318
+ expect(metadata.relations.flaggedItems).toBeDefined();
319
+ expect(metadata.relations.flaggedItems.target).toBeDefined();
320
+ expect(metadata.relations.flaggedItems.target!()).toBe(FlaggedTarget);
321
+
322
+ expect(metadata.relations.minimalItems.target).toBeDefined();
323
+ expect(metadata.relations.minimalItems.target!()).toBe(MinimalTarget);
324
+ });
325
+
326
+ it("should expose filter:false on opt-out relations", () => {
327
+ const metadata = ParentWithRelations.getModelMetadata();
328
+
329
+ // Default (not set) — filter should be undefined (treated as true)
330
+ expect(metadata.relations.flaggedItems.filter).toBeUndefined();
331
+
332
+ // Explicit opt-out
333
+ expect(metadata.relations.unfilteredItems.filter).toBe(false);
334
+ });
335
+
336
+ it("should expose explicit getter on relations with custom getter", () => {
337
+ const metadata = ParentWithRelations.getModelMetadata();
338
+
339
+ // Explicit getter provided via decorator (getter-only, no predicate)
340
+ expect(metadata.relations.customItems.getter).toBe(
341
+ "(<-link[WHERE predicate = 'test://custom'].in.uri)"
342
+ );
343
+ expect(metadata.relations.customItems.predicate).toBe("");
344
+
345
+ // Auto-generated getter is NOT in decorator metadata (it's in the SHACL shape)
346
+ expect(metadata.relations.flaggedItems.getter).toBeUndefined();
347
+ });
348
+
349
+ it("should produce matching getter between getModelMetadata target and SHACL shape", () => {
350
+ // This verifies that the auto-generated getter in the SHACL shape
351
+ // is consistent with what buildConformanceFilter produces from the
352
+ // target model that getModelMetadata() exposes.
353
+ const metadata = ParentWithRelations.getModelMetadata();
354
+ const { shape } = (ParentWithRelations as any).generateSHACL();
355
+
356
+ const flaggedRel = metadata.relations.flaggedItems;
357
+ const TargetClass = flaggedRel.target!();
358
+
359
+ // Build filter from the target class exposed by metadata
360
+ const filter = buildConformanceFilter(flaggedRel.predicate, TargetClass);
361
+ expect(filter).toBeDefined();
362
+
363
+ // Should match what generateSHACL() stored on the property shape
364
+ const shapeProp = shape.properties.find(
365
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
366
+ );
367
+ expect(shapeProp!.getter).toBe(filter!.getter);
368
+ expect(shapeProp!.conformanceConditions).toEqual(filter!.conformanceConditions);
369
+ });
370
+
371
+ it("should have correct direction for forward relations", () => {
372
+ const metadata = ParentWithRelations.getModelMetadata();
373
+
374
+ expect(metadata.relations.flaggedItems.direction).toBe("forward");
375
+ expect(metadata.relations.minimalItems.direction).toBe("forward");
376
+ expect(metadata.relations.unfilteredItems.direction).toBe("forward");
377
+ expect(metadata.relations.customItems.direction).toBe("forward");
378
+ });
379
+ });
380
+
381
+ // ============================================================================
382
+ // Validation tests
383
+ // ============================================================================
384
+
385
+ describe("Relation decorator validation", () => {
386
+ it("should throw if both getter and target are provided", () => {
387
+ expect(() => {
388
+ @Model({ name: "InvalidGetterTarget" })
389
+ class _Invalid extends Ad4mModel {
390
+ @HasMany({
391
+ getter: "(<-link.in.uri)",
392
+ target: () => FlaggedTarget,
393
+ })
394
+ items: string[] = [];
395
+ }
396
+ }).toThrow(/getter.*target.*mutually exclusive/i);
397
+ });
398
+
399
+ it("should throw if both getter and through are provided", () => {
400
+ expect(() => {
401
+ @Model({ name: "InvalidGetterThrough" })
402
+ class _Invalid extends Ad4mModel {
403
+ @HasMany({
404
+ getter: "(<-link.in.uri)",
405
+ through: "test://pred",
406
+ })
407
+ items: string[] = [];
408
+ }
409
+ }).toThrow(/getter.*through.*mutually exclusive/i);
410
+ });
411
+
412
+ it("should allow getter-only relations (read-only)", () => {
413
+ expect(() => {
414
+ @Model({ name: "ValidGetterOnly" })
415
+ class _Valid extends Ad4mModel {
416
+ @HasMany({
417
+ getter: "(<-link.in.uri)",
418
+ })
419
+ items: string[] = [];
420
+ }
421
+ }).not.toThrow();
422
+ });
423
+ });
424
+
425
+ // ============================================================================
426
+ // Default through tests
427
+ // ============================================================================
428
+
429
+ describe("Default through predicate", () => {
430
+ it("should default through to ad4m://has_child when omitted", () => {
431
+ @Model({ name: "DefaultThrough" })
432
+ class DefaultThrough extends Ad4mModel {
433
+ @HasMany(() => FlaggedTarget)
434
+ items: string[] = [];
435
+ }
436
+
437
+ const { shape } = (DefaultThrough as any).generateSHACL();
438
+ const itemsProp = shape.properties.find(
439
+ (p: SHACLPropertyShape) => p.name === "items"
440
+ );
441
+ expect(itemsProp).toBeDefined();
442
+ expect(itemsProp!.path).toBe("ad4m://has_child");
443
+ });
444
+
445
+ it("should use explicit through when provided", () => {
446
+ @Model({ name: "ExplicitThrough" })
447
+ class ExplicitThrough extends Ad4mModel {
448
+ @HasMany(() => FlaggedTarget, { through: "test://custom_pred" })
449
+ items: string[] = [];
450
+ }
451
+
452
+ const { shape } = (ExplicitThrough as any).generateSHACL();
453
+ const itemsProp = shape.properties.find(
454
+ (p: SHACLPropertyShape) => p.name === "items"
455
+ );
456
+ expect(itemsProp).toBeDefined();
457
+ expect(itemsProp!.path).toBe("test://custom_pred");
458
+ });
459
+ });
460
+
461
+ // ============================================================================
462
+ // sh:class tests
463
+ // ============================================================================
464
+
465
+ describe("sh:class target shape reference", () => {
466
+ it("should set sh:class on relation shapes when target is provided", () => {
467
+ const { shape } = (ParentWithRelations as any).generateSHACL();
468
+
469
+ const flaggedProp = shape.properties.find(
470
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
471
+ );
472
+ expect(flaggedProp).toBeDefined();
473
+ expect(flaggedProp!.class).toBeDefined();
474
+ expect(flaggedProp!.class).toContain("FlaggedTarget");
475
+ expect(flaggedProp!.class).toContain("Shape");
476
+ });
477
+
478
+ it("should set sh:class even when filter is false", () => {
479
+ const { shape } = (ParentWithRelations as any).generateSHACL();
480
+
481
+ const unfilteredProp = shape.properties.find(
482
+ (p: SHACLPropertyShape) => p.name === "unfilteredItems"
483
+ );
484
+ expect(unfilteredProp).toBeDefined();
485
+ // filter:false suppresses getter but NOT sh:class
486
+ expect(unfilteredProp!.getter).toBeUndefined();
487
+ expect(unfilteredProp!.class).toBeDefined();
488
+ expect(unfilteredProp!.class).toContain("FlaggedTarget");
489
+ });
490
+
491
+ it("should NOT set sh:class when no target is provided", () => {
492
+ @Model({ name: "NoTargetParent" })
493
+ class NoTargetParent extends Ad4mModel {
494
+ @HasMany({ through: "test://pred" })
495
+ items: string[] = [];
496
+ }
497
+
498
+ const { shape } = (NoTargetParent as any).generateSHACL();
499
+ const itemsProp = shape.properties.find(
500
+ (p: SHACLPropertyShape) => p.name === "items"
501
+ );
502
+ expect(itemsProp).toBeDefined();
503
+ expect(itemsProp!.class).toBeUndefined();
504
+ });
505
+
506
+ it("should round-trip sh:class through toLinks/fromLinks", () => {
507
+ const shape = new SHACLShape("test://Parent");
508
+ const prop: SHACLPropertyShape = {
509
+ name: "items",
510
+ path: "test://has_items",
511
+ nodeKind: "IRI",
512
+ class: "test://TargetShape",
513
+ };
514
+ shape.addProperty(prop);
515
+
516
+ const links = shape.toLinks();
517
+ const classLink = links.find(l => l.predicate === "sh://class");
518
+ expect(classLink).toBeDefined();
519
+ expect(classLink!.target).toBe("test://TargetShape");
520
+
521
+ const reconstructed = SHACLShape.fromLinks(
522
+ links.map((l: any) => ({ source: l.source, predicate: l.predicate, target: l.target })),
523
+ shape.nodeShapeUri
524
+ );
525
+ expect(reconstructed.properties[0].class).toBe("test://TargetShape");
526
+ });
527
+
528
+ it("should round-trip sh:class through toJSON/fromJSON", () => {
529
+ const shape = new SHACLShape("test://Parent");
530
+ const prop: SHACLPropertyShape = {
531
+ name: "items",
532
+ path: "test://has_items",
533
+ class: "test://TargetShape",
534
+ };
535
+ shape.addProperty(prop);
536
+
537
+ const json = shape.toJSON();
538
+ const reconstructed = SHACLShape.fromJSON(json);
539
+ expect(reconstructed.properties[0].class).toBe("test://TargetShape");
540
+ });
541
+ });
542
+
543
+ // ============================================================================
544
+ // where clause tests
545
+ // ============================================================================
546
+
547
+ describe("where clause validation", () => {
548
+ it("should throw if both where and getter are provided", () => {
549
+ expect(() => {
550
+ @Model({ name: "InvalidWhereGetter" })
551
+ class _Invalid extends Ad4mModel {
552
+ @HasMany({
553
+ where: { status: "active" },
554
+ getter: "(<-link.in.uri)",
555
+ })
556
+ items: string[] = [];
557
+ }
558
+ }).toThrow(/where.*getter.*mutually exclusive/i);
559
+ });
560
+
561
+ it("should throw if both where and filter:false are provided", () => {
562
+ expect(() => {
563
+ @Model({ name: "InvalidWhereFilterFalse" })
564
+ class _Invalid extends Ad4mModel {
565
+ @HasMany(() => FlaggedTarget, {
566
+ through: "test://pred",
567
+ where: { status: "active" },
568
+ filter: false,
569
+ })
570
+ items: string[] = [];
571
+ }
572
+ }).toThrow(/where.*filter.*contradictory/i);
573
+ });
574
+ });
575
+
576
+ describe("where clause compilation", () => {
577
+ it("should compile where clause to SurrealQL getter", () => {
578
+ @Model({ name: "WhereTarget" })
579
+ class WhereTarget extends Ad4mModel {
580
+ @Property({ through: "test://status", required: true })
581
+ status: string = "";
582
+ }
583
+
584
+ @Model({ name: "WhereParent" })
585
+ class WhereParent extends Ad4mModel {
586
+ @HasMany(() => WhereTarget, {
587
+ through: "test://has_item",
588
+ where: { status: "active" },
589
+ })
590
+ items: string[] = [];
591
+ }
592
+
593
+ const { shape } = (WhereParent as any).generateSHACL();
594
+ const itemsProp = shape.properties.find(
595
+ (p: SHACLPropertyShape) => p.name === "items"
596
+ );
597
+ expect(itemsProp).toBeDefined();
598
+ expect(itemsProp!.getter).toBeDefined();
599
+ expect(itemsProp!.getter).toContain("test://has_item");
600
+ expect(itemsProp!.getter).toContain("test://status");
601
+ expect(itemsProp!.getter).toContain("active");
602
+ });
603
+
604
+ it("should use where clause instead of auto-derived conformance when both target and where are set", () => {
605
+ @Model({ name: "WhereOverrideParent" })
606
+ class WhereOverrideParent extends Ad4mModel {
607
+ @HasMany(() => FlaggedTarget, {
608
+ through: "test://has_flagged",
609
+ where: { name: "specific" },
610
+ })
611
+ flaggedItems: string[] = [];
612
+ }
613
+
614
+ const { shape } = (WhereOverrideParent as any).generateSHACL();
615
+ const prop = shape.properties.find(
616
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
617
+ );
618
+ expect(prop).toBeDefined();
619
+ expect(prop!.getter).toBeDefined();
620
+ // Should contain the where condition (name = specific)
621
+ expect(prop!.getter).toContain("test://name");
622
+ expect(prop!.getter).toContain("specific");
623
+ // Should NOT contain the auto-derived flag condition
624
+ // (where overrides auto-conformance)
625
+ expect(prop!.getter).not.toContain("test://flagged_type");
626
+ });
627
+
628
+ it("should compile where clause with not operator", () => {
629
+ @Model({ name: "WhereNotTarget" })
630
+ class WhereNotTarget extends Ad4mModel {
631
+ @Property({ through: "test://status" })
632
+ status: string = "";
633
+ }
634
+
635
+ @Model({ name: "WhereNotParent" })
636
+ class WhereNotParent extends Ad4mModel {
637
+ @HasMany(() => WhereNotTarget, {
638
+ through: "test://has_item",
639
+ where: { status: { not: "archived" } },
640
+ })
641
+ items: string[] = [];
642
+ }
643
+
644
+ const { shape } = (WhereNotParent as any).generateSHACL();
645
+ const prop = shape.properties.find(
646
+ (p: SHACLPropertyShape) => p.name === "items"
647
+ );
648
+ expect(prop).toBeDefined();
649
+ expect(prop!.getter).toBeDefined();
650
+ // Should contain a negation condition
651
+ expect(prop!.getter).toContain("test://status");
652
+ expect(prop!.getter).toContain("archived");
653
+ });
654
+
655
+ it("should compile where clause with array values (IN)", () => {
656
+ @Model({ name: "WhereArrayTarget" })
657
+ class WhereArrayTarget extends Ad4mModel {
658
+ @Property({ through: "test://category" })
659
+ category: string = "";
660
+ }
661
+
662
+ @Model({ name: "WhereArrayParent" })
663
+ class WhereArrayParent extends Ad4mModel {
664
+ @HasMany(() => WhereArrayTarget, {
665
+ through: "test://has_item",
666
+ where: { category: ["food", "drink"] },
667
+ })
668
+ items: string[] = [];
669
+ }
670
+
671
+ const { shape } = (WhereArrayParent as any).generateSHACL();
672
+ const prop = shape.properties.find(
673
+ (p: SHACLPropertyShape) => p.name === "items"
674
+ );
675
+ expect(prop).toBeDefined();
676
+ expect(prop!.getter).toBeDefined();
677
+ expect(prop!.getter).toContain("test://category");
678
+ expect(prop!.getter).toContain("food");
679
+ expect(prop!.getter).toContain("drink");
680
+ });
681
+
682
+ it("should compile where clause without target using raw predicate URIs", () => {
683
+ @Model({ name: "WhereNoTargetParent" })
684
+ class WhereNoTargetParent extends Ad4mModel {
685
+ @HasMany({
686
+ through: "test://has_item",
687
+ where: { "test://status": "active" },
688
+ })
689
+ items: string[] = [];
690
+ }
691
+
692
+ const { shape } = (WhereNoTargetParent as any).generateSHACL();
693
+ const prop = shape.properties.find(
694
+ (p: SHACLPropertyShape) => p.name === "items"
695
+ );
696
+ expect(prop).toBeDefined();
697
+ expect(prop!.getter).toBeDefined();
698
+ expect(prop!.getter).toContain("test://status");
699
+ expect(prop!.getter).toContain("active");
700
+ });
701
+
702
+ it("should set both where-compiled getter and sh:class when target is present", () => {
703
+ @Model({ name: "WherePlusClassParent" })
704
+ class WherePlusClassParent extends Ad4mModel {
705
+ @HasMany(() => FlaggedTarget, {
706
+ through: "test://has_flagged",
707
+ where: { name: "specific" },
708
+ })
709
+ flaggedItems: string[] = [];
710
+ }
711
+
712
+ const { shape } = (WherePlusClassParent as any).generateSHACL();
713
+ const prop = shape.properties.find(
714
+ (p: SHACLPropertyShape) => p.name === "flaggedItems"
715
+ );
716
+ expect(prop).toBeDefined();
717
+ // where-compiled getter
718
+ expect(prop!.getter).toBeDefined();
719
+ expect(prop!.getter).toContain("specific");
720
+ // sh:class still set (target is present)
721
+ expect(prop!.class).toBeDefined();
722
+ expect(prop!.class).toContain("FlaggedTarget");
723
+ });
724
+
725
+ it("should round-trip where-compiled getter through toLinks/fromLinks", () => {
726
+ @Model({ name: "WhereRoundTripTarget" })
727
+ class WhereRoundTripTarget extends Ad4mModel {
728
+ @Property({ through: "test://status", required: true })
729
+ status: string = "";
730
+ }
731
+
732
+ @Model({ name: "WhereRoundTripParent" })
733
+ class WhereRoundTripParent extends Ad4mModel {
734
+ @HasMany(() => WhereRoundTripTarget, {
735
+ through: "test://has_item",
736
+ where: { status: "active" },
737
+ })
738
+ items: string[] = [];
739
+ }
740
+
741
+ const { shape } = (WhereRoundTripParent as any).generateSHACL();
742
+ const links = shape.toLinks();
743
+ const reconstructed = SHACLShape.fromLinks(
744
+ links.map((l: any) => ({ source: l.source, predicate: l.predicate, target: l.target })),
745
+ shape.nodeShapeUri
746
+ );
747
+
748
+ const prop = reconstructed.properties.find(
749
+ (p: SHACLPropertyShape) => p.name === "items"
750
+ );
751
+ expect(prop).toBeDefined();
752
+ expect(prop!.getter).toBeDefined();
753
+ expect(prop!.getter).toContain("test://status");
754
+ expect(prop!.getter).toContain("active");
755
+ });
756
+ });
757
+
758
+ // ============================================================================
759
+ // compileWhereClause() unit tests
760
+ // ============================================================================
761
+
762
+ describe("compileWhereClause()", () => {
763
+ it("should compile simple equality to SurrealQL condition", () => {
764
+ const conditions = compileWhereClause(
765
+ { status: "active" },
766
+ { properties: { status: { name: "status", predicate: "test://status", required: false, readOnly: false } }, relations: {}, className: "Test" }
767
+ );
768
+ expect(conditions).toHaveLength(1);
769
+ expect(conditions[0]).toContain("test://status");
770
+ expect(conditions[0]).toContain("active");
771
+ });
772
+
773
+ it("should compile not operator", () => {
774
+ const conditions = compileWhereClause(
775
+ { status: { not: "archived" } },
776
+ { properties: { status: { name: "status", predicate: "test://status", required: false, readOnly: false } }, relations: {}, className: "Test" }
777
+ );
778
+ expect(conditions).toHaveLength(1);
779
+ expect(conditions[0]).toContain("= 0"); // negation
780
+ expect(conditions[0]).toContain("archived");
781
+ });
782
+
783
+ it("should compile array values to IN clause", () => {
784
+ const conditions = compileWhereClause(
785
+ { category: ["food", "drink"] },
786
+ { properties: { category: { name: "category", predicate: "test://category", required: false, readOnly: false } }, relations: {}, className: "Test" }
787
+ );
788
+ expect(conditions).toHaveLength(1);
789
+ expect(conditions[0]).toContain("food");
790
+ expect(conditions[0]).toContain("drink");
791
+ expect(conditions[0]).toContain("IN");
792
+ });
793
+
794
+ it("should fall back to raw predicate URIs when metadata is null", () => {
795
+ const conditions = compileWhereClause(
796
+ { "test://raw_pred": "value" },
797
+ null as any
798
+ );
799
+ expect(conditions).toHaveLength(1);
800
+ expect(conditions[0]).toContain("test://raw_pred");
801
+ expect(conditions[0]).toContain("value");
802
+ });
803
+ });