Cube Socket Client

A lightweight TypeScript wrapper for socket.io-client that handles socket connections, heartbeat rooms, broadcasting, and topic subscriptions, designed for efficient real-time communication in modern applications.

Features

• Simplified integration with socket.io-client.
• Heartbeat mechanism for maintaining active connections.
• Ability to differentiate between listening clients and broadcasting clients.
• Create, join, and leave rooms for organized message handling.
• Subscribe and unsubscribe to topics dynamically.
• Broadcast messages to rooms or topics.
• TypeScript support with built-in type declarations.

Installation

You can install the package via npm:

npm install cube-socket-client

Usage

Here’s how you can use Cube Socket Client in your project:

Basic Setup

import GlobalSocketClient from "cube-socket-client";

// Initialize the client
const client = new GlobalSocketClient(
  "your-api-key",
  "https://your-socket-server.com"
);
client.init();

// Subscribe to a topic
client.subscribe("some-topic", (message) => {
  console.log("Received message on some-topic:", message);
});

// Broadcast a message to a topic or room
client.broadcast("some-topic", { data: "Hello World!" });

// Check if connected
if (client.isConnected()) {
  console.log("Successfully connected to the socket server");
}

// Close the socket connection when done
client.close();

Heartbeat Mechanism

Upon connecting, the client automatically joins a "heart-beat" room and broadcasts service information at regular intervals (every 60 seconds) to ensure the connection remains active.

API Documentation

Constructor

constructor(apiKey: string, serverUrl: string, shouldBroadcast = true)

• apiKey: A unique key that identifies your service.
• serverUrl: The URL of the socket server.
• shouldBroadcast: Optional boolean to indicate if the client should broadcast its own heartbeat messages (default: true).

Methods

init()

Initializes the socket connection.

subscribe(topic: string, callback: (message: any) => void)

Subscribes to a topic and triggers the callback whenever a message is received on that topic.

• topic: The name of the topic to subscribe to.
• callback: A function to be called with the message received on the topic.

unsubscribe(topic: string)

Unsubscribes from a specific topic.

• topic: The name of the topic to unsubscribe from.

createRoom(room: string)

Creates a room and joins it.

• room: The name of the room to create.

leaveRoom(room: string)

Leaves a specific room.

• room: The name of the room to leave.

createTopic(topic: string)

Creates a new topic (this only affects local management).

• topic: The name of the topic to create.

broadcast(topicOrRoom: string, message: any)

Broadcasts a message to a specific topic or room.

• topicOrRoom: The name of the topic or room where the message should be sent.
• message: The message content to send.

isConnected(): boolean

Returns true if the socket is connected to the server, otherwise false.

close()

Closes the socket connection and clears any active intervals (such as heartbeat).

Example: Heartbeat Room

The client automatically joins a heart-beat room to send periodic heartbeat messages containing service information. This is done to maintain an active connection with the server:

const serviceInfo = {
  serviceName: "your-api-key",
  timestamp: new Date().toISOString(),
};

// Heartbeat message will be broadcast every 60 seconds
client.broadcast("heart-beat", serviceInfo);

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Developed by Platform Team. You can reach out for support or contributions via [email protected].