@coasys/ad4m 0.12.0-rc1-dev.5 → 0.12.0-rc2

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 (161) hide show
  1. package/lib/index.cjs +4968 -4805
  2. package/lib/index.js +4936 -4801
  3. package/lib/src/agent/AgentClient.d.ts +4 -0
  4. package/lib/src/agent/AgentClient.js +34 -0
  5. package/lib/src/index.d.ts +2 -3
  6. package/lib/src/index.js +2 -3
  7. package/lib/src/model/Ad4mModel.d.ts +8 -812
  8. package/lib/src/model/Ad4mModel.js +78 -2390
  9. package/lib/src/model/ModelQueryBuilder.d.ts +370 -0
  10. package/lib/src/model/ModelQueryBuilder.js +556 -0
  11. package/lib/src/model/decorators.d.ts +2 -20
  12. package/lib/src/model/decorators.js +5 -410
  13. package/lib/src/model/hydration.d.ts +102 -0
  14. package/lib/src/model/hydration.js +709 -0
  15. package/lib/src/model/index.d.ts +20 -0
  16. package/lib/src/model/index.js +20 -0
  17. package/lib/src/model/{schema/fromJSONSchema.d.ts → json-schema.d.ts} +45 -12
  18. package/lib/src/model/json-schema.js +326 -0
  19. package/lib/src/model/prolog-facts.d.ts +37 -0
  20. package/lib/src/model/{prolog/generatePrologFacts.js → prolog-facts.js} +47 -52
  21. package/lib/src/model/query-common.d.ts +14 -0
  22. package/lib/src/model/query-common.js +36 -0
  23. package/lib/src/model/query-prolog.d.ts +15 -0
  24. package/lib/src/model/query-prolog.js +140 -0
  25. package/lib/src/model/query-surreal.d.ts +44 -0
  26. package/lib/src/model/query-surreal.js +249 -0
  27. package/lib/src/model/sdna.d.ts +14 -0
  28. package/lib/src/model/sdna.js +141 -0
  29. package/lib/src/model/shacl-gen.d.ts +31 -0
  30. package/lib/src/model/shacl-gen.js +246 -0
  31. package/lib/src/model/surreal-utils.d.ts +1 -1
  32. package/lib/src/model/types.d.ts +75 -96
  33. package/lib/src/model/types.js +4 -4
  34. package/lib/src/model/util.d.ts +4 -5
  35. package/lib/src/model/util.js +12 -32
  36. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  37. package/lib/src/perspectives/PerspectiveProxy.d.ts +1 -1
  38. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +79 -0
  39. package/lib/src/perspectives/WakerSubscriptionManager.js +196 -0
  40. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  41. package/lib/src/runtime/RuntimeResolver.js +73 -0
  42. package/lib/src/schema.gql +14 -0
  43. package/lib/src/typeDefs.js +14 -0
  44. package/package.json +13 -8
  45. package/src/agent/AgentClient.ts +45 -0
  46. package/src/index.ts +2 -3
  47. package/src/model/Ad4mModel.ts +1084 -3818
  48. package/src/model/ModelQueryBuilder.ts +617 -0
  49. package/src/model/Subject.ts +1 -1
  50. package/src/model/decorators.ts +17 -475
  51. package/src/model/hydration.ts +796 -0
  52. package/src/model/index.ts +21 -0
  53. package/src/model/json-schema.ts +424 -0
  54. package/src/model/prolog-facts.ts +145 -0
  55. package/src/model/query-common.ts +48 -0
  56. package/src/model/query-prolog.ts +148 -0
  57. package/src/model/query-surreal.ts +280 -0
  58. package/src/model/relation-filtering.test.ts +0 -1
  59. package/src/model/sdna.ts +170 -0
  60. package/src/model/shacl-gen.ts +292 -0
  61. package/src/model/surreal-utils.ts +1 -1
  62. package/src/model/types.ts +182 -0
  63. package/src/model/util.ts +13 -36
  64. package/src/perspectives/PerspectiveClient.ts +1 -1
  65. package/src/perspectives/PerspectiveProxy.ts +1 -1
  66. package/src/perspectives/WakerSubscriptionManager.ts +292 -0
  67. package/src/runtime/RuntimeResolver.ts +53 -0
  68. package/lib/src/Ad4mClient.test.d.ts +0 -1
  69. package/lib/src/Ad4mClient.test.js +0 -1204
  70. package/lib/src/Literal.test.d.ts +0 -1
  71. package/lib/src/Literal.test.js +0 -41
  72. package/lib/src/model/mutation.d.ts +0 -81
  73. package/lib/src/model/mutation.js +0 -317
  74. package/lib/src/model/parentUtils.d.ts +0 -32
  75. package/lib/src/model/parentUtils.js +0 -64
  76. package/lib/src/model/prolog/generatePrologFacts.d.ts +0 -36
  77. package/lib/src/model/prolog/index.d.ts +0 -1
  78. package/lib/src/model/prolog/index.js +0 -1
  79. package/lib/src/model/query/ModelQueryBuilder.d.ts +0 -82
  80. package/lib/src/model/query/ModelQueryBuilder.js +0 -115
  81. package/lib/src/model/query/QueryBuilder.d.ts +0 -101
  82. package/lib/src/model/query/QueryBuilder.js +0 -193
  83. package/lib/src/model/query/SurrealQueryBuilder.d.ts +0 -48
  84. package/lib/src/model/query/SurrealQueryBuilder.js +0 -371
  85. package/lib/src/model/query/fetchInstance.d.ts +0 -24
  86. package/lib/src/model/query/fetchInstance.js +0 -144
  87. package/lib/src/model/query/hydration.d.ts +0 -54
  88. package/lib/src/model/query/hydration.js +0 -214
  89. package/lib/src/model/query/operations.d.ts +0 -59
  90. package/lib/src/model/query/operations.js +0 -384
  91. package/lib/src/model/query/snapshot.d.ts +0 -59
  92. package/lib/src/model/query/snapshot.js +0 -106
  93. package/lib/src/model/query/surrealCompiler.d.ts +0 -42
  94. package/lib/src/model/query/surrealCompiler.js +0 -304
  95. package/lib/src/model/schema/fromJSONSchema.js +0 -264
  96. package/lib/src/model/schema/metadata.d.ts +0 -15
  97. package/lib/src/model/schema/metadata.js +0 -112
  98. package/lib/src/model/subscription.d.ts +0 -47
  99. package/lib/src/model/subscription.js +0 -231
  100. package/lib/src/model/transaction.d.ts +0 -27
  101. package/lib/src/model/transaction.js +0 -32
  102. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  103. package/lib/src/shims/type-graphql.d.ts +0 -32
  104. package/lib/src/src/Ad4mClient.d.ts +0 -28
  105. package/lib/src/src/Address.d.ts +0 -1
  106. package/lib/src/src/DID.d.ts +0 -1
  107. package/lib/src/src/Exception.d.ts +0 -7
  108. package/lib/src/src/Literal.d.ts +0 -7
  109. package/lib/src/src/PubSub.d.ts +0 -17
  110. package/lib/src/src/SmartLiteral.d.ts +0 -12
  111. package/lib/src/src/agent/Agent.d.ts +0 -110
  112. package/lib/src/src/agent/AgentClient.d.ts +0 -62
  113. package/lib/src/src/agent/AgentResolver.d.ts +0 -30
  114. package/lib/src/src/agent/AgentStatus.d.ts +0 -8
  115. package/lib/src/src/ai/AIClient.d.ts +0 -32
  116. package/lib/src/src/ai/AIResolver.d.ts +0 -75
  117. package/lib/src/src/ai/Tasks.d.ts +0 -37
  118. package/lib/src/src/buildSchema.d.ts +0 -1
  119. package/lib/src/src/expression/Expression.d.ts +0 -28
  120. package/lib/src/src/expression/ExpressionClient.d.ts +0 -13
  121. package/lib/src/src/expression/ExpressionRef.d.ts +0 -9
  122. package/lib/src/src/expression/ExpressionResolver.d.ts +0 -10
  123. package/lib/src/src/index.d.ts +0 -35
  124. package/lib/src/src/jestSetup.d.ts +0 -1
  125. package/lib/src/src/language/Icon.d.ts +0 -4
  126. package/lib/src/src/language/Language.d.ts +0 -206
  127. package/lib/src/src/language/LanguageClient.d.ts +0 -17
  128. package/lib/src/src/language/LanguageContext.d.ts +0 -37
  129. package/lib/src/src/language/LanguageHandle.d.ts +0 -9
  130. package/lib/src/src/language/LanguageMeta.d.ts +0 -35
  131. package/lib/src/src/language/LanguageRef.d.ts +0 -6
  132. package/lib/src/src/language/LanguageResolver.d.ts +0 -19
  133. package/lib/src/src/links/Links.d.ts +0 -39
  134. package/lib/src/src/links/Links.test.d.ts +0 -1
  135. package/lib/src/src/model/Ad4mModel.d.ts +0 -1438
  136. package/lib/src/src/model/Ad4mModel.test.d.ts +0 -1
  137. package/lib/src/src/model/Subject.d.ts +0 -25
  138. package/lib/src/src/model/decorators.d.ts +0 -545
  139. package/lib/src/src/model/util.d.ts +0 -12
  140. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +0 -10
  141. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +0 -25
  142. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +0 -19
  143. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +0 -1
  144. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +0 -24
  145. package/lib/src/src/perspectives/LinkQuery.d.ts +0 -11
  146. package/lib/src/src/perspectives/Perspective.d.ts +0 -38
  147. package/lib/src/src/perspectives/Perspective.test.d.ts +0 -1
  148. package/lib/src/src/perspectives/PerspectiveClient.d.ts +0 -97
  149. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +0 -9
  150. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +0 -18
  151. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +0 -865
  152. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +0 -57
  153. package/lib/src/src/runtime/RuntimeClient.d.ts +0 -56
  154. package/lib/src/src/runtime/RuntimeResolver.d.ts +0 -132
  155. package/lib/src/src/shacl/SHACLFlow.d.ts +0 -171
  156. package/lib/src/src/shacl/SHACLFlow.test.d.ts +0 -1
  157. package/lib/src/src/shacl/SHACLShape.d.ts +0 -117
  158. package/lib/src/src/shacl/SHACLShape.test.d.ts +0 -1
  159. package/lib/src/src/typeDefs.d.ts +0 -1
  160. package/lib/src/src/unwrapApolloResult.d.ts +0 -2
  161. package/lib/src/src/utils.d.ts +0 -25
