@coasys/ad4m 0.10.1 → 0.11.0

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.
@@ -27,11 +27,28 @@ export declare class PerspectiveClient {
27
27
  publishSnapshotByUUID(uuid: string): Promise<string | null>;
28
28
  queryLinks(uuid: string, query: LinkQuery): Promise<LinkExpression[]>;
29
29
  queryProlog(uuid: string, query: string): Promise<any>;
30
+ /**
31
+ * Executes a read-only SurrealQL query against a perspective's link cache.
32
+ *
33
+ * Security: Only SELECT, RETURN, and other read-only queries are permitted.
34
+ * Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
35
+ *
36
+ * Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
37
+ * as generated from Rust method "perspective_query_surreal_db"
38
+ */
39
+ querySurrealDB(uuid: string, query: string): Promise<any>;
30
40
  subscribeQuery(uuid: string, query: string): Promise<{
31
41
  subscriptionId: string;
32
42
  result: AllInstancesResult;
33
43
  isInit?: boolean;
34
44
  }>;
45
+ perspectiveSubscribeSurrealQuery(uuid: string, query: string): Promise<{
46
+ subscriptionId: string;
47
+ result: AllInstancesResult;
48
+ isInit?: boolean;
49
+ }>;
50
+ perspectiveKeepAliveSurrealQuery(uuid: string, subscriptionId: string): Promise<boolean>;
51
+ perspectiveDisposeSurrealQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
35
52
  subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void;
36
53
  keepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean>;
37
54
  disposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
@@ -138,6 +138,24 @@ export class PerspectiveClient {
138
138
  }));
139
139
  return JSON.parse(perspectiveQueryProlog);
140
140
  }
