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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/lib/index.cjs +2377 -849
  2. package/lib/index.js +2354 -846
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +5 -1
  5. package/lib/src/agent/AgentClient.js +48 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/index.d.ts +0 -1
  8. package/lib/src/index.js +0 -1
  9. package/lib/src/language/Language.d.ts +26 -176
  10. package/lib/src/language/Language.js +28 -2
  11. package/lib/src/model/Ad4mModel.d.ts +52 -28
  12. package/lib/src/model/Ad4mModel.js +255 -118
  13. package/lib/src/model/Ad4mModel.test.js +1727 -537
  14. package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
  15. package/lib/src/model/ModelQueryBuilder.js +208 -79
  16. package/lib/src/model/Subject.js +6 -6
  17. package/lib/src/model/decorators.d.ts +14 -8
  18. package/lib/src/model/decorators.js +41 -14
  19. package/lib/src/model/hydration-batch.d.ts +34 -0
  20. package/lib/src/model/hydration-batch.js +147 -0
  21. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  22. package/lib/src/model/hydration-batching.test.js +456 -0
  23. package/lib/src/model/hydration.d.ts +4 -3
  24. package/lib/src/model/hydration.js +365 -86
  25. package/lib/src/model/index.d.ts +4 -1
  26. package/lib/src/model/index.js +4 -1
  27. package/lib/src/model/json-schema.js +2 -2
  28. package/lib/src/model/query-cache.d.ts +30 -0
  29. package/lib/src/model/query-cache.js +66 -0
  30. package/lib/src/model/query-cache.test.d.ts +1 -0
  31. package/lib/src/model/query-cache.test.js +43 -0
  32. package/lib/src/model/query-common.d.ts +1 -1
  33. package/lib/src/model/query-common.js +1 -1
  34. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  35. package/lib/src/model/query-sparql-batch.js +260 -0
  36. package/lib/src/model/query-sparql.d.ts +124 -0
  37. package/lib/src/model/query-sparql.js +767 -0
  38. package/lib/src/model/query-sparql.test.d.ts +1 -0
  39. package/lib/src/model/query-sparql.test.js +495 -0
  40. package/lib/src/model/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
  41. package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
  42. package/lib/src/model/relation-filtering.test.js +15 -15
  43. package/lib/src/model/sdna.js +1 -1
  44. package/lib/src/model/shacl-gen.js +42 -18
  45. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  46. package/lib/src/model/subscription-delta.test.js +180 -0
  47. package/lib/src/model/subscription-pool.d.ts +39 -0
  48. package/lib/src/model/subscription-pool.js +165 -0
  49. package/lib/src/model/types.d.ts +52 -4
  50. package/lib/src/model/types.js +1 -1
  51. package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
  52. package/lib/src/perspectives/PerspectiveClient.js +42 -66
  53. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  54. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  55. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -30
  56. package/lib/src/perspectives/PerspectiveProxy.js +239 -177
  57. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  58. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  59. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  60. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  61. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  62. package/lib/src/runtime/RuntimeResolver.js +56 -0
  63. package/lib/src/schema.gql +11 -1
  64. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  65. package/lib/src/shacl/SHACLFlow.js +9 -9
  66. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  67. package/lib/src/shacl/SHACLShape.js +38 -38
  68. package/lib/src/typeDefs.js +11 -1
  69. package/lib/src/utils.d.ts +6 -6
  70. package/lib/src/utils.js +6 -6
  71. package/package.json +1 -1
  72. package/src/Ad4mClient.test.ts +56 -1
  73. package/src/Literal.test.ts +10 -5
  74. package/src/Literal.ts +6 -5
  75. package/src/agent/AgentClient.ts +53 -1
  76. package/src/expression/ExpressionRef.ts +2 -2
  77. package/src/index.ts +0 -1
  78. package/src/language/Language.ts +55 -231
  79. package/src/model/Ad4mModel.test.ts +1709 -572
  80. package/src/model/Ad4mModel.ts +274 -120
  81. package/src/model/ModelQueryBuilder.ts +234 -87
  82. package/src/model/Subject.ts +6 -6
  83. package/src/model/decorators.ts +51 -22
  84. package/src/model/hydration-batch.ts +205 -0
  85. package/src/model/hydration-batching.test.ts +563 -0
  86. package/src/model/hydration.ts +349 -84
  87. package/src/model/index.ts +4 -1
  88. package/src/model/json-schema.ts +2 -2
  89. package/src/model/query-cache.test.ts +54 -0
  90. package/src/model/query-cache.ts +79 -0
  91. package/src/model/query-common.ts +1 -1
  92. package/src/model/query-sparql-batch.ts +301 -0
  93. package/src/model/query-sparql.test.ts +568 -0
  94. package/src/model/query-sparql.ts +820 -0
  95. package/src/model/{surreal-utils.ts → query-utils.ts} +44 -27
  96. package/src/model/relation-filtering.test.ts +15 -15
  97. package/src/model/sdna.ts +1 -1
  98. package/src/model/shacl-gen.ts +42 -17
  99. package/src/model/subscription-delta.test.ts +207 -0
  100. package/src/model/subscription-pool.ts +211 -0
  101. package/src/model/types.ts +53 -4
  102. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  103. package/src/perspectives/PerspectiveClient.ts +41 -68
  104. package/src/perspectives/PerspectiveProxy.ts +244 -181
  105. package/src/perspectives/PerspectiveResolver.ts +0 -8
  106. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  107. package/src/runtime/RuntimeResolver.ts +43 -0
  108. package/src/shacl/SHACLFlow.ts +9 -9
  109. package/src/shacl/SHACLShape.ts +39 -39
  110. package/src/utils.ts +6 -6
  111. package/lib/src/model/query-surreal.d.ts +0 -44
  112. package/lib/src/model/query-surreal.js +0 -249
  113. package/src/language/LanguageContext.ts +0 -37
  114. package/src/model/query-surreal.ts +0 -280
  115. package/tsconfig-browser.json +0 -82
