@bytesocket/types - npm Package Compare versions

Comparing version 0.1.7 to 0.1.8

dist/index.cjs.map

@@ -1,1 +0,1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["LifecycleTypes","AuthState"],"mappings":";;;AAgCO,IAAK,cAAA,qBAAAA,eAAAA,KAAL;AACN,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,kBAAe,CAAA,CAAA,GAAf,cAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,CAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,qBAAkB,EAAA,CAAA,GAAlB,iBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,iBAAc,EAAA,CAAA,GAAd,aAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,yBAAsB,EAAA,CAAA,GAAtB,qBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AAxBW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAwKL,IAAK,SAAA,qBAAAC,UAAAA,KAAL;AAEN,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AAVW,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA","file":"index.cjs","sourcesContent":["import type { Options } from \"msgpackr\";\n\n/**\n * Extracts only the string keys from a type `T`.\n * Useful for strongly typing room names from a user-defined event map.\n *\n * @example\n * type MyEvents = { emitRoom: { chat: { message: string } } };\n * type RoomNames = StringKeys<MyEvents['emitRoom']>; // \"chat\"\n */\nexport type StringKeys<T> = Extract<keyof NonNullable<T>, string>;\n\n/**\n * Extracts keys that are either string or number from a type `T`.\n * Typically used for event names (which may be strings or numeric codes).\n *\n * @example\n * type MyEvents = { listen: { \"new_message\": string; 42: number } };\n * type EventNames = StringNumberKeys<MyEvents['listen']>; // \"new_message\" | 42\n */\nexport type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;\n\n/**\n * Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false.\n */\nexport type MsgpackrOptions = Omit<Options, \"useRecords\">;\n\n/**\n * Enumeration of all lifecycle message types used internally by ByteSocket.\n * These correspond to system-level events like connection open, authentication,\n * room join/leave, and errors.\n */\nexport enum LifecycleTypes {\n\topen = 1,\n\tclose = 2,\n\terror = 3,\n\tauth = 4,\n\tauth_success = 5,\n\tauth_error = 6,\n\tping = 7,\n\tpong = 8,\n\tjoin_room = 9,\n\tjoin_room_success = 10,\n\tjoin_room_error = 11,\n\tleave_room = 12,\n\tleave_room_success = 13,\n\tleave_room_error = 14,\n\tjoin_rooms = 15,\n\tjoin_rooms_success = 16,\n\tjoin_rooms_error = 17,\n\tleave_rooms = 18,\n\tleave_rooms_success = 19,\n\tleave_rooms_error = 20,\n\tqueue_full = 21,\n\treconnect_failed = 22,\n\tupgrade = 23,\n\tmessage = 24,\n}\n\n/**\n * Context object passed to error handlers, providing details about where an error occurred.\n */\nexport type ErrorContext = {\n\t/** The phase or component where the error originated (e.g., \"decode\", \"auth\", \"middleware\") */\n\tphase: string;\n\t/** The error object itself, if any */\n\terror?: unknown;\n\t/** The event name involved, if applicable */\n\tevent?: string;\n\t/** Raw message content (stringified) for debugging */\n\traw?: string;\n\t/** WebSocket close code, if applicable */\n\tcode?: number;\n\t/** Number of bytes received, if applicable */\n\tbytes?: number;\n};\n\n/**\n * Lifecycle message shape for events without additional data.\n */\nexport type LifecycleType = {\n\ttype: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;\n};\n\n/**\n * Lifecycle message shape for single-room operations (join/leave request/success).\n */\nexport type LifecycleRoomType<R extends string> = {\n\ttype: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;\n\troom: R;\n};\n\n/**\n * Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success).\n */\nexport type LifecycleRoomsType<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;\n\trooms: Rs;\n};\n\n/**\n * Lifecycle message shape for events that carry generic data (error, auth, auth_error).\n */\nexport type LifecyclePayload<D> = {\n\ttype: LifecycleTypes.auth;\n\tdata: D;\n};\n\n/**\n * Lifecycle message shape for events that carry generic data (error, auth, auth_error).\n */\nexport type LifecycleError = {\n\ttype: LifecycleTypes.error | LifecycleTypes.auth_error;\n\tdata: ErrorContext;\n};\n\n/**\n * Lifecycle error message for a single room.\n */\nexport type LifecycleRoomError<R extends string> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: ErrorContext;\n};\n\n/**\n * Lifecycle error message for multiple rooms.\n */\nexport type LifecycleRoomsError<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: ErrorContext;\n};\n\n/**\n * Union of all possible lifecycle messages that ByteSocket may send or receive.\n */\nexport type LifecycleMessage<R extends string, D> =\n\t| LifecycleType\n\t| LifecycleRoomType<R>\n\t| LifecycleRoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| LifecycleError\n\t| LifecycleRoomError<R>\n\t| LifecycleRoomsError<R[]>;\n\n/**\n * User‑defined event sent to a specific room.\n *\n * @example\n * // Emitting to room \"chat\" with event \"message\"\n * socket.rooms.emit(\"chat\", \"message\", { text: \"Hello!\" });\n */\nexport type RoomEvent<R extends string, E extends string | number, D> = {\n\troom: R;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent to multiple rooms simultaneously.\n *\n * @example\n * // Emitting to rooms [\"lobby\", \"announcements\"]\n * socket.rooms.bulk.emit([\"lobby\", \"announcements\"], \"alert\", { msg: \"Server restart in 5m\" });\n */\nexport type RoomsEvent<Rs extends readonly string[], E extends string | number, D> = {\n\trooms: Rs;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent globally (no room context).\n *\n * @example\n * socket.emit(\"userJoined\", { userId: \"abc123\" });\n */\nexport type GeneralEvent<E extends string | number, D> = {\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * Union of all possible user messages that can be emitted or listened to.\n */\nexport type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> =\n\t| GeneralEvent<E, D>\n\t| RoomEvent<R, E, D>\n\t| RoomsEvent<R[], E, D>;\n\n/**\n * Generic callback type used internally.\n * @internal\n */\nexport type AnyCallback = (...args: any[]) => Promise<void> | void;\n\n/**\n * Authentication state of a socket.\n */\nexport enum AuthState {\n\t/** Initial state before any connection attempt. */\n\tidle = 1,\n\t/** No authentication required / not configured. */\n\tnone = 2,\n\t/** Authentication request sent, awaiting server response. */\n\tpending = 3,\n\t/** Authentication successful. */\n\tsuccess = 4,\n\t/** Authentication failed permanently. */\n\tfailed = 5,\n}\n\n/**\n * Defines the shape of event maps for a type‑safe ByteSocket instance.\n *\n * @typeParam T - A map of event names to their payload types.\n *\n * @example\n * interface MyEvents extends SocketEvents<{\n *   emit: {\n *     message: { text: string };\n *     'user:typing': { userId: string };\n *   };\n *   listen: {\n *     message: { text: string; sender: string };\n *     connected: { userId: string };\n *   };\n *   emitRoom: {\n *     chat: { message: string };\n *     private: { whisper: string };\n *   };\n *   listenRoom: {\n *     chat: { message: string; sender: string };\n *   };\n * }> {}\n *\n * const io = new ByteSocket<MyEvents>('ws://...');     // for client\n * const io = new ByteSocket<MyEvents>(app);            // for server\n *\n * io.emit('message', { text: 'hello' });               // typed\n * io.emit('chat', { message: 'hi' });                  // typed room emit\n * io.on('message', (data) => { data.sender });         // typed\n * io.rooms.on('chat', 'message', (data) => {});        // typed room listen\n */\nexport type SocketEvents<T extends { [event: string | number]: unknown } = { [event: string | number]: unknown }> = {\n\t/** Events that can be emitted globally. */\n\temit?: T;\n\t/** Events that can be listened to globally. */\n\tlisten?: T;\n\t/** Events that can be emitted to a specific room, keyed by room name. */\n\temitRoom?: { [room: string]: T };\n\t/** Events that can be listened to on a specific room, keyed by room name. */\n\tlistenRoom?: { [room: string]: T };\n\t/** Events that can be emitted to multiple rooms at once. */\n\temitRooms?: { rooms: string[]; events: T };\n};\n\n/**\n * Extracts the event map for a specific set of rooms from `emitRooms`.\n */\nexport type EventsForRooms<T extends NonNullable<SocketEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["LifecycleTypes","AuthState"],"mappings":";;;AA8BO,IAAK,cAAA,qBAAAA,eAAAA,KAAL;AACN,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,kBAAe,CAAA,CAAA,GAAf,cAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,CAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,qBAAkB,EAAA,CAAA,GAAlB,iBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,iBAAc,EAAA,CAAA,GAAd,aAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,yBAAsB,EAAA,CAAA,GAAtB,qBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AAxBW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAkJL,IAAK,SAAA,qBAAAC,UAAAA,KAAL;AAEN,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AAVW,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA","file":"index.cjs","sourcesContent":["import type { Options } from \"msgpackr\";\n\n/**\n * Extracts only the string keys from a type `T`.\n * Useful for strongly typing room names from a user-defined event map.\n *\n * @example\n * type MyEvents = { emitRoom: { chat: { message: string } } };\n * type RoomNames = StringKeys<MyEvents['emitRoom']>; // \"chat\"\n */\nexport type StringKeys<T> = Extract<keyof NonNullable<T>, string>;\n\n/**\n * Extracts keys that are either string or number from a type `T`.\n * Typically used for event names (which may be strings or numeric codes).\n *\n * @example\n * type MyEvents = { listen: { \"new_message\": string; 42: number } };\n * type EventNames = StringNumberKeys<MyEvents['listen']>; // \"new_message\" | 42\n */\nexport type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;\n\n/** Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false. */\nexport type MsgpackrOptions = Omit<Options, \"useRecords\">;\n\n/**\n * Enumeration of all lifecycle message types used internally by ByteSocket.\n * These correspond to system-level events like connection open, authentication,\n * room join/leave, and errors.\n */\nexport enum LifecycleTypes {\n\topen = 1,\n\tclose = 2,\n\terror = 3,\n\tauth = 4,\n\tauth_success = 5,\n\tauth_error = 6,\n\tping = 7,\n\tpong = 8,\n\tjoin_room = 9,\n\tjoin_room_success = 10,\n\tjoin_room_error = 11,\n\tleave_room = 12,\n\tleave_room_success = 13,\n\tleave_room_error = 14,\n\tjoin_rooms = 15,\n\tjoin_rooms_success = 16,\n\tjoin_rooms_error = 17,\n\tleave_rooms = 18,\n\tleave_rooms_success = 19,\n\tleave_rooms_error = 20,\n\tqueue_full = 21,\n\treconnect_failed = 22,\n\tupgrade = 23,\n\tmessage = 24,\n}\n\n/** Context object passed to error handlers, providing details about where an error occurred. */\nexport type ErrorContext = {\n\t/** The phase or component where the error originated (e.g., \"decode\", \"auth\", \"middleware\") */\n\tphase: string;\n\t/** The error object itself, if any */\n\terror?: unknown;\n\t/** The event name involved, if applicable */\n\tevent?: string;\n\t/** Raw message content (stringified) for debugging */\n\traw?: string;\n\t/** WebSocket close code, if applicable */\n\tcode?: number;\n\t/** Number of bytes received, if applicable */\n\tbytes?: number;\n};\n\n/** Lifecycle message shape for events without additional data. */\nexport type LifecycleType = {\n\ttype: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;\n};\n\n/** Lifecycle message shape for single-room operations (join/leave request/success). */\nexport type LifecycleRoomType<R extends string> = {\n\ttype: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;\n\troom: R;\n};\n\n/** Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success). */\nexport type LifecycleRoomsType<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;\n\trooms: Rs;\n};\n\n/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */\nexport type LifecyclePayload<D> = {\n\ttype: LifecycleTypes.auth;\n\tdata: D;\n};\n\n/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */\nexport type LifecycleError = {\n\ttype: LifecycleTypes.error | LifecycleTypes.auth_error;\n\tdata: ErrorContext;\n};\n\n/** Lifecycle error message for a single room. */\nexport type LifecycleRoomError<R extends string> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: ErrorContext;\n};\n\n/** Lifecycle error message for multiple rooms. */\nexport type LifecycleRoomsError<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: ErrorContext;\n};\n\n/** Union of all possible lifecycle messages that ByteSocket may send or receive. */\nexport type LifecycleMessage<R extends string, D> =\n\t| LifecycleType\n\t| LifecycleRoomType<R>\n\t| LifecycleRoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| LifecycleError\n\t| LifecycleRoomError<R>\n\t| LifecycleRoomsError<R[]>;\n\n/**\n * User‑defined event sent to a specific room.\n *\n * @example\n * // Emitting to room \"chat\" with event \"message\"\n * socket.rooms.emit(\"chat\", \"message\", { text: \"Hello!\" });\n */\nexport type RoomEvent<R extends string, E extends string | number, D> = {\n\troom: R;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent to multiple rooms simultaneously.\n *\n * @example\n * // Emitting to rooms [\"lobby\", \"announcements\"]\n * socket.rooms.bulk.emit([\"lobby\", \"announcements\"], \"alert\", { msg: \"Server restart in 5m\" });\n */\nexport type RoomsEvent<Rs extends readonly string[], E extends string | number, D> = {\n\trooms: Rs;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent globally (no room context).\n *\n * @example\n * socket.emit(\"userJoined\", { userId: \"abc123\" });\n */\nexport type GeneralEvent<E extends string | number, D> = {\n\tevent: E;\n\tdata: D;\n};\n\n/** Union of all possible user messages that can be emitted or listened to. */\nexport type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> =\n\t| GeneralEvent<E, D>\n\t| RoomEvent<R, E, D>\n\t| RoomsEvent<R[], E, D>;\n\n/**\n * Generic callback type used internally.\n * @internal\n */\nexport type AnyCallback = (...args: any[]) => Promise<void> | void;\n\n/** Authentication state of a socket. */\nexport enum AuthState {\n\t/** Initial state before any connection attempt. */\n\tidle = 1,\n\t/** No authentication required / not configured. */\n\tnone = 2,\n\t/** Authentication request sent, awaiting server response. */\n\tpending = 3,\n\t/** Authentication successful. */\n\tsuccess = 4,\n\t/** Authentication failed permanently. */\n\tfailed = 5,\n}\n\n/**\n * Defines the shape of event maps for a type‑safe ByteSocket instance.\n *\n * This type supports two usage patterns:\n *\n * 1. **Symmetric events (direct generic):** Provide a single event map where\n *    emit and listen share the same event names and payloads.\n *\n * 2. **Asymmetric events (interface extension):** Extend this type and override\n *    individual properties to define different maps for emit, listen, rooms, etc.\n *\n * @typeParam T - A map of event names to their payload types. Defaults to\n *                `Record<string, unknown>`.\n *\n * @example Symmetric usage (most common)\n * ```ts\n * type MyEvents = SocketEvents<{\n *   \"chat:message\": { text: string };\n *   \"user:joined\": { userId: string };\n * }>;\n *\n * const socket = new ByteSocket<MyEvents>('ws://...');\n *\n * socket.emit('chat:message', { text: 'Hello' });          // ✅ typed\n * socket.on('user:joined', (data) => console.log(data.userId)); // ✅ typed\n * socket.rooms.emit('lobby', 'chat:message', { text: 'Hi' }); // ✅ typed\n * ```\n *\n * @example Asymmetric usage (full control)\n * ```ts\n * interface MyEvents extends SocketEvents {\n *   emit: {\n *     \"message:send\": { text: string };\n *     \"room:create\": { name: string };\n *   };\n *   listen: {\n *     \"message:receive\": { text: string; sender: string };\n *     \"user:joined\": { userId: string; name: string };\n *   };\n *   emitRoom: {\n *     chat: { \"message\": { text: string } };\n *     dm:   { \"message\": { text: string; recipient: string } };\n *   };\n *   listenRoom: {\n *     chat: { \"message\": { text: string; sender: string } };\n *   };\n * }\n *\n * const socket = new ByteSocket<MyEvents>('ws://...');\n *\n * socket.emit('room:create', { name: 'general' });\t\t\t\t// ✅ global emit\n * socket.on('message:receive', (data) => data.sender);\t\t\t// ✅ global listen\n * socket.rooms.emit('chat', 'message', { text: 'Hello' });\t\t// ✅ room emit\n * ```\n */\nexport type SocketEvents<T extends { [event: string | number]: unknown } = { [event: string | number]: unknown }> = {\n\t/** Events that can be emitted globally. */\n\temit?: T;\n\t/** Events that can be listened to globally. */\n\tlisten?: T;\n\t/** Events that can be emitted to a specific room, keyed by room name. */\n\temitRoom?: { [room: string]: T };\n\t/** Events that can be listened to on a specific room, keyed by room name. */\n\tlistenRoom?: { [room: string]: T };\n\t/** Events that can be emitted to multiple rooms at once. */\n\temitRooms?: { rooms: string[]; event: T };\n};\n\n/** Extracts the event map for a specific set of rooms from `emitRooms`. */\nexport type EventsForRooms<T extends NonNullable<SocketEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"event\"];\n"]}

