@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.
Files changed (115) hide show
  1. package/lib/index.cjs +2377 -849
  2. package/lib/index.js +2354 -846
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +5 -1
  5. package/lib/src/agent/AgentClient.js +48 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/index.d.ts +0 -1
  8. package/lib/src/index.js +0 -1
  9. package/lib/src/language/Language.d.ts +26 -176
  10. package/lib/src/language/Language.js +28 -2
  11. package/lib/src/model/Ad4mModel.d.ts +52 -28
  12. package/lib/src/model/Ad4mModel.js +255 -118
  13. package/lib/src/model/Ad4mModel.test.js +1727 -537
  14. package/lib/src/model/ModelQueryBuilder.d.ts +67 -34
  15. package/lib/src/model/ModelQueryBuilder.js +208 -79
  16. package/lib/src/model/Subject.js +6 -6
  17. package/lib/src/model/decorators.d.ts +14 -8
  18. package/lib/src/model/decorators.js +41 -14
  19. package/lib/src/model/hydration-batch.d.ts +34 -0
  20. package/lib/src/model/hydration-batch.js +147 -0
  21. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  22. package/lib/src/model/hydration-batching.test.js +456 -0
  23. package/lib/src/model/hydration.d.ts +4 -3
  24. package/lib/src/model/hydration.js +365 -86
  25. package/lib/src/model/index.d.ts +4 -1
  26. package/lib/src/model/index.js +4 -1
  27. package/lib/src/model/json-schema.js +2 -2
  28. package/lib/src/model/query-cache.d.ts +30 -0
  29. package/lib/src/model/query-cache.js +66 -0
  30. package/lib/src/model/query-cache.test.d.ts +1 -0
  31. package/lib/src/model/query-cache.test.js +43 -0
  32. package/lib/src/model/query-common.d.ts +1 -1
  33. package/lib/src/model/query-common.js +1 -1
  34. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  35. package/lib/src/model/query-sparql-batch.js +260 -0
  36. package/lib/src/model/query-sparql.d.ts +124 -0
  37. package/lib/src/model/query-sparql.js +767 -0
  38. package/lib/src/model/query-sparql.test.d.ts +1 -0
  39. package/lib/src/model/query-sparql.test.js +495 -0
  40. package/lib/src/model/{surreal-utils.d.ts → query-utils.d.ts} +12 -9
  41. package/lib/src/model/{surreal-utils.js → query-utils.js} +43 -27
  42. package/lib/src/model/relation-filtering.test.js +15 -15
  43. package/lib/src/model/sdna.js +1 -1
  44. package/lib/src/model/shacl-gen.js +42 -18
  45. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  46. package/lib/src/model/subscription-delta.test.js +180 -0
  47. package/lib/src/model/subscription-pool.d.ts +39 -0
  48. package/lib/src/model/subscription-pool.js +165 -0
  49. package/lib/src/model/types.d.ts +52 -4
  50. package/lib/src/model/types.js +1 -1
  51. package/lib/src/perspectives/PerspectiveClient.d.ts +3 -17
  52. package/lib/src/perspectives/PerspectiveClient.js +42 -66
  53. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  54. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  55. package/lib/src/perspectives/PerspectiveProxy.d.ts +54 -30
  56. package/lib/src/perspectives/PerspectiveProxy.js +239 -177
  57. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  58. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  59. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  60. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  61. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  62. package/lib/src/runtime/RuntimeResolver.js +56 -0
  63. package/lib/src/schema.gql +11 -1
  64. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  65. package/lib/src/shacl/SHACLFlow.js +9 -9
  66. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  67. package/lib/src/shacl/SHACLShape.js +38 -38
  68. package/lib/src/typeDefs.js +11 -1
  69. package/lib/src/utils.d.ts +6 -6
  70. package/lib/src/utils.js +6 -6
  71. package/package.json +1 -1
  72. package/src/Ad4mClient.test.ts +56 -1
  73. package/src/Literal.test.ts +10 -5
  74. package/src/Literal.ts +6 -5
  75. package/src/agent/AgentClient.ts +53 -1
  76. package/src/expression/ExpressionRef.ts +2 -2
  77. package/src/index.ts +0 -1
  78. package/src/language/Language.ts +55 -231
  79. package/src/model/Ad4mModel.test.ts +1709 -572
  80. package/src/model/Ad4mModel.ts +274 -120
  81. package/src/model/ModelQueryBuilder.ts +234 -87
  82. package/src/model/Subject.ts +6 -6
  83. package/src/model/decorators.ts +51 -22
  84. package/src/model/hydration-batch.ts +205 -0
  85. package/src/model/hydration-batching.test.ts +563 -0
  86. package/src/model/hydration.ts +349 -84
  87. package/src/model/index.ts +4 -1
  88. package/src/model/json-schema.ts +2 -2
  89. package/src/model/query-cache.test.ts +54 -0
  90. package/src/model/query-cache.ts +79 -0
  91. package/src/model/query-common.ts +1 -1
  92. package/src/model/query-sparql-batch.ts +301 -0
  93. package/src/model/query-sparql.test.ts +568 -0
  94. package/src/model/query-sparql.ts +820 -0
  95. package/src/model/{surreal-utils.ts → query-utils.ts} +44 -27
  96. package/src/model/relation-filtering.test.ts +15 -15
  97. package/src/model/sdna.ts +1 -1
  98. package/src/model/shacl-gen.ts +42 -17
  99. package/src/model/subscription-delta.test.ts +207 -0
  100. package/src/model/subscription-pool.ts +211 -0
  101. package/src/model/types.ts +53 -4
  102. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  103. package/src/perspectives/PerspectiveClient.ts +41 -68
  104. package/src/perspectives/PerspectiveProxy.ts +244 -181
  105. package/src/perspectives/PerspectiveResolver.ts +0 -8
  106. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  107. package/src/runtime/RuntimeResolver.ts +43 -0
  108. package/src/shacl/SHACLFlow.ts +9 -9
  109. package/src/shacl/SHACLShape.ts +39 -39
  110. package/src/utils.ts +6 -6
  111. package/lib/src/model/query-surreal.d.ts +0 -44
  112. package/lib/src/model/query-surreal.js +0 -249
  113. package/src/language/LanguageContext.ts +0 -37
  114. package/src/model/query-surreal.ts +0 -280
  115. package/tsconfig-browser.json +0 -82
