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

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 (94) hide show
  1. package/lib/index.cjs +1392 -777
  2. package/lib/index.js +1376 -775
  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/language/Language.d.ts +41 -3
  8. package/lib/src/model/Ad4mModel.d.ts +28 -28
  9. package/lib/src/model/Ad4mModel.js +129 -101
  10. package/lib/src/model/Ad4mModel.test.js +1543 -535
  11. package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
  12. package/lib/src/model/ModelQueryBuilder.js +163 -78
  13. package/lib/src/model/Subject.js +6 -6
  14. package/lib/src/model/decorators.d.ts +14 -8
  15. package/lib/src/model/decorators.js +41 -14
  16. package/lib/src/model/hydration-batch.d.ts +34 -0
  17. package/lib/src/model/hydration-batch.js +147 -0
  18. package/lib/src/model/hydration.d.ts +3 -3
  19. package/lib/src/model/hydration.js +106 -36
  20. package/lib/src/model/index.d.ts +4 -1
  21. package/lib/src/model/index.js +4 -1
  22. package/lib/src/model/json-schema.js +2 -2
  23. package/lib/src/model/query-cache.d.ts +30 -0
  24. package/lib/src/model/query-cache.js +66 -0
  25. package/lib/src/model/query-cache.test.d.ts +1 -0
  26. package/lib/src/model/query-cache.test.js +43 -0
  27. package/lib/src/model/query-common.d.ts +1 -1
  28. package/lib/src/model/query-common.js +1 -1
  29. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  30. package/lib/src/model/query-sparql-batch.js +260 -0
  31. package/lib/src/model/query-sparql.d.ts +47 -0
  32. package/lib/src/model/query-sparql.js +336 -0
  33. package/lib/src/model/query-utils.d.ts +45 -0
  34. package/lib/src/model/query-utils.js +140 -0
  35. package/lib/src/model/relation-filtering.test.js +15 -15
  36. package/lib/src/model/sdna.js +1 -1
  37. package/lib/src/model/shacl-gen.js +42 -18
  38. package/lib/src/model/subscription-pool.d.ts +39 -0
  39. package/lib/src/model/subscription-pool.js +119 -0
  40. package/lib/src/model/types.d.ts +3 -3
  41. package/lib/src/model/types.js +1 -1
  42. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
  43. package/lib/src/perspectives/PerspectiveClient.js +5 -57
  44. package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
  45. package/lib/src/perspectives/PerspectiveProxy.js +224 -177
  46. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  47. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  48. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  49. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  50. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  51. package/lib/src/runtime/RuntimeResolver.js +56 -0
  52. package/lib/src/schema.gql +11 -1
  53. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  54. package/lib/src/shacl/SHACLFlow.js +9 -9
  55. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  56. package/lib/src/shacl/SHACLShape.js +38 -38
  57. package/lib/src/typeDefs.js +11 -1
  58. package/lib/src/utils.d.ts +6 -6
  59. package/lib/src/utils.js +6 -6
  60. package/package.json +1 -1
  61. package/src/Literal.test.ts +10 -5
  62. package/src/Literal.ts +6 -5
  63. package/src/agent/AgentClient.ts +53 -1
  64. package/src/expression/ExpressionRef.ts +2 -2
  65. package/src/language/Language.ts +48 -3
  66. package/src/model/Ad4mModel.test.ts +1515 -565
  67. package/src/model/Ad4mModel.ts +142 -102
  68. package/src/model/ModelQueryBuilder.ts +185 -86
  69. package/src/model/Subject.ts +6 -6
  70. package/src/model/decorators.ts +51 -22
  71. package/src/model/hydration-batch.ts +205 -0
  72. package/src/model/hydration.ts +102 -39
  73. package/src/model/index.ts +4 -1
  74. package/src/model/json-schema.ts +2 -2
  75. package/src/model/query-cache.test.ts +54 -0
  76. package/src/model/query-cache.ts +79 -0
  77. package/src/model/query-common.ts +1 -1
  78. package/src/model/query-sparql-batch.ts +301 -0
  79. package/src/model/query-sparql.ts +363 -0
  80. package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
  81. package/src/model/relation-filtering.test.ts +15 -15
  82. package/src/model/sdna.ts +1 -1
  83. package/src/model/shacl-gen.ts +42 -17
  84. package/src/model/subscription-pool.ts +163 -0
  85. package/src/model/types.ts +3 -3
  86. package/src/perspectives/PerspectiveClient.ts +5 -61
  87. package/src/perspectives/PerspectiveProxy.ts +226 -181
  88. package/src/perspectives/PerspectiveResolver.ts +0 -8
  89. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  90. package/src/runtime/RuntimeResolver.ts +43 -0
  91. package/src/shacl/SHACLFlow.ts +9 -9
  92. package/src/shacl/SHACLShape.ts +39 -39
  93. package/src/utils.ts +6 -6
  94. package/src/model/query-surreal.ts +0 -280
