@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
@@ -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.
@@ -187,31 +187,9 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
187
187
  include(map: IncludeMap): ModelQueryBuilder<T>;
188
188
  overrideModelClassName(className: string): ModelQueryBuilder<T>;
189
189
  /**
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).
190
+ * Sets the query engine to use.
213
191
  */
214
- useSurrealDB(enabled?: boolean): ModelQueryBuilder<T>;
192
+ engine(eng: 'sparql' | 'prolog'): ModelQueryBuilder<T>;
215
193
  /**
216
194
  * Executes the query once and returns the results.
217
195
  *
@@ -225,6 +203,19 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
225
203
  * ```
226
204
  */
227
205
  get(): Promise<T[]>;
206
+ /**
207
+ * Executes the query once using SPARQL and returns the results.
208
+ */
209
+ getSparql(): Promise<T[]>;
210
+ /**
211
+ * Shared SPARQL query execution logic used by both get() and getSparql().
212
+ */
213
+ private executeSparqlQuery;
214
+ /**
215
+ * Groups raw SPARQL results and hydrates them into model instances.
216
+ * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
217
+ */
218
+ private processSparqlResult;
228
219
  /**
229
220
  * Returns the first matching instance, or `null` if none match.
230
221
  *
@@ -244,7 +235,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
244
235
  * Subscribes to the query and receives updates when results change.
245
236
  *
246
237
  * This method:
247
- * 1. Creates and initializes a SurrealDB live query subscription (default)
238
+ * 1. Creates and initializes a SPARQL live query subscription (default)
248
239
  * 2. Sets up the callback to process future updates
249
240
  * 3. Returns the initial results immediately
250
241
  *
@@ -268,10 +259,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
268
259
  * ```
269
260
  *
270
261
  * @remarks
271
- * By default, this uses SurrealDB live queries for real-time updates.
272
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
262
+ * By default, this uses SPARQL live queries for real-time updates.
263
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
273
264
  */
274
265
  subscribe(callback: (results: T[]) => void): Promise<T[]>;
266
+ /**
267
+ * Subscribes to the query and receives updates using SPARQL.
268
+ */
269
+ subscribeSparql(callback: (results: T[]) => void): Promise<T[]>;
275
270
  /**
276
271
  * Gets the total count of matching entities.
277
272
  *
@@ -285,11 +280,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
285
280
  * ```
286
281
  */
287
282
  count(): Promise<number>;
283
+ /**
284
+ * Gets the total count of matching entities using SPARQL.
285
+ * Delegates to count() with SPARQL engine forced.
286
+ */
287
+ countSparql(): Promise<number>;
288
288
  /**
289
289
  * Subscribes to count updates for matching entities.
290
290
  *
291
291
  * This method:
292
- * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
292
+ * 1. Creates and initializes a SPARQL live query subscription for the count (default)
293
293
  * 2. Sets up the callback to process future count updates
294
294
  * 3. Returns the initial count immediately
295
295
  *
@@ -313,10 +313,14 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
313
313
  * ```
314
314
  *
315
315
  * @remarks
316
- * By default, this uses SurrealDB live queries for real-time updates.
317
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
316
+ * By default, this uses SPARQL live queries for real-time updates.
317
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
318
318
  */
319
319
  countSubscribe(callback: (count: number) => void): Promise<number>;
320
+ /**
321
+ * Subscribes to count updates using SPARQL.
322
+ */
323
+ countSubscribeSparql(callback: (count: number) => void): Promise<number>;
320
324
  /**
321
325
  * Gets a page of results with pagination metadata.
322
326
  *
@@ -333,11 +337,16 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
333
337
  * ```
334
338
  */
335
339
  paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
340
+ /**
341
+ * Gets a page of results using SPARQL.
342
+ * Delegates to paginate() with SPARQL engine forced.
343
+ */
344
+ paginateSparql(pageSize: number, pageNumber: number): Promise<PaginationResult<T>>;
336
345
  /**
337
346
  * Subscribes to paginated results updates.
338
347
  *
339
348
  * This method:
340
- * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
349
+ * 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
341
350
  * 2. Sets up the callback to process future page updates
342
351
  * 3. Returns the initial page immediately
343
352
  *
@@ -363,8 +372,13 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
363
372
  * ```
364
373
  *
365
374
  * @remarks
366
- * By default, this uses SurrealDB live queries for real-time updates.
367
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
375
+ * By default, this uses SPARQL live queries for real-time updates.
376
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
368
377
  */
