@emeryld/rrroutes-client 2.6.4 → 2.6.6

package/dist/sockets/socket.client.context.provider.d.ts

@@ -1,9 +1,9 @@
 import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import * as React from 'react';
 import type { Socket } from 'socket.io-client';
-import { SocketClient, type SocketClientOptions } from './socket.client.core';
 import { type UseSocketConnectionArgs } from './socket.client.context.connection';
 import { SocketProviderDebugOptions } from './socket.client.context.debug';
+import { SocketClient, type SocketClientOptions } from './socket.client.core';
 type BaseOptions<T extends EventMap, C extends SocketConnectionConfigOutput> = Omit<SocketClientOptions<T, C>, 'socket'>;
 type ProviderRuntimeSocket = {
     socket: Socket | null;
@@ -11,7 +11,9 @@ type ProviderRuntimeSocket = {
     getSocket: () => Socket | Promise<Socket>;
 };
 export declare function buildSocketProvider<T extends EventMap, C extends SocketConnectionConfigOutput>(args: {
+    /** The events map for the SocketClient. This is required to ensure type safety when using the client and connection hooks. */
     events: T;
+    /** The base options for the SocketClient. This includes all options except the socket instance and debug options. */
     options: Omit<BaseOptions<T, C>, 'debug'> & {
         debug: BaseOptions<T, C>['debug'] & SocketProviderDebugOptions;
     };

package/dist/sockets/socket.client.core.d.ts

@@ -46,9 +46,22 @@ export type HeartbeatClientOptions = {
 export type SocketClientOptions<T extends EventMap = EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
     /** Inject an existing socket.io-client Socket. Can be null while bootstrapping. */
     socket: MaybeSocket;
+    /** The configuration of the ping/pong payload schemas and room join/leave meta message schemas. */
     config: C;
+    /** Optional debug configuration. */
     environment?: 'development' | 'production';
+    /** Optional debug configuration.
+     * emit: when emitting an event
+     * receive: when receiving an event
+     * connection: on connect/reconnect/disconnect/connect_error
+     * lifecycle: on client init and destroy
+     * heartbeat: on ping emit, pong receive, and validation failures
+     * config: when logging the socket config snapshot (only if debug.logger is set)
+     * room: on room join and leave attempts
+     * register: when registering and unregistering event handlers
+     */
     debug?: SocketClientDebugOptions<keyof T & string>;
+    /** Optional heartbeat configuration. If provided, the client will start the heartbeat loop on the default 'sys:connect' handler. */
     heartbeat?: HeartbeatClientOptions;
     sys: SysEventMap<T, C>;
 };
@@ -75,6 +88,7 @@ export declare class SocketClient<T extends EventMap, C extends SocketConnection
     private logSocketConfigSnapshot;
     private getValidationDetails;
     private getVerboseDetails;
+    private formatError;
     private getNamespace;
     constructor(events: T, opts: SocketClientOptions<T, C>);
     private getSysEvent;

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

@@ -1,43 +1,51 @@
+import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import type { Socket } from 'socket.io-client';
 import { z } from 'zod';
-import type { EventMap, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import type { SocketClient } from './socket.client.core';
 export type MaybeSocket = Socket | null;
 export type SysEventMap<T extends EventMap, C extends SocketConnectionConfigOutput = SocketConnectionConfigOutput> = {
+    /** Connect event, triggered when the socket successfully connects to the server. */
     'sys:connect': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
     }) => Promise<void> | void;
+    /** Disconnect event, triggered when the socket disconnects from the server. */
     'sys:disconnect': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
         reason: string;
     }) => Promise<void> | void;
+    /** Reconnect attempt event, triggered when the socket attempts to reconnect after a disconnection. */
     'sys:reconnect': (args: {
         socket: Socket;
         attempt: number;
         client: SocketClient<T, C>;
     }) => Promise<void> | void;
+    /** Connect error event, triggered when the socket encounters an error while trying to connect to the server. */
     'sys:connect_error': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
         error: string;
     }) => Promise<void> | void;
+    /** Ping event, triggered by the server to check if the client is still responsive. The client can respond with a pong event, optionally including a payload defined by the server. */
     'sys:ping': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
     }) => Promise<SocketSchemaOutput<C['pingPayload']>> | SocketSchemaOutput<C['pingPayload']>;
+    /** Pong event, triggered in response to a ping event, allowing the client to send a payload back to the server. */
     'sys:pong': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
         payload: SocketSchemaOutput<C['pongPayload']>;
     }) => Promise<void> | void;
+    /** Room join event, triggered when the client attempts to join one or more rooms. Return true to allow the join, or false to deny it. */
     'sys:room_join': (args: {
         socket: Socket;
         client: SocketClient<T, C>;
         rooms: string | string[];
         meta: SocketSchemaOutput<C['joinMetaMessage']>;
     }) => Promise<boolean> | boolean;
+    /** Room leave event, triggered when the client attempts to leave one or more rooms. Return true to allow the leave, or false to deny it. */
     'sys:room_leave': (args: {
         socket: Socket;
         client: SocketClient<T, C>;

package/dist/sockets/socketedRoute/socket.client.helper.route.d.ts

@@ -8,8 +8,11 @@ type SocketedRouteResult<L extends AnyLeafLowProfile> = (L['cfg']['feed'] extend
     rooms: string[];
 };
 export type SocketedRouteOptions<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput> = {
+    /** The built route to compose with socket wiring. This should be a route built with the `buildRoute` function */
     built: SocketedBuilt<L>;
+    /** A function that derives the rooms to join from the endpoint data. This will be called on initial render and whenever the endpoint data changes. */
     toRooms: ToRoomsMapper<L, C>;
+    /** An object mapping socket event names to functions that apply incoming socket messages to the endpoint data. Each function receives the previous data, the socket message payload, and an optional meta object containing the server envelope and client context. The function should return the new data (new referrence), or null to indicate no change. */
     applySocket: {
         [K in keyof Events & string]?: (prev: DataShape<L> | undefined, payload: Payload<Events, K>, meta: {
             envelope?: ServerEnvelope<Events, keyof Events & string>;
@@ -17,7 +20,14 @@ export type SocketedRouteOptions<L extends AnyLeafLowProfile, Events extends Eve
             args: UseEndpointArgs<L>;
         }) => DataShape<L> | undefined | null;
     };
+    /** A hook that returns the SocketClient instance. This is required to access the socket client within the route and apply socket messages. */
     useSocketClient: () => SocketClient<Events, C>;
+    /** Debug options for the socketed route. This is optional and can be used to enable debug logging for the route's internal operations, such as room joining and socket message application.
+     * client: Logs when the socket client becomes available or unavailable.
+     * render: Logs on each render of the route, including whether the client is available and the current rooms.
+     * hook: Logs when key hooks are triggered, such as receiving endpoint data or applying socket messages, along with snapshots of relevant state.
+     * room: Logs attempts to join or leave rooms, including reasons for skipping or errors.
+     */
     debug?: SocketedRouteDebugOptions;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "2.6.4",
+  "version": "2.6.6",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",