@coasys/ad4m 0.13.0-test-2 → 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 (54) hide show
  1. package/lib/index.cjs +1060 -147
  2. package/lib/index.js +1054 -147
  3. package/lib/src/index.d.ts +0 -1
  4. package/lib/src/index.js +0 -1
  5. package/lib/src/language/Language.d.ts +26 -214
  6. package/lib/src/language/Language.js +28 -2
  7. package/lib/src/model/Ad4mModel.d.ts +25 -1
  8. package/lib/src/model/Ad4mModel.js +139 -30
  9. package/lib/src/model/Ad4mModel.test.js +214 -32
  10. package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
  11. package/lib/src/model/ModelQueryBuilder.js +62 -18
  12. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  13. package/lib/src/model/hydration-batching.test.js +456 -0
  14. package/lib/src/model/hydration.d.ts +1 -0
  15. package/lib/src/model/hydration.js +279 -70
  16. package/lib/src/model/query-sparql.d.ts +78 -1
  17. package/lib/src/model/query-sparql.js +447 -16
  18. package/lib/src/model/query-sparql.test.d.ts +1 -0
  19. package/lib/src/model/query-sparql.test.js +495 -0
  20. package/lib/src/model/query-utils.js +4 -0
  21. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  22. package/lib/src/model/subscription-delta.test.js +180 -0
  23. package/lib/src/model/subscription-pool.js +48 -2
  24. package/lib/src/model/types.d.ts +49 -1
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
  26. package/lib/src/perspectives/PerspectiveClient.js +37 -9
  27. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  28. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  29. package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
  30. package/lib/src/perspectives/PerspectiveProxy.js +15 -0
  31. package/package.json +1 -1
  32. package/src/Ad4mClient.test.ts +56 -1
  33. package/src/index.ts +0 -1
  34. package/src/language/Language.ts +54 -275
  35. package/src/model/Ad4mModel.test.ts +222 -35
  36. package/src/model/Ad4mModel.ts +144 -30
  37. package/src/model/ModelQueryBuilder.ts +66 -18
  38. package/src/model/hydration-batching.test.ts +563 -0
  39. package/src/model/hydration.ts +249 -47
  40. package/src/model/query-sparql.test.ts +568 -0
  41. package/src/model/query-sparql.ts +473 -16
  42. package/src/model/query-utils.ts +4 -0
  43. package/src/model/subscription-delta.test.ts +207 -0
  44. package/src/model/subscription-pool.ts +50 -2
  45. package/src/model/types.ts +50 -1
  46. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  47. package/src/perspectives/PerspectiveClient.ts +36 -7
  48. package/src/perspectives/PerspectiveProxy.ts +18 -0
  49. package/lib/src/model/query-surreal.d.ts +0 -44
  50. package/lib/src/model/query-surreal.js +0 -249
  51. package/lib/src/model/surreal-utils.d.ts +0 -42
  52. package/lib/src/model/surreal-utils.js +0 -128
  53. package/src/language/LanguageContext.ts +0 -37
  54. package/tsconfig-browser.json +0 -82
@@ -16,8 +16,9 @@ import { compileWhereClause } from "./query-utils";
16
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
@@ -456,7 +457,7 @@ export async function evaluateCustomGettersForInstance(
456
457
  instance: any,
457
458
  perspective: PerspectiveProxy,
458
459
  metadata: ModelMetadata,
459
- options?: { requestedProperties?: string[]; include?: Record<string, any> }
460
+ options?: { requestedProperties?: string[]; include?: Record<string, any>; skipPropertyGetters?: boolean }
460
461
  ): Promise<void> {
461
462
  const safeBaseExpression = `<${instance.id}>`;
462
463
 
@@ -465,7 +466,8 @@ export async function evaluateCustomGettersForInstance(
465
466
  const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
466
467
  const projectionSet = projectionActive ? new Set(options!.requestedProperties) : null;
467
468
 
468
- // Evaluate property getters
469
+ // Evaluate property getters (skip when caller only wants relation type-filtering)
470
+ if (!options?.skipPropertyGetters) {
469
471
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
470
472
  if (projectionSet && !projectionSet.has(propName)) continue;
471
473
  if ((propMeta as any).getter) {
@@ -489,7 +491,8 @@ export async function evaluateCustomGettersForInstance(
489
491
  }
490
492
  }
491
493
  } else {
492
- // Legacy SurrealDB-style getter — no longer supported
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.
493
496
  console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
494
497
  }
495
498
  } catch (error) {
@@ -497,6 +500,7 @@ export async function evaluateCustomGettersForInstance(
497
500
  }
498
501
  }
499
502
  }