141
+ /**
142
+ * Executes a read-only SurrealQL query against a perspective's link cache.
143
+ *
144
+ * Security: Only SELECT, RETURN, and other read-only queries are permitted.
145
+ * Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
146
+ *
147
+ * Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
148
+ * as generated from Rust method "perspective_query_surreal_db"
149
+ */
150
+ async querySurrealDB(uuid, query) {
151
+ const { perspectiveQuerySurrealDb } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").query({
152
+ query: gql `query perspectiveQuerySurrealDb($uuid: String!, $query: String!) {
153
+ perspectiveQuerySurrealDb(uuid: $uuid, query: $query)
154
+ }`,
155
+ variables: { uuid, query }
156
+ }));
157
+ return JSON.parse(perspectiveQuerySurrealDb);
158
+ }
141
159
  async subscribeQuery(uuid, query) {
142
160
  const { perspectiveSubscribeQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
143
161
  mutation: gql `mutation perspectiveSubscribeQuery($uuid: String!, $query: String!) {
@@ -163,6 +181,49 @@ export class PerspectiveClient {
163
181
  }
164
182
  return { subscriptionId, result: finalResult, isInit };
165
183
  }
184
+ async perspectiveSubscribeSurrealQuery(uuid, query) {
185
+ const { perspectiveSubscribeSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
186
+ mutation: gql `mutation perspectiveSubscribeSurrealQuery($uuid: String!, $query: String!) {
187
+ perspectiveSubscribeSurrealQuery(uuid: $uuid, query: $query) {
188
+ subscriptionId
189
+ result
190
+ }
191
+ }`,
192
+ variables: { uuid, query }
193
+ }));
194
+ const { subscriptionId, result } = perspectiveSubscribeSurrealQuery;
195
+ let finalResult = result;
196
+ let isInit = false;
197
+ if (finalResult.startsWith("#init#")) {
198
+ finalResult = finalResult.substring(6);
199
+ isInit = true;
200
+ }
201
+ try {
202
+ finalResult = JSON.parse(finalResult);
203
+ }
204
+ catch (e) {
205
+ console.error('Error parsing perspectiveSubscribeSurrealQuery result:', e);
206
+ }
207
+ return { subscriptionId, result: finalResult, isInit };
208
+ }
209
+ async perspectiveKeepAliveSurrealQuery(uuid, subscriptionId) {
210
+ const { perspectiveKeepAliveSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
211
+ mutation: gql `mutation perspectiveKeepAliveSurrealQuery($uuid: String!, $subscriptionId: String!) {
212
+ perspectiveKeepAliveSurrealQuery(uuid: $uuid, subscriptionId: $subscriptionId)
213
+ }`,
214
+ variables: { uuid, subscriptionId }
215
+ }));
216
+ return perspectiveKeepAliveSurrealQuery;
217
+ }
218
+ async perspectiveDisposeSurrealQuerySubscription(uuid, subscriptionId) {
219
+ const { perspectiveDisposeSurrealQuerySubscription } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
220
+ mutation: gql `mutation perspectiveDisposeSurrealQuerySubscription($uuid: String!, $subscriptionId: String!) {
221
+ perspectiveDisposeSurrealQuerySubscription(uuid: $uuid, subscriptionId: $subscriptionId)
222
+ }`,
223
+ variables: { uuid, subscriptionId }
224
+ }));
225
+ return perspectiveDisposeSurrealQuerySubscription;
226
+ }
166
227
  subscribeToQueryUpdates(subscriptionId, onData) {
167
228
  const subscription = __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").subscribe({
168
229
  query: gql `
@@ -44,6 +44,7 @@ type QueryCallback = (result: AllInstancesResult) => void;
44
44
  */
45
45
  export declare class QuerySubscriptionProxy {
46
46
  #private;
47
+ isSurrealDB: boolean;
47
48
  /** Creates a new query subscription
48
49
  * @param uuid - The UUID of the perspective
49
50
  * @param query - The Prolog query to subscribe to
@@ -64,7 +65,9 @@ export declare class QuerySubscriptionProxy {
64
65
  * through the subscription channel. This ensures the subscription is fully
65
66
  * set up before allowing access to results or updates.
66
67
  *
67
- * The promise will reject if no result is received within 30 seconds.
68
+ * If no result is received within 30 seconds, the subscription will automatically
69
+ * retry. The promise will remain pending until a subscription message successfully
70
+ * arrives, or until a fatal error occurs during subscription setup.
68
71
  *
69
72
  * Note: You typically don't need to await this directly since the subscription
70
73
  * creation methods (like subscribeInfer) already wait for initialization.
@@ -281,6 +284,34 @@ export declare class PerspectiveProxy {
281
284
  * ```
282
285
  */
283
286
  infer(query: string): Promise<any>;
287
+ /**
288
+ * Executes a SurrealQL query against the perspective's link cache.
289
+ * This allows powerful SQL-like queries on the link data stored in SurrealDB.
290
+ *
291
+ * **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
292
+ * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
293
+ * blocked for security reasons. Use the perspective's add/remove methods to modify links.
294
+ *
295
+ * @param query - SurrealQL query string (read-only operations only)
296
+ * @returns Query results as parsed JSON
297
+ *
298
+ * @example
299
+ * ```typescript
300
+ * // Get all links
301
+ * const links = await perspective.querySurrealDB('SELECT * FROM link');
302
+ *
303
+ * // Filter links by predicate
304
+ * const follows = await perspective.querySurrealDB(
305
+ * "SELECT * FROM link WHERE predicate = 'follows'"
306
+ * );
307
+ *
308
+ * // Complex aggregation query
309
+ * const stats = await perspective.querySurrealDB(
310
+ * "SELECT predicate, count() as total FROM link GROUP BY predicate"
311
+ * );
312
+ * ```
313
+ */
314
+ querySurrealDB(query: string): Promise<any>;
284
315
  /**
285
316
  * Adds a new link to the perspective.
286
317
  *
@@ -621,5 +652,25 @@ export declare class PerspectiveProxy {
621
652
  * ```
622
653
  */
623
654
  subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
655
+ /**
656
+ * Creates a subscription for a SurrealQL query that updates in real-time.
657
+ *
658
+ * This method:
659
+ * 1. Creates the subscription on the Rust side
660
+ * 2. Sets up the subscription callback
661
+ * 3. Waits for the initial result to come through the subscription channel
662
+ * 4. Returns a fully initialized QuerySubscriptionProxy
663
+ *
664
+ * The returned subscription is guaranteed to be ready to receive updates,
665
+ * as this method waits for the initialization process to complete.
666
+ *
667
+ * The subscription will be automatically cleaned up on both frontend and backend
668
+ * when dispose() is called. Make sure to call dispose() when you're done to
669
+ * prevent memory leaks and ensure proper cleanup of resources.
670
+ *
671
+ * @param query - SurrealQL query string
672
+ * @returns Initialized QuerySubscriptionProxy instance
673
+ */
674
+ subscribeSurrealDB(query: string): Promise<QuerySubscriptionProxy>;
624
675
  }
625
676
  export {};
@@ -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 _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks;
12
+ var _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initResolve, _QuerySubscriptionProxy_initReject, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks;
13
13
  import { LinkQuery } from "./LinkQuery";
14
14
  import { Literal } from "../Literal";
15
15
  import { Subject } from "../model/Subject";
@@ -64,56 +64,119 @@ export class QuerySubscriptionProxy {
64
64
  _QuerySubscriptionProxy_latestResult.set(this, void 0);
65
65
  _QuerySubscriptionProxy_disposed.set(this, false);
66
66
  _QuerySubscriptionProxy_initialized.set(this, void 0);
67
+ _QuerySubscriptionProxy_initResolve.set(this, void 0);
68
+ _QuerySubscriptionProxy_initReject.set(this, void 0);
67
69
  _QuerySubscriptionProxy_initTimeoutId.set(this, void 0);
68
70
  _QuerySubscriptionProxy_query.set(this, void 0);
71
+ this.isSurrealDB = false;
69
72
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_uuid, uuid, "f");
70
73
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_query, query, "f");
71
74
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_client, client, "f");
72
75
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_callbacks, new Set(), "f");
73
76
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_latestResult, null, "f");
77
+ // Create the promise once and store its resolve/reject
78
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
79
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
80
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, reject, "f");
81
+ }), "f");
74
82
  }
