Channel Methods

Channel methods in the Cerebellum SDK enable you to work with specific communication channels. These methods allow you to subscribe to channels, unsubscribe when needed, and retrieve past messages. Channels provide a way to organize your real-time communication, making it easy to separate concerns and manage different streams of data within your application.

subscribeChannel

subscribeChannel(channelName: string, callback?: (message: Message) => any): void

Subscribes to a specified channel. Optionally takes a callback function that will be invoked when a new message is received in the channel.

Arguments

• channelName: string
  • Description: The name of the channel to subscribe to.
• callback?: (message: Message) => any
  • Description: An optional callback function that will be executed when a new message is received. The function receives a Message object.

Return Type

• void   - Description: This method does not return a value.

Callback Argument

• message: Message
  • Description: The callback function receives a Message object containing details of the new message.
• Message Interface:

interface Message {
  content: any;
  createdAt: string;
  socketId: string;
}

Example

cerebellum.subscribeChannel("general", (message) => {
  console.log("New message received:", message.content);
});

Explanation

• In this example, the subscribeChannel method subscribes to the "general" channel and sets up a callback to handle incoming messages. When a new message is received, the callback logs the message content.

---

unsubscribeChannel

unsubscribeChannel(channelName: string, callback?: (message: Message) => any): void

Description

Unsubscribes from a specified channel. If a callback was provided when subscribing to the channel, it should be passed to this method to deregister it.

Arguments

• channelName: string
  • Description: The name of the channel to unsubscribe from.
• callback?: (message: Message) => any
  • Description: An optional callback function that was used when subscribing to the channel. If provided, it will be deregistered from receiving messages.

Return Type

• void
  • Description: This method does not return a value.

Example

const onNewMessage = (message) => {
  console.log("New message received:", message.content);
};

cerebellum.unsubscribeChannel("general", onNewMessage);

Explanation

• In this example, the unsubscribeChannel method is used to unsubscribe from the "general" channel and remove the specified callback if it was registered previously.

---

getPastMessages

getPastMessages(
  channelName: string,
  options?: getPastMessagesOptions
): Promise<PastMessages>

Description

Fetches past messages from a specified channel. This method allows you to retrieve historical messages from the given channel, with options to control the number of messages returned, their sort order, and pagination.

Arguments

• channelName: string
  • Description: The name of the channel from which to retrieve past messages.
• options?: getPastMessagesOptions (optional)
  • Description: An object containing options to customize the retrieval of past messages.
  • limit?: number
    • Description: The maximum number of messages to retrieve. Defaults to 50 if not provided.
  • sortDirection?: "ascending" | "descending"
    • Description: The sort order of the messages. Can be either "ascending" or "descending". Defaults to "ascending".
  • lastEvaluatedKey?: LastEvaluatedKey
    • Description: Used for pagination. Specifies the last message received in the previous request to continue retrieving messages from where you left off.

Return Type

• Promise<PastMessages>
  • Description: Returns a promise that resolves to an object containing past messages and, optionally, a lastEvaluatedKey for pagination.
• PastMessages Interface:

interface PastMessages {
  messages: Message[];
  lastEvaluatedKey?: LastEvaluatedKey;
}

• messages: Message[]     - Description: An array of Message objects representing the past messages retrieved from the channel.   - lastEvaluatedKey?: LastEvaluatedKey (optional)     - Description: An object representing the last evaluated key used for pagination. This key can be used in subsequent requests to fetch more messages.

• Message Interface:

interface Message {
  content: any;
  createdAt: string;
}

• content: any
  • Description: The content of the message.
• createdAt: string
  • Description: The timestamp when the message was created.

Example

const pastMessages = await cerebellum.getPastMessages("general", {
  limit: 10,
  sortDirection: "descending",
})
console.log("Retrieved messages:", result.messages);
if (result.lastEvaluatedKey) {
  console.log("More messages available. Use lastEvaluatedKey to fetch them.");
}

Explanation

• In this example, getPastMessages is called with the channel name "general" and options to limit the results to 10 messages and sort them in descending order.
• The returned promise resolves to an object containing the messages and an optional lastEvaluatedKey.
• If lastEvaluatedKey is present, it indicates that there are more messages available beyond the current result. You can use this key to fetch additional messages if needed.

This method provides a flexible way to retrieve historical messages from a channel, supporting pagination and sorting to handle large datasets efficiently.