playsocketjs 2.5.1 → 2.5.3

package/dist/{playsocket-server.mjs → playsocket-server.js}

@@ -1,5 +1,5 @@
 import { WebSocketServer } from 'ws';
-import * as http from 'node:http';
+import { createServer } from 'node:http';
 
 function utf8Count(str) {
     const strLength = str.length;
@@ -1686,13 +1686,15 @@ function decode(buffer, options) {
 
 const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
 
+/**
+ * CRDT Manager
+ */
 class CRDTManager {
     // Storage
     #replicaId;
     #keyOperations = new Map();
     #vectorClock = new Map();
 
-    // Local only
     #propertyStore = {}; // Current local values per key, as object
     #lastPropertyStore = {}; // Last property store to compare against
 
@@ -1705,6 +1707,7 @@ class CRDTManager {
 
     /**
      * Create a new instance
+     * @param {boolean} [debug=false] - Enable debug logging
      */
     constructor(debug) {
         if (debug) this.#debug = true;
@@ -1714,7 +1717,7 @@ class CRDTManager {
 
     /**
      * Import the entire state of the CRDT manager (this overwrites the old state)
-     * @param {Object} state
+     * @param {object} state - Full state of the CRDT manager
      */
     importState(state) {
         try {
@@ -1731,7 +1734,7 @@ class CRDTManager {
             if (!this.#vectorClock.has(this.#replicaId)) this.#vectorClock.set(this.#replicaId, 0); // Add own vector clock if it wasn't present in the imported state
 
             // Map all operation uuids to current timestamp
-            this.#keyOperations.forEach((value, key) => {
+            this.#keyOperations.forEach((value, _key) => {
                 value?.forEach((operation) => {
                     this.#opUuidTimestamp.set(operation?.uuid, Date.now());
                 });
@@ -1747,7 +1750,7 @@ class CRDTManager {
 
     /**
      * Import property update
-     * @param {Object} data - Data to import
+     * @param {object} data - Property update data
      */
     importPropertyUpdate(data) {
         try {
@@ -1789,11 +1792,11 @@ class CRDTManager {
 
     /**
      * Update a property
-     * @param {string} key 
-     * @param {string} type 
-     * @param {*} value 
-     * @param {*} updateValue 
-     * @returns {Object} - Returns the property update
+     * @param {string} key - Storage key
+     * @param {string} type - Operation type
+     * @param {*} value - New value, or value to match
+     * @param {*} updateValue - New value for 'matching' operations
+     * @returns {object | undefined} - Returns the property update
      */
     updateProperty(key, type, value, updateValue) {
         try {
@@ -1830,6 +1833,9 @@ class CRDTManager {
         }
     }
 
+    /**
+     * Check if garbage collected can be performed & run it
+     */
     #checkGarbageCollection() {
         const MIN_GC_DELAY = 1000; // Minimum 1s delay between garbage collection runs
         const MIN_AGE_FOR_GC = 5000; // Garbage collect ops that are older than 5s
@@ -1855,7 +1861,7 @@ class CRDTManager {
                     if (this.#debug) console.log(CONSOLE_PREFIX + `Running garbage collection for key ${key} with current operations:`, operations);
                     const retainOps = operations.slice(-retainCount); // Newest ops
                     const removeOps = operations.slice(0, -retainCount); // Oldest ops (start =  idx 0, end = retainCount counted from right side)
-                    const baselineVectorClock = removeOps[removeOps.length - 1]?.vectorClock || []; // Use the vector clock from the last operation that we remove/overwrite 
+                    const baselineVectorClock = removeOps[removeOps.length - 1]?.vectorClock || []; // Use the vector clock from the last operation that we remove/overwrite
 
                     // Calculate the value at the point where retained operations start
                     let baselineValue = null;
@@ -1886,9 +1892,9 @@ class CRDTManager {
 
     /**
      * Create an operation object
-     * @param {Object} data 
-     * @param {Array} vectorClock 
-     * @returns {Object} - Operation object
+     * @param {object} data - Operation data, consists of type, value and updateValue
+     * @param {Array} vectorClock - Vector clock of the replica/client
+     * @returns {object} - Operation object
      */
     #createOperation(data, vectorClock) {
         const newOperation = {
@@ -1903,7 +1909,7 @@ class CRDTManager {
 
     /**
      * Process a property's value by applying all operations and set it in the property store
-     * @param {string} key 
+     * @param {string} key - Storage key
      */
     #processLocalProperty(key) {
         try {
@@ -1930,8 +1936,8 @@ class CRDTManager {
     }
 
     /**
-     * Sort by vector clock (causal order)
-     * @param {Array} operations
+     * Sort operations by vector clock (causal order)
+     * @param {Array} operations - Full operations that include vector clocks, data and a source
      * @returns {Array} - Sorted operations
      */
     #sortByVectorClock(operations) {
@@ -1967,10 +1973,10 @@ class CRDTManager {
 
     /**
      * Handle an operation
-     * @param {*} curValue 
-     * @param {string} type 
-     * @param {*} value 
-     * @param {*} [updateValue]
+     * @param {*} curValue - Current value of the storage key
+     * @param {string} type - Operation type
+     * @param {*} value - New value, or value to match
+     * @param {*} [updateValue] - New value for 'matching' operations
      * @returns {*} - Value after the operation
      */
     #handleOperation(curValue, type, value, updateValue) {
@@ -2002,10 +2008,11 @@ class CRDTManager {
                     case 'array-remove-matching':
                         curValue = curValue.filter(item => !compare(item));
                         break;
-                    case 'array-update-matching':
+                    case 'array-update-matching': {
                         const index = curValue.findIndex(compare);
                         if (index !== -1) curValue[index] = updateValue;
                         break;
+                    }
                 }
             }
 
@@ -2019,42 +2026,53 @@ class CRDTManager {
 
     /**
      * Remove HTML to prevent XSS and enforce size limits
-     * @param {Object} obj
-     * @returns {Object} - Sanitized object
+     * @param {*} value - Value to sanitize
+     * @returns {*} - Sanitized value
      */
-    #sanitizeValue(obj) {
+    #sanitizeValue(value) {
         // Check total serialized size
-        const jsonString = JSON.stringify(obj);
+        const jsonString = JSON.stringify(value);
         if (jsonString?.length > 50000) throw new Error('Value too large!'); // 50KB limit
 
-        if (typeof obj === 'string') return (obj.includes('<') || obj.includes('>')) ? obj.replace(/[<>]/g, '') : obj;
-        if (Array.isArray(obj)) return obj.map(item => this.#sanitizeValue(item));
-        if (obj && typeof obj === 'object') return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, this.#sanitizeValue(v)]));
-        return obj;
+        if (typeof value === 'string') return (value.includes('<') || value.includes('>')) ? value.replace(/[<>]/g, '') : value;
+        if (Array.isArray(value)) return value.map(item => this.#sanitizeValue(item));
+        if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.#sanitizeValue(v)]));
+        return value;
     }
 
-    // Get property store
+    /**
+     * Get property store
+     * @returns {Record<string, any>} - Object with key value pairs
+     */
     get getPropertyStore() {
         try {
             return structuredClone(this.#propertyStore); // Return deep clone
         } catch {
             console.error(CONSOLE_PREFIX + "Failed to parse property store");
-            return {};
+            return {}
         }
     }
 
-    // Check for changes in the local property store
+    /**
+     * Check for changes in the local property store
+     * @returns {boolean} - Check if any values changed going from the last to the current property update
+     */
     get didPropertiesChange() {
         try {
             if (JSON.stringify(this.#propertyStore) !== JSON.stringify(this.#lastPropertyStore)) {
                 this.#lastPropertyStore = structuredClone(this.#propertyStore);
                 return true;
             }
-        } catch { }
+        } catch {
+            console.error(CONSOLE_PREFIX + "Failed to stringify and compare property stores");
+        }
         return false;
     }
 
-    // Get state (can be imported using importState, converts the maps to arrays for serialization)
+    /**
+     * Export state (can be imported using importState, converts the maps to arrays for serialization)
+     * @returns {object} - State
+     */
     get getState() {
         return {
             keyOperations: [...this.#keyOperations.entries()],
@@ -2063,8 +2081,15 @@ class CRDTManager {
     }
 }
 
+/* eslint-disable jsdoc/require-returns */
+
+/**
+ * @typedef {import('node:http').Server} HttpServer
+ * @typedef {import('ws').WebSocket} WebSocket
+ */
+
 /**
- * PlaySocketServer - WebSocket server for PlaySocket multiplayer library
+ * PlaySocket Server
  */
 class PlaySocketServer {
     #server;
@@ -2086,10 +2111,12 @@ class PlaySocketServer {
 
     /**
      * Create a new PlaySocketServer instance
-     * @param {Object} options - Server configuration options
+     * @param {object} options - Server configuration options
      * @param {HttpServer} [options.server] - Existing http server
      * @param {number} [options.port=3000] - Port to listen on (if no server provided)
-     * @param {string} [options.path='/socket'] - WebSocket endpoint path
+     * @param {string} [options.path='/'] - WebSocket endpoint path
+     * @param {boolean} [options.debug=false] - Enable debug logging
+     * @param {number} [options.rateLimit=20] - Maximum number of operations per second per client
      */
     constructor(options = {}) {
         const { server, port = 3000, path = '/', debug = false, rateLimit = 20 } = options;
@@ -2103,7 +2130,7 @@ class PlaySocketServer {
             this.#server = server; // Use provided HTTP server
         } else {
             this.#ownsServer = true;
-            this.#server = http.createServer(); // Create HTTP server and start it
+            this.#server = createServer(); // Create HTTP server and start it
             this.#server.listen(port, () => {
                 console.log(`PlaySocket server running on port ${port}.`);
             });
@@ -2144,6 +2171,8 @@ class PlaySocketServer {
 
     /**
      * Handle WebSocket message
+     * @param {WebSocket} ws - WebSocket client
+     * @param {Buffer} message - Message encoded with messagepack
      * @private
      */
     async #handleMessage(ws, message) {
@@ -2156,12 +2185,13 @@ class PlaySocketServer {
                 if (!ws.isTerminating) {
                     ws.isTerminating = true; // Prevent multiple terminate calls (it is async)
                     ws.terminate();
-                    return console.error(`Connection ${ws.connectionId} terminated due to rate limit violations.`);
+                    console.error(`Connection ${ws.connectionId} terminated due to rate limit violations.`);
+                    return;
                 }
             }
 
             switch (data.type) {
-                case 'register':
+                case 'register': {
                     // Register client ID if provided & check for a duplicate
                     if (data.id && this.#clients.get(data.id)) {
                         ws.send(encode({ type: 'registration_failed', reason: 'ID is taken.' }), { binary: true });
@@ -2200,8 +2230,9 @@ class PlaySocketServer {
                     ws.send(encode({ type: 'registered', id: data.id, sessionToken }), { binary: true });
                     this.#triggerEvent("clientRegistered", data.id, data.customData);
                     break;
+                }
 
-                case 'reconnect':
+                case 'reconnect': {
                     // If user is pending disconnect, respond (otherwise it's too late)
                     const pd = this.#pendingDisconnects.get(data.id);
                     if (pd && data.sessionToken) {
@@ -2238,8 +2269,9 @@ class PlaySocketServer {
                         ws.send(encode({ type: 'reconnection_failed', reason: "Client unknown to server." }), { binary: true });
                     }
                     break;
+                }
 
-                case 'create_room':
+                case 'create_room': {
                     if (!ws.clientId) return;
 
                     let newRoomId;
@@ -2307,8 +2339,9 @@ class PlaySocketServer {
                     this.#triggerEvent("roomCreated", newRoomId);
                     if (this.#debug) console.log(`Room ${newRoomId} created with initial storage:`, data.initialStorage);
                     break;
+                }
 
-                case 'join_room':
+                case 'join_room': {
                     if (!data.roomId || !ws.clientId) return;
                     const roomId = data.roomId;
                     const room = this.#rooms[roomId];
@@ -2352,29 +2385,30 @@ class PlaySocketServer {
                     });
                     this.#triggerEvent("clientJoinedRoom", ws.clientId, roomId);
                     break;
+                }
 
-                case 'update_property':
-                    const updateRoomId = this.#clientRooms.get(ws.clientId);
-                    const updateRoom = updateRoomId ? this.#rooms[updateRoomId] : null;
+                case 'update_property': {
+                    const roomId = this.#clientRooms.get(ws.clientId);
+                    const room = roomId ? this.#rooms[roomId] : null;
 
-                    if (updateRoom && data.update) {
+                    if (room && data.update) {
                         // Check if update is allowed via event callback (provide clone to ensure update integrity)
-                        const updateAllowed = await this.#triggerEvent("storageUpdateRequested", { roomId: updateRoomId, clientId: ws.clientId, update: structuredClone(data.update) });
+                        const updateAllowed = await this.#triggerEvent("storageUpdateRequested", { roomId, clientId: ws.clientId, update: structuredClone(data.update) });
                         if (updateAllowed === false) {
                             ws.send(encode({
                                 type: 'property_update_rejected',
-                                state: updateRoom.crdtManager.getState
+                                state: room.crdtManager.getState
                             }), { binary: true });
                             return;
                         }
 
-                        updateRoom.crdtManager.importPropertyUpdate(data.update); // Import update into server state
+                        room.crdtManager.importPropertyUpdate(data.update); // Import update into server state
 
                         // Increment version for this room
-                        const currentVersion = this.#roomVersions.get(updateRoomId) + 1;
-                        this.#roomVersions.set(updateRoomId, currentVersion);
+                        const currentVersion = this.#roomVersions.get(roomId) + 1;
+                        this.#roomVersions.set(roomId, currentVersion);
 
-                        updateRoom.participants?.forEach(p => {
+                        room.participants?.forEach(p => {
                             const client = this.#clients.get(p);
                             if (client) {
                                 client.send(encode({
@@ -2385,16 +2419,18 @@ class PlaySocketServer {
                             }
                         });
 
-                        this.#triggerEvent("storageUpdated", { roomId: updateRoomId, clientId: ws.clientId, update: structuredClone(data.update), storage: this.getRoomStorage(updateRoomId) });
+                        this.#triggerEvent("storageUpdated", { roomId, clientId: ws.clientId, update: structuredClone(data.update), storage: this.getRoomStorage(roomId) });
                         if (this.#debug) console.log("Property update received and imported:", data.update);
                     }
                     break;
+                }
 
-                case 'request':
+                case 'request': {
                     if (!ws.clientId) return;
-                    const requestorRoomId = this.#clientRooms.get(ws.clientId) || null;
-                    this.#triggerEvent("requestReceived", { roomId: requestorRoomId, clientId: ws.clientId, name: data.request.name, data: data.request.data });
+                    const roomId = this.#clientRooms.get(ws.clientId) || null;
+                    this.#triggerEvent("requestReceived", { roomId, clientId: ws.clientId, name: data.request.name, data: data.request.data });
                     break;
+                }
 
                 case 'disconnect':
                     // Client signals to server that it will will willfully disconnect soon
@@ -2408,6 +2444,7 @@ class PlaySocketServer {
 
     /**
      * Generate a readable, 6 digit ID
+     * @returns {string} - Id
      */
     #generateId() {
         const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789';
@@ -2417,8 +2454,8 @@ class PlaySocketServer {
     /**
      * If the client that disconnected (and is now in the reconnection-phase) was the room host,
      * pick a new room host immediately to avoid host-less phase (in case important logic is attached to the host)
-     * @param {string} roomId
-     * @param {string} clientId
+     * @param {string} roomId - ID of the room that the disconnected client was in
+     * @param {string} clientId - ID of the disconnected client
      */
     #changeHostIfDisconnected(roomId, clientId) {
         const room = this.#rooms[roomId];
@@ -2449,9 +2486,12 @@ class PlaySocketServer {
 
     /**
      * Check rate limit using token bucket algorithm
+     * @param {string} connectionId - Random connection UUID which is different from the client ID
+     * @param {string} actionType - A string describing the action
+     * @returns {boolean} - Whether or not the action can be allowed, true means allowed, false means limited
      * @private
      */
-    #checkRateLimit(connectionId, operationType) {
+    #checkRateLimit(connectionId, actionType) {
         const now = Date.now();
 
         if (!this.#rateLimits.has(connectionId)) {
@@ -2467,7 +2507,7 @@ class PlaySocketServer {
             limit.lastReset = now;
         }
 
-        const pointCost = operationType == "create_room" ? 5 : 1;
+        const pointCost = actionType == "create_room" ? 5 : 1;
         if (limit.points < pointCost) return false;
 
         limit.points -= pointCost;
@@ -2476,6 +2516,7 @@ class PlaySocketServer {
 
     /**
      * Handle client disconnection
+     * @param {WebSocket} ws - WebSocket client
      * @private
      */
     #handleDisconnection(ws) {
@@ -2504,7 +2545,7 @@ class PlaySocketServer {
     /**
      * Disconnect a client
      * @private
-     * @param {Object} ws 
+     * @param {WebSocket} ws - WebSocket client
      */
     #disconnectClient(ws) {
         this.#pendingDisconnects.delete(ws.clientId);
@@ -2545,8 +2586,10 @@ class PlaySocketServer {
      */
     onEvent(event, callback) {
         const validEvents = ["clientRegistered", "clientRegistrationRequested", "clientDisconnected", "clientJoinedRoom", "clientJoinRequested", "roomCreated", "roomCreationRequested", "requestReceived", "storageUpdated", "storageUpdateRequested", "roomDestroyed"];
-        if (!validEvents.includes(event)) return console.warn(`Invalid PlaySocket event type "${event}"`);
-        if (!this.#callbacks.has(event)) this.#callbacks.set(event, []);
+        if (!validEvents.includes(event)) {
+            console.warn(`Invalid PlaySocket event type "${event}"`);
+            return;
+        }        if (!this.#callbacks.has(event)) this.#callbacks.set(event, []);
         this.#callbacks.get(event).push(callback);
     }
 
@@ -2566,6 +2609,9 @@ class PlaySocketServer {
 
     /**
      * Trigger an event to registered callbacks
+     * @param {string} event - Event name
+     * @param {...*} args - Arguments
+     * @returns {any} - Undefined if no callbacks, true if all callbacks ran, what the first callback with a return statement returns if present
      * @private
      */
     async #triggerEvent(event, ...args) {
@@ -2585,7 +2631,8 @@ class PlaySocketServer {
 
     /**
      * Get snapshot of a room's storage
-     * @returns {Object} - Storage object
+     * @param {string} roomId - ID of the room to get the storage from
+     * @returns {object|undefined} - Storage object or undefined if the room doesn't exist
      */
     getRoomStorage(roomId) {
         const room = this.#rooms[roomId];
@@ -2596,7 +2643,7 @@ class PlaySocketServer {
      * Update a value in a room's storage
      * @param {string} roomId - Room ID
      * @param {string} key - Storage key
-     * @param {string} type - Operation type
+     * @param {'set' | 'array-add' | 'array-add-unique' | 'array-remove-matching' | 'array-update-matching'} type - Operation type
      * @param {*} value - New value or value to operate on
      * @param {*} updateValue - New value for update-matching
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playsocketjs",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
   "type": "module",
   "module": "dist/playsocket-client.js",
@@ -9,18 +9,17 @@
       "import": "./dist/playsocket-client.js"
     },
     "./server": {
-      "import": "./dist/playsocket-server.mjs",
-      "require": "./dist/playsocket-server.cjs"
+      "import": "./dist/playsocket-server.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "start": "node example/example-server.cjs",
-    "start-module": "node example/example-server.mjs",
+    "start": "node example/example-server.js",
     "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "rollup -c rollup.config.mjs"
+    "build": "rollup -c rollup.config.js",
+    "lint": "eslint ./src"
   },
   "repository": {
     "type": "git",
@@ -28,11 +27,10 @@
   },
   "keywords": [
     "WebSocket",
-    "data channel",
+    "Data channel",
     "Socket",
-    "PlayPeerJS",
-    "multiplayer",
-    "game"
+    "Multiplayer",
+    "Game"
   ],
   "author": "PaulPlay",
   "license": "MIT",
@@ -41,9 +39,11 @@
   },
   "homepage": "https://github.com/therealPaulPlay/PlaySocketJS#readme",
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^28.0.2",
     "@rollup/plugin-node-resolve": "^16.0.0",
-    "rollup": "^4.31.0"
+    "eslint": "^9.35.0",
+    "eslint-plugin-jsdoc": "^54.4.0",
+    "rollup": "^4.31.0",
+    "globals": "^16.3.0"
   },
   "peerDependencies": {
     "ws": "^8.18.1"