@bytesocket/types - npm Package Compare versions

Comparing version 0.1.4 to 0.1.5

README.md

+# @bytesocket/types
+
+Shared TypeScript definitions for the ByteSocket ecosystem — used internally by both the client (`@bytesocket/client`) and server (`@bytesocket/uws`) packages.
+
+You do not need to install this package directly; it is a dependency of the main packages.
+
+## Exports
+
+### Core Types
+
+- `StringKeys<T>` – Extract only string keys from a type.
+- `StringNumberKeys<T>` – Extract string or number keys.
+- `SymmetricEvents<T>` – The event map shape for end‑to‑end type safety.
+- `EventsForRooms<T, R>` – Extract events for a specific set of rooms.
+
+### Lifecycle & Error Types
+
+- `LifecycleTypes` – Enum of all internal protocol message types (open, close, auth, ping, errors, room operations, etc.).
+- `ErrorContext` – Structured context for error events (`phase`, `error`, `event`, `raw`, `code`, `bytes`).
+- `LifecycleType` – Messages with only a `type` field (e.g., `open`, `ping`).
+- `LifecycleRoomType<R>` – Success messages for single‑room operations.
+- `LifecycleRoomsType<Rs>` – Success messages for bulk room operations.
+- `LifecyclePayload<D>` – Auth request message.
+- `LifecycleError` – Global error messages (`error`, `auth_error`).
+- `LifecycleRoomError<R>` – Error messages for single‑room operations.
+- `LifecycleRoomsError<Rs>` – Error messages for bulk room operations.
+- `LifecycleMessage<R, D>` – Complete union of all lifecycle messages (combines the above).
+
+### User Message Shapes
+
+- `GeneralEvent<E, D>` – Global user event.
+- `RoomEvent<R, E, D>` – User event scoped to a single room.
+- `RoomsEvent<Rs, E, D>` – User event scoped to multiple rooms.
+- `UserMessage<R, E, D>` – Union of all user‑defined messages.
+
+### Other
+
+- `MsgpackrOptions` – Type for msgpackr configuration (excludes internal `structures`).
+- `AuthState` – Enum of authentication states (`idle`, `none`, `pending`, `success`, `failed`).
+- `AnyCallback` – Generic callback type (internal).
+
+## Usage
+
+All types are re‑exported by `@bytesocket/client` and `@bytesocket/uws`. Import from those packages instead of directly from `@bytesocket/types`.
+
+```typescript
+// ✅ Recommended
+import { SymmetricEvents, LifecycleTypes } from "@bytesocket/client";
+// or
+import { SymmetricEvents, LifecycleTypes } from "@bytesocket/uws";
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Ahmed Ouda
+
+- GitHub: [@a7med3ouda](https://github.com/a7med3ouda)

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;AA6IL,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 `structures` field.\n */\nexport type MsgpackrOptions = Omit<Options, \"structures\">;\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 * 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 RoomType<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 RoomsType<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.error | LifecycleTypes.auth | LifecycleTypes.auth_error;\n\tdata: D;\n};\n\n/**\n * Lifecycle error message for a single room.\n */\nexport type RoomPayload<R extends string, D> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: D;\n};\n\n/**\n * Lifecycle error message for multiple rooms.\n */\nexport type RoomsPayload<Rs extends readonly string[], D> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: D;\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| RoomType<R>\n\t| RoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| RoomPayload<R, D>\n\t| RoomsPayload<R[], D>;\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 SymmetricEvents<{\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 SymmetricEvents<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<SymmetricEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}
+{"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 `structures` field.\n */\nexport type MsgpackrOptions = Omit<Options, \"structures\">;\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 SymmetricEvents<{\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 SymmetricEvents<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<SymmetricEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}

dist/index.d.cts

@@ -57,2 +57,19 @@ import { Options } from 'msgpackr';
 /**
+ * Context object passed to error handlers, providing details about where an error occurred.
+ */
+type ErrorContext = {
+    /** The phase or component where the error originated (e.g., "decode", "auth", "middleware") */
+    phase: string;
+    /** The error object itself, if any */
+    error?: unknown;
+    /** The event name involved, if applicable */
+    event?: string;
+    /** Raw message content (stringified) for debugging */
+    raw?: string;
+    /** WebSocket close code, if applicable */
+    code?: number;
+    /** Number of bytes received, if applicable */
+    bytes?: number;
+};
+/**
  * Lifecycle message shape for events without additional data.
@@ -66,3 +83,3 @@ */
  */
-type RoomType<R extends string> = {
+type LifecycleRoomType<R extends string> = {
     type: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;
@@ -74,3 +91,3 @@ room: R;
  */
-type RoomsType<Rs extends readonly string[]> = {
+type LifecycleRoomsType<Rs extends readonly string[]> = {
     type: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;
@@ -83,12 +100,19 @@ rooms: Rs;
 type LifecyclePayload<D> = {
-    type: LifecycleTypes.error | LifecycleTypes.auth | LifecycleTypes.auth_error;
+    type: LifecycleTypes.auth;
     data: D;
 };
 /**
+ * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
+ */
+type LifecycleError = {
+    type: LifecycleTypes.error | LifecycleTypes.auth_error;
+    data: ErrorContext;
+};
+/**
  * Lifecycle error message for a single room.
  */
-type RoomPayload<R extends string, D> = {
+type LifecycleRoomError<R extends string> = {
     type: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;
     room: R;
-    data: D;
+    data: ErrorContext;
 };
@@ -98,6 +122,6 @@ /**
  */
-type RoomsPayload<Rs extends readonly string[], D> = {
+type LifecycleRoomsError<Rs extends readonly string[]> = {
     type: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;
     rooms: Rs;
-    data: D;
+    data: ErrorContext;
 };
@@ -107,3 +131,3 @@ /**
  */
-type LifecycleMessage<R extends string, D> = LifecycleType | RoomType<R> | RoomsType<R[]> | LifecyclePayload<D> | RoomPayload<R, D> | RoomsPayload<R[], D>;
+type LifecycleMessage<R extends string, D> = LifecycleType | LifecycleRoomType<R> | LifecycleRoomsType<R[]> | LifecyclePayload<D> | LifecycleError | LifecycleRoomError<R> | LifecycleRoomsError<R[]>;
 /**
@@ -229,2 +253,2 @@ * User‑defined event sent to a specific room.
 
-export { type AnyCallback, AuthState, type EventsForRooms, type GeneralEvent, type LifecycleMessage, type LifecyclePayload, type LifecycleType, LifecycleTypes, type MsgpackrOptions, type RoomEvent, type RoomPayload, type RoomType, type RoomsEvent, type RoomsPayload, type RoomsType, type StringKeys, type StringNumberKeys, type SymmetricEvents, type UserMessage };
+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 StringKeys, type StringNumberKeys, type SymmetricEvents, type UserMessage };

dist/index.d.ts

@@ -57,2 +57,19 @@ import { Options } from 'msgpackr';
 /**
+ * Context object passed to error handlers, providing details about where an error occurred.
+ */
+type ErrorContext = {
+    /** The phase or component where the error originated (e.g., "decode", "auth", "middleware") */
+    phase: string;
+    /** The error object itself, if any */
+    error?: unknown;
+    /** The event name involved, if applicable */
+    event?: string;
+    /** Raw message content (stringified) for debugging */
+    raw?: string;
+    /** WebSocket close code, if applicable */
+    code?: number;
+    /** Number of bytes received, if applicable */
+    bytes?: number;
+};
+/**
  * Lifecycle message shape for events without additional data.
@@ -66,3 +83,3 @@ */
  */
-type RoomType<R extends string> = {
+type LifecycleRoomType<R extends string> = {
     type: LifecycleTypes.join_room | LifecycleTypes.join_room_success | LifecycleTypes.leave_room | LifecycleTypes.leave_room_success;
@@ -74,3 +91,3 @@ room: R;
  */
-type RoomsType<Rs extends readonly string[]> = {
+type LifecycleRoomsType<Rs extends readonly string[]> = {
     type: LifecycleTypes.join_rooms | LifecycleTypes.join_rooms_success | LifecycleTypes.leave_rooms | LifecycleTypes.leave_rooms_success;
@@ -83,12 +100,19 @@ rooms: Rs;
 type LifecyclePayload<D> = {
-    type: LifecycleTypes.error | LifecycleTypes.auth | LifecycleTypes.auth_error;
+    type: LifecycleTypes.auth;
     data: D;
 };
 /**
+ * Lifecycle message shape for events that carry generic data (error, auth, auth_error).
+ */
+type LifecycleError = {
+    type: LifecycleTypes.error | LifecycleTypes.auth_error;
+    data: ErrorContext;
+};
+/**
  * Lifecycle error message for a single room.
  */
-type RoomPayload<R extends string, D> = {
+type LifecycleRoomError<R extends string> = {
     type: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;
     room: R;
-    data: D;
+    data: ErrorContext;
 };
@@ -98,6 +122,6 @@ /**
  */
-type RoomsPayload<Rs extends readonly string[], D> = {
+type LifecycleRoomsError<Rs extends readonly string[]> = {
     type: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;
     rooms: Rs;
-    data: D;
+    data: ErrorContext;
 };
@@ -107,3 +131,3 @@ /**
  */
-type LifecycleMessage<R extends string, D> = LifecycleType | RoomType<R> | RoomsType<R[]> | LifecyclePayload<D> | RoomPayload<R, D> | RoomsPayload<R[], D>;
+type LifecycleMessage<R extends string, D> = LifecycleType | LifecycleRoomType<R> | LifecycleRoomsType<R[]> | LifecyclePayload<D> | LifecycleError | LifecycleRoomError<R> | LifecycleRoomsError<R[]>;
 /**
@@ -229,2 +253,2 @@ * User‑defined event sent to a specific room.
 
-export { type AnyCallback, AuthState, type EventsForRooms, type GeneralEvent, type LifecycleMessage, type LifecyclePayload, type LifecycleType, LifecycleTypes, type MsgpackrOptions, type RoomEvent, type RoomPayload, type RoomType, type RoomsEvent, type RoomsPayload, type RoomsType, type StringKeys, type StringNumberKeys, type SymmetricEvents, type UserMessage };
+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 StringKeys, type StringNumberKeys, type SymmetricEvents, 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;AA6IL,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 `structures` field.\n */\nexport type MsgpackrOptions = Omit<Options, \"structures\">;\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 * 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 RoomType<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 RoomsType<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.error | LifecycleTypes.auth | LifecycleTypes.auth_error;\n\tdata: D;\n};\n\n/**\n * Lifecycle error message for a single room.\n */\nexport type RoomPayload<R extends string, D> = {\n\ttype: LifecycleTypes.join_room_error | LifecycleTypes.leave_room_error;\n\troom: R;\n\tdata: D;\n};\n\n/**\n * Lifecycle error message for multiple rooms.\n */\nexport type RoomsPayload<Rs extends readonly string[], D> = {\n\ttype: LifecycleTypes.join_rooms_error | LifecycleTypes.leave_rooms_error;\n\trooms: Rs;\n\tdata: D;\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| RoomType<R>\n\t| RoomsType<R[]>\n\t| LifecyclePayload<D>\n\t| RoomPayload<R, D>\n\t| RoomsPayload<R[], D>;\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 SymmetricEvents<{\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 SymmetricEvents<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<SymmetricEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}
+{"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 `structures` field.\n */\nexport type MsgpackrOptions = Omit<Options, \"structures\">;\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 SymmetricEvents<{\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 SymmetricEvents<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<SymmetricEvents[\"emitRooms\"]>, R> = Extract<T, { rooms: R }>[\"events\"];\n"]}

package.json

 {
   "name": "@bytesocket/types",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "MIT",
@@ -5,0 +5,0 @@ "description": "Shared types and enums for ByteSocket",

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

45661

15%

Number of package files

9

12.5%

Lines of code

324

8%

Number of medium quality alerts

0

-100%

Number of lines in readme file

60

Infinity%

No dependency changes