playsocketjs 3.1.2 → 4.1.0

package/types/server/server.d.ts

@@ -0,0 +1,143 @@
+import CRDTManager from "../universal/crdtManager.js";
+export declare const RECONNECT_GRACE_PERIOD = 5000;
+export type HttpServer = import("node:http").Server;
+export type PropertyUpdateType = import("../universal/crdtManager.js").PropertyUpdateType;
+export type PropertyUpdate = import("../universal/crdtManager.js").PropertyUpdate;
+export type CRDTState = import("../universal/crdtManager.js").CRDTState;
+export type WebSocket = import("ws").WebSocket;
+export type ClientMessage = {
+    /**
+     * - Message type
+     */
+    type: string;
+};
+export type RateLimit = {
+    points: number;
+    lastReset: number;
+};
+export type Room = {
+    /**
+     * - Client IDs of the room participants
+     */
+    participants: string[];
+    /**
+     * - Client ID of the room host ("server" for server-owned rooms, null if the room currently has no host)
+     */
+    host: string | null;
+    /**
+     * - Max. number of participants
+     */
+    size: number;
+    /**
+     * - CRDT manager holding the room storage
+     */
+    crdtManager: CRDTManager;
+};
+/**
+ * @typedef {import("node:http").Server} HttpServer
+ * @typedef {import("../universal/crdtManager.js").PropertyUpdateType} PropertyUpdateType
+ * @typedef {import("../universal/crdtManager.js").PropertyUpdate} PropertyUpdate
+ * @typedef {import("../universal/crdtManager.js").CRDTState} CRDTState
+ */
+/** @typedef {import("ws").WebSocket} WebSocket */ /**
+ * @typedef {object} ClientMessage
+ * @property {string} type - Message type
+ */
+/** @typedef {{ points: number, lastReset: number }} RateLimit */
+/**
+ * @typedef {object} Room
+ * @property {string[]} participants - Client IDs of the room participants
+ * @property {string | null} host - Client ID of the room host ("server" for server-owned rooms, null if the room currently has no host)
+ * @property {number} size - Max. number of participants
+ * @property {CRDTManager} crdtManager - CRDT manager holding the room storage
+ */
+/**
+ * PlaySocket Server
+ */
+export default class PlaySocketServer {
+    #private;
+    /**
+     * 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='/'] - WebSocket endpoint path
+     * @param {boolean} [options.debug=false] - Enable debug logging
+     * @param {number} [options.rateLimit=20] - Maximum number of operations per second per client
+     * @param {import("ws").ServerOptions["verifyClient"]} [options.verifyClient] - Optional callback to verify client connections before upgrade. Receives (info, callback) where info contains { req, origin } and callback is (verified, code?, message?) => void
+     */
+    constructor(options?: {
+        server?: HttpServer;
+        port?: number;
+        path?: string;
+        debug?: boolean;
+        rateLimit?: number;
+        verifyClient?: import("ws").ServerOptions["verifyClient"];
+    });
+    /**
+     * Register an event callback
+     * @param {string} event - Event name
+     * @param {Function} callback - Callback function
+     * @returns {Function} - Unsubscribe
+     */
+    onEvent(event: string, callback: Function): Function;
+    /**
+     * Kick a client from the server
+     * @param {string} clientId - Client ID
+     * @param {string} [reason] - Optional reason
+     */
+    kick(clientId: string, reason?: string): void;
+    /**
+     * Move client into a different room
+     * @param {string} clientId - Client ID
+     * @param {string} roomId - Room ID (Target)
+     */
+    move(clientId: string, roomId: string): void;
+    /**
+     * Get 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
+     */
+    getRoomStorage(roomId: string): 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
+     */
+    getUpdateDetails(update: PropertyUpdate): {
+        key: string | undefined;
+        type: PropertyUpdateType | undefined;
+        value: any;
+        secondValue: any;
+    };
+    /**
+     * Update a value in a room's storage
+     * @param {string} roomId - Room ID
+     * @param {string} key - Storage key
+     * @param {PropertyUpdateType} type - Operation type
+     * @param {*} value - Value
+     * @param {*} [secondValue] - Second value (needed for some operations)
+     */
+    updateRoomStorage(roomId: string, key: string, type: PropertyUpdateType, value: any, secondValue?: any): void;
+    /**
+     * 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)
+     * @returns {{ state: CRDTState, id: string }} Object containing room state and room ID
+     */
+    createRoom(initialStorage?: object, size?: number, host?: string): {
+        state: CRDTState;
+        id: string;
+    };
+    /**
+     * Destroy a room
+     * @param {string} roomId - Room ID
+     */
+    destroyRoom(roomId: string): void;
+    /**
+     * Close all client connections, then close the websocket and http server
+     */
+    stop(): void;
+    get rooms(): Record<string, Room>;
+}

