@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.
- package/lib/index.cjs +2377 -849
- package/lib/index.js +2354 -846
- package/lib/src/Literal.js +6 -5
- package/lib/src/agent/AgentClient.d.ts +5 -1
- package/lib/src/agent/AgentClient.js +48 -2
- package/lib/src/expression/ExpressionRef.js +2 -2
- package/lib/src/index.d.ts +0 -1
- package/lib/src/index.js +0 -1
- package/lib/src/language/Language.d.ts +26 -176
- package/lib/src/language/Language.js +28 -2
- package/lib/src/model/Ad4mModel.d.ts +52 -28
- package/lib/src/model/Ad4mModel.js +255 -118
- package/lib/src/model/Ad4mModel.test.js +1727 -537
- package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
- package/lib/src/model/ModelQueryBuilder.js +208 -79
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/decorators.d.ts +14 -8
- package/lib/src/model/decorators.js +41 -14
- package/lib/src/model/hydration-batch.d.ts +34 -0
- package/lib/src/model/hydration-batch.js +147 -0
- package/lib/src/model/hydration-batching.test.d.ts +7 -0
- package/lib/src/model/hydration-batching.test.js +456 -0
- package/lib/src/model/hydration.d.ts +4 -3
- package/lib/src/model/hydration.js +365 -86
- package/lib/src/model/index.d.ts +4 -1
- package/lib/src/model/index.js +4 -1
- package/lib/src/model/json-schema.js +2 -2
- package/lib/src/model/query-cache.d.ts +30 -0
- package/lib/src/model/query-cache.js +66 -0
- package/lib/src/model/query-cache.test.d.ts +1 -0
- package/lib/src/model/query-cache.test.js +43 -0
- package/lib/src/model/query-common.d.ts +1 -1
- package/lib/src/model/query-common.js +1 -1
- package/lib/src/model/query-sparql-batch.d.ts +17 -0
- package/lib/src/model/query-sparql-batch.js +260 -0
- package/lib/src/model/query-sparql.d.ts +124 -0
- package/lib/src/model/query-sparql.js +767 -0
- package/lib/src/model/query-sparql.test.d.ts +1 -0
- package/lib/src/model/query-sparql.test.js +495 -0
- package/lib/src/model/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
- package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/sdna.js +1 -1
- package/lib/src/model/shacl-gen.js +42 -18
- package/lib/src/model/subscription-delta.test.d.ts +24 -0
- package/lib/src/model/subscription-delta.test.js +180 -0
- package/lib/src/model/subscription-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +165 -0
- package/lib/src/model/types.d.ts +52 -4
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
- package/lib/src/perspectives/PerspectiveClient.js +42 -66
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -30
- package/lib/src/perspectives/PerspectiveProxy.js +239 -177
- package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveResolver.js +0 -11
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
- package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
- package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
- package/lib/src/runtime/RuntimeResolver.js +56 -0
- package/lib/src/schema.gql +11 -1
- package/lib/src/shacl/SHACLFlow.d.ts +1 -1
- package/lib/src/shacl/SHACLFlow.js +9 -9
- package/lib/src/shacl/SHACLShape.d.ts +1 -1
- package/lib/src/shacl/SHACLShape.js +38 -38
- package/lib/src/typeDefs.js +11 -1
- package/lib/src/utils.d.ts +6 -6
- package/lib/src/utils.js +6 -6
- package/package.json +1 -1
- package/src/Ad4mClient.test.ts +56 -1
- package/src/Literal.test.ts +10 -5
- package/src/Literal.ts +6 -5
- package/src/agent/AgentClient.ts +53 -1
- package/src/expression/ExpressionRef.ts +2 -2
- package/src/index.ts +0 -1
- package/src/language/Language.ts +55 -231
- package/src/model/Ad4mModel.test.ts +1709 -572
- package/src/model/Ad4mModel.ts +274 -120
- package/src/model/ModelQueryBuilder.ts +234 -87
- package/src/model/Subject.ts +6 -6
- package/src/model/decorators.ts +51 -22
- package/src/model/hydration-batch.ts +205 -0
- package/src/model/hydration-batching.test.ts +563 -0
- package/src/model/hydration.ts +349 -84
- package/src/model/index.ts +4 -1
- package/src/model/json-schema.ts +2 -2
- package/src/model/query-cache.test.ts +54 -0
- package/src/model/query-cache.ts +79 -0
- package/src/model/query-common.ts +1 -1
- package/src/model/query-sparql-batch.ts +301 -0
- package/src/model/query-sparql.test.ts +568 -0
- package/src/model/query-sparql.ts +820 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +44 -27
- package/src/model/relation-filtering.test.ts +15 -15
- package/src/model/sdna.ts +1 -1
- package/src/model/shacl-gen.ts +42 -17
- package/src/model/subscription-delta.test.ts +207 -0
- package/src/model/subscription-pool.ts +211 -0
- package/src/model/types.ts +53 -4
- package/src/perspectives/PerspectiveClient.test.ts +204 -0
- package/src/perspectives/PerspectiveClient.ts +41 -68
- package/src/perspectives/PerspectiveProxy.ts +244 -181
- package/src/perspectives/PerspectiveResolver.ts +0 -8
- package/src/perspectives/WakerSubscriptionManager.ts +8 -9
- package/src/runtime/RuntimeResolver.ts +43 -0
- package/src/shacl/SHACLFlow.ts +9 -9
- package/src/shacl/SHACLShape.ts +39 -39
- package/src/utils.ts +6 -6
- package/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/src/language/LanguageContext.ts +0 -37
- package/src/model/query-surreal.ts +0 -280
- package/tsconfig-browser.json +0 -82
|
@@ -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 {
|
|
9
|
+
import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults, buildSPARQLCountQuery, hasJsOnlyWhereFilters, parseSparqlCount } 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
|
|
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
|
|
527
|
-
const
|
|
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
|
|
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(`
|
|
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
|
|
592
|
+
* Generates a SPARQL query from a Query object.
|
|
600
593
|
*
|
|
601
594
|
* @description
|
|
602
|
-
* This method translates high-level query parameters into a
|
|
603
|
-
* that can be executed against the
|
|
604
|
-
* operate on SDNA-aware predicates,
|
|
605
|
-
* stored in
|
|
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
|
-
* -
|
|
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
|
|
614
|
+
* @returns Complete SPARQL query string ready for execution
|
|
622
615
|
*
|
|
623
616
|
* @example
|
|
624
617
|
* ```typescript
|
|
625
|
-
* const query = Recipe.
|
|
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
|
|
627
|
+
static async queryToSPARQL(perspective, query) {
|
|
635
628
|
const metadata = this.getModelMetadata();
|
|
636
629
|
const allRelMeta = getRelationsMetadata(this);
|
|
637
|
-
return
|
|
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
|
|
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
|
|
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
|
|
684
|
+
static async instancesFromQueryResult(perspective, query, result, computeTotalCount = false) {
|
|
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
|
-
|
|
714
|
-
//
|
|
715
|
-
|
|
716
|
-
if (
|
|
717
|
-
const
|
|
718
|
-
|
|
719
|
-
|
|
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
|
|
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.
|
|
@@ -761,24 +746,46 @@ export class Ad4mModel {
|
|
|
761
746
|
}
|
|
762
747
|
}));
|
|
763
748
|
}
|
|
764
|
-
// Evaluate custom getters for all instances
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
749
|
+
// Evaluate custom getters for all instances.
|
|
750
|
+
// Relation getters (type-conformance filtering) always run — they ensure
|
|
751
|
+
// correctness of @HasMany/@HasOne targets. Property getters only run when
|
|
752
|
+
// deepQuery is true or when where conditions reference getter-backed properties.
|
|
753
|
+
const whereGetterProperties = query.where
|
|
754
|
+
? Object.keys(query.where).filter((propName) => metadata.properties[propName]?.getter)
|
|
755
|
+
: [];
|
|
756
|
+
const shouldEvaluatePropertyGetters = query.deepQuery === true || whereGetterProperties.length > 0;
|
|
757
|
+
{
|
|
758
|
+
const skipPropertyGetters = !shouldEvaluatePropertyGetters;
|
|
759
|
+
const getterRequestedProperties = shouldEvaluatePropertyGetters
|
|
760
|
+
? (requestedProperties.length > 0
|
|
761
|
+
? Array.from(new Set([...requestedProperties, ...whereGetterProperties]))
|
|
762
|
+
: query.deepQuery === true
|
|
763
|
+
? [] // deepQuery: evaluate all getters
|
|
764
|
+
: whereGetterProperties) // only evaluate where-referenced getters
|
|
765
|
+
: [];
|
|
766
|
+
const getterOpts = {
|
|
767
|
+
...(getterRequestedProperties.length > 0 && { requestedProperties: getterRequestedProperties }),
|
|
768
|
+
...(query.include && { include: query.include }),
|
|
769
|
+
skipPropertyGetters,
|
|
770
|
+
};
|
|
771
|
+
for (const instance of instances) {
|
|
772
|
+
await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
|
|
773
|
+
}
|
|
770
774
|
}
|
|
771
|
-
// Filter by where conditions that couldn't be filtered in
|
|
775
|
+
// Filter by where conditions that couldn't be filtered in SPARQL
|
|
772
776
|
// This includes:
|
|
773
777
|
// - author/timestamp (computed from grouped links)
|
|
774
778
|
// - Properties with comparison operators (gt, gte, lt, lte, between, contains)
|
|
775
|
-
// because fn
|
|
779
|
+
// because <ad4m://fn/parse_literal>() returns strings, making numeric/date
|
|
780
|
+
// comparisons unreliable. Equality, IN, and NOT are pushed to SPARQL.
|
|
781
|
+
// - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
|
|
782
|
+
// which require reverse-link resolution before filtering
|
|
776
783
|
let filteredInstances = instances;
|
|
777
784
|
if (query.where) {
|
|
778
785
|
filteredInstances = instances.filter(instance => {
|
|
779
786
|
for (const [propertyName, condition] of Object.entries(query.where)) {
|
|
780
|
-
// Skip 'base' as it's filtered in
|
|
781
|
-
if (propertyName === 'base')
|
|
787
|
+
// Skip 'base'/'id' as it's filtered in SPARQL
|
|
788
|
+
if (propertyName === 'base' || propertyName === 'id')
|
|
782
789
|
continue;
|
|
783
790
|
// For author and timestamp, always filter in JS
|
|
784
791
|
if (propertyName === 'author' || propertyName === 'timestamp') {
|
|
@@ -787,19 +794,20 @@ export class Ad4mModel {
|
|
|
787
794
|
}
|
|
788
795
|
continue;
|
|
789
796
|
}
|
|
790
|
-
//
|
|
791
|
-
|
|
792
|
-
if (
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
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
|
-
}
|
|
797
|
+
// Check if this is a relation field (not in properties metadata)
|
|
798
|
+
const isPropField = propertyName in metadata.properties;
|
|
799
|
+
if (!isPropField) {
|
|
800
|
+
// Relation-based where — filter in JS against the populated field
|
|
801
|
+
if (!matchesCondition(instance[propertyName], condition)) {
|
|
802
|
+
return false;
|
|
802
803
|
}
|
|
804
|
+
continue;
|
|
805
|
+
}
|
|
806
|
+
// Filter ALL property conditions in JS (safety net).
|
|
807
|
+
// Equality/IN/NOT are also filtered in SPARQL via <ad4m://fn/parse_literal>()
|
|
808
|
+
// but JS re-validates after hydration resolves values.
|
|
809
|
+
if (!matchesCondition(instance[propertyName], condition)) {
|
|
810
|
+
return false;
|
|
803
811
|
}
|
|
804
812
|
}
|
|
805
813
|
return true;
|
|
@@ -809,7 +817,7 @@ export class Ad4mModel {
|
|
|
809
817
|
// If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
|
|
810
818
|
// This ensures consistent pagination behavior
|
|
811
819
|
const effectiveOrder = query.order ||
|
|
812
|
-
(query.limit !== undefined || query.offset !== undefined ? {
|
|
820
|
+
(query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' } : null);
|
|
813
821
|
if (effectiveOrder) {
|
|
814
822
|
const orderEntries = Object.entries(effectiveOrder);
|
|
815
823
|
filteredInstances.sort((a, b) => {
|
|
@@ -842,15 +850,63 @@ export class Ad4mModel {
|
|
|
842
850
|
return 0;
|
|
843
851
|
});
|
|
844
852
|
}
|
|
845
|
-
//
|
|
846
|
-
|
|
847
|
-
//
|
|
853
|
+
// Determine if SPARQL already applied LIMIT/OFFSET (i.e., the pagination
|
|
854
|
+
// subquery was used). When it was, skip JS-level slicing — instances are
|
|
855
|
+
// already the correct page.
|
|
856
|
+
const allRelsMeta2 = getRelationsMetadata(this);
|
|
857
|
+
const sparqlPaginated = !hasJsOnlyWhereFilters(metadata, allRelsMeta2, query.where)
|
|
858
|
+
&& (query.limit !== undefined || query.offset !== undefined)
|
|
859
|
+
&& query.order !== undefined && Object.keys(query.order).length > 0;
|
|
860
|
+
// Calculate totalCount BEFORE applying limit/offset.
|
|
861
|
+
// When SPARQL already paginated, filteredInstances.length is the page size,
|
|
862
|
+
// not the total — use a separate COUNT query for the real total.
|
|
863
|
+
// Only run the COUNT query when the caller actually needs it (computeTotalCount=true).
|
|
864
|
+
let totalCount;
|
|
865
|
+
if (sparqlPaginated && computeTotalCount) {
|
|
866
|
+
try {
|
|
867
|
+
const countSparql = buildSPARQLCountQuery(metadata, allRelsMeta2, query, this);
|
|
868
|
+
const countResult = await perspective.querySparql(countSparql);
|
|
869
|
+
totalCount = parseSparqlCount(countResult) ?? filteredInstances.length;
|
|
870
|
+
}
|
|
871
|
+
catch {
|
|
872
|
+
// Fallback: if count query fails, use what we have
|
|
873
|
+
totalCount = filteredInstances.length;
|
|
874
|
+
}
|
|
875
|
+
}
|
|
876
|
+
else {
|
|
877
|
+
totalCount = filteredInstances.length;
|
|
878
|
+
}
|
|
879
|
+
// Apply offset and limit in JavaScript only when SPARQL didn't already paginate.
|
|
880
|
+
// Subscription queries use unpaginated SPARQL, so JS must apply pagination.
|
|
881
|
+
// Direct queries use SPARQL-level pagination, so JS slicing would double-apply.
|
|
848
882
|
let paginatedInstances = filteredInstances;
|
|
849
|
-
if (query.offset !== undefined || query.limit !== undefined) {
|
|
883
|
+
if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
|
|
850
884
|
const start = query.offset || 0;
|
|
851
885
|
const end = query.limit ? start + query.limit : undefined;
|
|
852
886
|
paginatedInstances = filteredInstances.slice(start, end);
|
|
853
887
|
}
|
|
888
|
+
// Now that where-filtering is done, strip unrequested properties for sparse fieldsets.
|
|
889
|
+
// This must happen AFTER where-filtering so conditions can reference any property.
|
|
890
|
+
if (requestedProperties.length > 0) {
|
|
891
|
+
const requested = new Set(requestedProperties);
|
|
892
|
+
for (const inst of paginatedInstances) {
|
|
893
|
+
for (const propName of Object.keys(metadata.properties)) {
|
|
894
|
+
if (!requested.has(propName)) {
|
|
895
|
+
delete inst[propName];
|
|
896
|
+
}
|
|
897
|
+
}
|
|
898
|
+
for (const relName of Object.keys(metadata.relations)) {
|
|
899
|
+
if (!requested.has(relName) && !(query.include && relName in query.include)) {
|
|
900
|
+
delete inst[relName];
|
|
901
|
+
}
|
|
902
|
+
}
|
|
903
|
+
for (const metaField of ['author', 'createdAt', 'updatedAt']) {
|
|
904
|
+
if (!requested.has(metaField)) {
|
|
905
|
+
delete inst[metaField];
|
|
906
|
+
}
|
|
907
|
+
}
|
|
908
|
+
}
|
|
909
|
+
}
|
|
854
910
|
// Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
|
|
855
911
|
if (query.include && paginatedInstances.length > 0) {
|
|
856
912
|
await hydrateRelations(this, paginatedInstances, perspective, query.include);
|
|
@@ -875,15 +931,15 @@ export class Ad4mModel {
|
|
|
875
931
|
*
|
|
876
932
|
* @param perspective - The perspective to search in
|
|
877
933
|
* @param query - Optional query parameters to filter results
|
|
878
|
-
* @param
|
|
934
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
879
935
|
* @returns Array of matching models
|
|
880
936
|
*
|
|
881
937
|
* @example
|
|
882
938
|
* ```typescript
|
|
883
|
-
* // Get all recipes (uses
|
|
939
|
+
* // Get all recipes (uses SPARQL by default)
|
|
884
940
|
* const allRecipes = await Recipe.findAll(perspective);
|
|
885
941
|
*
|
|
886
|
-
* // Get recipes with specific criteria (uses
|
|
942
|
+
* // Get recipes with specific criteria (uses SPARQL)
|
|
887
943
|
* const recipes = await Recipe.findAll(perspective, {
|
|
888
944
|
* where: {
|
|
889
945
|
* name: "Pasta",
|
|
@@ -897,14 +953,23 @@ export class Ad4mModel {
|
|
|
897
953
|
* const recipesProlog = await Recipe.findAll(perspective, {}, false);
|
|
898
954
|
* ```
|
|
899
955
|
*/
|
|
900
|
-
static async findAll(perspective, query = {},
|
|
956
|
+
static async findAll(perspective, query = {}, engine = 'sparql') {
|
|
901
957
|
if (query.properties && query.properties.length === 0) {
|
|
902
958
|
throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
|
|
903
959
|
}
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
960
|
+
// Backward compatibility: boolean maps to sparql (true) or prolog (false)
|
|
961
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
962
|
+
? (engine ? 'sparql' : 'prolog')
|
|
963
|
+
: engine;
|
|
964
|
+
if (resolvedEngine === 'sparql') {
|
|
965
|
+
// Always use the regular SPARQL path + JS-level hydrateRelations for includes.
|
|
966
|
+
// The batch SPARQL approach had issues with sub-queries (where/order/limit on includes),
|
|
967
|
+
// non-conforming node filtering, and parse_literal compatibility.
|
|
968
|
+
// hydrateRelations handles all of these correctly via per-relation findAll calls.
|
|
969
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
970
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
971
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
972
|
+
const { results } = await this.instancesFromQueryResult(perspective, query, grouped);
|
|
908
973
|
return results;
|
|
909
974
|
}
|
|
910
975
|
else {
|
|
@@ -921,7 +986,7 @@ export class Ad4mModel {
|
|
|
921
986
|
*
|
|
922
987
|
* @param perspective - The perspective to search in
|
|
923
988
|
* @param query - Optional query parameters to filter results
|
|
924
|
-
* @param
|
|
989
|
+
* @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
|
|
925
990
|
* @returns The first matching instance, or `null`
|
|
926
991
|
*
|
|
927
992
|
* @example
|
|
@@ -934,9 +999,9 @@ export class Ad4mModel {
|
|
|
934
999
|
* }
|
|
935
1000
|
* ```
|
|
936
1001
|
*/
|
|
937
|
-
static async findOne(perspective, query = {},
|
|
1002
|
+
static async findOne(perspective, query = {}, engine = 'sparql') {
|
|
938
1003
|
const limitedQuery = { ...query, limit: 1 };
|
|
939
|
-
const results = await this.findAll(perspective, limitedQuery,
|
|
1004
|
+
const results = await this.findAll(perspective, limitedQuery, engine);
|
|
940
1005
|
return results[0] ?? null;
|
|
941
1006
|
}
|
|
942
1007
|
/**
|
|
@@ -944,7 +1009,7 @@ export class Ad4mModel {
|
|
|
944
1009
|
*
|
|
945
1010
|
* @param perspective - The perspective to search in
|
|
946
1011
|
* @param query - Optional query parameters to filter results
|
|
947
|
-
* @param
|
|
1012
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
948
1013
|
* @returns Object containing results array and total count
|
|
949
1014
|
*
|
|
950
1015
|
* @example
|
|
@@ -959,11 +1024,15 @@ export class Ad4mModel {
|
|
|
959
1024
|
* const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
|
|
960
1025
|
* ```
|
|
961
1026
|
*/
|
|
962
|
-
static async findAllAndCount(perspective, query = {},
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
1027
|
+
static async findAllAndCount(perspective, query = {}, engine = 'sparql') {
|
|
1028
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1029
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1030
|
+
: engine;
|
|
1031
|
+
if (resolvedEngine === 'sparql') {
|
|
1032
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
1033
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1034
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1035
|
+
return await this.instancesFromQueryResult(perspective, query, grouped, true);
|
|
967
1036
|
}
|
|
968
1037
|
else {
|
|
969
1038
|
const prologQuery = await this.queryToProlog(perspective, query);
|
|
@@ -978,7 +1047,7 @@ export class Ad4mModel {
|
|
|
978
1047
|
* @param pageSize - Number of items per page
|
|
979
1048
|
* @param pageNumber - Which page to retrieve (1-based)
|
|
980
1049
|
* @param query - Optional additional query parameters
|
|
981
|
-
* @param
|
|
1050
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
982
1051
|
* @returns Paginated results with metadata
|
|
983
1052
|
*
|
|
984
1053
|
* @example
|
|
@@ -992,12 +1061,16 @@ export class Ad4mModel {
|
|
|
992
1061
|
* const pageProlog = await Recipe.paginate(perspective, 10, 1, {}, false);
|
|
993
1062
|
* ```
|
|
994
1063
|
*/
|
|
995
|
-
static async paginate(perspective, pageSize, pageNumber, query,
|
|
1064
|
+
static async paginate(perspective, pageSize, pageNumber, query, engine = 'sparql') {
|
|
996
1065
|
const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1066
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1067
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1068
|
+
: engine;
|
|
1069
|
+
if (resolvedEngine === 'sparql') {
|
|
1070
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
|
|
1071
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1072
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1073
|
+
const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
|
|
1001
1074
|
return { results, totalCount, pageSize, pageNumber };
|
|
1002
1075
|
}
|
|
1003
1076
|
else {
|
|
@@ -1026,28 +1099,25 @@ export class Ad4mModel {
|
|
|
1026
1099
|
return fullQuery;
|
|
1027
1100
|
}
|
|
1028
1101
|
/**
|
|
1029
|
-
* Generates a
|
|
1102
|
+
* Generates a SPARQL COUNT query for the model.
|
|
1030
1103
|
*
|
|
1031
1104
|
* @param perspective - The perspective context
|
|
1032
1105
|
* @param query - Query parameters to filter the count
|
|
1033
|
-
* @returns
|
|
1106
|
+
* @returns SPARQL COUNT query string
|
|
1034
1107
|
*
|
|
1035
1108
|
* @private
|
|
1036
1109
|
*/
|
|
1037
|
-
static async
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
delete countQuery.limit;
|
|
1042
|
-
delete countQuery.offset;
|
|
1043
|
-
return await this.queryToSurrealQL(perspective, countQuery);
|
|
1110
|
+
static async countQueryToSPARQL(perspective, query) {
|
|
1111
|
+
const metadata = this.getModelMetadata();
|
|
1112
|
+
const allRelMeta = getRelationsMetadata(this);
|
|
1113
|
+
return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
|
|
1044
1114
|
}
|
|
1045
1115
|
/**
|
|
1046
1116
|
* Gets a count of all matching instances.
|
|
1047
1117
|
*
|
|
1048
1118
|
* @param perspective - The perspective to search in
|
|
1049
1119
|
* @param query - Optional query parameters to filter results
|
|
1050
|
-
* @param
|
|
1120
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
1051
1121
|
* @returns Total count of matching entities
|
|
1052
1122
|
*
|
|
1053
1123
|
* @example
|
|
@@ -1061,15 +1131,27 @@ export class Ad4mModel {
|
|
|
1061
1131
|
* const countProlog = await Recipe.count(perspective, {}, false);
|
|
1062
1132
|
* ```
|
|
1063
1133
|
*/
|
|
1064
|
-
static async count(perspective, query = {},
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
//
|
|
1070
|
-
//
|
|
1071
|
-
const
|
|
1072
|
-
|
|
1134
|
+
static async count(perspective, query = {}, engine = 'sparql') {
|
|
1135
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1136
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1137
|
+
: engine;
|
|
1138
|
+
if (resolvedEngine === 'sparql') {
|
|
1139
|
+
// When query has JS-only where filters (gt, between, author, timestamp, etc.),
|
|
1140
|
+
// we must fall back to full hydration + JS filtering to get accurate count.
|
|
1141
|
+
const metadata = this.getModelMetadata();
|
|
1142
|
+
const allRelMeta = getRelationsMetadata(this);
|
|
1143
|
+
if (hasJsOnlyWhereFilters(metadata, allRelMeta, query.where)) {
|
|
1144
|
+
// Fall back to full query + JS filter path for accurate count
|
|
1145
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
1146
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1147
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1148
|
+
const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped, true);
|
|
1149
|
+
return totalCount;
|
|
1150
|
+
}
|
|
1151
|
+
// No JS-only filters — use efficient COUNT query
|
|
1152
|
+
const countSparql = await this.countQueryToSPARQL(perspective, query);
|
|
1153
|
+
const countResult = await perspective.querySparql(countSparql);
|
|
1154
|
+
return parseSparqlCount(countResult) ?? 0;
|
|
1073
1155
|
}
|
|
1074
1156
|
else {
|
|
1075
1157
|
const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
|
|
@@ -1086,7 +1168,7 @@ export class Ad4mModel {
|
|
|
1086
1168
|
const actions = this.generatePropertySetterAction(key, metadata);
|
|
1087
1169
|
// Get resolve language from metadata (replaces Prolog query)
|
|
1088
1170
|
let resolveLanguage = metadata.resolveLanguage;
|
|
1089
|
-
// Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal
|
|
1171
|
+
// Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
|
|
1090
1172
|
if (value === undefined || value === null || value === "") {
|
|
1091
1173
|
return;
|
|
1092
1174
|
}
|
|
@@ -1357,6 +1439,61 @@ export class Ad4mModel {
|
|
|
1357
1439
|
}
|
|
1358
1440
|
}
|
|
1359
1441
|
}
|
|
1442
|
+
/**
|
|
1443
|
+
* Evaluate SPARQL getters for a batch of instances on demand.
|
|
1444
|
+
*
|
|
1445
|
+
* Use after a shallow collection query (the default) to resolve
|
|
1446
|
+
* getter-backed properties for visible items only. This avoids the
|
|
1447
|
+
* O(N × getters) cost of evaluating every getter on every instance in
|
|
1448
|
+
* a large collection query.
|
|
1449
|
+
*
|
|
1450
|
+
* @param instances - Array of model instances to evaluate getters on
|
|
1451
|
+
* @param perspective - The perspective to query against
|
|
1452
|
+
* @param propertyNames - Optional list of getter-backed property names to evaluate.
|
|
1453
|
+
* If omitted, all getters are evaluated.
|
|
1454
|
+
*
|
|
1455
|
+
* @example
|
|
1456
|
+
* ```typescript
|
|
1457
|
+
* const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
|
|
1458
|
+
* // messages[i].replyingTo is undefined (getter skipped by default)
|
|
1459
|
+
*
|
|
1460
|
+
* // Evaluate getters for the visible subset
|
|
1461
|
+
* await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
|
|
1462
|
+
* // messages[0..9].replyingTo is now populated
|
|
1463
|
+
* ```
|
|
1464
|
+
*/
|
|
1465
|
+
static async evaluateGetters(instances, perspective, propertyNames) {
|
|
1466
|
+
if (instances.length === 0)
|
|
1467
|
+
return;
|
|
1468
|
+
const metadata = this.getModelMetadata();
|
|
1469
|
+
const opts = propertyNames && propertyNames.length > 0
|
|
1470
|
+
? { requestedProperties: propertyNames }
|
|
1471
|
+
: undefined;
|
|
1472
|
+
// Determine which property names will actually be evaluated
|
|
1473
|
+
const evaluatedPropertyNames = [];
|
|
1474
|
+
for (const [propName, propMeta] of Object.entries(metadata.properties)) {
|
|
1475
|
+
if (propMeta.getter) {
|
|
1476
|
+
if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(propName)) {
|
|
1477
|
+
evaluatedPropertyNames.push(propName);
|
|
1478
|
+
}
|
|
1479
|
+
}
|
|
1480
|
+
}
|
|
1481
|
+
for (const instance of instances) {
|
|
1482
|
+
await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
|
|
1483
|
+
// Sync snapshot so isDirty() doesn't flag getter-only changes.
|
|
1484
|
+
// evaluateGetters() mutates instances in place, but their snapshots
|
|
1485
|
+
// were already taken during hydration. Without this sync, the computed
|
|
1486
|
+
// getter values would make isDirty() return true and save() would try
|
|
1487
|
+
// to write read-only computed properties.
|
|
1488
|
+
const modelInstance = instance;
|
|
1489
|
+
if (modelInstance._snapshot) {
|
|
1490
|
+
for (const propName of evaluatedPropertyNames) {
|
|
1491
|
+
const val = instance[propName];
|
|
1492
|
+
modelInstance._snapshot[propName] = normalizeValue(Array.isArray(val) ? [...val] : val);
|
|
1493
|
+
}
|
|
1494
|
+
}
|
|
1495
|
+
}
|
|
1496
|
+
}
|
|
1360
1497
|
/**
|
|
1361
1498
|
* Gets the model instance with all properties and relations populated.
|
|
1362
1499
|
*
|