@emeryld/rrroutes-client 2.0.11 → 2.0.13

package/dist/index.cjs

@@ -473,6 +473,7 @@ var buildRoomPayloadSchema = (metaSchema) => import_zod.z.object({
 
 // src/sockets/socket.client.context.tsx
 var React = __toESM(require("react"), 1);
+var import_socket = require("socket.io-client");
 var import_jsx_runtime = require("react/jsx-runtime");
 var SocketCtx = React.createContext(null);
 function dbg(dbgOpts, e) {
@@ -480,6 +481,43 @@ function dbg(dbgOpts, e) {
   if (!dbgOpts[e.type]) return;
   dbgOpts.logger(e);
 }
+function safeDescribeHookValue(value) {
+  if (value == null) return value;
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean") return value;
+  if (valueType === "bigint" || valueType === "symbol") return String(value);
+  if (valueType === "function") return `[function ${value.name || "anonymous"}]`;
+  if (Array.isArray(value)) return `[array length=${value.length}]`;
+  if (value instanceof import_socket.Socket) {
+    const socket = value;
+    return `[Socket id=${socket.id ?? "unknown"} connected=${socket.connected ?? false}]`;
+  }
+  const ctorName = value.constructor?.name ?? "object";
+  const keys = Object.keys(value);
+  const keyPreview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[${ctorName} keys=${keyPreview}${suffix}]`;
+}
+function createHookDebugEvent(prev, next, hook) {
+  const reason = prev ? "change" : "init";
+  const changed = Object.keys(next).reduce((acc, dependency) => {
+    const prevValue = prev ? prev[dependency] : void 0;
+    const nextValue = next[dependency];
+    if (!prev || !Object.is(prevValue, nextValue)) {
+      acc.push({ dependency, previous: safeDescribeHookValue(prevValue), next: safeDescribeHookValue(nextValue) });
+    }
+    return acc;
+  }, []);
+  if (!changed.length) return null;
+  return { type: "hook", hook, reason, changes: changed };
+}
+function trackHookTrigger({ ref, hook, providerDebug, snapshot }) {
+  const prev = ref.current;
+  ref.current = snapshot;
+  if (!providerDebug?.logger || !providerDebug?.hook) return;
+  const event = createHookDebugEvent(prev, snapshot, hook);
+  if (event) dbg(providerDebug, event);
+}
 function buildSocketProvider(args) {
   const { events, options: baseOptions } = args;
   return {
@@ -499,53 +537,76 @@ function SocketProvider(props) {
   const { events, baseOptions, children, fallback, providerDebug, destroyLeaveMeta } = props;
   const [resolvedSocket, setResolvedSocket] = React.useState(null);
   const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
+  const providerDebugRef = React.useRef();
+  providerDebugRef.current = providerDebug;
+  const resolveEffectDebugRef = React.useRef(null);
+  const clientMemoDebugRef = React.useRef(null);
+  const destroyEffectDebugRef = React.useRef(null);
   React.useEffect(() => {
+    trackHookTrigger({
+      ref: resolveEffectDebugRef,
+      hook: "resolve_effect",
+      providerDebug: providerDebugRef.current,
+      snapshot: { resolvedSocket }
+    });
     if (!("getSocket" in props)) return;
     let cancelled = false;
-    dbg(providerDebug, { type: "resolve", phase: "start" });
+    dbg(providerDebugRef.current, { type: "resolve", phase: "start" });
     if (!resolvedSocket) {
       Promise.resolve(props.getSocket()).then((s) => {
         if (cancelled) {
-          dbg(providerDebug, { type: "resolve", phase: "cancelled" });
+          dbg(providerDebugRef.current, { type: "resolve", phase: "cancelled" });
           return;
         }
         if (!s) {
-          dbg(providerDebug, { type: "resolve", phase: "missing" });
+          dbg(providerDebugRef.current, { type: "resolve", phase: "missing" });
           return;
         }
         setResolvedSocket(s);
-        dbg(providerDebug, { type: "resolve", phase: "ok" });
+        dbg(providerDebugRef.current, { type: "resolve", phase: "ok" });
       }).catch((err) => {
         if (cancelled) return;
-        dbg(providerDebug, { type: "resolve", phase: "error", err: String(err) });
+        dbg(providerDebugRef.current, { type: "resolve", phase: "error", err: String(err) });
       });
     }
     return () => {
       cancelled = true;
     };
   }, [resolvedSocket]);
+  trackHookTrigger({
+    ref: clientMemoDebugRef,
+    hook: "client_memo",
+    providerDebug: providerDebugRef.current,
+    snapshot: { events, baseOptions, socket }
+  });
   const client = React.useMemo(() => {
     if (!socket) {
-      dbg(providerDebug, { type: "client", phase: "missing" });
+      dbg(providerDebugRef.current, { type: "client", phase: "missing" });
       return null;
     }
     const c = new SocketClient(events, { ...baseOptions, socket });
-    dbg(providerDebug, { type: "client", phase: "ready" });
+    dbg(providerDebugRef.current, { type: "client", phase: "ready" });
     return c;
-  }, [events, baseOptions, socket, providerDebug]);
+  }, [events, baseOptions, socket]);
   React.useEffect(() => {
+    trackHookTrigger({
+      ref: destroyEffectDebugRef,
+      hook: "destroy_effect",
+      providerDebug: providerDebugRef.current,
+      snapshot: { client, destroyLeaveMeta }
+    });
     return () => {
       if (client) {
         client.destroy(destroyLeaveMeta);
-        dbg(providerDebug, { type: "client", phase: "destroy" });
+        dbg(providerDebugRef.current, { type: "client", phase: "destroy" });
       }
     };
-  }, [client, providerDebug]);
+  }, [client, destroyLeaveMeta]);
   if (!client) {
-    dbg(providerDebug, { type: "render", phase: "waiting_for_socket" });
+    dbg(providerDebugRef.current, { type: "render", phase: "waiting_for_socket" });
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: fallback ?? children });
   }
-  dbg(providerDebug, { type: "render", phase: "provide" });
+  dbg(providerDebugRef.current, { type: "render", phase: "provide" });
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SocketCtx.Provider, { value: client, children });
 }
 function useSocketClient() {
@@ -591,6 +652,32 @@ var SocketClient = class {
       intervalMs: hb.intervalMs ?? 15e3,
       timeoutMs: hb.timeoutMs ?? 7500
     };
+    this.dbg({
+      type: "lifecycle",
+      phase: "init_start",
+      socketId: this.socket?.id ?? void 0,
+      details: {
+        environment: this.environment
+      }
+    });
+    if (!this.socket) {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init_socket_missing",
+        err: "Socket reference is null during initialization"
+      });
+    } else {
+      this.dbg({
+        type: "lifecycle",
+        phase: "init_ready",
+        socketId: this.socket.id,
+        details: {
+          heartbeatIntervalMs: this.hb.intervalMs,
+          heartbeatTimeoutMs: this.hb.timeoutMs
+        }
+      });
+      this.logSocketConfigSnapshot("init", "constructor");
+    }
     this.onConnect = () => {
       if (!this.socket) {
         this.dbg({ type: "connection", phase: "connect", err: "Socket is null" });
@@ -599,8 +686,12 @@ var SocketClient = class {
       this.dbg({
         type: "connection",
         phase: "connect",
-        id: this.socket.id
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
+        }
       });
+      this.logSocketConfigSnapshot("update", "connect_event");
       this.getSysEvent("sys:connect")({
         socket: this.socket,
         client: this
@@ -615,8 +706,12 @@ var SocketClient = class {
         type: "connection",
         phase: "reconnect",
         attempt,
-        id: this.socket.id
+        id: this.socket.id,
+        details: {
+          nsp: this.getNamespace(this.socket)
+        }
       });
+      this.logSocketConfigSnapshot("update", "reconnect_event");
       this.getSysEvent("sys:reconnect")({
         attempt,
         socket: this.socket,
@@ -631,8 +726,12 @@ var SocketClient = class {
       this.dbg({
         type: "connection",
         phase: "disconnect",
-        reason: String(reason)
+        reason: String(reason),
+        details: {
+          roomsTracked: this.roomCounts.size
+        }
       });
+      this.logSocketConfigSnapshot("update", "disconnect_event");
       this.getSysEvent("sys:disconnect")({
         reason: String(reason),
         socket: this.socket,
@@ -647,8 +746,10 @@ var SocketClient = class {
       this.dbg({
         type: "connection",
         phase: "connect_error",
-        err: String(err)
+        err: String(err),
+        details: this.getVerboseDetails({ rawError: err })
       });
+      this.logSocketConfigSnapshot("update", "connect_error_event");
       this.getSysEvent("sys:connect_error")({
         error: String(err),
         socket: this.socket,
@@ -664,8 +765,9 @@ var SocketClient = class {
       if (!parsed.success) {
         this.dbg({
           type: "heartbeat",
-          action: "pong_recv",
-          err: `pong payload validation failed: ${parsed.error.message}`
+          action: "validation_failed",
+          err: `pong payload validation failed: ${parsed.error.message}`,
+          details: this.getValidationDetails(parsed.error)
         });
         return;
       }
@@ -689,6 +791,61 @@ var SocketClient = class {
       this.socket.on("sys:pong", this.onPong);
     }
   }
+  snapshotSocketConfig(socket) {
+    if (!socket) return null;
+    const manager = socket.io ?? null;
+    const base = {
+      nsp: this.getNamespace(socket)
+    };
+    if (!manager) return base;
+    const opts = manager.opts ?? {};
+    const transports = Array.isArray(opts.transports) ? opts.transports.filter((t) => typeof t === "string") : void 0;
+    const transportName = typeof manager.engine?.transport?.name === "string" ? manager.engine.transport?.name : void 0;
+    const readyState = typeof manager._readyState === "string" ? manager._readyState : void 0;
+    const uri = typeof manager.uri === "string" ? manager.uri : void 0;
+    return {
+      ...base,
+      url: uri,
+      path: typeof opts.path === "string" ? opts.path : void 0,
+      transport: transportName ?? transports?.[0],
+      transports,
+      readyState,
+      autoConnect: typeof opts.autoConnect === "boolean" ? opts.autoConnect : void 0,
+      reconnection: typeof opts.reconnection === "boolean" ? opts.reconnection : void 0,
+      reconnectionAttempts: typeof opts.reconnectionAttempts === "number" ? opts.reconnectionAttempts : void 0,
+      reconnectionDelay: typeof opts.reconnectionDelay === "number" ? opts.reconnectionDelay : void 0,
+      reconnectionDelayMax: typeof opts.reconnectionDelayMax === "number" ? opts.reconnectionDelayMax : void 0,
+      timeout: typeof opts.timeout === "number" ? opts.timeout : void 0,
+      hostname: typeof opts.hostname === "string" ? opts.hostname : void 0,
+      port: typeof opts.port === "number" || typeof opts.port === "string" ? opts.port : void 0,
+      secure: typeof opts.secure === "boolean" ? opts.secure : void 0
+    };
+  }
+  logSocketConfigSnapshot(phase, reason) {
+    if (!this.debug.logger || !this.debug.config) return;
+    const snapshot = this.snapshotSocketConfig(this.socket);
+    this.dbg({
+      type: "config",
+      phase,
+      reason,
+      socketId: this.socket?.id,
+      snapshot: snapshot ?? void 0,
+      err: snapshot ? void 0 : "Socket unavailable for config snapshot"
+    });
+  }
+  getValidationDetails(error) {
+    if (!this.debug.verbose) return void 0;
+    return { issues: error.issues };
+  }
+  getVerboseDetails(details) {
+    if (!this.debug.verbose) return void 0;
+    return details;
+  }
+  getNamespace(socket) {
+    if (!socket) return void 0;
+    const nsp = socket.nsp;
+    return typeof nsp === "string" ? nsp : void 0;
+  }
   getSysEvent(name) {
     return this.sysEvents[name];
   }
@@ -738,16 +895,44 @@ var SocketClient = class {
    */
   startHeartbeat() {
     this.stopHeartbeat();
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "heartbeat",
+        action: "start",
+        err: "Socket is null"
+      });
+      return;
+    }
     const socket = this.socket;
+    this.dbg({
+      type: "heartbeat",
+      action: "start",
+      details: {
+        intervalMs: this.hb.intervalMs,
+        timeoutMs: this.hb.timeoutMs
+      }
+    });
     const tick = () => {
-      if (!socket) return;
+      if (!socket) {
+        this.dbg({
+          type: "heartbeat",
+          action: "tick_skip",
+          err: "Socket missing during heartbeat tick"
+        });
+        return;
+      }
       const payload = this.getSysEvent("sys:ping")({
         socket,
         client: this
       });
       const check = this.config.pingPayload.safeParse(payload);
       if (!check.success) {
+        this.dbg({
+          type: "heartbeat",
+          action: "validation_failed",
+          err: "ping payload validation failed",
+          details: this.getValidationDetails(check.error)
+        });
         if (this.environment === "development") {
           console.warn("[socket] ping schema validation failed", check.error.issues);
         }
@@ -771,10 +956,18 @@ var SocketClient = class {
    * call it yourself from any sysHandler to fully control heartbeat lifecycle.
    */
   stopHeartbeat() {
+    const hadTimer = Boolean(this.hbTimer);
     if (this.hbTimer) {
       clearInterval(this.hbTimer);
       this.hbTimer = null;
     }
+    this.dbg({
+      type: "heartbeat",
+      action: "stop",
+      details: {
+        hadTimer
+      }
+    });
   }
   emit(event, payload, metadata) {
     if (!this.socket) {
@@ -783,7 +976,15 @@ var SocketClient = class {
     }
     const schema = this.events[event].message;
     const parsed = schema.safeParse(payload);
-    if (!parsed.success) throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
+    if (!parsed.success) {
+      this.dbg({
+        type: "emit",
+        event,
+        err: "payload_validation_failed",
+        details: this.getValidationDetails(parsed.error)
+      });
+      throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
+    }
     this.socket.emit(String(event), parsed.data);
     this.dbg({
       type: "emit",
@@ -819,7 +1020,13 @@ var SocketClient = class {
       });
       if (!payloadResult.success) {
         this.rollbackJoinIncrement(toJoin);
-        this.dbg({ type: "room", action: "join", rooms: toJoin, err: "payload validation failed" });
+        this.dbg({
+          type: "room",
+          action: "join",
+          rooms: toJoin,
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
+        });
         return;
       }
       const payload = payloadResult.data;
@@ -858,7 +1065,13 @@ var SocketClient = class {
       });
       if (!payloadResult.success) {
         this.rollbackLeaveDecrement(toLeave);
-        this.dbg({ type: "room", action: "leave", rooms: toLeave, err: "payload validation failed" });
+        this.dbg({
+          type: "room",
+          action: "leave",
+          rooms: toLeave,
+          err: "payload validation failed",
+          details: this.getValidationDetails(payloadResult.error)
+        });
         return;
       }
       const payload = payloadResult.data;
@@ -880,7 +1093,15 @@ var SocketClient = class {
       const maybeEnvelope = envelopeOrRaw;
       const rawData = maybeEnvelope?.data ?? maybeEnvelope;
       const parsed = schema.safeParse(rawData);
-      if (!parsed.success) return;
+      if (!parsed.success) {
+        this.dbg({
+          type: "receive",
+          event,
+          err: "payload_validation_failed",
+          details: this.getValidationDetails(parsed.error)
+        });
+        return;
+      }
       const receivedAt = /* @__PURE__ */ new Date();
       const sentAt = maybeEnvelope?.sentAt ? new Date(maybeEnvelope.sentAt) : void 0;
       const meta = {
@@ -894,7 +1115,7 @@ var SocketClient = class {
         ctx: {
           receivedAt,
           latencyMs: sentAt ? Math.max(0, receivedAt.getTime() - sentAt.getTime()) : void 0,
-          nsp: socket.nsp,
+          nsp: this.getNamespace(socket),
           socketId: socket.id,
           socket
         }
@@ -941,6 +1162,15 @@ var SocketClient = class {
   destroy(leaveMeta) {
     this.stopHeartbeat();
     const socket = this.socket;
+    this.dbg({
+      type: "lifecycle",
+      phase: "destroy_begin",
+      socketId: socket?.id,
+      details: {
+        roomsTracked: this.roomCounts.size,
+        handlerEvents: this.handlerMap.size
+      }
+    });
     if (socket) {
       socket.off("connect", this.onConnect);
       socket.off("reconnect", this.onReconnect);
@@ -960,18 +1190,58 @@ var SocketClient = class {
       this.leaveRooms(toLeave, leaveMeta);
     }
     this.roomCounts.clear();
+    this.dbg({
+      type: "lifecycle",
+      phase: "destroy_complete",
+      socketId: socket?.id,
+      details: {
+        roomsTracked: this.roomCounts.size,
+        handlerEvents: this.handlerMap.size
+      }
+    });
   }
   /** Pass-throughs. Managing connection is the caller’s responsibility. */
   disconnect() {
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "connection",
+        phase: "disconnect",
+        reason: "client_disconnect",
+        err: "Socket is null"
+      });
+      return;
+    }
     this.stopHeartbeat();
     this.socket.disconnect();
-    this.dbg({ type: "connection", phase: "disconnect", reason: "client_disconnect" });
+    this.dbg({
+      type: "connection",
+      phase: "disconnect",
+      reason: "client_disconnect",
+      details: {
+        nsp: this.getNamespace(this.socket)
+      }
+    });
+    this.logSocketConfigSnapshot("update", "disconnect_call");
   }
   connect() {
-    if (!this.socket) return;
+    if (!this.socket) {
+      this.dbg({
+        type: "connection",
+        phase: "connect",
+        err: "Socket is null"
+      });
+      return;
+    }
     this.socket.connect();
-    this.dbg({ type: "connection", phase: "connect", id: this.socket.id ?? "" });
+    this.dbg({
+      type: "connection",
+      phase: "connect",
+      id: this.socket.id ?? "",
+      details: {
+        nsp: this.getNamespace(this.socket)
+      }
+    });
+    this.logSocketConfigSnapshot("update", "connect_call");
   }
 };
 // Annotate the CommonJS export names for ESM import in node: