playsocketjs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Rhomberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# PlaySocket
+
+A WebSocket-based multiplayer library that simplifies game development by abstracting away the backend logic and moving it to the frontend.
+
+## Why use PlaySocket?
+
+PlaySocket eliminates the traditional complexity of multiplayer implementations:
+
+- **Streamlined Architecture**: No additional backend code is required
+- **State Synchronization**: Built-in storage system keeps game state synchronized across all users
+- **Resilient & Secure Connections**: Automatic reconnection handling and rate limiting
+- **Lightweight**: Uses WebSockets for efficient, predictable & reliable communication with little code required
+
+## Installation
+
+```bash
+npm install playsocketjs
+```
+
+## Usage
+
+Note that in production, you should **always try...catch** these promises, such as socket.init(), to ensure your application continues to run if errors occur.
+
+```javascript
+import PlaySocket from 'playsocketjs';
+
+// Create a new instance
+const socket = new PlaySocket('unique-client-id', {
+    endpoint: 'wss://example.com/socket'
+});
+
+// Set up event handlers
+socket.onEvent('status', status => console.log('Status:', status));
+socket.onEvent('storageUpdated', storage => console.log('Storage update received:', storage));
+
+// Initialize the socket
+await socket.init();
+
+// Create a new room
+const roomId = await socket.createRoom();
+
+// Optionally, you can create a room with an initial storage object
+const roomId = await socket.createRoom({
+  players: [],
+  moreThings: {},
+  latestPlayer: null,
+});
+
+// Join an existing room
+await socket.joinRoom('room-id');
+
+// Interact with the synced storage (available if in room)
+const currentState = socket.getStorage;
+socket.updateStorageArray('players', 'add-unique', { username: 'Player4', level: 2 }); // Special method to enable safe, simultaneous storage updates for arrays
+socket.updateStorage('latestPlayer', 'Player4'); // Regular synced storage update
+
+// To leave the room, destroy the instance
+socket.destroy();
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new PlaySocket(id: string, options: PlaySocketOptions)
+```
+
+Creates a new PlaySocket instance with a specified ID and configuration options.
+
+#### Configuration options
+- `endpoint`: WebSocket server endpoint (e.g., 'wss://example.com/socket')
+- `customData`: You can pass arbitrary data to the "clientRegistered" server event (optional)
+
+### Methods
+
+#### Core
+
+- `init()`: Initialize the WebSocket connection – Returns Promise (async)
+- `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
+
+#### State management
+
+- `updateStorage(key: string, value: any)`: Update a value in the synchronized storage
+- `updateStorageArray(key: string, operation: 'add' | 'add-unique' | 'remove-matching' | 'update-matching', value: any, updateValue?: any)`: Safely update arrays in storage by adding, removing, or updating items. This is necessary for when array updates might be happening simultaneously to ensure changes are being applied and not overwritten. Using add-unique instead of add ensures that this value can only be in the array once.
+- `onEvent(event: string, callback: Function)`: Register an event callback
+
+##### Event types
+
+- `status`: Connection status updates (returns status `string`)
+- `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`) – As compared to PlayPeerJS, the room id does NOT change when the host changes
+- `clientConnected`: New client connected to the room (returns client-id `string`)
+- `clientDisconnected`: Client disconnected from the room (returns client-id `string`)
+
+### Properties (Read-only)
+
+The `id` is used to distinguish the client from other clients on the WebSocket server. 
+Using a UUID is recommended, but it is also fine to use any other random string. If you're using a public WebSocket server, including your application's name in the `id` can help to prevent overlap (e.g. your-app-012345abcdef). 
+
+- `id`: Client's unique identifier
+- `isHost`: If this user is currently assigned the host role
+- `connectionCount`: Number of active client connections in room (without you)
+- `getStorage`: Retrieve storage object
+
+# PlaySocket Server
+
+PlaySocket includes a server implementation that can be set up in seconds.
+
+## Installation
+
+To use the server component, you'll need to install playsocketjs and the ws package:
+
+```bash
+npm install playsocketjs ws
+```
+
+## Usage
+
+Here are usage examples for a standalone server and an express application. The implementation is 
+framework agnostic and the Express example can be adapted to any other backend solution.
+
+### Standalone server
+
+```javascript
+const PlaySocketServer = require('playsocketjs/server');
+
+// Create and start the server
+const server = new PlaySocketServer();
+```
+
+### With Express.js
+
+```javascript
+const express = require('express');
+const http = require('http');
+const PlaySocketServer = require('playsocketjs/server');
+const port = 3000;
+
+const app = express();
+const httpServer = http.createServer(app);
+
+// Create PlaySocket server with your HTTP server
+// Uses a custom path here (which you'll likely want to do if used this way)
+const playSocketServer = new PlaySocketServer({ 
+  port,
+  server: httpServer,
+  path: '/socket'
+});
+
+// Start the server
+httpServer.listen(port, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new PlaySocket(options: PlaySocketServerOptions)
+```
+
+Creates a new PlaySocket Server instance with configuration options.
+
+### Configuration options
+
+- `port`: Port to listen on (default: 3000, used only if no server provided)
+- `path`: WebSocket endpoint path (default: '/')
+- `server`: Existing http server (optional)
+
+### Methods
+
+- `onEvent(event: string, callback: Function)`: Register a server-side event callback
+
+##### 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`)
+- `roomCreated`: Client created a room (returns room id `string`)
+- `roomJoined`: Client joined a room (returns the client's id `string`, room id `string`)
+
+### Properties (Read-only)
+
+- `getRooms`: Retrieve the rooms object
+
+# License
+
+MIT
+
+# Contributing
+
+Please feel free to fork the repository and submit a Pull Request.

package/dist/playsocket-client.js

@@ -0,0 +1,427 @@
+/**
+ * PlaySocket - WebSocket-based multiplayer for games
+ */
+
+const ERROR_PREFIX = "PlaySocket error: ";
+const WARNING_PREFIX = "PlaySocket warning: ";
+const TIMEOUT_MS = 3000; // 3 second timeout for operations
+
+class PlaySocket {
+    // Core properties
+    #id; // Unique client ID
+    #endpoint;
+    #socket; // WebSocket connection
+    #initialized = false; // Initialization status
+    #customData;
+
+    // Room properties
+    #storage = {}; // Shared storage object
+    #isHost = false; // Whether this client is host
+    #roomHost;
+    #roomId; // ID of the host (client only)
+    #connectionCount = 0;
+
+    // Event handling
+    #callbacks = new Map(); // Event callbacks
+
+    // Async server operations
+    #pendingJoin;
+    #pendingHost;
+    #pendingInit;
+
+    /**
+     * Create a new PlaySocket instance
+     * @param {string} id - Unique identifier for this client
+     * @param {object} options - Connection options
+     * @param {string} options.endpoint - WebSocket endpoint path
+     * @param {object} [options.customData] - Custom registration data
+     */
+    constructor(id, options = {}) {
+        this.#id = id;
+        if (options.endpoint) this.#endpoint = options.endpoint;
+        if (options.customData) this.#customData = { ...options.customData };
+    }
+
+    /**
+     * Helper to create timeout promises for create room, join room etc.
+     * @private
+     */
+    #createTimeout(operation) {
+        return new Promise((_, reject) =>
+            setTimeout(() => reject(new Error(`${operation} timed out`)), TIMEOUT_MS)
+        );
+    }
+
+    /**
+     * Register an event callback
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     */
+    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, []);
+        this.#callbacks.get(event).push(callback);
+    }
+
+    /**
+     * Trigger an event to registered callbacks
+     * @private
+     */
+    #triggerEvent(event, ...args) {
+        const callbacks = this.#callbacks.get(event);
+        callbacks?.forEach(callback => {
+            try {
+                callback(...args);
+            } catch (error) {
+                console.error(ERROR_PREFIX + `${event} callback error:`, error);
+            }
+        });
+    }
+
+    /**
+     * Initialize the PlaySocket instance by connecting to the WS server
+     * @returns {Promise} Resolves when connection is established
+     */
+    async init() {
+        if (this.#initialized) return Promise.reject(new Error("Already initialized."));
+        if (!this.#endpoint) return Promise.reject(new Error("No websocket endpoint provided."));
+        this.#triggerEvent("status", "Initializing...");
+
+        return Promise.race([
+            this.#connect(),
+            this.#createTimeout("Initialization")
+        ]);
+    }
+
+
+    /**
+     * Connect to the WS server and register
+     * @returns {Promise} Resolves when user is registered on the WS server
+     * @private 
+     */
+    async #connect() {
+        return new Promise((resolve, reject) => {
+            this.#socket = new WebSocket(this.#endpoint);
+            this.#setupSocketHandlers(); // Message & close events
+
+            // Resolve or reject depending on answer to registration msg
+            this.#pendingInit = { resolve, reject };
+
+            // Register with server
+            this.#socket.onopen = () => {
+                this.#initialized = true;
+                this.#sendToServer({
+                    type: 'register',
+                    id: this.#id,
+                    customData: this.#customData || undefined
+                });
+            };
+        });
+    }
+
+    /**
+     * Set up WebSocket message & close handlers
+     * @private
+     */
+    #setupSocketHandlers() {
+        this.#socket.onmessage = (event) => {
+            try {
+                const message = JSON.parse(event.data);
+                if (!message.type) return;
+
+                switch (message.type) {
+                    case 'connection_accepted':
+                        // Connected to room
+                        if (this.#pendingJoin) {
+                            this.#storage = message.storage;
+                            this.#connectionCount = message.participantCount - 1;
+                            this.#triggerEvent("status", `Connected to room.`);
+                            this.#triggerEvent("storageUpdated", { ...this.#storage });
+                            this.#pendingJoin.resolve();
+                            this.#pendingJoin = null;
+                        }
+                        break;
+
+                    case 'connection_rejected':
+                        // Connection to room failed
+                        if (this.#pendingJoin) {
+                            this.#triggerEvent("status", "Connection rejected: " + message.reason || 'Unknown reason');
+                            this.#pendingJoin.reject(new Error("Connection rejected: " + message.reason || 'Unknown reason'));
+                            this.#pendingJoin = null;
+                        }
+                        break;
+
+                    case 'room_created':
+                        if (this.#pendingHost) {
+                            this.#pendingHost.resolve(this.#roomId);
+                            this.#triggerEvent("status", `Room created${this.#pendingHost.maxSize ? ` with max size ${this.#pendingHost.maxSize}.` : '.'}`);
+                            this.#triggerEvent("storageUpdated", { ...this.#storage });
+                            this.#pendingHost = null;
+                        }
+                        break;
+
+                    case 'room_creation_failed':
+                        if (this.#pendingHost) {
+                            this.#pendingHost.reject(new Error("Failed to create room: " + message.reason || 'Unknown reason'));
+                            this.#triggerEvent("error", "Failed to create room: " + message.reason || 'Unknown reason');
+                            this.#pendingHost = null;
+                        }
+                        break;
+
+                    case 'id_taken':
+                        if (this.#pendingInit) {
+                            this.#pendingInit.reject(new Error("This id is already in use."));
+                            this.#triggerEvent("error", "This id is taken.");
+                            this.#pendingInit = null;
+                        }
+                        break;
+
+                    case 'registered':
+                        if (this.#pendingInit) {
+                            this.#pendingInit.resolve();
+                            this.#triggerEvent("status", "Connected to server.");
+                            this.#pendingInit = null;
+                        }
+                        break;
+
+                    case 'storage_sync':
+                        if (message.key && JSON.stringify(this.#storage[message.key]) !== JSON.stringify(message.value)) {
+                            this.#storage[message.key] = message.value;
+                            this.#triggerEvent("storageUpdated", { ...this.#storage });
+                        }
+                        break;
+
+                    case 'client_disconnected':
+                        this.#isHost = this.#id == message.updatedHost;
+                        this.#connectionCount = message.participantCount - 1; // Counted without the user themselves
+
+                        // If host has changed...
+                        if (this.#roomHost != message.updatedHost) {
+                            this.#roomHost = message.updatedHost;
+                            this.#triggerEvent("hostMigrated", this.#roomHost);
+                        }
+
+                        this.#triggerEvent("clientDisconnected", message.client);
+                        this.#triggerEvent("status", `Client ${message.client} disconnected.`);
+                        break;
+
+                    case 'client_connected':
+                        this.#connectionCount = message.participantCount - 1;
+                        this.#triggerEvent("clientConnected", message.client);
+                        this.#triggerEvent("status", `Client ${message.client} connected.`);
+                        break;
+                }
+            } catch (error) {
+                console.error(ERROR_PREFIX + "Error handling message:", error);
+            }
+        };
+
+        // Handle socket errors
+        this.#socket.onerror = () => {
+            this.#triggerEvent("error", "WebSocket error.");
+            if (this.#pendingInit) this.#pendingInit.reject(new Error("WebSocket error."));
+        };
+
+        // Handle socket close & attempt reconnect
+        this.#socket.onclose = () => {
+            this.#triggerEvent("status", "Disconnected from server.");
+
+            setTimeout(async () => {
+                if (!this.#initialized || !this.#socket) return;
+                try {
+                    await this.#connect(); // Will set status to connected if successful
+
+                    // Rejoin room if needed
+                    if (this.#roomId) {
+                        this.#triggerEvent("status", "Rejoining room...");
+                        await this.joinRoom(this.#roomId); // If this fails, it will be caught by the outer catch
+                    }
+                } catch (error) {
+                    this.#triggerEvent("error", "WebSocket connection permanently closed: " + error);
+                    this.#socket = null;
+                    this.destroy();
+                }
+            }, 1000);
+        };
+    };
+
+    /**
+     * Send a message to the server
+     * @private
+     */
+    #sendToServer(data) {
+        if (!this.#initialized || !this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
+            return console.error(ERROR_PREFIX + "Cannot send message - not connected.");
+        }
+        try {
+            this.#socket.send(JSON.stringify(data));
+        } catch (error) {
+            console.error(ERROR_PREFIX + "Error sending message:", error);
+            this.#triggerEvent("error", "Error sending message: " + error.message);
+        }
+    }
+
+    /**
+     * Create a new room and become host
+     * @param {object} initialStorage - Initial state
+     * @param {number} maxSize - Max number of participants
+     * @returns {Promise} Resolves with room ID
+     */
+    createRoom(initialStorage = {}, maxSize) {
+        if (!this.#initialized) {
+            this.#triggerEvent("error", "Cannot create room - not initialized");
+            return Promise.reject(new Error("Not initialized"));
+        }
+
+        return Promise.race([
+            new Promise((resolve, reject) => {
+                this.#isHost = true;
+                this.#storage = initialStorage;
+                this.#roomId = this.#id; // Create room with your own ID as the room ID to mimic p2p
+                this.#roomHost = this.#id;
+                this.#pendingHost = { maxSize, resolve, reject };
+
+                this.#sendToServer({
+                    type: 'create_room',
+                    storage: { ...initialStorage },
+                    size: maxSize,
+                    from: this.#id,
+                });
+            }),
+            this.#createTimeout("Room creation")
+        ]);
+    }
+
+    /**
+     * Join an existing room
+     * @param {string} roomId - ID of the room
+     * @returns {Promise} Resolves when connected
+     */
+    joinRoom(roomId) {
+        if (!this.#initialized) {
+            this.#triggerEvent("error", "Cannot join room - not initialized");
+            return Promise.reject(new Error("Not initialized"));
+        }
+
+        return Promise.race([
+            new Promise((resolve, reject) => {
+                this.#isHost = false;
+                this.#roomId = roomId;
+                this.#roomHost = roomId;
+                this.#pendingJoin = { resolve, reject };
+
+                // Send connection request
+                this.#triggerEvent("status", `Connecting to room ${roomId}...`);
+                this.#sendToServer({
+                    type: 'join_room',
+                    roomId
+                });
+            }),
+            this.#createTimeout("Room join")
+        ]);
+    }
+
+    /**
+     * Update a value in the shared storage
+     * @param {string} key - Storage key
+     * @param {*} value - New value
+     */
+    updateStorage(key, value) {
+        if (JSON.stringify(this.#storage[key]) === JSON.stringify(value)) return;
+        this.#storage[key] = value;
+        this.#triggerEvent("storageUpdated", { ...this.#storage });
+        this.#sendToServer({
+            type: 'room_storage_update',
+            key,
+            value
+        });
+    }
+
+    /**
+     * Update an array in storage with special operations
+     * @param {string} key - Storage key
+     * @param {string} operation - Operation type: add, add-unique, remove-matching, update-matching
+     * @param {*} value - Value to operate on
+     * @param {*} updateValue - New value for update-matching
+     */
+    updateStorageArray(key, operation, value, updateValue) {
+        this.#handleArrayUpdate(key, operation, value, updateValue);
+        this.#sendToServer({
+            type: 'room_storage_array_update',
+            key,
+            operation,
+            value,
+            updateValue
+        });
+    }
+
+    /**
+     * Handle array operations client-side
+     * @private
+     */
+    #handleArrayUpdate(key, operation, value, updateValue) {
+        if (!this.#storage[key] || !Array.isArray(this.#storage[key])) this.#storage[key] = [];
+        let array = this.#storage[key];
+
+        const isObject = typeof value === 'object' && value !== null;
+        const compare = (item) => isObject ?
+            JSON.stringify(item) === JSON.stringify(value) : item === value;
+
+        switch (operation) {
+            case 'add':
+                array.push(value);
+                break;
+
+            case 'add-unique':
+                if (!array.some(compare)) array.push(value);
+                break;
+
+            case 'remove-matching':
+                this.#storage[key] = array.filter(item => !compare(item));
+                break;
+
+            case 'update-matching':
+                const index = array.findIndex(compare);
+                if (index !== -1) array[index] = updateValue;
+                break;
+
+            default:
+                console.error(ERROR_PREFIX + `Unknown array operation: ${operation}`);
+                return;
+        }
+
+        this.#triggerEvent("storageUpdated", { ...this.#storage });
+    }
+
+    /**
+     * Destroy the PlaySocket instance and disconnect
+     */
+    destroy() {
+        if (this.#socket) {
+            this.#socket.close();
+            this.#socket = null;
+        }
+
+        // Reset state
+        this.#initialized = false;
+        this.#isHost = false;
+        this.#roomHost = null;
+        this.#storage = {};
+        this.#roomId = null;
+        this.#connectionCount = 0;
+
+        this.#triggerEvent("status", "Destroyed.");
+        this.#triggerEvent("instanceDestroyed");
+    }
+
+    // Public getters
+    get connectionCount() { return this.#connectionCount; }
+    get getStorage() { return { ...this.#storage }; }
+    get isHost() { return this.#isHost; }
+    get id() { return this.#id; }
+}
+
+export { PlaySocket as default };

package/dist/playsocket-server.js

@@ -0,0 +1,349 @@
+'use strict';
+
+var require$$0 = require('ws');
+var require$$1 = require('http');
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+var server$1;
+var hasRequiredServer;
+
+function requireServer () {
+	if (hasRequiredServer) return server$1;
+	hasRequiredServer = 1;
+	const WebSocket = require$$0;
+	const http = require$$1;
+
+	/**
+	 * PlaySocketServer - WebSocket server for PlaySocket multiplayer library
+	 */
+	class PlaySocketServer {
+	    #server;
+	    #wss;
+	    #clients = new Map(); // ClientId -> WebSocket instance
+	    #rooms = {};
+	    #clientRooms = new Map(); // ClientId -> RoomId
+	    #rateLimits = new Map(); // Rate limiting storage
+	    #callbacks = new Map();
+
+	    /**
+	     * Create a new PlaySocketServer instance
+	     * @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
+	     */
+	    constructor(options = {}) {
+	        const { server, port = 3000, path = '/' } = options;
+
+	        // Handle server creation / usage
+	        if (server) {
+	            this.#server = server; // Use provided HTTP server
+	        } else {
+	            this.#server = http.createServer(); // Create HTTP server and start it
+	            this.#server.listen(port, () => {
+	                console.log(`PlaySocket server running on port ${port}`);
+	            });
+	        }
+
+	        // Create WebSocket server
+	        this.#wss = new WebSocket.Server({
+	            server: this.#server,
+	            path
+	        });
+
+	        // Set up ws event handlers
+	        this.#wss.on('connection', ws => {
+	            ws.on('message', msg => this.#handleMessage(ws, msg));
+	            ws.on('close', () => this.#handleDisconnection(ws));
+	        });
+
+	        process.on('SIGINT', () => this.#stop()); // Graceful shutdown
+	    }
+
+	    /**
+	     * Handle WebSocket message
+	     * @private
+	     */
+	    #handleMessage(ws, message) {
+	        try {
+	            const data = JSON.parse(message);
+
+	            // Apply rate limiting after client is registered
+	            if (ws.clientId && !this.#checkRateLimit(ws.clientId, data.type)) {
+	                return console.error(`Client ${ws.clientId} rate limit exceeded.`);
+	            }
+
+	            switch (data.type) {
+	                case 'register':
+	                    // Register client ID
+	                    if (!data.id) return;
+	                    if (this.#clients.get(data.id)) {
+	                        ws.send(JSON.stringify({ type: 'id_taken' }));
+	                        return;
+	                    }
+	                    ws.clientId = data.id; // Adds the provided id to the ws object as clientId
+	                    this.#clients.set(data.id, ws);
+	                    ws.send(JSON.stringify({ type: 'registered' }));
+	                    this.#triggerEvent("clientRegistered", data.id, data.customData);
+	                    break;
+
+	                case 'create_room':
+	                    if (!ws.clientId) return;
+	                    const newRoomId = ws.clientId;
+	                    if (this.#clientRooms.get(ws.clientId) || this.#rooms[newRoomId]) {
+	                        ws.send(JSON.stringify({
+	                            type: 'room_creation_failed',
+	                            reason: this.#clientRooms.get(ws.clientId) ? 'Already in a room' : 'Room id is taken'
+	                        }));
+	                        return;
+	                    }
+
+	                    this.#rooms[newRoomId] = {
+	                        participants: [ws.clientId],
+	                        maxSize: data.size || null,
+	                        storage: data.storage || {},
+	                    };
+
+	                    this.#clientRooms.set(ws.clientId, newRoomId);
+	                    ws.send(JSON.stringify({ type: 'room_created' }));
+	                    this.#triggerEvent("roomCreated", ws.clientId); // Client id = room id
+	                    break;
+
+	                case 'join_room':
+	                    if (!data.roomId) return;
+	                    const roomId = data.roomId;
+	                    const room = this.#rooms[roomId];
+
+	                    if (!room ||
+	                        (room.maxSize && room.participants.length >= room.maxSize) ||
+	                        this.#clientRooms.get(ws.clientId)) {
+	                        ws.send(JSON.stringify({
+	                            type: 'connection_rejected',
+	                            reason: !room ? 'Room not found' :
+	                                room.maxSize && room.participants.length >= room.maxSize ? 'Room full' :
+	                                    'Already in a room'
+	                        }));
+	                        return;
+	                    }
+
+	                    room.participants.push(ws.clientId);
+	                    this.#clientRooms.set(ws.clientId, roomId);
+
+	                    // Notify joiner with initial storage
+	                    ws.send(JSON.stringify({
+	                        type: 'connection_accepted',
+	                        storage: room.storage,
+	                        participantCount: room.participants.length
+	                    }));
+
+	                    // Notify existing participants
+	                    room.participants.forEach(p => {
+	                        if (p === ws.clientId) return;
+	                        const client = this.#clients.get(p);
+	                        if (client) {
+	                            client.send(JSON.stringify({
+	                                type: 'client_connected',
+	                                client: ws.clientId,
+	                                participantCount: room.participants.length
+	                            }));
+	                        }
+	                    });
+	                    this.#triggerEvent("roomJoined", ws.clientId, roomId);
+	                    break;
+
+	                case 'room_storage_update':
+	                    const updateRoomId = this.#clientRooms.get(ws.clientId);
+	                    const updateRoom = updateRoomId ? this.#rooms[updateRoomId] : null;
+	                    if (updateRoom && data.key) {
+	                        updateRoom.storage[data.key] = data.value;
+	                        this.#syncRoomStorageKey(updateRoomId, data.key);
+	                    }
+	                    break;
+
+	                case 'room_storage_array_update':
+	                    const arrayRoomId = this.#clientRooms.get(ws.clientId);
+	                    const arrayRoom = arrayRoomId ? this.#rooms[arrayRoomId] : null;
+	                    if (arrayRoom && data.key) {
+	                        this.#arrayUpdate(arrayRoom.storage, data.key, data.operation, data.value, data.updateValue);
+	                        this.#syncRoomStorageKey(arrayRoomId, data.key);
+	                    }
+	                    break;
+	            }
+	        } catch (error) {
+	            console.error('Error processing message:', error);
+	        }
+	    }
+
+	    /**
+	     * Check rate limit using token bucket algorithm
+	     * @private
+	     */
+	    #checkRateLimit(clientId, operationType) {
+	        const MAX_POINTS = 100;
+	        const now = Date.now();
+
+	        if (!this.#rateLimits.has(clientId)) {
+	            this.#rateLimits.set(clientId, { points: MAX_POINTS, lastReset: now });
+	            return true;
+	        }
+
+	        const limit = this.#rateLimits.get(clientId);
+
+	        // Reset points if interval has passed (5s)
+	        if (now - limit.lastReset > 5000) {
+	            limit.points = MAX_POINTS;
+	            limit.lastReset = now;
+	        }
+
+	        const pointCost = ['create_room', 'join_room'].includes(operationType) ? 20 : 1;
+	        if (limit.points < pointCost) return false;
+
+	        limit.points -= pointCost;
+	        return true;
+	    }
+
+	    /**
+	     * Sync storage key to all clients in room
+	     * @private
+	     */
+	    #syncRoomStorageKey(roomId, key) {
+	        const room = this.#rooms[roomId];
+	        if (!room) return;
+
+	        room.participants.forEach(p => {
+	            const client = this.#clients.get(p);
+	            if (client) {
+	                client.send(JSON.stringify({
+	                    type: 'storage_sync',
+	                    key,
+	                    value: room.storage[key]
+	                }));
+	            }
+	        });
+	    }
+
+	    /**
+	     * Handle array operations
+	     * @private
+	     */
+	    #arrayUpdate(storage, key, operation, value, updateValue) {
+	        if (!storage[key] || !Array.isArray(storage[key])) storage[key] = [];
+	        let array = storage[key];
+
+	        const isObject = typeof value === 'object' && value !== null;
+	        const compare = (item) => isObject ?
+	            JSON.stringify(item) === JSON.stringify(value) : item === value;
+
+	        switch (operation) {
+	            case 'add':
+	                array.push(value);
+	                break;
+
+	            case 'add-unique':
+	                if (!array.some(compare)) array.push(value);
+	                break;
+
+	            case 'remove-matching':
+	                storage[key] = array.filter(item => !compare(item));
+	                break;
+
+	            case 'update-matching':
+	                const index = array.findIndex(compare);
+	                if (index !== -1) array[index] = updateValue;
+	                break;
+	        }
+	    }
+
+	    /**
+	     * Handle client disconnection
+	     * @private
+	     */
+	    #handleDisconnection(ws) {
+	        if (!ws.clientId) return;
+
+	        this.#clients.delete(ws.clientId);
+	        this.#rateLimits.delete(ws.clientId);
+
+	        const roomId = this.#clientRooms.get(ws.clientId);
+	        const room = roomId ? this.#rooms[roomId] : null;
+
+	        if (room) {
+	            room.participants = room.participants?.filter(p => p !== ws.clientId);
+	            this.#clientRooms.delete(ws.clientId);
+
+	            // Notify remaining participants
+	            room.participants?.forEach(p => {
+	                const client = this.#clients.get(p);
+	                if (client) {
+	                    try {
+	                        client.send(JSON.stringify({
+	                            type: 'client_disconnected',
+	                            updatedHost: room.participants?.[0],
+	                            client: ws.clientId,
+	                            participantCount: room.participants?.length
+	                        }));
+	                    } catch (error) {
+	                        console.error(`Error notifying client of disconnection:`, error);
+	                    }
+	                }
+	            });
+	            if (room.participants?.length === 0) delete this.#rooms[roomId]; // Delete room if now empty
+	        }
+
+	        this.#triggerEvent("clientDisconnected", ws.clientId);
+	    }
+
+	    /**
+	     * Register an event callback
+	     * @param {string} event - Event name
+	     * @param {Function} callback - Callback function
+	     */
+	    onEvent(event, callback) {
+	        const validEvents = ["clientRegistered", "clientDisconnected", "roomCreated", "roomJoined"];
+	        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);
+	    }
+
+	    /**
+	     * Trigger an event to registered callbacks
+	     * @private
+	     */
+	    #triggerEvent(event, ...args) {
+	        const callbacks = this.#callbacks.get(event);
+	        callbacks?.forEach(callback => {
+	            try { callback(...args); } catch (error) { console.error(`PlaySocket ${event} callback error:`, error); }
+	        });
+	    }
+
+	    /**
+	     * Stop the server
+	     * @private
+	     */
+	    #stop() {
+	        if (this.#wss) {
+	            this.#wss.clients.forEach(client => client.close());
+	            this.#wss.close(); // TODO necessary?
+	        }
+
+	        if (this.#server) {
+	            this.#server.close(() => {
+	                console.log('PlaySocket server stopped');
+	            });
+	        }
+	    }
+
+	    get getRooms() { return { ...this.#rooms } }
+	}
+
+	server$1 = PlaySocketServer;
+	return server$1;
+}
+
+var serverExports = requireServer();
+var server = /*@__PURE__*/getDefaultExportFromCjs(serverExports);
+
+module.exports = server;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "playsocketjs",
+  "version": "1.0.0",
+  "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
+  "module": "dist/playsocket-client.js",
+  "exports": {
+    ".": {
+      "import": "./dist/playsocket-client.js"
+    },
+    "./server": {
+      "require": "./dist/playsocket-server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "rollup -c rollup.config.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/therealPaulPlay/PlaySocketJS.git"
+  },
+  "keywords": [
+    "WebSocket",
+    "data channel",
+    "Socket",
+    "PlayPeerJS",
+    "multiplayer",
+    "game"
+  ],
+  "author": "PaulPlay",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/therealPaulPlay/PlaySocketJS/issues"
+  },
+  "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"
+  },
+  "peerDependencies": {
+    "ws": "^8.18.1"
+  }
+}