@coasys/ad4m 0.12.0-rc1-dev.2 → 0.12.0-rc1-dev.4

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 (153) hide show
  1. package/jest.config.js +10 -3
  2. package/lib/index.cjs +6893 -5884
  3. package/lib/index.js +6889 -5872
  4. package/lib/src/Ad4mClient.d.ts +9 -16
  5. package/lib/src/Ad4mClient.js +46 -25
  6. package/lib/src/Literal.d.ts +1 -2
  7. package/lib/src/Literal.js +38 -35
  8. package/lib/src/SmartLiteral.d.ts +1 -2
  9. package/lib/src/SmartLiteral.js +30 -15
  10. package/lib/src/agent/AgentClient.d.ts +1 -4
  11. package/lib/src/agent/AgentClient.js +79 -99
  12. package/lib/src/ai/AIClient.d.ts +1 -2
  13. package/lib/src/ai/AIClient.js +224 -220
  14. package/lib/src/expression/ExpressionClient.d.ts +1 -1
  15. package/lib/src/expression/ExpressionClient.js +73 -86
  16. package/lib/src/index.d.ts +1 -1
  17. package/lib/src/index.js +1 -1
  18. package/lib/src/language/LanguageClient.d.ts +1 -1
  19. package/lib/src/language/LanguageClient.js +52 -52
  20. package/lib/src/model/Ad4mModel.d.ts +1351 -144
  21. package/lib/src/model/Ad4mModel.js +3760 -228
  22. package/lib/src/model/Ad4mModel.test.js +522 -979
  23. package/lib/src/model/Subject.d.ts +3 -3
  24. package/lib/src/model/Subject.js +25 -25
  25. package/lib/src/model/decorators.d.ts +444 -100
  26. package/lib/src/model/decorators.js +686 -321
  27. package/lib/src/model/util.d.ts +6 -6
  28. package/lib/src/model/util.js +24 -24
  29. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +1 -5
  30. package/lib/src/neighbourhood/NeighbourhoodClient.js +179 -242
  31. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +1 -2
  32. package/lib/src/neighbourhood/NeighbourhoodProxy.js +28 -13
  33. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +5 -1
  34. package/lib/src/perspectives/PerspectiveClient.d.ts +9 -9
  35. package/lib/src/perspectives/PerspectiveClient.js +240 -316
  36. package/lib/src/perspectives/PerspectiveProxy.d.ts +99 -61
  37. package/lib/src/perspectives/PerspectiveProxy.js +485 -832
  38. package/lib/src/runtime/RuntimeClient.d.ts +1 -5
  39. package/lib/src/runtime/RuntimeClient.js +238 -412
  40. package/lib/src/shacl/SHACLFlow.test.js +105 -164
  41. package/lib/src/shacl/SHACLShape.d.ts +12 -17
  42. package/lib/src/shacl/SHACLShape.js +115 -128
  43. package/lib/src/shacl/SHACLShape.test.js +176 -244
  44. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  45. package/lib/src/shims/type-graphql.d.ts +32 -0
  46. package/lib/src/src/Ad4mClient.d.ts +28 -0
  47. package/lib/src/src/Address.d.ts +1 -0
  48. package/lib/src/src/DID.d.ts +1 -0
  49. package/lib/src/src/Exception.d.ts +7 -0
  50. package/lib/src/src/Literal.d.ts +7 -0
  51. package/lib/src/src/PubSub.d.ts +17 -0
  52. package/lib/src/src/SmartLiteral.d.ts +12 -0
  53. package/lib/src/src/agent/Agent.d.ts +110 -0
  54. package/lib/src/src/agent/AgentClient.d.ts +62 -0
  55. package/lib/src/src/agent/AgentResolver.d.ts +30 -0
  56. package/lib/src/src/agent/AgentStatus.d.ts +8 -0
  57. package/lib/src/src/ai/AIClient.d.ts +32 -0
  58. package/lib/src/src/ai/AIResolver.d.ts +75 -0
  59. package/lib/src/src/ai/Tasks.d.ts +37 -0
  60. package/lib/src/src/buildSchema.d.ts +1 -0
  61. package/lib/src/src/expression/Expression.d.ts +28 -0
  62. package/lib/src/src/expression/ExpressionClient.d.ts +13 -0
  63. package/lib/src/src/expression/ExpressionRef.d.ts +9 -0
  64. package/lib/src/src/expression/ExpressionResolver.d.ts +10 -0
  65. package/lib/src/src/index.d.ts +35 -0
  66. package/lib/src/src/jestSetup.d.ts +1 -0
  67. package/lib/src/src/language/Icon.d.ts +4 -0
  68. package/lib/src/src/language/Language.d.ts +206 -0
  69. package/lib/src/src/language/LanguageClient.d.ts +17 -0
  70. package/lib/src/src/language/LanguageContext.d.ts +37 -0
  71. package/lib/src/src/language/LanguageHandle.d.ts +9 -0
  72. package/lib/src/src/language/LanguageMeta.d.ts +35 -0
  73. package/lib/src/src/language/LanguageRef.d.ts +6 -0
  74. package/lib/src/src/language/LanguageResolver.d.ts +19 -0
  75. package/lib/src/src/links/Links.d.ts +39 -0
  76. package/lib/src/src/links/Links.test.d.ts +1 -0
  77. package/lib/src/src/model/Ad4mModel.d.ts +1438 -0
  78. package/lib/src/src/model/Ad4mModel.test.d.ts +1 -0
  79. package/lib/src/src/model/Subject.d.ts +25 -0
  80. package/lib/src/src/model/decorators.d.ts +545 -0
  81. package/lib/src/src/model/util.d.ts +12 -0
  82. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +10 -0
  83. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +25 -0
  84. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +19 -0
  85. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +1 -0
  86. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +24 -0
  87. package/lib/src/src/perspectives/LinkQuery.d.ts +11 -0
  88. package/lib/src/src/perspectives/Perspective.d.ts +38 -0
  89. package/lib/src/src/perspectives/Perspective.test.d.ts +1 -0
  90. package/lib/src/src/perspectives/PerspectiveClient.d.ts +97 -0
  91. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +9 -0
  92. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +18 -0
  93. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +865 -0
  94. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +57 -0
  95. package/lib/src/src/runtime/RuntimeClient.d.ts +56 -0
  96. package/lib/src/src/runtime/RuntimeResolver.d.ts +132 -0
  97. package/lib/src/src/shacl/SHACLFlow.d.ts +171 -0
  98. package/lib/src/src/shacl/SHACLFlow.test.d.ts +1 -0
  99. package/lib/src/src/shacl/SHACLShape.d.ts +117 -0
  100. package/lib/src/src/shacl/SHACLShape.test.d.ts +1 -0
  101. package/lib/src/src/typeDefs.d.ts +1 -0
  102. package/lib/src/src/unwrapApolloResult.d.ts +2 -0
  103. package/lib/src/src/utils.d.ts +25 -0
  104. package/lib/src/utils.d.ts +0 -8
  105. package/lib/src/utils.js +7 -21
  106. package/package.json +15 -14
  107. package/src/Ad4mClient.test.ts +1315 -1564
  108. package/src/Ad4mClient.ts +54 -55
  109. package/src/Literal.test.ts +26 -45
  110. package/src/Literal.ts +66 -82
  111. package/src/SmartLiteral.ts +58 -74
  112. package/src/agent/AgentClient.ts +99 -144
  113. package/src/ai/AIClient.ts +359 -409
  114. package/src/expression/ExpressionClient.ts +96 -142
  115. package/src/index.ts +1 -1
  116. package/src/language/LanguageClient.ts +113 -137
  117. package/src/model/Ad4mModel.test.ts +616 -1114
  118. package/src/model/Ad4mModel.ts +4386 -451
  119. package/src/model/Subject.ts +159 -0
  120. package/src/model/decorators.ts +1168 -667
  121. package/src/model/util.ts +54 -53
  122. package/src/neighbourhood/NeighbourhoodClient.ts +266 -392
  123. package/src/neighbourhood/NeighbourhoodProxy.test.ts +7 -3
  124. package/src/neighbourhood/NeighbourhoodProxy.ts +40 -58
  125. package/src/perspectives/PerspectiveClient.ts +540 -779
  126. package/src/perspectives/PerspectiveProxy.ts +2067 -2860
  127. package/src/runtime/RuntimeClient.ts +476 -775
  128. package/src/shacl/SHACLFlow.test.ts +129 -196
  129. package/src/shacl/SHACLShape.test.ts +190 -284
  130. package/src/shacl/SHACLShape.ts +200 -224
  131. package/src/utils.ts +17 -31
  132. package/tsconfig.json +10 -9
  133. package/src/model/IMPROVEMENTS.md +0 -482
  134. package/src/model/PREDICATE_COLLISION_FIX.md +0 -651
  135. package/src/model/README.md +0 -317
  136. package/src/model/SHACL_MUTATION_DECOUPLING.md +0 -356
  137. package/src/model/SUBSCRIPTION_STRATEGY.md +0 -317
  138. package/src/model/TC39_STAGE_3_DECORATORS.md +0 -609
  139. package/src/model/mutation.ts +0 -461
  140. package/src/model/parentUtils.ts +0 -91
  141. package/src/model/prolog/generatePrologFacts.ts +0 -176
  142. package/src/model/prolog/index.ts +0 -1
  143. package/src/model/query/ModelQueryBuilder.ts +0 -173
  144. package/src/model/query/fetchInstance.ts +0 -181
  145. package/src/model/query/hydration.ts +0 -273
  146. package/src/model/query/operations.ts +0 -510
  147. package/src/model/query/snapshot.ts +0 -126
  148. package/src/model/query/surrealCompiler.ts +0 -376
  149. package/src/model/schema/fromJSONSchema.ts +0 -411
  150. package/src/model/schema/metadata.ts +0 -148
  151. package/src/model/subscription.ts +0 -307
  152. package/src/model/transaction.ts +0 -60
  153. package/src/model/types.ts +0 -207
