playsocketjs 2.5.2 → 2.5.4

package/README.md

@@ -99,7 +99,7 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 - `createRoom(initialStorage?: object, maxSize?: number)`: Create a new room and become host – Returns Promise (async) which resolves with the room ID. The room participant maximum is 100
 - `joinRoom(hostId: string)`: Join an existing room – Returns Promise (async)
 - `destroy()`: Use this to leave a room and close the connection
-- `updateStorage(key: string, type: 'set' | 'array-add' | 'array-add-unique' | 'array-remove-matching' | 'array-update-matching', value: any, updateValue?: any)`: Update the shared storage (max. 100 keys). Safely update arrays in storage by adding, removing, or updating items. UpdateValue is only required for the 'array-update-matching' operation type
+- `updateStorage(key: string, type: 'set' | 'array-add' | 'array-add-unique' | 'array-remove-matching' | 'array-update-matching', value: any, updateValue?: any)`: Update a key in the shared storage (max. 100 keys). Array operation types allow for conflict-free simultaneous array updates. For '-matching' operations, value becomes the value to match, and updateValue the replacement. 
 - `sendRequest(name: string, data?: any)`: Send requests to the server with optional custom data (handle these in the `requestReceived` server event)
 - `onEvent(event: string, callback: Function)`: Register an event callback
 
@@ -212,7 +212,7 @@ Creates a new PlaySocket Server instance with configuration options.
 - `kick(clientId: string, reason?: string)`: Kick a client by their clientID – this will close their connection and set an error message
 - `onEvent(event: string, callback: Function)`: Register a server-side event callback
 - `getRoomStorage(roomId: string)`: Get a snapshot of the current room storage (returns storage `object`)
-- `updateRoomStorage(roomId: string, key: string, type: 'set' | 'array-add' | 'array-add-unique' | 'array-remove-matching' | 'array-update-matching', value: any, updateValue?: any)`: Update the shared room storage from the server.
+- `updateRoomStorage(roomId: string, key: string, type: 'set' | 'array-add' | 'array-add-unique' | 'array-remove-matching' | 'array-update-matching', value: any, updateValue?: any)`: Update a key in the shared room storage from the server.
 
 #### Event types
 