@@ -3,11 +3,10 @@ import { Link } from "../links/Links";
3
3
  import { LinkQuery } from "../perspectives/LinkQuery";
4
4
  import { makeRandomId } from "./util";
5
5
  import { getPropertiesMetadata, getRelationsMetadata } from "./decorators";
6
- import { formatSurrealValue } from "./surreal-utils";
7
6
  import { resolveParentPredicate } from "./query-common";
8
7
  import { buildParentQuery, buildAuthorAndTimestampQuery, buildPropertiesQuery, buildWhereQuery, buildCountQuery, buildOrderQuery, buildOffsetQuery, buildLimitQuery } from "./query-prolog";
9
8
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
10
- import { buildSurrealQLQuery } from "./query-surreal";
9
+ import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults } from "./query-sparql";
11
10
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
12
11
  import { normalizeValue, matchesCondition, hydrateFromLinks, assignValuesToInstance as _assignValuesToInstance, evaluateCustomGettersForInstance, hydrateRelations, } from "./hydration";
13
12
  /**
@@ -291,7 +290,7 @@ export class Ad4mModel {
291
290
  * const recipe = new Recipe(perspective);
292
291
  *
293
292
  * // Create with specific base expression
294
- * const recipe = new Recipe(perspective, "literal://...");
293
+ * const recipe = new Recipe(perspective, "literal:...");
295
294
  * ```
296
295
  */
