@coasys/ad4m 0.12.1-dev → 0.13.0-test-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/lib/index.cjs +1469 -781
  2. package/lib/index.js +1453 -779
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +8 -1
  5. package/lib/src/agent/AgentClient.js +73 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/language/Language.d.ts +41 -3
  8. package/lib/src/model/Ad4mModel.d.ts +28 -28
  9. package/lib/src/model/Ad4mModel.js +129 -101
  10. package/lib/src/model/Ad4mModel.test.js +1543 -535
  11. package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
  12. package/lib/src/model/ModelQueryBuilder.js +163 -78
  13. package/lib/src/model/Subject.js +6 -6
  14. package/lib/src/model/decorators.d.ts +14 -8
  15. package/lib/src/model/decorators.js +41 -14
  16. package/lib/src/model/hydration-batch.d.ts +34 -0
  17. package/lib/src/model/hydration-batch.js +147 -0
  18. package/lib/src/model/hydration.d.ts +3 -3
  19. package/lib/src/model/hydration.js +106 -36
  20. package/lib/src/model/index.d.ts +4 -1
  21. package/lib/src/model/index.js +4 -1
  22. package/lib/src/model/json-schema.js +2 -2
  23. package/lib/src/model/query-cache.d.ts +30 -0
  24. package/lib/src/model/query-cache.js +66 -0
  25. package/lib/src/model/query-cache.test.d.ts +1 -0
  26. package/lib/src/model/query-cache.test.js +43 -0
  27. package/lib/src/model/query-common.d.ts +1 -1
  28. package/lib/src/model/query-common.js +1 -1
  29. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  30. package/lib/src/model/query-sparql-batch.js +260 -0
  31. package/lib/src/model/query-sparql.d.ts +47 -0
  32. package/lib/src/model/query-sparql.js +336 -0
  33. package/lib/src/model/query-utils.d.ts +45 -0
  34. package/lib/src/model/query-utils.js +140 -0
  35. package/lib/src/model/relation-filtering.test.js +15 -15
  36. package/lib/src/model/sdna.js +1 -1
  37. package/lib/src/model/shacl-gen.js +42 -18
  38. package/lib/src/model/subscription-pool.d.ts +39 -0
  39. package/lib/src/model/subscription-pool.js +119 -0
  40. package/lib/src/model/types.d.ts +3 -3
  41. package/lib/src/model/types.js +1 -1
  42. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
  43. package/lib/src/perspectives/PerspectiveClient.js +5 -57
  44. package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
  45. package/lib/src/perspectives/PerspectiveProxy.js +224 -177
  46. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  47. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  48. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  49. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  50. package/lib/src/runtime/RuntimeClient.d.ts +2 -0
  51. package/lib/src/runtime/RuntimeClient.js +17 -0
  52. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  53. package/lib/src/runtime/RuntimeResolver.js +84 -0
  54. package/lib/src/schema.gql +14 -1
  55. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  56. package/lib/src/shacl/SHACLFlow.js +9 -9
  57. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  58. package/lib/src/shacl/SHACLShape.js +38 -38
  59. package/lib/src/typeDefs.js +14 -1
  60. package/lib/src/utils.d.ts +6 -6
  61. package/lib/src/utils.js +6 -6
  62. package/package.json +1 -1
  63. package/src/Literal.test.ts +10 -5
  64. package/src/Literal.ts +6 -5
  65. package/src/agent/AgentClient.ts +81 -1
  66. package/src/expression/ExpressionRef.ts +2 -2
  67. package/src/language/Language.ts +48 -3
  68. package/src/model/Ad4mModel.test.ts +1515 -565
  69. package/src/model/Ad4mModel.ts +142 -102
  70. package/src/model/ModelQueryBuilder.ts +185 -86
  71. package/src/model/Subject.ts +6 -6
  72. package/src/model/decorators.ts +51 -22
  73. package/src/model/hydration-batch.ts +205 -0
  74. package/src/model/hydration.ts +102 -39
  75. package/src/model/index.ts +4 -1
  76. package/src/model/json-schema.ts +2 -2
  77. package/src/model/query-cache.test.ts +54 -0
  78. package/src/model/query-cache.ts +79 -0
  79. package/src/model/query-common.ts +1 -1
  80. package/src/model/query-sparql-batch.ts +301 -0
  81. package/src/model/query-sparql.ts +363 -0
  82. package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
  83. package/src/model/relation-filtering.test.ts +15 -15
  84. package/src/model/sdna.ts +1 -1
  85. package/src/model/shacl-gen.ts +42 -17
  86. package/src/model/subscription-pool.ts +163 -0
  87. package/src/model/types.ts +3 -3
  88. package/src/perspectives/PerspectiveClient.ts +5 -61
  89. package/src/perspectives/PerspectiveProxy.ts +226 -181
  90. package/src/perspectives/PerspectiveResolver.ts +0 -8
  91. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  92. package/src/runtime/RuntimeClient.ts +19 -0
  93. package/src/runtime/RuntimeResolver.ts +58 -0
  94. package/src/shacl/SHACLFlow.ts +9 -9
  95. package/src/shacl/SHACLShape.ts +39 -39
  96. package/src/utils.ts +6 -6
  97. package/src/model/query-surreal.ts +0 -280