503
+ } // end skipPropertyGetters guard
500
504
 
501
505
  // Evaluate relation getters (explicit or auto-generated from target)
502
506
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
@@ -576,7 +580,8 @@ export async function evaluateCustomGettersForInstance(
576
580
  instance[relName] = values;
577
581
  }
578
582
  } else {
579
- // Legacy SurrealDB-style getter — no longer supported
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.
580
585
  console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
581
586
  }
582
587
  } catch (error) {
@@ -634,7 +639,160 @@ export async function hydrateRelations<T>(
634
639
 
635
640
  const relMeta = getRelationsMetadata(modelClass);
636
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) ───────────────────────────────────
637
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
+
638
796
  const meta: RelationMetadataEntry | undefined = relMeta[relName];
639
797
  if (!meta) {
640
798
  console.warn(`include: relation "${relName}" not found in metadata, skipping`);
@@ -653,17 +811,88 @@ export async function hydrateRelations<T>(
653
811
  // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
654
812
  // The link goes target→instance, so we query backwards:
655
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).
656
817
  if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
657
- // 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
658
893
  for (const inst of instances) {
659
- const reverseLinks = await perspective.get(
660
- new LinkQuery({ predicate: meta.predicate, target: (inst as any).id })
661
- );
662
- // Defensive filter: perspective.get may return extra results; ensure
663
- // we only use links that genuinely point to this instance.
664
- const sourceIds = reverseLinks
665
- .filter(l => l.data.target === (inst as any).id)
666
- .map(l => l.data.source);
894
+ const instId = (inst as any).id;
895
+ const sourceIds = sourcesByTarget.get(instId) ?? [];
667
896
 
668
897
  if (meta.kind === 'belongsToOne') {
669
898
  if (sourceIds.length === 0) {
@@ -671,42 +900,15 @@ export async function hydrateRelations<T>(
671
900
  continue;
672
901
  }
673
902
  const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
674
- try {
675
- const related = new TargetClass(perspective, sourceId);
676
- await related.get();
677
- (inst as any)[relName] = related;
678
- } catch {
679
- (inst as any)[relName] = null;
680
- }
903
+ (inst as any)[relName] = hydratedMap.get(sourceId) ?? null;
681
904
  } else {
682
905
  // belongsToMany — return array of hydrated instances
683
- let hydrated: any[] = [];
684
-
685
- // If there's a where/order sub-query, delegate to findAll for filtering
686
- if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
687
- const whereWithIds: Record<string, any> = {
688
- id: sourceIds,
689
- ...(subQuery.where ?? {}),
690
- };
691
- hydrated = await TargetClass.findAll(perspective, {
692
- where: whereWithIds as any,
693
- ...(subQuery.order && { order: subQuery.order as any }),
694
- ...(subQuery.properties && { properties: subQuery.properties }),
695
- });
696
- } else {
697
- await Promise.all(sourceIds.map(async (sid: string) => {
698
- try {
699
- const related = new TargetClass(perspective, sid);
700
- await related.get(
701
- subQuery?.properties ? { properties: subQuery.properties } : undefined
702
- );
703
- hydrated.push(related);
704
- } catch { /* skip */ }
705
- }));
706
- }
906
+ let hydrated = sourceIds
907
+ .map(sid => hydratedMap.get(sid))
908
+ .filter((v: any): v is any => v != null);
707
909
 
708
- // Apply order (client-side, if not already handled by findAll above)
709
- if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
910
+ // Apply order (client-side)
911
+ if (subQuery?.order) {
710
912
  const orderEntries = Object.entries(subQuery.order);
711
913
  hydrated = hydrated.sort((a: any, b: any) => {
712
914
  for (const [field, dir] of orderEntries) {