369
378
  paginateSubscribe(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
379
+ /**
380
+ * Subscribes to paginated results updates using SPARQL.
381
+ * Delegates to paginateSubscribe() with SPARQL engine forced.
382
+ */
383
+ paginateSubscribeSparql(pageSize: number, pageNumber: number, callback: (results: PaginationResult<T>) => void): Promise<PaginationResult<T>>;
370
384
  }
@@ -4,6 +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";
8
+ import { pooledSubscribe } from "./subscription-pool";
7
9
  /** Query builder for Ad4mModel queries.
8
10
  * Allows building queries with a fluent interface and either running them once
9
11
  * or subscribing to updates.
@@ -28,7 +30,7 @@ export class ModelQueryBuilder {
28
30
  constructor(perspective, ctor, query) {
29
31
  this.queryParams = {};
30
32
  this.modelClassName = null;
31
- this.useSurrealDBFlag = true;
33
+ this.engineFlag = 'sparql';
32
34
  this.perspective = perspective;
33
35
  this.ctor = ctor;
34
36
  if (query)
@@ -236,32 +238,10 @@ export class ModelQueryBuilder {
236
238
  return this;
237
239
  }
238
240
  /**
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).
241
+ * Sets the query engine to use.
262
242
  */
263
- useSurrealDB(enabled = true) {
264
- this.useSurrealDBFlag = enabled;
243
+ engine(eng) {
244
+ this.engineFlag = eng;
265
245
  return this;
266
246
  }
267
247
  /**
@@ -278,10 +258,8 @@ export class ModelQueryBuilder {
278
258
  */
279
259
  async get() {
280
260
  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));
261
+ if (this.engineFlag === 'sparql') {
262
+ results = await this.executeSparqlQuery();
285
263
  }
286
264
  else {
287
265
  const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -290,6 +268,29 @@ export class ModelQueryBuilder {
290
268
  }
291
269
  return results;
292
270
  }
271
+ /**
272
+ * Executes the query once using SPARQL and returns the results.
273
+ */
274
+ async getSparql() {
275
+ return this.executeSparqlQuery();
276
+ }
277
+ /**
278
+ * Shared SPARQL query execution logic used by both get() and getSparql().
279
+ */
280
+ async executeSparqlQuery() {
281
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
282
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
283
+ const { results } = await this.processSparqlResult(rawResult);
284
+ return results;
285
+ }
286
+ /**
287
+ * Groups raw SPARQL results and hydrates them into model instances.
288
+ * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
289
+ */
290
+ async processSparqlResult(rawResult, queryOverride) {
291
+ const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
292
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped);
293
+ }
293
294
  /**
294
295
  * Returns the first matching instance, or `null` if none match.
295
296
  *
@@ -313,7 +314,7 @@ export class ModelQueryBuilder {
313
314
  * Subscribes to the query and receives updates when results change.
314
315
  *
315
316
  * This method:
316
- * 1. Creates and initializes a SurrealDB live query subscription (default)
317
+ * 1. Creates and initializes a SPARQL live query subscription (default)
317
318
  * 2. Sets up the callback to process future updates
318
319
  * 3. Returns the initial results immediately
319
320
  *
@@ -337,26 +338,40 @@ export class ModelQueryBuilder {
337
338
  * ```
338
339
  *
339
340
  * @remarks
340
- * By default, this uses SurrealDB live queries for real-time updates.
341
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
341
+ * By default, this uses SPARQL live queries for real-time updates.
342
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
342
343
  */
343
344
  async subscribe(callback) {
344
345
  // Clean up any existing subscription
345
346
  this.dispose();
346
347
  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);
