@colyseus/core 0.16.24 → 0.17.1

package/build/src/Room.d.ts

@@ -0,0 +1,497 @@
+import { ClockTimer as Clock } from '@colyseus/timer';
+import type { Presence } from './presence/Presence.ts';
+import type { Serializer } from './serializer/Serializer.ts';
+import { type Type, Deferred } from './utils/Utils.ts';
+import { type AuthContext, type Client, ClientArray, type ISendOptions, type MessageArgs } from './Transport.ts';
+import { type RoomMethodName, type RoomException } from './errors/RoomExceptions.ts';
+import { type StandardSchemaV1 } from './utils/StandardSchema.ts';
+export declare const DEFAULT_SEAT_RESERVATION_TIME: number;
+export type SimulationCallback = (deltaTime: number) => void;
+export interface RoomOptions {
+    state?: object;
+    metadata?: any;
+    client?: Client;
+}
+export type ExtractRoomState<T> = T extends {
+    state?: infer S extends object;
+} ? S : any;
+export type ExtractRoomMetadata<T> = T extends {
+    metadata?: infer M;
+} ? M : any;
+export type ExtractRoomClient<T> = T extends {
+    client?: infer C extends Client;
+} ? C : Client;
+export interface IBroadcastOptions extends ISendOptions {
+    except?: Client | Client[];
+}
+/**
+ * Message handler with automatic type inference from format schema.
+ * When a format is provided, the message type is automatically inferred from the schema.
+ */
+export type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, This = any> = {
+    format: T;
+    handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;
+};
+export type MessageHandler<This = any> = ((this: This, client: Client, message: any) => void) | MessageHandlerWithFormat<any, This>;
+/**
+ * Extract the message payload type from a message handler.
+ * Works with both function handlers and format handlers.
+ *
+ * (Imported from @colyseus/sdk, not used in the server-side)
+ */
+export type ExtractMessageType<T> = T extends {
+    format: infer Format extends StandardSchemaV1;
+    handler: any;
+} ? StandardSchemaV1.InferOutput<Format> : T extends (this: any, client: any, message: infer Message) => void ? Message : any;
+/**
+ * A map of message types to message handlers.
+ */
+export type Messages<This extends Room> = Record<string, MessageHandler<This>>;
+/**
+ * Helper function to create a validated message handler with automatic type inference.
+ *
+ * @example
+ * ```typescript
+ * messages = {
+ *   move: validate(z.object({ x: z.number(), y: z.number() }), (client, message) => {
+ *     // message.x and message.y are automatically typed as numbers
+ *     console.log(message.x, message.y);
+ *   })
+ * }
+ * ```
+ */
+export declare function validate<T extends StandardSchemaV1, This = any>(format: T, handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void): MessageHandlerWithFormat<T, This>;
+export declare const RoomInternalState: {
+    readonly CREATING: 0;
+    readonly CREATED: 1;
+    readonly DISPOSING: 2;
+};
+export type RoomInternalState = (typeof RoomInternalState)[keyof typeof RoomInternalState];
+export type OnCreateOptions<T extends Type<Room>> = Parameters<NonNullable<InstanceType<T>['onCreate']>>[0];
+/**
+ * A Room class is meant to implement a game session, and/or serve as the communication channel
+ * between a group of clients.
+ *
+ * - Rooms are created on demand during matchmaking by default
+ * - Room classes must be exposed using `.define()`
+ *
+ * @example
+ * ```typescript
+ * class MyRoom extends Room<{
+ *   state: MyState,
+ *   metadata: { difficulty: string },
+ *   client: MyClient
+ * }> {
+ *   // ...
+ * }
+ * ```
+ */
+export declare class Room<T extends RoomOptions = RoomOptions> {
+    #private;
+    '~client': ExtractRoomClient<T>;
+    '~state': ExtractRoomState<T>;
+    '~metadata': ExtractRoomMetadata<T>;
+    /**
+     * This property will change on these situations:
+     * - The maximum number of allowed clients has been reached (`maxClients`)
+     * - You manually locked, or unlocked the room using lock() or `unlock()`.
+     *
+     * @readonly
+     */
+    get locked(): boolean;
+    /**
+     * Get the room's matchmaking metadata.
+     */
+    get metadata(): ExtractRoomMetadata<T>;
+    /**
+     * Set the room's matchmaking metadata.
+     *
+     * **Note**: This setter does NOT automatically persist. Use `setMatchmaking()` for automatic persistence.
+     *
+     * @example
+     * ```typescript
+     * class MyRoom extends Room<{ metadata: { difficulty: string; rating: number } }> {
+     *   async onCreate() {
+     *     this.metadata = { difficulty: "hard", rating: 1500 };
+     *   }
+     * }
+     * ```
+     */
+    set metadata(meta: ExtractRoomMetadata<T>);
+    /**
+     * The room listing cache for matchmaking.
+     * @internal
+     */
+    private _listing;
+    /**
+     * Timing events tied to the room instance.
+     * Intervals and timeouts are cleared when the room is disposed.
+     */
+    clock: Clock;
+    /**
+     * Maximum number of clients allowed to connect into the room. When room reaches this limit,
+     * it is locked automatically. Unless the room was explicitly locked by you via `lock()` method,
+     * the room will be unlocked as soon as a client disconnects from it.
+     */
+    maxClients: number;
+    /**
+     * Automatically dispose the room when last client disconnects.
+     *
+     * @default true
+     */
+    autoDispose: boolean;
+    /**
+     * Frequency to send the room state to connected clients, in milliseconds.
+     *
+     * @default 50ms (20fps)
+     */
+    patchRate: number | null;
+    /**
+     * Maximum number of messages a client can send to the server per second.
+     * If a client sends more messages than this, it will be disconnected.
+     *
+     * @default 60
+     */
+    maxMessagesPerSecond: number;
+    /**
+     * The state instance you provided to `setState()`.
+     */
+    state: ExtractRoomState<T>;
+    /**
+     * The presence instance. Check Presence API for more details.
+     *
+     * @see [Presence API](https://docs.colyseus.io/server/presence)
+     */
+    presence: Presence;
+    /**
+     * The array of connected clients.
+     *
+     * @see [Client instance](https://docs.colyseus.io/room#client)
+     */
+    clients: ClientArray<ExtractRoomClient<T>>;
+    /**
+     * Set the number of seconds a room can wait for a client to effectively join the room.
+     * You should consider how long your `onAuth()` will have to wait for setting a different seat reservation time.
+     * The default value is 15 seconds. You may set the `COLYSEUS_SEAT_RESERVATION_TIME`
+     * environment variable if you'd like to change the seat reservation time globally.
+     *
+     * @default 15 seconds
+     */
+    seatReservationTimeout: number;
+    private _events;
+    private _reservedSeats;
+    private _reservedSeatTimeouts;
+    private _reconnections;
+    messages?: Messages<any>;
+    private onMessageEvents;
+    private onMessageValidators;
+    private onMessageFallbacks;
+    private _serializer;
+    private _afterNextPatchQueue;
+    private _simulationInterval;
+    private _internalState;
+    private _lockedExplicitly;
+    private _autoDisposeTimeout;
+    constructor();
+    /**
+     * This method is called by the MatchMaker before onCreate()
+     * @internal
+     */
+    private __init;
+    /**
+     * The name of the room you provided as first argument for `gameServer.define()`.
+     *
+     * @returns roomName string
+     */
+    get roomName(): string;
+    /**
+     * Setting the name of the room. Overwriting this property is restricted.
+     *
+     * @param roomName
+     */
+    set roomName(roomName: string);
+    /**
+     * A unique, auto-generated, 9-character-long id of the room.
+     * You may replace `this.roomId` during `onCreate()`.
+     *
+     * @returns roomId string
+     */
+    get roomId(): string;
+    /**
+     * Setting the roomId, is restricted in room lifetime except upon room creation.
+     *
+     * @param roomId
+     * @returns roomId string
+     */
+    set roomId(roomId: string);
+    /**
+     * This method is called before the latest version of the room's state is broadcasted to all clients.
+     */
+    onBeforePatch?(state: ExtractRoomState<T>): void | Promise<any>;
+    /**
+     * This method is called when the room is created.
+     * @param options - The options passed to the room when it is created.
+     */
+    onCreate?(options: any): void | Promise<any>;
+    /**
+     * This method is called when a client joins the room.
+     * @param client - The client that joined the room.
+     * @param options - The options passed to the client when it joined the room.
+     */
+    onJoin?(client: ExtractRoomClient<T>, options?: any): void | Promise<any>;
+    /**
+     * This method is called when a client leaves the room without consent.
+     * You may allow the client to reconnect by calling `allowReconnection` within this method.
+     *
+     * @param client - The client that was dropped from the room.
+     * @param code - The close code of the leave event.
+     */
+    onDrop?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
+    /**
+     * This method is called when a client reconnects to the room.
+     * @param client - The client that reconnected to the room.
+     */
+    onReconnect?(client: ExtractRoomClient<T>): void | Promise<any>;
+    /**
+     * This method is called when a client effectively leaves the room.
+     * @param client - The client that left the room.
+     * @param code - The close code of the leave event.
+     */
+    onLeave?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
+    /**
+     * This method is called when the room is disposed.
+     */
+    onDispose?(): void | Promise<any>;
+    /**
+     * Define a custom exception handler.
+     * If defined, all lifecycle hooks will be wrapped by try/catch, and the exception will be forwarded to this method.
+     *
+     * These methods will be wrapped by try/catch:
+     * - `onMessage`
+     * - `onAuth` / `onJoin` / `onLeave` / `onCreate` / `onDispose`
+     * - `clock.setTimeout` / `clock.setInterval`
+     * - `setSimulationInterval`
+     *
+     * (Experimental: this feature is subject to change in the future - we're currently getting feedback to improve it)
+     */
+    onUncaughtException?(error: RoomException, methodName: RoomMethodName): void;
+    /**
+     * This method is called before onJoin() - this is where you should authenticate the client
+     * @param client - The client that is authenticating.
+     * @param options - The options passed to the client when it is authenticating.
+     * @param context - The authentication context, including the token and the client's IP address.
+     * @returns The authentication result.
+     *
+     * @example
+     * ```typescript
+     * return {
+     *   userId: 123,
+     *   username: "John Doe",
+     *   email: "john.doe@example.com",
+     * };
+     * ```
+     */
+    onAuth(client: Client, options: any, context: AuthContext): any | Promise<any>;
+    static onAuth(token: string, options: any, context: AuthContext): Promise<unknown>;
+    /**
+     * This method is called during graceful shutdown of the server process
+     * You may override this method to dispose the room in your own way.
+     *
+     * Once process reaches room count of 0, the room process will be terminated.
+     */
+    onBeforeShutdown(): void;
+    /**
+     * devMode: When `devMode` is enabled, `onCacheRoom` method is called during
+     * graceful shutdown.
+     *
+     * Implement this method to return custom data to be cached. `onRestoreRoom`
+     * will be called with the data returned by `onCacheRoom`
+     */
+    onCacheRoom?(): any;
+    /**
+     * devMode: When `devMode` is enabled, `onRestoreRoom` method is called during
+     * process startup, with the data returned by the `onCacheRoom` method.
+     */
+    onRestoreRoom?(cached?: any): void;
+    /**
+     * Returns whether the sum of connected clients and reserved seats exceeds maximum number of clients.
+     *
+     * @returns boolean
+     */
+    hasReachedMaxClients(): boolean;
+    /**
+     * @deprecated Use `seatReservationTimeout=` instead.
+     */
+    setSeatReservationTime(seconds: number): this;
+    hasReservedSeat(sessionId: string, reconnectionToken?: string): boolean;
+    checkReconnectionToken(reconnectionToken: string): string;
+    /**
+     * (Optional) Set a simulation interval that can change the state of the game.
+     * The simulation interval is your game loop.
+     *
+     * @default 16.6ms (60fps)
+     *
+     * @param onTickCallback - You can implement your physics or world updates here!
+     *  This is a good place to update the room state.
+     * @param delay - Interval delay on executing `onTickCallback` in milliseconds.
+     */
+    setSimulationInterval(onTickCallback?: SimulationCallback, delay?: number): void;
+    /**
+     * @deprecated Use `.patchRate=` instead.
+     */
+    setPatchRate(milliseconds: number | null): void;
+    /**
+     * @deprecated Use `.state =` instead.
+     */
+    setState(newState: ExtractRoomState<T>): void;
+    setSerializer(serializer: Serializer<ExtractRoomState<T>>): void;
+    setMetadata(meta: Partial<ExtractRoomMetadata<T>>, persist?: boolean): Promise<void>;
+    setPrivate(bool?: boolean, persist?: boolean): Promise<void>;
+    /**
+     * Update multiple matchmaking/listing properties at once with a single persist operation.
+     * This is the recommended way to update room listing properties.
+     *
+     * @param updates - Object containing the properties to update
+     *
+     * @example
+     * ```typescript
+     * // Update multiple properties at once
+     * await this.setMatchmaking({
+     *   metadata: { difficulty: "hard", rating: 1500 },
+     *   private: true,
+     *   locked: true,
+     *   maxClients: 10
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update only metadata
+     * await this.setMatchmaking({
+     *   metadata: { status: "in_progress" }
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Partial metadata update (merges with existing)
+     * await this.setMatchmaking({
+     *   metadata: { ...this.metadata, round: this.metadata.round + 1 }
+     * });
+     * ```
+     */
+    setMatchmaking(updates: {
+        metadata?: ExtractRoomMetadata<T>;
+        private?: boolean;
+        locked?: boolean;
+        maxClients?: number;
+        unlisted?: boolean;
+        [key: string]: any;
+    }): Promise<void>;
+    /**
+     * Lock the room. This prevents new clients from joining this room.
+     */
+    lock(): Promise<void>;
+    /**
+     * Unlock the room. This allows new clients to join this room, if maxClients is not reached.
+     */
+    unlock(): Promise<void>;
+    /**
+     * @deprecated Use `client.send(...)` instead.
+     */
+    send(client: Client, type: string | number, message: any, options?: ISendOptions): void;
+    /**
+     * Broadcast a message to all connected clients.
+     * @param type - The type of the message.
+     * @param message - The message to broadcast.
+     * @param options - The options for the broadcast.
+     *
+     * @example
+     * ```typescript
+     * this.broadcast('message', { message: 'Hello, world!' });
+     * ```
+     */
+    broadcast<K extends keyof ExtractRoomClient<T>['~messages'] & string | number>(type: K, ...args: MessageArgs<ExtractRoomClient<T>['~messages'][K], IBroadcastOptions>): void;
+    /**
+     * Broadcast bytes (UInt8Arrays) to a particular room
+     */
+    broadcastBytes(type: string | number, message: Uint8Array, options: IBroadcastOptions): void;
+    /**
+     * Checks whether mutations have occurred in the state, and broadcast them to all connected clients.
+     */
+    broadcastPatch(): boolean;
+    /**
+     * Register a message handler for a specific message type.
+     * This method is used to handle messages sent by clients to the room.
+     * @param messageType - The type of the message.
+     * @param callback - The callback to call when the message is received.
+     * @returns A function to unbind the callback.
+     *
+     * @example
+     * ```typescript
+     * this.onMessage('message', (client, message) => {
+     *   console.log(message);
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * const unbind = this.onMessage('message', (client, message) => {
+     *   console.log(message);
+     * });
+     *
+     * // Unbind the callback when no longer needed
+     * unbind();
+     * ```
+     */
+    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: '*', callback: (client: C, type: string | number, message: T) => void): any;
+    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T) => void): any;
+    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
+    onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T) => void): any;
+    onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
+    /**
+     * Disconnect all connected clients, and then dispose the room.
+     *
+     * @param closeCode WebSocket close code (default = 4000, which is a "consented leave")
+     * @returns Promise<void>
+     */
+    disconnect(closeCode?: number): Promise<any>;
+    private _onJoin;
+    /**
+     * Allow the specified client to reconnect into the room. Must be used inside `onLeave()` method.
+     * If seconds is provided, the reconnection is going to be cancelled after the provided amount of seconds.
+     *
+     * @param client - The client that is allowed to reconnect into the room.
+     * @param seconds - The time in seconds that the client is allowed to reconnect into the room.
+     *
+     * @returns Deferred<Client> - The differed is a promise like type.
+     *  This type can forcibly reject the promise by calling `.reject()`.
+     *
+     * @example
+     * ```typescript
+     * onDrop(client: Client, code: CloseCode) {
+     *   // Allow the client to reconnect into the room with a 15 seconds timeout.
+     *   this.allowReconnection(client, 15);
+     * }
+     * ```
+     */
+    allowReconnection(previousClient: Client, seconds: number | "manual"): Deferred<Client>;
+    private resetAutoDisposeTimeout;
+    private broadcastMessageType;
+    private sendFullState;
+    private _dequeueAfterPatchMessages;
+    private _reserveSeat;
+    private _reserveMultipleSeats;
+    private _onMessage;
+    private _onLeave;
+}
+/**
+ * (WIP) Alternative, method-based room definition.
+ * We should be able to define
+ */
+type RoomLifecycleMethods = 'messages' | 'onCreate' | 'onJoin' | 'onLeave' | 'onDispose' | 'onCacheRoom' | 'onRestoreRoom' | 'onDrop' | 'onReconnect' | 'onUncaughtException' | 'onAuth' | 'onBeforeShutdown' | 'onBeforePatch';
+type DefineRoomOptions<T extends RoomOptions = RoomOptions> = Partial<Pick<Room<T>, RoomLifecycleMethods>> & {
+    state?: ExtractRoomState<T> | (() => ExtractRoomState<T>);
+} & ThisType<Exclude<Room<T>, RoomLifecycleMethods>> & ThisType<Room<T>>;
+export declare function room<T>(options: DefineRoomOptions<T>): typeof Room<T>;
+export {};