dist/index.d.cts

@@ -21,5 +21,3 @@ import { Options } from 'msgpackr';
 type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;
-/**
- * Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false.
- */
+/** Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false. */
 type MsgpackrOptions = Omit<Options, "useRecords">;
@@ -57,5 +55,3 @@ /**
 }
-/**
- * Context object passed to error handlers, providing details about where an error occurred.
- */
+/** Context object passed to error handlers, providing details about where an error occurred. */
 type ErrorContext = {
@@ -75,11 +71,7 @@ /** The phase or component where the error originated (e.g., "decode", "auth", "middleware") */
 };
-/**
- * Lifecycle message shape for events without additional data.
- */
+/** Lifecycle message shape for events without additional data. */
 type LifecycleType = {
     type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;
 };
-/**
- * Lifecycle message shape for single-room operations (join/leave request/success).
- */
+/** Lifecycle message shape for single-room operations (join/leave request/success). */
 type LifecycleRoomType<R extends string> = {
@@ -89,5 +81,3 @@ type: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;
 };
-/**
- * Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success).
- */
+/** Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success). */
 type LifecycleRoomsType<Rs extends readonly string[]> = {
@@ -97,5 +87,3 @@ type: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;
 };
-/**
- * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
- */
+/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */
 type LifecyclePayload<D> = {
@@ -105,5 +93,3 @@ type: LifecycleTypes.auth;
 };
