@colyseus/shared-types 0.17.3 → 0.17.5

package/build/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n * Note: onJoin is optional because core Room defines it as optional.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin?: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Extract instance type from a constructor type.\n * If T is not a constructor, returns T as-is.\n */\ntype Instantiate<T> = T extends abstract new (...args: any) => infer I ? I : T;\n\n/**\n * Check if a type is a Schema (has ~refId marker).\n * Schema defines ~refId as optional, so we check keyof instead of property presence.\n */\ntype IsSchema<T> = '~refId' extends keyof T ? true : false;\n\n/**\n * Check if ~state phantom property contains a useful type (not object/any/never).\n * Returns true if ~state exists and has meaningful structure.\n */\ntype HasUsefulStatePhantom<T> = T extends { '~state': infer S }\n    ? [S] extends [never] ? false           // never is not useful\n    : unknown extends S ? false             // any is not useful\n    : S extends object\n        ? [keyof S] extends [never] ? false // {} or object with no keys is not useful\n        : true\n        : false\n    : false;\n\n/**\n * Extract state from a Room-like instance type.\n * Priority: useful ~state phantom > Schema state property > return T as-is\n */\ntype ExtractStateFromRoom<T> = T extends { '~state': infer S }\n    ? HasUsefulStatePhantom<T> extends true\n        ? S  // Use ~state if it's useful\n        : T extends { state: infer St }\n            ? IsSchema<St> extends true ? St : T  // Fallback to state if Schema\n            : T\n    : T extends { state: infer S }\n        ? IsSchema<S> extends true ? S : T\n        : T;\n\n/**\n * Infer the state type from T, or use explicit S if provided.\n *\n * Supports multiple usage patterns:\n * - Room<MyState>: T is a Schema type, return as-is\n * - Room<MyRoom>: T is a Room instance, extract from ~state or state property\n * - Room<typeof MyRoom>: T is a constructor, instantiate first then extract\n * - Room<T, ExplicitState>: S overrides all inference\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? Instantiate<T> extends infer I\n        ? IsSchema<I> extends true\n            ? I  // It's a Schema, return as-is\n            : ExtractStateFromRoom<I>\n        : never\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = Instantiate<T> extends { '~state': any } ? T : any;\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = Instantiate<T> extends { messages: infer M } ? M : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = Instantiate<T> extends { '~client': { '~messages': infer M } } ? M : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * A map of message types to message handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, MessageHandler<Client, Room>>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"],
+  "sourcesContent": ["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n * Note: onJoin is optional because core Room defines it as optional.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin?: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Extract instance type from a constructor type.\n * If T is not a constructor, returns T as-is.\n */\ntype Instantiate<T> = T extends abstract new (...args: any) => infer I ? I : T;\n\n/**\n * Check if a type is a Schema (has ~refId marker).\n * Schema defines ~refId as optional, so we check keyof instead of property presence.\n */\ntype IsSchema<T> = '~refId' extends keyof T ? true : false;\n\n/**\n * Check if ~state phantom property contains a useful type (not object/any/never).\n * Returns true if ~state exists and has meaningful structure.\n */\ntype HasUsefulStatePhantom<T> = T extends { '~state': infer S }\n    ? [S] extends [never] ? false           // never is not useful\n    : unknown extends S ? false             // any is not useful\n    : S extends object\n        ? [keyof S] extends [never] ? false // {} or object with no keys is not useful\n        : true\n        : false\n    : false;\n\n/**\n * Extract state from a Room-like instance type.\n * Priority: useful ~state phantom > Schema state property > return T as-is\n */\ntype ExtractStateFromRoom<T> = T extends { '~state': infer S }\n    ? HasUsefulStatePhantom<T> extends true\n        ? S  // Use ~state if it's useful\n        : T extends { state: infer St }\n            ? IsSchema<St> extends true ? St : T  // Fallback to state if Schema\n            : T\n    : T extends { state: infer S }\n        ? IsSchema<S> extends true ? S : T\n        : T;\n\n/**\n * Infer the state type from T, or use explicit S if provided.\n *\n * Supports multiple usage patterns:\n * - Room<MyState>: T is a Schema type, return as-is\n * - Room<MyRoom>: T is a Room instance, extract from ~state or state property\n * - Room<typeof MyRoom>: T is a constructor, instantiate first then extract\n * - Room<T, ExplicitState>: S overrides all inference\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? Instantiate<T> extends infer I\n        ? IsSchema<I> extends true\n            ? I  // It's a Schema, return as-is\n            : ExtractStateFromRoom<I>\n        : never\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = Instantiate<T> extends { '~state': any } ? T : any;\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = Instantiate<T> extends { messages: infer M } ? M : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = Instantiate<T> extends { '~client': { '~messages': infer M } } ? M : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * Fallback message handler that receives the message type as an additional parameter.\n * Used for \"_\" or \"*\" catch-all handlers.\n *\n * @template Client - The client type\n * @template This - The Room class context\n */\nexport type FallbackMessageHandler<Client = any, This = any> =\n  (this: This, client: Client, type: string, message: any) => void;\n\n/**\n * Message handler type including fallback handlers.\n * Used internally to allow \"_\" and \"*\" fallback handlers in the Messages type.\n * @internal\n */\nexport type AnyMessageHandler<Client = any, This = any> =\n  | MessageHandler<Client, This>\n  | FallbackMessageHandler<Client, This>;\n\n/**\n * A map of message types to message handlers.\n * Supports special \"_\" and \"*\" keys for fallback/catch-all handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, AnyMessageHandler<Client, Room>> & ThisType<Room>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,sBAA+C;",
   "names": []
 }

