@emeryld/rrroutes-server 2.5.4 → 2.6.1

package/dist/sockets/socket.server.index.d.ts

@@ -4,11 +4,14 @@ import type { SocketDebugOptions } from './socket.server.debug';
 import type { HeartbeatServerOptions, SysServerEventMap } from './socket.server.sys';
 import type { HandlerCtx } from './socket.server.types';
 export interface SocketConnection<T extends EventMap> {
+    /** Registers a handler for a specific event. The handler receives the parsed payload and a context object with information about the socket and helper methods. Returns an unregister function to remove the handler. */
     on<K extends keyof T & string>(args: {
         eventName: K;
         handler: (payload: Payload<T, K>, ctx: HandlerCtx) => void | Promise<void>;
     }): () => void;
+    /** Unregisters all handlers for a specific event. */
     off<K extends keyof T & string>(eventName: K): void;
+    /** Emits an event with a validated payload to specific rooms or sockets. The payload is validated against the schema defined for the event, and an envelope with metadata is sent. If the event is not registered, it falls back to a raw emit without validation or envelope. */
     emit<K extends keyof T & string>(args: {
         eventName: K;
         payload: Payload<T, K>;
@@ -16,6 +19,7 @@ export interface SocketConnection<T extends EventMap> {
         metadata?: Record<string, unknown>;
         onAck?: (ack: unknown) => void;
     }): void;
+    /** Emits an event with an unvalidated payload to specific rooms or sockets. This method does not perform schema validation or envelope wrapping, and is intended for emitting events that are not registered in the events map. */
     emitAny(args: {
         eventName: string;
         payload: unknown;
@@ -23,13 +27,31 @@ export interface SocketConnection<T extends EventMap> {
         metadata?: Record<string, unknown>;
         onAck?: (ack: unknown) => void;
     }): void;
+    /** Destroys the socket connection by removing all event handlers, cleaning up resources, and detaching from the Socket.IO server. After calling this method, the SocketConnection instance should not be used. */
     destroy(): void;
 }
-export declare function createSocketConnections<T extends EventMap, TConfig extends SocketConnectionConfigOutput = SocketConnectionConfigOutput>(io: Server, events: T, opts: {
+export declare function createSocketConnections<T extends EventMap, TConfig extends SocketConnectionConfigOutput = SocketConnectionConfigOutput>(
+/** The Socket.IO server instance to bind to */
+io: Server, 
+/** The options for the socket connection, including debug settings, heartbeat configuration, system event handlers, and any custom config values */
+events: T, 
+/** The options for the socket connection, including debug settings, heartbeat configuration, system event handlers, and any custom config values */
+opts: {
+    /** Optional debug configuration for logging socket events and actions
+     * register: when handlers are registered/unregistered
+     * handler: when events are received and processed by handlers, including validation results and errors
+     * emit: when events are emitted, including payload validation results and errors
+     * rooms: when sockets join or leave rooms, including the rooms involved and any issues
+     * heartbeat: when heartbeat pings are received and pongs are sent, including any issues or errors
+     * config: when a socket connects and receives the initial config snapshot
+     * lifecycle: for general lifecycle events like server initialization and destruction
+     */
     debug?: SocketDebugOptions;
+    /** Optional heartbeat configuration to enable connection health checks and automatic disconnections */
     heartbeat?: HeartbeatServerOptions;
     /** System event customization (connect / disconnect / ping / pong / room join/leave) */
     sys: SysServerEventMap<TConfig, T>;
+    /** Custom config values that can be used in system event handlers via the HandlerCtx */
     config: TConfig;
 }): SocketConnection<T>;
 export type { SocketDebugOptions, SocketServerConfigSnapshot, SocketServerDebugEvent, SocketServerHeartbeatPhase, SocketServerLifecycleStage, } from './socket.server.debug';

package/dist/sockets/socket.server.sys.d.ts

@@ -12,6 +12,7 @@ export type HeartbeatServerOptions = {
     enabled?: boolean;
 };
 export type SysServerEventMap<Config extends SocketConnectionConfigOutput = SocketConnectionConfigOutput, Events extends EventMap = EventMap> = {
+    /** Handler for new socket connections. Must call `complete()` to proceed with default connection setup (attaching built-in handlers for heartbeat, room join/leave, disconnect, etc). */
     'sys:connect': (args: {
         socket: Socket;
         helper: SocketConnectionHelper<Events>;
@@ -21,6 +22,7 @@ export type SysServerEventMap<Config extends SocketConnectionConfigOutput = Sock
          */
         complete: () => void;
     }) => void | Promise<void>;
+    /** Handler for socket disconnections. Must call `cleanup()` to proceed with default disconnect cleanup (removing built-in handlers). */
     'sys:disconnect': (args: {
         socket: Socket;
         helper: SocketConnectionHelper<Events>;
@@ -28,12 +30,14 @@ export type SysServerEventMap<Config extends SocketConnectionConfigOutput = Sock
         cleanup: () => void;
         reason: string;
     }) => void | Promise<void>;
+    /** Handler for heartbeat pings. Must return the payload for the corresponding pong response. */
     'sys:ping': (args: {
         socket: Socket;
         helper: SocketConnectionHelper<Events>;
         ping: SocketSchemaOutput<Config['pingPayload']>;
         ctx: HandlerCtxNoAck;
     }) => SocketSchemaOutput<Config['pongPayload']> | Promise<SocketSchemaOutput<Config['pongPayload']>>;
+    /** Handler for joining rooms. Must call `join(room)` for each room to be joined. */
     'sys:room_join': (args: {
         socket: Socket;
         helper: SocketConnectionHelper<Events>;
@@ -41,6 +45,7 @@ export type SysServerEventMap<Config extends SocketConnectionConfigOutput = Sock
         meta: SocketSchemaOutput<Config['joinMetaMessage']>;
         join: (room: string) => Promise<void>;
     }) => void | Promise<void>;
+    /** Handler for leaving rooms. Must call `leave(room)` for each room to be left. */
     'sys:room_leave': (args: {
         socket: Socket;
         helper: SocketConnectionHelper<Events>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-server",
-  "version": "2.5.4",
+  "version": "2.6.1",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -17,7 +17,7 @@
     "dist"
   ],
   "dependencies": {
-    "@emeryld/rrroutes-contract": "^2.5.13",
+    "@emeryld/rrroutes-contract": "^2.6.0",
     "jose": "^6.1.3",
     "multer": "1.4.5-lts.2",
     "socket.io": "^4.8.3",