@@ -225,7 +225,7 @@ Creates a new PlaySocket Server instance with configuration options.
 - `roomDestroyed`: Room was destroyed, this happens when all participants leave (returns room ID `string`)
 - `roomCreationRequested`: Room creation requested by client (returns `object` containing the client's ID `string`, room ID `string` and the initialStorage `object`) – if you return an `object` in the callback, it will take that as the initial storage instead. If you return `false`, the creation will be denied
 - `storageUpdated`: Room storage property updated (returns `object` containing the ID of the client who requested the update `string`, room ID `string`, the update `object`, and the storage `object`)
-- `storageUpdateRequested`: Room storage property update requested by client (returns `object` containing the client's ID `string`, room ID `string` and the update `object`) – if you return `false` in the callback, the update will be blocked
+- `storageUpdateRequested`: Room storage property update requested by client (returns `object` containing the client's ID `string`, room ID `string`, the update `object`, and the current storage `object` that hasn't been updated yet) – if you return `false` in the callback, the update will be blocked
 - `requestReceived`: Request from client was received by the server (returns `object` containing client's ID `string`, if in room – room ID `string`, request name `string` and optional passed data of type `any`)
 
 ### Properties (Read-only)

package/dist/playsocket-client.js

@@ -1683,13 +1683,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
 
@@ -1702,6 +1704,7 @@ class CRDTManager {
 
     /**
      * Create a new instance
+     * @param {boolean} [debug=false] - Enable debug logging
      */
     constructor(debug) {
         if (debug) this.#debug = true;
@@ -1711,7 +1714,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 {
@@ -1728,7 +1731,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());
                 });
@@ -1744,7 +1747,7 @@ class CRDTManager {
 
     /**
      * Import property update
-     * @param {Object} data - Data to import
+     * @param {object} data - Property update data
      */
     importPropertyUpdate(data) {
         try {
@@ -1786,11 +1789,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 {
@@ -1827,6 +1830,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
@@ -1852,7 +1858,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;
@@ -1883,9 +1889,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 = {
@@ -1900,7 +1906,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 {
@@ -1927,8 +1933,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) {
@@ -1964,10 +1970,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) {
@@ -1999,10 +2005,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;
+                    }
                 }
             }
 
@@ -2016,42 +2023,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()],
@@ -2060,16 +2078,14 @@ class CRDTManager {
     }
 }
 
-/**
- * PlaySocket - WebSocket-based multiplayer for games
- */
-
-
 const ERROR_PREFIX = "PlaySocket error: ";
 const WARNING_PREFIX = "PlaySocket warning: ";
 const LOG_PREFIX = "PlaySocket log: ";
 const TIMEOUT_MS = 3000; // 3 second timeout for WS messages
 
+/**
+ * PlaySocket Client
+ */
 class PlaySocket {
     // Core properties
     #id; // Unique client ID
@@ -2122,11 +2138,13 @@ class PlaySocket {
 
     /**
      * Helper to create timeout promises for create room, join room etc.
+     * @param {string} name - Name of the timeout
+     * @returns {Promise} - Promise that rejects after the timeout
      * @private
      */
-    #createTimeout(operation) {
+    #createTimeout(name) {
         return new Promise((_, reject) =>
-            setTimeout(() => reject(new Error(`${operation} timed out`)), TIMEOUT_MS)
+            setTimeout(() => reject(new Error(`${name} timed out`)), TIMEOUT_MS)
         );
     }
 
@@ -2137,13 +2155,17 @@ class PlaySocket {
      */
     onEvent(event, callback) {
         const validEvents = ["status", "error", "instanceDestroyed", "storageUpdated", "hostMigrated", "clientConnected", "clientDisconnected"];
-        if (!validEvents.includes(event)) return console.warn(WARNING_PREFIX + `Invalid event type "${event}".`);
-        if (!this.#callbacks.has(event)) this.#callbacks.set(event, []);
+        if (!validEvents.includes(event)) {
+            console.warn(WARNING_PREFIX + `Invalid event type "${event}".`);
+            return;
+        }        if (!this.#callbacks.has(event)) this.#callbacks.set(event, []);
         this.#callbacks.get(event).push(callback);
     }
 
     /**
      * Trigger an event to registered callbacks
+     * @param {string} event - Event name
+     * @param {...*} args - Arguments
      * @private
      */
     #triggerEvent(event, ...args) {
@@ -2375,7 +2397,8 @@ class PlaySocket {
         this.#reconnectCount++;
         if (this.#reconnectCount > 9) {
             this.#triggerEvent("error", "Disconnected from server.");
-            return this.destroy();
+            this.destroy();
+            return;
         }
 
         this.#triggerEvent("status", `Attempting to reconnect... (${this.#reconnectCount})`);
@@ -2383,7 +2406,7 @@ class PlaySocket {
         try {
             await this.#connect();
             await Promise.race([
-                new Promise(async (resolve, reject) => {
+                new Promise((resolve, reject) => {
                     this.#pendingReconnect = { resolve, reject };
                     this.#sendToServer({
                         type: 'reconnect',
@@ -2416,11 +2439,13 @@ class PlaySocket {
 
     /**
      * Send a message to the server
+     * @param {object} data - The data to send to the server
      * @private
      */
     #sendToServer(data) {
         if (!this.#socket || this.#socket?.readyState !== WebSocket.OPEN) {
-            return console.warn(WARNING_PREFIX + "Cannot send message - not connected.");
+            console.warn(WARNING_PREFIX + "Cannot send message - not connected.");
+            return;
         }
         try {
             this.#socket.send(encode(data));
@@ -2461,7 +2486,7 @@ class PlaySocket {
     /**
      * Join an existing room
      * @param {string} roomId - ID of the room
-     * @returns {Promise} Resolves when connected
+     * @returns {Promise} - Resolves when connected
      */
     async joinRoom(roomId) {
         if (!this.#initialized) {
@@ -2494,8 +2519,10 @@ class PlaySocket {
      * @param {*} updateValue - New value for update-matching
      */
     updateStorage(key, type, value, updateValue) {
-        if (!this.#inRoom) return this.#triggerEvent("error", "Cannot update storage when not in a room.");
-        if (this.#debug) console.log(LOG_PREFIX + `Property update for key ${key}, operation ${type}, value ${value} and updateValue ${updateValue}.`);
+        if (!this.#inRoom) {
+            this.#triggerEvent("error", "Cannot update storage when not in a room.");
+            return;
+        }        if (this.#debug) console.log(LOG_PREFIX + `Property update for key ${key}, operation ${type}, value ${value} and updateValue ${updateValue}.`);
         const propUpdate = this.#crdtManager.updateProperty(key, type, value, updateValue);
         this.#sendToServer({
             type: 'update_property',