@@ -11,6 +11,8 @@ import type {
11
11
  Where, Order, IncludeMap, Query,
12
12
  AllInstancesResult, ResultsWithTotalCount, PaginationResult,
13
13
  } from "./types";
14
+ import { groupSPARQLResults } from "./query-sparql";
15
+ import { pooledSubscribe } from "./subscription-pool";
14
16
 
15
17
  /** Query builder for Ad4mModel queries.
16
18
  * Allows building queries with a fluent interface and either running them once
@@ -38,7 +40,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
38
40
  private modelClassName: string | null = null;
39
41
  private ctor: typeof Ad4mModel;
40
42
  private currentSubscription?: any;
41
- private useSurrealDBFlag: boolean = true;
43
+ private engineFlag: 'sparql' | 'prolog' = 'sparql';
42
44
 
43
45
  constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query) {
44
46
  this.perspective = perspective;
@@ -261,32 +263,10 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
261
263
  }
262
264
 
263
265
  /**
264
- * Enables or disables SurrealDB query path.
265
- *
266
- * @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
267
- * @returns The query builder for chaining
268
- *
269
- * @example
270
- * ```typescript
271
- * // Use SurrealDB (default)
272
- * const recipes = await Recipe.query(perspective)
273
- * .where({ category: "Dessert" })
274
- * .useSurrealDB(true)
275
- * .get();
276
- *
277
- * // Use Prolog (legacy)
278
- * const recipesProlog = await Recipe.query(perspective)
279
- * .where({ category: "Dessert" })
280
- * .useSurrealDB(false)
281
- * .get();
282
- * ```
283
- *
284
- * @remarks
285
- * Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
286
- * if useSurrealDB(true) is set (default).
266
+ * Sets the query engine to use.
287
267
  */
