JS Helpers and Utilities

Relevant source files

The following files were used as context for generating this wiki page:

• guest-js/index.ts
• README.md
• examples/tauri-app/src/App.svelte
• package.json
• permissions/schemas/schema.json

The JS Helpers and Utilities module provides a high-level abstraction layer over the raw Tauri IPC commands used to interact with the Centrifugo plugin. It simplifies complex operations such as automated JSON serialization, base64 encoding/decoding, and managed subscription lifecycles.

This module is primarily contained within guest-js/index.ts and is designed to provide developers with a "convenience-first" API. By wrapping the core invoke and listen functions, it reduces boilerplate code required for common real-time communication patterns like publishing structured data or awaiting connection stability.

Sources: guest-js/index.ts:1-12, README.md:144-150

Data Transformation Utilities

The utils object provides essential methods for handling the data format requirements of the Centrifugo protocol. Since the underlying Rust plugin and Centrifugo server often expect or provide data as base64-encoded strings, these utilities automate the conversion between JavaScript objects and the required transport format.

Encoding and Decoding Logic

The utility module handles both raw string base64 conversion and structured JSON transformation. It utilizes standard browser APIs (btoa and atob) to perform these operations within the Tauri webview environment.

The diagram above illustrates the flow of data through the transformation utilities.
Sources: guest-js/index.ts:241-278, examples/tauri-app/src/App.svelte:115-121

Utility Methods Summary

Method	Input	Output	Description
encode	string	string	Encodes a UTF-8 string to base64.
decode	string	string	Decodes a base64 string back to UTF-8.
encodeJson	any	string	Stringifies an object and encodes it to base64.
decodeJson	string	T	Decodes a base64 string and parses it as JSON.

Sources: guest-js/index.ts:241-278

High-Level API Helpers

The helpers object aggregates complex sequences of plugin commands into single, awaitable functions. These helpers manage state, such as waiting for a connection to be valid before proceeding with operations.

Publication and RPC Helpers

These helpers automate the process of preparing data before sending it over the Tauri bridge. Instead of manually encoding payloads, developers can pass native JavaScript objects directly.

• publishJson: Encodes the provided data using utils.encodeJson before invoking the core publish command.
• rpcJson: A bidirectional helper that encodes the request parameters and automatically decodes the base64 response from the server into a JS object.

Sources: guest-js/index.ts:284-298, README.md:152-162

Connection Management Helpers

Managing the asynchronous nature of WebSocket connections is handled via specialized polling and retry logic.

• waitForConnection: A promise-based helper that polls the isConnected state at 100ms intervals until the connection is established or a timeout (default 10s) is reached.
• getConnectionStatus: Implements a retry mechanism (default 3 attempts) for retrieving the connection state, providing resilience against transient IPC failures.

Sources: guest-js/index.ts:326-360, examples/tauri-app/src/App.svelte:270-280

Subscription Helpers

The subscription helpers combine channel attachment with event registration to provide a unified "subscribe and listen" pattern.

The sequence diagram shows how helpers.subscribeToChannel synchronizes backend subscription with frontend message routing.
Sources: guest-js/index.ts:303-321, README.md:164-170

Enhanced Event Listeners

Beyond standard event wrappers, the JS module includes specialized listeners that perform automatic message filtering and decoding.

Specialized Publication Listeners

Listener	Trigger	Behavior
onMessage	Any publication	Decodes base64 data to JSON; returns raw if decoding fails.
onChannelMessage	Specific channel	Filters incoming messages by channel name before decoding.
onAnyMessage	Any publication	Returns decoded data along with a client-side timestamp.

Sources: guest-js/index.ts:203-239, README.md:275-290

Event Data Wrappers

All events are encapsulated in a TauriEventWrapper<T>, ensuring consistent access to the event name, payload, and unique ID provided by the Tauri event system.

export interface TauriEventWrapper<T> {
  event: string
  payload: T
  id: number
}

Sources: guest-js/index.ts:68-72

Permission and Security Context

The execution of these JS helpers is governed by the Tauri permission system. The centrifugo:default permission set must be enabled to allow these utilities to invoke the underlying commands.

The default permission set includes:

• allow-connect, allow-disconnect
• allow-publish, allow-rpc
• allow-add-subscription, allow-remove-subscription
• allow-get-connection-state, allow-get-subscriptions

Sources: permissions/schemas/schema.json:590-620, README.md:374-385

Conclusion

The JS Helpers and Utilities module acts as the primary interface for frontend developers, effectively hiding the complexity of base64 data handling and IPC event management. By providing the utils and helpers namespaces, the plugin ensures that common tasks like JSON publication and managed subscriptions are implemented consistently and safely across the application.