@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
@@ -619,23 +619,15 @@ describe("Ad4mModel.queryToSPARQL()", () => {
619
619
  expect(norm).toContain("&&");
620
620
  });
621
621
  // ---- ORDER BY, LIMIT, OFFSET are JS post-processed ----
622
- it("should not include ORDER BY in SPARQL (JS post-processed)", async () => {
623
- const query = await Recipe.queryToSPARQL(mockPerspective, { order: { name: "ASC" } });
622
+ it("should include ORDER BY/LIMIT/OFFSET in SPARQL pagination subquery", async () => {
623
+ const query = await Recipe.queryToSPARQL(mockPerspective, { order: { name: "ASC" }, limit: 10, offset: 5 });
624
624
  const norm = normalizeQuery(query);
625
625
  expect(norm).toContain("SELECT ?source");
626
- expect(norm).not.toContain("ORDER BY");
627
- });
628
- it("should not include LIMIT in SPARQL (JS post-processed)", async () => {
629
- const query = await Recipe.queryToSPARQL(mockPerspective, { limit: 10 });
630
- const norm = normalizeQuery(query);
631
- expect(norm).toContain("SELECT ?source");
632
- expect(norm).not.toContain("LIMIT");
633
- });
634
- it("should not include OFFSET in SPARQL (JS post-processed)", async () => {
635
- const query = await Recipe.queryToSPARQL(mockPerspective, { offset: 5 });
636
- const norm = normalizeQuery(query);
637
- expect(norm).toContain("SELECT ?source");
638
- expect(norm).not.toContain("OFFSET");
626
+ // SPARQL-level pagination via subquery
627
+ expect(norm).toContain("ORDER BY");
628
+ expect(norm).toContain("LIMIT 10");
629
+ expect(norm).toContain("OFFSET 5");
630
+ expect(norm).toContain("SELECT DISTINCT ?source");
639
631
  });
640
632
  });