-/**
- * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
- */
+/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */
 type LifecycleError = {
@@ -113,5 +99,3 @@ type: LifecycleTypes.error | LifecycleTypes.auth_error;
 };
-/**
- * Lifecycle error message for a single room.
- */
+/** Lifecycle error message for a single room. */
 type LifecycleRoomError<R extends string> = {
@@ -122,5 +106,3 @@ type: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;
 };
-/**
- * Lifecycle error message for multiple rooms.
- */
+/** Lifecycle error message for multiple rooms. */
 type LifecycleRoomsError<Rs extends readonly string[]> = {
@@ -131,5 +113,3 @@ type: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;
 };
-/**
- * Union of all possible lifecycle messages that ByteSocket may send or receive.
- */
+/** Union of all possible lifecycle messages that ByteSocket may send or receive. */
 type LifecycleMessage<R extends string, D> = LifecycleType | LifecycleRoomType<R> | LifecycleRoomsType<R[]> | LifecyclePayload<D> | LifecycleError | LifecycleRoomError<R> | LifecycleRoomsError<R[]>;
@@ -170,5 +150,3 @@ /**
 };
-/**
- * Union of all possible user messages that can be emitted or listened to.
- */
+/** Union of all possible user messages that can be emitted or listened to. */
 type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> = GeneralEvent<E, D> | RoomEvent<R, E, D> | RoomsEvent<R[], E, D>;
