signal.io-client

Installation

To install the library, use npm:

npm install signal-io-client

Description

A lightweight library designed to enable low-latency, bidirectional, and event-based communication between client and server using WebSockets. This library simplifies real-time data exchange, making it ideal for applications requiring fast and reliable communication. It offers an intuitive API, seamless integration, and efficient handling of various data types, ensuring smooth and responsive interactions across your applications.

Note: Server-side support is currently limited to Golang.

Usage

To initialize the library, use the following code:

import { io } from 'signal-io-client';

const socket = io("ws://127.0.0.1:5173", { /* Options */ });

Alternatively, include the library via CDN using the following code:

<script type="module">
  import { io } from "./dist/index.esm.js";
  const socket = io("ws://127.0.0.1:5173", { /* Options */ });
</script>

Available Options

• autoConnect: Determines whether to automatically connect upon initialization. Set to true (default) to auto-connect, or false to prevent automatic connection.

• reconnect: Determines whether to automatically attempt reconnection after an error. Set to false to disable automatic reconnection.

• auth: Authentication data to include during the connection initialization. Typically used for passing authentication tokens or credentials.

• query: Custom query parameters to include during the connection initialization. Useful for passing additional data, such as authentication tokens or user information.

Emitting Events

You can send events to the server using the emit method. For example:

socket.emit('message', payload);

Here, emit sends the message event with the provided payload to the server.

Overview

A Socket acts as an EventEmitter, enabling the sending and receiving of events between the client and server over the network.

Event Handling

You can listen for events using the on method. For example:

socket.on('eventName', (data) => {
  console.log('Event received:', data);
});

The on method registers a callback that will be fired when the specified eventName is triggered.

Built-in Events

The library comes with several built-in events that are essential for handling the connection lifecycle. These events cannot be overwritten. Here are the available built-in events:

• connect Triggered when the socket successfully connects to the server.

socket.on('connect', (payload) => {
  console.log('Connected:', payload);
});

• disconnect Triggered when the socket disconnects from the server, providing the disconnect code and reason.

socket.on('disconnect', (code, reason) => {
  console.log(`Disconnected with code ${code} due to: ${reason}`);
});

• error Triggered when an error occurs within the socket.

socket.on('error', (error) => {
  console.error('Socket error:', error);
});

• reconnect_attempt Triggered when the library attempts to reconnect after a disconnection.

socket.on('reconnect_attempt', (attempt) => {
  console.log(`Reconnect attempt #${attempt}`);
});

Features

Our library provides a robust set of features for seamless WebSocket communication. Here are some key features:

Separated Rooms

• Room Management: and manage separate rooms to organize communication channels. This allows for logical separation of messages and events between different groups or sessions.
• Join/Leave Rooms: Clients can join or leave rooms dynamically, ensuring that they only receive messages relevant to their specific group or context.
• Room-Specific Events: Emit and listen for events within specific rooms, allowing for targeted communication.

// Join a room
socket.emit('join', 'roomName');

// Leave a room
socket.emit('leave', 'roomName');

// Emit an event to a specific room
socket.emit('eventName', {...payload, roomName: "roomName"});

// Listen for events within a specific room
socket.on('eventName', (payload) => {
  console.log('Received in room:', payload);
});

Additional Features

Authentication and Authorization

• Secure Connections: Ensure that only authorized clients can connect by implementing authentication mechanisms.
• Token-Based Authentication: Support token-based authentication to manage access and permissions for different users or groups.

// Connect with authentication token
const socket = io("ws://127.0.0.1:5173", {
  auth: { token: 'your-authentication-token' }
});

Query Data Support

• Custom Query Parameters: Include custom query data when initializing the connection. This allows you to pass additional information during the connection handshake, such as authentication tokens, user IDs, or other contextual data.

// Initialize the connection with query parameters
const socket = io("ws://127.0.0.1:5173", {
  query: { example: 'exampleValue' }
});

The server can access these query parameters to handle specific logic

This feature provides flexibility in managing connections based on dynamic parameters, making it easier to customize the connection process to meet your application's needs.

This feature enhances the ability to pass custom data during the connection, which can be useful for a variety of scenarios, such as authentication or contextual configuration.

Donations and Sponsorships

If you find this library useful and want to support its ongoing development, you can contribute through donations or sponsorships. Your support helps me maintain and improve the library, add new features, and provide better support to the community.

How to Donate

You can make a donation via the following platforms:

• GitHub Sponsors: Support me directly through GitHub Sponsors. Contributions on GitHub help me fund development and cover project costs.

• Cryptocurrency: You can also support me through cryptocurrency. If you prefer to donate this way, you can use the following wallet addresses:

  • Binance Coin (BNB): 0x1E9890ac2f04F0B446D16ad1A26519c0a9535938 (BNB Chain network assets)
  • Bitcoin (BTCB): 0x1E9890ac2f04F0B446D16ad1A26519c0a9535938 (BNB Chain network assets)
  • Ethereum (ETH): 0x1E9890ac2f04F0B446D16ad1A26519c0a9535938 (BNB Chain network assets)

  Please make sure to include a note or reference that indicates your donation is for the library to help me track and acknowledge your support.

Sponsorship Opportunities

We also offer sponsorship opportunities for organizations and businesses interested in supporting our work. As a sponsor, you can benefit from:

• Prominent Recognition: Your company's name and logo will be featured on our GitHub repository and project website.
• Priority Support: Receive priority support and dedicated assistance for integrating and using the library.
• Custom Features: Request custom features or enhancements tailored to your organization's needs.

For more information about sponsorship opportunities and benefits, please contact me at [email protected]

Why Support Me?

Contributions and sponsorships help me to:

• Improve the Library: Develop new features, fix bugs, and enhance performance.
• Provide Better Support: Offer timely support and resolve issues more efficiently.
• Maintain the Project: Cover costs associated with hosting, development, and maintenance.

Thank you for considering supporting our project. Your contributions make a significant difference!