package/build/{Server.d.ts → src/Server.d.ts}

@@ -1,10 +1,10 @@
-import http, { IncomingMessage, ServerResponse } from 'http';
-import * as matchMaker from './MatchMaker.js';
-import { RegisteredHandler } from './matchmaker/RegisteredHandler.js';
-import { Presence } from './presence/Presence.js';
-import { Room } from './Room.js';
-import { Type } from './utils/types.js';
-import { Transport } from './Transport.js';
+import * as matchMaker from './MatchMaker.ts';
+import { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
+import { type OnCreateOptions, Room } from './Room.ts';
+import { type Type } from './utils/Utils.ts';
+import type { Presence } from "./presence/Presence.ts";
+import { Transport } from './Transport.ts';
+import { type Router } from './router/index.ts';
 export type ServerOptions = {
     publicAddress?: string;
     presence?: Presence;
@@ -34,21 +34,20 @@ export type ServerOptions = {
      * Default: true
      */
     greet?: boolean;
-    /**
-     * Options below are now part of WebSocketTransport (@colyseus/ws-transport)
-     * TODO: remove me on 0.15.0
-     */
-    /** @deprecated */
-    pingInterval?: number;
-    /** @deprecated */
-    pingMaxRetries?: number;
-    /** @deprecated */
-    verifyClient?: any;
-    /** @deprecated */
-    server?: http.Server;
 };
-export declare class Server {
+/**
+ * Exposed types for the client-side SDK.
+ */
+export interface SDKTypes<RoomTypes extends Record<string, RegisteredHandler> = any, Routes extends Router = any> {
+    '~rooms': RoomTypes;
+    '~routes': Routes;
+}
+export declare class Server<RoomTypes extends Record<string, RegisteredHandler> = any, Routes extends Router = any> implements SDKTypes<RoomTypes, Routes> {
+    '~rooms': RoomTypes;
+    '~routes': Routes;
     transport: Transport;
+    router: Routes;
+    options: ServerOptions;
     protected presence: Presence;
     protected driver: matchMaker.MatchMakerDriver;
     protected port: number;
@@ -65,7 +64,6 @@ export declare class Server {
      * @param listeningListener
      */
     listen(port: number, hostname?: string, backlog?: number, listeningListener?: Function): Promise<void>;
-    registerProcessForDiscovery(): Promise<void>;
     /**
      * Define a new type of room for matchmaking.
      *
@@ -73,8 +71,8 @@ export declare class Server {
      * @param roomClass Room class definition
      * @param defaultOptions default options for `onCreate`
      */
-    define<T extends Type<Room>>(roomClass: T, defaultOptions?: Parameters<NonNullable<InstanceType<T>['onCreate']>>[0]): RegisteredHandler;
-    define<T extends Type<Room>>(name: string, roomClass: T, defaultOptions?: Parameters<NonNullable<InstanceType<T>['onCreate']>>[0]): RegisteredHandler;
+    define<T extends Type<Room>>(roomClass: T, defaultOptions?: OnCreateOptions<T>): RegisteredHandler;
+    define<T extends Type<Room>>(name: string, roomClass: T, defaultOptions?: OnCreateOptions<T>): RegisteredHandler;
     /**
      * Remove a room definition from matchmaking.
      * This method does not destroy any room. It only dissallows matchmaking
@@ -95,6 +93,6 @@ export declare class Server {
     protected getDefaultTransport(_: any): Transport;
     protected onShutdownCallback: () => void | Promise<any>;
     protected onBeforeShutdownCallback: () => void | Promise<any>;
-    protected attachMatchMakingRoutes(server: http.Server): void;
-    protected handleMatchMakeRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
 }
+export declare function defineServer<T extends Record<string, RegisteredHandler>, R extends Router>(roomHandlers: T, router?: R, serverOptions?: ServerOptions): Server<T, R>;
+export declare function defineRoom<T extends Type<Room>>(roomKlass: T, defaultOptions?: Parameters<NonNullable<InstanceType<T>['onCreate']>>[0]): RegisteredHandler<T>;