Channels API Reference

The Channels API allows you to manage real-time communication channels, subscribe to events, publish messages, and handle channel states. This reference covers the methods and types available for working with channels.

Methods

connect()

connect(channelName: string): Promise<Channel>

Connects to a channel or creates a new one if it doesn't exist.

const channel = await realtime.connect('channel-name');

subscribe()

subscribe<T>(event: string | ChannelEvents, callback: Callback<T>)

Subscribes to a specific channel event. You can use either a string literal or the ChannelEvents enum.

const callback = (event: RealtimeMessage) => {
  console.log("Event received", event.data);
};

// Using ChannelEvents enum
channel.subscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED, callback);

// Using string literal
channel.subscribe('custom-event', callback);

unsubscribe()

unsubscribe(event: string | ChannelEvents)

Unsubscribes from a specific channel event. You can use either a string literal or the ChannelEvents enum.

// Using ChannelEvents enum
channel.unsubscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED);

// Using string literal
channel.unsubscribe('custom-event');

publish()

publish<T>(event: string, data: T)

Publishes an event with associated data to the channel.

channel.publish('custom-event', { message: "Hello, channel!" });

fetchHistory()

fetchHistory(eventName?: string): Promise<Record<string, RealtimeMessage[]> | RealtimeMessage[]>

Retrieves the history of events for the channel. If an event name is provided, it returns the history for that specific event.

// Fetch all events
const allEvents = await channel.fetchHistory();

// Fetch history for a specific event
const eventHistory = await channel.fetchHistory('custom-event');

Types

RealtimeComponentState

Enum representing the state of the realtime component.

Event	Value	Description
STARTED	'STARTED'	The realtime component has started
STOPPED	'STOPPED'	The realtime component has stopped

RealtimeChannelState

Enum representing the state of a realtime channel.

Event	Value	Description
DISCONNECTED	'DISCONNECTED'	The channel is disconnected
CONNECTED	'CONNECTED'	The channel is connected
CONNECTING	'CONNECTING'	The channel is in the process of connecting

RealtimeComponentEvent

Enum of available realtime component events.

Event	Value	Description
REALTIME_STATE_CHANGED	'realtime-component.state-changed'	Triggered when the realtime component state changes

RealtimeChannelEvent

Enum of available realtime channel events.

Event	Value	Description
REALTIME_CHANNEL_STATE_CHANGED	'realtime-channel.state-changed'	Triggered when the channel state changes

RealtimeMessage<T>

Represents a realtime message.

Field	Type	Description
name	string	The name of the event
connectionId	string	Unique identifier for the connection
participantId	string | null	Identifier for the participant, or null
data	T	The payload of the message
timestamp	number	Unix timestamp of when the message was sent

Callback<T>

Callback function type for channel events.

Parameter	Type	Description
data	RealtimeMessage<T> | string	The data received in the callback, either a state or a RealtimeMessage

Usage Example

Here's a complete example demonstrating the usage of the Channels API:

import { RealtimeChannelEvent, RealtimeChannelState } from '@superviz/realtime';

const channel = await realtime.connect('channel-name');

// Subscribe to channel state changes
channel.subscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED, (state: RealtimeChannelState) => {
  console.log("Channel state changed", state);
});

// Subscribe to a custom event
channel.subscribe('custom-event', (message: RealtimeMessage) => {
  console.log("Custom event received", message.data);
});

// Publish a custom event
channel.publish('custom-event', { message: "Hello, channel!" });

// Fetch history for all events
const allEvents = await channel.fetchHistory();
console.log("All events", allEvents);

// Fetch history for a specific event
const customEventHistory = await channel.fetchHistory('custom-event');
console.log("Custom event history", customEventHistory);

// Unsubscribe from events
channel.unsubscribe(RealtimeChannelEvent.REALTIME_CHANNEL_STATE_CHANGED);
channel.unsubscribe('custom-event');

This example shows how to connect to a channel, subscribe to channel state changes and custom events, publish events, fetch event history, and unsubscribe from events.