288
- useSurrealDB(enabled: boolean = true): ModelQueryBuilder<T> {
289
- this.useSurrealDBFlag = enabled;
268
+ engine(eng: 'sparql' | 'prolog'): ModelQueryBuilder<T> {
269
+ this.engineFlag = eng;
290
270
  return this;
291
271
  }
292
272
 
@@ -304,10 +284,8 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
304
284
  */
305
285
  async get(): Promise<T[]> {
306
286
  let results: T[];
307
- if (this.useSurrealDBFlag) {
308
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
309
- const result = await this.perspective.querySurrealDB(surrealQuery);
310
- ({ results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result) as { results: T[] });
287
+ if (this.engineFlag === 'sparql') {
288
+ results = await this.executeSparqlQuery();
311
289
  } else {
312
290
  const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
313
291
  const result = await this.perspective.infer(query);
@@ -317,6 +295,32 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
317
295
  return results;
318
296
  }
319
297
 
298
+ /**
299
+ * Executes the query once using SPARQL and returns the results.
300
+ */
301
+ async getSparql(): Promise<T[]> {
302
+ return this.executeSparqlQuery();
303
+ }
304
+
305
+ /**
306
+ * Shared SPARQL query execution logic used by both get() and getSparql().
307
+ */
308
+ private async executeSparqlQuery(): Promise<T[]> {
309
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
310
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
311
+ const { results } = await this.processSparqlResult(rawResult);
312
+ return results;
313
+ }
314
+
315
+ /**
316
+ * Groups raw SPARQL results and hydrates them into model instances.
317
+ * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
318
+ */
319
+ private async processSparqlResult(rawResult: any, queryOverride?: Query): Promise<{ results: T[], totalCount: number }> {
320
+ const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
321
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped) as { results: T[], totalCount: number };
322
+ }
323
+
320
324
  /**
321
325
  * Returns the first matching instance, or `null` if none match.
322
326
  *
@@ -341,7 +345,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
341
345
  * Subscribes to the query and receives updates when results change.
342
346
  *
343
347
  * This method:
344
- * 1. Creates and initializes a SurrealDB live query subscription (default)
348
+ * 1. Creates and initializes a SPARQL live query subscription (default)
345
349
  * 2. Sets up the callback to process future updates
346
350
  * 3. Returns the initial results immediately
347
351
  *
@@ -365,8 +369,8 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
365
369
  * ```
366
370
  *
367
371
  * @remarks
368
- * By default, this uses SurrealDB live queries for real-time updates.
369
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
372
+ * By default, this uses SPARQL live queries for real-time updates.
373
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
370
374
  */
371
375
  async subscribe(callback: (results: T[]) => void): Promise<T[]> {
372
376
  // Clean up any existing subscription
@@ -374,26 +378,42 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
374
378
 
375
379
  const ctor = this.ctor;
376
380
 
377
- if (this.useSurrealDBFlag) {
378
- const surrealQuery = await ctor.queryToSurrealQL(this.perspective, this.queryParams);
379
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
381
+ if (this.engineFlag === 'sparql') {
382
+ const sparqlQuery = await ctor.queryToSPARQL(this.perspective, this.queryParams);
380
383
 
381
- const processResults = async (result: any) => {
382
- const { results } = await ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
383
- callback(results as T[]);
384
+ // Track last emitted result fingerprint to suppress duplicate callbacks
385
+ let lastResultFingerprint: string | null = null;
386
+
387
+ const buildFingerprint = (results: any[]) => {
388
+ if (results.length === 0) return '0:';
389
+ const ids = results.map((r: any) => r.id || '').sort().join(',');
390
+ const ts = results.map((r: any) => r.updatedAt || r.timestamp || '').join(',');
391
+ return `${results.length}:${ids}:${ts}`;
384
392
  };
385
393
 
386
- this.currentSubscription.onResult(processResults);
387
-
388
- // Process initial result
389
- const { results } = await ctor.instancesFromSurrealResult(
390
- this.perspective,
391
- this.queryParams,
392
- this.currentSubscription.result
394
+ const hydrate = async (rawResult: any) => {
395
+ const { results } = await this.processSparqlResult(rawResult);
396
+ return results;
397
+ };
398
+
399
+ const pooled = await pooledSubscribe(
400
+ this.perspective,
401
+ sparqlQuery,
402
+ hydrate,
403
+ (hydratedResults: T[]) => {
404
+ const fp = buildFingerprint(hydratedResults);
405
+ if (fp === lastResultFingerprint) return;
406
+ lastResultFingerprint = fp;
407
+ callback(hydratedResults);
408
+ },
393
409
  );
394
- // Also invoke callback with initial results so subscribers see them
395
- callback(results as T[]);
396
- return results as T[];
410
+
411
+ // Store dispose function as subscription
412
+ this.currentSubscription = { dispose: pooled.dispose };
413
+
414
+ const initialResults = pooled.initialResult as T[];
415
+ lastResultFingerprint = buildFingerprint(initialResults);
416
+ return initialResults;
397
417
  } else {
398
418
  const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
399
419
  this.currentSubscription = await this.perspective.subscribeInfer(query);
@@ -409,12 +429,32 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
409
429
  this.queryParams,
410
430
  this.currentSubscription.result
411
431
  );
412
- // Also invoke callback with initial results so subscribers see them
413
- callback(results as T[]);
432
+ // Initial results returned via Promise only — callback is for subsequent updates
414
433
  return results as T[];
415
434
  }
416
435
  }
417
436
 
437
+ /**
438
+ * Subscribes to the query and receives updates using SPARQL.
439
+ */
440
+ async subscribeSparql(callback: (results: T[]) => void): Promise<T[]> {
441
+ this.dispose();
442
+
443
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
444
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
445
+
446
+ const processResults = async (result: any) => {
447
+ const { results } = await this.processSparqlResult(result);
448
+ callback(results as T[]);
449
+ };
450
+
451
+ this.currentSubscription.onResult(processResults);
452
+
453
+ const { results } = await this.processSparqlResult(this.currentSubscription.result);
454
+ // Initial results returned via Promise only — callback is for subsequent updates
455
+ return results as T[];
456
+ }
457
+
418
458
  /**
419
459
  * Gets the total count of matching entities.
420
460
  *
@@ -428,13 +468,10 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
428
468
  * ```
429
469
  */
430
470
  async count(): Promise<number> {
431
- if (this.useSurrealDBFlag) {
432
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
433
- const result = await this.perspective.querySurrealDB(surrealQuery);
434
- // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
435
- // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
436
- // This ensures count() returns the same number as get().length
437
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
471
+ if (this.engineFlag === 'sparql') {
472
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
473
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
474
+ const { totalCount } = await this.processSparqlResult(rawResult);
438
475
  return totalCount;
439
476
  } else {
440
477
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -443,11 +480,25 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
443
480
  }
444
481
  }
445
482
 
483
+ /**
484
+ * Gets the total count of matching entities using SPARQL.
485
+ * Delegates to count() with SPARQL engine forced.
486
+ */
487
+ async countSparql(): Promise<number> {
488
+ const prev = this.engineFlag;
489
+ this.engineFlag = 'sparql';
490
+ try {
491
+ return await this.count();
492
+ } finally {
493
+ this.engineFlag = prev;
494
+ }
495
+ }
496
+
446
497
  /**
447
498
  * Subscribes to count updates for matching entities.
448
499
  *
449
500
  * This method:
450
- * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
501
+ * 1. Creates and initializes a SPARQL live query subscription for the count (default)
451
502
  * 2. Sets up the callback to process future count updates
452
503
  * 3. Returns the initial count immediately
453
504
  *
@@ -471,29 +522,25 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
471
522
  * ```
472
523
  *
473
524
  * @remarks
474
- * By default, this uses SurrealDB live queries for real-time updates.
475
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
525
+ * By default, this uses SPARQL live queries for real-time updates.
526
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
476
527
  */
477
528
  async countSubscribe(callback: (count: number) => void): Promise<number> {
478
529
  // Clean up any existing subscription
479
530
  this.dispose();
480
531
 
481
- if (this.useSurrealDBFlag) {
482
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
483
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
532
+ if (this.engineFlag === 'sparql') {
533
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
534
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
484
535
 
485
536
  const processResults = async (result: any) => {
486
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
537
+ const { totalCount } = await this.processSparqlResult(result);
487
538
  callback(totalCount);
488
539
  };
489
540
 
490
541
  this.currentSubscription.onResult(processResults);
491
- const { totalCount } = await this.ctor.instancesFromSurrealResult(
492
- this.perspective,
493
- this.queryParams,
494
- this.currentSubscription.result
495
- );
496
- callback(totalCount);
542
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
543
+ // Initial count returned via Promise — callback for updates only
497
544
  return totalCount;
498
545
  } else {
499
546
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -506,11 +553,31 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
506
553
 
507
554
  this.currentSubscription.onResult(processResults);
508
555
  const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
509
- callback(initialCount);
556
+ // Initial count returned via Promise — callback for subsequent updates only
510
557
  return initialCount;
511
558
  }
512
559
  }
513
560
 
561
+ /**
562
+ * Subscribes to count updates using SPARQL.
563
+ */
564
+ async countSubscribeSparql(callback: (count: number) => void): Promise<number> {
565
+ this.dispose();
566
+
567
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
568
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
569
+
570
+ const processResults = async (result: any) => {
571
+ const { totalCount } = await this.processSparqlResult(result);
572
+ callback(totalCount);
573
+ };
574
+
575
+ this.currentSubscription.onResult(processResults);
576
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
577
+ // Initial count returned via Promise — callback for updates only
578
+ return totalCount;
579
+ }
580
+
514
581
  /**
515
582
  * Gets a page of results with pagination metadata.
516
583
  *
@@ -528,10 +595,10 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
528
595
  */
529
596
  async paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>> {
530
597
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
531
- if (this.useSurrealDBFlag) {
532
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
533
- const result = await this.perspective.querySurrealDB(surrealQuery);
534
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
598
+ if (this.engineFlag === 'sparql') {
599
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
600
+ const result = await this.perspective.querySparql(sparqlQuery);
601
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery) as ResultsWithTotalCount<T>;
535
602
  return { results, totalCount, pageSize, pageNumber };
536
603
  } else {
537
604
  const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
@@ -541,11 +608,25 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
541
608
  }
542
609
  }
543
610
 
611
+ /**
612
+ * Gets a page of results using SPARQL.
613
+ * Delegates to paginate() with SPARQL engine forced.
614
+ */
615
+ async paginateSparql(pageSize: number, pageNumber: number): Promise<PaginationResult<T>> {
616
+ const prev = this.engineFlag;
617
+ this.engineFlag = 'sparql';
618
+ try {
619
+ return await this.paginate(pageSize, pageNumber);
620
+ } finally {
621
+ this.engineFlag = prev;
622
+ }
623
+ }
624
+
544
625
  /**
545
626
  * Subscribes to paginated results updates.
546
627
  *
547
628
  * This method:
548
- * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
629
+ * 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
549
630
  * 2. Sets up the callback to process future page updates
550
631
  * 3. Returns the initial page immediately
551
632
  *
@@ -571,8 +652,8 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
571
652
  * ```
572
653
  *
573
654
  * @remarks
574
- * By default, this uses SurrealDB live queries for real-time updates.
575
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
655
+ * By default, this uses SPARQL live queries for real-time updates.
656
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
576
657
  */
577
658
  async paginateSubscribe(
578
659
  pageSize: number,
@@ -584,19 +665,19 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
584
665
 
585
666
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
586
667
 
587
- if (this.useSurrealDBFlag) {
588
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
589
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
668
+ if (this.engineFlag === 'sparql') {
669
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
670
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
590
671
 
591
672
  const processResults = async (result: any) => {
592
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
673
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery) as ResultsWithTotalCount<T>;
593
674
  callback({ results, totalCount, pageSize, pageNumber });
594
675
  };
595
676
 
596
677
  this.currentSubscription.onResult(processResults);
597
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
678
+ const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery) as ResultsWithTotalCount<T>;
598
679
  const initialPage = { results, totalCount, pageSize, pageNumber };
599
- callback(initialPage);
680
+ // Initial page returned via Promise — callback for subsequent updates only
600
681
  return initialPage;
601
682
  } else {
602
683
  const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
@@ -610,8 +691,26 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
610
691
  this.currentSubscription.onResult(processResults);
611
692
  const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
612
693
  const initialPrologPage = { results, totalCount, pageSize, pageNumber };
613
- callback(initialPrologPage);
694
+ // Initial page returned via Promise — callback for subsequent updates only
614
695
  return initialPrologPage;
615
696
  }
616
697
  }
698
+
699
+ /**
700
+ * Subscribes to paginated results updates using SPARQL.
701
+ * Delegates to paginateSubscribe() with SPARQL engine forced.
702
+ */
703
+ async paginateSubscribeSparql(
704
+ pageSize: number,
705
+ pageNumber: number,
706
+ callback: (results: PaginationResult<T>) => void
707
+ ): Promise<PaginationResult<T>> {
708
+ const prev = this.engineFlag;
709
+ this.engineFlag = 'sparql';
710
+ try {
711
+ return await this.paginateSubscribe(pageSize, pageNumber, callback);
712
+ } finally {
713
+ this.engineFlag = prev;
714
+ }
715
+ }
617
716
  }
@@ -50,11 +50,11 @@ export class Subject {
50
50
  Object.defineProperty(this, p, {
51
51
  configurable: true,
52
52
  get: async () => {
53
- // Use SurrealDB for data queries
53
+ // Use SPARQL for data queries
54
54
  try {
55
- return await this.#perspective.getPropertyValueViaSurreal(this.#baseExpression, this.#subjectClassName, p);
55
+ return await this.#perspective.getPropertyValueViaSparql(this.#baseExpression, this.#subjectClassName, p);
56
56
  } catch (err) {
57
- console.warn(`Failed to get property ${p} via SurrealDB:`, err);
57
+ console.warn(`Failed to get property ${p} via SPARQL:`, err);
58
58
  return undefined;
59
59
  }
60
60
  }
@@ -91,11 +91,11 @@ export class Subject {
91
91
  Object.defineProperty(this, c, {
92
92
  configurable: true,
93
93
  get: async () => {
94
- // Use SurrealDB for data queries
94
+ // Use SPARQL for data queries
95
95
  try {
96
- return await this.#perspective.getRelationValuesViaSurreal(this.#baseExpression, this.#subjectClassName, c);
96
+ return await this.#perspective.getRelationValuesViaSparql(this.#baseExpression, this.#subjectClassName, c);
97
97
  } catch (err) {
98
- console.warn(`Failed to get relation ${c} via SurrealDB:`, err);
98
+ console.warn(`Failed to get relation ${c} via SPARQL:`, err);
99
99
  return [];
100
100
  }
101
101
  }