@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,15 +2,16 @@
2
2
  * hydration.ts — Instance hydration helpers extracted from Ad4mModel.
3
3
  *
4
4
  * Pure / stateless functions that populate Ad4mModel instances from
5
- * raw link arrays, Prolog tuples, or SurrealDB rows. None of these
5
+ * raw link arrays, Prolog tuples, or query results. None of these
6
6
  * functions depend on the `Ad4mModel` class at runtime — they accept
7
7
  * the instance, metadata, or perspective as explicit parameters.
8
8
  */
9
9
  import { Literal } from "../Literal";
10
10
  import { LinkQuery } from "../perspectives/LinkQuery";
11
11
  import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter } from "./decorators";
12
- import { escapeSurrealString } from "../utils";
13
- import { formatSurrealValue, compileWhereClause } from "./surreal-utils";
12
+ import { compileWhereClause } from "./query-utils";
13
+ import { escapeQueryString } from "../utils";
14
+ import { buildSPARQLGroupedCountQuery, parseSparqlGroupedCount } from "./query-sparql";
14
15
  // ──────────────────────────────────────────────────────────
15
16
  // Pure helpers
16
17
  // ──────────────────────────────────────────────────────────
@@ -102,7 +103,7 @@ export async function hydratePropertyValue(target, propMeta, perspective, expect
102
103
  if (propMeta.resolveLanguage != null &&
103
104
  propMeta.resolveLanguage !== 'literal' &&
104
105
  typeof target === 'string' &&
105
- !target.startsWith('literal://')) {
106
+ !target.startsWith('literal:')) {
106
107
  try {
107
108
  const expression = await perspective.getExpression(target);
108
109
  if (expression) {
@@ -121,7 +122,7 @@ export async function hydratePropertyValue(target, propMeta, perspective, expect
121
122
  // Literal URI parsing
122
123
  else if (propMeta.resolveLanguage === 'literal' &&
123
124
  typeof target === 'string' &&
124
- target.startsWith('literal://')) {
125
+ target.startsWith('literal:')) {
125
126
  try {
126
127
  const parsed = Literal.fromUrl(target).get();
127
128
  value = parsed.data !== undefined ? parsed.data : parsed;
@@ -355,10 +356,10 @@ export async function assignValuesToInstance(perspective, instance, values) {
355
356
  Object.assign(instance, writableProps);
356
357
  }
357
358
  // ──────────────────────────────────────────────────────────
358
- // SurrealQL custom getter evaluation
359
+ // SPARQL custom getter evaluation
359
360
  // ──────────────────────────────────────────────────────────
360
361
  /**
361
- * Builds a SurrealQL conformance getter for a relation whose `target` model
362
+ * Builds a SPARQL conformance getter for a relation whose `target` model
362
363
  * is known but no explicit `getter` string was supplied.
363
364
  *
364
365
  * The generated getter traverses outgoing links matching the relation's
@@ -370,7 +371,7 @@ export async function assignValuesToInstance(perspective, instance, values) {
370
371
  *
371
372
  * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
372
373
  * @param targetClass - The target model class (result of calling the `target()` thunk)
373
- * @returns A SurrealQL expression string, or `undefined` if no conformance
374
+ * @returns A SPARQL expression string, or `undefined` if no conformance
374
375
  * conditions could be derived from the target model.
375
376
  */
376
377
  export function buildConformanceGetter(relationPredicate, targetClass) {
@@ -389,30 +390,49 @@ export function buildConformanceGetter(relationPredicate, targetClass) {
389
390
  * getter is auto-generated from the target model's metadata (unless `filter: false`).
390
391
  */
391
392
  export async function evaluateCustomGettersForInstance(instance, perspective, metadata, options) {
392
- const safeBaseExpression = formatSurrealValue(instance.id);
393
+ const safeBaseExpression = `<${instance.id}>`;
393
394
  // Build projection filter — when requestedProperties is active, only
394
395
  // evaluate getters for fields that are requested (or included).
395
396
  const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
396
397
  const projectionSet = projectionActive ? new Set(options.requestedProperties) : null;
397
- // Evaluate property getters
398
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
399
- if (projectionSet && !projectionSet.has(propName))
400
- continue;
401
- if (propMeta.getter) {
402
- try {
403
- // Replace 'Base' placeholder with actual base expression
404
- const query = propMeta.getter.replace(/Base/g, safeBaseExpression);
405
- // Query from node table to have graph traversal context
406
- const result = await perspective.querySurrealDB(`SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`);
407
- if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
408
- instance[propName] = result[0].value;
398
+ // Evaluate property getters (skip when caller only wants relation type-filtering)
399
+ if (!options?.skipPropertyGetters) {
400
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
401
+ if (projectionSet && !projectionSet.has(propName))
402
+ continue;
403
+ if (propMeta.getter) {
404
+ try {
405
+ const rawGetter = propMeta.getter;
406
+ const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
407
+ // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
408
+ const trimmed = getterWithBase.trim().toUpperCase();
409
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
410
+ const result = await perspective.querySparql(getterWithBase);
411
+ if (trimmed.startsWith('ASK')) {
412
+ instance[propName] = result === true || result === 'true';
413
+ }
414
+ else if (result && result.length > 0) {
415
+ // Get first binding's first value
416
+ const firstRow = result[0];
417
+ const firstKey = Object.keys(firstRow)[0];
418
+ const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
419
+ if (val !== undefined && val !== null && val !== 'None' && val !== '') {
420
+ instance[propName] = val;
421
+ }
422
+ }
423
+ }
424
+ else {
425
+ // Legacy SurrealDB-style getter — safety guard for getters that don't match
426
+ // SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
427
+ console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
428
+ }
429
+ }
430
+ catch (error) {
431
+ console.warn(`Failed to evaluate getter for ${propName}:`, error);
409
432
  }
410
- }
411
- catch (error) {
412
- console.warn(`Failed to evaluate getter for ${propName}:`, error);
413
433
  }
414
434
  }
415
- }
435
+ } // end skipPropertyGetters guard
416
436
  // Evaluate relation getters (explicit or auto-generated from target)
417
437
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
418
438
  // Skip relations excluded by property projection (unless in include map)
@@ -421,12 +441,11 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
421
441
  const meta = relMeta;
422
442
  // Determine the getter to execute:
423
443
  // 1. Explicit `getter` always wins
424
- // 2. `where` clause → compile DSL to SurrealQL getter
425
- // 3. If `target` is set and `filter !== false`, auto-generate from target metadata
444
+ // 2. If `target` is set and `filter !== false`, auto-generate conformance getter
426
445
  // BUT skip auto-generation for reverse relations (belongsToMany / belongsToOne)
427
- // because buildConformanceGetter traverses outgoing links (->link) which is
428
- // wrong for reverse relations. Their values are already populated by the
429
- // reverse link lookup in instancesFromSurrealResult / getData.
446
+ // because buildConformanceGetter traverses outgoing links which is wrong for
447
+ // reverse relations. Their values are already populated by the reverse link
448
+ // lookup in instancesFromQueryResult / getData.
430
449
  let getter = meta.getter;
431
450
  if (!getter && meta.where && meta.direction !== 'reverse') {
432
451
  try {
@@ -434,14 +453,35 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
434
453
  const targetMetadata = TargetClass
435
454
  ? TargetClass.getModelMetadata?.() ?? null
436
455
  : null;
437
- const conditions = compileWhereClause(meta.where, targetMetadata);
438
- if (conditions.length > 0) {
439
- const escapedPred = escapeSurrealString(meta.predicate);
440
- getter = `(->link[WHERE predicate = '${escapedPred}'].out[WHERE ${conditions.join(' AND ')}].uri)`;
456
+ // Check if all where conditions can be SPARQL-filtered.
457
+ // literal-resolved properties store signed expressions (literal:json:{…}),
458
+ // not raw literal:string: IRIs, so SPARQL exact-match fails for them.
459
+ let allSparqlFilterable = true;
460
+ if (targetMetadata) {
461
+ for (const propName of Object.keys(meta.where)) {
462
+ if (['id', 'author', 'timestamp'].includes(propName))
463
+ continue;
464
+ const propMeta = targetMetadata.properties[propName];
465
+ if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
466
+ allSparqlFilterable = false;
467
+ break;
468
+ }
469
+ }
470
+ }
471
+ else {
472
+ allSparqlFilterable = false;
441
473
  }
474
+ if (allSparqlFilterable) {
475
+ const conditions = compileWhereClause(meta.where, targetMetadata);
476
+ if (conditions.length > 0) {
477
+ const escapedPredicate = escapeQueryString(meta.predicate);
478
+ getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
479
+ }
480
+ }
481
+ // If not filterable, fall through to buildConformanceGetter + JS post-filter below
442
482
  }
443
483
  catch (e) {
444
- // Target metadata may not be available yet
484
+ console.warn(`[Ad4mModel] where-clause compilation failed for relation "${relName}":`, e);
445
485
  }
446
486
  }
447
487
  if (!getter && meta.target && meta.filter !== false && meta.direction !== 'reverse') {
@@ -458,23 +498,58 @@ export async function evaluateCustomGettersForInstance(instance, perspective, me
458
498
  }
459
499
  if (getter) {
460
500
  try {
461
- // Replace 'Base' placeholder with actual base expression
462
- const query = getter.replace(/Base/g, safeBaseExpression);
463
- const fullQuery = `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`;
464
- // Query from node table to have graph traversal context
465
- const result = await perspective.querySurrealDB(fullQuery);
466
- if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
467
- // Filter out 'None' from relation results
468
- const value = result[0].value;
469
- instance[relName] = Array.isArray(value)
470
- ? value.filter((v) => v !== undefined && v !== null && v !== '' && v !== 'None')
471
- : value;
501
+ const getterWithBase = getter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/\bBase\b/g, `<${instance.id}>`);
502
+ const trimmed = getterWithBase.trim().toUpperCase();
503
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
504
+ // Native SPARQL getter — execute directly
505
+ const result = await perspective.querySparql(getterWithBase);
506
+ if (result && result.length > 0) {
507
+ const values = result.map((r) => {
508
+ const firstKey = Object.keys(r)[0];
509
+ return r[firstKey]?.value ?? r[firstKey];
510
+ }).filter((v) => v !== undefined && v !== null && v !== '' && v !== 'None');
511
+ instance[relName] = values;
512
+ }
513
+ }
514
+ else {
515
+ // Legacy SurrealDB-style getter — safety guard for relation getters that don't
516
+ // match SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
517
+ console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
472
518
  }
473
519
  }
474
520
  catch (error) {
475
521
  console.warn(`Failed to evaluate getter for ${relName}:`, error);
476
522
  }
477
523
  }
524
+ // JS post-filter for where conditions that couldn't be SPARQL-filtered
525
+ // (e.g. literal-resolved properties storing signed expressions)
526
+ const currentValues = instance[relName];
527
+ if (meta.where && Array.isArray(currentValues) && currentValues.length > 0) {
528
+ const TargetClass = meta.target?.();
529
+ if (TargetClass) {
530
+ const filtered = [];
531
+ for (const targetId of currentValues) {
532
+ try {
533
+ const inst = new TargetClass(perspective, targetId);
534
+ await inst.get();
535
+ let matches = true;
536
+ for (const [prop, expected] of Object.entries(meta.where)) {
537
+ if (inst[prop] !== expected) {
538
+ matches = false;
539
+ break;
540
+ }
541
+ }
542
+ if (matches)
543
+ filtered.push(targetId);
544
+ }
545
+ catch {
546
+ // If we can't hydrate, keep the value (conservative)
547
+ filtered.push(targetId);
548
+ }
549
+ }
550
+ instance[relName] = filtered;
551
+ }
552
+ }
478
553
  }
479
554
  }
480
555
  /**
@@ -494,7 +569,166 @@ export async function hydrateRelations(modelClass, instances, perspective, inclu
494
569
  if (!includeMap || Object.keys(includeMap).length === 0)
495
570
  return;
496
571
  const relMeta = getRelationsMetadata(modelClass);
572
+ // ── Projections ($-prefixed keys) ────────────────────────────────────────
573
+ // Collect all projection entries up-front so we can batch the count queries
574
+ // together per-projection before processing. Each projection key starts
575
+ // with '$' and has a descriptor with a `from` field.
576
+ const projectionEntries = [];
577
+ for (const [key, val] of Object.entries(includeMap)) {
578
+ if (key.startsWith('$') && val !== null && typeof val === 'object' && 'from' in val) {
579
+ projectionEntries.push([key, val]);
580
+ }
581
+ }
582
+ for (const [projKey, proj] of projectionEntries) {
583
+ const sourceMeta = relMeta[proj.from];
584
+ if (!sourceMeta) {
585
+ console.warn(`include projection "${projKey}": relation "${proj.from}" not found in metadata, skipping`);
586
+ for (const inst of instances)
587
+ inst[projKey] = proj.count ? 0 : [];
588
+ continue;
589
+ }
590
+ const TargetClass = sourceMeta.target();
591
+ const allParentIds = instances.map(inst => inst.id).filter(Boolean);
592
+ if (proj.count) {
593
+ // ── Path A: grouped SPARQL COUNT ─────────────────────────────────────
594
+ // One round-trip, zero instance hydration. Returns one row per parent.
595
+ const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
596
+ const targetRelMeta = TargetClass.getAllRelationsMetadata?.() ?? {};
597
+ let countMap = new Map();
598
+ if (targetMetadata && allParentIds.length > 0) {
599
+ try {
600
+ const sparql = buildSPARQLGroupedCountQuery(targetMetadata, targetRelMeta, sourceMeta.predicate, allParentIds, proj.where);
601
+ const raw = await perspective.querySparql(sparql);
602
+ const rows = Array.isArray(raw) ? raw
603
+ : raw?.results?.bindings ?? raw?.bindings ?? [];
604
+ countMap = parseSparqlGroupedCount(rows);
605
+ }
606
+ catch (e) {
607
+ console.warn(`include projection "${projKey}" count query failed, falling back to 0:`, e);
608
+ }
609
+ }
610
+ for (const inst of instances) {
611
+ inst[projKey] = countMap.get(inst.id) ?? 0;
612
+ }
613
+ }
614
+ else {
615
+ // ── Path B: findAll + Map distribution ───────────────────────────────
616
+ // For reverse relations we don't have the child IDs on the instance,
617
+ // so fall back to a parent-scoped findAll per instance (uncommon path).
618
+ const isReverse = sourceMeta.kind === 'belongsToOne' || sourceMeta.kind === 'belongsToMany';
619
+ if (isReverse) {
620
+ // Reverse: the link goes child→parent, reuse the batched SPARQL pattern
621
+ // from the existing belongsTo path to collect source IDs per parent.
622
+ if (allParentIds.length > 0) {
623
+ const sparqlQuery = `SELECT ?source ?target WHERE {
624
+ GRAPH ?g { ?source <${sourceMeta.predicate}> ?target }
625
+ FILTER(?target IN (${allParentIds.map(id => `<${id}>`).join(', ')}))
626
+ }`;
627
+ const sourcesByTarget = new Map();
628
+ try {
629
+ const raw = await perspective.querySparql(sparqlQuery);
630
+ const bindings = Array.isArray(raw) ? raw : raw?.results?.bindings ?? raw?.bindings ?? [];
631
+ for (const row of bindings) {
632
+ const source = row.source?.value ?? row.source;
633
+ const target = row.target?.value ?? row.target;
634
+ if (!source || !target)
635
+ continue;
636
+ if (!sourcesByTarget.has(target))
637
+ sourcesByTarget.set(target, []);
638
+ sourcesByTarget.get(target).push(source);
639
+ }
640
+ }
641
+ catch (e) {
642
+ console.warn(`include projection "${projKey}" reverse SPARQL failed:`, e);
643
+ }
644
+ const allSourceIds = new Set();
645
+ for (const ids of sourcesByTarget.values())
646
+ for (const id of ids)
647
+ allSourceIds.add(id);
648
+ const hydratedMap = new Map();
649
+ if (allSourceIds.size > 0) {
650
+ const results = await TargetClass.findAll(perspective, {
651
+ where: { id: Array.from(allSourceIds), ...(proj.where ?? {}) },
652
+ });
653
+ for (const r of results)
654
+ hydratedMap.set(r.id, r);
655
+ }
656
+ for (const inst of instances) {
657
+ const sourceIds = sourcesByTarget.get(inst.id) ?? [];
658
+ let resolved = sourceIds.map(id => hydratedMap.get(id)).filter((v) => v != null);
659
+ if (proj.limit != null) {
660
+ if (proj.limit === 1) {
661
+ inst[projKey] = resolved[0] ?? null;
662
+ }
663
+ else {
664
+ inst[projKey] = resolved.slice(0, proj.limit);
665
+ }
666
+ }
667
+ else {
668
+ inst[projKey] = resolved;
669
+ }
670
+ }
671
+ }
672
+ else {
673
+ for (const inst of instances)
674
+ inst[projKey] = proj.limit === 1 ? null : [];
675
+ }
676
+ }
677
+ else {
678
+ // Forward: instance[from] holds raw child URIs — collect across all parents
679
+ const uriSet = new Set();
680
+ const rawCache = new Map();
681
+ for (const inst of instances) {
682
+ const raw = inst[proj.from];
683
+ const uris = [];
684
+ if (Array.isArray(raw)) {
685
+ for (const v of raw) {
686
+ const id = typeof v === 'string' ? v : v?.id;
687
+ if (id) {
688
+ uriSet.add(id);
689
+ uris.push(id);
690
+ }
691
+ }
692
+ }
693
+ else if (typeof raw === 'string') {
694
+ uriSet.add(raw);
695
+ uris.push(raw);
696
+ }
697
+ else if (raw?.id) {
698
+ uriSet.add(raw.id);
699
+ uris.push(raw.id);
700
+ }
701
+ rawCache.set(inst, uris);
702
+ }
703
+ const hydratedMap = new Map();
704
+ if (uriSet.size > 0) {
705
+ const results = await TargetClass.findAll(perspective, {
706
+ where: { id: Array.from(uriSet), ...(proj.where ?? {}) },
707
+ });
708
+ for (const r of results)
709
+ hydratedMap.set(r.id, r);
710
+ }
711
+ for (const inst of instances) {
712
+ const uris = rawCache.get(inst) ?? [];
713
+ const resolved = uris.map(id => hydratedMap.get(id)).filter((v) => v != null);
714
+ if (proj.limit === 1) {
715
+ inst[projKey] = resolved[0] ?? null;
716
+ }
717
+ else if (proj.limit != null) {
718
+ inst[projKey] = resolved.slice(0, proj.limit);
719
+ }
720
+ else {
721
+ inst[projKey] = resolved;
722
+ }
723
+ }
724
+ }
725
+ }
726
+ }
727
+ // ── Standard relations (non-projected) ───────────────────────────────────
497
728
  for (const [relName, includeValue] of Object.entries(includeMap)) {
729
+ // Skip projection keys — already handled above
730
+ if (relName.startsWith('$') && typeof includeValue === 'object' && includeValue !== null && 'from' in includeValue)
731
+ continue;
498
732
  const meta = relMeta[relName];
499
733
  if (!meta) {
500
734
  console.warn(`include: relation "${relName}" not found in metadata, skipping`);
@@ -509,57 +743,102 @@ export async function hydrateRelations(modelClass, instances, perspective, inclu
509
743
  // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
510
744
  // The link goes target→instance, so we query backwards:
511
745
  // predicate = meta.predicate, target = inst.id → source is the related id
746
+ //
747
+ // PERF: Batch all reverse lookups into a single SPARQL query instead of
748
+ // N sequential perspective.get() calls (N+1 → 1 optimisation).
512
749
  if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
513
- // Per-instance reverse lookup (can't batch easily across instances)
750
+ const allIds = instances.map(inst => inst.id).filter(Boolean);
751
+ // Batch query: find all (source, target) pairs for this predicate
752
+ // where target is one of our instance IDs
753
+ const sourcesByTarget = new Map();
754
+ if (allIds.length > 0) {
755
+ const sparqlQuery = `SELECT ?source ?target WHERE {
756
+ GRAPH ?g { ?source <${meta.predicate}> ?target }
757
+ FILTER(?target IN (${allIds.map(id => `<${id}>`).join(', ')}))
758
+ }`;
759
+ try {
760
+ const sparqlResult = await perspective.querySparql(sparqlQuery);
761
+ // Parse SPARQL results — querySparql returns a flat array of row objects
762
+ // e.g. [{ source: "uri1", target: "uri2" }, ...]
763
+ const bindings = Array.isArray(sparqlResult) ? sparqlResult
764
+ : sparqlResult?.results?.bindings ?? sparqlResult?.bindings ?? [];
765
+ for (const row of bindings) {
766
+ const source = row.source?.value ?? row.source;
767
+ const target = row.target?.value ?? row.target;
768
+ if (!source || !target)
769
+ continue;
770
+ if (!sourcesByTarget.has(target))
771
+ sourcesByTarget.set(target, []);
772
+ sourcesByTarget.get(target).push(source);
773
+ }
774
+ }
775
+ catch (e) {
776
+ // Fallback: sequential queries if SPARQL fails
777
+ console.warn('Batched reverse relation SPARQL failed, falling back to sequential:', e);
778
+ for (const inst of instances) {
779
+ const reverseLinks = await perspective.get(new LinkQuery({ predicate: meta.predicate, target: inst.id }));
780
+ const sourceIds = reverseLinks
781
+ .filter(l => l.data.target === inst.id)
782
+ .map(l => l.data.source);
783
+ if (sourceIds.length > 0) {
784
+ sourcesByTarget.set(inst.id, sourceIds);
785
+ }
786
+ }
787
+ }
788
+ }
789
+ // Collect ALL source IDs across all instances for batch hydration
790
+ const allSourceIds = new Set();
791
+ for (const ids of sourcesByTarget.values()) {
792
+ for (const id of ids)
793
+ allSourceIds.add(id);
794
+ }
795
+ // Batch-hydrate all related instances at once (1 findAll instead of N)
796
+ const hydratedMap = new Map();
797
+ if (allSourceIds.size > 0) {
798
+ const fetchQuery = {
799
+ where: {
800
+ id: Array.from(allSourceIds),
801
+ ...(subQuery?.where ?? {}),
802
+ },
803
+ ...(subQuery?.order && { order: subQuery.order }),
804
+ ...(subQuery?.properties && { properties: subQuery.properties }),
805
+ };
806
+ try {
807
+ const allResults = await TargetClass.findAll(perspective, fetchQuery);
808
+ for (const r of allResults)
809
+ hydratedMap.set(r.id, r);
810
+ }
811
+ catch {
812
+ // Fallback: hydrate individually
813
+ await Promise.all(Array.from(allSourceIds).map(async (sid) => {
814
+ try {
815
+ const related = new TargetClass(perspective, sid);
816
+ await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
817
+ hydratedMap.set(sid, related);
818
+ }
819
+ catch { /* skip */ }
820
+ }));
821
+ }
822
+ }
823
+ // Assign hydrated instances to each parent
514
824
  for (const inst of instances) {
515
- const reverseLinks = await perspective.get(new LinkQuery({ predicate: meta.predicate, target: inst.id }));
516
- // Defensive filter: perspective.get may return extra results; ensure
517
- // we only use links that genuinely point to this instance.
518
- const sourceIds = reverseLinks
519
- .filter(l => l.data.target === inst.id)
520
- .map(l => l.data.source);
825
+ const instId = inst.id;
826
+ const sourceIds = sourcesByTarget.get(instId) ?? [];
521
827
  if (meta.kind === 'belongsToOne') {
522
828
  if (sourceIds.length === 0) {
523
829
  inst[relName] = null;
524
830
  continue;
525
831
  }
526
832
  const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
527
- try {
528
- const related = new TargetClass(perspective, sourceId);
529
- await related.get();
530
- inst[relName] = related;
531
- }
532
- catch {
533
- inst[relName] = null;
534
- }
833
+ inst[relName] = hydratedMap.get(sourceId) ?? null;
535
834
  }
536
835
  else {
537
836
  // belongsToMany — return array of hydrated instances
538
- let hydrated = [];
539
- // If there's a where/order sub-query, delegate to findAll for filtering
540
- if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
541
- const whereWithIds = {
542
- id: sourceIds,
543
- ...(subQuery.where ?? {}),
544
- };
545
- hydrated = await TargetClass.findAll(perspective, {
546
- where: whereWithIds,
547
- ...(subQuery.order && { order: subQuery.order }),
548
- ...(subQuery.properties && { properties: subQuery.properties }),
549
- });
550
- }
551
- else {
552
- await Promise.all(sourceIds.map(async (sid) => {
553
- try {
554
- const related = new TargetClass(perspective, sid);
555
- await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
556
- hydrated.push(related);
557
- }
558
- catch { /* skip */ }
559
- }));
560
- }
561
- // Apply order (client-side, if not already handled by findAll above)
562
- if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
837
+ let hydrated = sourceIds
838
+ .map(sid => hydratedMap.get(sid))
839
+ .filter((v) => v != null);
840
+ // Apply order (client-side)
841
+ if (subQuery?.order) {
563
842
  const orderEntries = Object.entries(subQuery.order);
564
843
  hydrated = hydrated.sort((a, b) => {
565
844
  for (const [field, dir] of orderEntries) {
@@ -13,8 +13,11 @@ export * from "./query-common";
13
13
  export * from "./query-prolog";
14
14
  export * from "./prolog-facts";
15
15
  export * from "./json-schema";
16
- export * from "./query-surreal";
16
+ export * from "./query-utils";
17
+ export * from "./query-sparql";
17
18
  export * from "./hydration";
18
19
  export * from "./ModelQueryBuilder";
19
20
  export * from "./sdna";
20
21
  export * from "./shacl-gen";
22
+ export * from "./query-cache";
23
+ export * from "./subscription-pool";
@@ -13,8 +13,11 @@ export * from "./query-common";
13
13
  export * from "./query-prolog";
14
14
  export * from "./prolog-facts";
15
15
  export * from "./json-schema";
16
- export * from "./query-surreal";
16
+ export * from "./query-utils";
17
+ export * from "./query-sparql";
17
18
  export * from "./hydration";
18
19
  export * from "./ModelQueryBuilder";
19
20
  export * from "./sdna";
20
21
  export * from "./shacl-gen";
22
+ export * from "./query-cache";
23
+ export * from "./subscription-pool";
@@ -263,14 +263,14 @@ export function buildModelFromJSONSchema(BaseClass, schema, options) {
263
263
  }
264
264
  // Default resolveLanguage to 'literal' for all remaining property types,
265
265
  // matching the @Property decorator behaviour. Without this, string values
266
- // stored as literal:// URLs are returned unparsed.
266
+ // stored as literal: URLs are returned unparsed.
267
267
  if (resolveLanguage === undefined || resolveLanguage === null) {
268
268
  resolveLanguage = 'literal';
269
269
  }
270
270
  // If property is required, ensure it has an initial value
271
271
  if (isRequired && !initial) {
272
272
  if (isObjectType(propertySchema)) {
273
- initial = 'literal://json:{}';
273
+ initial = 'literal:json:{}';
274
274
  }
275
275
  else {
276
276
  initial = "ad4m://undefined";
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Query Result TTL Cache
3
+ *
4
+ * Short-lived cache (200ms TTL) for SPARQL query results.
5
+ * Prevents redundant queries during rapid render cycles where
6
+ * multiple components issue the same query within milliseconds.
7
+ *
8
+ * Key: `perspectiveUUID + queryText`
9
+ */
10
+ /**
11
+ * Get a cached query result if it exists and hasn't expired.
12
+ */
13
+ export declare function getCachedResult(perspectiveUUID: string, queryText: string): any | undefined;
14
+ /**
15
+ * Store a query result in the cache with TTL.
16
+ */
17
+ export declare function setCachedResult(perspectiveUUID: string, queryText: string, result: any, ttlMs?: number): void;
18
+ /**
19
+ * Invalidate all cache entries for a given perspective.
20
+ * Called after write operations to ensure stale data isn't served.
21
+ */
22
+ export declare function invalidatePerspectiveCache(perspectiveUUID: string): void;
23
+ /**
24
+ * Clear all cache entries (useful for testing).
25
+ */
26
+ export declare function clearQueryCache(): void;
27
+ /**
28
+ * Get the current size of the cache (useful for testing).
29
+ */
30
+ export declare function queryCacheSize(): number;