@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
@@ -0,0 +1,820 @@
1
+ /**
2
+ * SPARQL query building utilities for Ad4mModel.
3
+ *
4
+ * Uses the direct triple + named graph storage model where each AD4M link
5
+ * is stored in a named graph (keyed by link hash) with metadata in the default graph.
6
+ *
7
+ * All AD4M URIs (source, predicate, target) become RDF IRIs.
8
+ *
9
+ * @module
10
+ */
11
+
12
+ import { Literal } from "../Literal";
13
+ import { resolveParentPredicate } from "./query-common";
14
+ import type { RelationMetadataEntry } from "./decorators";
15
+ import type { Where, Query, ModelMetadata, PropertyMetadata } from "./types";
16
+
17
+ /**
18
+ * Check whether a `where` clause contains filters that cannot be pushed down
19
+ * to SPARQL and must be evaluated in JS after hydration.
20
+ *
21
+ * JS-only filters include:
22
+ * - Literal-stored properties (equality, comparison, contains, etc.)
23
+ * - Reverse relations (belongsToOne / belongsToMany)
24
+ * - author / timestamp filters (skipped by buildSPARQLWhereFilters)
25
+ *
26
+ * When JS-only filters exist, SPARQL-level LIMIT/OFFSET must NOT be applied
27
+ * because the database would cap the candidate set before JS filters run,
28
+ * potentially discarding matches beyond the LIMIT.
29
+ */
30
+ export function hasJsOnlyWhereFilters(
31
+ metadata: ModelMetadata,
32
+ allRelationsMetadata: Record<string, RelationMetadataEntry>,
33
+ where?: Where,
34
+ ): boolean {
35
+ if (!where) return false;
36
+
37
+ for (const [propertyName, condition] of Object.entries(where)) {
38
+ if (propertyName === "base" || propertyName === "id") continue;
39
+
40
+ // author/timestamp: return true so that count() falls back to the full hydration
41
+ // path (which uses buildSPARQLQuery — which DOES bind ?author/?timestamp via the
42
+ // named graph block). buildSPARQLCountQuery intentionally omits the named graph,
43
+ // so emitting an ?author FILTER there would produce unbound-variable SPARQL.
44
+ // buildSPARQLWhereFilters still pushes these into FILTER when called from
45
+ // buildSPARQLQuery / buildSPARQLGroupedCountQuery, which both include the named graph.
46
+ if (propertyName === "author" || propertyName === "timestamp") return true;
47
+
48
+ const propMeta = metadata.properties[propertyName];
49
+ if (!propMeta) continue;
50
+
51
+ // Reverse relations are JS-only
52
+ const relMeta = allRelationsMetadata[propertyName];
53
+ if (relMeta && (relMeta.kind === 'belongsToOne' || relMeta.kind === 'belongsToMany')) {
54
+ return true;
55
+ }
56
+
57
+ // Literal-stored properties: equality/IN/NOT can be pushed to SPARQL via
58
+ // <ad4m://fn/parse_literal>(), but comparison operators (gt/lt/gte/lte/between/contains)
59
+ // must remain JS-only because parse_literal returns strings.
60
+ if (isLiteralStoredProperty(propMeta)) {
61
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
62
+ const ops = condition as any;
63
+ const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
64
+ ops.lt !== undefined || ops.lte !== undefined ||
65
+ ops.between !== undefined || ops.contains !== undefined;
66
+ if (hasCompOps) return true;
67
+ // NOT with simple value can be pushed to SPARQL — not JS-only
68
+ }
69
+ // Simple equality and IN filters can be pushed to SPARQL — not JS-only
70
+ }
71
+ }
72
+
73
+ return false;
74
+ }
75
+
76
+ /**
77
+ * Check if a string value looks like a URI (has a scheme).
78
+ */
79
+ function looksLikeUri(value: string): boolean {
80
+ return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
81
+ }
82
+
83
+ /**
84
+ * Convert a JS value to its literal: IRI form, matching how the Rust executor
85
+ * stores property values that don't have a resolveLanguage set.
86
+ * Strings that already look like URIs are returned as-is.
87
+ */
88
+ function valueToLiteralIri(value: any): string {
89
+ if (typeof value === 'string') {
90
+ if (looksLikeUri(value)) return value;
91
+ return Literal.from(value).toUrl();
92
+ }
93
+ if (typeof value === 'number') {
94
+ return Literal.from(value).toUrl();
95
+ }
96
+ if (typeof value === 'boolean') {
97
+ return Literal.from(value).toUrl();
98
+ }
99
+ return Literal.from(String(value)).toUrl();
100
+ }
101
+
102
+ /**
103
+ * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
104
+ * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
105
+ * both store values as literal: URIs. Only properties with a non-literal resolveLanguage
106
+ * (e.g. file storage) or flag properties store raw URIs.
107
+ */
108
+ function isLiteralStoredProperty(propMeta: PropertyMetadata): boolean {
109
+ if (propMeta.flag) return false;
110
+ // If resolveLanguage is set to something other than "literal", it's a language expression URI
111
+ if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal") return false;
112
+ // Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
113
+ return true;
114
+ }
115
+
116
+ /**
117
+ * Escape a string for use as a SPARQL string literal.
118
+ */
119
+ function escapeSPARQL(value: string): string {
120
+ return value
121
+ .replace(/\\/g, "\\\\")
122
+ .replace(/"/g, '\\"')
123
+ .replace(/\n/g, "\\n")
124
+ .replace(/\r/g, "\\r")
125
+ .replace(/\t/g, "\\t");
126
+ }
127
+
128
+ /**
129
+ * Format a value as a SPARQL string literal (double-quoted).
130
+ */
131
+ export function formatSPARQLValue(value: any): string {
132
+ if (typeof value === "string") {
133
+ return `"${escapeSPARQL(value)}"`;
134
+ }
135
+ return `"${String(value)}"`;
136
+ }
137
+
138
+ /**
139
+ * Format an AD4M URI as an RDF IRI for use in SPARQL triple patterns.
140
+ * All AD4M link source/predicate/target values become IRIs in angle brackets.
141
+ * The Rust SPARQL service transparently transforms these to valid IRI format.
142
+ */
143
+ function iri(value: string): string {
144
+ return `<${value}>`;
145
+ }
146
+
147
+ /**
148
+ * Map a user-facing property name to the SPARQL variable alias used in the query.
149
+ *
150
+ * Properties appear in the query as:
151
+ * - Required properties: `?cfTarget_${name}`
152
+ * - Where-clause joins: `?wTarget_${name}`
153
+ * - Initial-value fallback: `?cfInitTarget_${name}`
154
+ *
155
+ * For ORDER BY, we prefer the conformance variable (always present for required props),
156
+ * then the where-target variable.
157
+ */
158
+ function mapPropertyToSPARQLVar(propertyName: string, metadata: ModelMetadata): string {
159
+ const propMeta = metadata.properties[propertyName];
160
+ if (propMeta) {
161
+ if (propMeta.required && !propMeta.getter && !(propMeta.flag && propMeta.initial)) {
162
+ return `?cfTarget_${propertyName}`;
163
+ }
164
+ if (propMeta.initial && !propMeta.flag) {
165
+ return `?cfInitTarget_${propertyName}`;
166
+ }
167
+ }
168
+ // Fallback: where-clause variable or raw name
169
+ return `?wTarget_${propertyName}`;
170
+ }
171
+
172
+ /**
173
+ * Build a SPARQL query that returns all links belonging to instances of
174
+ * the given model class, optionally filtered by `where` conditions.
175
+ *
176
+ * Uses direct triple patterns: ?source ?predicate ?target
177
+ * with named graph storage and metadata keyed by graph IRI.
178
+ */
179
+ export function buildSPARQLQuery(
180
+ metadata: ModelMetadata,
181
+ allRelationsMetadata: Record<string, RelationMetadataEntry>,
182
+ query: Query,
183
+ modelClass: any,
184
+ ): string {
185
+ const joinPatterns: string[] = [];
186
+ const filterExpressions: string[] = [];
187
+
188
+ // Parent filter — direct triple pattern
189
+ if (query.parent) {
190
+ const parentPredicate = resolveParentPredicate(query.parent, modelClass);
191
+ joinPatterns.push(`
192
+ ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
193
+ }
194
+
195
+ // Required property JOIN patterns — direct triple patterns
196
+ let hasConformance = false;
197
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
198
+ if (propMeta.required) {
199
+ if (propMeta.getter) continue;
200
+ hasConformance = true;
201
+ if (propMeta.flag && propMeta.initial) {
202
+ joinPatterns.push(`
203
+ ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
204
+ } else {
205
+ joinPatterns.push(`
206
+ ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
207
+ }
208
+ }
209
+ }
210
+
211
+ // Fallback: initial-value JOIN patterns
212
+ if (!hasConformance) {
213
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
214
+ if (propMeta.initial) {
215
+ hasConformance = true;
216
+ if (propMeta.flag) {
217
+ joinPatterns.push(`
218
+ ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
219
+ } else {
220
+ joinPatterns.push(`
221
+ ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
222
+ }
223
+ break;
224
+ }
225
+ }
226
+ }
227
+
228
+ // Fallback: open-world structural matching
229
+ // Use a subquery with DISTINCT to avoid row multiplication when the main
230
+ // ?source ?predicate ?target pattern cross-joins with multiple structural matches.
231
+ if (!hasConformance && joinPatterns.length === 0) {
232
+ const knownPredicates: string[] = [];
233
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
234
+ if (propMeta.predicate) {
235
+ knownPredicates.push(iri(propMeta.predicate));
236
+ }
237
+ }
238
+ if (metadata.relations) {
239
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
240
+ if (relMeta.predicate) {
241
+ knownPredicates.push(iri(relMeta.predicate));
242
+ }
243
+ }
244
+ }
245
+ if (knownPredicates.length > 0) {
246
+ joinPatterns.push(`
247
+ { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(", ")})) } }`);
248
+ }
249
+ }
250
+
251
+ // Build WHERE clause filters from user query
252
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, query.where);
253
+ joinPatterns.push(...userJoins);
254
+ filterExpressions.push(...userFilters);
255
+
256
+ // Main triple pattern — fetches all links for matched sources
257
+ // The direct triple in named graph: GRAPH ?linkGraph { ?source ?predicate ?target }
258
+ // FILTER(isIRI(?source)) excludes non-IRI subjects
259
+ const joinClause = joinPatterns.join("\n");
260
+ const filterClause = filterExpressions.length > 0
261
+ ? `FILTER(\n ${filterExpressions.join(" &&\n ")}\n )`
262
+ : "";
263
+
264
+ // Determine if SPARQL-level pagination is safe.
265
+ // When JS-only where filters exist, we must NOT limit at the SPARQL level
266
+ // because the database would cap candidates before JS filters run.
267
+ // Without an explicit ORDER BY, SPARQL OFFSET/LIMIT produces non-deterministic
268
+ // ordering across different query plans and index traversals. Fall back to
269
+ // JS-level slicing in that case to preserve the grouping order from the full
270
+ // result set.
271
+ const canPaginateInSPARQL = !hasJsOnlyWhereFilters(metadata, allRelationsMetadata, query.where)
272
+ && (query.limit !== undefined || query.offset !== undefined)
273
+ && query.order !== undefined && Object.keys(query.order).length > 0;
274
+
275
+ // Build a pagination subquery that constrains ?source to only the page
276
+ // of interest. This avoids fetching all links for all matching instances.
277
+ const paginationSubquery = canPaginateInSPARQL
278
+ ? buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query)
279
+ : '';
280
+
281
+ if (paginationSubquery) {
282
+ // Use the pagination subquery to constrain ?source, then fetch all links
283
+ // for those sources only.
284
+ return `
285
+ SELECT ?source ?predicate ?target ?author ?timestamp WHERE {
286
+ ${paginationSubquery}${joinClause}
287
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
288
+ FILTER(isIRI(?source) && isIRI(?predicate))
289
+ ?linkGraph <ad4m://ontology/author> ?author .
290
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
291
+ ${filterClause}
292
+ }
293
+ `.trim();
294
+ }
295
+
296
+ return `
297
+ SELECT ?source ?predicate ?target ?author ?timestamp WHERE {${joinClause}
298
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
299
+ FILTER(isIRI(?source) && isIRI(?predicate))
300
+ ?linkGraph <ad4m://ontology/author> ?author .
301
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
302
+ ${filterClause}
303
+ }
304
+ ${buildSPARQLOrderLimitOffset(metadata, query)}
305
+ `.trim();
306
+ }
307
+
308
+ /**
309
+ * Build ORDER BY / LIMIT / OFFSET clauses for the SPARQL query.
310
+ *
311
+ * NOTE: The outer SELECT returns multiple rows per instance (one per link),
312
+ * so LIMIT/OFFSET at the outer level would cut off links mid-instance.
313
+ * This function is kept for backward compatibility and always returns "".
314
+ * SPARQL-level pagination is handled via a subquery in buildSPARQLQuery
315
+ * using buildPaginationSubquery().
316
+ */
317
+ export function buildSPARQLOrderLimitOffset(_metadata: ModelMetadata, query: Query): string {
318
+ return "";
319
+ }
320
+
321
+ /**
322
+ * Build an inner subquery that selects DISTINCT ?source URIs with
323
+ * ORDER BY, LIMIT, and OFFSET applied at the instance level.
324
+ *
325
+ * Because the outer SELECT returns multiple rows per instance (one per link),
326
+ * we cannot apply LIMIT/OFFSET there. Instead this subquery constrains
327
+ * ?source to only the instances on the requested page.
328
+ *
329
+ * @internal — used by buildSPARQLQuery when SPARQL-level pagination is safe.
330
+ */
331
+ export function buildPaginationSubquery(
332
+ joinPatterns: string[],
333
+ filterExpressions: string[],
334
+ metadata: ModelMetadata,
335
+ query: Query,
336
+ ): string {
337
+ const innerJoin = joinPatterns.join('\n');
338
+ const innerFilter = filterExpressions.length > 0
339
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
340
+ : '';
341
+
342
+ // Build ORDER BY clause from query.order.
343
+ // When ORDER BY references non-grouped variables we must use SAMPLE()
344
+ // aggregates so the query is valid SPARQL 1.1.
345
+ let orderByClause = '';
346
+ const orderJoinPatterns: string[] = [];
347
+ const sampleProjections: string[] = []; // e.g. (SAMPLE(?cfTarget_title) AS ?pg_sort_0)
348
+ const needsGroupBy = query.order && Object.keys(query.order).length > 0;
349
+
350
+ if (query.order) {
351
+ let sortIdx = 0;
352
+ const orderTerms = Object.entries(query.order).map(([prop, dir]) => {
353
+ const sparqlVar = mapPropertyToSPARQLVar(prop, metadata);
354
+ // Check if this order property's variable is already bound by existing
355
+ // join patterns. If not, add an OPTIONAL join so ORDER BY is deterministic.
356
+ const varAlreadyBound = innerJoin.includes(sparqlVar);
357
+ if (!varAlreadyBound) {
358
+ const propMeta = metadata.properties[prop];
359
+ if (propMeta && propMeta.predicate && !propMeta.getter) {
360
+ orderJoinPatterns.push(`\n OPTIONAL { ?source <${propMeta.predicate}> ${sparqlVar} . }`);
361
+ }
362
+ }
363
+ // Use SAMPLE() aggregate so ORDER BY is valid with GROUP BY ?source.
364
+ const sortAlias = `?pg_sort_${sortIdx++}`;
365
+ sampleProjections.push(`(SAMPLE(${sparqlVar}) AS ${sortAlias})`);
366
+ return dir === 'DESC' ? `DESC(${sortAlias})` : `ASC(${sortAlias})`;
367
+ });
368
+ if (orderTerms.length > 0) {
369
+ orderByClause = `ORDER BY ${orderTerms.join(' ')}`;
370
+ }
371
+ }
372
+
373
+ const limitClause = query.limit !== undefined ? `LIMIT ${query.limit}` : '';
374
+ const offsetClause = query.offset !== undefined && query.offset > 0 ? `OFFSET ${query.offset}` : '';
375
+
376
+ // When there's no ORDER BY, DISTINCT alone handles deduplication — no GROUP BY needed.
377
+ // When there IS ORDER BY, use GROUP BY ?source with SAMPLE() aggregates for the sort keys.
378
+ const sampleSelect = sampleProjections.length > 0 ? ' ' + sampleProjections.join(' ') : '';
379
+ const groupByClause = needsGroupBy ? 'GROUP BY ?source' : '';
380
+
381
+ return `
382
+ { SELECT DISTINCT ?source${sampleSelect} WHERE {${innerJoin}${orderJoinPatterns.join('')}
383
+ FILTER(isIRI(?source))
384
+ ${innerFilter}
385
+ } ${groupByClause} ${orderByClause} ${limitClause} ${offsetClause} }\n`;
386
+ }
387
+
388
+ /**
389
+ * Build a SPARQL COUNT query that returns the total number of matching
390
+ * instances WITHOUT hydrating them. Uses the same WHERE clause as
391
+ * buildSPARQLQuery but wraps it in SELECT (COUNT(DISTINCT ?source) AS ?count).
392
+ *
393
+ * LIMIT/OFFSET from the query are stripped internally — this always counts
394
+ * the full result set.
395
+ */
396
+ export function buildSPARQLCountQuery(
397
+ metadata: ModelMetadata,
398
+ allRelationsMetadata: Record<string, RelationMetadataEntry>,
399
+ query: Query,
400
+ modelClass: any,
401
+ ): string {
402
+ // Build the same join/filter patterns as buildSPARQLQuery
403
+ const joinPatterns: string[] = [];
404
+ const filterExpressions: string[] = [];
405
+
406
+ if (query.parent) {
407
+ const parentPredicate = resolveParentPredicate(query.parent, modelClass);
408
+ joinPatterns.push(`\n ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
409
+ }
410
+
411
+ let hasConformance = false;
412
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
413
+ if (propMeta.required) {
414
+ if (propMeta.getter) continue;
415
+ hasConformance = true;
416
+ if (propMeta.flag && propMeta.initial) {
417
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
418
+ } else {
419
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
420
+ }
421
+ }
422
+ }
423
+
424
+ if (!hasConformance) {
425
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
426
+ if (propMeta.initial) {
427
+ hasConformance = true;
428
+ if (propMeta.flag) {
429
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
430
+ } else {
431
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
432
+ }
433
+ break;
434
+ }
435
+ }
436
+ }
437
+
438
+ if (!hasConformance && joinPatterns.length === 0) {
439
+ const knownPredicates: string[] = [];
440
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
441
+ if (propMeta.predicate) knownPredicates.push(iri(propMeta.predicate));
442
+ }
443
+ if (metadata.relations) {
444
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
445
+ if (relMeta.predicate) knownPredicates.push(iri(relMeta.predicate));
446
+ }
447
+ }
448
+ if (knownPredicates.length > 0) {
449
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(", ")})) } }`);
450
+ }
451
+ }
452
+
453
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, query.where);
454
+ joinPatterns.push(...userJoins);
455
+ filterExpressions.push(...userFilters);
456
+
457
+ const joinClause = joinPatterns.join('\n');
458
+ const filterClause = filterExpressions.length > 0
459
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
460
+ : '';
461
+
462
+ return `
463
+ SELECT (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
464
+ FILTER(isIRI(?source))
465
+ ${filterClause}
466
+ }
467
+ `.trim();
468
+ }
469
+
470
+ /**
471
+ * Build a SPARQL query to fetch all links for a single instance.
472
+ */
473
+ export function buildSPARQLGetDataQuery(baseExpression: string): string {
474
+ return `
475
+ SELECT ?source ?predicate ?target ?author ?timestamp WHERE {
476
+ GRAPH ?linkGraph { ${iri(baseExpression)} ?predicate ?target . }
477
+ FILTER(isIRI(?predicate))
478
+ BIND(${iri(baseExpression)} AS ?source)
479
+ ?linkGraph <ad4m://ontology/author> ?author .
480
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
481
+ }
482
+ `.trim();
483
+ }
484
+
485
+ /**
486
+ * Group flat SPARQL link rows into the same shape that SPARQL returned:
487
+ * `{ source_uri: string, links: Array<{predicate, target, author, timestamp}> }`
488
+ */
489
+ export function groupSPARQLResults(
490
+ rows: Array<{ source: string; predicate: string; target: string; author: string; timestamp: string }>
491
+ ): Array<{ source_uri: string; links: Array<{ predicate: string; target: string; author: string; timestamp: string }> }> {
492
+ const grouped = new Map<string, { predicate: string; target: string; author: string; timestamp: string }[]>();
493
+
494
+ for (const row of rows) {
495
+ const key = row.source;
496
+ if (!grouped.has(key)) {
497
+ grouped.set(key, []);
498
+ }
499
+ grouped.get(key)!.push({
500
+ predicate: row.predicate,
501
+ target: row.target,
502
+ author: row.author,
503
+ timestamp: row.timestamp,
504
+ });
505
+ }
506
+
507
+ return Array.from(grouped.entries()).map(([source_uri, links]) => ({
508
+ source_uri,
509
+ links,
510
+ }));
511
+ }
512
+
513
+ /**
514
+ * Build SPARQL FILTER expressions from user `where` conditions.
515
+ * Uses direct triple patterns instead of link-node reification.
516
+ */
517
+ function buildSPARQLWhereFilters(
518
+ metadata: ModelMetadata,
519
+ _allRelationsMetadata: Record<string, RelationMetadataEntry>,
520
+ where?: Where,
521
+ ): { joins: string[]; filters: string[] } {
522
+ if (!where) return { joins: [], filters: [] };
523
+
524
+ const joins: string[] = [];
525
+ const filters: string[] = [];
526
+
527
+ for (const [propertyName, condition] of Object.entries(where)) {
528
+ // 'base' maps to ?source
529
+ if (propertyName === "base" || propertyName === "id") {
530
+ if (Array.isArray(condition)) {
531
+ const formatted = (condition as any[]).map(v => iri(v)).join(", ");
532
+ filters.push(`?source IN (${formatted})`);
533
+ } else if (typeof condition === "object" && condition !== null) {
534
+ const ops = condition as any;
535
+ if (ops.not !== undefined) {
536
+ if (Array.isArray(ops.not)) {
537
+ const formatted = (ops.not as any[]).map(v => iri(v)).join(", ");
538
+ filters.push(`!(?source IN (${formatted}))`);
539
+ } else {
540
+ filters.push(`?source != ${iri(ops.not)}`);
541
+ }
542
+ }
543
+ } else {
544
+ filters.push(`?source = ${iri(String(condition))}`);
545
+ }
546
+ continue;
547
+ }
548
+
549
+ if (propertyName === "author") {
550
+ // ?author is bound by the named graph block in buildSPARQLQuery /
551
+ // buildSPARQLGroupedCountQuery — push equality/IN filters into SPARQL.
552
+ if (Array.isArray(condition)) {
553
+ const formatted = (condition as any[]).map(v => formatSPARQLValue(String(v))).join(', ');
554
+ filters.push(`STR(?author) IN (${formatted})`);
555
+ } else if (typeof condition === 'object' && condition !== null) {
556
+ const ops = condition as any;
557
+ if (ops.not !== undefined) {
558
+ if (Array.isArray(ops.not)) {
559
+ const formatted = (ops.not as any[]).map((v: any) => formatSPARQLValue(String(v))).join(', ');
560
+ filters.push(`!(STR(?author) IN (${formatted}))`);
561
+ } else {
562
+ filters.push(`STR(?author) != ${formatSPARQLValue(String(ops.not))}`);
563
+ }
564
+ }
565
+ // Other operators (gt/lt/etc.) fall through to JS post-filter
566
+ } else {
567
+ filters.push(`STR(?author) = ${formatSPARQLValue(String(condition))}`);
568
+ }
569
+ continue;
570
+ }
571
+
572
+ if (propertyName === "timestamp") {
573
+ // ?timestamp is bound by the named graph block — push numeric comparisons.
574
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
575
+ const ops = condition as any;
576
+ if (ops.gt !== undefined) filters.push(`?timestamp > ${Number(ops.gt)}`);
577
+ if (ops.gte !== undefined) filters.push(`?timestamp >= ${Number(ops.gte)}`);
578
+ if (ops.lt !== undefined) filters.push(`?timestamp < ${Number(ops.lt)}`);
579
+ if (ops.lte !== undefined) filters.push(`?timestamp <= ${Number(ops.lte)}`);
580
+ if (ops.between !== undefined && Array.isArray(ops.between)) {
581
+ filters.push(`?timestamp >= ${Number(ops.between[0])} && ?timestamp <= ${Number(ops.between[1])}`);
582
+ }
583
+ if (ops.not !== undefined) {
584
+ filters.push(`?timestamp != ${Number(ops.not)}`);
585
+ }
586
+ } else if (typeof condition === 'number' || (typeof condition === 'string' && !isNaN(Number(condition)))) {
587
+ filters.push(`?timestamp = ${Number(condition)}`);
588
+ }
589
+ continue;
590
+ }
591
+
592
+ const propMeta = metadata.properties[propertyName];
593
+ if (!propMeta) continue;
594
+
595
+ // Skip reverse relations (belongsToOne / belongsToMany) — these are registered as
596
+ // read-only properties but the link direction is reversed (target→source, not source→target).
597
+ // Adding a forward join pattern would match nothing. These are filtered in JS post-filter.
598
+ const relMeta = _allRelationsMetadata[propertyName];
599
+ if (relMeta && (relMeta.kind === 'belongsToOne' || relMeta.kind === 'belongsToMany')) {
600
+ continue;
601
+ }
602
+
603
+ // Determine if this property stores values as literal: IRIs
604
+ const useParseLiteral = isLiteralStoredProperty(propMeta);
605
+
606
+ // For literal-stored properties, push equality/IN/NOT filters to SPARQL using
607
+ // <ad4m://fn/parse_literal>() which extracts the raw value from literal: IRIs.
608
+ // The correct SPARQL syntax is <ad4m://fn/parse_literal>(?var) — NOT fn::parse_literal
609
+ // (which was SurrealDB syntax that Oxigraph rejects at parse time).
610
+ // Comparison operators (gt/lt/gte/lte/between/contains) remain JS-only because
611
+ // parse_literal returns strings and numeric/date comparisons would be unreliable.
612
+ // JS post-filter in instancesFromQueryResult remains as a safety net for all cases.
613
+ if (useParseLiteral) {
614
+ if (typeof condition === "object" && condition !== null && !Array.isArray(condition)) {
615
+ const ops = condition as any;
616
+ const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
617
+ ops.lt !== undefined || ops.lte !== undefined ||
618
+ ops.between !== undefined || ops.contains !== undefined;
619
+ if (hasCompOps) {
620
+ // Comparison operators: join only, filter in JS
621
+ joins.push(`
622
+ ?source ${iri(propMeta.predicate)} ?wTarget_cmp_${propertyName} .`);
623
+ }
624
+ if (ops.not !== undefined) {
625
+ // NOT filter: push down to SPARQL
626
+ joins.push(`
627
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
628
+ if (Array.isArray(ops.not)) {
629
+ const formatted = (ops.not as any[]).map((v: any) => formatSPARQLValue(v)).join(", ");
630
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) NOT IN (${formatted})`);
631
+ } else {
632
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) != ${formatSPARQLValue(ops.not)}`);
633
+ }
634
+ }
635
+ } else if (Array.isArray(condition)) {
636
+ // IN filter: push down to SPARQL
637
+ joins.push(`
638
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
639
+ const formatted = (condition as any[]).map((v: any) => formatSPARQLValue(v)).join(", ");
640
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) IN (${formatted})`);
641
+ } else {
642
+ // Simple equality: push down to SPARQL
643
+ joins.push(`
644
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
645
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) = ${formatSPARQLValue(condition)}`);
646
+ }
647
+ } else if (Array.isArray(condition)) {
648
+ const formatted = (condition as any[]).map(v => iri(v)).join(", ");
649
+ joins.push(`
650
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
651
+ filters.push(`?wTarget_${propertyName} IN (${formatted})`);
652
+ } else if (typeof condition === "object" && condition !== null) {
653
+ const ops = condition as any;
654
+ if (ops.not !== undefined) {
655
+ if (Array.isArray(ops.not)) {
656
+ const formatted = (ops.not as any[]).map(v => iri(v)).join(", ");
657
+ filters.push(`
658
+ NOT EXISTS {
659
+ ?source ${iri(propMeta.predicate)} ?wTarget_not_${propertyName} .
660
+ FILTER(?wTarget_not_${propertyName} IN (${formatted}))
661
+ }
662
+ `);
663
+ } else {
664
+ filters.push(`
665
+ NOT EXISTS {
666
+ ?source ${iri(propMeta.predicate)} ${iri(ops.not)} .
667
+ }
668
+ `);
669
+ }
670
+ }
671
+
672
+ const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
673
+ ops.lt !== undefined || ops.lte !== undefined ||
674
+ ops.between !== undefined || ops.contains !== undefined;
675
+ if (hasCompOps) {
676
+ joins.push(`
677
+ ?source ${iri(propMeta.predicate)} ?wTarget_cmp_${propertyName} .`);
678
+ }
679
+ } else {
680
+ // Simple equality — non-literal property, use exact IRI match
681
+ joins.push(`
682
+ ?source ${iri(propMeta.predicate)} ${iri(String(condition))} .`);
683
+ }
684
+ }
685
+
686
+ return { joins, filters };
687
+ }
688
+
689
+ /**
690
+ * Parse a SPARQL COUNT result row into a number.
691
+ * Handles `row.count?.value` (RDF binding), `row.count` (direct number/string),
692
+ * NaN results, and empty/malformed results.
693
+ *
694
+ * @returns The parsed count, or `null` if the result cannot be interpreted.
695
+ */
696
+ export function parseSparqlCount(result: any[]): number | null {
697
+ if (!Array.isArray(result) || result.length === 0) return null;
698
+ const row = result[0];
699
+ const val = row.count?.value ?? row.count;
700
+ if (val === undefined || val === null) return null;
701
+ const parsed = typeof val === 'number' ? val : parseInt(String(val), 10);
702
+ return isNaN(parsed) ? null : parsed;
703
+ }
704
+
705
+ /**
706
+ * Build a SPARQL query that counts child instances grouped by parent IRI.
707
+ *
708
+ * Used by the projection Path A (`count: true`) in `hydrateRelations` to get
709
+ * per-parent counts in a single round-trip with zero instance hydration.
710
+ *
711
+ * Includes the full named graph block so that `?author` and `?timestamp` are
712
+ * bound and available for SPARQL FILTER expressions (unlike the intentionally
713
+ * minimal `buildSPARQLCountQuery` which omits them for speed).
714
+ *
715
+ * @param metadata - Model metadata for the **child** (target) class
716
+ * @param allRelationsMetadata - Relations metadata for the child class
717
+ * @param relationPredicate - The predicate linking `?parent` → `?source` (child)
718
+ * @param parentIds - IRI strings of all parent instances to count for
719
+ * @param where - Optional filter applied to child instances
720
+ */
721
+ export function buildSPARQLGroupedCountQuery(
722
+ metadata: ModelMetadata,
723
+ allRelationsMetadata: Record<string, RelationMetadataEntry>,
724
+ relationPredicate: string,
725
+ parentIds: string[],
726
+ where?: import('./types').Where,
727
+ ): string {
728
+ const joinPatterns: string[] = [];
729
+ const filterExpressions: string[] = [];
730
+
731
+ // Parent → child join and IN filter
732
+ joinPatterns.push(`\n ?parent ${iri(relationPredicate)} ?source .`);
733
+ const parentIris = parentIds.map(id => iri(id)).join(', ');
734
+ filterExpressions.push(`?parent IN (${parentIris})`);
735
+
736
+ // Conformance patterns (mirrors buildSPARQLCountQuery logic)
737
+ let hasConformance = false;
738
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
739
+ if (propMeta.required) {
740
+ if (propMeta.getter) continue;
741
+ hasConformance = true;
742
+ if (propMeta.flag && propMeta.initial) {
743
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
744
+ } else {
745
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
746
+ }
747
+ }
748
+ }
749
+
750
+ if (!hasConformance) {
751
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
752
+ if (propMeta.initial) {
753
+ hasConformance = true;
754
+ if (propMeta.flag) {
755
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
756
+ } else {
757
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
758
+ }
759
+ break;
760
+ }
761
+ }
762
+ }
763
+
764
+ if (!hasConformance && joinPatterns.length <= 1) {
765
+ // Only the parent join so far — add open-world structural matching
766
+ const knownPredicates: string[] = [];
767
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
768
+ if (propMeta.predicate) knownPredicates.push(iri(propMeta.predicate));
769
+ }
770
+ if (metadata.relations) {
771
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
772
+ if (relMeta.predicate) knownPredicates.push(iri(relMeta.predicate));
773
+ }
774
+ }
775
+ if (knownPredicates.length > 0) {
776
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(', ')})) } }`);
777
+ }
778
+ }
779
+
780
+ // User where-clause filters (including author/timestamp after the SPARQL push)
781
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, where);
782
+ joinPatterns.push(...userJoins);
783
+ filterExpressions.push(...userFilters);
784
+
785
+ const joinClause = joinPatterns.join('\n');
786
+ const filterClause = filterExpressions.length > 0
787
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
788
+ : '';
789
+
790
+ return `
791
+ SELECT ?parent (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
792
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
793
+ FILTER(isIRI(?source) && isIRI(?predicate))
794
+ ?linkGraph <ad4m://ontology/author> ?author .
795
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
796
+ ${filterClause}
797
+ }
798
+ GROUP BY ?parent
799
+ `.trim();
800
+ }
801
+
802
+ /**
803
+ * Parse the result of `buildSPARQLGroupedCountQuery` into a map from parent IRI
804
+ * to count. Missing parents (zero matches) are absent from the map — callers
805
+ * should use `map.get(id) ?? 0`.
806
+ *
807
+ * @returns Map from parentId string → count number
808
+ */
809
+ export function parseSparqlGroupedCount(result: any[]): Map<string, number> {
810
+ const out = new Map<string, number>();
811
+ if (!Array.isArray(result)) return out;
812
+ for (const row of result) {
813
+ const parentVal = row.parent?.value ?? row.parent;
814
+ const countVal = row.count?.value ?? row.count;
815
+ if (!parentVal || countVal === undefined || countVal === null) continue;
816
+ const parsed = typeof countVal === 'number' ? countVal : parseInt(String(countVal), 10);
817
+ if (!isNaN(parsed)) out.set(String(parentVal), parsed);
818
+ }
819
+ return out;
820
+ }