package/build/index.d.ts

@@ -115,13 +115,28 @@ 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;
+/**
+ * Fallback message handler that receives the message type as an additional parameter.
+ * Used for "_" or "*" catch-all handlers.
+ *
+ * @template Client - The client type
+ * @template This - The Room class context
+ */
+export type FallbackMessageHandler<Client = any, This = any> = (this: This, client: Client, type: string, message: any) => void;
+/**
+ * Message handler type including fallback handlers.
+ * Used internally to allow "_" and "*" fallback handlers in the Messages type.
+ * @internal
+ */
+export type AnyMessageHandler<Client = any, This = any> = MessageHandler<Client, This> | FallbackMessageHandler<Client, This>;
 /**
  * A map of message types to message handlers.
+ * Supports special "_" and "*" keys for fallback/catch-all handlers.
  *
  * @template Room - The Room class type
  * @template Client - The client type
  */
-export type Messages<Room = any, Client = any> = Record<string, MessageHandler<Client, Room>>;
+export type Messages<Room = any, Client = any> = Record<string, AnyMessageHandler<Client, Room>> & ThisType<Room>;
 /**
  * Exposed types for the client-side SDK.
  * Used by defineServer() to expose room and route types to the client.

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,2BAA2B;AAC3B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC","sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Helper types for flexible Room generics on the client SDK.\n * Allows: Room<State>, Room<ServerRoom>, or Room<ServerRoom, State>\n *\n * Uses `~state` phantom property to distinguish Room types from plain state types.\n * This prevents incorrectly extracting `state` from a state type that happens to have a `state` property.\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? (T extends abstract new (...args: any) => { '~state': infer ST }\n        ? ST  // Constructor type (typeof MyRoom): extract state via ~state phantom\n        : T extends { '~state': infer ST }\n            ? ST  // Instance type (MyRoom): extract state via ~state phantom\n            : T)  // State type or other: return as-is\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = T extends abstract new (...args: any) => { '~state': any }\n    ? T  // Constructor type with ~state: keep as-is\n    : T extends { '~state': any }\n        ? T  // Instance type with ~state: keep as-is\n        : any;  // Plain state type: normalize to any\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = T extends abstract new (...args: any) => { messages: infer M }\n    ? M\n    : T extends { messages: infer M }\n        ? M\n        : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = T extends abstract new (...args: any) => { '~client': { '~messages': infer M } }\n    ? M\n    : T extends { '~client': { '~messages': infer M } }\n        ? M\n        : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * A map of message types to message handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, MessageHandler<Client, Room>>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,2BAA2B;AAC3B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC","sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n * Note: onJoin is optional because core Room defines it as optional.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin?: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Extract instance type from a constructor type.\n * If T is not a constructor, returns T as-is.\n */\ntype Instantiate<T> = T extends abstract new (...args: any) => infer I ? I : T;\n\n/**\n * Check if a type is a Schema (has ~refId marker).\n * Schema defines ~refId as optional, so we check keyof instead of property presence.\n */\ntype IsSchema<T> = '~refId' extends keyof T ? true : false;\n\n/**\n * Check if ~state phantom property contains a useful type (not object/any/never).\n * Returns true if ~state exists and has meaningful structure.\n */\ntype HasUsefulStatePhantom<T> = T extends { '~state': infer S }\n    ? [S] extends [never] ? false           // never is not useful\n    : unknown extends S ? false             // any is not useful\n    : S extends object\n        ? [keyof S] extends [never] ? false // {} or object with no keys is not useful\n        : true\n        : false\n    : false;\n\n/**\n * Extract state from a Room-like instance type.\n * Priority: useful ~state phantom > Schema state property > return T as-is\n */\ntype ExtractStateFromRoom<T> = T extends { '~state': infer S }\n    ? HasUsefulStatePhantom<T> extends true\n        ? S  // Use ~state if it's useful\n        : T extends { state: infer St }\n            ? IsSchema<St> extends true ? St : T  // Fallback to state if Schema\n            : T\n    : T extends { state: infer S }\n        ? IsSchema<S> extends true ? S : T\n        : T;\n\n/**\n * Infer the state type from T, or use explicit S if provided.\n *\n * Supports multiple usage patterns:\n * - Room<MyState>: T is a Schema type, return as-is\n * - Room<MyRoom>: T is a Room instance, extract from ~state or state property\n * - Room<typeof MyRoom>: T is a constructor, instantiate first then extract\n * - Room<T, ExplicitState>: S overrides all inference\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? Instantiate<T> extends infer I\n        ? IsSchema<I> extends true\n            ? I  // It's a Schema, return as-is\n            : ExtractStateFromRoom<I>\n        : never\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = Instantiate<T> extends { '~state': any } ? T : any;\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = Instantiate<T> extends { messages: infer M } ? M : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = Instantiate<T> extends { '~client': { '~messages': infer M } } ? M : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * Fallback message handler that receives the message type as an additional parameter.\n * Used for \"_\" or \"*\" catch-all handlers.\n *\n * @template Client - The client type\n * @template This - The Room class context\n */\nexport type FallbackMessageHandler<Client = any, This = any> =\n  (this: This, client: Client, type: string, message: any) => void;\n\n/**\n * Message handler type including fallback handlers.\n * Used internally to allow \"_\" and \"*\" fallback handlers in the Messages type.\n * @internal\n */\nexport type AnyMessageHandler<Client = any, This = any> =\n  | MessageHandler<Client, This>\n  | FallbackMessageHandler<Client, This>;\n\n/**\n * A map of message types to message handlers.\n * Supports special \"_\" and \"*\" keys for fallback/catch-all handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, AnyMessageHandler<Client, Room>> & ThisType<Room>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"]}

