This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk/realtime / Realtime

Realtime ​

Realtime of a client: one WebSocket connection shared by all topics, opened on the first subscribe and closed about 1 s after the last off().

Methods ​

onResync() ​

Call Signature ​

onResync(listener): () => void

Subscribes to resync requests for all topics: after each reconnection (once per active topic) and when a snapshot requested in sequenced mode does not arrive within 10 s. Messages may have been lost: reload the base data over HTTP (e.g. wallet.getBalance(), the market orderbook). To react to a single topic, prefer the subscription with the topic descriptor.

Parameters ​
listener ​

(topic) => void

Receives the full topic, e.g. 'predictions:orderbook:m-1'.

Returns ​

() => void

Example ​
ts
realtime.onResync((topic) => queryClient.invalidateQueries({ queryKey: [topic] }))
Throws ​

CONFIGURATION_ERROR if listener is not a function (JS without types, an undefined value). It also goes to the client's onError.

Call Signature ​

onResync(topic, listener): () => void

Subscribes to resync requests for one topic (at the same moments as the other subscription); returns the function to cancel. Pass the same descriptor as subscribe: there is no need to build or compare the topic text. On a private topic (e.g. coreTopics.balance()), it applies to the session's user at the moment of firing, including after a user switch.

Parameters ​
topic ​

Topic<unknown>

Topic descriptor, e.g. coreTopics.balance() or predictionsTopics.orderbook({ marketId }).

listener ​

() => void

Called with no arguments on each resync request for that topic.

Returns ​

() => void

Example ​
ts
const offResync = realtime.onResync(coreTopics.balance(), () => void loadBalance())
Throws ​

CONFIGURATION_ERROR with a descriptor that did not come from defineTopic or a listener that is not a function. It also goes to the client's onError.


onStatus() ​

onStatus(listener): () => void

Subscribes to connection status changes; returns the function to cancel. It does not call the listener with the current status: use Realtime.status.

Parameters ​

listener ​

(status) => void

Called on each status change.

Returns ​

() => void

Example ​

ts
const off = realtime.onStatus((status) => setOnline(status === 'open'))

Throws ​

Never throws.


status() ​

status(): RealtimeStatus

Current connection status.

Returns ​

RealtimeStatus

Example ​

ts
if (realtime.status() === 'unavailable') showPollingFallback()

Throws ​

Never throws.


subscribe() ​

subscribe<T>(topic, handler): () => void

Subscribes handler to a topic and returns the function that cancels the subscription (idempotent). Opens the connection if needed; on a drop, it reconnects and resubscribes by itself. The message already arrives validated and in camelCase, under the client's validation mode (strict: a message outside the schema is not delivered). A private topic (e.g. balance) uses the current session's user: if the user changes (logout, account switch), the subscription is dropped — the previous user's handler never receives a message for the next one — and the app must subscribe again for the new user (e.g. by reacting to enginex.session.subscribe). Without an available WebSocket or without a URL (old runtime, nothing passed in webSocket), it returns a no-op and the status stays 'unavailable': it never throws in that case, not even for a private topic without a session.

Type Parameters ​

T ​

T

Parameters ​

topic ​

Topic<T>

Descriptor created by a topic factory (e.g. coreTopics.balance()).

handler ​

(message, meta) => void

Called on each message of the topic. An error thrown here does not affect the SDK.

Returns ​

() => void

Example ​

ts
const off = realtime.subscribe(coreTopics.balance(), (balance, meta) => {
  console.log(balance.available, meta.kind)
})
// later
off()

Throws ​

UNAUTHENTICATED on a private topic without a session; CONFIGURATION_ERROR after client.dispose() or with a descriptor that did not come from defineTopic. Both also go to the client's onError.