348
+ if (this.engineFlag === 'sparql') {
349
+ const sparqlQuery = await ctor.queryToSPARQL(this.perspective, this.queryParams);
350
+ // Track last emitted result fingerprint to suppress duplicate callbacks
351
+ let lastResultFingerprint = null;
352
+ const buildFingerprint = (results) => {
353
+ if (results.length === 0)
354
+ 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}`;
353
358
  };
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;
359
+ const hydrate = async (rawResult) => {
360
+ const { results } = await this.processSparqlResult(rawResult);
361
+ return results;
362
+ };
363
+ const pooled = await pooledSubscribe(this.perspective, sparqlQuery, hydrate, (hydratedResults) => {
364
+ const fp = buildFingerprint(hydratedResults);
365
+ if (fp === lastResultFingerprint)
366
+ return;
367
+ lastResultFingerprint = fp;
368
+ callback(hydratedResults);
369
+ });
370
+ // Store dispose function as subscription
371
+ this.currentSubscription = { dispose: pooled.dispose };
372
+ const initialResults = pooled.initialResult;
373
+ lastResultFingerprint = buildFingerprint(initialResults);
374
+ return initialResults;
360
375
  }
361
376
  else {
362
377
  const query = await ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -367,11 +382,26 @@ export class ModelQueryBuilder {
367
382
  };
368
383
  this.currentSubscription.onResult(processResults);
369
384
  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);
385
+ // Initial results returned via Promise only — callback is for subsequent updates
372
386
  return results;
373
387
  }
374
388
  }
389
+ /**
390
+ * Subscribes to the query and receives updates using SPARQL.
391
+ */
392
+ async subscribeSparql(callback) {
393
+ this.dispose();
394
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
395
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
396
+ const processResults = async (result) => {
397
+ const { results } = await this.processSparqlResult(result);
398
+ callback(results);
399
+ };
400
+ this.currentSubscription.onResult(processResults);
401
+ const { results } = await this.processSparqlResult(this.currentSubscription.result);
402
+ // Initial results returned via Promise only — callback is for subsequent updates
403
+ return results;
404
+ }
375
405
  /**
376
406
  * Gets the total count of matching entities.
377
407
  *
@@ -385,13 +415,10 @@ export class ModelQueryBuilder {
385
415
  * ```
386
416
  */
387
417
  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);
418
+ 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);
395
422
  return totalCount;
396
423
  }
397
424
  else {
@@ -400,11 +427,25 @@ export class ModelQueryBuilder {
400
427
  return result?.[0]?.TotalCount || 0;
401
428
  }
402
429
  }
430
+ /**
431
+ * Gets the total count of matching entities using SPARQL.
432
+ * Delegates to count() with SPARQL engine forced.
433
+ */
434
+ async countSparql() {
435
+ const prev = this.engineFlag;
436
+ this.engineFlag = 'sparql';
437
+ try {
438
+ return await this.count();
439
+ }
440
+ finally {
441
+ this.engineFlag = prev;
442
+ }
443
+ }
403
444
  /**
404
445
  * Subscribes to count updates for matching entities.
405
446
  *
406
447
  * This method:
407
- * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
448
+ * 1. Creates and initializes a SPARQL live query subscription for the count (default)
408
449
  * 2. Sets up the callback to process future count updates
409
450
  * 3. Returns the initial count immediately
410
451
  *
@@ -428,22 +469,22 @@ export class ModelQueryBuilder {
428
469
  * ```
429
470
  *
430
471
  * @remarks
431
- * By default, this uses SurrealDB live queries for real-time updates.
432
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
472
+ * By default, this uses SPARQL live queries for real-time updates.
473
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
433
474
  */
434
475
  async countSubscribe(callback) {
435
476
  // Clean up any existing subscription
436
477
  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);
478
+ if (this.engineFlag === 'sparql') {
479
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
480
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
440
481
  const processResults = async (result) => {
441
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
482
+ const { totalCount } = await this.processSparqlResult(result);
442
483
  callback(totalCount);
443
484
  };
444
485
  this.currentSubscription.onResult(processResults);
445
- const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, this.currentSubscription.result);
446
- callback(totalCount);
486
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
487
+ // Initial count returned via Promise — callback for updates only
447
488
  return totalCount;
448
489
  }
449
490
  else {
@@ -455,10 +496,26 @@ export class ModelQueryBuilder {
455
496
  };
456
497
  this.currentSubscription.onResult(processResults);
457
498
  const initialCount = this.currentSubscription.result?.[0]?.TotalCount || 0;
458
- callback(initialCount);
499
+ // Initial count returned via Promise — callback for subsequent updates only
459
500
  return initialCount;
460
501
  }
461
502
  }
