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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/lib/index.cjs +1060 -147
  2. package/lib/index.js +1054 -147
  3. package/lib/src/index.d.ts +0 -1
  4. package/lib/src/index.js +0 -1
  5. package/lib/src/language/Language.d.ts +26 -214
  6. package/lib/src/language/Language.js +28 -2
  7. package/lib/src/model/Ad4mModel.d.ts +25 -1
  8. package/lib/src/model/Ad4mModel.js +139 -30
  9. package/lib/src/model/Ad4mModel.test.js +214 -32
  10. package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
  11. package/lib/src/model/ModelQueryBuilder.js +62 -18
  12. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  13. package/lib/src/model/hydration-batching.test.js +456 -0
  14. package/lib/src/model/hydration.d.ts +1 -0
  15. package/lib/src/model/hydration.js +279 -70
  16. package/lib/src/model/query-sparql.d.ts +78 -1
  17. package/lib/src/model/query-sparql.js +447 -16
  18. package/lib/src/model/query-sparql.test.d.ts +1 -0
  19. package/lib/src/model/query-sparql.test.js +495 -0
  20. package/lib/src/model/query-utils.js +4 -0
  21. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  22. package/lib/src/model/subscription-delta.test.js +180 -0
  23. package/lib/src/model/subscription-pool.js +48 -2
  24. package/lib/src/model/types.d.ts +49 -1
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
  26. package/lib/src/perspectives/PerspectiveClient.js +37 -9
  27. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  28. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  29. package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
  30. package/lib/src/perspectives/PerspectiveProxy.js +15 -0
  31. package/package.json +1 -1
  32. package/src/Ad4mClient.test.ts +56 -1
  33. package/src/index.ts +0 -1
  34. package/src/language/Language.ts +54 -275
  35. package/src/model/Ad4mModel.test.ts +222 -35
  36. package/src/model/Ad4mModel.ts +144 -30
  37. package/src/model/ModelQueryBuilder.ts +66 -18
  38. package/src/model/hydration-batching.test.ts +563 -0
  39. package/src/model/hydration.ts +249 -47
  40. package/src/model/query-sparql.test.ts +568 -0
  41. package/src/model/query-sparql.ts +473 -16
  42. package/src/model/query-utils.ts +4 -0
  43. package/src/model/subscription-delta.test.ts +207 -0
  44. package/src/model/subscription-pool.ts +50 -2
  45. package/src/model/types.ts +50 -1
  46. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  47. package/src/perspectives/PerspectiveClient.ts +36 -7
  48. package/src/perspectives/PerspectiveProxy.ts +18 -0
  49. package/lib/src/model/query-surreal.d.ts +0 -44
  50. package/lib/src/model/query-surreal.js +0 -249
  51. package/lib/src/model/surreal-utils.d.ts +0 -42
  52. package/lib/src/model/surreal-utils.js +0 -128
  53. package/src/language/LanguageContext.ts +0 -37
  54. package/tsconfig-browser.json +0 -82
