@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
• #initTimeoutId
• #initialized
• #keepaliveTimer
• #latestResult
• #query
• #subscriptionId
• #unsubscribe
• #uuid

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:75

Properties

#callbacks

• Private #callbacks: Set<QueryCallback>

Defined in

perspectives/PerspectiveProxy.ts:61

#client

• Private #client: PerspectiveClient

Defined in

perspectives/PerspectiveProxy.ts:60

#disposed

• Private #disposed: boolean = false

Defined in

perspectives/PerspectiveProxy.ts:65

#initTimeoutId

• Private Optional #initTimeoutId: Timeout

Defined in

perspectives/PerspectiveProxy.ts:67

#initialized

• Private #initialized: Promise<boolean>

Defined in

perspectives/PerspectiveProxy.ts:66

#keepaliveTimer

• Private #keepaliveTimer: number

Defined in

perspectives/PerspectiveProxy.ts:62

#latestResult

• Private #latestResult: AllInstancesResult

Defined in

perspectives/PerspectiveProxy.ts:64

#query

• Private #query: string

Defined in

perspectives/PerspectiveProxy.ts:68

#subscriptionId

• Private #subscriptionId: string

Defined in

perspectives/PerspectiveProxy.ts:59

#unsubscribe

• Private Optional #unsubscribe: () => void

Type declaration

▸ (): void

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:63

#uuid

• Private #uuid: string

Defined in

perspectives/PerspectiveProxy.ts:58

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:151

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.

The promise will reject if no result is received within 30 seconds.

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:164

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:176

Methods

#notifyCallbacks

▸ Private #notifyCallbacks(result): void

Internal method to notify all callbacks of a new result

Parameters

Returns

void

Defined in

perspectives/PerspectiveProxy.ts:205

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:226

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:199

subscribe

▸ subscribe(): Promise<void>

Returns

Promise<void>

Defined in

perspectives/PerspectiveProxy.ts:83