@@ -180,5 +158,3 @@ /**
 type AnyCallback = (...args: any[]) => Promise<void> | void;
-/**
- * Authentication state of a socket.
- */
+/** Authentication state of a socket. */
 declare enum AuthState {
@@ -199,30 +175,53 @@ /** Initial state before any connection attempt. */
  *
- * @typeParam T - A map of event names to their payload types.
+ * This type supports two usage patterns:
  *
- * @example
- * interface MyEvents extends SocketEvents<{
+ * 1. **Symmetric events (direct generic):** Provide a single event map where
+ *    emit and listen share the same event names and payloads.
+ *
+ * 2. **Asymmetric events (interface extension):** Extend this type and override
+ *    individual properties to define different maps for emit, listen, rooms, etc.
+ *
+ * @typeParam T - A map of event names to their payload types. Defaults to
+ *                `Record<string, unknown>`.
+ *
+ * @example Symmetric usage (most common)
+ * ```ts
+ * type MyEvents = SocketEvents<{
+ *   "chat:message": { text: string };
+ *   "user:joined": { userId: string };
+ * }>;
+ *
+ * const socket = new ByteSocket<MyEvents>('ws://...');
+ *
+ * socket.emit('chat:message', { text: 'Hello' });          // ✅ typed
+ * socket.on('user:joined', (data) => console.log(data.userId)); // ✅ typed
+ * socket.rooms.emit('lobby', 'chat:message', { text: 'Hi' }); // ✅ typed
+ * ```
+ *
+ * @example Asymmetric usage (full control)
+ * ```ts
+ * interface MyEvents extends SocketEvents {
  *   emit: {
- *     message: { text: string };
- *     'user:typing': { userId: string };
+ *     "message:send": { text: string };
+ *     "room:create": { name: string };
  *   };
  *   listen: {
- *     message: { text: string; sender: string };
- *     connected: { userId: string };
+ *     "message:receive": { text: string; sender: string };
+ *     "user:joined": { userId: string; name: string };
  *   };
  *   emitRoom: {
- *     chat: { message: string };
- *     private: { whisper: string };
+ *     chat: { "message": { text: string } };
+ *     dm:   { "message": { text: string; recipient: string } };
  *   };
  *   listenRoom: {
- *     chat: { message: string; sender: string };
+ *     chat: { "message": { text: string; sender: string } };
  *   };
- * }> {}
+ * }
  *
- * const io = new ByteSocket<MyEvents>('ws://...');     // for client
- * const io = new ByteSocket<MyEvents>(app);            // for server
+ * const socket = new ByteSocket<MyEvents>('ws://...');
  *
- * io.emit('message', { text: 'hello' });               // typed
- * io.emit('chat', { message: 'hi' });                  // typed room emit
- * io.on('message', (data) => { data.sender });         // typed
- * io.rooms.on('chat', 'message', (data) => {});        // typed room listen
+ * socket.emit('room:create', { name: 'general' });				// ✅ global emit
+ * socket.on('message:receive', (data) => data.sender);			// ✅ global listen
+ * socket.rooms.emit('chat', 'message', { text: 'Hello' });		// ✅ room emit
+ * ```
  */
@@ -249,12 +248,10 @@ type SocketEvents<T extends {
         rooms: string[];
-        events: T;
+        event: T;
     };
 };
-/**
- * Extracts the event map for a specific set of rooms from `emitRooms`.
- */
+/** Extracts the event map for a specific set of rooms from `emitRooms`. */
 type EventsForRooms<T extends NonNullable<SocketEvents["emitRooms"]>, R> = Extract<T, {
     rooms: R;
-}>["events"];
+}>["event"];
 
 export { type AnyCallback, AuthState, type ErrorContext, type EventsForRooms, type GeneralEvent, type LifecycleError, type LifecycleMessage, type LifecyclePayload, type LifecycleRoomError, type LifecycleRoomType, type LifecycleRoomsError, type LifecycleRoomsType, type LifecycleType, LifecycleTypes, type MsgpackrOptions, type RoomEvent, type RoomsEvent, type SocketEvents, type StringKeys, type StringNumberKeys, type UserMessage };

dist/index.d.ts

@@ -21,5 +21,3 @@ import { Options } from 'msgpackr';
 type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;
-/**
- * Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false.
- */
+/** Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false. */
 type MsgpackrOptions = Omit<Options, "useRecords">;
@@ -57,5 +55,3 @@ /**
 }
-/**
- * Context object passed to error handlers, providing details about where an error occurred.
- */
+/** Context object passed to error handlers, providing details about where an error occurred. */
 type ErrorContext = {
@@ -75,11 +71,7 @@ /** The phase or component where the error originated (e.g., "decode", "auth", "middleware") */
 };
-/**
- * Lifecycle message shape for events without additional data.
- */
+/** Lifecycle message shape for events without additional data. */
 type LifecycleType = {
     type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;
 };