641
633
  describe("Ad4mModel.instancesFromQueryResult() and SPARQL integration", () => {
@@ -821,24 +813,23 @@ describe("Ad4mModel.instancesFromQueryResult() and SPARQL integration", () => {
821
813
  { source: "literal:recipe1", predicate: "recipe://rating", target: "5", author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" },
822
814
  { source: "literal:recipe1", predicate: "recipe://ingredient", target: "pasta", author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" }
823
815
  ];
824
- mockPerspective.querySparql.mockResolvedValue(queryResults);
825
- const page = await Recipe.paginate(mockPerspective, 10, 1, {}, 'sparql');
826
- expect(mockPerspective.querySparql).toHaveBeenCalledTimes(1);
816
+ // First call returns data, second call returns count (for SPARQL-paginated totalCount)
817
+ mockPerspective.querySparql
818
+ .mockResolvedValueOnce(queryResults)
819
+ .mockResolvedValueOnce([{ count: 1 }]);
820
+ // Include order to trigger SPARQL-level pagination (data + count queries)
821
+ const page = await Recipe.paginate(mockPerspective, 10, 1, { order: { name: 'ASC' } }, 'sparql');
822
+ // paginate now issues 2 SPARQL queries: data + count
823
+ expect(mockPerspective.querySparql).toHaveBeenCalledTimes(2);
827
824
  expect(mockPerspective.infer).not.toHaveBeenCalled();
828
825
  expect(page.results).toHaveLength(1);
829
826
  expect(page.pageSize).toBe(10);
830
827
  expect(page.pageNumber).toBe(1);
828
+ expect(page.totalCount).toBe(1);
831
829
  });
832
830
  it("should use SPARQL when engine is 'sparql' in count()", async () => {
833
- // Since count() uses result.length and GROUP BY returns one row per source,
834
- // mock 5 recipe sources
835
- const queryResults = [
836
- ...Array.from({ length: 5 }, (_, i) => [
837
- { source: `literal:recipe${i + 1}`, predicate: "recipe://name", target: `Recipe ${i + 1}`, author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" },
838
- { source: `literal:recipe${i + 1}`, predicate: "recipe://rating", target: "5", author: "did:key:alice", timestamp: "2023-01-01T00:00:00Z" }
839
- ]).flat()
840
- ];
841
- mockPerspective.querySparql.mockResolvedValue(queryResults);
831
+ // count() now uses an efficient COUNT query that returns [{ count: N }]
832
+ mockPerspective.querySparql.mockResolvedValue([{ count: 5 }]);
842
833
  const count = await Recipe.count(mockPerspective, {}, 'sparql');
843
834
  expect(mockPerspective.querySparql).toHaveBeenCalledTimes(1);
844
835
  expect(mockPerspective.infer).not.toHaveBeenCalled();
@@ -1889,24 +1880,26 @@ describe("Push-down FILTER for literal equality", () => {
1889
1880
  Model({ name: "FilterTest" })
1890
1881
  ], FilterTest);
1891
1882
  const normalizeQuery = (q) => q.replace(/\s+/g, " ").trim();
1892
- it("SPARQL query for where: { name: 'Alice' } should add JOIN but NOT parse_literal FILTER", async () => {
1883
+ it("SPARQL query for where: { name: 'Alice' } should use <ad4m://fn/parse_literal> FILTER", async () => {
1893
1884
  const query = await FilterTest.queryToSPARQL(mockPerspective, { where: { name: "Alice" } });
1894
1885
  const norm = normalizeQuery(query);
1895
- // JOIN pattern exists (ensures property is present for JS post-filter)
1886
+ // JOIN pattern exists
1896
1887
  expect(norm).toContain("?wTarget_name");
1897
- // No parse_literal FILTER — custom fn:: functions aren't valid in parsed SPARQL
1888
+ // parse_literal push-down FILTER is present (using correct SPARQL IRI syntax)
1889
+ expect(norm).toContain("ad4m://fn/parse_literal");
1898
1890
  expect(norm).not.toContain("fn::parse_literal");
1899
1891
  });
1900
- it("SPARQL query for where: { name: ['Alice', 'Bob'] } should add JOIN but NOT parse_literal FILTER", async () => {
1892
+ it("SPARQL query for where: { name: ['Alice', 'Bob'] } should use <ad4m://fn/parse_literal> IN FILTER", async () => {
1901
1893
  const query = await FilterTest.queryToSPARQL(mockPerspective, { where: { name: ["Alice", "Bob"] } });
1902
1894
  const norm = normalizeQuery(query);
1903
1895
  expect(norm).toContain("?wTarget_name");
1896
+ expect(norm).toContain("ad4m://fn/parse_literal");
1904
1897
  expect(norm).not.toContain("fn::parse_literal");
1905
1898
  });
1906
1899
  it("SPARQL query for where: { rating: { gt: 5 } } should NOT include parse_literal FILTER", async () => {
1907
1900
  const query = await FilterTest.queryToSPARQL(mockPerspective, { where: { rating: { gt: 5 } } });
1908
1901
  const norm = normalizeQuery(query);
1909
- expect(norm).not.toContain("fn::parse_literal");
1902
+ expect(norm).not.toContain("parse_literal");
1910
1903
  });
1911
1904
  it("literal property where clause adds JOIN for JS post-filter", async () => {
1912
1905
  const query = await FilterTest.queryToSPARQL(mockPerspective, { where: { name: "Alice" } });
@@ -2315,3 +2308,192 @@ describe("Lazy Conformance Filters", () => {
2315
2308
  expect(shacl.name).toBe("LazyParent2");
2316
2309
  });
2317
2310
  });
2311
+ // ──────────────────────────────────────────────────────────
2312
+ // instancesFromQueryResult — SPARQL vs JS pagination behaviour
2313
+ // ──────────────────────────────────────────────────────────
2314
+ describe("instancesFromQueryResult — SPARQL vs JS pagination", () => {
2315
+ let PaginationTestChannel = class PaginationTestChannel extends Ad4mModel {
2316
+ constructor() {
2317
+ super(...arguments);
2318
+ this.type = "";
2319
+ this.name = "";
2320
+ }
2321
+ };
2322
+ __decorate([
2323
+ Flag({ through: "flux://entry_type", value: "flux://channel" }),
2324
+ __metadata("design:type", String)
2325
+ ], PaginationTestChannel.prototype, "type", void 0);
2326
+ __decorate([
2327
+ Property({ through: "flux://name", resolveLanguage: "literal" }),
2328
+ __metadata("design:type", String)
2329
+ ], PaginationTestChannel.prototype, "name", void 0);
2330
+ PaginationTestChannel = __decorate([
2331
+ Model({ name: "PaginationTestChannel" })
2332
+ ], PaginationTestChannel);
2333
+ const mockPerspective = {
2334
+ uuid: "test-uuid",
2335
+ querySparql: jest.fn().mockResolvedValue([]),
2336
+ get: jest.fn().mockResolvedValue([]),
2337
+ getExpression: jest.fn().mockResolvedValue(null),
2338
+ };
2339
+ it("does NOT slice results when SPARQL pagination was applied", async () => {
2340
+ const grouped = Array.from({ length: 5 }, (_, i) => ({
2341
+ source_uri: `flux://ch-${i}`,
2342
+ links: [
2343
+ { predicate: "flux://entry_type", target: "flux://channel", author: "did:key:a", timestamp: String(1000 + i) },
2344
+ { predicate: "flux://name", target: `literal:string:Channel${i}`, author: "did:key:a", timestamp: String(1000 + i) },
2345
+ ],
2346
+ }));
2347
+ // Include order to trigger SPARQL-level pagination (subquery with ORDER BY)
2348
+ const query = { limit: 5, offset: 10, order: { name: 'ASC' } };
2349
+ const result = await PaginationTestChannel.instancesFromQueryResult(mockPerspective, query, grouped);
2350
+ // sparqlPaginated = true (limit+offset+order present, no JS-only where filters),
2351
+ // so JS should NOT re-slice — all 5 items come through as-is.
2352
+ expect(result.results.length).toBe(5);
2353
+ expect(result.totalCount).toBe(5);
2354
+ });
2355
+ it("applies JS-level slicing as fallback when JS-only filters exist", async () => {
2356
+ const grouped = Array.from({ length: 10 }, (_, i) => ({
2357
+ source_uri: `flux://ch-${i}`,
2358
+ links: [
2359
+ { predicate: "flux://entry_type", target: "flux://channel", author: "did:key:a", timestamp: String(1000 + i) },
2360
+ { predicate: "flux://name", target: `literal:string:Ch${i}`, author: "did:key:a", timestamp: String(1000 + i) },
2361
+ ],
2362
+ }));
2363
+ const query = { limit: 3, offset: 0, where: { author: "did:key:a" } };
2364
+ const result = await PaginationTestChannel.instancesFromQueryResult(mockPerspective, query, grouped);
2365
+ expect(result.results.length).toBe(3);
2366
+ });
2367
+ });
2368
+ // ──────────────────────────────────────────────────────────
2369
+ // deepQuery opt-in — getter evaluation on collection queries
2370
+ // ──────────────────────────────────────────────────────────
2371
+ describe("deepQuery opt-in — getter evaluation", () => {
2372
+ let DeepQueryTestMessage = class DeepQueryTestMessage extends Ad4mModel {
2373
+ constructor() {
2374
+ super(...arguments);
2375
+ this.type = "";
2376
+ this.body = "";
2377
+ this.isPopular = false;
2378
+ this.reactions = [];
2379
+ }
2380
+ };
2381
+ __decorate([
2382
+ Flag({ through: "flux://entry_type", value: "flux://message" }),
2383
+ __metadata("design:type", String)
2384
+ ], DeepQueryTestMessage.prototype, "type", void 0);
2385
+ __decorate([
2386
+ Property({ through: "flux://body", resolveLanguage: "literal" }),
2387
+ __metadata("design:type", String)
2388
+ ], DeepQueryTestMessage.prototype, "body", void 0);
2389
+ __decorate([
2390
+ Property({
2391
+ through: "flux://has_reply",
2392
+ getter: `SELECT ?target WHERE { ?source <flux://has_reply> ?target . } LIMIT 1`,
2393
+ }),
2394
+ __metadata("design:type", String)
2395
+ ], DeepQueryTestMessage.prototype, "replyingTo", void 0);
2396
+ __decorate([
2397
+ ReadOnly({
2398
+ through: "flux://is_popular",
2399
+ getter: `ASK WHERE { ?source <flux://is_popular> "true" . }`,
2400
+ }),
2401
+ __metadata("design:type", Boolean)
2402
+ ], DeepQueryTestMessage.prototype, "isPopular", void 0);
2403
+ __decorate([
2404
+ HasMany({ through: "flux://reaction" }),
2405
+ __metadata("design:type", Array)
2406
+ ], DeepQueryTestMessage.prototype, "reactions", void 0);
2407
+ DeepQueryTestMessage = __decorate([
2408
+ Model({ name: "DeepQueryTestMessage" })
2409
+ ], DeepQueryTestMessage);
2410
+ let sparqlCalls;
2411
+ const mockPerspective = {
2412
+ uuid: "test-uuid",
2413
+ querySparql: jest.fn(async (q) => {
2414
+ sparqlCalls.push(q);
2415
+ return [];
2416
+ }),
2417
+ get: jest.fn().mockResolvedValue([]),
2418
+ getExpression: jest.fn().mockResolvedValue(null),
2419
+ stringOrTemplateObjectToSubjectClassName: jest.fn().mockResolvedValue("DeepQueryTestMessage"),
2420
+ };
2421
+ beforeEach(() => {
2422
+ sparqlCalls = [];
2423
+ mockPerspective.querySparql.mockClear();
2424
+ mockPerspective.get.mockClear();
2425
+ });
2426
+ function makeMessageRows(count) {
2427
+ return Array.from({ length: count }, (_, i) => ({
2428
+ source_uri: `flux://msg-${i}`,
2429
+ links: [
2430
+ { predicate: "flux://entry_type", target: "flux://message", author: "did:key:a", timestamp: String(2000 + i) },
2431
+ { predicate: "flux://body", target: `literal:string:Hello${i}`, author: "did:key:a", timestamp: String(2000 + i) },
2432
+ ],
2433
+ }));
2434
+ }
2435
+ it("skips getter evaluation on collection queries by default", async () => {
2436
+ const grouped = makeMessageRows(5);
2437
+ const result = await DeepQueryTestMessage.instancesFromQueryResult(mockPerspective, {}, grouped);
2438
+ expect(result.results.length).toBe(5);
2439
+ const getterCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply") || q.includes("flux://is_popular"));
2440
+ expect(getterCalls.length).toBe(0);
2441
+ });
2442
+ it("evaluates getter properties when deepQuery is true", async () => {
2443
+ const grouped = makeMessageRows(3);
2444
+ const result = await DeepQueryTestMessage.instancesFromQueryResult(mockPerspective, { deepQuery: true }, grouped);
2445
+ expect(result.results.length).toBe(3);
2446
+ const getterCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply") || q.includes("flux://is_popular"));
2447
+ expect(getterCalls.length).toBe(6); // 3 instances × 2 getters
2448
+ });
2449
+ it("single-instance get() still evaluates getters by default", async () => {
2450
+ const instance = new DeepQueryTestMessage(mockPerspective, "flux://msg-single");
2451
+ mockPerspective.querySparql.mockImplementation(async (q) => {
2452
+ sparqlCalls.push(q);
2453
+ if (q.includes("flux://msg-single") && !q.includes("flux://has_reply") && !q.includes("flux://is_popular")) {
2454
+ return [
2455
+ { source: "flux://msg-single", predicate: "flux://entry_type", target: "flux://message", author: "did:key:a", timestamp: "3000" },
2456
+ { source: "flux://msg-single", predicate: "flux://body", target: "literal:string:Hello", author: "did:key:a", timestamp: "3000" },
2457
+ ];
2458
+ }
2459
+ return [];
2460
+ });
2461
+ await instance.get();
2462
+ const getterCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply") || q.includes("flux://is_popular"));
2463
+ expect(getterCalls.length).toBe(2);
2464
+ });
2465
+ describe("Ad4mModel.evaluateGetters()", () => {
2466
+ it("resolves getters for a batch of instances", async () => {
2467
+ const grouped = makeMessageRows(4);
2468
+ const result = await DeepQueryTestMessage.instancesFromQueryResult(mockPerspective, {}, grouped);
2469
+ sparqlCalls = [];
2470
+ await DeepQueryTestMessage.evaluateGetters(result.results.slice(0, 2), mockPerspective, ["replyingTo"]);
2471
+ const replyCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply"));
2472
+ expect(replyCalls.length).toBe(2);
2473
+ const popularCalls = sparqlCalls.filter((q) => q.includes("flux://is_popular"));
2474
+ expect(popularCalls.length).toBe(0);
2475
+ });
2476
+ it("evaluates all getters when propertyNames is omitted", async () => {
2477
+ const grouped = makeMessageRows(2);
2478
+ const result = await DeepQueryTestMessage.instancesFromQueryResult(mockPerspective, {}, grouped);
2479
+ sparqlCalls = [];
2480
+ await DeepQueryTestMessage.evaluateGetters(result.results, mockPerspective);
2481
+ const replyCalls = sparqlCalls.filter((q) => q.includes("flux://has_reply"));
2482
+ const popularCalls = sparqlCalls.filter((q) => q.includes("flux://is_popular"));
2483
+ expect(replyCalls.length).toBe(2);
2484
+ expect(popularCalls.length).toBe(2);
2485
+ });
2486
+ it("handles empty array gracefully", async () => {
2487
+ sparqlCalls = [];
2488
+ await DeepQueryTestMessage.evaluateGetters([], mockPerspective);
2489
+ expect(sparqlCalls.length).toBe(0);
2490
+ });
2491
+ });
2492
+ describe("deepQuery via ModelQueryBuilder", () => {
2493
+ it("deepQuery() method sets deepQuery flag on queryParams", () => {
2494
+ const builder = DeepQueryTestMessage.query(mockPerspective);
2495
+ builder.deepQuery();
2496
+ expect(builder.queryParams.deepQuery).toBe(true);
2497
+ });
2498
+ });
2499
+ });
@@ -158,6 +158,25 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
158
158
  * ```
159
159
  */
160
160
  properties(properties: string[]): ModelQueryBuilder<T>;
161
+ /**
162
+ * Opts in to evaluating SPARQL property getters during collection hydration.
163
+ *
164
+ * By default, collection queries skip getter evaluation for performance.
165
+ * Call `.deepQuery()` when you need getter-backed properties in the result set.
166
+ *
167
+ * @returns The query builder for chaining
168
+ *
169
+ * @example
170
+ * ```typescript
171
+ * const messages = await Message.query(perspective)
172
+ * .parent(channel)
173
+ * .deepQuery()
174
+ * .limit(30)
175
+ * .get();
176
+ * // messages[i].replyingTo is populated
177
+ * ```
178
+ */
179
+ deepQuery(): ModelQueryBuilder<T>;
161
180
  /**
162
181
  * Specifies which relations to eager-load (hydrate into model instances).
163
182
  *
@@ -4,7 +4,8 @@
4
4
  * Allows building queries with a chainable interface and either
5
5
  * running them once or subscribing to real-time updates.
6
6
  */
7
- import { groupSPARQLResults } from "./query-sparql";
7
+ import { groupSPARQLResults, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
8
+ import { getRelationsMetadata } from "./decorators";
8
9
  import { pooledSubscribe } from "./subscription-pool";
9
10
  /** Query builder for Ad4mModel queries.
10
11
  * Allows building queries with a fluent interface and either running them once
@@ -203,6 +204,28 @@ export class ModelQueryBuilder {
203
204
  this.queryParams.properties = properties;
204
205
  return this;
205
206
  }
207
+ /**
208
+ * Opts in to evaluating SPARQL property getters during collection hydration.
209
+ *
210
+ * By default, collection queries skip getter evaluation for performance.
211
+ * Call `.deepQuery()` when you need getter-backed properties in the result set.
212
+ *
213
+ * @returns The query builder for chaining
214
+ *
215
+ * @example
216
+ * ```typescript
217
+ * const messages = await Message.query(perspective)
218
+ * .parent(channel)
219
+ * .deepQuery()
220
+ * .limit(30)
221
+ * .get();
222
+ * // messages[i].replyingTo is populated
223
+ * ```
224
+ */
225
+ deepQuery() {
226
+ this.queryParams.deepQuery = true;
227
+ return this;
228
+ }
206
229
  /**
207
230
  * Specifies which relations to eager-load (hydrate into model instances).
208
231
  *
@@ -287,9 +310,9 @@ export class ModelQueryBuilder {
287
310
  * Groups raw SPARQL results and hydrates them into model instances.
288
311
  * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
289
312
  */
290
- async processSparqlResult(rawResult, queryOverride) {
313
+ async processSparqlResult(rawResult, queryOverride, computeTotalCount = false) {
291
314
  const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
292
- return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped);
315
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped, computeTotalCount);
293
316
  }
294
317
  /**
295
318
  * Returns the first matching instance, or `null` if none match.
@@ -352,9 +375,9 @@ export class ModelQueryBuilder {
352
375
  const buildFingerprint = (results) => {
353
376
  if (results.length === 0)
354
377
  return '0:';
355
- const ids = results.map((r) => r.id || '').sort().join(',');
356
- const ts = results.map((r) => r.updatedAt || r.timestamp || '').join(',');
357
- return `${results.length}:${ids}:${ts}`;
378
+ // Must include relation data (e.g. tags) — not just id/timestamp.
379
+ // Otherwise @HasMany changes on existing instances are suppressed as duplicates.
380
+ return JSON.stringify(results, (_, v) => typeof v === 'function' ? undefined : v);
358
381
  };
359
382
  const hydrate = async (rawResult) => {
360
383
  const { results } = await this.processSparqlResult(rawResult);
@@ -416,10 +439,19 @@ export class ModelQueryBuilder {
416
439
  */
417
440
  async count() {
418
441
  if (this.engineFlag === 'sparql') {
419
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
420
- const rawResult = await this.perspective.querySparql(sparqlQuery);
421
- const { totalCount } = await this.processSparqlResult(rawResult);
422
- return totalCount;
442
+ // When query has JS-only where filters, fall back to full hydration
443
+ const metadata = this.ctor.getModelMetadata();
444
+ const allRelMeta = getRelationsMetadata(this.ctor);
445
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, this.queryParams.where)) {
446
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
447
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
448
+ const { totalCount } = await this.processSparqlResult(rawResult, undefined, true);
449
+ return totalCount;
450
+ }
451
+ // Use efficient COUNT query — no hydration
452
+ const countSparql = await this.ctor.countQueryToSPARQL(this.perspective, this.queryParams);
453
+ const countResult = await this.perspective.querySparql(countSparql);
454
+ return parseSparqlCount(countResult) ?? 0;
423
455
  }
424
456
  else {
425
457
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -479,11 +511,11 @@ export class ModelQueryBuilder {
479
511
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
480
512
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
481
513
  const processResults = async (result) => {
482
- const { totalCount } = await this.processSparqlResult(result);
514
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
483
515
  callback(totalCount);
484
516
  };
485
517
  this.currentSubscription.onResult(processResults);
486
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
518
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
487
519
  // Initial count returned via Promise — callback for updates only
488
520
  return totalCount;
489
521
  }
@@ -508,11 +540,11 @@ export class ModelQueryBuilder {
508
540
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
509
541
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
510
542
  const processResults = async (result) => {
511
- const { totalCount } = await this.processSparqlResult(result);
543
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
512
544
  callback(totalCount);
513
545
  };
514
546
  this.currentSubscription.onResult(processResults);
515
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
547
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
516
548
  // Initial count returned via Promise — callback for updates only
517
549
  return totalCount;
518
550
  }
@@ -536,7 +568,7 @@ export class ModelQueryBuilder {
536
568
  if (this.engineFlag === 'sparql') {
537
569
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
538
570
  const result = await this.perspective.querySparql(sparqlQuery);
539
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
571
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery, true);
540
572
  return { results, totalCount, pageSize, pageNumber };
541
573
  }
542
574
  else {
@@ -598,14 +630,26 @@ export class ModelQueryBuilder {
598
630
  this.dispose();
599
631
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
600
632
  if (this.engineFlag === 'sparql') {
601
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
633
+ // Subscribe to the FULL result set (no LIMIT/OFFSET) so the subscription
634
+ // detects changes anywhere in the dataset (e.g. new items beyond current page).
635
+ // Pagination is applied in JS when processing each update.
636
+ const subscriptionParams = { ...(this.queryParams || {}) };
637
+ delete subscriptionParams.limit;
638
+ delete subscriptionParams.offset;
639
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, subscriptionParams);
602
640
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
641
+ // Query for processSparqlResult has NO limit/offset — gets all results, totalCount via count:true
642
+ const fullQuery = { ...(this.queryParams || {}), count: true };
603
643
  const processResults = async (result) => {
604
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
644
+ const { results: allResults, totalCount } = await this.processSparqlResult(result, fullQuery, true);
645
+ const start = pageSize * (pageNumber - 1);
646
+ const results = allResults.slice(start, start + pageSize);
605
647
  callback({ results, totalCount, pageSize, pageNumber });
606
648
  };
607
649
  this.currentSubscription.onResult(processResults);
608
- const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery);
650
+ const { results: allResults, totalCount } = await this.processSparqlResult(this.currentSubscription.result, fullQuery, true);
651
+ const start = pageSize * (pageNumber - 1);
652
+ const results = allResults.slice(start, start + pageSize);
609
653
  const initialPage = { results, totalCount, pageSize, pageNumber };
610
654
  // Initial page returned via Promise — callback for subsequent updates only
611
655
  return initialPage;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Tests for batched hydrateRelations() — verifies the N+1 → 1 SPARQL optimisation.
3
+ *
4
+ * We mock PerspectiveProxy to count querySparql / get calls and verify
5
+ * that the batched path issues 1 SPARQL query instead of N perspective.get() calls.
6
+ */
7
+ export {};