playsocketjs 2.7.0 → 3.0.0

package/README.md

@@ -67,7 +67,7 @@ socket.onEvent('storageUpdated', storage => (reactiveVariable = storage)); // As
 
 Interfacing with the synchronized storage (examples):
 ```javascript
-const currentState = socket.getStorage; // Synchronous, local access
+const currentState = socket.storage; // Synchronous, local access
 socket.updateStorage('players', 'array-add-unique', { username: 'Player4', level: 2 }); // Special method to enable conflict-free additions for arrays
 socket.updateStorage('latestPlayer', 'set', 'Player4'); // Regular synced storage update
 ```
@@ -92,20 +92,20 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `endpoint` | string | `none - set this!` | WebSocket server endpoint (e.g., 'wss://example.com/socket') |
-| `customData` | object | `{}` | Arbitrary data to pass to the "clientRegistered" server event (optional) |
+| `endpoint` | string | `undefined` | WebSocket server endpoint (e.g., 'wss://example.com/socket') (required) |
+| `customData` | object | `{}` | Arbitrary data to pass to the "clientRegistered" server event |
 | `debug` | boolean | `false` | Set to true to enable extra logging |
 
 ### Methods
 
 | Method | Parameters | Return type | Description |
 |--------|------------|-------------|-------------|
-| `init()` | - | `Promise<string>` | Initialize the WebSocket connection – Returns Promise which resolves with the client's ID |
-| `createRoom()` | `initialStorage?: object, size?: number` | `Promise<string>` | Create a new room and become host – Returns Promise which resolves with the room ID. The room participant maximum is 100 |
+| `init()` | - | `Promise<string>` | Initialize the WebSocket connection – Returns a promise which resolves with the client's ID |
+| `createRoom()` | `initialStorage?: object, size?: number` | `Promise<string>` | Create a new room and become host – Returns a promise which resolves with the room ID. The room participant maximum is 100 |
 | `joinRoom()` | `roomId: string` | `Promise<void>` | Join an existing room |
 | `destroy()` | - | `void` | 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` | `void` | 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` | `void` | Send requests to the server with optional custom data (handle these in the `requestReceived` server event) |
+| `sendRequest()` | `name: string, data?: any` | `void` | Send requests to the server with optional custom data (handle them in the `requestReceived` server event) |
 | `onEvent()` | `event: string, callback: Function` | `void` | Register an event callback |
 
 ### Event types
@@ -114,11 +114,12 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 |-------|-------------------|-------------|
 | `status` | `status: string` | Connection status updates |
 | `error` | `error: string` | Error events |
+| `moved` | `roomId: string` | Moved to different room |
 | `instanceDestroyed` | - | Destruction event - triggered by manual .destroy() method invocation or by fatal errors and disconnects |
 | `storageUpdated` | `storage: object` | Storage state changes |
 | `hostMigrated` | `roomId: string` | Host changes |
-| `clientConnected` | `clientId: string` | New client connected to the room |
-| `clientDisconnected` | `clientId: string, roomId?: string` | Client disconnected from the room |
+| `clientJoined` | `clientId: string` | New client joined the room |
+| `clientLeft` | `clientId: string, roomId?: string` | Client left the room |
 
 ### Properties (Read-only)
 
@@ -126,8 +127,8 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 |----------|------|-------------|
 | `id` | string | Client's unique identifier on the WebSocket server |
 | `isHost` | boolean | If this user is currently assigned the host role |
-| `connectionCount` | number | Number of active client connections in room (without yourself) |
-| `getStorage` | object | Retrieve storage object |
+| `participantCount` | number | Number of active client connections in room (with yourself) |
+| `storage` | object | Retrieve storage object |
 
 &nbsp;
 
@@ -160,7 +161,7 @@ function shutdown() {
     process.exit(0);
 }
 
-// Handle both SIGINT (Ctrl+C) and SIGTERM (Docker stop)
+// Handle both SIGINT and SIGTERM
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 ```
@@ -192,7 +193,7 @@ function shutdown() {
     process.exit(0);
 }
 
-// Handle both SIGINT (Ctrl+C) and SIGTERM (Docker stop)
+// Handle both SIGINT and SIGTERM
 process.on('SIGINT', shutdown);
 process.on('SIGTERM', shutdown);
 ```
@@ -243,6 +244,7 @@ The callback signature is `callback(verified, code?, message?)` where `code` and
 |--------|------------|-------------|-------------|
 | `stop()` | - | `void` | Closes all active client connections, the websocket server and the underlying http server if it's standalone |
 | `kick()` | `clientId: string, reason?: string` | `void` | Kick a client by their clientID – this will close their connection and set an error message |
+| `move()` | `clientId: string, roomId: string` | `void` | Move a client, that is already in a room, to a different room |
 | `onEvent()` | `event: string, callback: Function` | `void` | Register a server-side event callback |
 | `getRoomStorage()` | `roomId: string` | `object` | Get a snapshot of the current room storage |
 | `updateRoomStorage()` | `roomId: string, key: string, type: 'set' \| 'array-add' \| 'array-add-unique' \| 'array-remove-matching' \| 'array-update-matching', value: any, updateValue?: any` | `void` | Update a key in the shared room storage from the server |
@@ -255,7 +257,7 @@ The callback signature is `callback(verified, code?, message?)` where `code` and
 |-------|-------------------|-------------|--------------|
 | `clientRegistered` | `clientId: string, customData: object` | Client registered with the server | - |
 | `clientRegistrationRequested` | `clientId: string, customData: object` | Client requests to register | Return `false` or rejection reason `string` to block |
-| `clientDisconnected` | `clientId: string` | Client disconnected from the server | - |
+| `clientLeft` | `clientId: string` | Client disconnected from the server | - |
 | `clientJoinedRoom` | `clientId: string, roomId: string` | Client joined a room (clients can only leave by disconnecting) | - |
 | `clientJoinRequested` | `clientId: string, roomId: string` | Client requests to join a room | Return `false` or rejection reason `string` to block |
 | `roomCreated` | `roomId: string` | Client created a room | - |