-/**
- * Lifecycle message shape for single-room operations (join/leave request/success).
- */
+/** Lifecycle message shape for single-room operations (join/leave request/success). */
 type LifecycleRoomType<R extends string> = {
@@ -89,5 +81,3 @@ type: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;
 };
-/**
- * Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success).
- */
+/** Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success). */
 type LifecycleRoomsType<Rs extends readonly string[]> = {
@@ -97,5 +87,3 @@ type: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;
 };
-/**
- * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
- */
+/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */
 type LifecyclePayload<D> = {
@@ -105,5 +93,3 @@ type: LifecycleTypes.auth;
 };
-/**
- * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
- */
+/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */
 type LifecycleError = {
@@ -113,5 +99,3 @@ type: LifecycleTypes.error | LifecycleTypes.auth_error;
 };
-/**
- * Lifecycle error message for a single room.
- */
+/** Lifecycle error message for a single room. */
 type LifecycleRoomError<R extends string> = {
@@ -122,5 +106,3 @@ type: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;
 };
-/**
- * Lifecycle error message for multiple rooms.
- */
+/** Lifecycle error message for multiple rooms. */
 type LifecycleRoomsError<Rs extends readonly string[]> = {
@@ -131,5 +113,3 @@ type: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;
 };
-/**
- * Union of all possible lifecycle messages that ByteSocket may send or receive.
- */
+/** Union of all possible lifecycle messages that ByteSocket may send or receive. */
 type LifecycleMessage<R extends string, D> = LifecycleType | LifecycleRoomType<R> | LifecycleRoomsType<R[]> | LifecyclePayload<D> | LifecycleError | LifecycleRoomError<R> | LifecycleRoomsError<R[]>;
@@ -170,5 +150,3 @@ /**
 };
-/**
- * Union of all possible user messages that can be emitted or listened to.
- */
+/** Union of all possible user messages that can be emitted or listened to. */
 type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> = GeneralEvent<E, D> | RoomEvent<R, E, D> | RoomsEvent<R[], E, D>;
@@ -180,5 +158,3 @@ /**
 type AnyCallback = (...args: any[]) => Promise<void> | void;
-/**
- * Authentication state of a socket.
- */
+/** Authentication state of a socket. */
 declare enum AuthState {
@@ -199,30 +175,53 @@ /** Initial state before any connection attempt. */
  *
- * @typeParam T - A map of event names to their payload types.
+ * This type supports two usage patterns:
  *
- * @example
- * interface MyEvents extends SocketEvents<{
+ * 1. **Symmetric events (direct generic):** Provide a single event map where
+ *    emit and listen share the same event names and payloads.
+ *
+ * 2. **Asymmetric events (interface extension):** Extend this type and override
+ *    individual properties to define different maps for emit, listen, rooms, etc.
+ *
+ * @typeParam T - A map of event names to their payload types. Defaults to
+ *                `Record<string, unknown>`.
+ *
+ * @example Symmetric usage (most common)
+ * ```ts
+ * type MyEvents = SocketEvents<{
+ *   "chat:message": { text: string };
+ *   "user:joined": { userId: string };
+ * }>;
+ *
+ * const socket = new ByteSocket<MyEvents>('ws://...');
+ *
+ * socket.emit('chat:message', { text: 'Hello' });          // ✅ typed
+ * socket.on('user:joined', (data) => console.log(data.userId)); // ✅ typed
+ * socket.rooms.emit('lobby', 'chat:message', { text: 'Hi' }); // ✅ typed
+ * ```
+ *
+ * @example Asymmetric usage (full control)
+ * ```ts
+ * interface MyEvents extends SocketEvents {
  *   emit: {
- *     message: { text: string };
- *     'user:typing': { userId: string };
+ *     "message:send": { text: string };
+ *     "room:create": { name: string };
  *   };
  *   listen: {
- *     message: { text: string; sender: string };
- *     connected: { userId: string };
+ *     "message:receive": { text: string; sender: string };
+ *     "user:joined": { userId: string; name: string };
  *   };
  *   emitRoom: {
- *     chat: { message: string };
- *     private: { whisper: string };
+ *     chat: { "message": { text: string } };
+ *     dm:   { "message": { text: string; recipient: string } };
  *   };
  *   listenRoom: {
- *     chat: { message: string; sender: string };
+ *     chat: { "message": { text: string; sender: string } };
  *   };
- * }> {}
+ * }
  *
- * const io = new ByteSocket<MyEvents>('ws://...');     // for client
- * const io = new ByteSocket<MyEvents>(app);            // for server
+ * const socket = new ByteSocket<MyEvents>('ws://...');
  *
- * io.emit('message', { text: 'hello' });               // typed
- * io.emit('chat', { message: 'hi' });                  // typed room emit
- * io.on('message', (data) => { data.sender });         // typed
- * io.rooms.on('chat', 'message', (data) => {});        // typed room listen
+ * socket.emit('room:create', { name: 'general' });				// ✅ global emit
+ * socket.on('message:receive', (data) => data.sender);			// ✅ global listen
+ * socket.rooms.emit('chat', 'message', { text: 'Hello' });		// ✅ room emit
+ * ```
  */
@@ -249,12 +248,10 @@ type SocketEvents<T extends {
         rooms: string[];
-        events: T;
+        event: T;
     };
 };
-/**
- * Extracts the event map for a specific set of rooms from `emitRooms`.
- */
+/** Extracts the event map for a specific set of rooms from `emitRooms`. */
 type EventsForRooms<T extends NonNullable<SocketEvents["emitRooms"]>, R> = Extract<T, {
     rooms: R;
-}>["events"];
+}>["event"];
 
 export { type AnyCallback, AuthState, type ErrorContext, type EventsForRooms, type GeneralEvent, type LifecycleError, type LifecycleMessage, type LifecyclePayload, type LifecycleRoomError, type LifecycleRoomType, type LifecycleRoomsError, type LifecycleRoomsType, type LifecycleType, LifecycleTypes, type MsgpackrOptions, type RoomEvent, type RoomsEvent, type SocketEvents, type StringKeys, type StringNumberKeys, type UserMessage };

dist/index.js.map