75
83
  async subscribe() {
76
- // initialize the query subscription
77
- const result = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
78
- __classPrivateFieldSet(this, _QuerySubscriptionProxy_subscriptionId, result.subscriptionId, "f");
79
- // Subscribe to query updates
80
- __classPrivateFieldSet(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
81
- // Add timeout to prevent hanging promises
84
+ // Clean up previous subscription attempt if retrying
85
+ if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_unsubscribe, "f")) {
86
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_unsubscribe, "f").call(this);
87
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_unsubscribe, undefined, "f");
88
+ }
89
+ // Clear any existing timeout
90
+ if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_initTimeoutId, "f")) {
91
+ clearTimeout(__classPrivateFieldGet(this, _QuerySubscriptionProxy_initTimeoutId, "f"));
92
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initTimeoutId, undefined, "f");
93
+ }
94
+ // Clear any existing keepalive timer to prevent accumulation
95
+ if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_keepaliveTimer, "f")) {
96
+ clearTimeout(__classPrivateFieldGet(this, _QuerySubscriptionProxy_keepaliveTimer, "f"));
97
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_keepaliveTimer, undefined, "f");
98
+ }
99
+ try {
100
+ // Initialize the query subscription
101
+ let initialResult;
102
+ if (this.isSurrealDB) {
103
+ initialResult = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveSubscribeSurrealQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
104
+ }
105
+ else {
106
+ initialResult = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
107
+ }
108
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_subscriptionId, initialResult.subscriptionId, "f");
109
+ // Process the initial result immediately for fast UX
110
+ if (initialResult.result) {
111
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_latestResult, initialResult.result, "f");
112
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_notifyCallbacks).call(this, initialResult.result);
113
+ }
114
+ else {
115
+ console.warn('⚠️ No initial result returned from subscribeQuery!');
116
+ }
117
+ // Set up timeout for retry
82
118
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initTimeoutId, setTimeout(() => {
83
- reject(new Error('Subscription initialization timed out after 30 seconds. Resubscribing...'));
84
- this.subscribe();
85
- }, 30000), "f"); // 30 seconds timeout
119
+ console.error('Subscription initialization timed out after 30 seconds. Resubscribing...');
120
+ // Recursively retry subscription, catching any errors
121
+ this.subscribe().catch(error => {
122
+ console.error('Error during subscription retry after timeout:', error);
123
+ });
124
+ }, 30000), "f");
86
125
  // Subscribe to query updates
87
- __classPrivateFieldSet(this, _QuerySubscriptionProxy_unsubscribe, __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeToQueryUpdates(__classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"), (result) => {
126
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_unsubscribe, __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeToQueryUpdates(__classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"), (updateResult) => {
127
+ // Clear timeout on first message
88
128
  if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_initTimeoutId, "f")) {
89
129
  clearTimeout(__classPrivateFieldGet(this, _QuerySubscriptionProxy_initTimeoutId, "f"));
90
130
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_initTimeoutId, undefined, "f");
91
131
  }