@@ -1,13 +1,15 @@
1
1
  import { LinkCallback, PerspectiveClient, SyncStateChangeCallback } from "./PerspectiveClient";
2
2
  import { Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkMutations } from "../links/Links";
3
3
  import { LinkQuery } from "./LinkQuery";
4
- import { PerspectiveHandle, PerspectiveState } from "./PerspectiveHandle";
4
+ import { PerspectiveHandle, PerspectiveState } from './PerspectiveHandle';
5
5
  import { Perspective } from "./Perspective";
6
6
  import { ExpressionRendered } from "../expression/Expression";
7
7
  import { NeighbourhoodProxy } from "../neighbourhood/NeighbourhoodProxy";
8
8
  import { NeighbourhoodExpression } from "../neighbourhood/Neighbourhood";
9
9
  import { AIClient } from "../ai/AIClient";
10
10
  import { AllInstancesResult } from "../model/Ad4mModel";
11
+ import { SHACLShape } from "../shacl/SHACLShape";
12
+ import { SHACLFlow } from "../shacl/SHACLFlow";
11
13
  type QueryCallback = (result: AllInstancesResult) => void;
12
14
  /** Proxy object for a subscribed Prolog query that provides real-time updates
13
15
  *
@@ -43,19 +45,8 @@ type QueryCallback = (result: AllInstancesResult) => void;
43
45
  * ```
44
46
  */
