@bytesocket/core

Shared TypeScript definitions and low-level runtime primitives for the ByteSocket ecosystem -- used internally by both the client and server 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.
• SocketEvents<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 useRecords & structuredClone, which must always be false).
• Serialization - "json" | "binary".
• AuthState - Enum of authentication states (idle, none, pending, success, failed).
• AnyCallback - Generic callback type (internal).
• FLOAT32_OPTIONS - re-exported from msgpackr.

CallbackRegistry<Key>

A generic, typed pub/sub registry. This is the single primitive that backs every on/off/once API in both the client and server packages -- global event listeners, lifecycle listeners, and (wrapped in a ScopedRegistry) room-scoped listeners.

import { CallbackRegistry } from "@bytesocket/core";

const registry = new CallbackRegistry<string>(/* debug */ false);

registry.on("greet", (name: string) => console.log(`Hello, ${name}`));
registry.trigger("greet", "world"); // logs "Hello, world"
registry.off("greet");

Constructor: new CallbackRegistry<Key = string | number>(debug: boolean) When debug is true, errors thrown inside a triggered callback are logged with console.error instead of being silently swallowed.

Methods:

• on(key, callback) - register a listener.
• once(key, callback) - register a listener that auto-removes itself after firing once.
• off(key, callback?) - remove a specific listener, or every listener for key if callback is omitted.
• trigger(key, ...args) - synchronously invoke every listener registered for key.
• clear() - remove every listener for every key.

Properties:

• listeners: Map<Key, Set<AnyCallback>> - the underlying listener map (read-only usage recommended).

ScopedRegistry<Scope>

A CallbackRegistry namespaced by an additional "scope" key -- this is what powers room-scoped events (socket.rooms.on(room, event, cb) on the client, io.rooms.on(room, event, cb) on the server). Internally it lazily creates one CallbackRegistry per scope and tears it down once it has no listeners left.

import { ScopedRegistry } from "@bytesocket/core";

const rooms = new ScopedRegistry<string>(false);

rooms.on("lobby", "message", (data) => console.log(data));
rooms.trigger("lobby", "message", { text: "hi" });
rooms.off("lobby"); // removes every listener for the "lobby" scope

Constructor: new ScopedRegistry<Scope>(debug: boolean)

Methods:

• on(scope, event, callback)
• once(scope, event, callback)
• off(scope, event?, callback?) - omitting event clears the entire scope.
• trigger(scope, event, ...args)
• clear()

Properties:

• scopes: Map<Scope, CallbackRegistry>

Serializer

Wraps msgpackr and JSON behind one interface (ISerializer). Both the client and every server adapter construct exactly one Serializer instance and reuse it for every encode/decode call.

import { Serializer } from "@bytesocket/core";

const serializer = new Serializer(/* msgpackrOptions */ {}, /* serialization */ "binary");

const encoded = serializer.encode({ event: "chat", data: { text: "hi" } });
const decoded = serializer.decode(encoded);

Constructor: new Serializer(msgpackrOptions: MsgpackrOptions = {}, serialization: Serialization = "binary")

Methods:

• encode(payload, serialization?) - encodes any payload into a string (JSON) or a Buffer/Uint8Array (MessagePack). Falls back to the instance's default serialization if not overridden.
• decode(message, isBinary?) - decodes a raw WebSocket message back into a structured object. Handles:
  • Fragmented messages (Array<Uint8Array>) - concatenated automatically.
  • Plain text frames (string) - parsed as JSON.
  • Binary frames intended as text (isBinary === false) - decoded with TextDecoder.
  • Binary MessagePack frames - unpacked via the internal Packr instance.

Properties:

• serialization - the instance's default serialization mode.

ISerializer is also exported as a type; IByteSocketBase is kept as a deprecated alias of ISerializer for backwards compatibility.

Type Guards & Utilities

A set of pure, exported functions for verifying decoded message shapes at runtime. These replace what used to be protected methods on an internal base class -- they're now plain functions you can use directly if you're building custom tooling around the protocol.

• isObject(obj) - simple object check.
• isEventMessage(obj) - user event with event and data.
• isRoomEventMessage(obj) - user event scoped to a single room.
• isRoomsEventMessage(obj) - user event scoped to multiple rooms.
• isLifecycleMessage(type, obj) - composite guard for a specific lifecycle type.
• isLifecyclePayloadMessage(type, obj) - lifecycle message with a data payload.
• isLifecycleRoomMessage(type, obj) - single-room lifecycle message.
• isLifecycleRoomsMessage(type, obj) - multi-room lifecycle message.
• isLifecycleRoomErrorMessage(obj) - single-room error lifecycle message.
• isLifecycleRoomsErrorMessage(obj) - multi-room error lifecycle message.
• isErrorContext(obj) - checks whether a value already has the shape of an ErrorContext (used to avoid double-wrapping errors that arrive pre-structured, e.g. from the wire).
• safeStringify(value) - JSON.stringify with a String(value) fallback for values that can't be serialized (e.g. circular references); used internally wherever an error's raw payload is logged or relayed.

Usage

All types and primitives are re-exported by @bytesocket/client and @bytesocket/server. Import from those packages instead of directly from @bytesocket/core.

// ✅ Recommended
import { type SocketEvents, LifecycleTypes } from "@bytesocket/client";
// or
import { type SocketEvents, LifecycleTypes } from "@bytesocket/server";

License

MIT © 2026 Ahmed Ouda

• GitHub: @a7med3ouda