playsocketjs 5.0.0 → 5.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 An optimistic-first WebSocket synchronization library. Built for creating multiplayer games & collaborative experiences with reactive web frameworks.
 
+For an introduction to PlaySocket, visit the [PlaySocket website](https://therealpaulplay.github.io/PlaySocketJS/).
+
 ## Why use PlaySocket?
 
 PlaySocket makes developing shared experiences a breeze:
@@ -140,9 +142,9 @@ new PlaySocket(id?: string, options: PlaySocketOptions)
 | `moved` | `roomId: string` | Moved to different room. |
 | `instanceDestroyed` | `reason: string` | Instance destroyed through `destroy()` or error. |
 | `storageUpdated` | `storage: object` | Storage state changed. Does not trigger on no-op updates. |
-| `hostMigrated` | `roomId: string` | Host was changed. |
+| `hostMigrated` | `hostId: string` | Host was changed. |
 | `clientJoined` | `clientId: string` | New client joined the room. |
-| `clientLeft` | `clientId: string, roomId?: string` | A client left the room. |
+| `clientLeft` | `clientId: string` | A client left the room. |
 
 #### Properties
 
@@ -313,7 +315,7 @@ The callback signature is `callback(verified, code?, message?)` where `code` ref
 | `kick()` | `clientId: string, reason?: string` | `void` | Kick a client by their client ID. |
 | `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. Returns unsubscribe function. |
-| `getRoomStorage()` | `roomId: string` | `object` | Get a snapshot of the current room storage. |
+| `getRoomStorage()` | `roomId: string, options?: { dangerouslySkipCloning?: boolean }` | `object` | Get a snapshot of the current room storage. Pass `dangerouslySkipCloning: true` to get the uncloned store for performance reasons. |
 | `getUpdateDetails()` | `update: object` | `object` | Get the details (`key`, `type`, `value` and `secondValue`) of a storage update for building validation logic. |
 | `updateRoomStorage()` | `roomId: string, key: string, type: string, value: any, secondValue?: any` | `void` | Update a key in the shared storage of a room. |
 | `createRoom()` | `initialStorage?: object, size?: number` | `object` | Create a server-owned room (returns object containing room ID and state).|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playsocketjs",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "WebSocket wrapper for creating simple multiplayer systems with ease.",
   "type": "module",
   "module": "./src/client/client.js",

package/src/client/client.js

@@ -20,6 +20,18 @@ const TIMEOUT_MS = 3000; // 3 second timeout for WS messages
 
 /** @typedef {{ resolve: (value?: any) => void, reject: (reason?: any) => void }} PendingPromise */
 
+/**
+ * Event callback types
+ * @typedef {object} ClientEventMap
+ * @property {(message: string) => void} status
+ * @property {(roomId: string) => void} moved
+ * @property {(reason: string | undefined) => void} instanceDestroyed
+ * @property {(storage: Record<string, any>) => void} storageUpdated
+ * @property {(hostId: string) => void} hostMigrated
+ * @property {(clientId: string) => void} clientJoined
+ * @property {(clientId: string) => void} clientLeft
+ */
+
 /**
  * PlaySocket Client
  */
@@ -75,11 +87,11 @@ export default class PlaySocket {
 
     /**
      * Create a new PlaySocket instance
-     * @param {string} [id] - Unique identifier for this client (assigned by the server if omitted)
+     * @param {string | null} [id] - Unique identifier for this client (assigned by the server if omitted or null)
      * @param {PlaySocketOptions} options - Connection options
      */
     constructor(id, options = /** @type {PlaySocketOptions} */ ({})) {
-        this.#id = id;
+        this.#id = id ?? undefined;
         if (options.endpoint) this.#endpoint = options.endpoint;
         if (options.customData) this.#customData = { ...options.customData };
         if (options.debug) this.#debug = true; // Enabling extra logging
@@ -89,7 +101,7 @@ export default class PlaySocket {
     /**
      * Helper to create timeout promises for create room, join room etc.
      * @param {string} name - Name of the timeout
-     * @returns {Promise<never>} - Promise that rejects after the timeout
+     * @returns {Promise<never>} Promise that rejects after the timeout
      */
     #createTimeout(name) {
         return new Promise((_, reject) =>
@@ -99,9 +111,10 @@ export default class PlaySocket {
 
     /**
      * Register an event callback
-     * @param {string} event - Event name
-     * @param {Function} callback - Callback function
-     * @returns {Function} - Unsubscribe
+     * @template {keyof ClientEventMap} E
+     * @param {E} event - Event name
+     * @param {ClientEventMap[E]} callback - Callback function
+     * @returns {Function} Unsubscribe
      */
     onEvent(event, callback) {
         const validEvents = ["status", "moved", "instanceDestroyed", "storageUpdated", "hostMigrated", "clientJoined", "clientLeft"];
@@ -396,11 +409,11 @@ export default class PlaySocket {
 
     /**
      * Create a new room and become host
-     * @param {object} [initialStorage] - Initial state
+     * @param {object | null} [initialStorage] - Initial state
      * @param {number} [size] - Max number of participants
      * @returns {Promise<string>} Resolves with room ID
      */
-    async createRoom(initialStorage = {}, size) {
+    async createRoom(initialStorage, size) {
         if (!this.#initialized) throw new Error("Not initialized");
 
         return /** @type {Promise<string>} */ (Promise.race([
@@ -422,7 +435,7 @@ export default class PlaySocket {
     /**
      * Join an existing room
      * @param {string} roomId - ID of the room
-     * @returns {Promise<void>} - Resolves when connected
+     * @returns {Promise<void>} Resolves when connected
      */
     async joinRoom(roomId) {
         if (!this.#initialized) throw new Error("Not initialized");
@@ -469,7 +482,7 @@ export default class PlaySocket {
      * Send a custom request to the server
      * @param {string} name - Name of the request
      * @param {*} [data] - Custom data
-     * @returns {Promise<void>} - Request promise
+     * @returns {Promise<void>} Request promise
      */
     async sendRequest(name, data) {
         if (!this.#initialized) throw new Error("Not initialized");

package/src/server/server.js

@@ -31,6 +31,25 @@ export const RECONNECT_GRACE_PERIOD = 5000; // Exported for use in tests
  * @property {CRDTManager} crdtManager - CRDT manager holding the room storage
  */
 
+/** @typedef {boolean | string | void} RejectViaStringOrBool */
+
+/**
+ * Event callback types
+ * @typedef {object} ServerEventMap
+ * @property {(clientId: string, customData: any) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} clientRegistrationRequested
+ * @property {(clientId: string, customData: any) => void} clientRegistered
+ * @property {(clientId: string) => void} clientDisconnected
+ * @property {(clientId: string, roomId: string) => void} clientJoinedRoom
+ * @property {(clientId: string, roomId: string) => void} clientLeftRoom
+ * @property {(clientId: string, roomId: string) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} clientJoinRequested
+ * @property {(roomId: string) => void} roomCreated
+ * @property {(roomId: string) => void} roomDestroyed
+ * @property {(payload: { clientId: string, initialStorage: Record<string, any> }) => Record<string, any> | RejectViaStringOrBool | Promise<Record<string, any> | RejectViaStringOrBool>} roomCreationRequested
+ * @property {(payload: { roomId: string | null, clientId: string, name: string, data: unknown }) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} requestReceived
+ * @property {(payload: { roomId: string, clientId: string, update: PropertyUpdate, storage: Record<string, any> | undefined }) => RejectViaStringOrBool} storageUpdateRequested
+ * @property {(payload: { roomId: string, clientId: string | null, update: PropertyUpdate, storage: Record<string, any> | undefined }) => void} storageUpdated
+ */
+
 /**
  * PlaySocket Server
  */
@@ -358,7 +377,7 @@ export default class PlaySocketServer {
 
     /**
      * Generate a readable, 6 digit ID
-     * @returns {string} - Id
+     * @returns {string} Id
      */
     #generateId() {
         const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789";
@@ -392,7 +411,7 @@ export default class PlaySocketServer {
 
     /**
      * Generate a random token to prevent malicious reconnect attempts
-     * @returns {string} - Token
+     * @returns {string} Token
      */
     #generateSessionToken() {
         let token = "";
@@ -404,7 +423,7 @@ export default class PlaySocketServer {
      * Check rate limit using token bucket algorithm
      * @param {string} connUuid - Connection UUID (which is different from the client ID)
      * @param {string} actionType - A string describing the action
-     * @returns {boolean} - Whether or not the action can be allowed, true means allowed, false means limited
+     * @returns {boolean} Whether or not the action can be allowed, true means allowed, false means limited
      */
     #checkRateLimit(connUuid, actionType) {
         const now = Date.now();
@@ -469,9 +488,10 @@ export default class PlaySocketServer {
 
     /**
      * Register an event callback
-     * @param {string} event - Event name
-     * @param {Function} callback - Callback function
-     * @returns {Function} - Unsubscribe
+     * @template {keyof ServerEventMap} E
+     * @param {E} event - Event name
+     * @param {ServerEventMap[E]} callback - Callback function
+     * @returns {Function} Unsubscribe
      */
     onEvent(event, callback) {
         const validEvents = ["clientRegistered", "clientRegistrationRequested", "clientDisconnected", "clientJoinedRoom", "clientLeftRoom", "clientJoinRequested", "roomCreated", "roomCreationRequested", "requestReceived", "storageUpdated", "storageUpdateRequested", "roomDestroyed"];
@@ -494,7 +514,7 @@ export default class PlaySocketServer {
      * Trigger an event to registered callbacks
      * @param {string} event - Event name
      * @param {...*} args - Arguments
-     * @returns {Promise<any>} - The first non-null callback return value if present (all callbacks run, a throwing callback counts as returning false), otherwise true
+     * @returns {Promise<any>} The first non-null callback return value if present (all callbacks run, a throwing callback counts as returning false), otherwise true
      */
     async #triggerEvent(event, ...args) {
         const syncOnlyEvents = ["storageUpdateRequested"]; // Async storage validation could mess up GC and would lead to potentially poor UX (slow sync)
@@ -556,19 +576,21 @@ export default class PlaySocketServer {
     }
 
     /**
-     * Get snapshot of a room's storage
+     * Get a snapshot of a room's storage
      * @param {string} roomId - ID of the room to get the storage from
-     * @returns {Record<string, any> | undefined} - Storage object or undefined if the room doesn't exist
+     * @param {object} [options] - Options
+     * @param {boolean} [options.dangerouslySkipCloning=false] - Return uncloned store (faster, but allows illegal mutation)
+     * @returns {Record<string, any> | undefined} Storage object or undefined if the room doesn't exist
      */
-    getRoomStorage(roomId) {
+    getRoomStorage(roomId, { dangerouslySkipCloning = false } = {}) {
         const room = this.#rooms[roomId];
-        if (room) return room.crdtManager.propertyStore;
+        if (room) return dangerouslySkipCloning ? room.crdtManager.rawPropertyStore : room.crdtManager.propertyStore;
     }
 
     /**
      * Get the operation details from a storage update (e.g. in the "storageUpdateRequested" event)
      * @param {PropertyUpdate} update - Property update
-     * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} - Operation details
+     * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} Operation details
      */
     getUpdateDetails(update) {
         return getUpdateDetails(update);
@@ -606,7 +628,7 @@ export default class PlaySocketServer {
 
     /**
      * Create a server-owned room 
-     * @param {object} [initialStorage] - Optional initial storage object
+     * @param {object | null} [initialStorage] - Optional initial storage object
      * @param {number} [size] - Max. room size, up to 500
      * @returns {{ state: CRDTState, id: string }} Object containing room state and room ID
      */
@@ -617,7 +639,7 @@ export default class PlaySocketServer {
     /**
      * Create a room
      * @param {string} host - Host ID (when set to "server", room will not be deleted if all clients leave)
-     * @param {object} [initialStorage] - Optional initial storage object
+     * @param {object | null} [initialStorage] - Optional initial storage object
      * @param {number} [size] - Max. room size, up to 500
      * @returns {{ state: CRDTState, id: string }} Object containing room state and room ID
      */

package/src/universal/constants.js

@@ -9,7 +9,7 @@ export const HEARTBEAT_INTERVAL = 5000;
 /**
  * Library version, must match package.json
  */
-export const VERSION = "5.0.0";
+export const VERSION = "5.2.0";
 
 /**
  * Logging prefixes

package/src/universal/crdtManager.js

@@ -179,7 +179,7 @@ export default class CRDTManager {
      * @param {PropertyUpdateType} type - Operation type
      * @param {*} value - Value
      * @param {*} [secondValue] - Second value (needed for some operations)
-     * @returns {PropertyUpdate | undefined} - Returns the property update
+     * @returns {PropertyUpdate | undefined} Returns the property update
      */
     updateProperty(key, type, value, secondValue) {
         try {
@@ -276,7 +276,7 @@ export default class CRDTManager {
      * Create an operation object
      * @param {OperationData} data - Operation data, consists of type, value and secondValue
      * @param {VectorClockEntries} vectorClock - Vector clock of the replica/client
-     * @returns {Operation} - Operation object
+     * @returns {Operation} Operation object
      */
     #createOperation(data, vectorClock) {
         const newOperation = {
@@ -323,7 +323,7 @@ export default class CRDTManager {
     /**
      * Sort operations by vector clock (causal order)
      * @param {Operation[]} operations - Full operations that include vector clocks, data and a source
-     * @returns {Operation[]} - Sorted operations
+     * @returns {Operation[]} Sorted operations
      */
     #sortByVectorClock(operations) {
         return [...operations].sort((a, b) => {
@@ -362,16 +362,16 @@ export default class CRDTManager {
      * @param {PropertyUpdateType} type - Operation type
      * @param {*} value - Value
      * @param {*} [secondValue] - Second value (needed for some operations)
-     * @returns {*} - Value after the operation
+     * @returns {*} Value after the operation
      */
     #handleOperation(curValue, type, value, secondValue) {
         try {
+            // Set operation (before the structured clone since for set we don't care about curValue anyway)
+            if (type === "set") return value;
+
             // Deep copy to avoid reference issues in case value is or contains object(s)
             curValue = structuredClone(curValue);
 
-            // Set operation
-            if (type === "set") return value;
-
             // Number increment operation
             if (type === "number-increment") {
                 if (!Number.isFinite(curValue)) curValue = 0; // Auto-convert to number if current value isn't a finite number
@@ -433,7 +433,7 @@ export default class CRDTManager {
     /**
      * Remove HTML to prevent XSS and enforce size limits
      * @param {*} value - Value to sanitize
-     * @returns {*} - Sanitized value
+     * @returns {*} Sanitized value
      */
     #sanitizeValue(value) {
         if (value === undefined) return null; // Normalize undefined to null to avoid divergence in transport
@@ -450,7 +450,7 @@ export default class CRDTManager {
 
     /**
      * Get property store
-     * @returns {Record<string, any>} - Object with key value pairs
+     * @returns {Record<string, any>} Object with key value pairs
      */
     get propertyStore() {
         try {
@@ -461,9 +461,17 @@ export default class CRDTManager {
         }
     }
 
+    /**
+     * Get uncloned property store
+     * @returns {Record<string, any>} Object with key value pairs
+     */
+    get rawPropertyStore() {
+        return this.#propertyStore;
+    }
+
     /**
      * Check for changes in the local property store
-     * @returns {boolean} - Check if any values changed going from the last to the current property update
+     * @returns {boolean} Check if any values changed going from the last to the current property update
      */
     get didPropertiesChange() {
         try {
@@ -479,7 +487,7 @@ export default class CRDTManager {
 
     /**
      * Export state (can be imported using importState, converts the maps to arrays for serialization)
-     * @returns {CRDTState} - State
+     * @returns {CRDTState} State
      */
     get state() {
         return {
@@ -492,7 +500,7 @@ export default class CRDTManager {
 /**
  * Get the operation details from a property update
  * @param {PropertyUpdate} update - Property update
- * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} - Operation details
+ * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} Operation details
  */
 export function getUpdateDetails(update) {
     const data = update?.operation?.data;

package/types/client/client.d.ts

@@ -23,6 +23,15 @@ export type PendingPromise = {
     resolve: (value?: any) => void;
     reject: (reason?: any) => void;
 };
+export type ClientEventMap = {
+    status: (message: string) => void;
+    moved: (roomId: string) => void;
+    instanceDestroyed: (reason: string | undefined) => void;
+    storageUpdated: (storage: Record<string, any>) => void;
+    hostMigrated: (hostId: string) => void;
+    clientJoined: (clientId: string) => void;
+    clientLeft: (clientId: string) => void;
+};
 /** @typedef {import("../universal/crdtManager.js").PropertyUpdateType} PropertyUpdateType */
 /**
  * @typedef {object} PlaySocketOptions
@@ -35,6 +44,17 @@ export type PendingPromise = {
  * @property {string} type - Message type
  */
 /** @typedef {{ resolve: (value?: any) => void, reject: (reason?: any) => void }} PendingPromise */
+/**
+ * Event callback types
+ * @typedef {object} ClientEventMap
+ * @property {(message: string) => void} status
+ * @property {(roomId: string) => void} moved
+ * @property {(reason: string | undefined) => void} instanceDestroyed
+ * @property {(storage: Record<string, any>) => void} storageUpdated
+ * @property {(hostId: string) => void} hostMigrated
+ * @property {(clientId: string) => void} clientJoined
+ * @property {(clientId: string) => void} clientLeft
+ */
 /**
  * PlaySocket Client
  */
@@ -42,17 +62,18 @@ export default class PlaySocket {
     #private;
     /**
      * Create a new PlaySocket instance
-     * @param {string} [id] - Unique identifier for this client (assigned by the server if omitted)
+     * @param {string | null} [id] - Unique identifier for this client (assigned by the server if omitted or null)
      * @param {PlaySocketOptions} options - Connection options
      */
-    constructor(id?: string, options?: PlaySocketOptions);
+    constructor(id?: string | null, options?: PlaySocketOptions);
     /**
      * Register an event callback
-     * @param {string} event - Event name
-     * @param {Function} callback - Callback function
-     * @returns {Function} - Unsubscribe
+     * @template {keyof ClientEventMap} E
+     * @param {E} event - Event name
+     * @param {ClientEventMap[E]} callback - Callback function
+     * @returns {Function} Unsubscribe
      */
-    onEvent(event: string, callback: Function): Function;
+    onEvent<E extends keyof ClientEventMap>(event: E, callback: ClientEventMap[E]): Function;
     /**
      * Initialize the PlaySocket instance by connecting to the WS server
      * @returns {Promise<string>} Resolves with the client ID when the connection is established
@@ -60,15 +81,15 @@ export default class PlaySocket {
     init(): Promise<string>;
     /**
      * Create a new room and become host
-     * @param {object} [initialStorage] - Initial state
+     * @param {object | null} [initialStorage] - Initial state
      * @param {number} [size] - Max number of participants
      * @returns {Promise<string>} Resolves with room ID
      */
-    createRoom(initialStorage?: object, size?: number): Promise<string>;
+    createRoom(initialStorage?: object | null, size?: number): Promise<string>;
     /**
      * Join an existing room
      * @param {string} roomId - ID of the room
-     * @returns {Promise<void>} - Resolves when connected
+     * @returns {Promise<void>} Resolves when connected
      */
     joinRoom(roomId: string): Promise<void>;
     /**
@@ -83,7 +104,7 @@ export default class PlaySocket {
      * Send a custom request to the server
      * @param {string} name - Name of the request
      * @param {*} [data] - Custom data
-     * @returns {Promise<void>} - Request promise
+     * @returns {Promise<void>} Request promise
      */
     sendRequest(name: string, data?: any): Promise<void>;
     /**

package/types/server/server.d.ts

@@ -33,6 +33,39 @@ export type Room = {
      */
     crdtManager: CRDTManager;
 };
+export type RejectViaStringOrBool = boolean | string | void;
+export type ServerEventMap = {
+    clientRegistrationRequested: (clientId: string, customData: any) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>;
+    clientRegistered: (clientId: string, customData: any) => void;
+    clientDisconnected: (clientId: string) => void;
+    clientJoinedRoom: (clientId: string, roomId: string) => void;
+    clientLeftRoom: (clientId: string, roomId: string) => void;
+    clientJoinRequested: (clientId: string, roomId: string) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>;
+    roomCreated: (roomId: string) => void;
+    roomDestroyed: (roomId: string) => void;
+    roomCreationRequested: (payload: {
+        clientId: string;
+        initialStorage: Record<string, any>;
+    }) => Record<string, any> | RejectViaStringOrBool | Promise<Record<string, any> | RejectViaStringOrBool>;
+    requestReceived: (payload: {
+        roomId: string | null;
+        clientId: string;
+        name: string;
+        data: unknown;
+    }) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>;
+    storageUpdateRequested: (payload: {
+        roomId: string;
+        clientId: string;
+        update: PropertyUpdate;
+        storage: Record<string, any> | undefined;
+    }) => RejectViaStringOrBool;
+    storageUpdated: (payload: {
+        roomId: string;
+        clientId: string | null;
+        update: PropertyUpdate;
+        storage: Record<string, any> | undefined;
+    }) => void;
+};
 /**
  * @typedef {import("node:http").Server} HttpServer
  * @typedef {import("../universal/crdtManager.js").PropertyUpdateType} PropertyUpdateType
@@ -51,6 +84,23 @@ export type Room = {
  * @property {number} size - Max. number of participants
  * @property {CRDTManager} crdtManager - CRDT manager holding the room storage
  */
+/** @typedef {boolean | string | void} RejectViaStringOrBool */
+/**
+ * Event callback types
+ * @typedef {object} ServerEventMap
+ * @property {(clientId: string, customData: any) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} clientRegistrationRequested
+ * @property {(clientId: string, customData: any) => void} clientRegistered
+ * @property {(clientId: string) => void} clientDisconnected
+ * @property {(clientId: string, roomId: string) => void} clientJoinedRoom
+ * @property {(clientId: string, roomId: string) => void} clientLeftRoom
+ * @property {(clientId: string, roomId: string) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} clientJoinRequested
+ * @property {(roomId: string) => void} roomCreated
+ * @property {(roomId: string) => void} roomDestroyed
+ * @property {(payload: { clientId: string, initialStorage: Record<string, any> }) => Record<string, any> | RejectViaStringOrBool | Promise<Record<string, any> | RejectViaStringOrBool>} roomCreationRequested
+ * @property {(payload: { roomId: string | null, clientId: string, name: string, data: unknown }) => RejectViaStringOrBool | Promise<RejectViaStringOrBool>} requestReceived
+ * @property {(payload: { roomId: string, clientId: string, update: PropertyUpdate, storage: Record<string, any> | undefined }) => RejectViaStringOrBool} storageUpdateRequested
+ * @property {(payload: { roomId: string, clientId: string | null, update: PropertyUpdate, storage: Record<string, any> | undefined }) => void} storageUpdated
+ */
 /**
  * PlaySocket Server
  */
@@ -76,11 +126,12 @@ export default class PlaySocketServer {
     });
     /**
      * Register an event callback
-     * @param {string} event - Event name
-     * @param {Function} callback - Callback function
-     * @returns {Function} - Unsubscribe
+     * @template {keyof ServerEventMap} E
+     * @param {E} event - Event name
+     * @param {ServerEventMap[E]} callback - Callback function
+     * @returns {Function} Unsubscribe
      */
-    onEvent(event: string, callback: Function): Function;
+    onEvent<E extends keyof ServerEventMap>(event: E, callback: ServerEventMap[E]): Function;
     /**
      * Kick a client from the server
      * @param {string} clientId - Client ID
@@ -94,15 +145,19 @@ export default class PlaySocketServer {
      */
     move(clientId: string, roomId: string): void;
     /**
-     * Get snapshot of a room's storage
+     * Get a snapshot of a room's storage
      * @param {string} roomId - ID of the room to get the storage from
-     * @returns {Record<string, any> | undefined} - Storage object or undefined if the room doesn't exist
+     * @param {object} [options] - Options
+     * @param {boolean} [options.dangerouslySkipCloning=false] - Return uncloned store (faster, but allows illegal mutation)
+     * @returns {Record<string, any> | undefined} Storage object or undefined if the room doesn't exist
      */
-    getRoomStorage(roomId: string): Record<string, any> | undefined;
+    getRoomStorage(roomId: string, { dangerouslySkipCloning }?: {
+        dangerouslySkipCloning?: boolean;
+    }): Record<string, any> | undefined;
     /**
      * Get the operation details from a storage update (e.g. in the "storageUpdateRequested" event)
      * @param {PropertyUpdate} update - Property update
-     * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} - Operation details
+     * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} Operation details
      */
     getUpdateDetails(update: PropertyUpdate): {
         key: string | undefined;
@@ -121,11 +176,11 @@ export default class PlaySocketServer {
     updateRoomStorage(roomId: string, key: string, type: PropertyUpdateType, value: any, secondValue?: any): void;
     /**
      * Create a server-owned room
-     * @param {object} [initialStorage] - Optional initial storage object
+     * @param {object | null} [initialStorage] - Optional initial storage object
      * @param {number} [size] - Max. room size, up to 500
      * @returns {{ state: CRDTState, id: string }} Object containing room state and room ID
      */
-    createRoom(initialStorage?: object, size?: number): {
+    createRoom(initialStorage?: object | null, size?: number): {
         state: CRDTState;
         id: string;
     };

package/types/universal/constants.d.ts

@@ -8,7 +8,7 @@ export declare const HEARTBEAT_INTERVAL = 5000;
 /**
  * Library version, must match package.json
  */
-export declare const VERSION = "5.0.0";
+export declare const VERSION = "5.2.0";
 /**
  * Logging prefixes
  */

package/types/universal/crdtManager.d.ts

@@ -115,29 +115,34 @@ export default class CRDTManager {
      * @param {PropertyUpdateType} type - Operation type
      * @param {*} value - Value
      * @param {*} [secondValue] - Second value (needed for some operations)
-     * @returns {PropertyUpdate | undefined} - Returns the property update
+     * @returns {PropertyUpdate | undefined} Returns the property update
      */
     updateProperty(key: string, type: PropertyUpdateType, value: any, secondValue?: any): PropertyUpdate | undefined;
     /**
      * Get property store
-     * @returns {Record<string, any>} - Object with key value pairs
+     * @returns {Record<string, any>} Object with key value pairs
      */
     get propertyStore(): Record<string, any>;
+    /**
+     * Get uncloned property store
+     * @returns {Record<string, any>} Object with key value pairs
+     */
+    get rawPropertyStore(): Record<string, any>;
     /**
      * Check for changes in the local property store
-     * @returns {boolean} - Check if any values changed going from the last to the current property update
+     * @returns {boolean} Check if any values changed going from the last to the current property update
      */
     get didPropertiesChange(): boolean;
     /**
      * Export state (can be imported using importState, converts the maps to arrays for serialization)
-     * @returns {CRDTState} - State
+     * @returns {CRDTState} State
      */
     get state(): CRDTState;
 }
 /**
  * Get the operation details from a property update
  * @param {PropertyUpdate} update - Property update
- * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} - Operation details
+ * @returns {{key: string | undefined, type: PropertyUpdateType | undefined, value: *, secondValue: *}} Operation details
  */
 export declare function getUpdateDetails(update: PropertyUpdate): {
     key: string | undefined;