503
+ /**
504
+ * Subscribes to count updates using SPARQL.
505
+ */
506
+ async countSubscribeSparql(callback) {
507
+ this.dispose();
508
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
509
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
510
+ const processResults = async (result) => {
511
+ const { totalCount } = await this.processSparqlResult(result);
512
+ callback(totalCount);
513
+ };
514
+ this.currentSubscription.onResult(processResults);
515
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
516
+ // Initial count returned via Promise — callback for updates only
517
+ return totalCount;
518
+ }
462
519
  /**
463
520
  * Gets a page of results with pagination metadata.
464
521
  *
@@ -476,10 +533,10 @@ export class ModelQueryBuilder {
476
533
  */
477
534
  async paginate(pageSize, pageNumber) {
478
535
  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));
536
+ if (this.engineFlag === 'sparql') {
537
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
538
+ const result = await this.perspective.querySparql(sparqlQuery);
539
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
483
540
  return { results, totalCount, pageSize, pageNumber };
484
541
  }
485
542
  else {
@@ -489,11 +546,25 @@ export class ModelQueryBuilder {
489
546
  return { results, totalCount, pageSize, pageNumber };
490
547
  }
491
548
  }
549
+ /**
550
+ * Gets a page of results using SPARQL.
551
+ * Delegates to paginate() with SPARQL engine forced.
552
+ */
553
+ async paginateSparql(pageSize, pageNumber) {
554
+ const prev = this.engineFlag;
555
+ this.engineFlag = 'sparql';
556
+ try {
557
+ return await this.paginate(pageSize, pageNumber);
558
+ }
559
+ finally {
560
+ this.engineFlag = prev;
561
+ }
562
+ }
492
563
  /**
493
564
  * Subscribes to paginated results updates.
494
565
  *
495
566
  * This method:
496
- * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
567
+ * 1. Creates and initializes a SPARQL live query subscription for the paginated results (default)
497
568
  * 2. Sets up the callback to process future page updates
498
569
  * 3. Returns the initial page immediately
499
570
  *
@@ -519,24 +590,24 @@ export class ModelQueryBuilder {
519
590
  * ```
520
591
  *
521
592
  * @remarks
522
- * By default, this uses SurrealDB live queries for real-time updates.
523
- * Prolog subscriptions remain available via `.useSurrealDB(false)`.
593
+ * By default, this uses SPARQL live queries for real-time updates.
594
+ * Prolog subscriptions remain available via `.useSPARQL(false)`.
524
595
  */
525
596
  async paginateSubscribe(pageSize, pageNumber, callback) {
526
597
  // Clean up any existing subscription
527
598
  this.dispose();
528
599
  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);
600
+ if (this.engineFlag === 'sparql') {
601
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
602
+ this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
532
603
  const processResults = async (result) => {
533
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result));
604
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
534
605
  callback({ results, totalCount, pageSize, pageNumber });
535
606
  };
536
607
  this.currentSubscription.onResult(processResults);
537
- const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result));
608
+ const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery);
538
609
  const initialPage = { results, totalCount, pageSize, pageNumber };
539
- callback(initialPage);
610
+ // Initial page returned via Promise — callback for subsequent updates only
540
611
  return initialPage;
541
612
  }
542
613
  else {
@@ -549,8 +620,22 @@ export class ModelQueryBuilder {
549
620
  this.currentSubscription.onResult(processResults);
550
621
  const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result));
551
622
  const initialPrologPage = { results, totalCount, pageSize, pageNumber };
552
- callback(initialPrologPage);
623
+ // Initial page returned via Promise — callback for subsequent updates only
553
624
  return initialPrologPage;
554
625
  }
555
626
  }
627
+ /**
628
+ * Subscribes to paginated results updates using SPARQL.
629
+ * Delegates to paginateSubscribe() with SPARQL engine forced.
630
+ */
631
+ async paginateSubscribeSparql(pageSize, pageNumber, callback) {
632
+ const prev = this.engineFlag;
633
+ this.engineFlag = 'sparql';
634
+ try {
635
+ return await this.paginateSubscribe(pageSize, pageNumber, callback);
636
+ }
637
+ finally {
638
+ this.engineFlag = prev;
639
+ }
640
+ }
556
641
  }
@@ -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
  }