@@ -33,7 +33,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
33
33
  private modelClassName;
34
34
  private ctor;
35
35
  private currentSubscription?;
36
- private useSurrealDBFlag;
36
+ private engineFlag;
37
37
  constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query);
38
38
  /**
39
39
  * Disposes of the current subscription if one exists.
@@ -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
  *
@@ -187,31 +206,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
187
206
  include(map: IncludeMap): ModelQueryBuilder<T>;
188
207
  overrideModelClassName(className: string): ModelQueryBuilder<T>;
189
208
  /**
190
- * Enables or disables SurrealDB query path.
191
- *
192
- * @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
193
- * @returns The query builder for chaining
194
- *
195
- * @example
196
- * ```typescript
197
- * // Use SurrealDB (default)
198
- * const recipes = await Recipe.query(perspective)
199
- * .where({ category: "Dessert" })
200
- * .useSurrealDB(true)
201
- * .get();
202
- *
203
- * // Use Prolog (legacy)
204
- * const recipesProlog = await Recipe.query(perspective)
205
- * .where({ category: "Dessert" })
206
- * .useSurrealDB(false)
207
- * .get();
208
- * ```
209
- *
210
- * @remarks
211
- * Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
212
- * if useSurrealDB(true) is set (default).
209
+ * Sets the query engine to use.
213
210
  */
214
- useSurrealDB(enabled?: boolean): ModelQueryBuilder<T>;
211
+ engine(eng: 'sparql' | 'prolog'): ModelQueryBuilder<T>;
215
212
  /**
216
213
  * Executes the query once and returns the results.
217
214
  *
@@ -225,6 +222,19 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
225
222
  * ```
226
223
  */