package/build/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n * Note: onJoin is optional because core Room defines it as optional.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin?: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Extract instance type from a constructor type.\n * If T is not a constructor, returns T as-is.\n */\ntype Instantiate<T> = T extends abstract new (...args: any) => infer I ? I : T;\n\n/**\n * Check if a type is a Schema (has ~refId marker).\n * Schema defines ~refId as optional, so we check keyof instead of property presence.\n */\ntype IsSchema<T> = '~refId' extends keyof T ? true : false;\n\n/**\n * Check if ~state phantom property contains a useful type (not object/any/never).\n * Returns true if ~state exists and has meaningful structure.\n */\ntype HasUsefulStatePhantom<T> = T extends { '~state': infer S }\n    ? [S] extends [never] ? false           // never is not useful\n    : unknown extends S ? false             // any is not useful\n    : S extends object\n        ? [keyof S] extends [never] ? false // {} or object with no keys is not useful\n        : true\n        : false\n    : false;\n\n/**\n * Extract state from a Room-like instance type.\n * Priority: useful ~state phantom > Schema state property > return T as-is\n */\ntype ExtractStateFromRoom<T> = T extends { '~state': infer S }\n    ? HasUsefulStatePhantom<T> extends true\n        ? S  // Use ~state if it's useful\n        : T extends { state: infer St }\n            ? IsSchema<St> extends true ? St : T  // Fallback to state if Schema\n            : T\n    : T extends { state: infer S }\n        ? IsSchema<S> extends true ? S : T\n        : T;\n\n/**\n * Infer the state type from T, or use explicit S if provided.\n *\n * Supports multiple usage patterns:\n * - Room<MyState>: T is a Schema type, return as-is\n * - Room<MyRoom>: T is a Room instance, extract from ~state or state property\n * - Room<typeof MyRoom>: T is a constructor, instantiate first then extract\n * - Room<T, ExplicitState>: S overrides all inference\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? Instantiate<T> extends infer I\n        ? IsSchema<I> extends true\n            ? I  // It's a Schema, return as-is\n            : ExtractStateFromRoom<I>\n        : never\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = Instantiate<T> extends { '~state': any } ? T : any;\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = Instantiate<T> extends { messages: infer M } ? M : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = Instantiate<T> extends { '~client': { '~messages': infer M } } ? M : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * A map of message types to message handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, MessageHandler<Client, Room>>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"],
+  "sourcesContent": ["import type { StandardSchemaV1 } from '@standard-schema/spec';\n\n// Re-export StandardSchemaV1 for convenience\nexport type { StandardSchemaV1 };\n\n// Re-export Protocol types\nexport { Protocol, ErrorCode, CloseCode } from './Protocol.js';\n\n/**\n * Minimal Room-like interface for SDK type inference.\n * Allows typing SDK methods without depending on @colyseus/core.\n * Note: onJoin is optional because core Room defines it as optional.\n */\nexport interface ServerRoomLike<State = any, Options = any> {\n  state: State;\n  onJoin?: (client: any, options?: Options, auth?: any) => any;\n  messages?: Record<string, any>;\n  '~client'?: { '~messages'?: Record<string, any> };\n}\n\n/**\n * Seat reservation returned by matchmaking operations.\n */\nexport interface ISeatReservation {\n  name: string;\n  sessionId: string;\n  roomId: string;\n  publicAddress?: string;\n  processId?: string;\n  reconnectionToken?: string;\n  devMode?: boolean;\n}\n\n/**\n * Extract instance type from a constructor type.\n * If T is not a constructor, returns T as-is.\n */\ntype Instantiate<T> = T extends abstract new (...args: any) => infer I ? I : T;\n\n/**\n * Check if a type is a Schema (has ~refId marker).\n * Schema defines ~refId as optional, so we check keyof instead of property presence.\n */\ntype IsSchema<T> = '~refId' extends keyof T ? true : false;\n\n/**\n * Check if ~state phantom property contains a useful type (not object/any/never).\n * Returns true if ~state exists and has meaningful structure.\n */\ntype HasUsefulStatePhantom<T> = T extends { '~state': infer S }\n    ? [S] extends [never] ? false           // never is not useful\n    : unknown extends S ? false             // any is not useful\n    : S extends object\n        ? [keyof S] extends [never] ? false // {} or object with no keys is not useful\n        : true\n        : false\n    : false;\n\n/**\n * Extract state from a Room-like instance type.\n * Priority: useful ~state phantom > Schema state property > return T as-is\n */\ntype ExtractStateFromRoom<T> = T extends { '~state': infer S }\n    ? HasUsefulStatePhantom<T> extends true\n        ? S  // Use ~state if it's useful\n        : T extends { state: infer St }\n            ? IsSchema<St> extends true ? St : T  // Fallback to state if Schema\n            : T\n    : T extends { state: infer S }\n        ? IsSchema<S> extends true ? S : T\n        : T;\n\n/**\n * Infer the state type from T, or use explicit S if provided.\n *\n * Supports multiple usage patterns:\n * - Room<MyState>: T is a Schema type, return as-is\n * - Room<MyRoom>: T is a Room instance, extract from ~state or state property\n * - Room<typeof MyRoom>: T is a constructor, instantiate first then extract\n * - Room<T, ExplicitState>: S overrides all inference\n */\nexport type InferState<T, S> = [S] extends [never]\n    ? Instantiate<T> extends infer I\n        ? IsSchema<I> extends true\n            ? I  // It's a Schema, return as-is\n            : ExtractStateFromRoom<I>\n        : never\n    : S;\n\n/**\n * Normalizes T for message extraction: returns T if it has ~state (Room type),\n * otherwise returns any (plain state type). This ensures Room<State> is equivalent\n * to Room<any, State> when State doesn't have ~state.\n */\nexport type NormalizeRoomType<T> = Instantiate<T> extends { '~state': any } ? T : any;\n\n/**\n * Extract room messages type from a Room constructor or instance type.\n * Supports both constructor types (typeof MyRoom) and instance types (MyRoom)\n */\nexport type ExtractRoomMessages<T> = Instantiate<T> extends { messages: infer M } ? M : {};\n\n/**\n * Extract client-side messages type from a Room constructor or instance type.\n * These are messages that the server can send to the client.\n */\nexport type ExtractRoomClientMessages<T> = Instantiate<T> extends { '~client': { '~messages': infer M } } ? M : {};\n\n/**\n * Message handler with automatic type inference from format schema.\n * When a format is provided, the message type is automatically inferred from the schema.\n *\n * @template T - The StandardSchema type for message validation\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandlerWithFormat<T extends StandardSchemaV1 = any, Client = any, This = any> = {\n  format: T;\n  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void;\n};\n\n/**\n * Message handler type that can be either a function or a format handler with validation.\n *\n * @template Client - The client type (from @colyseus/core Transport)\n * @template This - The Room class context\n */\nexport type MessageHandler<Client = any, This = any> =\n  | ((this: This, client: Client, message: any) => void)\n  | MessageHandlerWithFormat<any, Client, This>;\n\n/**\n * Extract the message payload type from a message handler.\n * Works with both function handlers and format handlers.\n */\nexport type ExtractMessageType<T> =\n  T extends { format: infer Format extends StandardSchemaV1; handler: any }\n    ? StandardSchemaV1.InferOutput<Format>\n    : T extends (this: any, client: any, message: infer Message) => void\n      ? Message\n      : any;\n\n/**\n * Fallback message handler that receives the message type as an additional parameter.\n * Used for \"_\" or \"*\" catch-all handlers.\n *\n * @template Client - The client type\n * @template This - The Room class context\n */\nexport type FallbackMessageHandler<Client = any, This = any> =\n  (this: This, client: Client, type: string, message: any) => void;\n\n/**\n * Message handler type including fallback handlers.\n * Used internally to allow \"_\" and \"*\" fallback handlers in the Messages type.\n * @internal\n */\nexport type AnyMessageHandler<Client = any, This = any> =\n  | MessageHandler<Client, This>\n  | FallbackMessageHandler<Client, This>;\n\n/**\n * A map of message types to message handlers.\n * Supports special \"_\" and \"*\" keys for fallback/catch-all handlers.\n *\n * @template Room - The Room class type\n * @template Client - The client type\n */\nexport type Messages<Room = any, Client = any> = Record<string, AnyMessageHandler<Client, Room>> & ThisType<Room>;\n\n/**\n * Exposed types for the client-side SDK.\n * Used by defineServer() to expose room and route types to the client.\n *\n * @template RoomTypes - Record of room names to their RegisteredHandler types\n * @template Routes - Router type from @colyseus/better-call\n */\nexport interface SDKTypes<\n  RoomTypes extends Record<string, any> = any,\n  Routes = any\n> {\n  '~rooms': RoomTypes;\n  '~routes': Routes;\n}\n"],
   "mappings": ";AAMA,SAAS,UAAU,WAAW,iBAAiB;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/shared-types",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "Shared TypeScript types for Colyseus server and client SDK",
   "type": "module",
   "input": "./src/index.ts",
