JavaScript API

Everything tauri-plugin-centrifugo-api exports, generated from guest-js/index.ts. Option and result types are on the types page; how the pieces fit together is in the guides.

Functions

Each one is a thin wrapper over one Tauri command.

connect()

connect(config: StartConfig): Promise<void>

Create the client, subscribe to config.channels and start connecting. Resolves at once (closing a previous client first); progress arrives as connecting / connected / disconnected events. The SDK reconnects with backoff by itself.

disconnect()

disconnect(): Promise<void>

Close the connection and drop the client with all its subscriptions.

setToken()

setToken(token: string): Promise<void>

Replace the connection token; the SDK uses it from the next connect attempt. Rejects when there is no client.

provideToken()

provideToken(token: string): Promise<void>

Answer a pending need_token event with a connection token. '' means "no token" (anonymous on connect, unauthorized on refresh). Rejects when no request is pending.

publish()

publish(request: PublishRequest): Promise<void>

Publish request.data to a channel. data is base64 unless dataEncoding: 'rawJson'. Map publish fields are rejected.

rpc()

rpc(request: RpcRequest): Promise<string>

Call an RPC method on the server. Resolves to the result data as base64.

presence()

presence(request: PresenceRequest): Promise<string[]>

Client IDs currently present in the channel.

presenceStats()

presenceStats(request: PresenceStatsRequest): Promise<[number, number]>

[numClients, numUsers] of the channel.

history()

history(request: HistoryRequest): Promise<PublicationData[]>

Publications from the channel history (limit, reverse). The channel must have history enabled on the server.

send()

send(request: SendRequest): Promise<void>

Send an asynchronous message to the server (no reply). Needs a server-side handler (proxy) for messages.

refresh()

refresh(request: RefreshRequest): Promise<void>

Answer a pending need_token request with a fresh connection token, or, when none is pending, set the token for the next connect. The SDK refreshes tokens itself (it emits need_token before expiry).

subRefresh()

subRefresh(request: SubRefreshRequest): Promise<void>

Answer a pending need_sub_token request for request.channel (sent for subscriptions created with a token, before it expires).

ping()

ping(): Promise<void>

Deprecated. The SDK keeps the connection alive with server pings and has no client ping. Resolves when connected, rejects otherwise.

isConnected()

isConnected(): Promise<boolean>

true while the client is in the connected state.

getSubscriptions()

getSubscriptions(): Promise<Record<string, boolean>>

Channels added through the plugin; the value is true while subscribed.

getConnectionState()

getConnectionState(): Promise<string>

'connecting', 'connected', 'closed' or 'disconnected' (also when there is no client).

addSubscription()

addSubscription(channel: string): Promise<void>

Subscribe to a channel with default options. Rejects when there is no client (call connect first).

addSubscriptionWithOptions()

addSubscriptionWithOptions(options: SubscribeOptions): Promise<void>

Subscribe to a channel with options: token, recovery, join/leave, positioning, delta compression, resume position.

removeSubscription()

removeSubscription(channel: string): Promise<void>

Unsubscribe from a channel and forget it. Unknown channels are ignored.

removeAllSubscriptions()

removeAllSubscriptions(): Promise<void>

Unsubscribe from every channel.

Event listeners

Each resolves to an UnlistenFn. The callback gets the whole Tauri event ({ event, payload, id }) unless noted; see Events for every event and its payload.

onCentrifugoEvent()

onCentrifugoEvent<T = TauriEventWrapper<unknown>>(event: | 'connecting' | 'connected' | 'disconnected' | 'error' | 'subscribed' | 'unsubscribed' | 'subscribing' | 'publication' | 'need_token' | 'need_sub_token' | 'join' | 'leave' | 'server_subscribed' | 'server_subscribing' | 'server_unsubscribed' | 'server_publication' | 'server_join' | 'server_leave', callback: (data: T) => void): Promise<UnlistenFn>

Listen to a centrifugo:<event> Tauri event. The callback gets the whole Tauri event ({ event, payload, id }); the data the backend sent is in payload. Pass TauriEventWrapper<Payload> as T.

onConnecting()

onConnecting(callback: (data: TauriEventWrapper<ConnectionStatus>) => void): Promise<UnlistenFn>

Connection attempt started (also on every reconnect). Payload: ts, code, reason.

onConnected()

onConnected(callback: (data: TauriEventWrapper<ConnectionStatus>) => void): Promise<UnlistenFn>

Connection established. Payload: ts, client (client ID).

onDisconnected()

onDisconnected(callback: (data: TauriEventWrapper<ConnectionStatus>) => void): Promise<UnlistenFn>

