@eleven-am/pondsocket 0.1.63 → 0.1.65

package/README.md

@@ -1,139 +1,303 @@
-
 # PondSocket
 
-PondSocket is a fast, minimalist and bidirectional socket framework for NodeJS. Pond allows you to think of each action during a sockets lifetime as a request instead of a huge callback that exists inside the connection event.
-## Documentation
+PondSocket is a high-performance, minimalist, and bidirectional socket framework designed for Node.js. It provides a seamless way to handle real-time communication between server and client applications, making it an ideal choice for building WebSocket-based projects.
+
+## Installation
 
-This is a Node.js module available through the npm registry.
+To integrate PondSocket into your Node.js project, simply install it via npm:
 
 ```bash
-  npm install @eleven-am/pondsocket
+npm install @eleven-am/pondsocket
 ```
 
-PondSocket usage depends on the environment in which it is being used.
-
-#### On the server
-
-When using PondSocket, an endpoint is created. The endpoint is the gateway by which sockets actually connect to the server.
-Multiple endpoints can be created but every endpoint is independent of the other, ie sockets on one endpoint cannot communicate with sockets on another endpoint.
-
-```js
-  import { PondSocket } from "@eleven-am/pondsocket";
-  
-  const pond = new PondSocket();
- 
-  const endpoint = pond.createEndpoint('/api/socket', (req, res, _endpoint) => {
-       const token = req.query.token;   
-       if (!token)         
-            return res.reject('No token provided');      
-       res.accept({
-            assign: {
-                token
-            }
-       });  
-  })
-```
+## Overview
+
+PondSocket simplifies the complexity of handling WebSocket connections by abstracting the communication process into individual requests rather than dealing with intricate callbacks within the connection event. It offers a lightweight yet powerful solution for managing bidirectional communication channels, enabling real-time updates and collaboration between server and client components.
+
+## Server-side Usage
+
+When setting up the server, PondSocket allows you to create multiple endpoints, each serving as a gateway for sockets to connect and communicate. Each endpoint operates independently, ensuring that sockets from one endpoint cannot interact with sockets from another. This isolation enhances security and simplifies resource management.
+
+```javascript
+import PondSocket from "@eleven-am/pondsocket";
+
+const pond = new PondSocket();
 
-While sockets connect through the endpoint, communication between sockets cannot occur on the endpoint level. Sockets have to join a channel to communicate
-between themselves.
-
-```js
-  const channel = endpoint.createChannel(/^channel(.*?)/, (req, res, channel) => {
-       const isAdmin = req.clientAssigns.admin;
-       if (!isAdmin)       
-            return res.reject('You are not an admin');
-
-       res.accept({
-           assign: {
-               admin: true, 
-               joinedDate: new Date()
-            }, 
-            presence: {
-                state: 'online'
-            }, 
-            channelData: {
-                locked: true,
-                numberOfUsers: channel.presence.length
-            }
-        });  
-   });   
+// Create an endpoint for handling socket connections
+const endpoint = pond.createEndpoint('/api/socket', (req, res) => {
+    // Handle socket connection and authentication
+});
 ```
 
-A user goes through the createChannel function to join a channel.
-When a user joins a channel, some private information can be assigned to the user. This assign could be viewed as a cookie that is only available serverside.
-The presence is the current state of the user. When you reassign a new presence information to a user, all other users connected to the same channel are informed of the change.
-This could be used as *user is typing*, *user is away*, etc. The channelData is information that is stored on the channel and accessible from anywhere the channel is available.
-It can be anything from a boolean to an instance of a class. This data cannot be accessed from another channel as it is private to the channel.
-
-```js
-    channel.on('hello', (req, res, channel) => {      
-       const users = channel.presence;      
-       res.assign({
-           assign: {
-               pingDate: new Date(),
-               users: users.length
-           }
-        }); 
-
-        // res.reject('curse words are not allowed on a child friendly channel') 
-        // channel.closeFromChannel(req.client.clientId);
-    })
+Within each endpoint, sockets interact through channels. Channels provide an organized way to group users and manage efficient communication among them. When users join a channel, they can participate in real-time events and exchange information with other users in the same channel.
+
+```javascript
+const channel = endpoint.createChannel('/channel/:id', (req, res) => {
+    // Handle channel-specific events and actions
+});
 ```
 
