@bytesocket/types - npm Package Compare versions

Comparing version 0.2.2 to 0.3.0

dist/index.cjs.map

@@ -1,1 +0,1 @@
-{"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 = 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[] = 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 = unknown> = {\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 = 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[] = 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 = string, D = unknown> =\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 = string, E extends string | number = string | number, D = unknown> = {\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[] = string[], E extends string | number = string | number, D = unknown> = {\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 = string | number, D = unknown> = {\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"]}
+{"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;AAEA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,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;AA1BW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAoJL,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\t/** @deprecated We use now a zero‑length byte array instead of custom message */\n\tping = 7,\n\t/** @deprecated We use now a zero‑length byte array instead of custom message */\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.auth_success;\n};\n\n/** Lifecycle message shape for single-room operations (join/leave request/success). */\nexport type LifecycleRoomType<R extends string = 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[] = 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 = unknown> = {\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 = 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[] = 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 = string, D = unknown> =\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 = string, E extends string | number = string | number, D = unknown> = {\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[] = string[], E extends string | number = string | number, D = unknown> = {\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 = string | number, D = unknown> = {\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.\n * @default 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

@@ -35,3 +35,5 @@ import { Options } from 'msgpackr';
     auth_error = 6,
+    /** @deprecated We use now a zero‑length byte array instead of custom message */
     ping = 7,
+    /** @deprecated We use now a zero‑length byte array instead of custom message */
     pong = 8,
@@ -72,3 +74,3 @@ join_room = 9,
 type LifecycleType = {
-    type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;
+    type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.auth_success;
 };
@@ -174,4 +176,4 @@ /** Lifecycle message shape for single-room operations (join/leave request/success). */
  *
- * @typeParam T - A map of event names to their payload types. Defaults to
- *                `Record<string, unknown>`.
+ * @typeParam T - A map of event names to their payload types.
+ * @default Record<string, unknown>
  *
@@ -178,0 +180,0 @@ * @example Symmetric usage (most common)

dist/index.d.ts

@@ -35,3 +35,5 @@ import { Options } from 'msgpackr';
     auth_error = 6,
+    /** @deprecated We use now a zero‑length byte array instead of custom message */
     ping = 7,
+    /** @deprecated We use now a zero‑length byte array instead of custom message */
     pong = 8,
@@ -72,3 +74,3 @@ join_room = 9,
 type LifecycleType = {
-    type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.ping | LifecycleTypes.pong | LifecycleTypes.auth_success;
+    type: LifecycleTypes.open | LifecycleTypes.close | LifecycleTypes.auth_success;
 };
@@ -174,4 +176,4 @@ /** Lifecycle message shape for single-room operations (join/leave request/success). */
  *
- * @typeParam T - A map of event names to their payload types. Defaults to
- *                `Record<string, unknown>`.
+ * @typeParam T - A map of event names to their payload types.
+ * @default Record<string, unknown>
  *
@@ -178,0 +180,0 @@ * @example Symmetric usage (most common)

dist/index.js.map

@@ -1,1 +0,1 @@
-{"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 = 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[] = 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 = unknown> = {\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 = 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[] = 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 = string, D = unknown> =\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 = string, E extends string | number = string | number, D = unknown> = {\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[] = string[], E extends string | number = string | number, D = unknown> = {\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 = string | number, D = unknown> = {\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"]}
+{"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;AAEA,EAAAA,eAAAA,CAAAA,eAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AAEA,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;AA1BW,EAAA,OAAAA,eAAAA;AAAA,CAAA,EAAA,cAAA,IAAA,EAAA;AAoJL,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\t/** @deprecated We use now a zero‑length byte array instead of custom message */\n\tping = 7,\n\t/** @deprecated We use now a zero‑length byte array instead of custom message */\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.auth_success;\n};\n\n/** Lifecycle message shape for single-room operations (join/leave request/success). */\nexport type LifecycleRoomType<R extends string = 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[] = 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 = unknown> = {\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 = 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[] = 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 = string, D = unknown> =\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 = string, E extends string | number = string | number, D = unknown> = {\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[] = string[], E extends string | number = string | number, D = unknown> = {\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 = string | number, D = unknown> = {\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.\n * @default 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.2.2",
+  "version": "0.3.0",
   "description": "Shared types and enums for ByteSocket",
@@ -5,0 +5,0 @@ "keywords": [

No alert changes

Improved metrics

Total package byte prevSize

50683

0.86%

Lines of code

323

0.62%

No dependency changes