@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
@@ -184,7 +184,7 @@ export declare class Ad4mModel {
184
184
  * const recipe = new Recipe(perspective);
185
185
  *
186
186
  * // Create with specific base expression
187
- * const recipe = new Recipe(perspective, "literal://...");
187
+ * const recipe = new Recipe(perspective, "literal:...");
188
188
  * ```
189
189
  */
190
190
  constructor(perspective: PerspectiveProxy, baseExpression?: string);
@@ -270,13 +270,13 @@ export declare class Ad4mModel {
270
270
  private getData;
271
271
  static queryToProlog(perspective: PerspectiveProxy, query: Query, modelClassName?: string | null): Promise<string>;
272
272
  /**
273
- * Generates a SurrealQL query from a Query object.
273
+ * Generates a SPARQL query from a Query object.
274
274
  *
275
275
  * @description
276
- * This method translates high-level query parameters into a SurrealQL query string
277
- * that can be executed against the SurrealDB backend. Unlike Prolog queries which
278
- * operate on SDNA-aware predicates, SurrealQL queries operate directly on raw links
279
- * stored in SurrealDB.
276
+ * This method translates high-level query parameters into a SPARQL query string
277
+ * that can be executed against the SPARQL backend. Unlike Prolog queries which
278
+ * operate on SDNA-aware predicates, SPARQL queries operate directly on raw links
279
+ * stored in SPARQL.
280
280
  *
281
281
  * The generated query uses a CTE (Common Table Expression) pattern:
282
282
  * 1. First, identify candidate base expressions by filtering links based on where conditions
@@ -284,7 +284,7 @@ export declare class Ad4mModel {
284
284
  * 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
285
285
  *
286
286
  * Key architectural notes:
287
- * - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
287
+ * - SPARQL stores only raw links (source, predicate, target, author, timestamp)
288
288
  * - No SDNA knowledge at the database level
289
289
  * - Properties are resolved via subqueries that look for links with specific predicates
290
290
  * - Relations are similar but return multiple values instead of one
@@ -292,11 +292,11 @@ export declare class Ad4mModel {
292
292
  *
293
293
  * @param perspective - The perspective to query (used for metadata extraction)
294
294
  * @param query - Query parameters (where, order, limit, offset, properties, relations)
295
- * @returns Complete SurrealQL query string ready for execution
295
+ * @returns Complete SPARQL query string ready for execution
296
296
  *
297
297
  * @example
298
298
  * ```typescript
299
- * const query = Recipe.queryToSurrealQL(perspective, {
299
+ * const query = Recipe.queryToSPARQL(perspective, {
300
300
  * where: { name: "Pasta", rating: { gt: 4 } },
301
301
  * order: { timestamp: "DESC" },
302
302
  * limit: 10
@@ -305,33 +305,33 @@ export declare class Ad4mModel {
305
305
  * // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
306
306
  * ```
307
307
  */
308
- static queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
308
+ static queryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
309
309
  static instancesFromPrologResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: AllInstancesResult): Promise<ResultsWithTotalCount<T>>;
310
310
  /**
311
- * Converts SurrealDB query results to Ad4mModel instances.
311
+ * Converts SPARQL query results to Ad4mModel instances.
312
312
  *
313
313
  * @param perspective - The perspective context
314
314
  * @param query - The query parameters used
315
- * @param result - Array of result objects from SurrealDB
315
+ * @param result - Array of result objects from SPARQL
316
316
  * @returns Promise resolving to results with total count
317
317
  *
318
318
  * @internal
319
319
  */
320
- static instancesFromSurrealResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: any[]): Promise<ResultsWithTotalCount<T>>;
320
+ static instancesFromQueryResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query: Query, result: any[], computeTotalCount?: boolean): Promise<ResultsWithTotalCount<T>>;
321
321
  /**
322
322
  * Gets all instances of the model in the perspective that match the query params.
323
323
  *
324
324
  * @param perspective - The perspective to search in
325
325
  * @param query - Optional query parameters to filter results
326
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
326
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
327
327
  * @returns Array of matching models
328
328
  *
329
329
  * @example
330
330
  * ```typescript
331
- * // Get all recipes (uses SurrealDB by default)
331
+ * // Get all recipes (uses SPARQL by default)
332
332
  * const allRecipes = await Recipe.findAll(perspective);
333
333
  *
334
- * // Get recipes with specific criteria (uses SurrealDB)
334
+ * // Get recipes with specific criteria (uses SPARQL)
335
335
  * const recipes = await Recipe.findAll(perspective, {
336
336
  * where: {
337
337
  * name: "Pasta",
@@ -345,7 +345,7 @@ export declare class Ad4mModel {
345
345
  * const recipesProlog = await Recipe.findAll(perspective, {}, false);
346
346
  * ```
347
347
  */
348
- static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): Promise<T[]>;
348
+ static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, engine?: 'sparql' | 'prolog' | boolean): Promise<T[]>;
349
349
  /**
350
350
  * Finds the first instance matching the query, or `null` if none exists.
351
351
  *
@@ -353,7 +353,7 @@ export declare class Ad4mModel {
353
353
  *
354
354
  * @param perspective - The perspective to search in
355
355
  * @param query - Optional query parameters to filter results
356
- * @param useSurrealDB - Whether to use SurrealDB (default: true) or Prolog (legacy)
356
+ * @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
357
357
  * @returns The first matching instance, or `null`
358
358
  *
359
359
  * @example
@@ -366,13 +366,13 @@ export declare class Ad4mModel {
366
366
  * }
367
367
  * ```
368
368
  */
369
- static findOne<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): Promise<T | null>;
369
+ static findOne<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, engine?: 'sparql' | 'prolog' | boolean): Promise<T | null>;
370
370
  /**
371
371
  * Gets all instances with count of total matches without offset & limit applied.
372
372
  *
373
373
  * @param perspective - The perspective to search in
374
374
  * @param query - Optional query parameters to filter results
375
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
375
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
376
376
  * @returns Object containing results array and total count
377
377
  *
378
378
  * @example
@@ -387,7 +387,7 @@ export declare class Ad4mModel {
387
387
  * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
388
388
  * ```
389
389
  */
390
- static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): Promise<ResultsWithTotalCount<T>>;
390
+ static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, engine?: 'sparql' | 'prolog' | boolean): Promise<ResultsWithTotalCount<T>>;
391
391
  /**
392
392
  * Helper function for pagination with explicit page size and number.
393
393
  *
@@ -395,7 +395,7 @@ export declare class Ad4mModel {
395
395
  * @param pageSize - Number of items per page
396
396
  * @param pageNumber - Which page to retrieve (1-based)
397
397
  * @param query - Optional additional query parameters
398
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
398
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
399
399
  * @returns Paginated results with metadata
400
400
  *
401
401
  * @example
@@ -409,24 +409,24 @@ export declare class Ad4mModel {
409
409
  * const pageProlog = await Recipe.paginate(perspective, 10, 1, {}, false);
410
410
  * ```
411
411
  */
412
- static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query, useSurrealDB?: boolean): Promise<PaginationResult<T>>;
412
+ static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query, engine?: 'sparql' | 'prolog' | boolean): Promise<PaginationResult<T>>;
413
413
  static countQueryToProlog(perspective: PerspectiveProxy, query?: Query, modelClassName?: string | null): Promise<string>;
414
414
  /**
415
- * Generates a SurrealQL COUNT query for the model.
415
+ * Generates a SPARQL COUNT query for the model.
416
416
  *
417
417
  * @param perspective - The perspective context
418
418
  * @param query - Query parameters to filter the count
419
- * @returns SurrealQL COUNT query string
419
+ * @returns SPARQL COUNT query string
420
420
  *
421
421
  * @private
422
422
  */
423
- static countQueryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
423
+ static countQueryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
424
424
  /**
425
425
  * Gets a count of all matching instances.
426
426
  *
427
427
  * @param perspective - The perspective to search in
428
428
  * @param query - Optional query parameters to filter results
429
- * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
429
+ * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
430
430
  * @returns Total count of matching entities
431
431
  *
432
432
  * @example
@@ -440,7 +440,7 @@ export declare class Ad4mModel {
440
440
  * const countProlog = await Recipe.count(perspective, {}, false);
441
441
  * ```
442
442
  */
443
- static count(perspective: PerspectiveProxy, query?: Query, useSurrealDB?: boolean): any;
443
+ static count(perspective: PerspectiveProxy, query?: Query, engine?: 'sparql' | 'prolog' | boolean): any;
444
444
  private setProperty;
445
445
  /** Resolve a relation argument to a plain string ID. Accepts either a raw
446
446
  * string ID or an Ad4mModel instance (in which case `.id` is used). */
@@ -477,6 +477,30 @@ export declare class Ad4mModel {
477
477
  save(batchId?: string): Promise<void>;
478
478
  private cleanCopy;
479
479
  private innerUpdate;
480
+ /**
481
+ * Evaluate SPARQL getters for a batch of instances on demand.
482
+ *
483
+ * Use after a shallow collection query (the default) to resolve
484
+ * getter-backed properties for visible items only. This avoids the
485
+ * O(N × getters) cost of evaluating every getter on every instance in
486
+ * a large collection query.
487
+ *
488
+ * @param instances - Array of model instances to evaluate getters on
489
+ * @param perspective - The perspective to query against
490
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
491
+ * If omitted, all getters are evaluated.
492
+ *
493
+ * @example
494
+ * ```typescript
495
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
496
+ * // messages[i].replyingTo is undefined (getter skipped by default)
497
+ *
498
+ * // Evaluate getters for the visible subset
499
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
500
+ * // messages[0..9].replyingTo is now populated
501
+ * ```
502
+ */
503
+ static evaluateGetters<T extends Ad4mModel>(instances: T[], perspective: PerspectiveProxy, propertyNames?: string[]): Promise<void>;
480
504
  /**
481
505
  * Gets the model instance with all properties and relations populated.
482
506
  *