sitemap.xml llms.txt
Skip to main content

Channel Class

The Channel class implements a push channel and

  • Constructs a CometD channel path based on the provided scope.
  • Automatically reuses existing subscriptions for the same path if available.
  • Provides methods to publish data to the channel and to subscribe/unsubscribe from it.
  • Supports automatic cleanup of duplicate subscriptions.
Class signature
export default class Channel<D = ChannelMessageData> {
    path: string;
    update: ((data: ChannelMessage<D>) => unknown) | undefined;
    subscription: SubscriptionHandle | null;

    constructor(scope: ChannelScope);
    publish(content: D): Promise<Message>;
    subscribe(
        update: (data: ChannelMessage<D>) => unknown,
        options?: { inert?: boolean },
    ): Promise<SubscriptionHandle>;
    unsubscribe(): Promise<void>;
    unsubscribeAll(): Promise<void>;
}

Type parameter​

Parameter D defaults to ChannelMessageData.

Defines the shape of the content payload carried by messages on this channel. Setting D gives you typed publish arguments and typed update callbacks.

Typed channel example
interface ChatMessage {
    text: string;
    userKey: string;
}

const channel = new Channel<ChatMessage>({
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: session.groupKey,
    pushCategory: PUSH_CATEGORY.CHAT,
});

await channel.subscribe((message) => {
    // message.content is typed as ChatMessage
    console.log(message.content.text);
});

Properties​

  • path (string): The computed CometD channel path, formatted as /{scopeBoundary}/{scopeKey}/{pushCategory} all lowercase.
  • update (((data: ChannelMessage<D>) => unknown) | undefined): A callback function invoked when a message is received.
  • subscription (SubscriptionHandle | null): The active CometD subscription handle, or null if the channel is not currently subscribed.

Constructor​

Constructs the channel path using the provided scope. If a subscription already exists for this path, it is reused.

Definition
constructor(scope: ChannelScope)

Parameters​

  • scope (ChannelScope object): An object defining the channel’s namespace, including:
    • scopeBoundary: Entity type. Takes a value of the SCOPE_BOUNDARY enum.
    • scopeKey: Entity key. Must be a GUID.
    • pushCategory: Define the type of the push channel. Takes a value of the PUSH_CATEGORY enum.
learn more

To learn about scope properties, read Defining scope.

Errors​

The constructor calls an internal validateScope and will throw an EpicenterError if:

  • scope is missing.
  • scopeBoundary, scopeKey, or pushCategory are missing.
  • scopeBoundary is not a value of the SCOPE_BOUNDARY enum.
  • pushCategory is not a value of the PUSH_CATEGORY enum.

Methods​

Publish​

Publishes content to the CometD channel.

Definition
publish(content: D): Promise<Message>

Parameters​

  • content (D): The payload to publish. Becomes the content field of the resulting ChannelMessage delivered to subscribers.

Returns​

A Promise<Message> that resolves with the CometD message envelope returned by the server on successful publish.

Example
import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';

const session = authAdapter.getLocalSession();
const channel = new Channel({
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: session.groupKey,
    pushCategory: PUSH_CATEGORY.CHAT,
});

await channel.publish({ message: 'Hello!' });

Subscribe​

Subscribes the currently logged in user to the CometD channel and attaches a handler for incoming messages. If a subscription already exists on this Channel instance, it is removed first — so only one subscription is ever active per instance.

Returns the SubscriptionHandle from CometD.

Definition
subscribe(
    update: (data: ChannelMessage<D>) => unknown,
    options?: { inert?: boolean },
): Promise<SubscriptionHandle>

Parameters​

  • update: Callback to run when a new message is received. Receives the full ChannelMessage envelope (address, sender, content, date, type).
  • options ({ inert?: boolean }, optional): Additional options:
    • options.inert (boolean): If true, creates an inert subscription that does not trigger reconnection logic on the underlying CometD adapter.

Returns​

A Promise<SubscriptionHandle> that resolves to the subscription handle returned by CometD on a successful subscribe.

Errors​

  • Re-throws any non-session error encountered during subscribe.
  • After 3 failed attempts, throws Error("Failed to subscribe to {path} after 3 attempts").
Example
import { Channel, authAdapter, SCOPE_BOUNDARY, PUSH_CATEGORY } from 'epicenter-libs';

const session = authAdapter.getLocalSession();
const channel = new Channel({
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: session.groupKey,
    pushCategory: PUSH_CATEGORY.CHAT,
});

await channel.subscribe((data) => {
    console.log(data.content);
});

Unsubscribe​

Removes the current user's subscription from CometD and clears the subscription handle. No-op if subscription is already null.

Definition
unsubscribe(): Promise<void>
Example
await channel.subscribe((data) => console.log(data));
// Later...
await channel.unsubscribe();

Unsubscribe all​

Removes all existing subscriptions for the current user from the CometD adapter.

Definition
unsubscribeAll(): Promise<void>
Example
await channel.unsubscribeAll();