Channels

The Channels interface is used to create and destroy RealtimeChannel objects. Access it via the channels property of a Realtime client instance.

JavaScript

const channels = realtime.channels;

Properties

The Channels interface has the following properties:

allRecord<String, RealtimeChannel>

A map of all the channels that have been instantiated via get() and have not yet been released via release().

Get a channel

channels.get(name: string, channelOptions?: ChannelOptions): RealtimeChannel

Creates a new RealtimeChannel object if none for the given name exists, or returns the existing channel object. The channel is created or returned with the supplied ChannelOptions.

JavaScript

const channel = realtime.channels.get('all-gas-ion');

// With channel options
const encryptedChannel = realtime.channels.get('all-gas-ion', {
  cipher: { key: '<key>' }
});

Parameters

The get() method takes the following parameters:

namerequiredString

The name of the channel.

channelOptionsoptionalChannelOptions

Options for the channel, such as encryption or channel parameters.

Returns

RealtimeChannel

Returns a RealtimeChannel object for the given name. If a channel with that name already exists, the existing object is returned.

Get a derived channel

channels.getDerived(name: string, deriveOptions: DeriveOptions, channelOptions?: ChannelOptions): RealtimeChannel

Creates a new RealtimeChannel object if none for the given name exists, or returns the existing channel object. The channel is created or returned with the specified DeriveOptions and optional ChannelOptions.

Derived channels enable you to subscribe to a filtered subset of messages on a channel using subscription filters.

JavaScript

const derived = realtime.channels.getDerived('all-gas-ion', {
  filter: "name == 'important'"
});

Parameters

The getDerived() method takes the following parameters:

namerequiredString

The name of the channel.

deriveOptionsrequiredDeriveOptions

The derive options used to filter the channel.

channelOptionsoptionalChannelOptions

Options for the channel.

Returns

RealtimeChannel

Returns a derived RealtimeChannel object configured with the supplied filter.

Release a channel

channels.release(name: string): void

Releases all SDK-held references to a RealtimeChannel object, enabling it to be garbage collected. Useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it.

This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected.

Channels not already in the initialized, detached, or failed state are detached before release. After release, calling channels.get() with the same name returns a fresh channel object in the initialized state.

JavaScript

realtime.channels.release('all-gas-ion');

Parameters

The release() method takes the following parameters:

namerequiredString

The name of the channel to release.