express-ws-easy

WebSocket Server Package

This package provides an easy and professional way to set up a WebSocket server integrated with an Express.js application. With this package, users can initialize and manage WebSocket connections, enabling real-time data communication in their applications.

Features

• Easy WebSocket server setup with an existing Express.js application.
• Handles WebSocket connections, messages, disconnections, and connection health checks via ping-pong.
• Allows sending notifications to individual clients, all clients, or broadcasting messages except for a specific client.
• Flexible, allowing the user to pass an instance of their Express app and port.
• Lightweight and designed to be integrated into any Express.js project.

Installation

To install the package via npm, run:

npm install express-ws-easy

Usage

To use this package in your project, follow the steps below.

1. Create an Express Application

First, you need to have an Express.js application where you'll integrate the WebSocket server.

Install Express.js if you haven’t:

npm install express

2. Set Up WebSocket with the Package

Create your Express.js app and integrate the WebSocket server from this package.

Example:

import express from 'express';
import { WebSocketApp } from 'express-ws-easy'; 

const app = express();
const port = 4000;

// Initialize WebSocket server by passing the Express app and port
const websocketApp = new WebSocketApp(app, port);

// Start the WebSocket and HTTP server
websocketApp.start();

// Express routes (optional) test the connection 
app.get('/', (req, res) => {
    res.send('WebSocket Server is running');
});

3. Notify Data via WebSocket

In your controller or any part of your application, you can notify WebSocket clients by sending data in real time. Here's an example of how to send a notification to all connected WebSocket clients:

import { websocketApp } from 'express-ws-easy';

// Notify all connected clients with user data
const userId = 123;
const data = { message: "Hello, WebSocket!" };

websocketApp.notifyData(userId, data);

4. Ping-Pong Mechanism for Connection Health

This package supports the ping-pong mechanism to ensure that WebSocket connections remain alive and healthy.

• The WebSocket server will periodically send ping messages to connected clients.
• Clients are expected to respond with pong messages.
• If the server does not receive a pong message within a certain timeout, it may assume the connection has dropped and close it.

This mechanism is crucial for keeping connections alive and detecting when clients have disconnected or become unresponsive.

5. Start the Server

To start your server with WebSocket enabled, run:

node index.js

API

new WebSocketApp(app, port)

• app: An instance of your Express app.
• port: The port number to run the WebSocket and HTTP server on.

Methods

.start()

Starts the HTTP server along with the WebSocket server.

.notifyData(userId, data)

Notifies a specific connected WebSocket client by sending them the userId and data.

• userId: The ID of the user to send data to.
• data: The data you want to send to the client.

.notifyDataToAllClients(data)

Sends a message to all connected WebSocket clients.

• data: The message or data to send to all clients.

.broadcastExcept(userId, data)

Broadcasts a message to all connected WebSocket clients except for the specified userId.

• userId: The ID of the user to exclude from the broadcast.
• data: The message or data to send to other clients.

.getAllConnectedClients()

Returns an array of all currently connected client userIds.

.pingAllClients()

Sends a ping message to all connected WebSocket clients to ensure connection health.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

### Key Additions:
- Added all new methods to the **API** section, including `notifyDataToAllClients`, `broadcastExcept`, `getAllConnectedClients`, and `pingAllClients`.
- Provided descriptions and examples for how to use each method effectively.

This README now covers all the new methods and functionalities added to the `Controller` class, giving users a complete guide on how to use your WebSocket server package.