@@ -269,7 +271,7 @@ The callback signature is `callback(verified, code?, message?)` where `code` and
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `getRooms` | object | Retrieve the rooms object |
+| `rooms` | object | Retrieve the rooms object |
 
 # License
 

package/dist/playsocket-client.js

@@ -170,6 +170,8 @@ function utf8Decode(bytes, inputOffset, byteLength) {
  * ExtData is used to handle Extension Types that are not registered to ExtensionCodec.
  */
 class ExtData {
+    type;
+    data;
     constructor(type, data) {
         this.type = type;
         this.data = data;
@@ -313,13 +315,18 @@ const timestampExtension = {
 
 // ExtensionCodec to handle MessagePack extensions
 class ExtensionCodec {
+    static defaultCodec = new ExtensionCodec();
+    // ensures ExtensionCodecType<X> matches ExtensionCodec<X>
+    // this will make type errors a lot more clear
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    __brand;
+    // built-in extensions
+    builtInEncoders = [];
+    builtInDecoders = [];
+    // custom extensions
+    encoders = [];
+    decoders = [];
     constructor() {
-        // built-in extensions
-        this.builtInEncoders = [];
-        this.builtInDecoders = [];
-        // custom extensions
-        this.encoders = [];
-        this.decoders = [];
         this.register(timestampExtension);
     }
     register({ type, encode, decode, }) {
@@ -375,7 +382,6 @@ class ExtensionCodec {
         }
     }
 }
-ExtensionCodec.defaultCodec = new ExtensionCodec();
 
 function isArrayBufferLike(buffer) {
     return (buffer instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && buffer instanceof SharedArrayBuffer));
@@ -399,8 +405,20 @@ function ensureUint8Array(buffer) {
 const DEFAULT_MAX_DEPTH = 100;
 const DEFAULT_INITIAL_BUFFER_SIZE = 2048;
 class Encoder {
+    extensionCodec;
+    context;
+    useBigInt64;
+    maxDepth;
+    initialBufferSize;
+    sortKeys;
+    forceFloat32;
+    ignoreUndefined;
+    forceIntegerToFloat;
+    pos;
+    view;
+    bytes;
+    entered = false;
     constructor(options) {
-        this.entered = false;
         this.extensionCodec = options?.extensionCodec ?? ExtensionCodec.defaultCodec;
         this.context = options?.context; // needs a type assertion because EncoderOptions has no context property when ContextType is undefined
         this.useBigInt64 = options?.useBigInt64 ?? false;
@@ -892,9 +910,12 @@ function prettyByte(byte) {
 const DEFAULT_MAX_KEY_LENGTH = 16;
 const DEFAULT_MAX_LENGTH_PER_KEY = 16;
 class CachedKeyDecoder {
+    hit = 0;
+    miss = 0;
+    caches;
+    maxKeyLength;
+    maxLengthPerKey;
     constructor(maxKeyLength = DEFAULT_MAX_KEY_LENGTH, maxLengthPerKey = DEFAULT_MAX_LENGTH_PER_KEY) {
-        this.hit = 0;
-        this.miss = 0;
         this.maxKeyLength = maxKeyLength;
         this.maxLengthPerKey = maxLengthPerKey;
         // avoid `new Array(N)`, which makes a sparse array,
@@ -957,10 +978,8 @@ const mapKeyConverter = (key) => {
     throw new DecodeError("The type of key must be string or number but " + typeof key);
 };
 class StackPool {
-    constructor() {
-        this.stack = [];
-        this.stackHeadPosition = -1;
-    }
+    stack = [];
+    stackHeadPosition = -1;
     get length() {
         return this.stackHeadPosition + 1;
     }
@@ -1039,14 +1058,25 @@ catch (e) {
 const MORE_DATA = new RangeError("Insufficient data");
 const sharedCachedKeyDecoder = new CachedKeyDecoder();
 class Decoder {
+    extensionCodec;
+    context;
+    useBigInt64;
+    rawStrings;
+    maxStrLength;
+    maxBinLength;
+    maxArrayLength;
+    maxMapLength;
+    maxExtLength;
+    keyDecoder;
+    mapKeyConverter;
+    totalPos = 0;
+    pos = 0;
+    view = EMPTY_VIEW;
+    bytes = EMPTY_BYTES;
+    headByte = HEAD_BYTE_REQUIRED;
+    stack = new StackPool();
+    entered = false;
     constructor(options) {
-        this.totalPos = 0;
-        this.pos = 0;
-        this.view = EMPTY_VIEW;
-        this.bytes = EMPTY_BYTES;
-        this.headByte = HEAD_BYTE_REQUIRED;
-        this.stack = new StackPool();
-        this.entered = false;
         this.extensionCodec = options?.extensionCodec ?? ExtensionCodec.defaultCodec;
         this.context = options?.context; // needs a type assertion because EncoderOptions has no context property when ContextType is undefined
         this.useBigInt64 = options?.useBigInt64 ?? false;
@@ -1669,7 +1699,7 @@ class Decoder {
  * It decodes a single MessagePack object in a buffer.
  *
  * This is a synchronous decoding function.
- * See other variants for asynchronous decoding: {@link decodeAsync}, {@link decodeStream}, or {@link decodeArrayStream}.
+ * See other variants for asynchronous decoding: {@link decodeAsync}, {@link decodeMultiStream}, or {@link decodeArrayStream}.
  *
  * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
  * @throws {@link DecodeError} if the buffer contains invalid data.
@@ -1679,12 +1709,19 @@ function decode(buffer, options) {
     return decoder.decode(buffer);
 }
 
-// Custom conflict-free replicated data type system with vector clocks
+/**
+ * Heartbeat ping interval in milliseconds
+ * Also used as the minimum age for CRDT garbage collection - operations are
+ * retained for at least one heartbeat cycle to ensure even slow clients can never 
+ * be desynced as a result of gc
+ */
+const HEARTBEAT_INTERVAL = 5000;
 
 const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
 
 /**
  * CRDT Manager
+ * Custom conflict-free replicated data type system with vector clocks
  */
 class CRDTManager {
     // Storage
@@ -1692,7 +1729,7 @@ class CRDTManager {
     #keyOperations = new Map();
     #vectorClock = new Map();
 
-    #propertyStore = {}; // Current local values per key, as object
+    #propertyStore = {}; // Current local values as key/value store object
     #lastPropertyStore = {}; // Last property store to compare against
 
     // Local Garbage Collection
@@ -1835,7 +1872,6 @@ class CRDTManager {
      */
     #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
 
         try {
             if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
@@ -1847,7 +1883,7 @@ class CRDTManager {
                 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) {
+                    if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > HEARTBEAT_INTERVAL) {
                         const removeCount = index + 1;
                         retainCount = operations.length - removeCount;
                         this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
@@ -2041,7 +2077,7 @@ class CRDTManager {
      * Get property store
      * @returns {Record<string, any>} - Object with key value pairs
      */
-    get getPropertyStore() {
+    get propertyStore() {
         try {
             return structuredClone(this.#propertyStore); // Return deep clone
         } catch {
@@ -2070,7 +2106,7 @@ class CRDTManager {
      * Export state (can be imported using importState, converts the maps to arrays for serialization)
      * @returns {object} - State
      */
-    get getState() {
+    get state() {
         return {
             keyOperations: [...this.#keyOperations.entries()],
             vectorClock: [...this.#vectorClock.entries()]
@@ -2098,7 +2134,7 @@ class PlaySocket {
     // Room properties
     #roomHost;
     #inRoom; // If the client is currently in  a room or not
-    #connectionCount = 0;
+    #participantCount = 0;
     #crdtManager;
     #roomVersion = 0; // Update version (used to compare local vs. remote state to detect package loss)
 
@@ -2154,7 +2190,7 @@ class PlaySocket {
      * @param {Function} callback - Callback function
      */
     onEvent(event, callback) {
-        const validEvents = ["status", "error", "instanceDestroyed", "storageUpdated", "hostMigrated", "clientConnected", "clientDisconnected"];
+        const validEvents = ["status", "error", "moved", "instanceDestroyed", "storageUpdated", "hostMigrated", "clientJoined", "clientLeft"];
         if (!validEvents.includes(event)) {
             console.warn(WARNING_PREFIX + `Invalid event type "${event}".`);
             return;
@@ -2245,64 +2281,59 @@ class PlaySocket {
 
                 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);
-                        }
+                        this.#triggerEvent("error", "Failed to register: " + message.reason);
+                        if (this.#pendingRegistration) this.#pendingRegistration.reject(new 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.");
-                        }
+                        this.#sessionToken = message.sessionToken;
+                        this.#initialized = true;
+                        if (this.#pendingRegistration) this.#pendingRegistration.resolve(message.id);
+                        this.#triggerEvent("status", "Connected to server.");
                         break;
 
                     case 'join_accepted':
                         // Connected to room
+                        if (this.#debug) console.log(LOG_PREFIX + "State received for join:", message.state);
+                        this.#inRoom = true;
+                        this.#crdtManager.importState(message.state);
+                        this.#participantCount = message.participantCount;
+                        this.#roomHost = message.host;
+                        this.#roomVersion = message.version;
+                        this.#triggerEvent("storageUpdated", this.storage);
                         if (this.#pendingJoin) {
-                            if (this.#debug) console.log(LOG_PREFIX + "State received for join:", message.state);
-                            this.#inRoom = true;
-                            this.#crdtManager.importState(message.state);
-                            this.#connectionCount = message.participantCount - 1; // Counted without the user themselves
-                            this.#roomHost = message.host;
-                            this.#roomVersion = message.version;
-                            this.#triggerEvent("storageUpdated", this.getStorage);
-                            this.#triggerEvent("status", `Connected to room.`);
+                            this.#triggerEvent("status", "Connected to room.");
                             this.#pendingJoin.resolve();
+                        } else {
+                            this.#triggerEvent("status", "Moved to room.");
+                            this.#triggerEvent("moved", message.roomId);
                         }
                         break;
 
                     case 'join_rejected':
                         // Connection to room failed
-                        if (this.#pendingJoin) {
-                            this.#triggerEvent("status", "Failed to join room: " + message.reason);
-                            this.#pendingJoin.reject(new Error("Failed to join room: " + message.reason));
-                        }
+                        this.#triggerEvent("status", "Failed to join room: " + message.reason);
+                        if (this.#pendingJoin) this.#pendingJoin.reject(new Error("Failed to join room: " + message.reason));
                         break;
 
                     case 'reconnected':
                         // Successfully reconnected
-                        if (this.#pendingReconnect) {
-                            this.#isReconnecting = false;
-                            this.#reconnectCount = 0;
-                            if (message.roomData) {
-                                if (this.#debug) console.log(LOG_PREFIX + "State received for reconnect:", message.roomData.state);
-                                this.#crdtManager.importState(message.roomData.state);
-                                this.#roomVersion = message.roomData.version;
-                                this.#connectionCount = message.roomData.participantCount - 1; // Counted without the user themselves
-                                this.#setHost(message.roomData.host); // Set host before in case there are .isHost checks in the storageUpdate fallback
-                                this.#triggerEvent("storageUpdated", this.getStorage);
-                            } else if (this.#inRoom) {
-                                // If no room data received, but client thinks they were in a room...
-                                this.#triggerEvent("error", "Reconnected, but room no longer exists.");
-                                return this.destroy();
-                            }
-                            this.#triggerEvent("status", "Reconnected.");
-                            this.#pendingReconnect.resolve();
+                        this.#isReconnecting = false;
+                        this.#reconnectCount = 0;
+                        if (message.roomData) {
+                            if (this.#debug) console.log(LOG_PREFIX + "State received for reconnect:", message.roomData.state);
+                            this.#crdtManager.importState(message.roomData.state);
+                            this.#roomVersion = message.roomData.version;
+                            this.#participantCount = message.roomData.participantCount;
+                            this.#setHost(message.roomData.host); // Set host before in case there are .isHost checks in the storageUpdate fallback
+                            this.#triggerEvent("storageUpdated", this.storage);
+                        } else if (this.#inRoom) {
+                            // If no room data received, but client thinks they were in a room...
+                            this.#triggerEvent("error", "Reconnected, but room no longer exists.");
+                            return this.destroy();
                         }
+                        this.#triggerEvent("status", "Reconnected.");
+                        if (this.#pendingReconnect) this.#pendingReconnect.resolve();
                         break;
 
                     case 'reconnection_failed':
@@ -2310,27 +2341,24 @@ class PlaySocket {
                         break;
 
                     case 'room_created':
-                        if (this.#pendingCreate) {
-                            this.#inRoom = true;
-                            this.#triggerEvent("status", `Room created.`);
-                            this.#crdtManager.importState(message.state);
-                            this.#triggerEvent("storageUpdated", this.getStorage);
-                            this.#pendingCreate.resolve(message.roomId);
-                        }
+                        this.#inRoom = true;
+                        this.#participantCount = message.participantCount;
+                        this.#triggerEvent("status", `Room created.`);
+                        this.#crdtManager.importState(message.state);
+                        this.#triggerEvent("storageUpdated", this.storage);
+                        if (this.#pendingCreate) this.#pendingCreate.resolve(message.roomId);
                         break;
 
                     case 'room_creation_failed':
-                        if (this.#pendingCreate) {
-                            this.#triggerEvent("error", "Failed to create room: " + message.reason);
-                            this.#pendingCreate.reject(new Error("Failed to create room: " + message.reason));
-                        }
+                        this.#triggerEvent("error", "Failed to create room: " + message.reason);
+                        if (this.#pendingCreate) this.#pendingCreate.reject(new Error("Failed to create room: " + message.reason));
                         break;
 
                     case 'property_updated':
                         this.#roomVersion++; // Increment room version
                         if (this.#debug) console.log(LOG_PREFIX + "Property update received:", message.update);
                         this.#crdtManager.importPropertyUpdate(message.update);
-                        if (this.#crdtManager.didPropertiesChange) this.#triggerEvent("storageUpdated", this.getStorage);
+                        if (this.#crdtManager.didPropertiesChange) this.#triggerEvent("storageUpdated", this.storage);
                         if (this.#roomVersion != message.version && this.#initialized && this.#socket?.readyState === WebSocket.OPEN) {
                             this.#triggerEvent("error", "Detected skipped update – forcing reconnect.");
                             this.#socket?.close();
@@ -2340,7 +2368,7 @@ class PlaySocket {
                     case 'property_update_rejected':
                         this.#triggerEvent("error", "Property update rejected. Re-syncing state.");
                         this.#crdtManager.importState(message.state);
-                        this.#triggerEvent("storageUpdated", this.getStorage);
+                        this.#triggerEvent("storageUpdated", this.storage);
                         break;
 
                     case 'kicked':
@@ -2352,15 +2380,15 @@ class PlaySocket {
                         this.#setHost(message.newHost);
                         break;
 
-                    case 'client_disconnected':
-                        this.#connectionCount = message.participantCount - 1; // Counted without the user themselves
-                        this.#triggerEvent("clientDisconnected", message.client);
+                    case 'client_left':
+                        this.#participantCount = message.participantCount;
+                        this.#triggerEvent("clientLeft", message.client);
                         this.#triggerEvent("status", `Client ${message.client} disconnected.`);
                         break;
 
-                    case 'client_connected':
-                        this.#connectionCount = message.participantCount - 1; // Counted without the user themselves
-                        this.#triggerEvent("clientConnected", message.client);
+                    case 'client_joined':
+                        this.#participantCount = message.participantCount;
+                        this.#triggerEvent("clientJoined", message.client);
                         this.#triggerEvent("status", `Client ${message.client} connected.`);
                         break;
                 }
@@ -2523,7 +2551,7 @@ class PlaySocket {
             type: 'update_property',
             update: propUpdate
         });
-        if (this.#crdtManager.didPropertiesChange) this.#triggerEvent("storageUpdated", this.getStorage); // Always trigger callback AFTER send in case msgs are sent in the callback (which would break the order)
+        if (this.#crdtManager.didPropertiesChange) this.#triggerEvent("storageUpdated", this.storage); // Always trigger callback AFTER send in case msgs are sent in the callback (which would break the order)
     }
 
     /**
@@ -2563,7 +2591,7 @@ class PlaySocket {
         clearTimeout(this.#reconnectTimeout);
         this.#roomHost = null;
         this.#inRoom = false;
-        this.#connectionCount = 0;
+        this.#participantCount = 0;
         this.#isReconnecting = false;
         this.#reconnectCount = 0;
         this.#roomVersion = 0;
@@ -2577,8 +2605,8 @@ class PlaySocket {
     }
 
     // Public getters
-    get connectionCount() { return this.#connectionCount; }
-    get getStorage() { return this.#crdtManager.getPropertyStore; }
+    get participantCount() { return this.#participantCount; }
+    get storage() { return this.#crdtManager.propertyStore; }
     get isHost() { return this.#id == this.#roomHost; }
     get id() { return this.#id; }
 }

package/dist/playsocket-server.js

@@ -173,6 +173,8 @@ function utf8Decode(bytes, inputOffset, byteLength) {
  * ExtData is used to handle Extension Types that are not registered to ExtensionCodec.
  */
 class ExtData {
+    type;
+    data;
     constructor(type, data) {
         this.type = type;
         this.data = data;
@@ -316,13 +318,18 @@ const timestampExtension = {
 
 // ExtensionCodec to handle MessagePack extensions
 class ExtensionCodec {
+    static defaultCodec = new ExtensionCodec();
+    // ensures ExtensionCodecType<X> matches ExtensionCodec<X>
+    // this will make type errors a lot more clear
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    __brand;
+    // built-in extensions
+    builtInEncoders = [];
+    builtInDecoders = [];
+    // custom extensions
+    encoders = [];
+    decoders = [];
     constructor() {
-        // built-in extensions
-        this.builtInEncoders = [];
-        this.builtInDecoders = [];
-        // custom extensions
-        this.encoders = [];
-        this.decoders = [];
         this.register(timestampExtension);
     }
     register({ type, encode, decode, }) {
@@ -378,7 +385,6 @@ class ExtensionCodec {
         }
     }
 }
-ExtensionCodec.defaultCodec = new ExtensionCodec();
 
 function isArrayBufferLike(buffer) {
     return (buffer instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && buffer instanceof SharedArrayBuffer));
@@ -402,8 +408,20 @@ function ensureUint8Array(buffer) {
 const DEFAULT_MAX_DEPTH = 100;
 const DEFAULT_INITIAL_BUFFER_SIZE = 2048;
 class Encoder {
+    extensionCodec;
+    context;
+    useBigInt64;
+    maxDepth;
+    initialBufferSize;
+    sortKeys;
+    forceFloat32;
+    ignoreUndefined;
+    forceIntegerToFloat;
+    pos;
+    view;
+    bytes;
+    entered = false;
     constructor(options) {
-        this.entered = false;
         this.extensionCodec = options?.extensionCodec ?? ExtensionCodec.defaultCodec;
         this.context = options?.context; // needs a type assertion because EncoderOptions has no context property when ContextType is undefined
         this.useBigInt64 = options?.useBigInt64 ?? false;
@@ -895,9 +913,12 @@ function prettyByte(byte) {
 const DEFAULT_MAX_KEY_LENGTH = 16;
 const DEFAULT_MAX_LENGTH_PER_KEY = 16;
 class CachedKeyDecoder {
+    hit = 0;
+    miss = 0;
+    caches;
+    maxKeyLength;
+    maxLengthPerKey;
     constructor(maxKeyLength = DEFAULT_MAX_KEY_LENGTH, maxLengthPerKey = DEFAULT_MAX_LENGTH_PER_KEY) {
-        this.hit = 0;
-        this.miss = 0;
         this.maxKeyLength = maxKeyLength;
         this.maxLengthPerKey = maxLengthPerKey;
         // avoid `new Array(N)`, which makes a sparse array,
@@ -960,10 +981,8 @@ const mapKeyConverter = (key) => {
     throw new DecodeError("The type of key must be string or number but " + typeof key);
 };
 class StackPool {
-    constructor() {
-        this.stack = [];
-        this.stackHeadPosition = -1;
-    }
+    stack = [];
+    stackHeadPosition = -1;
     get length() {
         return this.stackHeadPosition + 1;
     }
@@ -1042,14 +1061,25 @@ catch (e) {
 const MORE_DATA = new RangeError("Insufficient data");
 const sharedCachedKeyDecoder = new CachedKeyDecoder();
 class Decoder {
+    extensionCodec;
+    context;
+    useBigInt64;
+    rawStrings;
+    maxStrLength;
+    maxBinLength;
+    maxArrayLength;
+    maxMapLength;
+    maxExtLength;
+    keyDecoder;
+    mapKeyConverter;
+    totalPos = 0;
+    pos = 0;
+    view = EMPTY_VIEW;
+    bytes = EMPTY_BYTES;
+    headByte = HEAD_BYTE_REQUIRED;
+    stack = new StackPool();
+    entered = false;
     constructor(options) {
-        this.totalPos = 0;
-        this.pos = 0;
-        this.view = EMPTY_VIEW;
-        this.bytes = EMPTY_BYTES;
-        this.headByte = HEAD_BYTE_REQUIRED;
-        this.stack = new StackPool();
-        this.entered = false;
         this.extensionCodec = options?.extensionCodec ?? ExtensionCodec.defaultCodec;
         this.context = options?.context; // needs a type assertion because EncoderOptions has no context property when ContextType is undefined
         this.useBigInt64 = options?.useBigInt64 ?? false;
@@ -1672,7 +1702,7 @@ class Decoder {
  * It decodes a single MessagePack object in a buffer.
  *
  * This is a synchronous decoding function.
- * See other variants for asynchronous decoding: {@link decodeAsync}, {@link decodeStream}, or {@link decodeArrayStream}.
+ * See other variants for asynchronous decoding: {@link decodeAsync}, {@link decodeMultiStream}, or {@link decodeArrayStream}.
  *
  * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
  * @throws {@link DecodeError} if the buffer contains invalid data.
@@ -1682,12 +1712,19 @@ function decode(buffer, options) {
     return decoder.decode(buffer);
 }
 
-// Custom conflict-free replicated data type system with vector clocks
+/**
+ * Heartbeat ping interval in milliseconds
+ * Also used as the minimum age for CRDT garbage collection - operations are
+ * retained for at least one heartbeat cycle to ensure even slow clients can never 
+ * be desynced as a result of gc
+ */
+const HEARTBEAT_INTERVAL = 5000;
 
 const CONSOLE_PREFIX = "PlaySocket CRDT manager: ";
 
 /**
  * CRDT Manager
+ * Custom conflict-free replicated data type system with vector clocks
  */
 class CRDTManager {
     // Storage
@@ -1695,7 +1732,7 @@ class CRDTManager {
     #keyOperations = new Map();
     #vectorClock = new Map();
 
-    #propertyStore = {}; // Current local values per key, as object
+    #propertyStore = {}; // Current local values as key/value store object
     #lastPropertyStore = {}; // Last property store to compare against
 
     // Local Garbage Collection
@@ -1838,7 +1875,6 @@ class CRDTManager {
      */
     #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
 
         try {
             if (Date.now() - this.#lastGCCheck < MIN_GC_DELAY) return;
@@ -1850,7 +1886,7 @@ class CRDTManager {
                 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) {
+                    if (op.uuid && this.#opUuidTimestamp.has(op.uuid) && (Date.now() - this.#opUuidTimestamp.get(op.uuid)) > HEARTBEAT_INTERVAL) {
                         const removeCount = index + 1;
                         retainCount = operations.length - removeCount;
                         this.#opUuidTimestamp.delete(op.uuid); // Remove from timestamps if set to be deleted
@@ -2044,7 +2080,7 @@ class CRDTManager {
      * Get property store
      * @returns {Record<string, any>} - Object with key value pairs
      */
-    get getPropertyStore() {
+    get propertyStore() {
         try {
             return structuredClone(this.#propertyStore); // Return deep clone
         } catch {
@@ -2073,7 +2109,7 @@ class CRDTManager {
      * Export state (can be imported using importState, converts the maps to arrays for serialization)
      * @returns {object} - State
      */
-    get getState() {
+    get state() {
         return {
             keyOperations: [...this.#keyOperations.entries()],
             vectorClock: [...this.#vectorClock.entries()]
@@ -2084,6 +2120,7 @@ class CRDTManager {
 /* eslint-disable jsdoc/require-returns */
 
 const MAX_ROOM_SIZE = 500;
+const RECONNECT_GRACE_PERIOD = 5000; // Exported for use in tests
 
 /**
  * @typedef {import('node:http').Server} HttpServer
@@ -2170,7 +2207,7 @@ class PlaySocketServer {
                 ws.isAlive = false;
                 ws.ping();
             });
-        }, 15000);
+        }, HEARTBEAT_INTERVAL);
     }
 
     /**
@@ -2262,9 +2299,9 @@ class PlaySocketServer {
                             // If the room has no host (they were the only one and disconnected), restore them as host
                             if (formerRoom.host === null) formerRoom.host = data.id;
 
-                            if (this.#debug) console.log(`State sent for reconnection for room ${formerRoomId}:`, formerRoom.crdtManager.getState);
+                            if (this.#debug) console.log(`State sent for reconnection for room ${formerRoomId}:`, formerRoom.crdtManager.state);
                             roomData = {
-                                state: formerRoom.crdtManager.getState,
+                                state: formerRoom.crdtManager.state,
                                 participantCount: formerRoom.participants.length,
                                 host: formerRoom.host,
                                 version: this.#roomVersions.get(formerRoomId)
@@ -2306,7 +2343,7 @@ class PlaySocketServer {
 
                         this.#rooms[newRoom.id].participants.push(ws.clientId); // Add client to the room
                         this.#clientRooms.set(ws.clientId, newRoom.id); // Add client to the client-room map
-                        ws.send(encode({ type: 'room_created', state: newRoom.state, roomId: newRoom.id }), { binary: true });
+                        ws.send(encode({ type: 'room_created', state: newRoom.state, roomId: newRoom.id, participantCount: this.#rooms[newRoom.id].participants.length }), { binary: true });
                     } catch (error) {
                         console.error("PlaySocket error creating room:", error);
                         ws.send(encode({ type: 'room_creation_failed', reason: error.message }), { binary: true });
@@ -2317,7 +2354,6 @@ class PlaySocketServer {
                 case 'join_room': {
                     if (!data.roomId || !ws.clientId) return;
                     const roomId = data.roomId;
-                    const room = this.#rooms[roomId];
 
                     const rejectJoin = (reason) => {
                         ws.send(encode({ type: 'join_rejected', reason }), { binary: true });
@@ -2327,47 +2363,12 @@ class PlaySocketServer {
                     const joinAllowed = await this.#triggerEvent("clientJoinRequested", ws.clientId, roomId);
                     if (joinAllowed === false || typeof joinAllowed === 'string') return rejectJoin(typeof joinAllowed === 'string' ? joinAllowed : 'Denied.');
 
-                    if (!room) return rejectJoin("Room not found.");
-                    if (this.#clientRooms.get(ws.clientId)) return rejectJoin("Already in a room.");
-                    if (room.participants.length >= room.size) return rejectJoin("Room full.");
-
-                    room.participants.push(ws.clientId);
-                    this.#clientRooms.set(ws.clientId, roomId);
-
-                    // Notify joiner with initial storage
-                    if (this.#debug) console.log("Room state sent for join:", room.crdtManager.getState);
-                    ws.send(encode({
-                        type: 'join_accepted',
-                        state: room.crdtManager.getState,
-                        participantCount: room.participants.length,
-                        host: room.host,
-                        version: this.#roomVersions.get(roomId)
-                    }), { binary: true });
-
-                    // If the room has no host (previous host disconnected and was the only participant), make joiner the host
-                    // Since the room had to be empty, only the joiner needs to be notified
-                    const becameHost = room.host === null;
-                    if (becameHost) {
-                        room.host = ws.clientId;
-                        ws.send(encode({
-                            type: 'host_migrated',
-                            newHost: room.host,
-                        }), { binary: true });
+                    try {
+                        this.#joinRoom(ws.clientId, roomId);
+                    } catch (error) {
+                        rejectJoin(error.message);
                     }
 
-                    // Notify existing participants
-                    room.participants.forEach(p => {
-                        if (p === ws.clientId) return;
-                        const client = this.#clients.get(p);
-                        if (client) {
-                            client.send(encode({
-                                type: 'client_connected',
-                                client: ws.clientId,
-                                participantCount: room.participants.length
-                            }), { binary: true });
-                        }
-                    });
-                    this.#triggerEvent("clientJoinedRoom", ws.clientId, roomId);
                     break;
                 }
 
@@ -2381,7 +2382,7 @@ class PlaySocketServer {
                         if (updateAllowed === false) {
                             ws.send(encode({
                                 type: 'property_update_rejected',
-                                state: room.crdtManager.getState
+                                state: room.crdtManager.state
                             }), { binary: true });
                             return;
                         }
@@ -2436,29 +2437,28 @@ 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 - ID of the room that the disconnected client was in
-     * @param {string} clientId - ID of the disconnected client
+     * Migrate the host role to another participant
+     * @param {string} roomId - ID of the room
+     * @param {string} clientId - ID of the current host
      */
-    #changeHostIfDisconnected(roomId, clientId) {
+    #migrateHost(roomId, clientId) {
         const room = this.#rooms[roomId];
-        if (room && room.host === clientId) {
-            const participantsWithoutClient = room.participants.filter((e) => e !== clientId);
-
-            if (participantsWithoutClient.length >= 1) {
-                room.host = participantsWithoutClient[0]; // Set new host
-
-                // Inform all participants about the new host
-                participantsWithoutClient.forEach(p => {
-                    const client = this.#clients.get(p);
-                    if (client) client.send(encode({
-                        type: 'host_migrated',
-                        newHost: room.host,
-                    }), { binary: true });
-                });
-            } else room.host = null; // The next person to join will become the host
-        }
+        if (!room) throw new Error("Room not found.");
+        if (room.host !== clientId) throw new Error("Client is not the host.");
+
+        const remainingParticipants = room.participants.filter(p => p !== clientId);
+
+        if (remainingParticipants.length >= 1) {
+            // Inform all participants about the new host
+            room.host = remainingParticipants[0];
+            remainingParticipants.forEach(p => {
+                const client = this.#clients.get(p);
+                if (client) client.send(encode({
+                    type: 'host_migrated',
+                    newHost: room.host,
+                }), { binary: true });
+            });
+        } else room.host = null; // The next person to join will become the host
     }
 
     /**
@@ -2514,16 +2514,15 @@ class PlaySocketServer {
 
             // If client was in a room, check if they were the host & migrate
             const roomId = this.#clientRooms.get(ws.clientId);
-            if (roomId != null) this.#changeHostIfDisconnected(roomId, ws.clientId);
+            if (roomId != null && this.#rooms[roomId]?.host === ws.clientId) this.#migrateHost(roomId, ws.clientId);
 
-            if (ws.willfulDisconnect) {
-                this.#disconnectClient(ws); // Immediate disconnection
-            } else {
+            if (ws.willfulDisconnect) this.#disconnectClient(ws); // Immediate disconnection
+            else {
                 // Pending complete disconnection with 5s grace period to allow for reconnections
                 this.#pendingDisconnects.set(ws.clientId, {
                     timeout: setTimeout(() => {
                         this.#disconnectClient(ws);
-                    }, 5000)
+                    }, RECONNECT_GRACE_PERIOD)
                 });
             }
         }
@@ -2537,29 +2536,8 @@ class PlaySocketServer {
     #disconnectClient(ws) {
         this.#pendingDisconnects.delete(ws.clientId);
         this.#clientTokens.delete(ws.clientId);
-        let roomId = this.#clientRooms.get(ws.clientId);
-        const room = this.#rooms[roomId];
-
-        if (room) {
-            room.participants = room.participants.filter(p => p !== ws.clientId); // Remove client from room
-            this.#clientRooms.delete(ws.clientId);
-
-            if (room.participants?.length === 0 && room.host !== "server") {
-                this.destroyRoom(roomId); // Destroy room if now empty & not created by server
-                roomId = null; // If room was destroyed, set roomId to null
-            } else {
-                // Notify remaining participants
-                room.participants.forEach(p => {
-                    const client = this.#clients.get(p);
-                    if (client) client.send(encode({
-                        type: 'client_disconnected',
-                        client: ws.clientId,
-                        participantCount: room.participants.length
-                    }), { binary: true });
-                });
-            }
-        }
-
+        const roomId = this.#clientRooms.get(ws.clientId);
+        if (roomId && this.#rooms[roomId]) this.#leaveRoom(ws.clientId, roomId);
         this.#triggerEvent("clientDisconnected", ws.clientId, roomId);
     }
 
@@ -2578,17 +2556,37 @@ class PlaySocketServer {
     }
 
     /**
-     * Kick a player from the server
+     * Kick a client from the server
      * @param {string} clientId - Client ID
      * @param {string} [reason] - Optional reason
      */
     kick(clientId, reason) {
         const client = this.#clients.get(clientId);
-        if (client) {
-            client.willfulDisconnect = true;
-            client.send(encode({ type: 'kicked', reason }), { binary: true });
-            client.close();
-        }
+        if (!client) return; // Client not connected, skip
+        client.willfulDisconnect = true;
+        client.send(encode({ type: 'kicked', reason }), { binary: true });
+        client.close();
+    }
+
+    /**
+     * Move client into a different room
+     * @param {string} clientId - Client ID
+     * @param {string} roomId - Room ID (Target)
+     */
+    move(clientId, roomId) {
+        const client = this.#clients.get(clientId);
+        const oldRoomId = this.#clientRooms.get(clientId);
+        const oldRoom = this.#rooms[oldRoomId];
+        const targetRoom = this.#rooms[roomId];
+        if (!client) throw new Error("Client not found.");
+        if (!oldRoomId) throw new Error("Client is not in a room.");
+        if (!oldRoom) throw new Error("Client room not found.");
+        if (oldRoomId === roomId) throw new Error("Client is already in target room.");
+        if (!targetRoom) throw new Error("Target room not found.");
+        if (targetRoom.participants.length >= targetRoom.size) throw new Error("Target room is full.");
+        if (oldRoom.host === clientId) this.#migrateHost(oldRoomId, clientId);
+        this.#leaveRoom(clientId, oldRoomId);
+        this.#joinRoom(clientId, roomId);
     }
 
     /**
@@ -2620,7 +2618,7 @@ class PlaySocketServer {
      */
     getRoomStorage(roomId) {
         const room = this.#rooms[roomId];
-        if (room) return room.crdtManager.getPropertyStore;
+        if (room) return room.crdtManager.propertyStore;
     }
 
     /**
@@ -2654,7 +2652,7 @@ class PlaySocketServer {
     }
 
     /**
-     * Create a room from the server
+     * Create a room
      * @param {object} [initialStorage] - Optional initial storage object
      * @param {number} [size] - Max. room size, up to 500
      * @param {string} [host] - Host ID, defaults to "server" (when set to "server", room will not be deleted if all clients leave)
@@ -2671,7 +2669,7 @@ class PlaySocketServer {
             }
         }
 
-        if (!newRoomId) throw new Error("No available ID found.")
+        if (!newRoomId) throw new Error("No available ID found.");
         const roomCrdtManager = new CRDTManager(this.#debug);
 
         if (initialStorage) Object.entries(initialStorage)?.forEach(([key, value]) => {
@@ -2688,7 +2686,82 @@ class PlaySocketServer {
 
         this.#triggerEvent("roomCreated", newRoomId);
         if (this.#debug) console.log(`Room ${newRoomId} created with initial storage:`, initialStorage);
-        return { state: roomCrdtManager.getState, id: newRoomId };
+        return { state: roomCrdtManager.state, id: newRoomId };
+    }
+
+    /**
+     * Make a client join a room
+     * @param {string} clientId - Client ID
+     * @param {string} roomId - Room ID
+     */
+    #joinRoom(clientId, roomId) {
+        const room = this.#rooms[roomId];
+        const client = this.#clients.get(clientId);
+        if (!room) throw new Error("Room not found.");
+        if (!client) throw new Error("Client not found.");
+        if (this.#clientRooms.get(clientId)) throw new Error("Already in a room.");
+        if (room.participants.length >= room.size) throw new Error("Room full.");
+
+        room.participants.push(clientId);
+        this.#clientRooms.set(clientId, roomId);
+
+        // Notify joiner with initial storage
+        if (this.#debug) console.log("Room state sent for join:", room.crdtManager.state);
+        client.send(encode({
+            type: 'join_accepted',
+            roomId,
+            state: room.crdtManager.state,
+            participantCount: room.participants.length,
+            host: room.host,
+            version: this.#roomVersions.get(roomId)
+        }), { binary: true });
+
+        // If the room has no host (previous host disconnected and was the only participant), make joiner the host
+        // Since the room had to be empty, only the joiner needs to be notified
+        const becameHost = room.host === null;
+        if (becameHost) {
+            room.host = clientId;
+            client.send(encode({
+                type: 'host_migrated',
+                newHost: room.host,
+            }), { binary: true });
+        }
+
+        // Notify existing participants
+        room.participants.forEach(p => {
+            if (p === clientId) return;
+            const client = this.#clients.get(p);
+            if (client) {
+                client.send(encode({
+                    type: 'client_joined',
+                    client: clientId,
+                    participantCount: room.participants.length
+                }), { binary: true });
+            }
+        });
+        this.#triggerEvent("clientJoinedRoom", clientId, roomId);
+    }
+
+    #leaveRoom(clientId, roomId) {
+        const room = this.#rooms[roomId];
+        if (!room) throw new Error("Room not found.");
+
+        room.participants = room.participants.filter(p => p !== clientId); // Remove client from room
+        this.#clientRooms.delete(clientId);
+
+        if (room.participants.length === 0 && room.host !== "server") {
+            this.destroyRoom(roomId); // Destroy room if now empty & not by server
+        } else {
+            // Notify remaining participants
+            room.participants.forEach(p => {
+                const client = this.#clients.get(p);
+                if (client) client.send(encode({
+                    type: 'client_left',
+                    client: clientId,
+                    participantCount: room.participants.length
+                }), { binary: true });
+            });
+        }
     }
 
     /**
@@ -2697,9 +2770,9 @@ class PlaySocketServer {
      */
     destroyRoom(roomId) {
         const room = this.#rooms[roomId];
-        if (!room) return; // Return if room does not exist
+        if (!room) throw new Error("Room not found.");
 
-        // Disconnect participants if still in room
+        // Disconnect clients if still in room
         const participants = room.participants;
         participants.forEach((clientId) => {
             this.kick(clientId, "Room destroyed by server.");
@@ -2727,7 +2800,7 @@ class PlaySocketServer {
         });
     }
 
-    get getRooms() { return { ...this.#rooms } }
+    get rooms() { return structuredClone(this.#rooms) }
 }
 
-export { PlaySocketServer as default };
+export { RECONNECT_GRACE_PERIOD, PlaySocketServer as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playsocketjs",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
   "type": "module",
   "module": "dist/playsocket-client.js",
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "start": "node example/example-server.js",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "npm run build && npx playwright test --config e2e/playwright.config.js",
+    "test:headed": "npm run build && npx playwright test --config e2e/playwright.config.js --headed",
     "build": "rollup -c rollup.config.js",
     "lint": "eslint ./src"
   },
@@ -39,11 +40,12 @@
   },
   "homepage": "https://github.com/therealPaulPlay/PlaySocketJS#readme",
   "devDependencies": {
+    "@playwright/test": "^1.58.1",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "eslint": "^9.35.0",
     "eslint-plugin-jsdoc": "^54.4.0",
-    "rollup": "^4.31.0",
-    "globals": "^16.3.0"
+    "globals": "^16.3.0",
+    "rollup": "^4.31.0"
   },
   "peerDependencies": {
     "ws": "^8.18.1"
@@ -51,4 +53,4 @@
   "dependencies": {
     "@msgpack/msgpack": "^3.1.1"
   }
-}
+}