@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
@@ -20,8 +20,10 @@ export class Literal {
20
20
  _Literal_url.set(this, void 0);
21
21
  }
22
22
  static fromUrl(url) {
23
- if (!url || !url.startsWith("literal://"))
23
+ if (!url || !url.startsWith("literal:"))
24
24
  throw new Error("Can't create Literal from non-literal URL");
25
+ if (url.startsWith("literal://"))
26
+ throw new Error("literal:// format is no longer supported. Use literal: instead.");
25
27
  const l = new Literal();
26
28
  __classPrivateFieldSet(l, _Literal_url, url, "f");
27
29
  return l;
@@ -51,17 +53,16 @@ export class Literal {
51
53
  encoded = `json:${encodeRFC3986URIComponent(JSON.stringify(__classPrivateFieldGet(this, _Literal_literal, "f")))}`;
52
54
  break;
53
55
  }
54
- return `literal://${encoded}`;
56
+ return `literal:${encoded}`;
55
57
  }
56
58
  get() {
57
59
  if (__classPrivateFieldGet(this, _Literal_literal, "f"))
58
60
  return __classPrivateFieldGet(this, _Literal_literal, "f");
59
61
  if (!__classPrivateFieldGet(this, _Literal_url, "f"))
60
62
  throw new Error("Can't render empty Literal");
61
- if (!__classPrivateFieldGet(this, _Literal_url, "f").startsWith("literal://"))
63
+ if (!__classPrivateFieldGet(this, _Literal_url, "f").startsWith("literal:"))
62
64
  throw new Error("Can't render Literal from non-literal URL");
63
- // get rid of "literal://"
64
- const body = __classPrivateFieldGet(this, _Literal_url, "f").substring(10);
65
+ const body = __classPrivateFieldGet(this, _Literal_url, "f").substring(8);
65
66
  if (body.startsWith("string:")) {
66
67
  return decodeURIComponent(body.substring(7));
67
68
  }
@@ -1,7 +1,7 @@
1
1
  import { ApolloClient } from "@apollo/client/core";
2
2
  import { PerspectiveInput } from "../perspectives/Perspective";
3
3
  import { Agent, Apps, AuthInfoInput, EntanglementProof, EntanglementProofInput, UserCreationResult } from "./Agent";
4
- import { HostingUserInfo, PaymentRequestResult } from "../runtime/RuntimeResolver";
4
+ import { HostingUserInfo, PaymentRequestResult, ComputeLogEntry } from "../runtime/RuntimeResolver";
5
5
  import { AgentStatus } from "./AgentStatus";
6
6
  import { LinkMutations } from "../links/Links";
7
7
  import { VerificationRequestResult } from "../runtime/RuntimeResolver";
@@ -14,6 +14,8 @@ export interface InitializeArgs {
14
14
  export type AgentUpdatedCallback = (agent: Agent) => null;
15
15
  export type AgentStatusChangedCallback = (agent: Agent) => null;
16
16
  export type AgentAppsUpdatedCallback = () => null;
17
+ export type HostingUserInfoChangedCallback = (info: HostingUserInfo) => void;
18
+ export type ComputeLogUpdatedCallback = (entry: ComputeLogEntry) => void;
17
19
  /**
18
20
  * Provides access to all functions regarding the local agent,
19
21
  * such as generating, locking, unlocking, importing the DID keystore,
@@ -48,6 +50,10 @@ export declare class AgentClient {
48
50
  subscribeAppsChanged(): void;
49
51
  addAgentStatusChangedListener(listener: any): void;
50
52
  subscribeAgentStatusChanged(): void;
53
+ addHostingUserInfoChangedListener(listener: HostingUserInfoChangedCallback): void;
54
+ subscribeHostingUserInfoChanged(): void;
55
+ addComputeLogUpdatedListener(listener: ComputeLogUpdatedCallback): void;
56
+ subscribeComputeLogUpdated(): void;
51
57
  requestCapability(authInfo: AuthInfoInput): Promise<string>;
52
58
  permitCapability(auth: string): Promise<string>;
53
59
  generateJwt(requestId: string, rand: string): Promise<string>;
@@ -61,6 +67,7 @@ export declare class AgentClient {
61
67
  requestLoginVerification(email: string, appInfo?: AuthInfoInput): Promise<VerificationRequestResult>;
62
68
  verifyEmailCode(email: string, code: string, verificationType: string): Promise<string>;
63
69
  hostingUserInfo(): Promise<HostingUserInfo>;
70
+ computeLog(since?: string, limit?: number, userEmail?: string): Promise<ComputeLogEntry[]>;
64
71
  setHotWalletAddress(address: string): Promise<boolean>;
65
72
  requestPayment(amountHOT: string): Promise<PaymentRequestResult>;
66
73
  }
@@ -9,7 +9,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _AgentClient_apolloClient, _AgentClient_appsChangedCallback, _AgentClient_updatedCallbacks, _AgentClient_agentStatusChangedCallbacks;
12
+ var _AgentClient_apolloClient, _AgentClient_appsChangedCallback, _AgentClient_updatedCallbacks, _AgentClient_agentStatusChangedCallbacks, _AgentClient_hostingUserInfoChangedCallbacks, _AgentClient_computeLogUpdatedCallbacks;
13
13
  import { gql } from "@apollo/client/core";
14
14
  import unwrapApolloResult from "../unwrapApolloResult";
15
15
  import { Agent, } from "./Agent";
@@ -77,10 +77,14 @@ export class AgentClient {
77
77
  _AgentClient_appsChangedCallback.set(this, void 0);
78
78
  _AgentClient_updatedCallbacks.set(this, void 0);
79
79
  _AgentClient_agentStatusChangedCallbacks.set(this, void 0);
80
+ _AgentClient_hostingUserInfoChangedCallbacks.set(this, void 0);
81
+ _AgentClient_computeLogUpdatedCallbacks.set(this, void 0);
80
82
  __classPrivateFieldSet(this, _AgentClient_apolloClient, client, "f");
81
83
  __classPrivateFieldSet(this, _AgentClient_updatedCallbacks, [], "f");
82
84
  __classPrivateFieldSet(this, _AgentClient_agentStatusChangedCallbacks, [], "f");
83
85
  __classPrivateFieldSet(this, _AgentClient_appsChangedCallback, [], "f");
86
+ __classPrivateFieldSet(this, _AgentClient_hostingUserInfoChangedCallbacks, [], "f");
87
+ __classPrivateFieldSet(this, _AgentClient_computeLogUpdatedCallbacks, [], "f");
84
88
  if (subscribe) {
85
89
  this.subscribeAgentUpdated();
86
90
  this.subscribeAgentStatusChanged();
@@ -341,6 +345,55 @@ export class AgentClient {
341
345
  error: (e) => console.error(e),
342
346
  });
343
347
  }
348
+ addHostingUserInfoChangedListener(listener) {
349
+ __classPrivateFieldGet(this, _AgentClient_hostingUserInfoChangedCallbacks, "f").push(listener);
350
+ }
351
+ subscribeHostingUserInfoChanged() {
352
+ __classPrivateFieldGet(this, _AgentClient_apolloClient, "f")
353
+ .subscribe({
354
+ query: gql `subscription {
355
+ runtimeHostingUserInfoChanged {
356
+ email
357
+ remainingCredits
358
+ hotWalletAddress
359
+ freeAccess
360
+ }
361
+ }`,
362
+ })
363
+ .subscribe({
364
+ next: (result) => {
365
+ const info = result.data.runtimeHostingUserInfoChanged;
366
+ __classPrivateFieldGet(this, _AgentClient_hostingUserInfoChangedCallbacks, "f").forEach((cb) => cb(info));
367
+ },
368
+ error: (e) => console.error(e),
369
+ });
370
+ }
371
+ addComputeLogUpdatedListener(listener) {
372
+ __classPrivateFieldGet(this, _AgentClient_computeLogUpdatedCallbacks, "f").push(listener);
373
+ }
374
+ subscribeComputeLogUpdated() {
375
+ __classPrivateFieldGet(this, _AgentClient_apolloClient, "f")
376
+ .subscribe({
377
+ query: gql `subscription {
378
+ runtimeComputeLogUpdated {
379
+ id
380
+ userEmail
381
+ timestamp
382
+ operation
383
+ summary
384
+ cost
385
+ creditsAfter
386
+ }
387
+ }`,
388
+ })
389
+ .subscribe({
390
+ next: (result) => {
391
+ const entry = result.data.runtimeComputeLogUpdated;
392
+ __classPrivateFieldGet(this, _AgentClient_computeLogUpdatedCallbacks, "f").forEach((cb) => cb(entry));
393
+ },
394
+ error: (e) => console.error(e),
395
+ });
396
+ }
344
397
  async requestCapability(authInfo) {
345
398
  const { agentRequestCapability } = unwrapApolloResult(await __classPrivateFieldGet(this, _AgentClient_apolloClient, "f").mutate({
346
399
  mutation: gql `
@@ -487,6 +540,24 @@ export class AgentClient {
487
540
  }));
488
541
  return runtimeHostingUserInfo;
489
542
  }
543
+ async computeLog(since, limit, userEmail) {
544
+ const { runtimeComputeLog } = unwrapApolloResult(await __classPrivateFieldGet(this, _AgentClient_apolloClient, "f").query({
545
+ query: gql `query runtimeComputeLog($since: String, $limit: Int, $userEmail: String) {
546
+ runtimeComputeLog(since: $since, limit: $limit, userEmail: $userEmail) {
547
+ id
548
+ userEmail
549
+ timestamp
550
+ operation
551
+ summary
552
+ cost
553
+ creditsAfter
554
+ }
555
+ }`,
556
+ variables: { since, limit, userEmail },
557
+ fetchPolicy: 'network-only',
558
+ }));
559
+ return runtimeComputeLog;
560
+ }
490
561
  async setHotWalletAddress(address) {
491
562
  const { runtimeSetHotWalletAddress } = unwrapApolloResult(await __classPrivateFieldGet(this, _AgentClient_apolloClient, "f").mutate({
492
563
  mutation: gql `mutation runtimeSetHotWalletAddress($address: String!) {
@@ -509,4 +580,4 @@ export class AgentClient {
509
580
  return runtimeRequestPayment;
510
581
  }
511
582
  }
512
- _AgentClient_apolloClient = new WeakMap(), _AgentClient_appsChangedCallback = new WeakMap(), _AgentClient_updatedCallbacks = new WeakMap(), _AgentClient_agentStatusChangedCallbacks = new WeakMap();
583
+ _AgentClient_apolloClient = new WeakMap(), _AgentClient_appsChangedCallback = new WeakMap(), _AgentClient_updatedCallbacks = new WeakMap(), _AgentClient_agentStatusChangedCallbacks = new WeakMap(), _AgentClient_hostingUserInfoChangedCallbacks = new WeakMap(), _AgentClient_computeLogUpdatedCallbacks = new WeakMap();
@@ -38,11 +38,11 @@ export function exprRef2String(ref) {
38
38
  return `${ref.language.address}://${ref.expression}`;
39
39
  }
40
40
  export function parseExprUrl(url) {
41
- if (url.startsWith("literal://")) {
41
+ if (url.startsWith("literal:")) {
42
42
  const languageRef = new LanguageRef();
43
43
  languageRef.address = 'literal';
44
44
  languageRef.name = 'literal';
45
- const content = url.substring(10);
45
+ const content = url.substring(8);
46
46
  return new ExpressionRef(languageRef, content);
47
47
  }
48
48
  const URIregexp = /^([^:^\s]+):\/\/([\s\S]+)$/;
@@ -4,6 +4,7 @@ import type { Expression } from '../expression/Expression';
4
4
  import { Perspective, PerspectiveExpression } from '../perspectives/Perspective';
5
5
  import { PerspectiveDiff } from '../perspectives/PerspectiveDiff';
6
6
  import { PerspectiveState } from '../perspectives/PerspectiveHandle';
7
+ import { LinkQuery } from '../perspectives/LinkQuery';
7
8
  /** Interface of AD4M Languages
8
9
  *
9
10
  * Any JavaScript module that implements a create() function that returns an object that implements this interface
@@ -34,7 +35,11 @@ export interface Language {
34
35
  /** Interface for getting UI/web components for rendering Expressions of this Language */
35
36
  readonly expressionUI?: ExpressionUI;
36
37
  /** Interface of LinkLanguages for the core implementation of Neighbourhoods */
37
- readonly linksAdapter?: LinkSyncAdapter;
38
+ readonly perspectiveSyncAdapter?: PerspectiveSyncAdapter;
39
+ /** Interface for Languages that implement a query return a Perspective (snapshot)
40
+ * Used for back-links and wrapping of APIs that implement queries.
41
+ */
42
+ readonly pespectiveQueryAdapter?: PerspectiveQueryAdapter;
38
43
  /** Additional Interface of LinkLanguages that support telepresence features,
39
44
  * that is:
40
45
  * - seeing who is online and getting a status
@@ -123,11 +128,11 @@ export type SyncStateChangeObserver = (state: PerspectiveState) => void;
123
128
  * The assumption is that every version of the shared Perspective
124
129
  * is labeled with a unique revision string.
125
130
  * Changes are committed and retrieved through diffs.
126
- * Think of a LinkSyncAdapter as a git branch to which agents commit
131
+ * Think of a PerspectiveSyncAdapter as a git branch to which agents commit
127
132
  * their changes to and pull diffs from their current revision
128
133
  * to the latest one.
129
134
  */
130
- export interface LinkSyncAdapter {
135
+ export interface PerspectiveSyncAdapter {
131
136
  writable(): boolean;
132
137
  public(): boolean;
133
138
  others(): Promise<DID[]>;
@@ -204,3 +209,36 @@ export interface TelepresenceAdapter {
204
209
  sendBroadcast(payload: PerspectiveExpression): Promise<object>;
205
210
  registerSignalCallback(callback: TelepresenceSignalCallback): Promise<void>;
206
211
  }
212
+ /** Interface for Languages that implement queries returning links, i.e. a Perspective (-snapshot)
213
+ * Main differentiation between these Languages and LinkLanguages is that this enables
214
+ * access to other shared perspectives without forcing a full-sync.
215
+ *
216
+ * All PerspectiveQuery Languages are supposed to implement `linkQuery` which is a simple graph query
217
+ * specifying non or all of source, predicate, target of the links we want to get.
218
+ * This is enough to implement simple back-links.
219
+ *
220
+ * Prolog queries are optional since this requires a Prolog engine to be available.
221
+ *
222
+ */
223
+ export interface PerspectiveQueryAdapter {
224
+ /** Same semantic as PerspectiveProxy.get(LinkQuery) */
225
+ linkQuery(query: LinkQuery): Promise<Perspective>;
226
+ /** Tells ADAM if Prolog queries are implemented by this Language.
227
+ * If not, prologQuery won't be used, instead in some circumstances,
228
+ * linkQuery() might be called with an all-query, followed by using
229
+ * ADAM's internal Prolog engine on the result.
230
+ */
231
+ supportsPrologQueries(): boolean;
232
+ /** Same semantic as PerspectiveProxy.infer, will return plain Prolog results */
233
+ infer(prologQuery: string): Promise<any>;
234
+ /** Specify which links shall be returned through Prolog.
235
+ * Assumes unbound variables in query that describe a LinkExpression:
236
+ * - Source
237
+ * - Predicate
238
+ * - Target
239
+ * - Author
240
+ * - Timestamp
241
+ * Will construct a Perspective where each link is a solution to the query.
242
+ */
243
+ prologQuery(query: string): Promise<Perspective>;
244
+ }
@@ -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[]): 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). */