297
296
  constructor(perspective, baseExpression) {
@@ -518,19 +517,13 @@ export class Ad4mModel {
518
517
  }
519
518
  async getData(opts) {
520
519
  // Builds an object with the author, timestamp, all properties, & all relations on the Ad4mModel and saves it to the instance
521
- // Use SurrealDB for data queries
520
+ // Use SPARQL for data queries
522
521
  try {
523
522
  const ctor = this.constructor;
524
523
  const metadata = ctor.getModelMetadata();
525
524
  // Query for all links from this specific node (base expression)
526
- const safeBaseExpression = formatSurrealValue(this._baseExpression);
527
- const linksQuery = `
528
- SELECT id, predicate, out.uri AS target, author, timestamp
529
- FROM link
530
- WHERE in.uri = ${safeBaseExpression}
531
- ORDER BY timestamp ASC
532
- `;
533
- const links = await this._perspective.querySurrealDB(linksQuery);
525
+ const linksQuery = buildSPARQLGetDataQuery(this._baseExpression);
526
+ const links = await this._perspective.querySparql(linksQuery);
534
527
  if (links && links.length > 0) {
535
528
  // Core hydration: properties (latest-wins), relations, timestamps/author
536
529
  const requestedProperties = opts?.properties && opts.properties.length > 0 ? opts.properties : undefined;
@@ -555,7 +548,7 @@ export class Ad4mModel {
555
548
  this[relName] = sourceIds;
556
549
  }
557
550
  }
558
- // Evaluate SurrealQL getters
551
+ // Evaluate SPARQL getters
559
552
  const getterOpts = opts?.properties || opts?.include
560
553
  ? { requestedProperties: opts?.properties, include: opts?.include }
561
554
  : undefined;
@@ -566,7 +559,7 @@ export class Ad4mModel {
566
559
  }
567
560
  }
568
561
  catch (e) {
569
- console.error(`SurrealDB getData also failed for ${this._baseExpression}:`, e);
562
+ console.error(`SPARQL getData also failed for ${this._baseExpression}:`, e);
570
563
  }
571
564
  this.takeSnapshot();
572
565
  return this;
@@ -596,13 +589,13 @@ export class Ad4mModel {
596
589
  return fullQuery;
597
590
  }
598
591
  /**
599
- * Generates a SurrealQL query from a Query object.
592
+ * Generates a SPARQL query from a Query object.
600
593
  *
601
594
  * @description
602
- * This method translates high-level query parameters into a SurrealQL query string
603
- * that can be executed against the SurrealDB backend. Unlike Prolog queries which
604
- * operate on SDNA-aware predicates, SurrealQL queries operate directly on raw links
605
- * stored in SurrealDB.
595
+ * This method translates high-level query parameters into a SPARQL query string
596
+ * that can be executed against the SPARQL backend. Unlike Prolog queries which
597
+ * operate on SDNA-aware predicates, SPARQL queries operate directly on raw links
598
+ * stored in SPARQL.
606
599
  *
607
600
  * The generated query uses a CTE (Common Table Expression) pattern:
608
601
  * 1. First, identify candidate base expressions by filtering links based on where conditions
@@ -610,7 +603,7 @@ export class Ad4mModel {
610
603
  * 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
611
604
  *
612
605
  * Key architectural notes:
613
- * - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
606
+ * - SPARQL stores only raw links (source, predicate, target, author, timestamp)
614
607
  * - No SDNA knowledge at the database level
615
608
  * - Properties are resolved via subqueries that look for links with specific predicates
616
609
  * - Relations are similar but return multiple values instead of one
@@ -618,11 +611,11 @@ export class Ad4mModel {
618
611
  *
619
612
  * @param perspective - The perspective to query (used for metadata extraction)
620
613
  * @param query - Query parameters (where, order, limit, offset, properties, relations)
621
- * @returns Complete SurrealQL query string ready for execution
614
+ * @returns Complete SPARQL query string ready for execution
622
615
  *
623
616
  * @example
624
617
  * ```typescript
625
- * const query = Recipe.queryToSurrealQL(perspective, {
618
+ * const query = Recipe.queryToSPARQL(perspective, {
626
619
  * where: { name: "Pasta", rating: { gt: 4 } },
627
620
  * order: { timestamp: "DESC" },
628
621
  * limit: 10
@@ -631,10 +624,10 @@ export class Ad4mModel {
631
624
  * // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
632
625
  * ```
633
626
  */
634
- static async queryToSurrealQL(perspective, query) {
627
+ static async queryToSPARQL(perspective, query) {
635
628
  const metadata = this.getModelMetadata();
636
629
  const allRelMeta = getRelationsMetadata(this);
637
- return buildSurrealQLQuery(metadata, allRelMeta, query, this);
630
+ return buildSPARQLQuery(metadata, allRelMeta, query, this);
638
631
  }
639
632
  static async instancesFromPrologResult(perspective, query, result) {
640
633
  if (!result?.[0]?.AllInstances)
@@ -679,16 +672,16 @@ export class Ad4mModel {
679
672
  return { results: instances, totalCount: result[0].TotalCount };
680
673
  }
681
674
  /**
682
- * Converts SurrealDB query results to Ad4mModel instances.
675
+ * Converts SPARQL query results to Ad4mModel instances.
683
676
  *
684
677
  * @param perspective - The perspective context
685
678
  * @param query - The query parameters used
686
- * @param result - Array of result objects from SurrealDB
679
+ * @param result - Array of result objects from SPARQL
687
680
  * @returns Promise resolving to results with total count
688
681
  *
689
682
  * @internal
690
683
  */
691
- static async instancesFromSurrealResult(perspective, query, result) {
684
+ static async instancesFromQueryResult(perspective, query, result) {
692
685
  if (!result || result.length === 0)
693
686
  return { results: [], totalCount: 0 };
694
687
  const metadata = this.getModelMetadata();
@@ -709,33 +702,25 @@ export class Ad4mModel {
709
702
  }
710
703
  const links = row.links || [];
711
704
  const instance = new this(perspective, base);
712
- // Core hydration via unified helper (pass requestedProperties for sparse fieldset)
713
- await hydrateFromLinks(instance, links, metadata, perspective, requestedProperties.length > 0 ? requestedProperties : undefined);
714
- // When specific properties are requested, delete unrequested properties
715
- // so they return undefined instead of their constructor defaults (e.g. 0, [])
716
- if (requestedProperties.length > 0) {
717
- const requested = new Set(requestedProperties);
718
- for (const propName of Object.keys(metadata.properties)) {
719
- if (!requested.has(propName)) {
720
- delete instance[propName];
721
- }
722
- }
723
- for (const relName of Object.keys(metadata.relations)) {
724
- if (!requested.has(relName) && !(query.include && relName in query.include)) {
725
- delete instance[relName];
726
- }
727
- }
728
- // Also strip metadata fields unless explicitly requested
729
- for (const metaField of ['author', 'createdAt', 'updatedAt']) {
730
- if (!requested.has(metaField)) {
731
- delete instance[metaField];
705
+ // Core hydration via unified helper (pass requestedProperties for sparse fieldset).
706
+ // Also hydrate any properties referenced in `where` so the JS post-filter can match them,
707
+ // even if they're not in the user's `properties` projection.
708
+ let hydrationProps = requestedProperties.length > 0 ? [...requestedProperties] : undefined;
709
+ if (hydrationProps && query.where) {
710
+ for (const key of Object.keys(query.where)) {
711
+ if (!hydrationProps.includes(key)) {
712
+ hydrationProps.push(key);
732
713
  }
733
714
  }
734
715
  }
716
+ await hydrateFromLinks(instance, links, metadata, perspective, hydrationProps);
717
+ // NOTE: Property deletion for sparse fieldsets is deferred until AFTER
718
+ // where-filtering so that where conditions can reference any property,
719
+ // even ones not in the `properties` projection.
735
720
  instances.push(instance);
736
721
  }
737
722
  catch (error) {
738
- console.error(`Failed to process SurrealDB instance ${base}:`, error);
723
+ console.error(`Failed to process SPARQL instance ${base}:`, error);
739
724
  }
740
725
  }
741
726
  // Populate reverse relation fields (belongsToOne / belongsToMany) as string IDs.
@@ -768,17 +753,19 @@ export class Ad4mModel {
768
753
  for (const instance of instances) {
769
754
  await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
770
755
  }
771
- // Filter by where conditions that couldn't be filtered in SQL
756
+ // Filter by where conditions that couldn't be filtered in SPARQL
772
757
  // This includes:
773
758
  // - author/timestamp (computed from grouped links)
774
759
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
775
- // because fn::parse_literal() comparisons in SurrealDB subqueries don't work reliably
760
+ // because fn::parse_literal() comparisons in SPARQL subqueries don't work reliably
761
+ // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
762
+ // which require reverse-link resolution before filtering
776
763
  let filteredInstances = instances;
777
764
  if (query.where) {
778
765
  filteredInstances = instances.filter(instance => {
779
766
  for (const [propertyName, condition] of Object.entries(query.where)) {
780
- // Skip 'base' as it's filtered in SQL
781
- if (propertyName === 'base')
767
+ // Skip 'base'/'id' as it's filtered in SPARQL
768
+ if (propertyName === 'base' || propertyName === 'id')
782
769
  continue;
783
770
  // For author and timestamp, always filter in JS
784
771
  if (propertyName === 'author' || propertyName === 'timestamp') {
@@ -787,19 +774,20 @@ export class Ad4mModel {
787
774
  }
788
775
  continue;
789
776
  }
790
- // For regular properties, only filter comparison operators in JS
791
- // Simple equality and NOT are handled in SQL, but gt/gte/lt/lte/between/contains need JS
792
- if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
793
- const ops = condition;
794
- // Check if any comparison operators are present
795
- const hasComparisonOps = ops.gt !== undefined || ops.gte !== undefined ||
796
- ops.lt !== undefined || ops.lte !== undefined ||
797
- ops.between !== undefined || ops.contains !== undefined;
798
- if (hasComparisonOps) {
799
- if (!matchesCondition(instance[propertyName], condition)) {
800
- return false;
801
- }
777
+ // Check if this is a relation field (not in properties metadata)
778
+ const isPropField = propertyName in metadata.properties;
779
+ if (!isPropField) {
780
+ // Relation-based where — filter in JS against the populated field
781
+ if (!matchesCondition(instance[propertyName], condition)) {
782
+ return false;
802
783
  }
784
+ continue;
785
+ }
786
+ // Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
787
+ // SPARQL-level filtering with parse_literal is unreliable across environments,
788
+ // so we do all property filtering here after hydration resolves values.
789
+ if (!matchesCondition(instance[propertyName], condition)) {
790
+ return false;
803
791
  }
804
792
  }
805
793
  return true;
@@ -851,6 +839,28 @@ export class Ad4mModel {
851
839
  const end = query.limit ? start + query.limit : undefined;
852
840
  paginatedInstances = filteredInstances.slice(start, end);
853
841
  }
842
+ // Now that where-filtering is done, strip unrequested properties for sparse fieldsets.
843
+ // This must happen AFTER where-filtering so conditions can reference any property.
844
+ if (requestedProperties.length > 0) {
845
+ const requested = new Set(requestedProperties);
846
+ for (const inst of paginatedInstances) {
847
+ for (const propName of Object.keys(metadata.properties)) {
848
+ if (!requested.has(propName)) {
849
+ delete inst[propName];
850
+ }
851
+ }
852
+ for (const relName of Object.keys(metadata.relations)) {
853
+ if (!requested.has(relName) && !(query.include && relName in query.include)) {
854
+ delete inst[relName];
855
+ }
856
+ }
857
+ for (const metaField of ['author', 'createdAt', 'updatedAt']) {
858
+ if (!requested.has(metaField)) {
859
+ delete inst[metaField];
860
+ }
861
+ }
862
+ }
863
+ }
854
864
  // Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
855
865
  if (query.include && paginatedInstances.length > 0) {
856
866
  await hydrateRelations(this, paginatedInstances, perspective, query.include);
@@ -875,15 +885,15 @@ export class Ad4mModel {
875
885
  *
876
886
  * @param perspective - The perspective to search in
877
887
  * @param query - Optional query parameters to filter results
878
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
888
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
879
889
  * @returns Array of matching models
880
890
  *
881
891
  * @example
882
892
  * ```typescript
883
- * // Get all recipes (uses SurrealDB by default)
893
+ * // Get all recipes (uses SPARQL by default)
884
894
  * const allRecipes = await Recipe.findAll(perspective);
885
895
  *
886
- * // Get recipes with specific criteria (uses SurrealDB)
896
+ * // Get recipes with specific criteria (uses SPARQL)
887
897
  * const recipes = await Recipe.findAll(perspective, {
888
898
  * where: {
889
899
  * name: "Pasta",
@@ -897,14 +907,23 @@ export class Ad4mModel {
897
907
  * const recipesProlog = await Recipe.findAll(perspective, {}, false);
898
908
  * ```
899
909
  */
900
- static async findAll(perspective, query = {}, useSurrealDB = true) {
910
+ static async findAll(perspective, query = {}, engine = 'sparql') {
901
911
  if (query.properties && query.properties.length === 0) {
902
912
  throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
903
913
  }
904
- if (useSurrealDB) {
905
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
906
- const result = await perspective.querySurrealDB(surrealQuery);
907
- const { results } = await this.instancesFromSurrealResult(perspective, query, result);
914
+ // Backward compatibility: boolean maps to sparql (true) or prolog (false)
915
+ const resolvedEngine = typeof engine === 'boolean'
916
+ ? (engine ? 'sparql' : 'prolog')
917
+ : engine;
918
+ if (resolvedEngine === 'sparql') {
919
+ // Always use the regular SPARQL path + JS-level hydrateRelations for includes.
920
+ // The batch SPARQL approach had issues with sub-queries (where/order/limit on includes),
921
+ // non-conforming node filtering, and parse_literal compatibility.
922
+ // hydrateRelations handles all of these correctly via per-relation findAll calls.
923
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
924
+ const rawResult = await perspective.querySparql(sparqlQuery);
925
+ const grouped = groupSPARQLResults(rawResult);
926
+ const { results } = await this.instancesFromQueryResult(perspective, query, grouped);
908
927
  return results;
909
928
  }
910
929
  else {
@@ -921,7 +940,7 @@ export class Ad4mModel {
921
940
  *
922
941
  * @param perspective - The perspective to search in
923
942
  * @param query - Optional query parameters to filter results
924
- * @param useSurrealDB - Whether to use SurrealDB (default: true) or Prolog (legacy)
943
+ * @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
925
944
  * @returns The first matching instance, or `null`
926
945
  *
927
946
  * @example
@@ -934,9 +953,9 @@ export class Ad4mModel {
934
953
  * }
935
954
  * ```
936
955
  */
937
- static async findOne(perspective, query = {}, useSurrealDB = true) {
956
+ static async findOne(perspective, query = {}, engine = 'sparql') {
938
957
  const limitedQuery = { ...query, limit: 1 };
939
- const results = await this.findAll(perspective, limitedQuery, useSurrealDB);
958
+ const results = await this.findAll(perspective, limitedQuery, engine);
940
959
  return results[0] ?? null;
941
960
  }
942
961
  /**
@@ -944,7 +963,7 @@ export class Ad4mModel {
944
963
  *
945
964
  * @param perspective - The perspective to search in
946
965
  * @param query - Optional query parameters to filter results
947
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
966
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
948
967
  * @returns Object containing results array and total count
949
968
  *
950
969
  * @example
@@ -959,11 +978,15 @@ export class Ad4mModel {
959
978
  * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
960
979
  * ```
961
980
  */
962
- static async findAllAndCount(perspective, query = {}, useSurrealDB = true) {
963
- if (useSurrealDB) {
964
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
965
- const result = await perspective.querySurrealDB(surrealQuery);
966
- return await this.instancesFromSurrealResult(perspective, query, result);
981
+ static async findAllAndCount(perspective, query = {}, engine = 'sparql') {
982
+ const resolvedEngine = typeof engine === 'boolean'
983
+ ? (engine ? 'sparql' : 'prolog')
984
+ : engine;
985
+ if (resolvedEngine === 'sparql') {
986
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
987
+ const rawResult = await perspective.querySparql(sparqlQuery);
988
+ const grouped = groupSPARQLResults(rawResult);
989
+ return await this.instancesFromQueryResult(perspective, query, grouped);
967
990
  }
968
991
  else {
969
992
  const prologQuery = await this.queryToProlog(perspective, query);
@@ -978,7 +1001,7 @@ export class Ad4mModel {
978
1001
  * @param pageSize - Number of items per page
979
1002
  * @param pageNumber - Which page to retrieve (1-based)
980
1003
  * @param query - Optional additional query parameters
981
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1004
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
982
1005
  * @returns Paginated results with metadata
983
1006
  *
984
1007
  * @example
@@ -992,12 +1015,16 @@ export class Ad4mModel {
992
1015
  * const pageProlog = await Recipe.paginate(perspective, 10, 1, {}, false);
993
1016
  * ```
994
1017
  */
995
- static async paginate(perspective, pageSize, pageNumber, query, useSurrealDB = true) {
1018
+ static async paginate(perspective, pageSize, pageNumber, query, engine = 'sparql') {
996
1019
  const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
997
- if (useSurrealDB) {
998
- const surrealQuery = await this.queryToSurrealQL(perspective, paginationQuery);
999
- const result = await perspective.querySurrealDB(surrealQuery);
1000
- const { results, totalCount } = await this.instancesFromSurrealResult(perspective, paginationQuery, result);
1020
+ const resolvedEngine = typeof engine === 'boolean'
1021
+ ? (engine ? 'sparql' : 'prolog')
1022
+ : engine;
1023
+ if (resolvedEngine === 'sparql') {
1024
+ const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
1025
+ const rawResult = await perspective.querySparql(sparqlQuery);
1026
+ const grouped = groupSPARQLResults(rawResult);
1027
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
1001
1028
  return { results, totalCount, pageSize, pageNumber };
1002
1029
  }
1003
1030
  else {
@@ -1026,28 +1053,28 @@ export class Ad4mModel {
1026
1053
  return fullQuery;
1027
1054
  }
1028
1055
  /**
1029
- * Generates a SurrealQL COUNT query for the model.
1056
+ * Generates a SPARQL COUNT query for the model.
1030
1057
  *
1031
1058
  * @param perspective - The perspective context
1032
1059
  * @param query - Query parameters to filter the count
1033
- * @returns SurrealQL COUNT query string
1060
+ * @returns SPARQL COUNT query string
1034
1061
  *
1035
1062
  * @private
1036
1063
  */
1037
- static async countQueryToSurrealQL(perspective, query) {
1064
+ static async countQueryToSPARQL(perspective, query) {
1038
1065
  // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
1039
1066
  // We'll count the number of rows returned (one row per source)
1040
1067
  const countQuery = { ...query };
1041
1068
  delete countQuery.limit;
1042
1069
  delete countQuery.offset;
1043
- return await this.queryToSurrealQL(perspective, countQuery);
1070
+ return await this.queryToSPARQL(perspective, countQuery);
1044
1071
  }
1045
1072
  /**
1046
1073
  * Gets a count of all matching instances.
1047
1074
  *
1048
1075
  * @param perspective - The perspective to search in
1049
1076
  * @param query - Optional query parameters to filter results
1050
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
1077
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
1051
1078
  * @returns Total count of matching entities
1052
1079
  *
1053
1080
  * @example
@@ -1061,14 +1088,15 @@ export class Ad4mModel {
1061
1088
  * const countProlog = await Recipe.count(perspective, {}, false);
1062
1089
  * ```
1063
1090
  */
1064
- static async count(perspective, query = {}, useSurrealDB = true) {
1065
- if (useSurrealDB) {
1066
- const surrealQuery = await this.queryToSurrealQL(perspective, query);
1067
- const result = await perspective.querySurrealDB(surrealQuery);
1068
- // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
1069
- // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
1070
- // This ensures count() returns the same number as findAll().length
1071
- const { totalCount } = await this.instancesFromSurrealResult(perspective, query, result);
1091
+ static async count(perspective, query = {}, engine = 'sparql') {
1092
+ const resolvedEngine = typeof engine === 'boolean'
1093
+ ? (engine ? 'sparql' : 'prolog')
1094
+ : engine;
1095
+ if (resolvedEngine === 'sparql') {
1096
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
1097
+ const rawResult = await perspective.querySparql(sparqlQuery);
1098
+ const grouped = groupSPARQLResults(rawResult);
1099
+ const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
1072
1100
  return totalCount;
1073
1101
  }
1074
1102
  else {
@@ -1086,7 +1114,7 @@ export class Ad4mModel {
1086
1114
  const actions = this.generatePropertySetterAction(key, metadata);
1087
1115
  // Get resolve language from metadata (replaces Prolog query)
1088
1116
  let resolveLanguage = metadata.resolveLanguage;
1089
- // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal://string:)
1117
+ // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
1090
1118
  if (value === undefined || value === null || value === "") {
1091
1119
  return;
1092
1120
  }