227
224
  get(): Promise<T[]>;
225
+ /**
226
+ * Executes the query once using SPARQL and returns the results.
227
+ */
228
+ getSparql(): Promise<T[]>;
229
+ /**
230
+ * Shared SPARQL query execution logic used by both get() and getSparql().
231
+ */
232
+ private executeSparqlQuery;
233
+ /**
234
+ * Groups raw SPARQL results and hydrates them into model instances.
235
+ * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
236
+ */
237
+ private processSparqlResult;
228
238
  /**
229
239
  * Returns the first matching instance, or `null` if none match.
230
240
  *
@@ -244,7 +254,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
244
254
  * Subscribes to the query and receives updates when results change.
245
255
  *
246
256
  * This method:
247
- * 1. Creates and initializes a SurrealDB live query subscription (default)
257
+ * 1. Creates and initializes a SPARQL live query subscription (default)
248
258
  * 2. Sets up the callback to process future updates
249
259
  * 3. Returns the initial results immediately
250
260
  *
@@ -268,10 +278,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
268
278
  * ```
269
279
  *
270
280
  * @remarks
271
- * By default, this uses SurrealDB live queries for real-time updates.
272
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
281
+ * By default, this uses SPARQL live queries for real-time updates.
282
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
273
283
  */
274
284
  subscribe(callback: (results: T[]) => void): Promise<T[]>;
285
+ /**
286
+ * Subscribes to the query and receives updates using SPARQL.
287
+ */
288
+ subscribeSparql(callback: (results: T[]) => void): Promise<T[]>;
275
289
  /**
276
290
  * Gets the total count of matching entities.
277
291
  *
@@ -285,11 +299,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
285
299
  * ```
286
300
  */
287
301
  count(): Promise<number>;
302
+ /**
303
+ * Gets the total count of matching entities using SPARQL.
304
+ * Delegates to count() with SPARQL engine forced.
305
+ */
306
+ countSparql(): Promise<number>;
288
307
  /**
289
308
  * Subscribes to count updates for matching entities.
290
309
  *
291
310
  * This method:
292
- * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
311
+ * 1. Creates and initializes a SPARQL live query subscription for the count (default)
293
312
  * 2. Sets up the callback to process future count updates
294
313
  * 3. Returns the initial count immediately
295
314
  *
@@ -313,10 +332,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
313
332
  * ```
314
333
  *
315
334
  * @remarks
316
- * By default, this uses SurrealDB live queries for real-time updates.
317
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
335
+ * By default, this uses SPARQL live queries for real-time updates.
336
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
318
337
  */
319
338
  countSubscribe(callback: (count: number) => void): Promise<number>;
339
+ /**
340
+ * Subscribes to count updates using SPARQL.
341
+ */
342
+ countSubscribeSparql(callback: (count: number) => void): Promise<number>;
320
343
  /**
321
344
  * Gets a page of results with pagination metadata.
322
345
  *
@@ -333,11 +356,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
333
356
  * ```
334
357
  */
335
358
  paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