92
- resolve(true);
93
- // if the result is one of those repeated initialization results
94
- // and we got a result before, we don't notify the callbacks
95
- // so they don't get confused (we could have gotten another
96
- // more recent result in between)
97
- if (result.isInit && __classPrivateFieldGet(this, _QuerySubscriptionProxy_latestResult, "f")) {
98
- return;
132
+ // Resolve the initialization promise (only resolves once)
133
+ if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_initResolve, "f")) {
134
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_initResolve, "f").call(this, true);
135
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, undefined, "f"); // Prevent double-resolve
136
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, undefined, "f");
99
137
  }
100
- __classPrivateFieldSet(this, _QuerySubscriptionProxy_latestResult, result, "f");
101
- __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_notifyCallbacks).call(this, result);
138
+ // Skip duplicate init messages
139
+ if (updateResult.isInit && __classPrivateFieldGet(this, _QuerySubscriptionProxy_latestResult, "f"))
140
+ return;
141
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_latestResult, updateResult, "f");
142
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_notifyCallbacks).call(this, updateResult);
102
143
  }), "f");
103
- }), "f");
144
+ }
145
+ catch (error) {
146
+ console.error('Error setting up subscription:', error);
147
+ // Reject the promise if this is the first attempt
148
+ if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_initReject, "f")) {
149
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_initReject, "f").call(this, error);
150
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initResolve, undefined, "f");
151
+ __classPrivateFieldSet(this, _QuerySubscriptionProxy_initReject, undefined, "f");
152
+ }
153
+ throw error; // Re-throw so caller knows it failed
154
+ }
104
155
  // Start keepalive loop using platform-agnostic setTimeout
105
156
  const keepaliveLoop = async () => {
106
157
  if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_disposed, "f"))
107
158
  return;
108
159
  try {
109
- await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").keepAliveQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
160
+ if (this.isSurrealDB) {
161
+ await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveKeepAliveSurrealQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
162
+ }
163
+ else {
164
+ await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").keepAliveQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
165
+ }
110
166
  }
111
167
  catch (e) {
112
168
  console.error('Error in keepalive:', e);
113
169
  // try to reinitialize the subscription
114
170
  console.log('Reinitializing subscription for query:', __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
115
- await this.subscribe();
116
- console.log('Subscription reinitialized');
171
+ try {
172
+ await this.subscribe();
173
+ console.log('Subscription reinitialized');
174
+ }
175
+ catch (resubscribeError) {
176
+ console.error('Error during resubscription from keepalive:', resubscribeError);
177
+ // Don't schedule another keepalive on resubscribe failure
178
+ return;
179
+ }
117
180
  }
118
181
  // Schedule next keepalive if not disposed
119
182
  if (!__classPrivateFieldGet(this, _QuerySubscriptionProxy_disposed, "f")) {
@@ -138,7 +201,9 @@ export class QuerySubscriptionProxy {
138
201
  * through the subscription channel. This ensures the subscription is fully
139
202
  * set up before allowing access to results or updates.
140
203
  *
141
- * The promise will reject if no result is received within 30 seconds.
204
+ * If no result is received within 30 seconds, the subscription will automatically
205
+ * retry. The promise will remain pending until a subscription message successfully
206
+ * arrives, or until a fatal error occurs during subscription setup.
142
207
  *
143
208
  * Note: You typically don't need to await this directly since the subscription
144
209
  * creation methods (like subscribeInfer) already wait for initialization.
@@ -204,12 +269,18 @@ export class QuerySubscriptionProxy {
204
269
  }
205
270
  // Tell the backend to dispose of the subscription
206
271
  if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f")) {
207
- __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").disposeQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
208
- .catch(e => console.error('Error disposing query subscription:', e));
272
+ if (this.isSurrealDB) {
273
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveDisposeSurrealQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
274
+ .catch(e => console.error('Error disposing surreal query subscription:', e));
275
+ }
276
+ else {
277
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").disposeQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
278
+ .catch(e => console.error('Error disposing query subscription:', e));
279
+ }
209
280
  }
210
281
  }
211
282
  }