-When a message is sent on a channel by a user, an event is triggered. The *on* function can be used to listen for these events. If the function is specified, it is called when the message is received.
-You can choose to decline the message being sent, or you can allow the message to be sent as usual. You can also do all the normal assigns to the channel, or user.
-In case there is no *on* function, the message will be sent without any action being taken.
+## Client-side Usage
 
-#### On the browser
+On the client-side, PondSocket provides the PondClient class to establish connections with the server. Clients can easily initiate connections, join channels, and participate in real-time interactions.
 
-```js
-    import { PondClient } from "@eleven-am/pondsocket/client";
+```javascript
+import PondClient from "@eleven-am/pondsocket/client";
 
-    export const socket = new PondClient('/api/socket', {});
-    socket.connect();
+const socket = new PondClient('/api/socket', {});
+socket.connect();
 ```
 
-The browser compatible package can be imported from @eleven-am/pondsocket/client.
-AN url string is provided to the class along with other url params, like token.
+Once connected, clients can create and join channels to engage in real-time communication with other users and the server.
+
+```javascript
+const channel = socket.createChannel('/channel/123');
+channel.join();
+```
 
-Multiple classes can be created, but it is advised to use a single class throughout the application.
-You can just create multiple channels and maintain the single socket connection.
+### Node Client
 
-```js
-    const channelTopic = 'channel:one';
-    const options = {
-        username: 'eleven-am'
-    }
+PondSocket also offers a Node.js client, which can be imported using:
 
-    export const channel = socket.createChannel(channelTopic, options);
-    channel.join();
+```javascript
+import PondClient from "@eleven-am/pondsocket/node";
 ```
 
-When connected to the channel you can subscribe to the events from the channel.
+This node client allows you to turn another server into a client, enabling easy communication between different server instances.
 
-```js
-    const subscriptionPresence = channel.onPresenceUpdate(presence => {
-        // handle the presence changes of the channel
-    });
+## Key Features
 
-    const subscriptionMessage = channel.onMessage((event, data) => {
-        // handle the message being received 
-    });
+- **Simple and Efficient API**: PondSocket offers an easy-to-use API, making WebSocket communication straightforward and hassle-free.
+- **Organized Channels**: Channels provide a structured approach for grouping users and facilitating efficient communication.
+- **Assigns**: PondSocket allows the storage of private information for users and channels, enhancing data security.
+- **Presence**: The presence feature keeps track of users' current states and notifies other users about any changes.
+- **Broadcasting**: PondSocket enables broadcasting messages to all users or specific groups within a channel, facilitating real-time updates.
+- **Typed and Well-documented**: The codebase is thoroughly documented and typed, providing a seamless development experience with improved IDE suggestions.
 
-    // When done with the channel remember to unsubscribe from these listeners
-    subscriptionPresence.unsubscribe();
-    subscriptionMessage.unsubscribe();
-```
+## License
 
-There are many other features available on the channel object. Since the application is completely typed,
-suggestions should be provided by your IDE.
+PondSocket is released under the MIT License. Please refer to the `LICENSE` file for detailed licensing information.
 