package/types/universal/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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
+ */
+export declare const HEARTBEAT_INTERVAL = 5000;

package/types/universal/crdtManager.d.ts

@@ -0,0 +1,147 @@
+export type PropertyUpdateType = "set" | "number-increment" | "array-add" | "array-add-unique" | "array-remove-matching" | "array-update-matching" | "object-set-key" | "object-remove-key";
+export type VectorClockEntries = [string, number][];
+export type OperationData = {
+    /**
+     * - Operation type
+     */
+    type: PropertyUpdateType;
+    /**
+     * - Value
+     */
+    value: any;
+    /**
+     * - Second value (needed for some operations)
+     */
+    secondValue?: any;
+};
+export type Operation = {
+    /**
+     * - Operation data
+     */
+    data: OperationData;
+    /**
+     * - Vector clock entries at creation time
+     */
+    vectorClock: VectorClockEntries;
+    /**
+     * - ID of the replica that created the operation
+     */
+    source: string;
+    /**
+     * - Unique operation ID
+     */
+    uuid: string;
+};
+export type PropertyUpdate = {
+    /**
+     * - Storage key
+     */
+    key: string;
+    /**
+     * - New operation
+     */
+    operation: Operation;
+    /**
+     * - Vector clock entries of the replica
+     */
+    vectorClock: VectorClockEntries;
+};
+export type CRDTState = {
+    /**
+     * - Operations per storage key
+     */
+    keyOperations: [string, Operation[]][];
+    /**
+     * - Vector clock entries
+     */
+    vectorClock: VectorClockEntries;
+};
+/** @typedef {"set" | "number-increment" | "array-add" | "array-add-unique" | "array-remove-matching" | "array-update-matching" | "object-set-key" | "object-remove-key"} PropertyUpdateType */
+/** @typedef {[string, number][]} VectorClockEntries */
+/**
+ * @typedef {object} OperationData
+ * @property {PropertyUpdateType} type - Operation type
+ * @property {*} value - Value
+ * @property {*} [secondValue] - Second value (needed for some operations)
+ */
+/**
+ * @typedef {object} Operation
+ * @property {OperationData} data - Operation data
+ * @property {VectorClockEntries} vectorClock - Vector clock entries at creation time
+ * @property {string} source - ID of the replica that created the operation
+ * @property {string} uuid - Unique operation ID
+ */
+/**
+ * @typedef {object} PropertyUpdate
+ * @property {string} key - Storage key
+ * @property {Operation} operation - New operation
+ * @property {VectorClockEntries} vectorClock - Vector clock entries of the replica
+ */
+/**
+ * @typedef {object} CRDTState
+ * @property {[string, Operation[]][]} keyOperations - Operations per storage key
+ * @property {VectorClockEntries} vectorClock - Vector clock entries
+ */
+/**
+ * CRDT Manager
+ * Custom conflict-free replicated data type system with vector clocks
+ */
+export default class CRDTManager {
+    #private;
+    /**
+     * Create a new instance
+     * @param {boolean} [debug=false] - Enable debug logging
+     */
+    constructor(debug?: boolean);
+    /**
+     * Import the entire state of the CRDT manager (this overwrites the old state)
+     * @param {CRDTState} state - Full state of the CRDT manager
+     */
+    importState(state: CRDTState): void;
+    /**
+     * Import property update
+     * @param {PropertyUpdate} update - Property update
+     */
+    importPropertyUpdate(update: PropertyUpdate): void;
+    /**
+     * Revert a local property update by removing the operation and recomputing the affected key
+     * Should NOT be used on the server or for synced ops, only for reverting local optimistic updates
+     * @param {PropertyUpdate} update - Property update
+     */
+    revertPropertyUpdate(update: PropertyUpdate): void;
+    /**
+     * Update a property
+     * @param {string} key - Storage key
+     * @param {PropertyUpdateType} type - Operation type
+     * @param {*} value - Value
+     * @param {*} [secondValue] - Second value (needed for some operations)
+     * @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
+     */
+    get propertyStore(): 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
+     */
+    get didPropertiesChange(): boolean;
+    /**
+     * Export state (can be imported using importState, converts the maps to arrays for serialization)
+     * @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
+ */
+export declare function getUpdateDetails(update: PropertyUpdate): {
+    key: string | undefined;
+    type: PropertyUpdateType | undefined;
+    value: any;
+    secondValue: any;
+};