@@ -606,25 +606,15 @@ describe("Ad4mModel.queryToSPARQL()", () => {
606
606
 
607
607
  // ---- ORDER BY, LIMIT, OFFSET are JS post-processed ----
608
608
 
609
- it("should not include ORDER BY in SPARQL (JS post-processed)", async () => {
610
- const query = await (Recipe as any).queryToSPARQL(mockPerspective, { order: { name: "ASC" } });
609
+ it("should include ORDER BY/LIMIT/OFFSET in SPARQL pagination subquery", async () => {
610
+ const query = await (Recipe as any).queryToSPARQL(mockPerspective, { order: { name: "ASC" }, limit: 10, offset: 5 });
611
611
  const norm = normalizeQuery(query);
612
612
  expect(norm).toContain("SELECT ?source");
613
- expect(norm).not.toContain("ORDER BY");
614
- });
615
-
616
- it("should not include LIMIT in SPARQL (JS post-processed)", async () => {
617
- const query = await (Recipe as any).queryToSPARQL(mockPerspective, { limit: 10 });
618
- const norm = normalizeQuery(query);
619
- expect(norm).toContain("SELECT ?source");
620
- expect(norm).not.toContain("LIMIT");
621
- });
622
-
623
- it("should not include OFFSET in SPARQL (JS post-processed)", async () => {
624
- const query = await (Recipe as any).queryToSPARQL(mockPerspective, { offset: 5 });
625
- const norm = normalizeQuery(query);
626
- expect(norm).toContain("SELECT ?source");
627
- expect(norm).not.toContain("OFFSET");
613
+ // SPARQL-level pagination via subquery
614
+ expect(norm).toContain("ORDER BY");
615
+ expect(norm).toContain("LIMIT 10");
616
+ expect(norm).toContain("OFFSET 5");
617
+ expect(norm).toContain("SELECT DISTINCT ?source");
628
618
  });
629
619
  });
630
620
  describe("Ad4mModel.instancesFromQueryResult() and SPARQL integration", () => {
@@ -838,28 +828,26 @@ describe("Ad4mModel.instancesFromQueryResult() and SPARQL integration", () => {
838
828
  { source: "literal:recipe1", predicate: "recipe://ingredient", target: "pasta", author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" }
839
829
  ];
840
830
 
841
- mockPerspective.querySparql.mockResolvedValue(queryResults);
831
+ // First call returns data, second call returns count (for SPARQL-paginated totalCount)
832
+ mockPerspective.querySparql
833
+ .mockResolvedValueOnce(queryResults)
834
+ .mockResolvedValueOnce([{ count: 1 }]);
842
835
 
843
- const page = await Recipe.paginate(mockPerspective, 10, 1, {}, 'sparql');
836
+ // Include order to trigger SPARQL-level pagination (data + count queries)
837
+ const page = await Recipe.paginate(mockPerspective, 10, 1, { order: { name: 'ASC' as const } }, 'sparql');
844
838
 
845
- expect(mockPerspective.querySparql).toHaveBeenCalledTimes(1);
839
+ // paginate now issues 2 SPARQL queries: data + count
840
+ expect(mockPerspective.querySparql).toHaveBeenCalledTimes(2);
846
841
  expect(mockPerspective.infer).not.toHaveBeenCalled();
847
842
  expect(page.results).toHaveLength(1);
848
843
  expect(page.pageSize).toBe(10);
849
844
  expect(page.pageNumber).toBe(1);
845
+ expect(page.totalCount).toBe(1);
850
846
  });
851
847
 
852
848
  it("should use SPARQL when engine is 'sparql' in count()", async () => {
853
- // Since count() uses result.length and GROUP BY returns one row per source,
854
- // mock 5 recipe sources
855
- const queryResults = [
856
- ...Array.from({ length: 5 }, (_, i) => [
857
- { source: `literal:recipe${i+1}`, predicate: "recipe://name", target: `Recipe ${i+1}`, author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" },
858
- { source: `literal:recipe${i+1}`, predicate: "recipe://rating", target: "5", author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" }
859
- ]).flat()
860
- ];
861
-
862
- mockPerspective.querySparql.mockResolvedValue(queryResults);
849
+ // count() now uses an efficient COUNT query that returns [{ count: N }]
850
+ mockPerspective.querySparql.mockResolvedValue([{ count: 5 }]);
863
851
 
864
852
  const count = await Recipe.count(mockPerspective, {}, 'sparql');
865
853
 
@@ -1970,26 +1958,28 @@ describe("Push-down FILTER for literal equality", () => {
1970
1958
 
1971
1959
  const normalizeQuery = (q: string) => q.replace(/\s+/g, " ").trim();
1972
1960
 
1973
- it("SPARQL query for where: { name: 'Alice' } should add JOIN but NOT parse_literal FILTER", async () => {
1961
+ it("SPARQL query for where: { name: 'Alice' } should use <ad4m://fn/parse_literal> FILTER", async () => {
1974
1962
  const query = await (FilterTest as any).queryToSPARQL(mockPerspective, { where: { name: "Alice" } });
1975
1963
  const norm = normalizeQuery(query);
1976
- // JOIN pattern exists (ensures property is present for JS post-filter)
1964
+ // JOIN pattern exists
1977
1965
  expect(norm).toContain("?wTarget_name");
1978
- // No parse_literal FILTER — custom fn:: functions aren't valid in parsed SPARQL
1966
+ // parse_literal push-down FILTER is present (using correct SPARQL IRI syntax)
1967
+ expect(norm).toContain("ad4m://fn/parse_literal");
1979
1968
  expect(norm).not.toContain("fn::parse_literal");
1980
1969
  });
1981
1970
 
1982
- it("SPARQL query for where: { name: ['Alice', 'Bob'] } should add JOIN but NOT parse_literal FILTER", async () => {
1971
+ it("SPARQL query for where: { name: ['Alice', 'Bob'] } should use <ad4m://fn/parse_literal> IN FILTER", async () => {
1983
1972
  const query = await (FilterTest as any).queryToSPARQL(mockPerspective, { where: { name: ["Alice", "Bob"] } });
1984
1973
  const norm = normalizeQuery(query);
1985
1974
  expect(norm).toContain("?wTarget_name");
1975
+ expect(norm).toContain("ad4m://fn/parse_literal");
1986
1976
  expect(norm).not.toContain("fn::parse_literal");
1987
1977
  });
1988
1978
 
1989
1979
  it("SPARQL query for where: { rating: { gt: 5 } } should NOT include parse_literal FILTER", async () => {
1990
1980
  const query = await (FilterTest as any).queryToSPARQL(mockPerspective, { where: { rating: { gt: 5 } } });
1991
1981
  const norm = normalizeQuery(query);
1992
- expect(norm).not.toContain("fn::parse_literal");
1982
+ expect(norm).not.toContain("parse_literal");
1993
1983
  });
1994
1984
 
1995
1985
  it("literal property where clause adds JOIN for JS post-filter", async () => {
@@ -2407,3 +2397,200 @@ describe("Lazy Conformance Filters", () => {
2407
2397
  expect(shacl.name).toBe("LazyParent2");
2408
2398
  });
2409
2399
  });
2400
+
2401
+ // ──────────────────────────────────────────────────────────
2402
+ // instancesFromQueryResult — SPARQL vs JS pagination behaviour
2403
+ // ──────────────────────────────────────────────────────────
2404
+
2405
+ describe("instancesFromQueryResult — SPARQL vs JS pagination", () => {
2406
+ @Model({ name: "PaginationTestChannel" })
2407
+ class PaginationTestChannel extends Ad4mModel {
2408
+ @Flag({ through: "flux://entry_type", value: "flux://channel" })
2409
+ type: string = "";
2410
+
2411
+ @Property({ through: "flux://name", resolveLanguage: "literal" })
2412
+ name: string = "";
2413
+ }
2414
+
2415
+ const mockPerspective: any = {
2416
+ uuid: "test-uuid",
2417
+ querySparql: jest.fn().mockResolvedValue([]),
2418
+ get: jest.fn().mockResolvedValue([]),
2419
+ getExpression: jest.fn().mockResolvedValue(null),
2420
+ };
2421
+
2422
+ it("does NOT slice results when SPARQL pagination was applied", async () => {
2423
+ const grouped = Array.from({ length: 5 }, (_, i) => ({
2424
+ source_uri: `flux://ch-${i}`,
2425
+ links: [
2426
+ { predicate: "flux://entry_type", target: "flux://channel", author: "did:key:a", timestamp: String(1000 + i) },
2427
+ { predicate: "flux://name", target: `literal:string:Channel${i}`, author: "did:key:a", timestamp: String(1000 + i) },
2428
+ ],
2429
+ }));
2430
+
2431
+ // Include order to trigger SPARQL-level pagination (subquery with ORDER BY)
2432
+ const query = { limit: 5, offset: 10, order: { name: 'ASC' as const } };
2433
+ const result = await (PaginationTestChannel as any).instancesFromQueryResult(mockPerspective, query, grouped);
2434
+
2435
+ // sparqlPaginated = true (limit+offset+order present, no JS-only where filters),
2436
+ // so JS should NOT re-slice — all 5 items come through as-is.
2437
+ expect(result.results.length).toBe(5);
2438
+ expect(result.totalCount).toBe(5);
2439
+ });
2440
+
2441
+ it("applies JS-level slicing as fallback when JS-only filters exist", async () => {
2442
+ const grouped = Array.from({ length: 10 }, (_, i) => ({
2443
+ source_uri: `flux://ch-${i}`,
2444
+ links: [
2445
+ { predicate: "flux://entry_type", target: "flux://channel", author: "did:key:a", timestamp: String(1000 + i) },
2446
+ { predicate: "flux://name", target: `literal:string:Ch${i}`, author: "did:key:a", timestamp: String(1000 + i) },
2447
+ ],
2448
+ }));
2449
+
2450
+ const query = { limit: 3, offset: 0, where: { author: "did:key:a" } };
2451
+ const result = await (PaginationTestChannel as any).instancesFromQueryResult(mockPerspective, query, grouped);
2452
+ expect(result.results.length).toBe(3);
2453
+ });
2454
+ });
2455
+
2456
+ // ──────────────────────────────────────────────────────────
2457
+ // deepQuery opt-in — getter evaluation on collection queries
2458
+ // ──────────────────────────────────────────────────────────
2459
+
2460
+ describe("deepQuery opt-in — getter evaluation", () => {
2461
+ @Model({ name: "DeepQueryTestMessage" })
2462
+ class DeepQueryTestMessage extends Ad4mModel {
2463
+ @Flag({ through: "flux://entry_type", value: "flux://message" })
2464
+ type: string = "";
2465
+
2466
+ @Property({ through: "flux://body", resolveLanguage: "literal" })
2467
+ body: string = "";
2468
+
2469
+ @Property({
2470
+ through: "flux://has_reply",
2471
+ getter: `SELECT ?target WHERE { ?source <flux://has_reply> ?target . } LIMIT 1`,
2472
+ })
2473
+ replyingTo?: string;
2474
+
2475
+ @ReadOnly({
2476
+ through: "flux://is_popular",
2477
+ getter: `ASK WHERE { ?source <flux://is_popular> "true" . }`,
2478
+ })
2479
+ isPopular: boolean = false;
2480
+
2481
+ @HasMany({ through: "flux://reaction" })
2482
+ reactions: string[] = [];
2483
+ }
2484
+
2485
+ let sparqlCalls: string[];
2486
+ const mockPerspective: any = {
2487
+ uuid: "test-uuid",
2488
+ querySparql: jest.fn(async (q: string) => {
2489
+ sparqlCalls.push(q);
2490
+ return [];
2491
+ }),
2492
+ get: jest.fn().mockResolvedValue([]),
2493
+ getExpression: jest.fn().mockResolvedValue(null),
2494
+ stringOrTemplateObjectToSubjectClassName: jest.fn().mockResolvedValue("DeepQueryTestMessage"),
2495
+ };
2496
+
2497
+ beforeEach(() => {
2498
+ sparqlCalls = [];
2499
+ mockPerspective.querySparql.mockClear();
2500
+ mockPerspective.get.mockClear();
2501
+ });
2502
+
2503
+ function makeMessageRows(count: number) {
2504
+ return Array.from({ length: count }, (_, i) => ({
2505
+ source_uri: `flux://msg-${i}`,
2506
+ links: [
2507
+ { predicate: "flux://entry_type", target: "flux://message", author: "did:key:a", timestamp: String(2000 + i) },
2508
+ { predicate: "flux://body", target: `literal:string:Hello${i}`, author: "did:key:a", timestamp: String(2000 + i) },
2509
+ ],
2510
+ }));
2511
+ }
2512
+
2513
+ it("skips getter evaluation on collection queries by default", async () => {
2514
+ const grouped = makeMessageRows(5);
2515
+ const result = await (DeepQueryTestMessage as any).instancesFromQueryResult(mockPerspective, {}, grouped);
2516
+ expect(result.results.length).toBe(5);
2517
+
2518
+ const getterCalls = sparqlCalls.filter(
2519
+ (q) => q.includes("flux://has_reply") || q.includes("flux://is_popular")
2520
+ );
2521
+ expect(getterCalls.length).toBe(0);
2522
+ });
2523
+
2524
+ it("evaluates getter properties when deepQuery is true", async () => {
2525
+ const grouped = makeMessageRows(3);
2526
+ const result = await (DeepQueryTestMessage as any).instancesFromQueryResult(mockPerspective, { deepQuery: true }, grouped);
2527
+ expect(result.results.length).toBe(3);
2528
+
2529
+ const getterCalls = sparqlCalls.filter(
2530
+ (q) => q.includes("flux://has_reply") || q.includes("flux://is_popular")
2531
+ );
2532
+ expect(getterCalls.length).toBe(6); // 3 instances × 2 getters
2533
+ });
2534
+
2535
+ it("single-instance get() still evaluates getters by default", async () => {
2536
+ const instance = new DeepQueryTestMessage(mockPerspective, "flux://msg-single");
2537
+ mockPerspective.querySparql.mockImplementation(async (q: string) => {
2538
+ sparqlCalls.push(q);
2539
+ if (q.includes("flux://msg-single") && !q.includes("flux://has_reply") && !q.includes("flux://is_popular")) {
2540
+ return [
2541
+ { source: "flux://msg-single", predicate: "flux://entry_type", target: "flux://message", author: "did:key:a", timestamp: "3000" },
2542
+ { source: "flux://msg-single", predicate: "flux://body", target: "literal:string:Hello", author: "did:key:a", timestamp: "3000" },
2543
+ ];
2544
+ }
2545
+ return [];
2546
+ });
2547
+
2548
+ await instance.get();
2549
+ const getterCalls = sparqlCalls.filter(
2550
+ (q) => q.includes("flux://has_reply") || q.includes("flux://is_popular")
2551
+ );
2552
+ expect(getterCalls.length).toBe(2);
2553
+ });
2554
+
2555
+ describe("Ad4mModel.evaluateGetters()", () => {
2556
+ it("resolves getters for a batch of instances", async () => {
2557
+ const grouped = makeMessageRows(4);
2558
+ const result = await (DeepQueryTestMessage as any).instancesFromQueryResult(mockPerspective, {}, grouped);
2559
+ sparqlCalls = [];
2560
+
2561
+ await DeepQueryTestMessage.evaluateGetters(result.results.slice(0, 2), mockPerspective, ["replyingTo"]);
2562
+
2563
+ const replyCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply"));
2564
+ expect(replyCalls.length).toBe(2);
2565
+ const popularCalls = sparqlCalls.filter((q) => q.includes("flux://is_popular"));
2566
+ expect(popularCalls.length).toBe(0);
2567
+ });
2568
+
2569
+ it("evaluates all getters when propertyNames is omitted", async () => {
2570
+ const grouped = makeMessageRows(2);
2571
+ const result = await (DeepQueryTestMessage as any).instancesFromQueryResult(mockPerspective, {}, grouped);
2572
+ sparqlCalls = [];
2573
+
2574
+ await DeepQueryTestMessage.evaluateGetters(result.results, mockPerspective);
2575
+
2576
+ const replyCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply"));
2577
+ const popularCalls = sparqlCalls.filter((q) => q.includes("flux://is_popular"));
2578
+ expect(replyCalls.length).toBe(2);
2579
+ expect(popularCalls.length).toBe(2);
2580
+ });
2581
+
2582
+ it("handles empty array gracefully", async () => {
2583
+ sparqlCalls = [];
2584
+ await DeepQueryTestMessage.evaluateGetters([], mockPerspective);
2585
+ expect(sparqlCalls.length).toBe(0);
2586
+ });
2587
+ });
2588
+
2589
+ describe("deepQuery via ModelQueryBuilder", () => {
2590
+ it("deepQuery() method sets deepQuery flag on queryParams", () => {
2591
+ const builder = DeepQueryTestMessage.query(mockPerspective);
2592
+ (builder as any).deepQuery();
2593
+ expect((builder as any).queryParams.deepQuery).toBe(true);
2594
+ });
2595
+ });
2596
+ });
@@ -11,7 +11,7 @@ import { buildParentQuery, buildAuthorAndTimestampQuery, buildPropertiesQuery, b
11
11
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
12
12
  import type { JSONSchemaProperty, JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
13
13
 
14
- import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults } from "./query-sparql";
14
+ import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults, buildSPARQLCountQuery, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
15
15
  import { buildBatchSPARQLQuery } from "./query-sparql-batch";
16
16
  import { hydrateBatchResult } from "./hydration-batch";
17
17
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
@@ -793,7 +793,8 @@ export class Ad4mModel {
793
793
  this: typeof Ad4mModel & (new (...args: any[]) => T),
794
794
  perspective: PerspectiveProxy,
795
795
  query: Query,
796
- result: any[]
796
+ result: any[],
797
+ computeTotalCount: boolean = false
797
798
  ): Promise<ResultsWithTotalCount<T>> {
798
799
  if (!result || result.length === 0) return { results: [], totalCount: 0 };
799
800
 
@@ -874,19 +875,39 @@ export class Ad4mModel {
874
875
  );
875
876
  }
876
877
 
877
- // Evaluate custom getters for all instances (single pass)
878
- const getterOpts = requestedProperties.length > 0 || query.include
879
- ? { requestedProperties, include: query.include }
880
- : undefined;
881
- for (const instance of instances) {
882
- 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
+ }
883
903
  }
884
904
 
885
905
  // Filter by where conditions that couldn't be filtered in SPARQL
886
906
  // This includes:
887
907
  // - author/timestamp (computed from grouped links)
888
908
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
889
- // because fn::parse_literal() comparisons in SPARQL 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.
890
911
  // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
891
912
  // which require reverse-link resolution before filtering
892
913
  let filteredInstances = instances;
@@ -915,9 +936,9 @@ export class Ad4mModel {
915
936
  continue;
916
937
  }
917
938
 
918
- // Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
919
- // SPARQL-level filtering with parse_literal is unreliable across environments,
920
- // so we do all property filtering here after hydration resolves values.
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.
921
942
  if (!matchesCondition(instance[propertyName], condition)) {
922
943
  return false;
923
944
  }
@@ -930,7 +951,7 @@ export class Ad4mModel {
930
951
  // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
931
952
  // This ensures consistent pagination behavior
932
953
  const effectiveOrder = query.order ||
933
- (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' as 'ASC' } : null);
954
+ (query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' as 'ASC' } : null);
934
955
 
935
956
  if (effectiveOrder) {
936
957
  const orderEntries = Object.entries(effectiveOrder);
@@ -964,12 +985,37 @@ export class Ad4mModel {
964
985
  });
965
986
  }
966
987
 
967
- // Calculate totalCount BEFORE applying limit/offset
968
- 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
+ }
969
1013
 
970
- // 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.
971
1017
  let paginatedInstances = filteredInstances;
972
- if (query.offset !== undefined || query.limit !== undefined) {
1018
+ if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
973
1019
  const start = query.offset || 0;
974
1020
  const end = query.limit ? start + query.limit : undefined;
975
1021
  paginatedInstances = filteredInstances.slice(start, end);
@@ -1145,7 +1191,7 @@ export class Ad4mModel {
1145
1191
  const sparqlQuery = await this.queryToSPARQL(perspective, query);
1146
1192
  const rawResult = await perspective.querySparql(sparqlQuery);
1147
1193
  const grouped = groupSPARQLResults(rawResult);
1148
- return await this.instancesFromQueryResult(perspective, query, grouped);
1194
+ return await this.instancesFromQueryResult(perspective, query, grouped, true);
1149
1195
  } else {
1150
1196
  const prologQuery = await this.queryToProlog(perspective, query);
1151
1197
  const result = await perspective.infer(prologQuery);
@@ -1191,7 +1237,7 @@ export class Ad4mModel {
1191
1237
  const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
1192
1238
  const rawResult = await perspective.querySparql(sparqlQuery);
1193
1239
  const grouped = groupSPARQLResults(rawResult);
1194
- const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
1240
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
1195
1241
  return { results, totalCount, pageSize, pageNumber };
1196
1242
  } else {
1197
1243
  const prologQuery = await this.queryToProlog(perspective, paginationQuery);
@@ -1232,12 +1278,9 @@ export class Ad4mModel {
1232
1278
  * @private
1233
1279
  */
1234
1280
  public static async countQueryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
1235
- // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
1236
- // We'll count the number of rows returned (one row per source)
1237
- const countQuery = { ...query };
1238
- delete countQuery.limit;
1239
- delete countQuery.offset;
1240
- return await this.queryToSPARQL(perspective, countQuery);
1281
+ const metadata = this.getModelMetadata();
1282
+ const allRelMeta = getRelationsMetadata(this as any);
1283
+ return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
1241
1284
  }
1242
1285
 
1243
1286
  /**
@@ -1265,11 +1308,21 @@ export class Ad4mModel {
1265
1308
  : engine;
1266
1309
 
1267
1310
  if (resolvedEngine === 'sparql') {
1268
- const sparqlQuery = await this.queryToSPARQL(perspective, query);
1269
- const rawResult = await perspective.querySparql(sparqlQuery);
1270
- const grouped = groupSPARQLResults(rawResult);
1271
- const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
1272
- return totalCount;
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;
1273
1326
  } else {
1274
1327
  const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
1275
1328
  return result?.[0]?.TotalCount || 0;
@@ -1605,6 +1658,67 @@ export class Ad4mModel {
1605
1658
  }
1606
1659
  }
1607
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
+
1608
1722
  /**
1609
1723
  * Gets the model instance with all properties and relations populated.
1610
1724
  *