-```js
-    channel.broadcast('hello', {
-        name: 'eleven-am',
-        message: 'I am the man, man'
-    })
+## API Documentation
 
-    // channel.broadcastFrom broadcasts a message to everyone but the client that emitted the message
-    // channel.sendMessage sends a message to clients specified in the function
-```
+Apologies for the confusion. Let me remove "Class" from the title of each section:
+
+### PondSocket
+
+The `PondSocket` class is the core class that represents the socket server.
+
+**Constructor:**
+
+- `constructor(server?: HTTPServer, socketServer?: WebSocketServer)`: Creates a new instance of the PondSocket with an optional HTTP server and WebSocket server.
+
+**Methods:**
+
+- `listen(...args: any[]): HTTPServer`: Specifies the port to listen on with the provided arguments.
+
+- `close(callback?: () => void): HTTPServer`: Closes the server, and an optional callback can be provided.
+
+- `createEndpoint<Path extends string>(path: PondPath<Path>, handler: (request: IncomingConnection<Path>, response: ConnectionResponse) => void | Promise<void>): Endpoint`: Accepts a new socket upgrade request on the provided endpoint using the handler function to authenticate the socket.
+
+### ConnectionResponse
+
+The `ConnectionResponse` class represents the response object for the incoming connection.
+
+**Methods:**
+
+- `accept(assigns?: PondAssigns): void`: Accepts the request and optionally assigns data to the client.
+
+- `reject(message?: string, errorCode?: number): void`: Rejects the request with the given error message and optional error code.
+
+- `send(event: string, payload: PondMessage, assigns?: PondAssigns): void`: Emits a direct message to the client with the specified event and payload.
+
+### Endpoint
+
+The `Endpoint` class represents an endpoint in the PondSocket server where channels can be created.
+
+**Methods:**
+
+- `createChannel<Path extends string>(path: PondPath<Path>, handler: (request: JoinRequest<Path>, response: JoinResponse) => void | Promise<void>): PondChannel`: Adds a new PondChannel to this path on this endpoint with the provided handler function to authenticate the client.
+
+- `broadcast(event: string, payload: PondMessage): void`: Broadcasts a message to all clients connected to this endpoint with the specified event and payload.
+
+- `closeConnection(clientIds: string | string[]): void`: Closes specific clients connected to this endpoint identified by the provided clientIds.
+
+### JoinRequest
+
+The `JoinRequest` class represents the request object when a client joins a channel.
+
+**Properties:**
+
+- `event: PondEvent<Path>`: The event associated with the request.
+
+- `channelName: string`: The name of the channel.
+
+- `assigns: UserAssigns`: The assigns data for the client.
+
+- `presence: UserPresences`: The presence data for the client.
+
+- `joinParams: JoinParams`: The join parameters for the client.
+
+- `user: UserData`: The user data associated with the client.
+
+- `client: Client`: The Client instance associated with the request.
+
+### JoinResponse
+
+The `JoinResponse` class represents the response object for the join request.
+
+**Methods:**
+
+- `accept(assigns?: PondAssigns): JoinResponse`: Accepts the join request and optionally assigns data to the client.
+
+- `reject(message?: string, errorCode?: number): JoinResponse`: Rejects the join request with the given error message and optional error code.
+
+- `send(event: string, payload: PondMessage, assigns?: PondAssigns): JoinResponse`: Emits a direct message to the client with the specified event, payload, and optional assigns data.
+
+- `broadcast(event: string, payload: PondMessage): JoinResponse`: Emits a message to all clients in the channel with the specified event and payload.
+
+- `broadcastFromUser(event: string, payload: PondMessage): JoinResponse`: Emits a message to all clients in the channel except the sender with the specified event and payload.
+
+- `sendToUsers(event: string, payload: PondMessage, userIds: string[]): JoinResponse`: Emits a message to a specific set of clients identified by the provided userIds with the specified event and payload.
+
+- `trackPresence(presence: PondPresence): JoinResponse`: Tracks the presence of the client in the channel.
+
+### PondChannel
+
+The `PondChannel` class represents a Generic channel in the PondSocket server. It is used to create a channel whose path matches the provided PondPath.
+
+**Methods:**
+
+- `onEvent<Event extends string>(event: PondPath<Event>, handler: (request: EventRequest<Event>, response: EventResponse) => void | Promise<void>): void`: Handles an event request made by a user for the specified event with the provided handler function.
+
+- `broadcast(event: string, payload: PondMessage, channelName?: string): void`: Broadcasts a message to all users in the channel with the specified event and payload. Optionally, a specific channel name can be provided to broadcast the message only to users in that channel.
+
+### EventRequest
+
+The `EventRequest` class represents the request object when an event is received from a client.
+
+**Properties:**
+
+- `event: PondEvent<Path>`: The event associated with the request.
+
+- `channelName: string`: The name of the channel.
+
+- `assigns: UserAssigns`: The assigns data for the client.
+
+- `presence: UserPresences`: The presence data for the client.
+
+- `user: UserData`: The user data associated with the client.
+
+- `client: Client`: The Client instance associated with the request.
+
+### EventResponse
+
+The `EventResponse` class represents the response object for handling events from clients.
+
+**Methods:**
+
+- `accept(assigns?: PondAssigns): EventResponse`: Accepts the request and optionally assigns data to the client.
+
+- `reject(message?: string, errorCode?: number, assigns?: PondAssigns): EventResponse`: Rejects the request with the given error message, optional error code, and optional assigns data.
+
+- `send(event: string, payload: PondMessage, assigns?: PondAssigns): void`: Emits a direct message to the client with the specified event, payload, and optional assigns data.
+
+- `broadcast(event: string, payload: PondMessage): EventResponse`: Sends a message to all clients in the channel with the specified event and payload.
+
+- `broadcastFromUser(event: string, payload: PondMessage): EventResponse`: Sends a message to all clients in the channel except the sender with the specified event and payload.
+
+- `sendToUsers(event: string, payload: PondMessage, userIds: string[]): EventResponse`: Sends
+
+a message to a specific set of clients identified by the provided userIds with the specified event and payload.
+
+- `trackPresence(presence: PondPresence, userId?: string): EventResponse`: Tracks a user's presence in the channel.
+
+- `updatePresence(presence: PondPresence, userId?: string): EventResponse`: Updates a user's presence in the channel.
+
+- `unTrackPresence(userId?: string): EventResponse`: Removes a user's presence from the channel.
+
+- `evictUser(reason: string, userId?: string): void`: Evicts a user from the channel.
+
+- `closeChannel(reason: string): void`: Closes the channel from the server-side for all clients.
+
+### Client
+
+The `Client` class represents a single Channel created by the PondSocket server. Note that a PondChannel can have multiple clients.
+
+**Methods:**
+
+- `getAssigns: UserAssigns`: Gets the current assign data for the client.
+
+- `getUserData(userId: string): UserData`: Gets the assign data for a specific user identified by the provided `userId`.
+
+- `broadcastMessage(event: string, payload: PondMessage): void`: Broadcasts a message to every client in the channel with the specified event and payload.
+
+- `sendToUser(userId: string, event: string, payload: PondMessage): void`: Sends a message to a specific client in the channel identified by the provided `userId`, with the specified event and payload.
+
+- `banUser(userId: string, reason?: string): void`: Bans a user from the channel identified by the provided `userId`. Optionally, you can provide a `reason` for the ban.
+
+- `trackPresence(userId: string, presence: PondPresence): void`: Tracks a user's presence in the channel identified by the provided `userId`.
+
+- `removePresence(userId: string): void`: Removes a user's presence from the channel identified by the provided `userId`.
+
+- `updatePresence(userId: string, presence: PondPresence): void`: Updates a user's presence in the channel identified by the provided `userId`.
+
+### PondClient
+
+The `PondClient` class represents a client that connects to the PondSocket server.
+
+**Constructor:**
+
+- `constructor(endpoint: string, params?: Record<string, any>)`: Creates a new instance of the PondClient with the provided endpoint URL and optional parameters.
+
+**Methods:**
+
+- `connect(backoff?: number): void`: Connects to the server with an optional backoff time.
+
+- `getState(): boolean`: Returns the current state of the socket.
+
+- `disconnect(): void`: Disconnects the socket.
+
+- `createChannel(name: string, params?: JoinParams): Channel`: Creates a channel with the given name and optional join parameters.
+
+- `onConnectionChange(callback: (state: boolean) => void): Unsubscribe`: Subscribes to the connection state changes and calls the provided callback when the state changes.
+
+### Channel
+
+The `Channel` class represents a channel in the PondSocket server.
+
+**Methods:**
+
+- `join(): void`: Connects to the channel.
+
+- `leave(): void`: Disconnects from the channel.
+
+- `onMessage(callback: (event: string, message: PondMessage) => void): Unsubscribe`: Monitors the channel for messages and calls the provided callback when a message is received.
+
+- `onMessageEvent(event: string, callback: (message: PondMessage) => void): Unsubscribe`: Monitors the channel for messages with the specified event and calls the provided callback when a message is received.
+
+- `onChannelStateChange(callback: (connected: ChannelState) => void): Unsubscribe`: Monitors the channel state of the channel and calls the provided callback when the connection state changes.
+
+- `onJoin(callback: (presence: PondPresence) => void): Unsubscribe`: Detects when clients join the channel and calls the provided callback when a client joins the channel.
+
+- `onLeave(callback: (presence: PondPresence) => void): Unsubscribe`: Detects when clients leave the channel and calls the provided callback when a client leaves the channel.
+
+- `onPresenceChange(callback: (presence: PresencePayload) => void): Unsubscribe`: Detects when clients change their presence in the channel and calls the provided callback when a client changes their presence in the channel.
+
+- `sendMessage(event: string, payload: PondMessage, recipient: string[]): void`: Sends a message to specific clients in the channel with the specified event, payload, and recipient.
+
+- `broadcastFrom(event: string, payload: PondMessage): void`: Broadcasts a message to every other client in the channel except yourself with the specified event and payload.
+
+- `broadcast(event: string, payload: PondMessage): void`: Broadcasts a message to the channel, including yourself, with the specified event and payload.
+
+- `getPresence(): PondPresence[]`: Gets the current presence of the channel.
+
+- `onUsersChange(callback: (users: PondPresence[]) => void): Unsubscribe`: Monitors the presence of the channel and calls the provided callback when the presence changes.
+
+- `isConnected(): boolean`: Gets the current connection state of the channel.
+
+- `onConnectionChange(callback: (connected: boolean) => void): Unsubscribe`: Monitors the connection state of the channel and calls the provided callback when the connection state changes.
+
+## Conclusion
+
+PondSocket is a powerful and versatile solution for building real-time applications that require efficient bidirectional communication between server and client components. Its minimalist design and comprehensive feature set make it an excellent choice for WebSocket-based projects, providing developers with a straightforward and reliable tool for building real-time communication systems. With the Node.js client, it also allows for easy communication between multiple server instances, expanding its capabilities even further.