@@ -19,7 +19,7 @@ export interface RelationMetadataEntry {
19
19
  maxCount?: number;
20
20
  local?: boolean;
21
21
  /**
22
- * Custom SurrealQL getter to resolve the relation values.
22
+ * Custom getter to resolve the relation values.
23
23
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
24
24
  */
25
25
  getter?: string;
@@ -39,13 +39,19 @@ export interface RelationMetadataEntry {
39
39
  /**
40
40
  * Retrieve property metadata for a given class constructor.
41
41
  * Walks the prototype chain so subclass decorators compose with parent decorators.
42
+ * Results are memoised per class constructor.
42
43
  */
43
44
  export declare function getPropertiesMetadata(ctor: Function): Record<string, PropertyMetadataEntry>;
44
45
  /**
45
46
  * Retrieve relation metadata for a given class constructor.
46
47
  * Walks the prototype chain so subclass decorators compose with parent decorators.
48
+ * Results are memoised per class constructor.
47
49
  */
48
50
  export declare function getRelationsMetadata(ctor: Function): Record<string, RelationMetadataEntry>;
51
+ /**
52
+ * Get or compute memoised SHACL for a class. Used by @Model decorator.
53
+ */
54
+ export declare function getMemoizedSHACL(target: Function, compute: () => any): any;
49
55
  /**
50
56
  * Programmatically register property metadata for a given constructor.
51
57
  * Used by `fromJSONSchema()` and other dynamic model builders.
@@ -72,7 +78,7 @@ export interface Ad4mModelLike {
72
78
  *
73
79
  * Inspects the target class's property metadata to derive:
74
80
  * - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
75
- * - `getter`: Pre-computed SurrealQL expression that traverses outgoing links and filters
81
+ * - `getter`: Pre-computed graph traversal expression that traverses outgoing links and filters
76
82
  * target nodes to only those conforming to the target shape.
77
83
  *
78
84
  * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
@@ -114,9 +120,9 @@ export interface PropertyOptions {
114
120
  */
115
121
  prologSetter?: string;
116
122
  /**
117
- * Custom SurrealQL getter to resolve the property value. Use this for custom graph traversals.
123
+ * Custom getter to resolve the property value. Use this for custom graph traversals.
118
124
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
119
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].in.uri)[0]"
125
+ * Example: "SELECT ?target WHERE { <Base> <flux://has_reply> ?target . } LIMIT 1"
120
126
  */
121
127
  getter?: string;
122
128
  /**
@@ -294,7 +300,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
294
300
  * Properties are optional by default. When a model instance is created without
295
301
  * providing a value for an optional property, no link is added to the graph.
296
302
  * Set `required: true` explicitly when a property must always be present (this
297
- * also adds a `"literal://string:uninitialized"` sentinel as the initial value
303
+ * also adds a `"literal:string:uninitialized"` sentinel as the initial value
298
304
  * so that the SDNA constructor creates a placeholder link).
299
305
  *
300
306
  * @example
@@ -333,7 +339,7 @@ export declare function Model(opts: ModelConfig): (target: any) => void;
333
339
  * @param {PropertyOptions} opts - Property configuration
334
340
  * @param {string} opts.through - The predicate URI for the property
335
341
  * @param {boolean} [opts.required=false] - Whether the property is required (adds query filters and sentinel initial value)
336
- * @param {string} [opts.initial] - Initial value (defaults to "literal://string:uninitialized" when required)
342
+ * @param {string} [opts.initial] - Initial value (defaults to "literal:string:uninitialized" when required)
337
343
  * @param {string} [opts.resolveLanguage] - Language to use for value resolution (e.g. "literal")
338
344
  * @param {string} [opts.prologGetter] - Custom Prolog code for getting the property value
339
345
  * @param {string} [opts.prologSetter] - Custom Prolog code for setting the property value
@@ -410,9 +416,9 @@ export interface RelationOptions {
410
416
  * Cannot be combined with `getter`. */
411
417
  target?: () => Ad4mModelLike;
412
418
  /**
413
- * Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
419
+ * Custom getter to resolve the relation values. Use this for custom graph traversals.
414
420
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
415
- * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
421
+ * Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
416
422
  *
417
423
  * Mutually exclusive with `through` and `target`. When `getter` is provided the
418
424
  * relation is read-only (no adder/remover actions are generated).