@@ -1,1 +0,1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["LifecycleTypes","AuthState"],"mappings":";AAgCO,IAAK,cAAA,qBAAAA,eAAAA,KAAL;AACN,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,kBAAe,CAAA,CAAA,GAAf,cAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,CAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,qBAAkB,EAAA,CAAA,GAAlB,iBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,iBAAc,EAAA,CAAA,GAAd,aAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,yBAAsB,EAAA,CAAA,GAAtB,qBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AAxBW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAwKL,IAAK,SAAA,qBAAAC,UAAAA,KAAL;AAEN,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AAVW,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA","file":"index.js","sourcesContent":["import type { Options } from \"msgpackr\";\n\n/**\n * Extracts only the string keys from a type `T`.\n * Useful for strongly typing room names from a user-defined event map.\n *\n * @example\n * type MyEvents = { emitRoom: { chat: { message: string } } };\n * type RoomNames = StringKeys<MyEvents['emitRoom']>; // \"chat\"\n */\nexport type StringKeys<T> = Extract<keyof NonNullable<T>, string>;\n\n/**\n * Extracts keys that are either string or number from a type `T`.\n * Typically used for event names (which may be strings or numeric codes).\n *\n * @example\n * type MyEvents = { listen: { \"new_message\": string; 42: number } };\n * type EventNames = StringNumberKeys<MyEvents['listen']>; // \"new_message\" | 42\n */\nexport type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;\n\n/**\n * Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false.\n */\nexport type MsgpackrOptions = Omit<Options, \"useRecords\">;\n\n/**\n * Enumeration of all lifecycle message types used internally by ByteSocket.\n * These correspond to system-level events like connection open, authentication,\n * room join/leave, and errors.\n */\nexport enum LifecycleTypes {\n\topen = 1,\n\tclose = 2,\n\terror = 3,\n\tauth = 4,\n\tauth_success = 5,\n\tauth_error = 6,\n\tping = 7,\n\tpong = 8,\n\tjoin_room = 9,\n\tjoin_room_success = 10,\n\tjoin_room_error = 11,\n\tleave_room = 12,\n\tleave_room_success = 13,\n\tleave_room_error = 14,\n\tjoin_rooms = 15,\n\tjoin_rooms_success = 16,\n\tjoin_rooms_error = 17,\n\tleave_rooms = 18,\n\tleave_rooms_success = 19,\n\tleave_rooms_error = 20,\n\tqueue_full = 21,\n\treconnect_failed = 22,\n\tupgrade = 23,\n\tmessage = 24,\n}\n\n/**\n * Context object passed to error handlers, providing details about where an error occurred.\n */\nexport type ErrorContext = {\n\t/** The phase or component where the error originated (e.g., \"decode\", \"auth\", \"middleware\") */\n\tphase: string;\n\t/** The error object itself, if any */\n\terror?: unknown;\n\t/** The event name involved, if applicable */\n\tevent?: string;\n\t/** Raw message content (stringified) for debugging */\n\traw?: string;\n\t/** WebSocket close code, if applicable */\n\tcode?: number;\n\t/** Number of bytes received, if applicable */\n\tbytes?: number;\n};\n\n/**\n * Lifecycle message shape for events without additional data.\n */\nexport type LifecycleType = {\n\ttype: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;\n};\n\n/**\n * Lifecycle message shape for single-room operations (join/leave request/success).\n */\nexport type LifecycleRoomType<R extends string> = {\n\ttype: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;\n\troom: R;\n};\n\n/**\n * Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success).\n */\nexport type LifecycleRoomsType<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;\n\trooms: Rs;\n};\n\n/**\n * Lifecycle message shape for events that carry generic data (error, auth, auth_error).\n */\nexport type LifecyclePayload<D> = {\n\ttype: LifecycleTypes.auth;\n\tdata: D;\n};\n\n/**\n * Lifecycle message shape for events that carry generic data (error, auth, auth_error).\n */\nexport type LifecycleError = {\n\ttype: LifecycleTypes.error | LifecycleTypes.auth_error;\n\tdata: ErrorContext;\n};\n\n/**\n * Lifecycle error message for a single room.\n */\nexport type LifecycleRoomError<R extends string> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: ErrorContext;\n};\n\n/**\n * Lifecycle error message for multiple rooms.\n */\nexport type LifecycleRoomsError<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: ErrorContext;\n};\n\n/**\n * Union of all possible lifecycle messages that ByteSocket may send or receive.\n */\nexport type LifecycleMessage<R extends string, D> =\n\t| LifecycleType\n\t| LifecycleRoomType<R>\n\t| LifecycleRoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| LifecycleError\n\t| LifecycleRoomError<R>\n\t| LifecycleRoomsError<R[]>;\n\n/**\n * User‑defined event sent to a specific room.\n *\n * @example\n * // Emitting to room \"chat\" with event \"message\"\n * socket.rooms.emit(\"chat\", \"message\", { text: \"Hello!\" });\n */\nexport type RoomEvent<R extends string, E extends string | number, D> = {\n\troom: R;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent to multiple rooms simultaneously.\n *\n * @example\n * // Emitting to rooms [\"lobby\", \"announcements\"]\n * socket.rooms.bulk.emit([\"lobby\", \"announcements\"], \"alert\", { msg: \"Server restart in 5m\" });\n */\nexport type RoomsEvent<Rs extends readonly string[], E extends string | number, D> = {\n\trooms: Rs;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent globally (no room context).\n *\n * @example\n * socket.emit(\"userJoined\", { userId: \"abc123\" });\n */\nexport type GeneralEvent<E extends string | number, D> = {\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * Union of all possible user messages that can be emitted or listened to.\n */\nexport type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> =\n\t| GeneralEvent<E, D>\n\t| RoomEvent<R, E, D>\n\t| RoomsEvent<R[], E, D>;\n\n/**\n * Generic callback type used internally.\n * @internal\n */\nexport type AnyCallback = (...args: any[]) => Promise<void> | void;\n\n/**\n * Authentication state of a socket.\n */\nexport enum AuthState {\n\t/** Initial state before any connection attempt. */\n\tidle = 1,\n\t/** No authentication required / not configured. */\n\tnone = 2,\n\t/** Authentication request sent, awaiting server response. */\n\tpending = 3,\n\t/** Authentication successful. */\n\tsuccess = 4,\n\t/** Authentication failed permanently. */\n\tfailed = 5,\n}\n\n/**\n * Defines the shape of event maps for a type‑safe ByteSocket instance.\n *\n * @typeParam T - A map of event names to their payload types.\n *\n * @example\n * interface MyEvents extends SocketEvents<{\n *   emit: {\n *     message: { text: string };\n *     'user:typing': { userId: string };\n *   };\n *   listen: {\n *     message: { text: string; sender: string };\n *     connected: { userId: string };\n *   };\n *   emitRoom: {\n *     chat: { message: string };\n *     private: { whisper: string };\n *   };\n *   listenRoom: {\n *     chat: { message: string; sender: string };\n *   };\n * }> {}\n *\n * const io = new ByteSocket<MyEvents>('ws://...');     // for client\n * const io = new ByteSocket<MyEvents>(app);            // for server\n *\n * io.emit('message', { text: 'hello' });               // typed\n * io.emit('chat', { message: 'hi' });                  // typed room emit\n * io.on('message', (data) => { data.sender });         // typed\n * io.rooms.on('chat', 'message', (data) => {});        // typed room listen\n */\nexport type SocketEvents<T extends { [event: string | number]: unknown } = { [event: string | number]: unknown }> = {\n\t/** Events that can be emitted globally. */\n\temit?: T;\n\t/** Events that can be listened to globally. */\n\tlisten?: T;\n\t/** Events that can be emitted to a specific room, keyed by room name. */\n\temitRoom?: { [room: string]: T };\n\t/** Events that can be listened to on a specific room, keyed by room name. */\n\tlistenRoom?: { [room: string]: T };\n\t/** Events that can be emitted to multiple rooms at once. */\n\temitRooms?: { rooms: string[]; events: T };\n};\n\n/**\n * Extracts the event map for a specific set of rooms from `emitRooms`.\n */\nexport type EventsForRooms<T extends NonNullable<SocketEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["LifecycleTypes","AuthState"],"mappings":";AA8BO,IAAK,cAAA,qBAAAA,eAAAA,KAAL;AACN,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,kBAAe,CAAA,CAAA,GAAf,cAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,CAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,qBAAkB,EAAA,CAAA,GAAlB,iBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,wBAAqB,EAAA,CAAA,GAArB,oBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,iBAAc,EAAA,CAAA,GAAd,aAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,yBAAsB,EAAA,CAAA,GAAtB,qBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,uBAAoB,EAAA,CAAA,GAApB,mBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,gBAAa,EAAA,CAAA,GAAb,YAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,sBAAmB,EAAA,CAAA,GAAnB,kBAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AACA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,aAAU,EAAA,CAAA,GAAV,SAAA;AAxBW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAkJL,IAAK,SAAA,qBAAAC,UAAAA,KAAL;AAEN,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAEA,EAAAA,UAAAA,CAAAA,UAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AAVW,EAAA,OAAAA,UAAAA;AAAA,CAAA,EAAA,SAAA,IAAA,EAAA","file":"index.js","sourcesContent":["import type { Options } from \"msgpackr\";\n\n/**\n * Extracts only the string keys from a type `T`.\n * Useful for strongly typing room names from a user-defined event map.\n *\n * @example\n * type MyEvents = { emitRoom: { chat: { message: string } } };\n * type RoomNames = StringKeys<MyEvents['emitRoom']>; // \"chat\"\n */\nexport type StringKeys<T> = Extract<keyof NonNullable<T>, string>;\n\n/**\n * Extracts keys that are either string or number from a type `T`.\n * Typically used for event names (which may be strings or numeric codes).\n *\n * @example\n * type MyEvents = { listen: { \"new_message\": string; 42: number } };\n * type EventNames = StringNumberKeys<MyEvents['listen']>; // \"new_message\" | 42\n */\nexport type StringNumberKeys<T> = Extract<keyof NonNullable<T>, string | number>;\n\n/** Options for the msgpackr serialization library, excluding the internal `useRecords` field must be false. */\nexport type MsgpackrOptions = Omit<Options, \"useRecords\">;\n\n/**\n * Enumeration of all lifecycle message types used internally by ByteSocket.\n * These correspond to system-level events like connection open, authentication,\n * room join/leave, and errors.\n */\nexport enum LifecycleTypes {\n\topen = 1,\n\tclose = 2,\n\terror = 3,\n\tauth = 4,\n\tauth_success = 5,\n\tauth_error = 6,\n\tping = 7,\n\tpong = 8,\n\tjoin_room = 9,\n\tjoin_room_success = 10,\n\tjoin_room_error = 11,\n\tleave_room = 12,\n\tleave_room_success = 13,\n\tleave_room_error = 14,\n\tjoin_rooms = 15,\n\tjoin_rooms_success = 16,\n\tjoin_rooms_error = 17,\n\tleave_rooms = 18,\n\tleave_rooms_success = 19,\n\tleave_rooms_error = 20,\n\tqueue_full = 21,\n\treconnect_failed = 22,\n\tupgrade = 23,\n\tmessage = 24,\n}\n\n/** Context object passed to error handlers, providing details about where an error occurred. */\nexport type ErrorContext = {\n\t/** The phase or component where the error originated (e.g., \"decode\", \"auth\", \"middleware\") */\n\tphase: string;\n\t/** The error object itself, if any */\n\terror?: unknown;\n\t/** The event name involved, if applicable */\n\tevent?: string;\n\t/** Raw message content (stringified) for debugging */\n\traw?: string;\n\t/** WebSocket close code, if applicable */\n\tcode?: number;\n\t/** Number of bytes received, if applicable */\n\tbytes?: number;\n};\n\n/** Lifecycle message shape for events without additional data. */\nexport type LifecycleType = {\n\ttype: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;\n};\n\n/** Lifecycle message shape for single-room operations (join/leave request/success). */\nexport type LifecycleRoomType<R extends string> = {\n\ttype: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;\n\troom: R;\n};\n\n/** Lifecycle message shape for bulk room operations (join/leave multiple rooms request/success). */\nexport type LifecycleRoomsType<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;\n\trooms: Rs;\n};\n\n/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */\nexport type LifecyclePayload<D> = {\n\ttype: LifecycleTypes.auth;\n\tdata: D;\n};\n\n/** Lifecycle message shape for events that carry generic data (error, auth, auth_error). */\nexport type LifecycleError = {\n\ttype: LifecycleTypes.error | LifecycleTypes.auth_error;\n\tdata: ErrorContext;\n};\n\n/** Lifecycle error message for a single room. */\nexport type LifecycleRoomError<R extends string> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: ErrorContext;\n};\n\n/** Lifecycle error message for multiple rooms. */\nexport type LifecycleRoomsError<Rs extends readonly string[]> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: ErrorContext;\n};\n\n/** Union of all possible lifecycle messages that ByteSocket may send or receive. */\nexport type LifecycleMessage<R extends string, D> =\n\t| LifecycleType\n\t| LifecycleRoomType<R>\n\t| LifecycleRoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| LifecycleError\n\t| LifecycleRoomError<R>\n\t| LifecycleRoomsError<R[]>;\n\n/**\n * User‑defined event sent to a specific room.\n *\n * @example\n * // Emitting to room \"chat\" with event \"message\"\n * socket.rooms.emit(\"chat\", \"message\", { text: \"Hello!\" });\n */\nexport type RoomEvent<R extends string, E extends string | number, D> = {\n\troom: R;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent to multiple rooms simultaneously.\n *\n * @example\n * // Emitting to rooms [\"lobby\", \"announcements\"]\n * socket.rooms.bulk.emit([\"lobby\", \"announcements\"], \"alert\", { msg: \"Server restart in 5m\" });\n */\nexport type RoomsEvent<Rs extends readonly string[], E extends string | number, D> = {\n\trooms: Rs;\n\tevent: E;\n\tdata: D;\n};\n\n/**\n * User‑defined event sent globally (no room context).\n *\n * @example\n * socket.emit(\"userJoined\", { userId: \"abc123\" });\n */\nexport type GeneralEvent<E extends string | number, D> = {\n\tevent: E;\n\tdata: D;\n};\n\n/** Union of all possible user messages that can be emitted or listened to. */\nexport type UserMessage<R extends string = string, E extends string | number = string | number, D = unknown> =\n\t| GeneralEvent<E, D>\n\t| RoomEvent<R, E, D>\n\t| RoomsEvent<R[], E, D>;\n\n/**\n * Generic callback type used internally.\n * @internal\n */\nexport type AnyCallback = (...args: any[]) => Promise<void> | void;\n\n/** Authentication state of a socket. */\nexport enum AuthState {\n\t/** Initial state before any connection attempt. */\n\tidle = 1,\n\t/** No authentication required / not configured. */\n\tnone = 2,\n\t/** Authentication request sent, awaiting server response. */\n\tpending = 3,\n\t/** Authentication successful. */\n\tsuccess = 4,\n\t/** Authentication failed permanently. */\n\tfailed = 5,\n}\n\n/**\n * Defines the shape of event maps for a type‑safe ByteSocket instance.\n *\n * This type supports two usage patterns:\n *\n * 1. **Symmetric events (direct generic):** Provide a single event map where\n *    emit and listen share the same event names and payloads.\n *\n * 2. **Asymmetric events (interface extension):** Extend this type and override\n *    individual properties to define different maps for emit, listen, rooms, etc.\n *\n * @typeParam T - A map of event names to their payload types. Defaults to\n *                `Record<string, unknown>`.\n *\n * @example Symmetric usage (most common)\n * ```ts\n * type MyEvents = SocketEvents<{\n *   \"chat:message\": { text: string };\n *   \"user:joined\": { userId: string };\n * }>;\n *\n * const socket = new ByteSocket<MyEvents>('ws://...');\n *\n * socket.emit('chat:message', { text: 'Hello' });          // ✅ typed\n * socket.on('user:joined', (data) => console.log(data.userId)); // ✅ typed\n * socket.rooms.emit('lobby', 'chat:message', { text: 'Hi' }); // ✅ typed\n * ```\n *\n * @example Asymmetric usage (full control)\n * ```ts\n * interface MyEvents extends SocketEvents {\n *   emit: {\n *     \"message:send\": { text: string };\n *     \"room:create\": { name: string };\n *   };\n *   listen: {\n *     \"message:receive\": { text: string; sender: string };\n *     \"user:joined\": { userId: string; name: string };\n *   };\n *   emitRoom: {\n *     chat: { \"message\": { text: string } };\n *     dm:   { \"message\": { text: string; recipient: string } };\n *   };\n *   listenRoom: {\n *     chat: { \"message\": { text: string; sender: string } };\n *   };\n * }\n *\n * const socket = new ByteSocket<MyEvents>('ws://...');\n *\n * socket.emit('room:create', { name: 'general' });\t\t\t\t// ✅ global emit\n * socket.on('message:receive', (data) => data.sender);\t\t\t// ✅ global listen\n * socket.rooms.emit('chat', 'message', { text: 'Hello' });\t\t// ✅ room emit\n * ```\n */\nexport type SocketEvents<T extends { [event: string | number]: unknown } = { [event: string | number]: unknown }> = {\n\t/** Events that can be emitted globally. */\n\temit?: T;\n\t/** Events that can be listened to globally. */\n\tlisten?: T;\n\t/** Events that can be emitted to a specific room, keyed by room name. */\n\temitRoom?: { [room: string]: T };\n\t/** Events that can be listened to on a specific room, keyed by room name. */\n\tlistenRoom?: { [room: string]: T };\n\t/** Events that can be emitted to multiple rooms at once. */\n\temitRooms?: { rooms: string[]; event: T };\n};\n\n/** Extracts the event map for a specific set of rooms from `emitRooms`. */\nexport type EventsForRooms<T extends NonNullable<SocketEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"event\"];\n"]}

package.json

 {
   "name": "@bytesocket/types",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Shared types and enums for ByteSocket",
@@ -5,0 +5,0 @@ "keywords": [

README.md

 # @bytesocket/types
 
-Shared TypeScript definitions for the ByteSocket ecosystem — used internally by both the client (`@bytesocket/client`) and server (`@bytesocket/uws`) packages.
+Shared TypeScript definitions for the ByteSocket ecosystem -- used internally by both the client (`@bytesocket/client`) and server (`@bytesocket/uws`) packages.
 
@@ -5,0 +5,0 @@ You do not need to install this package directly; it is a dependency of the main packages.

No alert changes

Improved metrics

Total package byte prevSize

49113

7.29%

Worsened metrics

Lines of code

321

-0.93%

No dependency changes