playsocketjs 2.1.0 → 2.2.0

package/README.md

@@ -72,12 +72,17 @@ socket.updateStorage('players', 'array-add-unique', { username: 'Player4', level
 socket.updateStorage('latestPlayer', 'set', 'Player4'); // Regular synced storage update
 ```
 
+Sending traditional requests to the server:
+```javascript
+socket.sendRequest('chosen-request-name', { fact: "You can build server-authoritative logic using this!" })
+```
+
 ## API Reference
 
 ### Constructor
 
 Creates a new PlaySocket instance with a specified ID and configuration options.
-The id can be set to `null` to let the server pick a unique one.
+The ID can be set to `null` to let the server pick a unique one.
 
 ```javascript
 new PlaySocket(id?: string, options: PlaySocketOptions)
@@ -90,11 +95,12 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 
 ### Methods
 
-- `init()`: Initialize the WebSocket connection – Returns Promise (async) which resolves with the client's id
-- `createRoom(initialStorage?: object, maxSize?: number)`: Create a new room and become host – Returns Promise (async) which resolves with the room id (matches the creator's id)
+- `init()`: Initialize the WebSocket connection – Returns Promise (async) which resolves with the client's ID
+- `createRoom(initialStorage?: object, maxSize?: number)`: Create a new room and become host – Returns Promise (async) which resolves with the room ID (matches the creator's ID)
 - `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. Safely update arrays in storage by adding, removing, or updating items. UpdateValue is only required for the 'array-update-matching' operation type
+- `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
 
 #### Event types
@@ -103,15 +109,15 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 - `error`: Error events (returns error `string`)
 - `instanceDestroyed`: Destruction event - triggered by manual .destroy() method invocation or by fatal errors and disconnects
 - `storageUpdated`: Storage state changes (returns storage `object`)
-- `hostMigrated`: Host changes (returns the new host's id `string`)
-- `clientConnected`: New client connected to the room (returns client-id `string`)
-- `clientDisconnected`: Client disconnected from the room (returns client-id `string`, room id (if available) `string`)
+- `hostMigrated`: Host changes (returns the new host's ID `string`)
+- `clientConnected`: New client connected to the room (returns client's ID `string`)
+- `clientDisconnected`: Client disconnected from the room (returns client's ID `string`, room ID (if available) `string`)
 
 ### Properties (Read-only)
 
 - `id`: Client's unique identifier on the WebSocket server
 - `isHost`: If this user is currently assigned the host role
-- `connectionCount`: Number of active client connections in room (without you)
+- `connectionCount`: Number of active client connections in room (without yourself)
 - `getStorage`: Retrieve storage object
 
  
@@ -209,13 +215,15 @@ Creates a new PlaySocket Server instance with configuration options.
 
 #### Event types
 
-- `clientRegistered`: Client registered with the server (returns the client's id `string`, customData `object`)
-- `clientDisconnected`: Client disconnected from the server (returns the client's id `string`)
-- `clientJoinedRoom`: Client joined a room – note that clients can only leave by disconnecting (returns the client's id `string`, room id `string`)
-- `roomCreated`: Client created a room (returns room id `string`)
-- `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
-- `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
+- `clientRegistered`: Client registered with the server (returns the client's ID `string`, customData `object`)
+- `clientRegistrationRequested`: Client requests to register (returns the client's ID `string`, customData `object`) – return `false` or a rejection reason `string` to block the registration
+- `clientDisconnected`: Client disconnected from the server (returns the client's ID `string`)
+- `clientJoinedRoom`: Client joined a room – note that clients can only leave by disconnecting (returns the client's ID `string`, room ID `string`)
+- `roomCreated`: Client created a room (returns room ID `string`)
+- `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
+- `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
+- `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

@@ -1687,7 +1687,7 @@ function requireCrdtManager () {
 	hasRequiredCrdtManager = 1;
 	// Custom conflict-free replicated data type system with vector clocks
 
-	const CONSOLE_PREFIX = "CRDT Manager: ";
+	const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
 
 	class CRDTManager {
 	    // Storage
@@ -1835,50 +1835,53 @@ function requireCrdtManager () {
 	        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
 
-	        if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
-	        this.#lastGCCheck = Date.now();
-
-	        for (const [key, operations] of this.#keyOperations.entries()) {
-	            if (operations?.length < 5) continue; // Min op amount per key for garbage collection to run (otherwise not worth it)
-
-	            let retainCount = operations.length;
-	            operations.forEach((op, index) => {
-	                // Count how many ops, from last to latest, are older than the min-age in a row
-	                if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > MIN_AGE_FOR_GC) {
-	                    const removeCount = index + 1;
-	                    retainCount = operations.length - removeCount;
-	                    this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
-	                }
-	            });
+	        try {
+	            if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
+	            this.#lastGCCheck = Date.now();
+
+	            for (const [key, operations] of this.#keyOperations.entries()) {
+	                if (operations?.length < 5) continue; // Min op amount per key for garbage collection to run (otherwise not worth it)
+
+	                let retainCount = operations.length;
+	                operations.forEach((op, index) => {
+	                    // Count how many ops, from last to latest, are older than the min-age in a row
+	                    if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > MIN_AGE_FOR_GC) {
+	                        const removeCount = index + 1;
+	                        retainCount = operations.length - removeCount;
+	                        this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
+	                    }
+	                });
 
-	            if (retainCount < operations.length) {
-	                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 
-
-	                // Calculate the value at the point where retained operations start
-	                let baselineValue = null;
-	                for (const op of removeOps) {
-	                    if (!op.data) continue;
-	                    if (op.data.type.startsWith('array') && !Array.isArray(baselineValue)) baselineValue = []; // Initialize array if required
-	                    baselineValue = this.#handleOperation(
-	                        baselineValue,
-	                        op.data.type,
-	                        op.data.value,
-	                        op.data.updateValue
-	                    );
+	                if (retainCount < operations.length) {
+	                    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 
+
+	                    // Calculate the value at the point where retained operations start
+	                    let baselineValue = null;
+	                    for (const op of removeOps) {
+	                        if (!op.data) continue;
+	                        baselineValue = this.#handleOperation(
+	                            baselineValue,
+	                            op.data.type,
+	                            op.data.value,
+	                            op.data.updateValue
+	                        );
+	                    }
+
+	                    // Create a compact operation with baseline value and appropriate vector clock
+	                    const compactOp = this.#createOperation({ type: "set", value: baselineValue }, baselineVectorClock);
+
+	                    // Debug log
+	                    if (this.#debug) console.log(CONSOLE_PREFIX + "Operations after garbage collection for this key:", [compactOp, ...retainOps]);
+
+	                    // Combine compact op with retained operations
+	                    this.#keyOperations.set(key, [compactOp, ...retainOps]);
 	                }
-
-	                // Create a compact operation with baseline value and appropriate vector clock
-	                const compactOp = this.#createOperation({ type: "set", value: baselineValue }, baselineVectorClock);
-
-	                // Debug log
-	                if (this.#debug) console.log(CONSOLE_PREFIX + "Operations after garbage collection for this key:", [compactOp, ...retainOps]);
-
-	                // Combine compact op with retained operations
-	                this.#keyOperations.set(key, [compactOp, ...retainOps]);
 	            }
+	        } catch (error) {
+	            console.error(CONSOLE_PREFIX + "Error running garbage collection:", error);
 	        }
 	    }
 
@@ -1913,7 +1916,6 @@ function requireCrdtManager () {
 
 	            for (const op of ops) {
 	                if (!op.data) continue;
-	                if (op.data.type.startsWith('array') && !Array.isArray(value)) value = []; // Initialize array if required
 	                value = this.#handleOperation(
 	                    value,
 	                    op.data.type,
@@ -2225,6 +2227,22 @@ class PlaySocket {
                 if (!message.type) return;
 
                 switch (message.type) {
+                    case 'registration_failed':
+                        if (this.#pendingRegistration) {
+                            this.#pendingRegistration.reject(new Error("Failed to register: " + message.reason));
+                            this.#triggerEvent("error", "Failed to register: " + message.reason);
+                        }
+                        break;
+
+                    case 'registered':
+                        if (this.#pendingRegistration) {
+                            this.#sessionToken = message.sessionToken;
+                            this.#initialized = true;
+                            this.#pendingRegistration.resolve(message.id);
+                            this.#triggerEvent("status", "Connected to server.");
+                        }
+                        break;
+
                     case 'join_accepted':
                         // Connected to room
                         if (this.#pendingJoin) {
@@ -2291,22 +2309,6 @@ class PlaySocket {
                         }
                         break;
 
-                    case 'id_taken':
-                        if (this.#pendingRegistration) {
-                            this.#pendingRegistration.reject(new Error("This id is already in use"));
-                            this.#triggerEvent("error", "This id is taken.");
-                        }
-                        break;
-
-                    case 'registered':
-                        if (this.#pendingRegistration) {
-                            this.#sessionToken = message.sessionToken;
-                            this.#initialized = true;
-                            this.#pendingRegistration.resolve(message.id);
-                            this.#triggerEvent("status", "Connected to server.");
-                        }
-                        break;
-
                     case 'property_updated':
                         this.#roomVersion++; // Increment room version
                         if (this.#debug) console.log(LOG_PREFIX + "Property update received:", message.update);

package/dist/playsocket-server.js

@@ -1813,7 +1813,7 @@ function requireCrdtManager () {
 	hasRequiredCrdtManager = 1;
 	// Custom conflict-free replicated data type system with vector clocks
 
-	const CONSOLE_PREFIX = "CRDT Manager: ";
+	const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
 
 	class CRDTManager {
 	    // Storage
@@ -1961,50 +1961,53 @@ function requireCrdtManager () {
 	        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
 
-	        if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
-	        this.#lastGCCheck = Date.now();
-
-	        for (const [key, operations] of this.#keyOperations.entries()) {
-	            if (operations?.length < 5) continue; // Min op amount per key for garbage collection to run (otherwise not worth it)
-
-	            let retainCount = operations.length;
-	            operations.forEach((op, index) => {
-	                // Count how many ops, from last to latest, are older than the min-age in a row
-	                if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > MIN_AGE_FOR_GC) {
-	                    const removeCount = index + 1;
-	                    retainCount = operations.length - removeCount;
-	                    this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
-	                }
-	            });
+	        try {
+	            if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
+	            this.#lastGCCheck = Date.now();
+
+	            for (const [key, operations] of this.#keyOperations.entries()) {
+	                if (operations?.length < 5) continue; // Min op amount per key for garbage collection to run (otherwise not worth it)
+
+	                let retainCount = operations.length;
+	                operations.forEach((op, index) => {
+	                    // Count how many ops, from last to latest, are older than the min-age in a row
+	                    if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > MIN_AGE_FOR_GC) {
+	                        const removeCount = index + 1;
+	                        retainCount = operations.length - removeCount;
+	                        this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
+	                    }
+	                });
 
-	            if (retainCount < operations.length) {
-	                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 
-
-	                // Calculate the value at the point where retained operations start
-	                let baselineValue = null;
-	                for (const op of removeOps) {
-	                    if (!op.data) continue;
-	                    if (op.data.type.startsWith('array') && !Array.isArray(baselineValue)) baselineValue = []; // Initialize array if required
-	                    baselineValue = this.#handleOperation(
-	                        baselineValue,
-	                        op.data.type,
-	                        op.data.value,
-	                        op.data.updateValue
-	                    );
-	                }
+	                if (retainCount < operations.length) {
+	                    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 
+
+	                    // Calculate the value at the point where retained operations start
+	                    let baselineValue = null;
+	                    for (const op of removeOps) {
+	                        if (!op.data) continue;
+	                        baselineValue = this.#handleOperation(
+	                            baselineValue,
+	                            op.data.type,
+	                            op.data.value,
+	                            op.data.updateValue
+	                        );
+	                    }
 
-	                // Create a compact operation with baseline value and appropriate vector clock
-	                const compactOp = this.#createOperation({ type: "set", value: baselineValue }, baselineVectorClock);
+	                    // Create a compact operation with baseline value and appropriate vector clock
+	                    const compactOp = this.#createOperation({ type: "set", value: baselineValue }, baselineVectorClock);
 
-	                // Debug log
-	                if (this.#debug) console.log(CONSOLE_PREFIX + "Operations after garbage collection for this key:", [compactOp, ...retainOps]);
+	                    // Debug log
+	                    if (this.#debug) console.log(CONSOLE_PREFIX + "Operations after garbage collection for this key:", [compactOp, ...retainOps]);
 
-	                // Combine compact op with retained operations
-	                this.#keyOperations.set(key, [compactOp, ...retainOps]);
+	                    // Combine compact op with retained operations
+	                    this.#keyOperations.set(key, [compactOp, ...retainOps]);
+	                }
 	            }
+	        } catch (error) {
+	            console.error(CONSOLE_PREFIX + "Error running garbage collection:", error);
 	        }
 	    }
 
@@ -2039,7 +2042,6 @@ function requireCrdtManager () {
 
 	            for (const op of ops) {
 	                if (!op.data) continue;
-	                if (op.data.type.startsWith('array') && !Array.isArray(value)) value = []; // Initialize array if required
 	                value = this.#handleOperation(
 	                    value,
 	                    op.data.type,
@@ -2297,7 +2299,7 @@ function requireServer () {
 	                case 'register':
 	                    // Register client ID if provided & check for a duplicate
 	                    if (data.id && this.#clients.get(data.id)) {
-	                        ws.send(encode({ type: 'id_taken' }), { binary: true });
+	                        ws.send(encode({ type: 'registration_failed', reason: 'ID is taken.' }), { binary: true });
 	                        return;
 	                    }
 
@@ -2313,11 +2315,20 @@ function requireServer () {
 	                            }
 	                        }
 	                        if (!data.id) {
-	                            ws.send(encode({ type: 'id_taken' }), { binary: true });
+	                            ws.send(encode({ type: 'registration_failed', reason: 'No available ID found.' }), { binary: true });
 	                            throw new Error('Failed to generate unique ID!');
 	                        }
 	                    }
 
+	                    // Event callback
+	                    const registrationAllowed = await this.#triggerEvent("clientRegistrationRequested", data.id, data.customData);
+	                    if (registrationAllowed === false || typeof registrationAllowed === 'string') {
+	                        ws.send(encode({
+	                            type: 'registration_failed',
+	                            reason: typeof registrationAllowed === 'string' ? registrationAllowed : 'Denied.'
+	                        }), { binary: true });
+	                        return;
+	                    }
 
 	                    ws.clientId = data.id; // Adds the provided id to the ws object as clientId
 	                    this.#clients.set(data.id, ws);
@@ -2462,8 +2473,8 @@ function requireServer () {
 
 	                    if (updateRoom && data.update) {
 	                        // Check if update is allowed via event callback (provide clone to ensure update integrity)
-	                        const allowed = await this.#triggerEvent("storageUpdateRequested", { roomId: updateRoomId, clientId: ws.clientId, update: structuredClone(data.update) });
-	                        if (allowed === false) {
+	                        const updateAllowed = await this.#triggerEvent("storageUpdateRequested", { roomId: updateRoomId, clientId: ws.clientId, update: structuredClone(data.update) });
+	                        if (updateAllowed === false) {
 	                            ws.send(encode({
 	                                type: 'property_update_rejected',
 	                                state: updateRoom.crdtManager.getState
@@ -2636,7 +2647,7 @@ function requireServer () {
 	     * @param {Function} callback - Callback function
 	     */
 	    onEvent(event, callback) {
-	        const validEvents = ["clientRegistered", "clientDisconnected", "clientJoinedRoom", "roomCreationRequested", "requestReceived", "roomCreated", "storageUpdateRequested", "roomDestroyed"];
+	        const validEvents = ["clientRegistered", "clientRegistrationRequested", "clientDisconnected", "clientJoinedRoom", "roomCreationRequested", "requestReceived", "roomCreated", "storageUpdateRequested", "roomDestroyed"];
 	        if (!validEvents.includes(event)) return console.warn(`Invalid PlaySocket event type "${event}"`);
 	        if (!this.#callbacks.has(event)) this.#callbacks.set(event, []);
 	        this.#callbacks.get(event).push(callback);
@@ -2667,8 +2678,7 @@ function requireServer () {
 	        for (const callback of callbacks) {
 	            try {
 	                const result = await callback(...args);
-	                if (result === false) return false; // False = block (in supported events)
-	                if (typeof result === 'object') return result; // If response object is provided -> pass on
+	                if (result != null) return result; // Return any non-null/undefined result
 	            } catch (error) {
 	                console.error(`PlaySocket ${event} callback error:`, error);
 	            }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playsocketjs",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
   "module": "dist/playsocket-client.js",
   "exports": {