@@ -47,8 +47,8 @@
   },
   "devDependencies": {
     "vitest": "^3.1.1",
-    "@colyseus/core": "^0.17.21",
-    "@colyseus/sdk": "^0.17.21"
+    "@colyseus/sdk": "^0.17.25",
+    "@colyseus/core": "^0.17.26"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -140,13 +140,33 @@ export type ExtractMessageType<T> =
       ? Message
       : any;
 
+/**
+ * Fallback message handler that receives the message type as an additional parameter.
+ * Used for "_" or "*" catch-all handlers.
+ *
+ * @template Client - The client type
+ * @template This - The Room class context
+ */
+export type FallbackMessageHandler<Client = any, This = any> =
+  (this: This, client: Client, type: string, message: any) => void;
+
+/**
+ * Message handler type including fallback handlers.
+ * Used internally to allow "_" and "*" fallback handlers in the Messages type.
+ * @internal
+ */
+export type AnyMessageHandler<Client = any, This = any> =
+  | MessageHandler<Client, This>
+  | FallbackMessageHandler<Client, This>;
+
 /**
  * A map of message types to message handlers.
+ * Supports special "_" and "*" keys for fallback/catch-all handlers.
  *
  * @template Room - The Room class type
  * @template Client - The client type
  */
-export type Messages<Room = any, Client = any> = Record<string, MessageHandler<Client, Room>>;
+export type Messages<Room = any, Client = any> = Record<string, AnyMessageHandler<Client, Room>> & ThisType<Room>;
 
 /**
  * Exposed types for the client-side SDK.