@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
@@ -5,12 +5,15 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
5
5
  import { makeRandomId } from "./util";
6
6
  import { getPropertiesMetadata, getRelationsMetadata } from "./decorators";
7
7
  import type { PropertyOptions, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
8
- import { formatSurrealValue } from "./surreal-utils";
8
+ import { formatQueryValue } from "./query-utils";
9
9
  import { resolveParentPredicate } from "./query-common";
10
10
  import { buildParentQuery, buildAuthorAndTimestampQuery, buildPropertiesQuery, buildWhereQuery, buildCountQuery, buildOrderQuery, buildOffsetQuery, buildLimitQuery } from "./query-prolog";
11
11
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
12
12
  import type { JSONSchemaProperty, JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
13
- import { buildSurrealQLQuery } from "./query-surreal";
13
+
14
+ import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults, buildSPARQLCountQuery, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
15
+ import { buildBatchSPARQLQuery } from "./query-sparql-batch";
16
+ import { hydrateBatchResult } from "./hydration-batch";
14
17
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
15
18
  import {
16
19
  normalizeValue, matchesCondition, hydrateFromLinks,
@@ -341,7 +344,7 @@ export class Ad4mModel {
341
344
  * const recipe = new Recipe(perspective);
342
345
  *
343
346
  * // Create with specific base expression
344
- * const recipe = new Recipe(perspective, "literal://...");
347
+ * const recipe = new Recipe(perspective, "literal:...");
345
348
  * ```
346
349
  */
347
350
  constructor(perspective: PerspectiveProxy, baseExpression?: string) {
@@ -601,20 +604,14 @@ export class Ad4mModel {
601
604
 
602
605
  private async getData(opts?: GetOptions) {
603
606
  // Builds an object with the author, timestamp, all properties, & all relations on the Ad4mModel and saves it to the instance
604
- // Use SurrealDB for data queries
607
+ // Use SPARQL for data queries
605
608
  try {
606
609
  const ctor = this.constructor as typeof Ad4mModel;
607
610
  const metadata = ctor.getModelMetadata();
608
611
 
609
612
  // Query for all links from this specific node (base expression)
610
- const safeBaseExpression = formatSurrealValue(this._baseExpression);
611
- const linksQuery = `
612
- SELECT id, predicate, out.uri AS target, author, timestamp
613
- FROM link
614
- WHERE in.uri = ${safeBaseExpression}
615
- ORDER BY timestamp ASC
616
- `;
617
- const links = await this._perspective.querySurrealDB(linksQuery);
613
+ const linksQuery = buildSPARQLGetDataQuery(this._baseExpression);
614
+ const links = await this._perspective.querySparql(linksQuery);
618
615
 
619
616
  if (links && links.length > 0) {
620
617
  // Core hydration: properties (latest-wins), relations, timestamps/author
@@ -641,7 +638,7 @@ export class Ad4mModel {
641
638
  }
642
639
  }
643
640
 
644
- // Evaluate SurrealQL getters
641
+ // Evaluate SPARQL getters
645
642
  const getterOpts = opts?.properties || opts?.include
646
643
  ? { requestedProperties: opts?.properties, include: opts?.include }
647
644
  : undefined;
@@ -652,7 +649,7 @@ export class Ad4mModel {
652
649
  await hydrateRelations(ctor, [this], this._perspective, opts.include);
653
650
  }
654
651
  } catch (e) {
655
- console.error(`SurrealDB getData also failed for ${this._baseExpression}:`, e);
652
+ console.error(`SPARQL getData also failed for ${this._baseExpression}:`, e);
656
653
  }
657
654
 
658
655
  this.takeSnapshot();
@@ -690,13 +687,13 @@ export class Ad4mModel {
690
687
  }
691
688
 
692
689
  /**
693
- * Generates a SurrealQL query from a Query object.
690
+ * Generates a SPARQL query from a Query object.
694
691
  *
695
692
  * @description
696
- * This method translates high-level query parameters into a SurrealQL query string
697
- * that can be executed against the SurrealDB backend. Unlike Prolog queries which
698
- * operate on SDNA-aware predicates, SurrealQL queries operate directly on raw links
699
- * stored in SurrealDB.
693
+ * This method translates high-level query parameters into a SPARQL query string
694
+ * that can be executed against the SPARQL backend. Unlike Prolog queries which
695
+ * operate on SDNA-aware predicates, SPARQL queries operate directly on raw links
696
+ * stored in SPARQL.
700
697
  *
701
698
  * The generated query uses a CTE (Common Table Expression) pattern:
702
699
  * 1. First, identify candidate base expressions by filtering links based on where conditions
@@ -704,7 +701,7 @@ export class Ad4mModel {
704
701
  * 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
705
702
  *
706
703
  * Key architectural notes:
707
- * - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
704
+ * - SPARQL stores only raw links (source, predicate, target, author, timestamp)
708
705
  * - No SDNA knowledge at the database level
709
706
  * - Properties are resolved via subqueries that look for links with specific predicates
710
707
  * - Relations are similar but return multiple values instead of one
@@ -712,11 +709,11 @@ export class Ad4mModel {
712
709
  *
713
710
  * @param perspective - The perspective to query (used for metadata extraction)
714
711
  * @param query - Query parameters (where, order, limit, offset, properties, relations)
715
- * @returns Complete SurrealQL query string ready for execution
712
+ * @returns Complete SPARQL query string ready for execution
716
713
  *
717
714
  * @example
718
715
  * ```typescript
719
- * const query = Recipe.queryToSurrealQL(perspective, {
716
+ * const query = Recipe.queryToSPARQL(perspective, {
720
717
  * where: { name: "Pasta", rating: { gt: 4 } },
721
718
  * order: { timestamp: "DESC" },
722
719
  * limit: 10
@@ -725,10 +722,10 @@ export class Ad4mModel {
725
722
  * // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
726
723
  * ```
727
724
  */
728
- public static async queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
725
+ public static async queryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
729
726
  const metadata = this.getModelMetadata();
730
727
  const allRelMeta = getRelationsMetadata(this as any);
731
- return buildSurrealQLQuery(metadata, allRelMeta, query, this);
728
+ return buildSPARQLQuery(metadata, allRelMeta, query, this);
732
729
  }
733
730
 
734
731
  public static async instancesFromPrologResult<T extends Ad4mModel>(
@@ -783,20 +780,21 @@ export class Ad4mModel {
783
780
  }
784
781
 
785
782
  /**
786
- * Converts SurrealDB query results to Ad4mModel instances.
783
+ * Converts SPARQL query results to Ad4mModel instances.
787
784
  *
788
785
  * @param perspective - The perspective context
789
786
  * @param query - The query parameters used
790
- * @param result - Array of result objects from SurrealDB
787
+ * @param result - Array of result objects from SPARQL
791
788
  * @returns Promise resolving to results with total count
792
789
  *
793
790
  * @internal
794
791
  */
795
- public static async instancesFromSurrealResult<T extends Ad4mModel>(
792
+ public static async instancesFromQueryResult<T extends Ad4mModel>(
796
793
  this: typeof Ad4mModel & (new (...args: any[]) => T),
797
794
  perspective: PerspectiveProxy,
798
795
  query: Query,
799
- result: any[]
796
+ result: any[],
797
+ computeTotalCount: boolean = false
800
798
  ): Promise<ResultsWithTotalCount<T>> {
801
799
  if (!result || result.length === 0) return { results: [], totalCount: 0 };
802
800
 
@@ -824,34 +822,26 @@ export class Ad4mModel {
824
822
 
825
823
  const instance = new this(perspective, base) as any;
826
824
 
827
- // Core hydration via unified helper (pass requestedProperties for sparse fieldset)
828
- await hydrateFromLinks(instance, links, metadata, perspective, requestedProperties.length > 0 ? requestedProperties : undefined);
829
-
830
- // When specific properties are requested, delete unrequested properties
831
- // so they return undefined instead of their constructor defaults (e.g. 0, [])
832
- if (requestedProperties.length > 0) {
833
- const requested = new Set(requestedProperties);
834
- for (const propName of Object.keys(metadata.properties)) {
835
- if (!requested.has(propName)) {
836
- delete instance[propName];
837
- }
838
- }
839
- for (const relName of Object.keys(metadata.relations)) {
840
- if (!requested.has(relName) && !(query.include && relName in query.include)) {
841
- delete instance[relName];
842
- }
843
- }
844
- // Also strip metadata fields unless explicitly requested
845
- for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
846
- if (!requested.has(metaField)) {
847
- delete instance[metaField];
825
+ // Core hydration via unified helper (pass requestedProperties for sparse fieldset).
826
+ // Also hydrate any properties referenced in `where` so the JS post-filter can match them,
827
+ // even if they're not in the user's `properties` projection.
828
+ let hydrationProps = requestedProperties.length > 0 ? [...requestedProperties] : undefined;
829
+ if (hydrationProps && query.where) {
830
+ for (const key of Object.keys(query.where)) {
831
+ if (!hydrationProps.includes(key)) {
832
+ hydrationProps.push(key);
848
833
  }
849
834
  }
850
835
  }
836
+ await hydrateFromLinks(instance, links, metadata, perspective, hydrationProps);
837
+
838
+ // NOTE: Property deletion for sparse fieldsets is deferred until AFTER
839
+ // where-filtering so that where conditions can reference any property,
840
+ // even ones not in the `properties` projection.
851
841
 
852
842
  instances.push(instance);
853
843
  } catch (error) {
854
- console.error(`Failed to process SurrealDB instance ${base}:`, error);
844
+ console.error(`Failed to process SPARQL instance ${base}:`, error);
855
845
  }
856
846
  }
857
847
 
@@ -885,25 +875,47 @@ export class Ad4mModel {
885
875
  );
886
876
  }
887
877
 
888
- // Evaluate custom getters for all instances (single pass)
889
- const getterOpts = requestedProperties.length > 0 || query.include
890
- ? { requestedProperties, include: query.include }
891
- : undefined;
892
- for (const instance of instances) {
893
- await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
878
+ // Evaluate custom getters for all instances.
879
+ // Relation getters (type-conformance filtering) always run — they ensure
880
+ // correctness of @HasMany/@HasOne targets. Property getters only run when
881
+ // deepQuery is true or when where conditions reference getter-backed properties.
882
+ const whereGetterProperties = query.where
883
+ ? Object.keys(query.where).filter((propName) => (metadata.properties[propName] as any)?.getter)
884
+ : [];
885
+ const shouldEvaluatePropertyGetters = query.deepQuery === true || whereGetterProperties.length > 0;
886
+ {
887
+ const skipPropertyGetters = !shouldEvaluatePropertyGetters;
888
+ const getterRequestedProperties = shouldEvaluatePropertyGetters
889
+ ? (requestedProperties.length > 0
890
+ ? Array.from(new Set([...requestedProperties, ...whereGetterProperties]))
891
+ : query.deepQuery === true
892
+ ? [] // deepQuery: evaluate all getters
893
+ : whereGetterProperties) // only evaluate where-referenced getters
894
+ : [];
895
+ const getterOpts = {
896
+ ...(getterRequestedProperties.length > 0 && { requestedProperties: getterRequestedProperties }),
897
+ ...(query.include && { include: query.include }),
898
+ skipPropertyGetters,
899
+ };
900
+ for (const instance of instances) {
901
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
902
+ }
894
903
  }
895
904
 
896
- // Filter by where conditions that couldn't be filtered in SQL
905
+ // Filter by where conditions that couldn't be filtered in SPARQL
897
906
  // This includes:
898
907
  // - author/timestamp (computed from grouped links)
899
908
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
900
- // because fn::parse_literal() comparisons in SurrealDB subqueries don't work reliably
909
+ // because <ad4m://fn/parse_literal>() returns strings, making numeric/date
910
+ // comparisons unreliable. Equality, IN, and NOT are pushed to SPARQL.
911
+ // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
912
+ // which require reverse-link resolution before filtering
901
913
  let filteredInstances = instances;
902
914
  if (query.where) {
903
915
  filteredInstances = instances.filter(instance => {
904
916
  for (const [propertyName, condition] of Object.entries(query.where!)) {
905
- // Skip 'base' as it's filtered in SQL
906
- if (propertyName === 'base') continue;
917
+ // Skip 'base'/'id' as it's filtered in SPARQL
918
+ if (propertyName === 'base' || propertyName === 'id') continue;
907
919
 
908
920
  // For author and timestamp, always filter in JS
909
921
  if (propertyName === 'author' || propertyName === 'timestamp') {
@@ -913,19 +925,22 @@ export class Ad4mModel {
913
925
  continue;
914
926
  }
915
927
 
916
- // For regular properties, only filter comparison operators in JS
917
- // Simple equality and NOT are handled in SQL, but gt/gte/lt/lte/between/contains need JS
918
- if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
919
- const ops = condition as any;
920
- // Check if any comparison operators are present
921
- const hasComparisonOps = ops.gt !== undefined || ops.gte !== undefined ||
922
- ops.lt !== undefined || ops.lte !== undefined ||
923
- ops.between !== undefined || ops.contains !== undefined;
924
- if (hasComparisonOps) {
925
- if (!matchesCondition(instance[propertyName], condition)) {
926
- return false;
927
- }
928
+ // Check if this is a relation field (not in properties metadata)
929
+ const isPropField = propertyName in metadata.properties;
930
+
931
+ if (!isPropField) {
932
+ // Relation-based where — filter in JS against the populated field
933
+ if (!matchesCondition(instance[propertyName], condition)) {
934
+ return false;
928
935
  }
936
+ continue;
937
+ }
938
+
939
+ // Filter ALL property conditions in JS (safety net).
940
+ // Equality/IN/NOT are also filtered in SPARQL via <ad4m://fn/parse_literal>()
941
+ // but JS re-validates after hydration resolves values.
942
+ if (!matchesCondition(instance[propertyName], condition)) {
943
+ return false;
929
944
  }
930
945
  }
931
946
  return true;
@@ -936,7 +951,7 @@ export class Ad4mModel {
936
951
  // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
937
952
  // This ensures consistent pagination behavior
938
953
  const effectiveOrder = query.order ||
939
- (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' as 'ASC' } : null);
954
+ (query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' as 'ASC' } : null);
940
955
 
941
956
  if (effectiveOrder) {
942
957
  const orderEntries = Object.entries(effectiveOrder);
@@ -970,17 +985,65 @@ export class Ad4mModel {
970
985
  });
971
986
  }
972
987
 
973
- // Calculate totalCount BEFORE applying limit/offset
974
- const totalCount = filteredInstances.length;
988
+ // Determine if SPARQL already applied LIMIT/OFFSET (i.e., the pagination
989
+ // subquery was used). When it was, skip JS-level slicing — instances are
990
+ // already the correct page.
991
+ const allRelsMeta2 = getRelationsMetadata(this as any);
992
+ const sparqlPaginated = !hasJsOnlyWhereFilters(metadata, allRelsMeta2, query.where)
993
+ && (query.limit !== undefined || query.offset !== undefined)
994
+ && query.order !== undefined && Object.keys(query.order).length > 0;
995
+
996
+ // Calculate totalCount BEFORE applying limit/offset.
997
+ // When SPARQL already paginated, filteredInstances.length is the page size,
998
+ // not the total — use a separate COUNT query for the real total.
999
+ // Only run the COUNT query when the caller actually needs it (computeTotalCount=true).
1000
+ let totalCount: number;
1001
+ if (sparqlPaginated && computeTotalCount) {
1002
+ try {
1003
+ const countSparql = buildSPARQLCountQuery(metadata, allRelsMeta2, query, this);
1004
+ const countResult = await perspective.querySparql(countSparql);
1005
+ totalCount = parseSparqlCount(countResult) ?? filteredInstances.length;
1006
+ } catch {
1007
+ // Fallback: if count query fails, use what we have
1008
+ totalCount = filteredInstances.length;
1009
+ }
1010
+ } else {
1011
+ totalCount = filteredInstances.length;
1012
+ }
975
1013
 
976
- // Apply offset and limit in JavaScript
1014
+ // Apply offset and limit in JavaScript only when SPARQL didn't already paginate.
1015
+ // Subscription queries use unpaginated SPARQL, so JS must apply pagination.
1016
+ // Direct queries use SPARQL-level pagination, so JS slicing would double-apply.
977
1017
  let paginatedInstances = filteredInstances;
978
- if (query.offset !== undefined || query.limit !== undefined) {
1018
+ if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
979
1019
  const start = query.offset || 0;
980
1020
  const end = query.limit ? start + query.limit : undefined;
981
1021
  paginatedInstances = filteredInstances.slice(start, end);
982
1022
  }
983
1023
 
1024
+ // Now that where-filtering is done, strip unrequested properties for sparse fieldsets.
1025
+ // This must happen AFTER where-filtering so conditions can reference any property.
1026
+ if (requestedProperties.length > 0) {
1027
+ const requested = new Set(requestedProperties);
1028
+ for (const inst of paginatedInstances) {
1029
+ for (const propName of Object.keys(metadata.properties)) {
1030
+ if (!requested.has(propName)) {
1031
+ delete (inst as any)[propName];
1032
+ }
1033
+ }
1034
+ for (const relName of Object.keys(metadata.relations)) {
1035
+ if (!requested.has(relName) && !(query.include && relName in query.include)) {
1036
+ delete (inst as any)[relName];
1037
+ }
1038
+ }
1039
+ for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
1040
+ if (!requested.has(metaField)) {
1041
+ delete (inst as any)[metaField];
1042
+ }
1043
+ }
1044
+ }
1045
+ }
1046
+
984
1047
  // Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
985
1048
  if (query.include && paginatedInstances.length > 0) {
986
1049
  await hydrateRelations(this, paginatedInstances, perspective, query.include);
@@ -1008,15 +1071,15 @@ export class Ad4mModel {
1008
1071
  *
1009
1072
  * @param perspective - The perspective to search in
1010
1073
  * @param query - Optional query parameters to filter results
1011
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1074
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
1012
1075
  * @returns Array of matching models
1013
1076
  *
1014
1077
  * @example
1015
1078
  * ```typescript
1016
- * // Get all recipes (uses SurrealDB by default)
1079
+ * // Get all recipes (uses SPARQL by default)
1017
1080
  * const allRecipes = await Recipe.findAll(perspective);
1018
1081
  *
1019
- * // Get recipes with specific criteria (uses SurrealDB)
1082
+ * // Get recipes with specific criteria (uses SPARQL)
1020
1083
  * const recipes = await Recipe.findAll(perspective, {
1021
1084
  * where: {
1022
1085
  * name: "Pasta",
@@ -1034,15 +1097,26 @@ export class Ad4mModel {
1034
1097
  this: typeof Ad4mModel & (new (...args: any[]) => T),
1035
1098
  perspective: PerspectiveProxy,
1036
1099
  query: Query = {},
1037
- useSurrealDB: boolean = true
1100
+ engine: 'sparql' | 'prolog' | boolean = 'sparql'
1038
1101
  ): Promise<T[]> {
1039
1102
  if (query.properties && query.properties.length === 0) {
1040
1103
  throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
1041
1104
  }
1042
- if (useSurrealDB) {
1043
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
1044
- const result = await perspective.querySurrealDB(surrealQuery);
1045
- const { results } = await this.instancesFromSurrealResult(perspective, query, result);
1105
+
1106
+ // Backward compatibility: boolean maps to sparql (true) or prolog (false)
1107
+ const resolvedEngine = typeof engine === 'boolean'
1108
+ ? (engine ? 'sparql' : 'prolog')
1109
+ : engine;
1110
+
1111
+ if (resolvedEngine === 'sparql') {
1112
+ // Always use the regular SPARQL path + JS-level hydrateRelations for includes.
1113
+ // The batch SPARQL approach had issues with sub-queries (where/order/limit on includes),
1114
+ // non-conforming node filtering, and parse_literal compatibility.
1115
+ // hydrateRelations handles all of these correctly via per-relation findAll calls.
1116
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
1117
+ const rawResult = await perspective.querySparql(sparqlQuery);
1118
+ const grouped = groupSPARQLResults(rawResult);
1119
+ const { results } = await this.instancesFromQueryResult(perspective, query, grouped);
1046
1120
  return results;
1047
1121
  } else {
1048
1122
  const prologQuery = await this.queryToProlog(perspective, query);
@@ -1059,7 +1133,7 @@ export class Ad4mModel {
1059
1133
  *
1060
1134
  * @param perspective - The perspective to search in
1061
1135
  * @param query - Optional query parameters to filter results
1062
- * @param useSurrealDB - Whether to use SurrealDB (default: true) or Prolog (legacy)
1136
+ * @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
1063
1137
  * @returns The first matching instance, or `null`
1064
1138
  *
1065
1139
  * @example
@@ -1076,10 +1150,10 @@ export class Ad4mModel {
1076
1150
  this: typeof Ad4mModel & (new (...args: any[]) => T),
1077
1151
  perspective: PerspectiveProxy,
1078
1152
  query: Query = {},
1079
- useSurrealDB: boolean = true,
1153
+ engine: 'sparql' | 'prolog' | boolean = 'sparql',
1080
1154
  ): Promise<T | null> {
1081
1155
  const limitedQuery = { ...query, limit: 1 };
1082
- const results = await this.findAll(perspective, limitedQuery, useSurrealDB);
1156
+ const results = await this.findAll(perspective, limitedQuery, engine);
1083
1157
  return results[0] ?? null;
1084
1158
  }
1085
1159
 
@@ -1088,7 +1162,7 @@ export class Ad4mModel {
1088
1162
  *
1089
1163
  * @param perspective - The perspective to search in
1090
1164
  * @param query - Optional query parameters to filter results
1091
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1165
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
1092
1166
  * @returns Object containing results array and total count
1093
1167
  *
1094
1168
  * @example
@@ -1107,12 +1181,17 @@ export class Ad4mModel {
1107
1181
  this: typeof Ad4mModel & (new (...args: any[]) => T),
1108
1182
  perspective: PerspectiveProxy,
1109
1183
  query: Query = {},
1110
- useSurrealDB: boolean = true
1184
+ engine: 'sparql' | 'prolog' | boolean = 'sparql'
1111
1185
  ): Promise<ResultsWithTotalCount<T>> {
1112
- if (useSurrealDB) {
1113
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
1114
- const result = await perspective.querySurrealDB(surrealQuery);
1115
- return await this.instancesFromSurrealResult(perspective, query, result);
1186
+ const resolvedEngine = typeof engine === 'boolean'
1187
+ ? (engine ? 'sparql' : 'prolog')
1188
+ : engine;
1189
+
1190
+ if (resolvedEngine === 'sparql') {
1191
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
1192
+ const rawResult = await perspective.querySparql(sparqlQuery);
1193
+ const grouped = groupSPARQLResults(rawResult);
1194
+ return await this.instancesFromQueryResult(perspective, query, grouped, true);
1116
1195
  } else {
1117
1196
  const prologQuery = await this.queryToProlog(perspective, query);
1118
1197
  const result = await perspective.infer(prologQuery);
@@ -1127,7 +1206,7 @@ export class Ad4mModel {
1127
1206
  * @param pageSize - Number of items per page
1128
1207
  * @param pageNumber - Which page to retrieve (1-based)
1129
1208
  * @param query - Optional additional query parameters
1130
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1209
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
1131
1210
  * @returns Paginated results with metadata
1132
1211
  *
1133
1212
  * @example
@@ -1147,13 +1226,18 @@ export class Ad4mModel {
1147
1226
  pageSize: number,
1148
1227
  pageNumber: number,
1149
1228
  query?: Query,
1150
- useSurrealDB: boolean = true
1229
+ engine: 'sparql' | 'prolog' | boolean = 'sparql'
1151
1230
  ): Promise<PaginationResult<T>> {
1152
1231
  const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1153
- if (useSurrealDB) {
1154
- const surrealQuery = await this.queryToSurrealQL(perspective, paginationQuery);
1155
- const result = await perspective.querySurrealDB(surrealQuery);
1156
- const { results, totalCount } = await this.instancesFromSurrealResult(perspective, paginationQuery, result);
1232
+ const resolvedEngine = typeof engine === 'boolean'
1233
+ ? (engine ? 'sparql' : 'prolog')
1234
+ : engine;
1235
+
1236
+ if (resolvedEngine === 'sparql') {
1237
+ const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
1238
+ const rawResult = await perspective.querySparql(sparqlQuery);
1239
+ const grouped = groupSPARQLResults(rawResult);
1240
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
1157
1241
  return { results, totalCount, pageSize, pageNumber };
1158
1242
  } else {
1159
1243
  const prologQuery = await this.queryToProlog(perspective, paginationQuery);
@@ -1185,21 +1269,18 @@ export class Ad4mModel {
1185
1269
  }
1186
1270
 
1187
1271
  /**
1188
- * Generates a SurrealQL COUNT query for the model.
1272
+ * Generates a SPARQL COUNT query for the model.
1189
1273
  *
1190
1274
  * @param perspective - The perspective context
1191
1275
  * @param query - Query parameters to filter the count
1192
- * @returns SurrealQL COUNT query string
1276
+ * @returns SPARQL COUNT query string
1193
1277
  *
1194
1278
  * @private
1195
1279
  */
1196
- public static async countQueryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
1197
- // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
1198
- // We'll count the number of rows returned (one row per source)
1199
- const countQuery = { ...query };
1200
- delete countQuery.limit;
1201
- delete countQuery.offset;
1202
- return await this.queryToSurrealQL(perspective, countQuery);
1280
+ public static async countQueryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
1281
+ const metadata = this.getModelMetadata();
1282
+ const allRelMeta = getRelationsMetadata(this as any);
1283
+ return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
1203
1284
  }
1204
1285
 
1205
1286
  /**
@@ -1207,7 +1288,7 @@ export class Ad4mModel {
1207
1288
  *
1208
1289
  * @param perspective - The perspective to search in
1209
1290
  * @param query - Optional query parameters to filter results
1210
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1291
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
1211
1292
  * @returns Total count of matching entities
1212
1293
  *
1213
1294
  * @example
@@ -1221,15 +1302,27 @@ export class Ad4mModel {
1221
1302
  * const countProlog = await Recipe.count(perspective, {}, false);
1222
1303
  * ```
1223
1304
  */
1224
- static async count(perspective: PerspectiveProxy, query: Query = {}, useSurrealDB: boolean = true) {
1225
- if (useSurrealDB) {
1226
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
1227
- const result = await perspective.querySurrealDB(surrealQuery);
1228
- // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
1229
- // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
1230
- // This ensures count() returns the same number as findAll().length
1231
- const { totalCount } = await this.instancesFromSurrealResult(perspective, query, result);
1232
- return totalCount;
1305
+ static async count(perspective: PerspectiveProxy, query: Query = {}, engine: 'sparql' | 'prolog' | boolean = 'sparql') {
1306
+ const resolvedEngine = typeof engine === 'boolean'
1307
+ ? (engine ? 'sparql' : 'prolog')
1308
+ : engine;
1309
+
1310
+ if (resolvedEngine === 'sparql') {
1311
+ // When query has JS-only where filters (gt, between, author, timestamp, etc.),
1312
+ // we must fall back to full hydration + JS filtering to get accurate count.
1313
+ const metadata = this.getModelMetadata();
1314
+ const allRelMeta = getRelationsMetadata(this as any);
1315
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, query.where)) {
1316
+ // Fall back to full query + JS filter path for accurate count
1317
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
1318
+ const rawResult = await perspective.querySparql(sparqlQuery);
1319
+ const grouped = groupSPARQLResults(rawResult);
1320
+ const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped, true); return totalCount;
1321
+ }
1322
+ // No JS-only filters — use efficient COUNT query
1323
+ const countSparql = await this.countQueryToSPARQL(perspective, query);
1324
+ const countResult = await perspective.querySparql(countSparql);
1325
+ return parseSparqlCount(countResult) ?? 0;
1233
1326
  } else {
1234
1327
  const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
1235
1328
  return result?.[0]?.TotalCount || 0;
@@ -1249,7 +1342,7 @@ export class Ad4mModel {
1249
1342
  // Get resolve language from metadata (replaces Prolog query)
1250
1343
  let resolveLanguage = metadata.resolveLanguage;
1251
1344
 
1252
- // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal://string:)
1345
+ // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
1253
1346
  if (value === undefined || value === null || value === "") {
1254
1347
  return;
1255
1348
  }
@@ -1565,6 +1658,67 @@ export class Ad4mModel {
1565
1658
  }
1566
1659
  }
1567
1660
 
1661
+ /**
1662
+ * Evaluate SPARQL getters for a batch of instances on demand.
1663
+ *
1664
+ * Use after a shallow collection query (the default) to resolve
1665
+ * getter-backed properties for visible items only. This avoids the
1666
+ * O(N × getters) cost of evaluating every getter on every instance in
1667
+ * a large collection query.
1668
+ *
1669
+ * @param instances - Array of model instances to evaluate getters on
1670
+ * @param perspective - The perspective to query against
1671
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
1672
+ * If omitted, all getters are evaluated.
1673
+ *
1674
+ * @example
1675
+ * ```typescript
1676
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
1677
+ * // messages[i].replyingTo is undefined (getter skipped by default)
1678
+ *
1679
+ * // Evaluate getters for the visible subset
1680
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
1681
+ * // messages[0..9].replyingTo is now populated
1682
+ * ```
1683
+ */
1684
+ static async evaluateGetters<T extends Ad4mModel>(
1685
+ instances: T[],
1686
+ perspective: PerspectiveProxy,
1687
+ propertyNames?: string[],
1688
+ ): Promise<void> {
1689
+ if (instances.length === 0) return;
1690
+ const metadata = this.getModelMetadata();
1691
+ const opts = propertyNames && propertyNames.length > 0
1692
+ ? { requestedProperties: propertyNames }
1693
+ : undefined;
1694
+
1695
+ // Determine which property names will actually be evaluated
1696
+ const evaluatedPropertyNames: string[] = [];
1697
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1698
+ if ((propMeta as any).getter) {
1699
+ if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(propName)) {
1700
+ evaluatedPropertyNames.push(propName);
1701
+ }
1702
+ }
1703
+ }
1704
+
1705
+ for (const instance of instances) {
1706
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
1707
+ // Sync snapshot so isDirty() doesn't flag getter-only changes.
1708
+ // evaluateGetters() mutates instances in place, but their snapshots
1709
+ // were already taken during hydration. Without this sync, the computed
1710
+ // getter values would make isDirty() return true and save() would try
1711
+ // to write read-only computed properties.
1712
+ const modelInstance = instance as Ad4mModel;
1713
+ if (modelInstance._snapshot) {
1714
+ for (const propName of evaluatedPropertyNames) {
1715
+ const val = (instance as any)[propName];
1716
+ modelInstance._snapshot[propName] = normalizeValue(Array.isArray(val) ? [...val] : val);
1717
+ }
1718
+ }
1719
+ }
1720
+ }
1721
+
1568
1722
  /**
1569
1723
  * Gets the model instance with all properties and relations populated.
1570
1724
  *