45
47
  export declare class QuerySubscriptionProxy {
46
- private _uuid;
47
- private _subscriptionId;
48
- private _client;
49
- private _callbacks;
50
- private _keepaliveTimer;
51
- private _unsubscribe?;
52
- private _latestResult;
53
- private _disposed;
54
- private _initialized;
55
- private _initResolve?;
56
- private _initReject?;
57
- private _initTimeoutId?;
58
- private _query;
48
+ #private;
49
+ isSurrealDB: boolean;
59
50
  /** Creates a new query subscription
60
51
  * @param uuid - The UUID of the perspective
61
52
  * @param query - The Prolog query to subscribe to
@@ -113,8 +104,6 @@ export declare class QuerySubscriptionProxy {
113
104
  * ```
114
105
  */
115
106
  onResult(callback: QueryCallback): () => void;
116
- /** Internal method to notify all callbacks of a new result */
117
- private _notifyCallbacks;
118
107
  /** Clean up the subscription and stop keepalive signals
119
108
  *
120
109
  * This method:
@@ -134,7 +123,47 @@ interface Parameter {
134
123
  name: string;
135
124
  value: string;
136
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
+ */
137
165
  export declare class PerspectiveProxy {
166
+ #private;
138
167
  /** Unique identifier of this perspective */
139
168
  uuid: string;
140
169
  /** Human-readable name of this perspective */
@@ -147,12 +176,6 @@ export declare class PerspectiveProxy {
147
176
  state: PerspectiveState | null;
148
177
  /** List of owners of this perspective */
149
178
  owners?: string[];
150
- private _handle;
151
- private _client;
152
- private _perspectiveLinkAddedCallbacks;
153
- private _perspectiveLinkRemovedCallbacks;
154
- private _perspectiveLinkUpdatedCallbacks;
155
- private _perspectiveSyncStateChangeCallbacks;
156
179
  /**
157
180
  * Creates a new PerspectiveProxy instance.
158
181
  * Note: Don't create this directly, use ad4m.perspective.add() instead.
@@ -176,7 +199,7 @@ export declare class PerspectiveProxy {
176
199
  * Each action is an object with the following format:
177
200
  * ```typescript
178
201
  * {
179
- * action: "addLink" | "removeLink" | "setSingleTarget" | "relationSetter",
202
+ * action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
180
203
  * source: string, // Usually "this" to reference the current expression
181
204
  * predicate: string, // The predicate URI
182
205
  * target: string // The target value or "value" for parameters
@@ -187,7 +210,7 @@ export declare class PerspectiveProxy {
187
210
  * - `addLink`: Creates a new link
188
211
  * - `removeLink`: Removes an existing link
189
212
  * - `setSingleTarget`: Removes all existing links with the same source/predicate and adds a new one
190
- * - `relationSetter`: Special command for bulk-setting a relation (clears existing links, then adds new ones)
213
+ * - `collectionSetter`: Special command for setting relation properties
191
214
  *
192
215
  * When used with parameters, the special value "value" in the target field will be
193
216
  * replaced with the actual parameter value.
@@ -357,21 +380,21 @@ export declare class PerspectiveProxy {
357
380
  */
358
381
  linkMutations(mutations: LinkMutations, status?: LinkStatus): Promise<LinkExpressionMutations>;
359
382
  /**
360
- * Adds a pre-signed LinkExpression to the perspective.
361
- *
362
- * @param link - The signed LinkExpression to add
363
- * @param status - Whether the link should be shared
364
- * @param batchId - Optional batch ID to group this operation with others
365
- * @returns The added LinkExpression
366
- */
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
+ */
367
390
  addLinkExpression(link: LinkExpression, status?: LinkStatus, batchId?: string): Promise<LinkExpression>;
368
391
  /**
369
- * Updates an existing link with new data.
370
- *
371
- * @param oldLink - The existing link to update
372
- * @param newLink - The new link data
373
- * @param batchId - Optional batch ID to group this operation with others
374
- */
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
+ */
375
398
  update(oldLink: LinkExpressionInput, newLink: Link, batchId?: string): Promise<LinkExpression>;
376
399
  /**
377
400
  * Removes a link from the perspective.
@@ -551,22 +574,22 @@ export declare class PerspectiveProxy {
551
574
  * shape.addProperty({
552
575
  * name: 'ingredients',
553
576
  * path: 'recipe://has_ingredient',
554
- * // No maxCount = collection
577
+ * // No maxCount = relation
555
578
  * });
556
579
  *
557
580
  * await perspective.addShacl('Recipe', shape);
558
581
  */
559
- addShacl(name: string, shape: import("../shacl/SHACLShape").SHACLShape): Promise<void>;
582
+ addShacl(name: string, shape: SHACLShape): Promise<void>;
560
583
  /**
561
584
  * Retrieve a SHACL shape by name from this Perspective
562
585
  */
563
- getShacl(name: string): Promise<import("../shacl/SHACLShape").SHACLShape | null>;
586
+ getShacl(name: string): Promise<SHACLShape | null>;
564
587
  /**
565
588
  * Get all SHACL shapes stored in this Perspective
566
589
  */
567
590
  getAllShacl(): Promise<Array<{
568
591
  name: string;
569
- shape: import("../shacl/SHACLShape").SHACLShape;
592
+ shape: SHACLShape;
570
593
  }>>;
571
594
  /**
572
595
  * **Recommended way to add Flow definitions.**
@@ -605,14 +628,14 @@ export declare class PerspectiveProxy {
605
628
  * await perspective.addFlow('TODO', todoFlow);
606
629
  * ```
607
630
  */
608
- addFlow(name: string, flow: import("../shacl/SHACLFlow").SHACLFlow): Promise<void>;
631
+ addFlow(name: string, flow: SHACLFlow): Promise<void>;
609
632
  /**
610
633
  * Retrieve a Flow definition by name from this Perspective
611
634
  *
612
635
  * @param name - Flow name to retrieve
613
636
  * @returns The SHACLFlow or null if not found
614
637
  */
615
- getFlow(name: string): Promise<import("../shacl/SHACLFlow").SHACLFlow | null>;
638
+ getFlow(name: string): Promise<SHACLFlow | null>;
616
639
  /** Returns all the Subject classes defined in this perspectives SDNA
617
640
  *
618
641
  * Uses SHACL-based lookup (Prolog-free implementation).
@@ -654,7 +677,7 @@ export declare class PerspectiveProxy {
654
677
  * @param subjectClass Either a string with the name of the subject class, or an object
655
678
  * with the properties of the subject class. In the latter case, the first subject class
656
679
  * that matches the given properties will be used.
657
- */
680
+ */
658
681
  isSubjectInstance<T>(expression: string, subjectClass: T): Promise<boolean>;
659
682
  /** For an existing subject instance (existing in the perspective's links)
660
683
  * this function returns a proxy object that can be used to access the subject's
@@ -667,14 +690,8 @@ export declare class PerspectiveProxy {
667
690
  */
668
691
  getSubjectProxy<T>(base: string, subjectClass: T): Promise<T>;
669
692
  /**
670
- * Extracts subject class metadata from SDNA by parsing the Prolog text.
671
- * Parses the instance rule to extract required predicates.
672
- * Returns required predicates that define what makes something an instance,
673
- * plus a map of property/collection names to their predicates.
674
- */
675
- /**
676
- * Gets subject class metadata from SHACL links (Prolog-free implementation).
677
- * Uses the link API directly instead of SurrealDB queries.
693
+ * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
694
+ * Retrieves the SHACL shape and extracts metadata for instance queries.
678
695
  */
679
696
  getSubjectClassMetadataFromSDNA(className: string): Promise<{
680
697
  requiredPredicates: string[];
@@ -686,7 +703,7 @@ export declare class PerspectiveProxy {
686
703
  predicate: string;
687
704
  resolveLanguage?: string;
688
705
  }>;
689
- collections: Map<string, {
706
+ relations: Map<string, {
690
707
  predicate: string;
691
708
  instanceFilter?: string;
692
709
  condition?: string;
@@ -702,11 +719,11 @@ export declare class PerspectiveProxy {
702
719
  */
703
720
  getPropertyValueViaSurreal(baseExpression: string, className: string, propertyName: string): Promise<any>;
704
721
  /**
705
- * Gets collection values using SurrealDB when Prolog fails.
722
+ * Gets relation values using SurrealDB when Prolog fails.
706
723
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
707
724
  * Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
708
725
  */
709
- getCollectionValuesViaSurreal(baseExpression: string, className: string, collectionName: string): Promise<any[]>;
726
+ getRelationValuesViaSurreal(baseExpression: string, className: string, relationName: string): Promise<any[]>;
710
727
  /**
711
728
  * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
712
729
  * This avoids N+1 query problems by checking all values at once.
@@ -721,7 +738,7 @@ export declare class PerspectiveProxy {
721
738
  predicate: string;
722
739
  resolveLanguage?: string;
723
740
  }>;
724
- collections: Map<string, {
741
+ relations: Map<string, {
725
742
  predicate: string;
726
743
  instanceFilter?: string;
727
744
  condition?: string;
@@ -743,16 +760,17 @@ export declare class PerspectiveProxy {
743
760
  * that match the given properties will be used.
744
761
  */
745
762
  getAllSubjectProxies<T>(subjectClass: T): Promise<T[]>;
746
- private buildQueryFromTemplate;
747
- /** Finds a single subject class whose SHACL shape matches all properties
748
- * and collections present on `obj`. Returns `null` when no match is found.
763
+ /**
764
+ * Find a subject class by matching an object's properties/relations 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.
749
767
  */
750
768
  private findClassByProperties;
751
769
  /** Returns all subject classes that match the given template object.
752
770
  * This function looks at the properties of the template object and
753
- * its setters and collections to create a Prolog query that finds
771
+ * its setters and relations to create a Prolog query that finds
754
772
  * all subject classes that would be converted to a proxy object
755
- * with exactly the same properties and collections.
773
+ * with exactly the same properties and relations.
756
774
  *
757
775
  * Since there could be multiple subject classes that match the given
758
776
  * criteria, this function returns a list of class names.
@@ -823,5 +841,25 @@ export declare class PerspectiveProxy {
823
841
  * ```
824
842
  */
825
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>;
826
864
  }
827
865
  export {};