@@ -1,865 +0,0 @@
1
- import { LinkCallback, PerspectiveClient, SyncStateChangeCallback } from "./PerspectiveClient";
2
- import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
3
- import { LinkQuery } from "./LinkQuery";
4
- import { PerspectiveHandle, PerspectiveState } from './PerspectiveHandle';
5
- import { Perspective } from "./Perspective";
6
- import { ExpressionRendered } from "../expression/Expression";
7
- import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
- import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
- import { AIClient } from "../ai/AIClient";
10
- import { AllInstancesResult } from "../model/Ad4mModel";
11
- import { SHACLShape } from "../shacl/SHACLShape";
12
- import { SHACLFlow } from "../shacl/SHACLFlow";
13
- type QueryCallback = (result: AllInstancesResult) => void;
14
- /** Proxy object for a subscribed Prolog query that provides real-time updates
15
- *
16
- * This class handles:
17
- * - Keeping the subscription alive by sending periodic keepalive signals
18
- * - Managing callbacks for result updates
19
- * - Subscribing to query updates via GraphQL subscriptions
20
- * - Maintaining the latest query result
21
- * - Ensuring subscription is fully initialized before allowing access
22
- * - Cleaning up resources when disposed
23
- *
24
- * The subscription will remain active as long as keepalive signals are sent.
25
- * Make sure to call dispose() when you're done with the subscription to clean up
26
- * resources, stop keepalive signals, and notify the backend to remove the subscription.
27
- *
28
- * The subscription goes through an initialization process where it waits for the first
29
- * result to come through the subscription channel. You can await the `initialized`
30
- * promise to ensure the subscription is ready. The initialization will timeout after
31
- * 30 seconds if no result is received.
32
- *
33
- * Example usage:
34
- * ```typescript
35
- * const subscription = await perspective.subscribeInfer("my_query(X)");
36
- * // At this point the subscription is already initialized since subscribeInfer waits
37
- *
38
- * // Set up callback for future updates
39
- * const removeCallback = subscription.onResult(result => {
40
- * console.log("New result:", result);
41
- * });
42
- *
43
- * // Later: clean up subscription and notify backend
44
- * subscription.dispose();
45
- * ```
46
- */
47
- export declare class QuerySubscriptionProxy {
48
- #private;
49
- isSurrealDB: boolean;
50
- /** Creates a new query subscription
51
- * @param uuid - The UUID of the perspective
52
- * @param query - The Prolog query to subscribe to
53
- * @param client - The PerspectiveClient instance to use for communication
54
- */
55
- constructor(uuid: string, query: string, client: PerspectiveClient);
56
- subscribe(): Promise<void>;
57
- /** Get the subscription ID for this query subscription
58
- *
59
- * This is a unique identifier assigned when the subscription was created.
60
- * It can be used to reference this specific subscription, for example when
61
- * sending keepalive signals.
62
- *
63
- * @returns The subscription ID string
64
- */
65
- get id(): string;
66
- /** Promise that resolves when the subscription has received its first result
67
- * through the subscription channel. This ensures the subscription is fully
68
- * set up before allowing access to results or updates.
69
- *
70
- * If no result is received within 30 seconds, the subscription will automatically
71
- * retry. The promise will remain pending until a subscription message successfully
72
- * arrives, or until a fatal error occurs during subscription setup.
73
- *
74
- * Note: You typically don't need to await this directly since the subscription
75
- * creation methods (like subscribeInfer) already wait for initialization.
76
- */
77
- get initialized(): Promise<boolean>;
78
- /** Get the latest query result
79
- *
80
- * This returns the most recent result from the query, which could be either:
81
- * - The initial result from when the subscription was created
82
- * - The latest update received through the subscription
83
- *
84
- * @returns The latest query result as a string (usually a JSON array of bindings)
85
- */
86
- get result(): AllInstancesResult;
87
- /** Add a callback that will be called whenever new results arrive
88
- *
89
- * The callback will be called immediately with the current result,
90
- * and then again each time the query results change.
91
- *
92
- * @param callback - Function that takes a result string and processes it
93
- * @returns A function that can be called to remove this callback
94
- *
95
- * Example:
96
- * ```typescript
97
- * const removeCallback = subscription.onResult(result => {
98
- * const bindings = JSON.parse(result);
99
- * console.log("New bindings:", bindings);
100
- * });
101
- *
102
- * // Later: stop receiving updates
103
- * removeCallback();
104
- * ```
105
- */
106
- onResult(callback: QueryCallback): () => void;
107
- /** Clean up the subscription and stop keepalive signals
108
- *
109
- * This method:
110
- * 1. Stops the keepalive timer
111
- * 2. Unsubscribes from GraphQL subscription updates
112
- * 3. Clears all registered callbacks
113
- * 4. Cleans up any pending initialization timeout
114
- *
115
- * After calling this method, the subscription is no longer active and
116
- * will not receive any more updates. The instance should be discarded.
117
- */
118
- dispose(): void;
119
- }
120
- type PerspectiveListenerTypes = "link-added" | "link-removed" | "link-updated";
121
- export type LinkStatus = "shared" | "local";
122
- interface Parameter {
123
- name: string;
124
- value: string;
125
- }
126
- /**
127
- * PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs
128
- * that store and organize links between expressions.
129
- *
130
- * A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view
131
- * of their digital world. Through PerspectiveProxy, you can:
132
- * - Add, remove, and query links
133
- * - Work with Social DNA (subject classes and flows)
134
- * - Subscribe to real-time updates
135
- * - Share perspectives as Neighbourhoods
136
- * - Execute Prolog queries for complex graph patterns
137
- *
138
- *
139
- * @example
140
- * ```typescript
141
- * // Create and work with links
142
- * const perspective = await ad4m.perspective.add("My Space");
143
- * await perspective.add({
144
- * source: "did:key:alice",
145
- * predicate: "knows",
146
- * target: "did:key:bob"
147
- * });
148
- *
149
- * // Query links
150
- * const friends = await perspective.get({
151
- * source: "did:key:alice",
152
- * predicate: "knows"
153
- * });
154
- *
155
- * // Use Social DNA
156
- * await perspective.addSdna(todoClass, "subject_class");
157
- * const todo = await perspective.createSubject("Todo", "expression://123");
158
- *
159
- * // Subscribe to changes
160
- * perspective.addListener("link-added", (link) => {
161
- * console.log("New link added:", link);
162
- * });
163
- * ```
164
- */
165
- export declare class PerspectiveProxy {
166
- #private;
167
- /** Unique identifier of this perspective */
168
- uuid: string;
169
- /** Human-readable name of this perspective */
170
- name: string;
171
- /** If this perspective is shared as a Neighbourhood, this is its URL */
172
- sharedUrl: string | null;
173
- /** If this perspective is shared, this contains the Neighbourhood metadata */
174
- neighbourhood: NeighbourhoodExpression | null;
175
- /** Current sync state if this perspective is shared */
176
- state: PerspectiveState | null;
177
- /** List of owners of this perspective */
178
- owners?: string[];
179
- /**
180
- * Creates a new PerspectiveProxy instance.
181
- * Note: Don't create this directly, use ad4m.perspective.add() instead.
182
- */
183
- constructor(handle: PerspectiveHandle, ad4m: PerspectiveClient);
184
- /**
185
- * Escapes special regex characters in a string to prevent ReDoS attacks
186
- * and regex injection when building dynamic regular expressions.
187
- *
188
- * @param str - The string to escape
189
- * @returns The escaped string safe for use in RegExp constructor
190
- *
191
- * @private
192
- */
193
- private escapeRegExp;
194
- /**
195
- * Executes a set of actions on an expression with optional parameters.
196
- * Used internally by Social DNA flows and subject class operations.
197
- *
198
- * Actions are specified as an array of commands that modify links in the perspective.
199
- * Each action is an object with the following format:
200
- * ```typescript
201
- * {
202
- * action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
203
- * source: string, // Usually "this" to reference the current expression
204
- * predicate: string, // The predicate URI
205
- * target: string // The target value or "value" for parameters
206
- * }
207
- * ```
208
- *
209
- * Available commands:
210
- * - `addLink`: Creates a new link
211
- * - `removeLink`: Removes an existing link
212
- * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
213
- * - `collectionSetter`: Special command for setting collection properties
214
- *
215
- * When used with parameters, the special value "value" in the target field will be
216
- * replaced with the actual parameter value.
217
- *
218
- * @example
219
- * ```typescript
220
- * // Add a state link and remove an old one
221
- * await perspective.executeAction([
222
- * {
223
- * action: "addLink",
224
- * source: "this",
225
- * predicate: "todo://state",
226
- * target: "todo://doing"
227
- * },
228
- * {
229
- * action: "removeLink",
230
- * source: "this",
231
- * predicate: "todo://state",
232
- * target: "todo://ready"
233
- * }
234
- * ], "expression://123");
235
- *
236
- * // Set a property using a parameter
237
- * await perspective.executeAction([
238
- * {
239
- * action: "setSingleTarget",
240
- * source: "this",
241
- * predicate: "todo://title",
242
- * target: "value"
243
- * }
244
- * ], "expression://123", [
245
- * { name: "title", value: "New Title" }
246
- * ]);
247
- * ```
248
- *
249
- * @param actions - Array of action objects to execute
250
- * @param expression - Target expression address (replaces "this" in actions)
251
- * @param parameters - Optional parameters that replace "value" in actions
252
- * @param batchId - Optional batch ID to group this operation with others
253
- */
254
- executeAction(actions: any, expression: any, parameters: Parameter[], batchId?: string): Promise<boolean>;
255
- /**
256
- * Retrieves links from the perspective that match the given query.
257
- *
258
- * @param query - Query parameters to filter links
259
- * @returns Array of matching LinkExpressions
260
- *
261
- * @example
262
- * ```typescript
263
- * // Get all links where Alice knows someone
264
- * const links = await perspective.get({
265
- * source: "did:key:alice",
266
- * predicate: "knows"
267
- * });
268
- *
269
- * // Get all comments on a post
270
- * const comments = await perspective.get({
271
- * source: "post://123",
272
- * predicate: "comment"
273
- * });
274
- * ```
275
- */
276
- get(query: LinkQuery): Promise<LinkExpression[]>;
277
- /**
278
- * Executes a Prolog query against the perspective's knowledge base.
279
- * This is a powerful way to find complex patterns in the graph.
280
- *
281
- * @param query - Prolog query string
282
- * @returns Query results or false if no results
283
- *
284
- * @example
285
- * ```typescript
286
- * // Find friends of friends
287
- * const results = await perspective.infer(`
288
- * triple(A, "knows", B),
289
- * triple(B, "knows", C),
290
- * A \= C
291
- * `);
292
- *
293
- * // Find all active todos
294
- * const todos = await perspective.infer(`
295
- * instance(Todo, "Todo"),
296
- * property_getter("Todo", Todo, "state", "active")
297
- * `);
298
- * ```
299
- */
300
- infer(query: string): Promise<any>;
301
- /**
302
- * Executes a SurrealQL query against the perspective's link cache.
303
- * This allows powerful SQL-like queries on the link data stored in SurrealDB.
304
- *
305
- * **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
306
- * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
307
- * blocked for security reasons. Use the perspective's add/remove methods to modify links.
308
- *
309
- * @param query - SurrealQL query string (read-only operations only)
310
- * @returns Query results as parsed JSON
311
- *
312
- * @example
313
- * ```typescript
314
- * // Get all links
315
- * const links = await perspective.querySurrealDB('SELECT * FROM link');
316
- *
317
- * // Filter links by predicate
318
- * const follows = await perspective.querySurrealDB(
319
- * "SELECT * FROM link WHERE predicate = 'follows'"
320
- * );
321
- *
322
- * // Complex aggregation query
323
- * const stats = await perspective.querySurrealDB(
324
- * "SELECT predicate, count() as total FROM link GROUP BY predicate"
325
- * );
326
- * ```
327
- */
328
- querySurrealDB(query: string): Promise<any>;
329
- /**
330
- * Adds a new link to the perspective.
331
- *
332
- * @param link - The link to add
333
- * @param status - Whether the link should be shared in a Neighbourhood
334
- * @param batchId - Optional batch ID to group this operation with others
335
- * @returns The created LinkExpression
336
- *
337
- * @example
338
- * ```typescript
339
- * // Add a simple relationship
340
- * await perspective.add({
341
- * source: "did:key:alice",
342
- * predicate: "follows",
343
- * target: "did:key:bob"
344
- * });
345
- *
346
- * // Add a local-only link
347
- * await perspective.add({
348
- * source: "note://123",
349
- * predicate: "tag",
350
- * target: "private"
351
- * }, "local");
352
- * ```
353
- */
354
- add(link: Link, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
355
- /**
356
- * Adds multiple links to the perspective in a single operation.
357
- * More efficient than adding links one by one.
358
- *
359
- * @param links - Array of links to add
360
- * @param status - Whether the links should be shared
361
- * @param batchId - Optional batch ID to group this operation with others
362
- * @returns Array of created LinkExpressions
363
- */
364
- addLinks(links: Link[], status?: LinkStatus, batchId?: string): Promise<LinkExpression[]>;
365
- /**
366
- * Removes multiple links from the perspective.
367
- *
368
- * @param links - Array of links to remove
369
- * @param batchId - Optional batch ID to group this operation with others
370
- * @returns Array of removed LinkExpressions
371
- */
372
- removeLinks(links: LinkExpressionInput[], batchId?: string): Promise<LinkExpression[]>;
373
- /**
374
- * Applies a set of link mutations (adds and removes) in a single operation.
375
- * Useful for atomic updates to the perspective.
376
- *
377
- * @param mutations - Object containing links to add and remove
378
- * @param status - Whether new links should be shared
379
- * @returns Object containing results of the mutations
380
- */
381
- linkMutations(mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
382
- /**
383
- * Adds a pre-signed LinkExpression to the perspective.
384
- *
385
- * @param link - The signed LinkExpression to add
386
- * @param status - Whether the link should be shared
387
- * @param batchId - Optional batch ID to group this operation with others
388
- * @returns The added LinkExpression
389
- */
390
- addLinkExpression(link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
391
- /**
392
- * Updates an existing link with new data.
393
- *
394
- * @param oldLink - The existing link to update
395
- * @param newLink - The new link data
396
- * @param batchId - Optional batch ID to group this operation with others
397
- */
398
- update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
399
- /**
400
- * Removes a link from the perspective.
401
- *
402
- * @param link - The link to remove
403
- * @param batchId - Optional batch ID to group this operation with others
404
- */
405
- remove(link: LinkExpressionInput, batchId?: string): Promise<boolean>;
406
- /** Creates a new batch for grouping operations */
407
- createBatch(): Promise<string>;
408
- /** Commits a batch of operations */
409
- commitBatch(batchId: string): Promise<LinkExpressionMutations>;
410
- /**
411
- * Retrieves and renders an Expression referenced in this perspective.
412
- *
413
- * @param expressionURI - URI of the Expression to retrieve
414
- * @returns The rendered Expression
415
- */
416
- getExpression(expressionURI: string): Promise<ExpressionRendered>;
417
- /**
418
- * Creates a new Expression in the specified Language.
419
- *
420
- * @param content - Content for the new Expression
421
- * @param languageAddress - Address of the Language to use
422
- * @returns URI of the created Expression
423
- */
424
- createExpression(content: any, languageAddress: string): Promise<string>;
425
- /**
426
- * Subscribes to link changes in the perspective.
427
- *
428
- * @param type - Type of change to listen for
429
- * @param cb - Callback function
430
- *
431
- * @example
432
- * ```typescript
433
- * // Listen for new links
434
- * perspective.addListener("link-added", (link) => {
435
- * console.log("New link:", link);
436
- * });
437
- *
438
- * // Listen for removed links
439
- * perspective.addListener("link-removed", (link) => {
440
- * console.log("Link removed:", link);
441
- * });
442
- * ```
443
- */
444
- addListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
445
- /**
446
- * Subscribes to sync state changes if this perspective is shared.
447
- *
448
- * @param cb - Callback function
449
- *
450
- * @example
451
- * ```typescript
452
- * perspective.addSyncStateChangeListener((state) => {
453
- * console.log("Sync state:", state);
454
- * });
455
- * ```
456
- */
457
- addSyncStateChangeListener(cb: SyncStateChangeCallback): Promise<void>;
458
- /**
459
- * Unsubscribes from link changes.
460
- *
461
- * @param type - Type of change to stop listening for
462
- * @param cb - The callback function to remove
463
- */
464
- removeListener(type: PerspectiveListenerTypes, cb: LinkCallback): Promise<void>;
465
- /**
466
- * Creates a snapshot of the current perspective state.
467
- * Useful for backup or sharing.
468
- *
469
- * @returns Perspective object containing all links
470
- */
471
- snapshot(): Promise<Perspective>;
472
- /**
473
- * Loads a perspective snapshot, replacing current content.
474
- *
475
- * @param snapshot - Perspective snapshot to load
476
- */
477
- loadSnapshot(snapshot: Perspective): Promise<void>;
478
- /**
479
- * Gets a single target value matching a query.
480
- * Useful when you expect only one result.
481
- *
482
- * @param query - Query to find the target
483
- * @returns Target value or void if not found
484
- *
485
- * @example
486
- * ```typescript
487
- * // Get a user's name
488
- * const name = await perspective.getSingleTarget({
489
- * source: "did:key:alice",
490
- * predicate: "name"
491
- * });
492
- * ```
493
- */
494
- getSingleTarget(query: LinkQuery): Promise<string | void>;
495
- /**
496
- * Sets a single target value, removing any existing targets.
497
- *
498
- * @param link - Link defining the new target
499
- * @param status - Whether the link should be shared
500
- *
501
- * @example
502
- * ```typescript
503
- * // Set a user's status
504
- * await perspective.setSingleTarget({
505
- * source: "did:key:alice",
506
- * predicate: "status",
507
- * target: "online"
508
- * });
509
- * ```
510
- */
511
- setSingleTarget(link: Link, status?: LinkStatus): Promise<void>;
512
- /** Returns all the Social DNA flows defined in this perspective */
513
- sdnaFlows(): Promise<string[]>;
514
- /** Returns all Social DNA flows that can be started from the given expression */
515
- availableFlows(exprAddr: string): Promise<string[]>;
516
- /** Starts the Social DNA flow @param flowName on the expression @param exprAddr */
517
- startFlow(flowName: string, exprAddr: string): Promise<void>;
518
- /** Returns all expressions in the given state of given Social DNA flow */
519
- expressionsInFlowState(flowName: string, flowState: number): Promise<string[]>;
520
- /** Returns the given expression's flow state with regard to given Social DNA flow */
521
- flowState(flowName: string, exprAddr: string): Promise<number>;
522
- /** Returns available action names, with regard to Social DNA flow and expression's flow state */
523
- flowActions(flowName: string, exprAddr: string): Promise<string[]>;
524
- /** Runs given Social DNA flow action */
525
- runFlowAction(flowName: string, exprAddr: string, actionName: string): Promise<void>;
526
- /** Returns the perspective's Social DNA code
527
- * This will return all SDNA code elements in an array.
528
- */
529
- getSdna(): Promise<string[]>;
530
- /** Returns the Social DNA code for a specific class
531
- * This will return the SDNA code for the specified class, or null if not found.
532
- */
533
- getSdnaForClass(className: string): Promise<string | null>;
534
- /**
535
- * Adds Social DNA code to the perspective.
536
- *
537
- * **Recommended:** Use {@link addShacl} instead, which accepts the `SHACLShape` type directly.
538
- * This method is primarily for the GraphQL layer and legacy Prolog code.
539
- *
540
- * @param name - Unique name for this SDNA definition
541
- * @param sdnaCode - Prolog SDNA code (legacy, can be empty string if shaclJson provided)
542
- * @param sdnaType - Type of SDNA: "subject_class", "flow", or "custom"
543
- * @param shaclJson - SHACL JSON string (use addShacl() for type-safe alternative)
544
- *
545
- * @example
546
- * // Recommended: Use addShacl() with SHACLShape type
547
- * const shape = new SHACLShape('recipe://Recipe');
548
- * shape.addProperty({ name: 'title', path: 'recipe://title', datatype: 'xsd:string' });
549
- * await perspective.addShacl('Recipe', shape);
550
- *
551
- * // Legacy: Prolog code is auto-converted to SHACL
552
- * await perspective.addSdna('Recipe', prologCode, 'subject_class');
553
- */
554
- addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom", shaclJson?: string): Promise<boolean>;
555
- /**
556
- * **Recommended way to add SDNA schemas.**
557
- *
558
- * Store a SHACL shape in this Perspective using the type-safe `SHACLShape` class.
559
- * The shape is serialized as RDF triples (links) for native AD4M storage and querying.
560
- *
561
- * @param name - Unique name for this schema (e.g., 'Recipe', 'Task')
562
- * @param shape - SHACLShape instance defining the schema
563
- *
564
- * @example
565
- * import { SHACLShape } from '@coasys/ad4m';
566
- *
567
- * const shape = new SHACLShape('recipe://Recipe');
568
- * shape.addProperty({
569
- * name: 'title',
570
- * path: 'recipe://title',
571
- * datatype: 'xsd:string',
572
- * minCount: 1
573
- * });
574
- * shape.addProperty({
575
- * name: 'ingredients',
576
- * path: 'recipe://has_ingredient',
577
- * // No maxCount = collection
578
- * });
579
- *
580
- * await perspective.addShacl('Recipe', shape);
581
- */
582
- addShacl(name: string, shape: SHACLShape): Promise<void>;
583
- /**
584
- * Retrieve a SHACL shape by name from this Perspective
585
- */
586
- getShacl(name: string): Promise<SHACLShape | null>;
587
- /**
588
- * Get all SHACL shapes stored in this Perspective
589
- */
590
- getAllShacl(): Promise<Array<{
591
- name: string;
592
- shape: SHACLShape;
593
- }>>;
594
- /**
595
- * **Recommended way to add Flow definitions.**
596
- *
597
- * Store a SHACL Flow (state machine) in this Perspective using the type-safe `SHACLFlow` class.
598
- * The flow is serialized as RDF triples (links) for native AD4M storage and querying.
599
- *
600
- * @param name - Flow name (e.g., 'TODO', 'Approval')
601
- * @param flow - SHACLFlow instance defining the state machine
602
- *
603
- * @example
604
- * ```typescript
605
- * import { SHACLFlow } from '@coasys/ad4m';
606
- *
607
- * const todoFlow = new SHACLFlow('TODO', 'todo://');
608
- * todoFlow.flowable = 'any';
609
- *
610
- * // Define states
611
- * todoFlow.addState({ name: 'ready', value: 0, stateCheck: { predicate: 'todo://state', target: 'todo://ready' }});
612
- * todoFlow.addState({ name: 'done', value: 1, stateCheck: { predicate: 'todo://state', target: 'todo://done' }});
613
- *
614
- * // Define start action
615
- * todoFlow.startAction = [{ action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }];
616
- *
617
- * // Define transitions
618
- * todoFlow.addTransition({
619
- * actionName: 'Complete',
620
- * fromState: 'ready',
621
- * toState: 'done',
622
- * actions: [
623
- * { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://done' },
624
- * { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
625
- * ]
626
- * });
627
- *
628
- * await perspective.addFlow('TODO', todoFlow);
629
- * ```
630
- */
631
- addFlow(name: string, flow: SHACLFlow): Promise<void>;
632
- /**
633
- * Retrieve a Flow definition by name from this Perspective
634
- *
635
- * @param name - Flow name to retrieve
636
- * @returns The SHACLFlow or null if not found
637
- */
638
- getFlow(name: string): Promise<SHACLFlow | null>;
639
- /** Returns all the Subject classes defined in this perspectives SDNA
640
- *
641
- * Uses SHACL-based lookup (Prolog-free implementation).
642
- */
643
- subjectClasses(): Promise<string[]>;
644
- stringOrTemplateObjectToSubjectClassName<T>(subjectClass: T): Promise<string>;
645
- /**
646
- * Creates a new subject instance of the given subject class
647
- *
648
- * @param subjectClass Either a string with the name of the subject class, or an object
649
- * with the properties of the subject class.
650
- * @param exprAddr The address of the expression to be turned into a subject instance
651
- * @param initialValues Optional initial values for properties. If provided, these will be
652
- * merged with constructor actions for better performance.
653
- * @param batchId Optional batch ID for grouping operations. If provided, returns the expression address
654
- * instead of the subject proxy since the subject won't exist until the batch is committed.
655
- * @returns A proxy object for the created subject, or just the expression address if in batch mode
656
- */
657
- createSubject<T, B extends string | undefined = undefined>(subjectClass: T, exprAddr: string, initialValues?: Record<string, any>, batchId?: B): Promise<B extends undefined ? T : string>;
658
- getSubjectData<T>(subjectClass: T, exprAddr: string): Promise<T>;
659
- /**
660
- * Gets actions from SHACL links for a given predicate (e.g., ad4m://constructor, ad4m://destructor).
661
- * Returns the parsed action array if found, or null if not found.
662
- */
663
- private getActionsFromSHACL;
664
- /** Removes a subject instance by running its (SDNA defined) destructor,
665
- * which means removing links around the given expression address
666
- *
667
- * @param subjectClass Either a string with the name of the subject class, or an object
668
- * with the properties of the subject class. In the latter case, the first subject class
669
- * that matches the given properties will be used.
670
- * @param exprAddr The address of the expression to be turned into a subject instance
671
- * @param batchId Optional batch ID for grouping operations. If provided, the removal will be part of the batch
672
- * and won't be executed until the batch is committed.
673
- */
674
- removeSubject<T>(subjectClass: T, exprAddr: string, batchId?: string): Promise<void>;
675
- /** Checks if the given expression is a subject instance of the given subject class
676
- * @param expression The expression to be checked
677
- * @param subjectClass Either a string with the name of the subject class, or an object
678
- * with the properties of the subject class. In the latter case, the first subject class
679
- * that matches the given properties will be used.
680
- */
681
- isSubjectInstance<T>(expression: string, subjectClass: T): Promise<boolean>;
682
- /** For an existing subject instance (existing in the perspective's links)
683
- * this function returns a proxy object that can be used to access the subject's
684
- * properties and methods.
685
- *
686
- * @param base URI of the subject's root expression
687
- * @param subjectClass Either a string with the name of the subject class, or an object
688
- * with the properties of the subject class. In the latter case, the first subject class
689
- * that matches the given properties will be used.
690
- */
691
- getSubjectProxy<T>(base: string, subjectClass: T): Promise<T>;
692
- /**
693
- * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
694
- * Retrieves the SHACL shape and extracts metadata for instance queries.
695
- */
696
- getSubjectClassMetadataFromSDNA(className: string): Promise<{
697
- requiredPredicates: string[];
698
- requiredTriples: Array<{
699
- predicate: string;
700
- target?: string;
701
- }>;
702
- properties: Map<string, {
703
- predicate: string;
704
- resolveLanguage?: string;
705
- }>;
706
- collections: Map<string, {
707
- predicate: string;
708
- instanceFilter?: string;
709
- condition?: string;
710
- }>;
711
- } | null>;
712
- /**
713
- * Generates a SurrealDB query to find instances based on class metadata.
714
- */
715
- private generateSurrealInstanceQuery;
716
- /**
717
- * Gets a property value using SurrealDB when Prolog fails.
718
- * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
719
- */
720
- getPropertyValueViaSurreal(baseExpression: string, className: string, propertyName: string): Promise<any>;
721
- /**
722
- * Gets collection values using SurrealDB when Prolog fails.
723
- * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
724
- * Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
725
- */
726
- getCollectionValuesViaSurreal(baseExpression: string, className: string, collectionName: string): Promise<any[]>;
727
- /**
728
- * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
729
- * This avoids N+1 query problems by checking all values at once.
730
- */
731
- batchCheckSubjectInstances(expressions: string[], metadata: {
732
- requiredPredicates: string[];
733
- requiredTriples: Array<{
734
- predicate: string;
735
- target?: string;
736
- }>;
737
- properties: Map<string, {
738
- predicate: string;
739
- resolveLanguage?: string;
740
- }>;
741
- collections: Map<string, {
742
- predicate: string;
743
- instanceFilter?: string;
744
- condition?: string;
745
- }>;
746
- }): Promise<string[]>;
747
- /**
748
- * Fallback sequential instance checking when batch checking isn't available.
749
- */
750
- private filterInstancesSequential;
751
- /** Returns all subject instances of the given subject class as proxy objects.
752
- * @param subjectClass Either a string with the name of the subject class, or an object
753
- * with the properties of the subject class. In the latter case, all subject classes
754
- * that match the given properties will be used.
755
- */
756
- getAllSubjectInstances<T>(subjectClass: T): Promise<T[]>;
757
- /** Returns all subject proxies of the given subject class as proxy objects.
758
- * @param subjectClass Either a string with the name of the subject class, or an object
759
- * with the properties of the subject class. In the latter case, all subject classes
760
- * that match the given properties will be used.
761
- */
762
- getAllSubjectProxies<T>(subjectClass: T): Promise<T[]>;
763
- /**
764
- * Find a subject class by matching an object's properties/collections against SHACL shapes.
765
- * Queries SHACL links client-side to find a class whose properties contain all required ones.
766
- * @returns The matching class name, or null if no match found.
767
- */
768
- private findClassByProperties;
769
- /** Returns all subject classes that match the given template object.
770
- * This function looks at the properties of the template object and
771
- * its setters and collections to create a Prolog query that finds
772
- * all subject classes that would be converted to a proxy object
773
- * with exactly the same properties and collections.
774
- *
775
- * Since there could be multiple subject classes that match the given
776
- * criteria, this function returns a list of class names.
777
- *
778
- * @param obj The template object
779
- */
780
- subjectClassesByTemplate(obj: object): Promise<string[]>;
781
- /** Takes a JS class (its constructor) and assumes that it was decorated by
782
- * the @subjectClass etc. decorators. It then tests if there is a subject class
783
- * already present in the perspective's SDNA that matches the given class.
784
- * If there is no such class, it gets the JS class's SDNA by calling its
785
- * static generateSDNA() function and adds it to the perspective's SDNA.
786
- */
787
- ensureSDNASubjectClass(jsClass: any): Promise<void>;
788
- getNeighbourhoodProxy(): NeighbourhoodProxy;
789
- /**
790
- * Returns a proxy object for working with AI capabilities.
791
- *
792
- * @returns AIClient instance
793
- *
794
- * @example
795
- * ```typescript
796
- * // Use AI to analyze perspective content
797
- * const summary = await perspective.ai.summarize();
798
- *
799
- * // Generate new content
800
- * const suggestion = await perspective.ai.suggest("next action");
801
- * ```
802
- */
803
- get ai(): AIClient;
804
- /**
805
- * Creates a subscription for a Prolog query that updates in real-time.
806
- *
807
- * This method:
808
- * 1. Creates the subscription on the Rust side
809
- * 2. Sets up the subscription callback
810
- * 3. Waits for the initial result to come through the subscription channel
811
- * 4. Returns a fully initialized QuerySubscriptionProxy
812
- *
813
- * The returned subscription is guaranteed to be ready to receive updates,
814
- * as this method waits for the initialization process to complete.
815
- *
816
- * The subscription will be automatically cleaned up on both frontend and backend
817
- * when dispose() is called. Make sure to call dispose() when you're done to
818
- * prevent memory leaks and ensure proper cleanup of resources.
819
- *
820
- * @param query - Prolog query string
821
- * @returns Initialized QuerySubscriptionProxy instance
822
- *
823
- * @example
824
- * ```typescript
825
- * // Subscribe to active todos
826
- * const subscription = await perspective.subscribeInfer(`
827
- * instance(Todo, "Todo"),
828
- * property_getter("Todo", Todo, "state", "active")
829
- * `);
830
- *
831
- * // Subscription is already initialized here
832
- * console.log("Initial result:", subscription.result);
833
- *
834
- * // Set up callback for future updates
835
- * subscription.onResult((todos) => {
836
- * console.log("Active todos:", todos);
837
- * });
838
- *
839
- * // Clean up subscription when done
840
- * subscription.dispose();
841
- * ```
842
- */
843
- subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
844
- /**
845
- * Creates a subscription for a SurrealQL query that updates in real-time.
846
- *
847
- * This method:
848
- * 1. Creates the subscription on the Rust side
849
- * 2. Sets up the subscription callback
850
- * 3. Waits for the initial result to come through the subscription channel
851
- * 4. Returns a fully initialized QuerySubscriptionProxy
852
- *
853
- * The returned subscription is guaranteed to be ready to receive updates,
854
- * as this method waits for the initialization process to complete.
855
- *
856
- * The subscription will be automatically cleaned up on both frontend and backend
857
- * when dispose() is called. Make sure to call dispose() when you're done to
858
- * prevent memory leaks and ensure proper cleanup of resources.
859
- *
860
- * @param query - SurrealQL query string
861
- * @returns Initialized QuerySubscriptionProxy instance
862
- */
863
- subscribeSurrealDB(query: string): Promise<QuerySubscriptionProxy>;
864
- }
865
- export {};