Client is disconnected (disconnect() or a terminal server code); the SDK does not reconnect from this state. Payload: ts, code, reason.

onError()

onError(callback: (data: TauriEventWrapper<ErrorData>) => void): Promise<UnlistenFn>

Client or subscription error. Payload: error, plus channel for subscription errors.

onSubscribed()

onSubscribed(callback: (data: TauriEventWrapper<SubscribedStatus>) => void): Promise<UnlistenFn>

Subscription is active. Payload: channel, wasRecovering, recovered, streamPosition.

onUnsubscribed()

onUnsubscribed(callback: (data: TauriEventWrapper<ChannelStatus>) => void): Promise<UnlistenFn>

Subscription ended. Payload: channel, code, reason.

onSubscribing()

onSubscribing(callback: (data: TauriEventWrapper<ChannelStatus>) => void): Promise<UnlistenFn>

Subscription attempt started (also on resubscribe). Payload: channel, code, reason.

onPublication()

onPublication(callback: (data: TauriEventWrapper<PublicationData>) => void): Promise<UnlistenFn>

Publication in a client-side subscription.

onNeedToken()

onNeedToken(callback: (data: TauriEventWrapper<ConnectionStatus>) => void): Promise<UnlistenFn>

The SDK needs a connection token: answer with provideToken (or refresh).

onNeedSubToken()

onNeedSubToken(callback: (data: TauriEventWrapper<ChannelStatus & { ts: number }>) => void): Promise<UnlistenFn>

The SDK needs a token for a subscription created with token: answer with subRefresh.

onServerPublication()

onServerPublication(callback: (data: TauriEventWrapper<PublicationData>) => void): Promise<UnlistenFn>

Publication in a server-side subscription.

onPublicationRawJson()

onPublicationRawJson(callback: (data: { channel: string; data: unknown }) => void): Promise<UnlistenFn>

Publications whose data is valid JSON; the callback gets { channel, data } with the parsed JSON.

onServerPublicationRawJson()

onServerPublicationRawJson(callback: (data: { channel: string; data: unknown }) => void): Promise<UnlistenFn>

Like onPublicationRawJson, for server-side subscriptions.

onMessage()

onMessage<T = unknown>(callback: (data: { channel: string; data: T | string }) => void): Promise<UnlistenFn>

Every publication, decoded: parsed JSON, else the base64 string as is. The callback gets { channel, data }.

onChannelMessage()

onChannelMessage<T = unknown>(channel: string, callback: (data: T | string) => void): Promise<UnlistenFn>

Like onMessage for one channel; the callback gets only data.

onAnyMessage()

onAnyMessage<T = unknown>(callback: (data: { channel: string; data: T | string; timestamp: number }) => void): Promise<UnlistenFn>

Like onMessage plus timestamp (Date.now() on arrival).

utils

utils.encode()

utils.encode(data: string): string

Encode string to base64

utils.decode()

utils.decode(data: string): string

Decode base64 to string

utils.encodeJson()

utils.encodeJson<T extends JsonValue>(data: T): string

Encode object to base64 JSON

utils.decodeJson()

utils.decodeJson<T>(data: string): T

Decode base64 JSON to object

helpers

helpers.publishJson()

helpers.publishJson<T extends JsonValue = JsonValue>(channel: string, data: T): Promise<void>

Publish JSON data to channel (automatically encodes to base64)

helpers.publishRawJson()

helpers.publishRawJson<T extends JsonValue = JsonValue>(channel: string, data: T): Promise<void>

Publish JSON as is (dataEncoding: 'rawJson', no base64)

helpers.rpcJson()

helpers.rpcJson<TReq extends JsonValue = JsonValue, TRes = unknown>(method: string, data: TReq): Promise<TRes>

Execute RPC with JSON data (automatically encodes/decodes)

helpers.rpcRawJson()

helpers.rpcRawJson<TReq extends JsonValue = JsonValue>(method: string, data: TReq): Promise<string>

Execute RPC with raw JSON request data; resolves to the result as base64

helpers.subscribeToChannel()

helpers.subscribeToChannel<T = unknown>(channel: string, callback: (data: T | string) => void): Promise<UnlistenFn>

Subscribe to channel and listen for messages

helpers.subscribeToChannels()

helpers.subscribeToChannels<T = unknown>(channels: string[], callback: (data: { channel: string; data: T | string }) => void): Promise<UnlistenFn[]>

Subscribe to multiple channels

helpers.waitForConnection()

helpers.waitForConnection(timeout: number = 10000): Promise<boolean>

Wait for connection to be established

helpers.getConnectionStatus()

helpers.getConnectionStatus(retries: number = 3): Promise<string>

Get connection status with retry