@signe/room 0.0.1 → 0.0.2

package/src/server.ts

@@ -1,6 +1,12 @@
-import { createStatesSnapshot, getByPath, load, syncClass } from "@signe/sync";
 import { dset } from "dset";
 import z from "zod";
+import {
+  createStatesSnapshot,
+  getByPath,
+  load,
+  syncClass,
+} from "../../sync/src";
+import { generateShortUUID } from "../../sync/src/utils";
 import type * as Party from "./types/party";
 import {
   awaitReturn,
@@ -15,33 +21,121 @@ const Message = z.object({
   value: z.any(),
 });
 
+type CreateRoomOptions = {
+  getMemoryAll?: boolean;
+};
+
+/**
+ * @class Server
+ * @implements {Party.Server}
+ * @description Represents a server that manages rooms and connections for a multiplayer game or application.
+ * 
+ * @example
+ * ```typescript
+ * import { Room, Server, ServerIo } from "@yourpackage/room";
+ * 
+ * @Room({ path: "game" })
+ * class GameRoom {
+ *   // Room implementation
+ * }
+ * 
+ * class MyServer extends Server {
+ *   rooms = [GameRoom];
+ * }
+ * 
+ * const server = new MyServer(new ServerIo("game"));
+ * server.onStart();
+ * ```
+ */
 export class Server implements Party.Server {
-  memoryAll = {};
-  subRoom = {};
-  rooms = [];
+  subRoom = null;
+  rooms: any[] = [];
 
-  static async onBeforeConnect(request: Party.Request) {
-    try {
-      request.headers.set("X-User-ID", "" + Math.random());
-      return request;
-    } catch (e) {
-      return new Response("Unauthorized", { status: 401 });
+  /**
+   * @constructor
+   * @param {Party.Room} room - The room object representing the current game or application instance.
+   * 
+   * @example
+   * ```typescript
+   * const server = new MyServer(new ServerIo("game"));
+   * ```
+   */
+  constructor(readonly room: Party.Room) {}
+
+ /**
+   * @readonly
+   * @property {boolean} isHibernate - Indicates whether the server is in hibernate mode.
+   * 
+   * @example
+   * ```typescript
+   * if (!server.isHibernate) {
+   *   console.log("Server is active");
+   * }
+   * ```
+   */
+  get isHibernate(): boolean {
+    return !!this["options"]?.hibernate;
+  }
+
+  /**
+   * @method onStart
+   * @async
+   * @description Initializes the server and creates the initial room if not in hibernate mode.
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * ```typescript
+   * async function initServer() {
+   *   await server.onStart();
+   *   console.log("Server started");
+   * }
+   * ```
+   */
+
+  async onStart() {
+    // Only create a room if not in hibernate mode
+    // This prevents unnecessary resource allocation for inactive rooms
+    if (!this.isHibernate) {
+      this.subRoom = await this.createRoom();
     }
   }
 
-  constructor(readonly room: Party.Room) {
+  /**
+   * @method createRoom
+   * @private
+   * @async
+   * @param {CreateRoomOptions} [options={}] - Options for creating the room.
+   * @returns {Promise<Object>} The created room instance.
+   * @throws {Error} If no matching room is found.
+   * 
+   * @example
+   * ```typescript
+   * // This method is private and called internally
+   * async function internalCreateRoom() {
+   *   const room = await this.createRoom({ getMemoryAll: true });
+   *   console.log("Room created:", room);
+   * }
+   * ```
+   */
+  private async createRoom(options: CreateRoomOptions = {}) {
+    let instance
+    let init = true
+
+    // Find the appropriate room based on the current room ID
     for (let room of this.rooms) {
       const params = extractParams(room.path, this.room.id);
       if (params) {
-        this.subRoom = new room(this.room, params);
+        instance = new room(this.room, params);
         break;
       }
     }
 
-    if (!this.subRoom) {
+    if (!instance) {
       throw new Error("Room not found");
     }
 
+    // Load the room's memory from storage
+    // This ensures persistence across server restarts
     const loadMemory = async () => {
       const root = await this.room.storage.get(".");
       const memory = await this.room.storage.list();
@@ -52,77 +146,188 @@ export class Server implements Party.Server {
         }
         dset(tmpObject, key, value);
       }
-      load(this, tmpObject);
+      load(instance, tmpObject);
     };
 
-    loadMemory();
+    await loadMemory();
 
-    syncClass(this.subRoom, {
-      onSync: throttle((values) => {
-        const packet = buildObject(values, this.memoryAll);
-        this.room.broadcast(
-          JSON.stringify({
-            type: "sync",
-            value: packet,
-          })
-        );
-        values.clear();
-      }, 500),
-      onPersist: throttle(async (values) => {
-        for (let path of values) {
-          const instance =
-            path == "." ? this.subRoom : getByPath(this.subRoom, path);
-          const itemValue = createStatesSnapshot(instance);
-          await this.room.storage.put(path, itemValue);
-        }
-        values.clear();
-      }, this.subRoom['throttleStorage'] ?? 2000),
+    instance.$memoryAll = {}
+
+    // Sync callback: Broadcast changes to all clients
+    const syncCb = (values) => {
+      if (options.getMemoryAll) {
+        buildObject(values, instance.$memoryAll);
+      }
+      if (init && this.isHibernate) {
+        init = false;
+        return;
+      }
+      const packet = buildObject(values, instance.$memoryAll);
+      this.room.broadcast(
+        JSON.stringify({
+          type: "sync",
+          value: packet,
+        })
+      );
+      values.clear();
+    }
+
+    // Persist callback: Save changes to storage
+    const persistCb = async (values) => {
+      for (let path of values) {
+        const _instance =
+          path == "." ? instance : getByPath(instance, path);
+        const itemValue = createStatesSnapshot(_instance);
+        await this.room.storage.put(path, itemValue);
+      }
+      values.clear();
+    }
+
+    // Set up syncing and persistence with throttling to optimize performance
+    syncClass(instance, {
+      onSync: throttle(syncCb, instance["throttleSync"] ?? 500),
+      onPersist: throttle(persistCb, instance["throttleStorage"] ?? 2000),
     });
+
+    return instance
+  }
+
+  /**
+   * @method getSubRoom
+   * @private
+   * @async
+   * @param {Object} [options={}] - Options for getting the sub-room.
+   * @returns {Promise<Object>} The sub-room instance.
+   * 
+   * @example
+   * ```typescript
+   * // This method is private and called internally
+   * async function internalGetSubRoom() {
+   *   const subRoom = await this.getSubRoom();
+   *   console.log("Sub-room retrieved:", subRoom);
+   * }
+   * ```
+   */
+  private async getSubRoom(options = {}) {
+    let subRoom
+    if (this.isHibernate) {
+      subRoom = await this.createRoom(options)
+    }
+    else {
+      subRoom = this.subRoom
+    }
+    return subRoom
   }
 
-  private getUsersProperty() {
-    const meta = this.subRoom.constructor['_propertyMetadata'];
+  /**
+   * @method getUsersProperty
+   * @private
+   * @param {Object} subRoom - The sub-room instance.
+   * @returns {Object|null} The users property of the sub-room, or null if not found.
+   * 
+   * @example
+   * ```typescript
+   * // This method is private and called internally
+   * function internalGetUsers(subRoom) {
+   *   const users = this.getUsersProperty(subRoom);
+   *   console.log("Users:", users);
+   * }
+   * ```
+   */
+
+  private getUsersProperty(subRoom) {
+    const meta = subRoom.constructor["_propertyMetadata"];
     const propId = meta?.get("users");
     if (propId) {
-      return this.subRoom[propId];
+      return subRoom[propId];
     }
     return null;
   }
 
+  /**
+   * @method onConnect
+   * @async
+   * @param {Party.Connection} conn - The connection object for the new user.
+   * @param {Party.ConnectionContext} ctx - The context of the connection.
+   * @description Handles a new user connection, creates a user object, and sends initial sync data.
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * ```typescript
+   * server.onConnect = async (conn, ctx) => {
+   *   await server.onConnect(conn, ctx);
+   *   console.log("New user connected:", conn.id);
+   * };
+   * ```
+   */
   async onConnect(conn: Party.Connection, ctx: Party.ConnectionContext) {
-    const publicId = "a" + ("" + Math.random()).split(".")[1];
+    const subRoom = await this.getSubRoom({
+      getMemoryAll: true,
+    })
+    // Generate a unique public ID for the user
+    const publicId = generateShortUUID()
     let user = null;
-    const signal = this.getUsersProperty();
+    const signal = this.getUsersProperty(subRoom);
     if (signal) {
       const { classType } = signal.options;
+      // Create a new user instance based on the defined class type
       user = isClass(classType) ? new classType() : classType(conn, ctx);
       signal()[publicId] = user;
     }
-    await awaitReturn(this.subRoom['onJoin']?.(user, conn, ctx));
+    // Call the room's onJoin method if it exists
+    await awaitReturn(subRoom["onJoin"]?.(user, conn, ctx));
     conn.setState({ publicId });
+    // Send initial sync data to the new connection
     conn.send(
       JSON.stringify({
         type: "sync",
         value: {
           pId: publicId,
-          ...this.memoryAll,
+          ...subRoom.$memoryAll,
         },
       })
     );
   }
 
+  /**
+   * @method onMessage
+   * @async
+   * @param {string} message - The message received from a user.
+   * @param {Party.Connection} sender - The connection object of the sender.
+   * @description Processes incoming messages and triggers corresponding actions in the sub-room.
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * ```typescript
+   * server.onMessage = async (message, sender) => {
+   *   await server.onMessage(message, sender);
+   *   console.log("Message processed from:", sender.id);
+   * };
+   * ```
+   */
+
   async onMessage(message: string, sender: Party.Connection) {
-    const actions = this.subRoom.constructor['_actionMetadata'];
-    const result = Message.safeParse(JSON.parse(message));
+    let json
+    try {
+      json = JSON.parse(message)
+    }
+    catch (e) {
+      return;
+    }
+     // Validate incoming messages
+    const result = Message.safeParse(json);
     if (!result.success) {
       return;
     }
+    const subRoom = await this.getSubRoom()
+    const actions = subRoom.constructor["_actionMetadata"];
     if (actions) {
-      const signal = this.getUsersProperty();
+      const signal = this.getUsersProperty(subRoom);
       const { publicId } = sender.state as any;
       const user = signal?.()[publicId];
       const actionName = actions.get(result.data.action);
       if (actionName) {
+        // Validate action body if a validation schema is defined
         if (actionName.bodyValidation) {
           const bodyResult = actionName.bodyValidation.safeParse(
             result.data.value
@@ -131,19 +336,38 @@ export class Server implements Party.Server {
             return;
           }
         }
+        // Execute the action
         await awaitReturn(
-          this.subRoom[actionName.key](user, result.data.value, sender)
+          subRoom[actionName.key](user, result.data.value, sender)
         );
       }
     }
   }
 
+  /**
+   * @method onClose
+   * @async
+   * @param {Party.Connection} conn - The connection object of the disconnecting user.
+   * @description Handles user disconnection, removing them from the room and triggering the onLeave event.
+   * @returns {Promise<void>}
+   * 
+   * @example
+   * ```typescript
+   * server.onClose = async (conn) => {
+   *   await server.onClose(conn);
+   *   console.log("User disconnected:", conn.id);
+   * };
+   * ```
+   */
   async onClose(conn: Party.Connection) {
-    const signal = this.getUsersProperty();
+    const subRoom = await this.getSubRoom()
+    const signal = this.getUsersProperty(subRoom);
     const { publicId } = conn.state as any;
     const user = signal?.()[publicId];
-    await awaitReturn(this.subRoom['onLeave']?.(user, conn));
+    // Call the room's onLeave method if it exists
+    await awaitReturn(subRoom["onLeave"]?.(user, conn));
     if (signal) {
+      // Remove the user from the room
       delete signal()[publicId];
     }
   }

package/src/utils.ts

@@ -1,14 +1,45 @@
 import { dset } from "dset";
 
-export function isPromise(value: any): boolean {
-  return value && value instanceof Promise;
+/**
+ * Checks if a value is a Promise.
+ *
+ * @param {unknown} value - The value to check.
+ * @returns {boolean} - Returns true if the value is a Promise, otherwise false.
+ *
+ * @example
+ * isPromise(Promise.resolve()); // true
+ * isPromise(42); // false
+ */
+export function isPromise(value: unknown): value is Promise<any> {
+  return value instanceof Promise;
 }
 
-export async function awaitReturn(val: any) {
+/**
+ * Awaits the given value if it is a Promise, otherwise returns the value directly.
+ *
+ * @param {unknown} val - The value to await or return.
+ * @returns {Promise<any>} - Returns a Promise that resolves to the value.
+ *
+ * @example
+ * awaitReturn(Promise.resolve(42)); // 42
+ * awaitReturn(42); // 42
+ */
+export async function awaitReturn(val: unknown): Promise<any> {
   return isPromise(val) ? await val : val;
 }
 
-export function isClass(obj: any): boolean {
+/**
+ * Checks if a value is a class.
+ *
+ * @param {unknown} obj - The value to check.
+ * @returns {boolean} - Returns true if the value is a class, otherwise false.
+ *
+ * @example
+ * class MyClass {}
+ * isClass(MyClass); // true
+ * isClass(() => {}); // false
+ */
+export function isClass(obj: unknown): boolean {
   return (
     typeof obj === "function" &&
     obj.prototype &&
@@ -16,6 +47,24 @@ export function isClass(obj: any): boolean {
   );
 }
 
+
+/**
+ * Creates a throttled function that only invokes the provided function at most once per every wait milliseconds.
+ *
+ * The throttled function comes with a cancel method to cancel delayed invocations.
+ * If the throttled function is invoked more than once during the wait timeout,
+ * it will call the provided function with the latest arguments.
+ *
+ * @template F - The type of the function to throttle.
+ * @param {F} func - The function to throttle.
+ * @param {number} wait - The number of milliseconds to throttle invocations to.
+ * @returns {(...args: Parameters<F>) => void} - Returns the new throttled function.
+ *
+ * @example
+ * const log = throttle((message) => console.log(message), 1000);
+ * log("Hello"); // Will log "Hello" immediately
+ * log("World"); // Will log "World" after 1 second, if no other calls to log() are made within the 1 second.
+ */
 export function throttle<F extends (...args: any[]) => any>(
   func: F,
   wait: number
@@ -39,34 +88,92 @@ export function throttle<F extends (...args: any[]) => any>(
   };
 }
 
+/**
+ * Extracts parameters from a given string based on a specified pattern.
+ *
+ * The pattern can include placeholders in the form of {paramName}, which will be
+ * extracted from the input string if they match.
+ *
+ * @param {string} pattern - The pattern containing placeholders.
+ * @param {string} str - The string to extract parameters from.
+ * @returns {{ [key: string]: string } | null} - An object containing the extracted parameters,
+ *                                               or null if the string does not match the pattern.
+ *
+ * @example
+ * // returns { id: '123' }
+ * extractParams('game-{id}', 'game-123');
+ *
+ * @example
+ * // returns { foo: 'abc', bar: 'xyz' }
+ * extractParams('test-{foo}-{bar}', 'test-abc-xyz');
+ *
+ */
 export function extractParams(
   pattern: string,
   str: string
 ): { [key: string]: string } | null {
+  // Replace placeholders in the pattern with named capture groups
   const regexPattern = pattern.replace(/{(\w+)}/g, "(?<$1>[\\w-]+)");
 
+  // Create a strict regular expression from the pattern
   const regex = new RegExp(`^${regexPattern}$`);
   const match = regex.exec(str);
 
+  // If a match is found and groups are present, return the captured groups
   if (match && match.groups) {
     return match.groups;
+  } else if (pattern === str) {
+    // If the pattern exactly matches the string, return an empty object
+    return {};
   } else {
+    // Otherwise, return null
     return null;
   }
 }
 
-export function dremove(obj, keys) {
-  keys.split && (keys = keys.split("."));
-  var i = 0,
-    l = keys.length,
-    t = { ...obj },
-    k;
+/**
+ * Removes a property from an object based on a dot-separated key string or an array of keys.
+ *
+ * The function modifies the original object by deleting the specified property.
+ * It safely handles dangerous keys like __proto__, constructor, and prototype.
+ *
+ * @param {Record<string, any>} obj - The object from which to remove the property.
+ * @param {string | string[]} keys - The key(s) specifying the property to remove. Can be a dot-separated string or an array of strings.
+ *
+ * @example
+ * const obj = { a: { b: { c: 3 } } };
+ * dremove(obj, 'a.b.c');
+ * // obj is now { a: { b: {} } }
+ *
+ * @example
+ * const obj = { a: 1, b: 2 };
+ * dremove(obj, 'a');
+ * // obj is now { b: 2 }
+ *
+ * @example
+ * const obj = { a: { b: { c: 3 } } };
+ * dremove(obj, ['a', 'b', 'c']);
+ * // obj is now { a: { b: {} } }
+ */
+export function dremove(
+  obj: Record<string, any>,
+  keys: string | string[]
+): void {
+  // If keys is a string, convert it to an array using the "." separator
+  if (typeof keys === "string") {
+    keys = keys.split(".");
+  }
+
+  let i = 0;
+  const l = keys.length;
+  let t = obj;
+  let k;
 
   while (i < l - 1) {
     k = keys[i++];
-    if (k === "__proto__" || k === "constructor" || k === "prototype") return; // On évite les clés dangereuses
+    if (k === "__proto__" || k === "constructor" || k === "prototype") return; // Avoid dangerous keys
+    if (typeof t[k] !== "object" || t[k] === null) return; // If the object doesn't exist, stop
     t = t[k];
-    if (typeof t !== "object" || t === null) return; // Si l'objet n'existe pas, on arrête
   }
 
   k = keys[i];
@@ -79,16 +186,35 @@ export function dremove(obj, keys) {
   }
 }
 
-export function buildObject(valuesMap, allMemory) {
-    let memoryObj = {};
-    for (let path of valuesMap.keys()) {
-      const value = valuesMap.get(path);
-      dset(memoryObj, path, value);
-      if (path == "$delete") {
-        dremove(allMemory, value);
-      } else {
-        dset(allMemory, path, value);
-      }
+/**
+ * Builds an object from a map of values and updates the provided memory object.
+ *
+ * For each key-value pair in the map, this function sets the value at the given path in the `memoryObj`.
+ * If the value is "$delete", it removes the corresponding path from `allMemory`.
+ *
+ * @param {Map<string, any>} valuesMap - A map where the keys are paths and the values are the values to set at those paths.
+ * @param {Record<string, any>} allMemory - The object to update based on the values in the map.
+ * @returns {Record<string, any>} - The built memory object with the applied values from the map.
+ *
+ * @example
+ * const valuesMap = new Map();
+ * valuesMap.set('a.b.c', 1);
+ * valuesMap.set('x.y.z', '$delete');
+ * const allMemory = { x: { y: { z: 2 } } };
+ * const result = buildObject(valuesMap, allMemory);
+ * // result is { a: { b: { c: 1 } }, x: { y: { z: '$delete' } } }
+ * // allMemory is { a: { b: { c: 1 } }, x: { y: {} } }
+ */
+export function buildObject(valuesMap: Map<string, any>, allMemory: Record<string, any>): Record<string, any> {
+  let memoryObj = {};
+  for (let path of valuesMap.keys()) {
+    const value = valuesMap.get(path);
+    dset(memoryObj, path, value);
+    if (value === "$delete") {
+      dremove(allMemory, path);
+    } else {
+      dset(allMemory, path, value);
     }
-    return memoryObj;
-  }
+  }
+  return memoryObj;
+}