playsocketjs 2.1.1 → 2.2.0

package/README.md

@@ -72,6 +72,11 @@ 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
@@ -95,6 +100,7 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 - `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
@@ -111,7 +117,7 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 
 - `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
 
  
@@ -210,12 +216,14 @@ 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`)
+- `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

@@ -2227,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) {
@@ -2293,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

@@ -2299,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;
 	                    }
 
@@ -2315,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);
@@ -2464,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
@@ -2638,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);
@@ -2669,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.1",
+  "version": "2.2.0",
   "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
   "module": "dist/playsocket-client.js",
   "exports": {