@coasys/ad4m / Exports / QuerySubscriptionProxy

Class: QuerySubscriptionProxy

Proxy object for a subscribed Prolog query that provides real-time updates

This class handles:

• Keeping the subscription alive by sending periodic keepalive signals
• Managing callbacks for result updates
• Subscribing to query updates via GraphQL subscriptions
• Maintaining the latest query result
• Ensuring subscription is fully initialized before allowing access
• Cleaning up resources when disposed

The subscription will remain active as long as keepalive signals are sent. Make sure to call dispose() when you're done with the subscription to clean up resources, stop keepalive signals, and notify the backend to remove the subscription.

The subscription goes through an initialization process where it waits for the first result to come through the subscription channel. You can await the initialized promise to ensure the subscription is ready. The initialization will timeout after 30 seconds if no result is received.

Example usage:

const subscription = await perspective.subscribeInfer("my_query(X)");
// At this point the subscription is already initialized since subscribeInfer waits
 
// Set up callback for future updates
const removeCallback = subscription.onResult(result => {
    console.log("New result:", result);
});
 
// Later: clean up subscription and notify backend
subscription.dispose();

Table of contents

Constructors

• constructor

Properties

• #callbacks
• #client
• #disposed
• #initReject
• #initResolve
• #initTimeoutId
• #initialized
• #keepaliveTimer
• #latestResult
• #query
• #subscriptionId
• #unsubscribe
• #uuid
• isSurrealDB

Accessors

• id
• initialized
• result

Methods

• #notifyCallbacks
• dispose
• onResult
• subscribe

Constructors

constructor

• new QuerySubscriptionProxy(uuid, query, client)

Creates a new query subscription

Parameters

Defined in

perspectives/PerspectiveProxy.ts:78 (opens in a new tab)

Properties

#callbacks

• Private #callbacks: Set<QueryCallback>

Defined in

perspectives/PerspectiveProxy.ts:61 (opens in a new tab)

#client

• Private #client: PerspectiveClient

Defined in

perspectives/PerspectiveProxy.ts:60 (opens in a new tab)

#disposed

• Private #disposed: boolean = false

Defined in

perspectives/PerspectiveProxy.ts:65 (opens in a new tab)

#initReject

• Private Optional #initReject: (reason?: any) => void

Type declaration

▸ (reason?): void

Parameters

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:68 (opens in a new tab)

#initResolve

• Private Optional #initResolve: (value: boolean) => void

Type declaration

▸ (value): void

Parameters

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:67 (opens in a new tab)

#initTimeoutId

• Private Optional #initTimeoutId: Timeout

Defined in

perspectives/PerspectiveProxy.ts:69 (opens in a new tab)

#initialized

• Private #initialized: Promise<boolean>

Defined in

perspectives/PerspectiveProxy.ts:66 (opens in a new tab)

#keepaliveTimer

• Private #keepaliveTimer: number

Defined in

perspectives/PerspectiveProxy.ts:62 (opens in a new tab)

#latestResult

• Private #latestResult: AllInstancesResult

Defined in

perspectives/PerspectiveProxy.ts:64 (opens in a new tab)

#query

• Private #query: string

Defined in

perspectives/PerspectiveProxy.ts:70 (opens in a new tab)

#subscriptionId

• Private #subscriptionId: string

Defined in

perspectives/PerspectiveProxy.ts:59 (opens in a new tab)

#unsubscribe

• Private Optional #unsubscribe: () => void

Type declaration

▸ (): void

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:63 (opens in a new tab)

#uuid

• Private #uuid: string

Defined in

perspectives/PerspectiveProxy.ts:58 (opens in a new tab)

isSurrealDB

• isSurrealDB: boolean = false

Defined in

perspectives/PerspectiveProxy.ts:71 (opens in a new tab)

Accessors

id

• get id(): string

Get the subscription ID for this query subscription

This is a unique identifier assigned when the subscription was created. It can be used to reference this specific subscription, for example when sending keepalive signals.

Returns

string

The subscription ID string

Defined in

perspectives/PerspectiveProxy.ts:217 (opens in a new tab)

initialized

• get initialized(): Promise<boolean>

Promise that resolves when the subscription has received its first result through the subscription channel. This ensures the subscription is fully set up before allowing access to results or updates.

If no result is received within 30 seconds, the subscription will automatically retry. The promise will remain pending until a subscription message successfully arrives, or until a fatal error occurs during subscription setup.

Note: You typically don't need to await this directly since the subscription creation methods (like subscribeInfer) already wait for initialization.

Returns

Promise<boolean>

Defined in

perspectives/PerspectiveProxy.ts:232 (opens in a new tab)

result

• get result(): AllInstancesResult

Get the latest query result

This returns the most recent result from the query, which could be either:

• The initial result from when the subscription was created
• The latest update received through the subscription

Returns

AllInstancesResult

The latest query result as a string (usually a JSON array of bindings)

Defined in

perspectives/PerspectiveProxy.ts:244 (opens in a new tab)

Methods

#notifyCallbacks

▸ Private #notifyCallbacks(result): void

Internal method to notify all callbacks of a new result

Parameters

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:273 (opens in a new tab)

dispose

▸ dispose(): void

Clean up the subscription and stop keepalive signals

This method:

1. Stops the keepalive timer
2. Unsubscribes from GraphQL subscription updates
3. Clears all registered callbacks
4. Cleans up any pending initialization timeout

After calling this method, the subscription is no longer active and will not receive any more updates. The instance should be discarded.

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:294 (opens in a new tab)

onResult

▸ onResult(callback): () => void

Add a callback that will be called whenever new results arrive

The callback will be called immediately with the current result, and then again each time the query results change.

Parameters

Returns

fn

A function that can be called to remove this callback

Example:

const removeCallback = subscription.onResult(result => {
    const bindings = JSON.parse(result);
    console.log("New bindings:", bindings);
});
 
// Later: stop receiving updates
removeCallback();

▸ (): void

Add a callback that will be called whenever new results arrive

The callback will be called immediately with the current result, and then again each time the query results change.

Returns

void

A function that can be called to remove this callback

Example:

const removeCallback = subscription.onResult(result => {
    const bindings = JSON.parse(result);
    console.log("New bindings:", bindings);
});
 
// Later: stop receiving updates
removeCallback();

Defined in

perspectives/PerspectiveProxy.ts:267 (opens in a new tab)

subscribe

▸ subscribe(): Promise<void>

Returns

Promise<void>

Defined in

perspectives/PerspectiveProxy.ts:92 (opens in a new tab)