359
+ /**
360
+ * Gets a page of results using SPARQL.
361
+ * Delegates to paginate() with SPARQL engine forced.
362
+ */
363
+ paginateSparql(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
336
364
  /**
337
365
  * Subscribes to paginated results updates.
338
366
  *
339
367
  * This method:
340
- * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
368
+ * 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
341
369
  * 2. Sets up the callback to process future page updates
342
370
  * 3. Returns the initial page immediately
343
371
  *
@@ -363,8 +391,13 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
363
391
  * ```
364
392
  *
365
393
  * @remarks
366
- * By default, this uses SurrealDB live queries for real-time updates.
367
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
394
+ * By default, this uses SPARQL live queries for real-time updates.
395
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
368
396
  */
369
397
  paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
398
+ /**
399
+ * Subscribes to paginated results updates using SPARQL.
400
+ * Delegates to paginateSubscribe() with SPARQL engine forced.
401
+ */
402
+ paginateSubscribeSparql(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
370
403
  }
@@ -4,6 +4,9 @@
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, hasJsOnlyWhereFilters, parseSparqlCount } from "./query-sparql";
8
+ import { getRelationsMetadata } from "./decorators";
9
+ import { pooledSubscribe } from "./subscription-pool";
7
10
  /** Query builder for Ad4mModel queries.
8
11
  * Allows building queries with a fluent interface and either running them once
9
12
  * or subscribing to updates.
@@ -28,7 +31,7 @@ export class ModelQueryBuilder {
28
31
  constructor(perspective, ctor, query) {
29
32
  this.queryParams = {};
30
33
  this.modelClassName = null;
31
- this.useSurrealDBFlag = true;
34
+ this.engineFlag = 'sparql';
32
35
  this.perspective = perspective;
33
36
  this.ctor = ctor;
34
37
  if (query)
@@ -201,6 +204,28 @@ export class ModelQueryBuilder {
201
204
  this.queryParams.properties = properties;
202
205
  return this;
203
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
+ }
204
229
  /**
205
230
  * Specifies which relations to eager-load (hydrate into model instances).
206
231
  *
@@ -236,32 +261,10 @@ export class ModelQueryBuilder {
236
261
  return this;
237
262
  }
238
263
  /**
239
- * Enables or disables SurrealDB query path.
240
- *
241
- * @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
242
- * @returns The query builder for chaining
243
- *
244
- * @example
245
- * ```typescript
246
- * // Use SurrealDB (default)
247
- * const recipes = await Recipe.query(perspective)
248
- * .where({ category: "Dessert" })
249
- * .useSurrealDB(true)
250
- * .get();
251
- *
252
- * // Use Prolog (legacy)
253
- * const recipesProlog = await Recipe.query(perspective)
254
- * .where({ category: "Dessert" })
255
- * .useSurrealDB(false)
256
- * .get();
257
- * ```
258
- *
259
- * @remarks
260
- * Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
261
- * if useSurrealDB(true) is set (default).
264
+ * Sets the query engine to use.
262
265
  */