@@ -2,7 +2,7 @@
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
  */
@@ -12,12 +12,13 @@ import { LinkQuery } from "../perspectives/LinkQuery";
12
12
  import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
13
13
  import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter } from "./decorators";
14
14
  import type { RelationMetadataEntry } from "./decorators";
15
- import { escapeSurrealString } from "../utils";
16
- import { formatSurrealValue, compileWhereClause } from "./surreal-utils";
15
+ import { compileWhereClause } from "./query-utils";
16
+ import { escapeQueryString } from "../utils";
17
17
  import type {
18
18
  PropertyMetadata, RelationMetadata, ModelMetadata,
19
- ValueTuple, WhereCondition, IncludeMap, RelationSubQuery,
19
+ ValueTuple, WhereCondition, IncludeMap, RelationSubQuery, IncludeProjection,
20
20
  } from "./types";
21
+ import { buildSPARQLGroupedCountQuery, parseSparqlGroupedCount } from "./query-sparql";
21
22
 
22
23
  // ──────────────────────────────────────────────────────────
23
24
  // Pure helpers
@@ -131,7 +132,7 @@ export async function hydratePropertyValue(
131
132
  propMeta.resolveLanguage != null &&
132
133
  propMeta.resolveLanguage !== 'literal' &&
133
134
  typeof target === 'string' &&
134
- !target.startsWith('literal://')
135
+ !target.startsWith('literal:')
135
136
  ) {
136
137
  try {
137
138
  const expression = await perspective.getExpression(target);
@@ -146,7 +147,7 @@ export async function hydratePropertyValue(
146
147
  else if (
147
148
  propMeta.resolveLanguage === 'literal' &&
148
149
  typeof target === 'string' &&
149
- target.startsWith('literal://')
150
+ target.startsWith('literal:')
150
151
  ) {
151
152
  try {
152
153
  const parsed = Literal.fromUrl(target).get();
@@ -413,11 +414,11 @@ export async function assignValuesToInstance(
413
414
  }
414
415
 
415
416
  // ──────────────────────────────────────────────────────────
416
- // SurrealQL custom getter evaluation
417
+ // SPARQL custom getter evaluation
417
418
  // ──────────────────────────────────────────────────────────
418
419
 
419
420
  /**
420
- * Builds a SurrealQL conformance getter for a relation whose `target` model
421
+ * Builds a SPARQL conformance getter for a relation whose `target` model
421
422
  * is known but no explicit `getter` string was supplied.
422
423
  *
423
424
  * The generated getter traverses outgoing links matching the relation's
@@ -429,7 +430,7 @@ export async function assignValuesToInstance(
429
430
  *
430
431
  * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
431
432
  * @param targetClass - The target model class (result of calling the `target()` thunk)
432
- * @returns A SurrealQL expression string, or `undefined` if no conformance
433
+ * @returns A SPARQL expression string, or `undefined` if no conformance
433
434
  * conditions could be derived from the target model.
434
435
  */
435
436
  export function buildConformanceGetter(
@@ -451,38 +452,55 @@ export function buildConformanceGetter(
451
452
  * For relations that declare a `target` but no explicit `getter`, a conformance
452
453
  * getter is auto-generated from the target model's metadata (unless `filter: false`).
453
454
  */
455
+
454
456
  export async function evaluateCustomGettersForInstance(
455
457
  instance: any,
456
458
  perspective: PerspectiveProxy,
457
459
  metadata: ModelMetadata,
458
- options?: { requestedProperties?: string[]; include?: Record<string, any> }
460
+ options?: { requestedProperties?: string[]; include?: Record<string, any>; skipPropertyGetters?: boolean }
459
461
  ): Promise<void> {
460
- const safeBaseExpression = formatSurrealValue(instance.id);
462
+ const safeBaseExpression = `<${instance.id}>`;
461
463
 
462
464
  // Build projection filter — when requestedProperties is active, only
463
465
  // evaluate getters for fields that are requested (or included).
464
466
  const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
465
467
  const projectionSet = projectionActive ? new Set(options!.requestedProperties) : null;
466
468
 
467
- // Evaluate property getters
469
+ // Evaluate property getters (skip when caller only wants relation type-filtering)
470
+ if (!options?.skipPropertyGetters) {
468
471
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
469
472
  if (projectionSet && !projectionSet.has(propName)) continue;
470
473
  if ((propMeta as any).getter) {
471
474
  try {
472
- // Replace 'Base' placeholder with actual base expression
473
- const query = (propMeta as any).getter.replace(/Base/g, safeBaseExpression);
474
- // Query from node table to have graph traversal context
475
- const result = await perspective.querySurrealDB(
476
- `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`
477
- );
478
- if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null && result[0].value !== 'None' && result[0].value !== '') {
479
- instance[propName] = result[0].value;
475
+ const rawGetter = (propMeta as any).getter;
476
+ const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
477
+
478
+ // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
479
+ const trimmed = getterWithBase.trim().toUpperCase();
480
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
481
+ const result = await perspective.querySparql(getterWithBase);
482
+ if (trimmed.startsWith('ASK')) {
483
+ instance[propName] = result === true || result === 'true';
484
+ } else if (result && result.length > 0) {
485
+ // Get first binding's first value
486
+ const firstRow = result[0];
487
+ const firstKey = Object.keys(firstRow)[0];
488
+ const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
489
+ if (val !== undefined && val !== null && val !== 'None' && val !== '') {
490
+ instance[propName] = val;
491
+ }
492
+ }
493
+ } else {
494
+ // Legacy SurrealDB-style getter — safety guard for getters that don't match
495
+ // SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
496
+ console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
480
497
  }
481
498
  } catch (error) {
482
499
  console.warn(`Failed to evaluate getter for ${propName}:`, error);
483
500
  }
484
501
  }
485
502
  }
503
+ } // end skipPropertyGetters guard
486
504
 
487
505
  // Evaluate relation getters (explicit or auto-generated from target)
488
506
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
@@ -492,12 +510,11 @@ export async function evaluateCustomGettersForInstance(
492
510
 
493
511
  // Determine the getter to execute:
494
512
  // 1. Explicit `getter` always wins
495
- // 2. `where` clause → compile DSL to SurrealQL getter
496
- // 3. If `target` is set and `filter !== false`, auto-generate from target metadata
513
+ // 2. If `target` is set and `filter !== false`, auto-generate conformance getter
497
514
  // BUT skip auto-generation for reverse relations (belongsToMany / belongsToOne)
498
- // because buildConformanceGetter traverses outgoing links (->link) which is
499
- // wrong for reverse relations. Their values are already populated by the
500
- // reverse link lookup in instancesFromSurrealResult / getData.
515
+ // because buildConformanceGetter traverses outgoing links which is wrong for
516
+ // reverse relations. Their values are already populated by the reverse link
517
+ // lookup in instancesFromQueryResult / getData.
501
518
  let getter = meta.getter;
502
519
  if (!getter && meta.where && meta.direction !== 'reverse') {
503
520
  try {
@@ -505,13 +522,34 @@ export async function evaluateCustomGettersForInstance(
505
522
  const targetMetadata = TargetClass
506
523
  ? (TargetClass as any).getModelMetadata?.() ?? null
507
524
  : null;
508
- const conditions = compileWhereClause(meta.where, targetMetadata);
509
- if (conditions.length > 0) {
510
- const escapedPred = escapeSurrealString(meta.predicate);
511
- getter = `(->link[WHERE predicate = '${escapedPred}'].out[WHERE ${conditions.join(' AND ')}].uri)`;
525
+
526
+ // Check if all where conditions can be SPARQL-filtered.
527
+ // literal-resolved properties store signed expressions (literal:json:{…}),
528
+ // not raw literal:string: IRIs, so SPARQL exact-match fails for them.
529
+ let allSparqlFilterable = true;
530
+ if (targetMetadata) {
531
+ for (const propName of Object.keys(meta.where)) {
532
+ if (['id', 'author', 'timestamp'].includes(propName)) continue;
533
+ const propMeta = targetMetadata.properties[propName];
534
+ if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
535
+ allSparqlFilterable = false;
536
+ break;
537
+ }
538
+ }
539
+ } else {
540
+ allSparqlFilterable = false;
541
+ }
542
+
543
+ if (allSparqlFilterable) {
544
+ const conditions = compileWhereClause(meta.where, targetMetadata);
545
+ if (conditions.length > 0) {
546
+ const escapedPredicate = escapeQueryString(meta.predicate);
547
+ getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
548
+ }
512
549
  }
550
+ // If not filterable, fall through to buildConformanceGetter + JS post-filter below
513
551
  } catch (e) {
514
- // Target metadata may not be available yet
552
+ console.warn(`[Ad4mModel] where-clause compilation failed for relation "${relName}":`, e);
515
553
  }
516
554
  }
517
555
  if (!getter && meta.target && meta.filter !== false && meta.direction !== 'reverse') {
@@ -528,23 +566,53 @@ export async function evaluateCustomGettersForInstance(
528
566
 
529
567
  if (getter) {
530
568
  try {
531
- // Replace 'Base' placeholder with actual base expression
532
- const query = getter.replace(/Base/g, safeBaseExpression);
533
- const fullQuery = `SELECT (${query}) AS value FROM node WHERE uri = ${safeBaseExpression}`;
534
- // Query from node table to have graph traversal context
535
- const result = await perspective.querySurrealDB(fullQuery);
536
-
537
- if (result && result.length > 0 && result[0].value !== undefined && result[0].value !== null) {
538
- // Filter out 'None' from relation results
539
- const value = result[0].value;
540
- instance[relName] = Array.isArray(value)
541
- ? value.filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None')
542
- : value;
569
+ const getterWithBase = getter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/\bBase\b/g, `<${instance.id}>`);
570
+ const trimmed = getterWithBase.trim().toUpperCase();
571
+
572
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
573
+ // Native SPARQL getter — execute directly
574
+ const result = await perspective.querySparql(getterWithBase);
575
+ if (result && result.length > 0) {
576
+ const values = result.map((r: any) => {
577
+ const firstKey = Object.keys(r)[0];
578
+ return r[firstKey]?.value ?? r[firstKey];
579
+ }).filter((v: any) => v !== undefined && v !== null && v !== '' && v !== 'None');
580
+ instance[relName] = values;
581
+ }
582
+ } else {
583
+ // Legacy SurrealDB-style getter — safety guard for relation getters that don't
584
+ // match SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
585
+ console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
543
586
  }
544
587
  } catch (error) {
545
588
  console.warn(`Failed to evaluate getter for ${relName}:`, error);
546
589
  }
547
590
  }
591
+
592
+ // JS post-filter for where conditions that couldn't be SPARQL-filtered
593
+ // (e.g. literal-resolved properties storing signed expressions)
594
+ const currentValues = instance[relName];
595
+ if (meta.where && Array.isArray(currentValues) && currentValues.length > 0) {
596
+ const TargetClass = meta.target?.();
597
+ if (TargetClass) {
598
+ const filtered: string[] = [];
599
+ for (const targetId of currentValues) {
600
+ try {
601
+ const inst = new (TargetClass as any)(perspective, targetId);
602
+ await inst.get();
603
+ let matches = true;
604
+ for (const [prop, expected] of Object.entries(meta.where)) {
605
+ if ((inst as any)[prop] !== expected) { matches = false; break; }
606
+ }
607
+ if (matches) filtered.push(targetId);
608
+ } catch {
609
+ // If we can't hydrate, keep the value (conservative)
610
+ filtered.push(targetId);
611
+ }
612
+ }
613
+ instance[relName] = filtered;
614
+ }
615
+ }
548
616
  }
549
617
  }
550
618
 
@@ -571,7 +639,160 @@ export async function hydrateRelations<T>(
571
639
 
572
640
  const relMeta = getRelationsMetadata(modelClass);
573
641
 
642
+ // ── Projections ($-prefixed keys) ────────────────────────────────────────
643
+ // Collect all projection entries up-front so we can batch the count queries
644
+ // together per-projection before processing. Each projection key starts
645
+ // with '$' and has a descriptor with a `from` field.
646
+ const projectionEntries: Array<[string, IncludeProjection]> = [];
647
+ for (const [key, val] of Object.entries(includeMap)) {
648
+ if (key.startsWith('$') && val !== null && typeof val === 'object' && 'from' in val) {
649
+ projectionEntries.push([key, val as IncludeProjection]);
650
+ }
651
+ }
652
+
653
+ for (const [projKey, proj] of projectionEntries) {
654
+ const sourceMeta: RelationMetadataEntry | undefined = relMeta[proj.from];
655
+ if (!sourceMeta) {
656
+ console.warn(`include projection "${projKey}": relation "${proj.from}" not found in metadata, skipping`);
657
+ for (const inst of instances) (inst as any)[projKey] = proj.count ? 0 : [];
658
+ continue;
659
+ }
660
+
661
+ const TargetClass = sourceMeta.target() as any;
662
+ const allParentIds = instances.map(inst => (inst as any).id).filter(Boolean) as string[];
663
+
664
+ if (proj.count) {
665
+ // ── Path A: grouped SPARQL COUNT ─────────────────────────────────────
666
+ // One round-trip, zero instance hydration. Returns one row per parent.
667
+ const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
668
+ const targetRelMeta = TargetClass.getAllRelationsMetadata?.() ?? {};
669
+ let countMap = new Map<string, number>();
670
+
671
+ if (targetMetadata && allParentIds.length > 0) {
672
+ try {
673
+ const sparql = buildSPARQLGroupedCountQuery(
674
+ targetMetadata,
675
+ targetRelMeta,
676
+ sourceMeta.predicate,
677
+ allParentIds,
678
+ proj.where,
679
+ );
680
+ const raw = await perspective.querySparql(sparql);
681
+ const rows = Array.isArray(raw) ? raw
682
+ : raw?.results?.bindings ?? raw?.bindings ?? [];
683
+ countMap = parseSparqlGroupedCount(rows);
684
+ } catch (e) {
685
+ console.warn(`include projection "${projKey}" count query failed, falling back to 0:`, e);
686
+ }
687
+ }
688
+
689
+ for (const inst of instances) {
690
+ (inst as any)[projKey] = countMap.get((inst as any).id) ?? 0;
691
+ }
692
+ } else {
693
+ // ── Path B: findAll + Map distribution ───────────────────────────────
694
+ // For reverse relations we don't have the child IDs on the instance,
695
+ // so fall back to a parent-scoped findAll per instance (uncommon path).
696
+ const isReverse = sourceMeta.kind === 'belongsToOne' || sourceMeta.kind === 'belongsToMany';
697
+
698
+ if (isReverse) {
699
+ // Reverse: the link goes child→parent, reuse the batched SPARQL pattern
700
+ // from the existing belongsTo path to collect source IDs per parent.
701
+ if (allParentIds.length > 0) {
702
+ const sparqlQuery = `SELECT ?source ?target WHERE {
703
+ GRAPH ?g { ?source <${sourceMeta.predicate}> ?target }
704
+ FILTER(?target IN (${allParentIds.map(id => `<${id}>`).join(', ')}))
705
+ }`;
706
+ const sourcesByTarget = new Map<string, string[]>();
707
+ try {
708
+ const raw = await perspective.querySparql(sparqlQuery);
709
+ const bindings = Array.isArray(raw) ? raw : raw?.results?.bindings ?? raw?.bindings ?? [];
710
+ for (const row of bindings) {
711
+ const source = row.source?.value ?? row.source;
712
+ const target = row.target?.value ?? row.target;
713
+ if (!source || !target) continue;
714
+ if (!sourcesByTarget.has(target)) sourcesByTarget.set(target, []);
715
+ sourcesByTarget.get(target)!.push(source);
716
+ }
717
+ } catch (e) {
718
+ console.warn(`include projection "${projKey}" reverse SPARQL failed:`, e);
719
+ }
720
+
721
+ const allSourceIds = new Set<string>();
722
+ for (const ids of sourcesByTarget.values()) for (const id of ids) allSourceIds.add(id);
723
+
724
+ const hydratedMap = new Map<string, any>();
725
+ if (allSourceIds.size > 0) {
726
+ const results = await TargetClass.findAll(perspective, {
727
+ where: { id: Array.from(allSourceIds), ...(proj.where ?? {}) },
728
+ });
729
+ for (const r of results) hydratedMap.set(r.id, r);
730
+ }
731
+
732
+ for (const inst of instances) {
733
+ const sourceIds = sourcesByTarget.get((inst as any).id) ?? [];
734
+ let resolved = sourceIds.map(id => hydratedMap.get(id)).filter((v: any): v is any => v != null);
735
+ if (proj.limit != null) {
736
+ if (proj.limit === 1) {
737
+ (inst as any)[projKey] = resolved[0] ?? null;
738
+ } else {
739
+ (inst as any)[projKey] = resolved.slice(0, proj.limit);
740
+ }
741
+ } else {
742
+ (inst as any)[projKey] = resolved;
743
+ }
744
+ }
745
+ } else {
746
+ for (const inst of instances) (inst as any)[projKey] = proj.limit === 1 ? null : [];
747
+ }
748
+ } else {
749
+ // Forward: instance[from] holds raw child URIs — collect across all parents
750
+ const uriSet = new Set<string>();
751
+ const rawCache = new Map<any, string[]>();
752
+ for (const inst of instances) {
753
+ const raw = (inst as any)[proj.from];
754
+ const uris: string[] = [];
755
+ if (Array.isArray(raw)) {
756
+ for (const v of raw) {
757
+ const id = typeof v === 'string' ? v : v?.id;
758
+ if (id) { uriSet.add(id); uris.push(id); }
759
+ }
760
+ } else if (typeof raw === 'string') {
761
+ uriSet.add(raw); uris.push(raw);
762
+ } else if (raw?.id) {
763
+ uriSet.add(raw.id); uris.push(raw.id);
764
+ }
765
+ rawCache.set(inst, uris);
766
+ }
767
+
768
+ const hydratedMap = new Map<string, any>();
769
+ if (uriSet.size > 0) {
770
+ const results = await TargetClass.findAll(perspective, {
771
+ where: { id: Array.from(uriSet), ...(proj.where ?? {}) },
772
+ });
773
+ for (const r of results) hydratedMap.set(r.id, r);
774
+ }
775
+
776
+ for (const inst of instances) {
777
+ const uris = rawCache.get(inst) ?? [];
778
+ const resolved = uris.map(id => hydratedMap.get(id)).filter((v: any): v is any => v != null);
779
+ if (proj.limit === 1) {
780
+ (inst as any)[projKey] = resolved[0] ?? null;
781
+ } else if (proj.limit != null) {
782
+ (inst as any)[projKey] = resolved.slice(0, proj.limit);
783
+ } else {
784
+ (inst as any)[projKey] = resolved;
785
+ }
786
+ }
787
+ }
788
+ }
789
+ }
790
+
791
+ // ── Standard relations (non-projected) ───────────────────────────────────
574
792
  for (const [relName, includeValue] of Object.entries(includeMap)) {
793
+ // Skip projection keys — already handled above
794
+ if (relName.startsWith('$') && typeof includeValue === 'object' && includeValue !== null && 'from' in includeValue) continue;
795
+
575
796
  const meta: RelationMetadataEntry | undefined = relMeta[relName];
576
797
  if (!meta) {
577
798
  console.warn(`include: relation "${relName}" not found in metadata, skipping`);
@@ -590,17 +811,88 @@ export async function hydrateRelations<T>(
590
811
  // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
591
812
  // The link goes target→instance, so we query backwards:
592
813
  // predicate = meta.predicate, target = inst.id → source is the related id
814
+ //
815
+ // PERF: Batch all reverse lookups into a single SPARQL query instead of
816
+ // N sequential perspective.get() calls (N+1 → 1 optimisation).
593
817
  if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
594
- // Per-instance reverse lookup (can't batch easily across instances)
818
+ const allIds = instances.map(inst => (inst as any).id).filter(Boolean);
819
+
820
+ // Batch query: find all (source, target) pairs for this predicate
821
+ // where target is one of our instance IDs
822
+ const sourcesByTarget = new Map<string, string[]>();
823
+ if (allIds.length > 0) {
824
+ const sparqlQuery = `SELECT ?source ?target WHERE {
825
+ GRAPH ?g { ?source <${meta.predicate}> ?target }
826
+ FILTER(?target IN (${allIds.map(id => `<${id}>`).join(', ')}))
827
+ }`;
828
+ try {
829
+ const sparqlResult = await perspective.querySparql(sparqlQuery);
830
+ // Parse SPARQL results — querySparql returns a flat array of row objects
831
+ // e.g. [{ source: "uri1", target: "uri2" }, ...]
832
+ const bindings = Array.isArray(sparqlResult) ? sparqlResult
833
+ : sparqlResult?.results?.bindings ?? sparqlResult?.bindings ?? [];
834
+ for (const row of bindings) {
835
+ const source = row.source?.value ?? row.source;
836
+ const target = row.target?.value ?? row.target;
837
+ if (!source || !target) continue;
838
+ if (!sourcesByTarget.has(target)) sourcesByTarget.set(target, []);
839
+ sourcesByTarget.get(target)!.push(source);
840
+ }
841
+ } catch (e) {
842
+ // Fallback: sequential queries if SPARQL fails
843
+ console.warn('Batched reverse relation SPARQL failed, falling back to sequential:', e);
844
+ for (const inst of instances) {
845
+ const reverseLinks = await perspective.get(
846
+ new LinkQuery({ predicate: meta.predicate, target: (inst as any).id })
847
+ );
848
+ const sourceIds = reverseLinks
849
+ .filter(l => l.data.target === (inst as any).id)
850
+ .map(l => l.data.source);
851
+ if (sourceIds.length > 0) {
852
+ sourcesByTarget.set((inst as any).id, sourceIds);
853
+ }
854
+ }
855
+ }
856
+ }
857
+
858
+ // Collect ALL source IDs across all instances for batch hydration
859
+ const allSourceIds = new Set<string>();
860
+ for (const ids of sourcesByTarget.values()) {
861
+ for (const id of ids) allSourceIds.add(id);
862
+ }
863
+
864
+ // Batch-hydrate all related instances at once (1 findAll instead of N)
865
+ const hydratedMap = new Map<string, any>();
866
+ if (allSourceIds.size > 0) {
867
+ const fetchQuery: any = {
868
+ where: {
869
+ id: Array.from(allSourceIds),
870
+ ...(subQuery?.where ?? {}),
871
+ },
872
+ ...(subQuery?.order && { order: subQuery.order }),
873
+ ...(subQuery?.properties && { properties: subQuery.properties }),
874
+ };
875
+ try {
876
+ const allResults = await TargetClass.findAll(perspective, fetchQuery);
877
+ for (const r of allResults) hydratedMap.set(r.id, r);
878
+ } catch {
879
+ // Fallback: hydrate individually
880
+ await Promise.all(Array.from(allSourceIds).map(async (sid) => {
881
+ try {
882
+ const related = new TargetClass(perspective, sid);
883
+ await related.get(
884
+ subQuery?.properties ? { properties: subQuery.properties } : undefined
885
+ );
886
+ hydratedMap.set(sid, related);
887
+ } catch { /* skip */ }
888
+ }));
889
+ }
890
+ }
891
+
892
+ // Assign hydrated instances to each parent
595
893
  for (const inst of instances) {
596
- const reverseLinks = await perspective.get(
597
- new LinkQuery({ predicate: meta.predicate, target: (inst as any).id })
598
- );
599
- // Defensive filter: perspective.get may return extra results; ensure
600
- // we only use links that genuinely point to this instance.
601
- const sourceIds = reverseLinks
602
- .filter(l => l.data.target === (inst as any).id)
603
- .map(l => l.data.source);
894
+ const instId = (inst as any).id;
895
+ const sourceIds = sourcesByTarget.get(instId) ?? [];
604
896
 
605
897
  if (meta.kind === 'belongsToOne') {
606
898
  if (sourceIds.length === 0) {
@@ -608,42 +900,15 @@ export async function hydrateRelations<T>(
608
900
  continue;
609
901
  }
610
902
  const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
611
- try {
612
- const related = new TargetClass(perspective, sourceId);
613
- await related.get();
614
- (inst as any)[relName] = related;
615
- } catch {
616
- (inst as any)[relName] = null;
617
- }
903
+ (inst as any)[relName] = hydratedMap.get(sourceId) ?? null;
618
904
  } else {
619
905
  // belongsToMany — return array of hydrated instances
620
- let hydrated: any[] = [];
621
-
622
- // If there's a where/order sub-query, delegate to findAll for filtering
623
- if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
624
- const whereWithIds: Record<string, any> = {
625
- id: sourceIds,
626
- ...(subQuery.where ?? {}),
627
- };
628
- hydrated = await TargetClass.findAll(perspective, {
629
- where: whereWithIds as any,
630
- ...(subQuery.order && { order: subQuery.order as any }),
631
- ...(subQuery.properties && { properties: subQuery.properties }),
632
- });
633
- } else {
634
- await Promise.all(sourceIds.map(async (sid: string) => {
635
- try {
636
- const related = new TargetClass(perspective, sid);
637
- await related.get(
638
- subQuery?.properties ? { properties: subQuery.properties } : undefined
639
- );
640
- hydrated.push(related);
641
- } catch { /* skip */ }
642
- }));
643
- }
906
+ let hydrated = sourceIds
907
+ .map(sid => hydratedMap.get(sid))
908
+ .filter((v: any): v is any => v != null);
644
909
 
645
- // Apply order (client-side, if not already handled by findAll above)
646
- if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
910
+ // Apply order (client-side)
911
+ if (subQuery?.order) {
647
912
  const orderEntries = Object.entries(subQuery.order);
648
913
  hydrated = hydrated.sort((a: any, b: any) => {
649
914
  for (const [field, dir] of orderEntries) {
@@ -14,8 +14,11 @@ export * from "./query-common";
14
14
  export * from "./query-prolog";
15
15
  export * from "./prolog-facts";
16
16
  export * from "./json-schema";
17
- export * from "./query-surreal";
17
+ export * from "./query-utils";
18
+ export * from "./query-sparql";
18
19
  export * from "./hydration";
19
20
  export * from "./ModelQueryBuilder";
20
21
  export * from "./sdna";
21
22
  export * from "./shacl-gen";
23
+ export * from "./query-cache";
24
+ export * from "./subscription-pool";
@@ -353,7 +353,7 @@ export function buildModelFromJSONSchema(
353
353
 
354
354
  // Default resolveLanguage to 'literal' for all remaining property types,
355
355
  // matching the @Property decorator behaviour. Without this, string values
356
- // stored as literal:// URLs are returned unparsed.
356
+ // stored as literal: URLs are returned unparsed.
357
357
  if (resolveLanguage === undefined || resolveLanguage === null) {
358
358
  resolveLanguage = 'literal';
359
359
  }
@@ -361,7 +361,7 @@ export function buildModelFromJSONSchema(
361
361
  // If property is required, ensure it has an initial value
362
362
  if (isRequired && !initial) {
363
363
  if (isObjectType(propertySchema)) {
364
- initial = 'literal://json:{}';
364
+ initial = 'literal:json:{}';
365
365
  } else {
366
366
  initial = "ad4m://undefined";
367
367
  }
@@ -0,0 +1,54 @@
1
+ import { getCachedResult, setCachedResult, invalidatePerspectiveCache, clearQueryCache, queryCacheSize } from './query-cache';
2
+
3
+ describe('query-cache', () => {
4
+ beforeEach(() => {
5
+ clearQueryCache();
6
+ });
7
+
8
+ describe('lazy eviction', () => {
9
+ it('should remove expired entries when setting a new one', () => {
10
+ // Insert with a very short TTL
11
+ setCachedResult('p1', 'SELECT ?x', 'result1', 1);
12
+ expect(queryCacheSize()).toBe(1);
13
+
14
+ // Wait for expiry
15
+ const start = Date.now();
16
+ while (Date.now() - start < 5) { /* busy wait 5ms */ }
17
+
18
+ // Expired entry should still be in the map (not yet evicted)
19
+ // but getCachedResult should return undefined
20
+ expect(getCachedResult('p1', 'SELECT ?x')).toBeUndefined();
21
+
22
+ // Setting a new entry should evict the expired one
23
+ setCachedResult('p2', 'SELECT ?y', 'result2', 10000);
24
+ // Only the new entry should remain
25
+ expect(queryCacheSize()).toBe(1);
26
+ expect(getCachedResult('p2', 'SELECT ?y')).toBe('result2');
27
+ });
28
+ });
29
+
30
+ describe('invalidatePerspectiveCache', () => {
31
+ it('should remove all entries for a specific perspective', () => {
32
+ setCachedResult('p1', 'query1', 'r1', 10000);
33
+ setCachedResult('p1', 'query2', 'r2', 10000);
34
+ setCachedResult('p2', 'query1', 'r3', 10000);
35
+ expect(queryCacheSize()).toBe(3);
36
+
37
+ invalidatePerspectiveCache('p1');
38
+
39
+ expect(queryCacheSize()).toBe(1);
40
+ expect(getCachedResult('p1', 'query1')).toBeUndefined();
41
+ expect(getCachedResult('p1', 'query2')).toBeUndefined();
42
+ expect(getCachedResult('p2', 'query1')).toBe('r3');
43
+ });
44
+
45
+ it('should not affect other perspectives', () => {
46
+ setCachedResult('p1', 'q', 'r1', 10000);
47
+ setCachedResult('p2', 'q', 'r2', 10000);
48
+
49
+ invalidatePerspectiveCache('p3');
50
+
51
+ expect(queryCacheSize()).toBe(2);
52
+ });
53
+ });
54
+ });