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
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
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
const off = realtime.onStatus((status) => setOnline(status === 'open'))Throws
Never throws.
status()
status():
RealtimeStatus
Current connection status.
Returns
Example
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
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.