263
- useSurrealDB(enabled = true) {
264
- this.useSurrealDBFlag = enabled;
266
+ engine(eng) {
267
+ this.engineFlag = eng;
265
268
  return this;
266
269
  }
267
270
  /**
@@ -278,10 +281,8 @@ export class ModelQueryBuilder {
278
281
  */
279
282
  async get() {
280
283
  let results;
281
- if (this.useSurrealDBFlag) {
282
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
283
- const result = await this.perspective.querySurrealDB(surrealQuery);
284
- ({ results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result));
284
+ if (this.engineFlag === 'sparql') {
285
+ results = await this.executeSparqlQuery();
285
286
  }
286
287
  else {
287
288
  const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -290,6 +291,29 @@ export class ModelQueryBuilder {
290
291
  }
291
292
  return results;
292
293
  }
294
+ /**
295
+ * Executes the query once using SPARQL and returns the results.
296
+ */
297
+ async getSparql() {
298
+ return this.executeSparqlQuery();
299
+ }
300
+ /**
301
+ * Shared SPARQL query execution logic used by both get() and getSparql().
302
+ */
303
+ async executeSparqlQuery() {
304
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
305
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
306
+ const { results } = await this.processSparqlResult(rawResult);
307
+ return results;
308
+ }
309
+ /**
310
+ * Groups raw SPARQL results and hydrates them into model instances.
311
+ * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
312
+ */
313
+ async processSparqlResult(rawResult, queryOverride, computeTotalCount = false) {
314
+ const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
315
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped, computeTotalCount);
316
+ }
293
317
  /**
294
318
  * Returns the first matching instance, or `null` if none match.
295
319
  *
@@ -313,7 +337,7 @@ export class ModelQueryBuilder {
313
337
  * Subscribes to the query and receives updates when results change.
314
338
  *
315
339
  * This method:
316
- * 1. Creates and initializes a SurrealDB live query subscription (default)
340
+ * 1. Creates and initializes a SPARQL live query subscription (default)
317
341
  * 2. Sets up the callback to process future updates
318
342
  * 3. Returns the initial results immediately
319
343
  *
@@ -337,26 +361,40 @@ export class ModelQueryBuilder {
337
361
  * ```
338
362
  *
339
363
  * @remarks
340
- * By default, this uses SurrealDB live queries for real-time updates.
341
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
364
+ * By default, this uses SPARQL live queries for real-time updates.
365
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
342
366
  */
343
367
  async subscribe(callback) {
344
368
  // Clean up any existing subscription
345
369
  this.dispose();
346
370
  const ctor = this.ctor;
347
- if (this.useSurrealDBFlag) {
348
- const surrealQuery = await ctor.queryToSurrealQL(this.perspective, this.queryParams);
349
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
350
- const processResults = async (result) => {
351
- const { results } = await ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
352
- callback(results);
371
+ if (this.engineFlag === 'sparql') {
372
+ const sparqlQuery = await ctor.queryToSPARQL(this.perspective, this.queryParams);
373
+ // Track last emitted result fingerprint to suppress duplicate callbacks
374
+ let lastResultFingerprint = null;
375
+ const buildFingerprint = (results) => {
376
+ if (results.length === 0)
377
+ return '0:';
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);
353
381
  };
354
- this.currentSubscription.onResult(processResults);
355
- // Process initial result
356
- const { results } = await ctor.instancesFromSurrealResult(this.perspective, this.queryParams, this.currentSubscription.result);
357
- // Also invoke callback with initial results so subscribers see them
358
- callback(results);
359
- return results;
382
+ const hydrate = async (rawResult) => {
383
+ const { results } = await this.processSparqlResult(rawResult);
384
+ return results;
385
+ };
386
+ const pooled = await pooledSubscribe(this.perspective, sparqlQuery, hydrate, (hydratedResults) => {
387
+ const fp = buildFingerprint(hydratedResults);
388
+ if (fp === lastResultFingerprint)
389
+ return;
390
+ lastResultFingerprint = fp;
391
+ callback(hydratedResults);
392
+ });
393
+ // Store dispose function as subscription
394
+ this.currentSubscription = { dispose: pooled.dispose };
395
+ const initialResults = pooled.initialResult;
396
+ lastResultFingerprint = buildFingerprint(initialResults);
397
+ return initialResults;
360
398
  }
361
399
  else {
362
400
  const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -367,11 +405,26 @@ export class ModelQueryBuilder {
367
405
  };
368
406
  this.currentSubscription.onResult(processResults);
369
407
  const { results } = await ctor.instancesFromPrologResult(this.perspective, this.queryParams, this.currentSubscription.result);
370
- // Also invoke callback with initial results so subscribers see them
371
- callback(results);
408
+ // Initial results returned via Promise only — callback is for subsequent updates
372
409
  return results;
373
410
  }
374
411
  }
412
+ /**
413
+ * Subscribes to the query and receives updates using SPARQL.
414
+ */
415
+ async subscribeSparql(callback) {
416
+ this.dispose();
417
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
418
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
419
+ const processResults = async (result) => {
420
+ const { results } = await this.processSparqlResult(result);
421
+ callback(results);
422
+ };
423
+ this.currentSubscription.onResult(processResults);
424
+ const { results } = await this.processSparqlResult(this.currentSubscription.result);
425
+ // Initial results returned via Promise only — callback is for subsequent updates
426
+ return results;
427
+ }
375
428
  /**
376
429
  * Gets the total count of matching entities.
377
430
  *
@@ -385,14 +438,20 @@ export class ModelQueryBuilder {
385
438
  * ```
386
439
  */
387
440
  async count() {
388
- if (this.useSurrealDBFlag) {
389
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
390
- const result = await this.perspective.querySurrealDB(surrealQuery);
391
- // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
392
- // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
393
- // This ensures count() returns the same number as get().length
394
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
395
- return totalCount;
441
+ if (this.engineFlag === 'sparql') {
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;
396
455
  }
397
456
  else {
398
457
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -400,11 +459,25 @@ export class ModelQueryBuilder {
400
459
  return result?.[0]?.TotalCount || 0;
401
460
  }
402
461
  }
462
+ /**
463
+ * Gets the total count of matching entities using SPARQL.
464
+ * Delegates to count() with SPARQL engine forced.
465
+ */
466
+ async countSparql() {
467
+ const prev = this.engineFlag;
468
+ this.engineFlag = 'sparql';
469
+ try {
470
+ return await this.count();
471
+ }
472
+ finally {
473
+ this.engineFlag = prev;
474
+ }
475
+ }
403
476
  /**
404
477
  * Subscribes to count updates for matching entities.
405
478
  *
406
479
  * This method:
407
- * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
480
+ * 1. Creates and initializes a SPARQL live query subscription for the count (default)
408
481
  * 2. Sets up the callback to process future count updates
409
482
  * 3. Returns the initial count immediately
410
483
  *
@@ -428,22 +501,22 @@ export class ModelQueryBuilder {
428
501
  * ```
429
502
  *
430
503
  * @remarks
431
- * By default, this uses SurrealDB live queries for real-time updates.
432
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
504
+ * By default, this uses SPARQL live queries for real-time updates.
505
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
433
506
  */
434
507
  async countSubscribe(callback) {
435
508
  // Clean up any existing subscription
436
509
  this.dispose();
437
- if (this.useSurrealDBFlag) {
438
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
439
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
510
+ if (this.engineFlag === 'sparql') {
511
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
512
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
440
513
  const processResults = async (result) => {
441
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
514
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
442
515
  callback(totalCount);
443
516
  };
444
517
  this.currentSubscription.onResult(processResults);
445
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, this.currentSubscription.result);
446
- callback(totalCount);
518
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
519
+ // Initial count returned via Promise — callback for updates only
447
520
  return totalCount;
448
521
  }
449
522
  else {
@@ -455,10 +528,26 @@ export class ModelQueryBuilder {
455
528
  };
456
529
  this.currentSubscription.onResult(processResults);
457
530
  const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
458
- callback(initialCount);
531
+ // Initial count returned via Promise — callback for subsequent updates only
459
532
  return initialCount;
460
533
  }
461
534
  }
535
+ /**
536
+ * Subscribes to count updates using SPARQL.
537
+ */
538
+ async countSubscribeSparql(callback) {
539
+ this.dispose();
540
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
541
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
542
+ const processResults = async (result) => {
543
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
544
+ callback(totalCount);
545
+ };
546
+ this.currentSubscription.onResult(processResults);
547
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
548
+ // Initial count returned via Promise — callback for updates only
549
+ return totalCount;
550
+ }
462
551
  /**
463
552
  * Gets a page of results with pagination metadata.
464
553
  *
@@ -476,10 +565,10 @@ export class ModelQueryBuilder {
476
565
  */
477
566
  async paginate(pageSize, pageNumber) {
478
567
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
479
- if (this.useSurrealDBFlag) {
480
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
481
- const result = await this.perspective.querySurrealDB(surrealQuery);
482
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result));
568
+ if (this.engineFlag === 'sparql') {
569
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
570
+ const result = await this.perspective.querySparql(sparqlQuery);
571
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery, true);
483
572
  return { results, totalCount, pageSize, pageNumber };
484
573
  }
485
574
  else {
@@ -489,11 +578,25 @@ export class ModelQueryBuilder {
489
578
  return { results, totalCount, pageSize, pageNumber };
490
579
  }
491
580
  }
581
+ /**
582
+ * Gets a page of results using SPARQL.
583
+ * Delegates to paginate() with SPARQL engine forced.
584
+ */
585
+ async paginateSparql(pageSize, pageNumber) {
586
+ const prev = this.engineFlag;
587
+ this.engineFlag = 'sparql';
588
+ try {
589
+ return await this.paginate(pageSize, pageNumber);
590
+ }
591
+ finally {
592
+ this.engineFlag = prev;
593
+ }
594
+ }
492
595
  /**
493
596
  * Subscribes to paginated results updates.
494
597
  *
495
598
  * This method:
496
- * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
599
+ * 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
497
600
  * 2. Sets up the callback to process future page updates
498
601
  * 3. Returns the initial page immediately
499
602
  *
@@ -519,24 +622,36 @@ export class ModelQueryBuilder {
519
622
  * ```
520
623
  *
521
624
  * @remarks
522
- * By default, this uses SurrealDB live queries for real-time updates.
523
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
625
+ * By default, this uses SPARQL live queries for real-time updates.
626
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
524
627
  */
525
628
  async paginateSubscribe(pageSize, pageNumber, callback) {
526
629
  // Clean up any existing subscription
527
630
  this.dispose();
528
631
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
529
- if (this.useSurrealDBFlag) {
530
- const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
531
- this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
632
+ if (this.engineFlag === 'sparql') {
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);
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 };
532
643
  const processResults = async (result) => {
533
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result));
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);
534
647
  callback({ results, totalCount, pageSize, pageNumber });
535
648
  };
536
649
  this.currentSubscription.onResult(processResults);
537
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result));
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);
538
653
  const initialPage = { results, totalCount, pageSize, pageNumber };