package/client.js

@@ -95,7 +95,6 @@ class PondClient {
         return this._connectionState.subscribe(callback);
     }
 }
-exports.default = PondClient;
 _PondClient_channels = new WeakMap(), _PondClient_instances = new WeakSet(), _PondClient_createPublisher = function _PondClient_createPublisher() {
     return (message) => {
         if (this._connectionState.value) {
@@ -103,3 +102,4 @@ _PondClient_channels = new WeakMap(), _PondClient_instances = new WeakSet(), _Po
         }
     };
 };
+exports.default = PondClient;

package/enums.js

@@ -6,20 +6,20 @@ var PresenceEventTypes;
     PresenceEventTypes["JOIN"] = "JOIN";
     PresenceEventTypes["LEAVE"] = "LEAVE";
     PresenceEventTypes["UPDATE"] = "UPDATE";
-})(PresenceEventTypes = exports.PresenceEventTypes || (exports.PresenceEventTypes = {}));
+})(PresenceEventTypes || (exports.PresenceEventTypes = PresenceEventTypes = {}));
 var ServerActions;
 (function (ServerActions) {
     ServerActions["PRESENCE"] = "PRESENCE";
     ServerActions["SYSTEM"] = "SYSTEM";
     ServerActions["BROADCAST"] = "BROADCAST";
     ServerActions["ERROR"] = "ERROR";
-})(ServerActions = exports.ServerActions || (exports.ServerActions = {}));
+})(ServerActions || (exports.ServerActions = ServerActions = {}));
 var ClientActions;
 (function (ClientActions) {
     ClientActions["JOIN_CHANNEL"] = "JOIN_CHANNEL";
     ClientActions["LEAVE_CHANNEL"] = "LEAVE_CHANNEL";
     ClientActions["BROADCAST"] = "BROADCAST";
-})(ClientActions = exports.ClientActions || (exports.ClientActions = {}));
+})(ClientActions || (exports.ClientActions = ClientActions = {}));
 var ChannelState;
 (function (ChannelState) {
     ChannelState["IDLE"] = "IDLE";
@@ -27,7 +27,7 @@ var ChannelState;
     ChannelState["JOINED"] = "JOINED";
     ChannelState["STALLED"] = "STALLED";
     ChannelState["CLOSED"] = "CLOSED";
-})(ChannelState = exports.ChannelState || (exports.ChannelState = {}));
+})(ChannelState || (exports.ChannelState = ChannelState = {}));
 var ErrorTypes;
 (function (ErrorTypes) {
     ErrorTypes["UNAUTHORIZED_CONNECTION"] = "UNAUTHORIZED_CONNECTION";
@@ -39,18 +39,18 @@ var ErrorTypes;
     ErrorTypes["CHANNEL_ERROR"] = "CHANNEL_ERROR";
     ErrorTypes["ENDPOINT_ERROR"] = "ENDPOINT_ERROR";
     ErrorTypes["INTERNAL_SERVER_ERROR"] = "INTERNAL_SERVER_ERROR";
-})(ErrorTypes = exports.ErrorTypes || (exports.ErrorTypes = {}));
+})(ErrorTypes || (exports.ErrorTypes = ErrorTypes = {}));
 var SystemSender;
 (function (SystemSender) {
     SystemSender["ENDPOINT"] = "ENDPOINT";
     SystemSender["CHANNEL"] = "CHANNEL";
-})(SystemSender = exports.SystemSender || (exports.SystemSender = {}));
+})(SystemSender || (exports.SystemSender = SystemSender = {}));
 var ChannelReceiver;
 (function (ChannelReceiver) {
     ChannelReceiver["ALL_USERS"] = "ALL_USERS";
     ChannelReceiver["ALL_EXCEPT_SENDER"] = "ALL_EXCEPT_SENDER";
-})(ChannelReceiver = exports.ChannelReceiver || (exports.ChannelReceiver = {}));
+})(ChannelReceiver || (exports.ChannelReceiver = ChannelReceiver = {}));
 var Events;
 (function (Events) {
     Events["ACKNOWLEDGE"] = "ACKNOWLEDGE";
-})(Events = exports.Events || (exports.Events = {}));
+})(Events || (exports.Events = Events = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/pondsocket",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "PondSocket is a fast simple socket server",
   "keywords": [
     "socket",
@@ -22,30 +22,30 @@
   },
   "author": "Roy OSSAI",
   "license": "GPL-3.0",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Eleven-am/pondSocket.git"
   },
   "dependencies": {
     "websocket": "^1.0.34",
-    "ws": "^8.12.0"
+    "ws": "^8.13.0"
   },
   "devDependencies": {
-    "@types/express": "^4.17.14",
-    "@types/jest": "^29.5.0",
-    "@types/node": "^16.10.3",
+    "@types/express": "^4.17.17",
+    "@types/jest": "^29.5.3",
+    "@types/node": "^20.4.4",
     "@types/websocket": "^1.0.5",
-    "@types/ws": "^8.5.3",
-    "@typescript-eslint/eslint-plugin": "^5.58.0",
-    "eslint": "^8.38.0",
+    "@types/ws": "^8.5.5",
+    "@typescript-eslint/eslint-plugin": "^6.1.0",
+    "eslint": "^8.45.0",
     "eslint-plugin-file-progress": "^1.3.0",
     "eslint-plugin-import": "^2.27.5",
-    "jest": "^29.0.1",
+    "jest": "^29.6.1",
     "superwstest": "^2.0.3",
-    "ts-jest": "^29.1.0",
+    "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",
-    "typescript": "^4.9.4"
+    "typescript": "^5.1.6"
   }
 }