212
- _QuerySubscriptionProxy_uuid = new WeakMap(), _QuerySubscriptionProxy_subscriptionId = new WeakMap(), _QuerySubscriptionProxy_client = new WeakMap(), _QuerySubscriptionProxy_callbacks = new WeakMap(), _QuerySubscriptionProxy_keepaliveTimer = new WeakMap(), _QuerySubscriptionProxy_unsubscribe = new WeakMap(), _QuerySubscriptionProxy_latestResult = new WeakMap(), _QuerySubscriptionProxy_disposed = new WeakMap(), _QuerySubscriptionProxy_initialized = new WeakMap(), _QuerySubscriptionProxy_initTimeoutId = new WeakMap(), _QuerySubscriptionProxy_query = new WeakMap(), _QuerySubscriptionProxy_instances = new WeakSet(), _QuerySubscriptionProxy_notifyCallbacks = function _QuerySubscriptionProxy_notifyCallbacks(result) {
283
+ _QuerySubscriptionProxy_uuid = new WeakMap(), _QuerySubscriptionProxy_subscriptionId = new WeakMap(), _QuerySubscriptionProxy_client = new WeakMap(), _QuerySubscriptionProxy_callbacks = new WeakMap(), _QuerySubscriptionProxy_keepaliveTimer = new WeakMap(), _QuerySubscriptionProxy_unsubscribe = new WeakMap(), _QuerySubscriptionProxy_latestResult = new WeakMap(), _QuerySubscriptionProxy_disposed = new WeakMap(), _QuerySubscriptionProxy_initialized = new WeakMap(), _QuerySubscriptionProxy_initResolve = new WeakMap(), _QuerySubscriptionProxy_initReject = new WeakMap(), _QuerySubscriptionProxy_initTimeoutId = new WeakMap(), _QuerySubscriptionProxy_query = new WeakMap(), _QuerySubscriptionProxy_instances = new WeakSet(), _QuerySubscriptionProxy_notifyCallbacks = function _QuerySubscriptionProxy_notifyCallbacks(result) {
213
284
  for (const callback of __classPrivateFieldGet(this, _QuerySubscriptionProxy_callbacks, "f")) {
214
285
  try {
215
286
  callback(result);
@@ -399,6 +470,36 @@ export class PerspectiveProxy {
399
470
  async infer(query) {
400
471
  return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").queryProlog(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
401
472
  }
473
+ /**
474
+ * Executes a SurrealQL query against the perspective's link cache.
475
+ * This allows powerful SQL-like queries on the link data stored in SurrealDB.
476
+ *
477
+ * **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
478
+ * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
479
+ * blocked for security reasons. Use the perspective's add/remove methods to modify links.
480
+ *
481
+ * @param query - SurrealQL query string (read-only operations only)
482
+ * @returns Query results as parsed JSON
483
+ *
484
+ * @example
485
+ * ```typescript
486
+ * // Get all links
487
+ * const links = await perspective.querySurrealDB('SELECT * FROM link');
488
+ *
489
+ * // Filter links by predicate
490
+ * const follows = await perspective.querySurrealDB(
491
+ * "SELECT * FROM link WHERE predicate = 'follows'"
492
+ * );
493
+ *
494
+ * // Complex aggregation query
495
+ * const stats = await perspective.querySurrealDB(
496
+ * "SELECT predicate, count() as total FROM link GROUP BY predicate"
497
+ * );
498
+ * ```
499
+ */
500
+ async querySurrealDB(query) {
501
+ return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").querySurrealDB(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
502
+ }
402
503
  /**
403
504
  * Adds a new link to the perspective.
404
505
  *
@@ -1107,5 +1208,33 @@ export class PerspectiveProxy {
1107
1208
  await subscriptionProxy.initialized;
1108
1209
  return subscriptionProxy;
1109
1210
  }
1211
+ /**
1212
+ * Creates a subscription for a SurrealQL query that updates in real-time.
1213
+ *
1214
+ * This method:
1215
+ * 1. Creates the subscription on the Rust side
1216
+ * 2. Sets up the subscription callback
1217
+ * 3. Waits for the initial result to come through the subscription channel
1218
+ * 4. Returns a fully initialized QuerySubscriptionProxy
1219
+ *
1220
+ * The returned subscription is guaranteed to be ready to receive updates,
1221
+ * as this method waits for the initialization process to complete.
1222
+ *
1223
+ * The subscription will be automatically cleaned up on both frontend and backend
1224
+ * when dispose() is called. Make sure to call dispose() when you're done to
1225
+ * prevent memory leaks and ensure proper cleanup of resources.
1226
+ *
1227
+ * @param query - SurrealQL query string
1228
+ * @returns Initialized QuerySubscriptionProxy instance
1229
+ */
1230
+ async subscribeSurrealDB(query) {
1231
+ const subscriptionProxy = new QuerySubscriptionProxy(this.uuid, query, __classPrivateFieldGet(this, _PerspectiveProxy_client, "f"));
1232
+ subscriptionProxy.isSurrealDB = true;
1233
+ // Start the subscription on the Rust side first to get the real subscription ID
1234
+ await subscriptionProxy.subscribe();
1235
+ // Wait for the initial result
1236
+ await subscriptionProxy.initialized;
1237
+ return subscriptionProxy;
1238
+ }
1110
1239
  }
1111
1240
  _PerspectiveProxy_handle = new WeakMap(), _PerspectiveProxy_client = new WeakMap(), _PerspectiveProxy_perspectiveLinkAddedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkRemovedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkUpdatedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveSyncStateChangeCallbacks = new WeakMap();
@@ -22,6 +22,7 @@ export default class PerspectiveResolver {
22
22
  perspectivePublishSnapshot(uuid: string): String | null;
23
23
  perspectiveQueryLinks(uuid: string, query: LinkQuery): LinkExpression[];
24
24
  perspectiveQueryProlog(uuid: string, query: string): Promise<string>;
25
+ perspectiveQuerySurrealDB(uuid: string, query: string): Promise<string>;
25
26
  perspectiveSubscribeQuery(uuid: string, query: string): Promise<QuerySubscription>;
26
27
  perspectiveAdd(name: string, pubSub: any): PerspectiveHandle;
27
28
  perspectiveUpdate(uuid: string, name: string, pubSub: any): PerspectiveHandle;
@@ -87,6 +87,9 @@ let PerspectiveResolver = class PerspectiveResolver {
87
87
  async perspectiveQueryProlog(uuid, query) {
88
88
  return `[{"X": 1}]`;
89
89
  }
90
+ async perspectiveQuerySurrealDB(uuid, query) {
91
+ return `[]`;
92
+ }
90
93
  async perspectiveSubscribeQuery(uuid, query) {
91
94
  const result = `[{"X": 1}]`;
92
95
  return {
@@ -274,6 +277,14 @@ __decorate([
274
277
  __metadata("design:paramtypes", [String, String]),
275
278
  __metadata("design:returntype", Promise)
276
279
  ], PerspectiveResolver.prototype, "perspectiveQueryProlog", null);
280
+ __decorate([
281
+ Query(returns => String),
282
+ __param(0, Arg('uuid')),
283
+ __param(1, Arg('query')),
284
+ __metadata("design:type", Function),
285
+ __metadata("design:paramtypes", [String, String]),
286
+ __metadata("design:returntype", Promise)
287
+ ], PerspectiveResolver.prototype, "perspectiveQuerySurrealDB", null);
277
288
  __decorate([
278
289
  Mutation(returns => QuerySubscription),
279
290
  __param(0, Arg('uuid')),
@@ -470,6 +470,7 @@ type Query {
470
470
  perspective(uuid: String!): PerspectiveHandle
471
471
  perspectiveQueryLinks(query: LinkQuery!, uuid: String!): [LinkExpression!]
472
472
  perspectiveQueryProlog(query: String!, uuid: String!): String!
473
+ perspectiveQuerySurrealDB(query: String!, uuid: String!): String!
473
474
  perspectiveSnapshot(uuid: String!): Perspective
474
475
  perspectives: [PerspectiveHandle!]!
475
476
  runtimeFriendStatus(did: String!): PerspectiveExpression
@@ -466,6 +466,7 @@ type Query {
466
466
  perspective(uuid: String!): PerspectiveHandle
467
467
  perspectiveQueryLinks(query: LinkQuery!, uuid: String!): [LinkExpression!]
468
468
  perspectiveQueryProlog(query: String!, uuid: String!): String!
469
+ perspectiveQuerySurrealDB(query: String!, uuid: String!): String!
469
470
  perspectiveSnapshot(uuid: String!): Perspective
470
471
  perspectives: [PerspectiveHandle!]!
471
472
  runtimeFriendStatus(did: String!): PerspectiveExpression
package/package.json CHANGED
@@ -69,5 +69,5 @@
69
69
  "graphql@15.7.2": "patches/graphql@15.7.2.patch"
70
70
  }
71
71
  },
72
- "version": "0.10.1"
72
+ "version": "0.11.0"
73
73
  }