539
- callback(initialPage);
654
+ // Initial page returned via Promise — callback for subsequent updates only
540
655
  return initialPage;
541
656
  }
542
657
  else {
@@ -549,8 +664,22 @@ export class ModelQueryBuilder {
549
664
  this.currentSubscription.onResult(processResults);
550
665
  const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result));
551
666
  const initialPrologPage = { results, totalCount, pageSize, pageNumber };
552
- callback(initialPrologPage);
667
+ // Initial page returned via Promise — callback for subsequent updates only
553
668
  return initialPrologPage;
554
669
  }
555
670
  }
671
+ /**
672
+ * Subscribes to paginated results updates using SPARQL.
673
+ * Delegates to paginateSubscribe() with SPARQL engine forced.
674
+ */
675
+ async paginateSubscribeSparql(pageSize, pageNumber, callback) {
676
+ const prev = this.engineFlag;
677
+ this.engineFlag = 'sparql';
678
+ try {
679
+ return await this.paginateSubscribe(pageSize, pageNumber, callback);
680
+ }
681
+ finally {
682
+ this.engineFlag = prev;
683
+ }
684
+ }
556
685
  }
@@ -55,12 +55,12 @@ export class Subject {
55
55
  Object.defineProperty(this, p, {
56
56
  configurable: true,
57
57
  get: async () => {
58
- // Use SurrealDB for data queries
58
+ // Use SPARQL for data queries
59
59
  try {
60
- return await __classPrivateFieldGet(this, _Subject_perspective, "f").getPropertyValueViaSurreal(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), p);
60
+ return await __classPrivateFieldGet(this, _Subject_perspective, "f").getPropertyValueViaSparql(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), p);
61
61
  }
62
62
  catch (err) {
63
- console.warn(`Failed to get property ${p} via SurrealDB:`, err);
63
+ console.warn(`Failed to get property ${p} via SPARQL:`, err);
64
64
  return undefined;
65
65
  }
66
66
  }
@@ -94,12 +94,12 @@ export class Subject {
94
94
  Object.defineProperty(this, c, {
95
95
  configurable: true,
96
96
  get: async () => {
97
- // Use SurrealDB for data queries
97
+ // Use SPARQL for data queries
98
98
  try {
99
- return await __classPrivateFieldGet(this, _Subject_perspective, "f").getRelationValuesViaSurreal(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), c);
99
+ return await __classPrivateFieldGet(this, _Subject_perspective, "f").getRelationValuesViaSparql(__classPrivateFieldGet(this, _Subject_baseExpression, "f"), __classPrivateFieldGet(this, _Subject_subjectClassName, "f"), c);
100
100
  }
101
101
  catch (err) {
102
- console.warn(`Failed to get relation ${c} via SurrealDB:`, err);
102
+ console.warn(`Failed to get relation ${c} via SPARQL:`, err);
103
103
  return [];
104
104
  }
105
105
  }