@emeryld/rrroutes-client 2.0.12 → 2.1.0

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,54 +537,73 @@ 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: "init", missing: true });
       return null;
     }
     const c = new SocketClient(events, { ...baseOptions, socket });
-    dbg(providerDebug, { type: "client", phase: "ready" });
+    dbg(providerDebugRef.current, { type: "client", phase: "init", missing: false });
     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]);
-  if (!client) {
-    dbg(providerDebug, { 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" });
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SocketCtx.Provider, { value: client, children });
+  }, [client, destroyLeaveMeta]);
+  dbg(providerDebugRef.current, { type: "render", hasClient: !!client });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SocketCtx.Provider, { value: client, children: client == null ? fallback ?? children : children });
 }
 function useSocketClient() {
   const ctx = React.useContext(SocketCtx);
@@ -591,31 +648,24 @@ 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",
+        phase: "init",
         err: "Socket reference is null during initialization"
       });
     } else {
       this.dbg({
         type: "lifecycle",
-        phase: "init_ready",
+        phase: "init",
         socketId: this.socket.id,
         details: {
           heartbeatIntervalMs: this.hb.intervalMs,
-          heartbeatTimeoutMs: this.hb.timeoutMs
+          heartbeatTimeoutMs: this.hb.timeoutMs,
+          environment: this.environment
         }
       });
-      this.logSocketConfigSnapshot("init", "constructor");
+      this.logSocketConfigSnapshot("constructor");
     }
     this.onConnect = () => {
       if (!this.socket) {
@@ -630,7 +680,7 @@ var SocketClient = class {
           nsp: this.getNamespace(this.socket)
         }
       });
-      this.logSocketConfigSnapshot("update", "connect_event");
+      this.logSocketConfigSnapshot("connect_event");
       this.getSysEvent("sys:connect")({
         socket: this.socket,
         client: this
@@ -650,7 +700,7 @@ var SocketClient = class {
           nsp: this.getNamespace(this.socket)
         }
       });
-      this.logSocketConfigSnapshot("update", "reconnect_event");
+      this.logSocketConfigSnapshot("reconnect_event");
       this.getSysEvent("sys:reconnect")({
         attempt,
         socket: this.socket,
@@ -670,7 +720,7 @@ var SocketClient = class {
           roomsTracked: this.roomCounts.size
         }
       });
-      this.logSocketConfigSnapshot("update", "disconnect_event");
+      this.logSocketConfigSnapshot("disconnect_event");
       this.getSysEvent("sys:disconnect")({
         reason: String(reason),
         socket: this.socket,
@@ -688,7 +738,7 @@ var SocketClient = class {
         err: String(err),
         details: this.getVerboseDetails({ rawError: err })
       });
-      this.logSocketConfigSnapshot("update", "connect_error_event");
+      this.logSocketConfigSnapshot("connect_error_event");
       this.getSysEvent("sys:connect_error")({
         error: String(err),
         socket: this.socket,
@@ -697,14 +747,14 @@ var SocketClient = class {
     };
     this.onPong = (raw) => {
       if (!this.socket) {
-        this.dbg({ type: "heartbeat", action: "pong_recv", err: "Socket is null" });
+        this.dbg({ type: "heartbeat", phase: "pong_recv", err: "Socket is null" });
         throw new Error("Socket is null in onPong handler");
       }
       const parsed = this.config.pongPayload.safeParse(raw);
       if (!parsed.success) {
         this.dbg({
           type: "heartbeat",
-          action: "validation_failed",
+          phase: "validation_failed",
           err: `pong payload validation failed: ${parsed.error.message}`,
           details: this.getValidationDetails(parsed.error)
         });
@@ -713,7 +763,7 @@ var SocketClient = class {
       const validated = parsed.data;
       this.dbg({
         type: "heartbeat",
-        action: "pong_recv",
+        phase: "pong_recv",
         payload: validated
       });
       this.getSysEvent("sys:pong")({
@@ -760,16 +810,16 @@ var SocketClient = class {
       secure: typeof opts.secure === "boolean" ? opts.secure : void 0
     };
   }
-  logSocketConfigSnapshot(phase, reason) {
+  logSocketConfigSnapshot(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"
+      phase: reason,
+      ...snapshot == null ? { err: "Socket is missing. " } : {
+        socketId: this.socket?.id,
+        snapshot
+      }
     });
   }
   getValidationDetails(error) {
@@ -837,7 +887,7 @@ var SocketClient = class {
     if (!this.socket) {
       this.dbg({
         type: "heartbeat",
-        action: "start",
+        phase: "start",
         err: "Socket is null"
       });
       return;
@@ -845,7 +895,7 @@ var SocketClient = class {
     const socket = this.socket;
     this.dbg({
       type: "heartbeat",
-      action: "start",
+      phase: "start",
       details: {
         intervalMs: this.hb.intervalMs,
         timeoutMs: this.hb.timeoutMs
@@ -855,7 +905,7 @@ var SocketClient = class {
       if (!socket) {
         this.dbg({
           type: "heartbeat",
-          action: "tick_skip",
+          phase: "tick_skip",
           err: "Socket missing during heartbeat tick"
         });
         return;
@@ -868,7 +918,7 @@ var SocketClient = class {
       if (!check.success) {
         this.dbg({
           type: "heartbeat",
-          action: "validation_failed",
+          phase: "validation_failed",
           err: "ping payload validation failed",
           details: this.getValidationDetails(check.error)
         });
@@ -881,7 +931,7 @@ var SocketClient = class {
       socket.emit("sys:ping", dataToSend);
       this.dbg({
         type: "heartbeat",
-        action: "ping_emit",
+        phase: "ping_emit",
         payload: dataToSend
       });
     };
@@ -902,7 +952,7 @@ var SocketClient = class {
     }
     this.dbg({
       type: "heartbeat",
-      action: "stop",
+      phase: "stop",
       details: {
         hadTimer
       }
@@ -933,7 +983,7 @@ var SocketClient = class {
   }
   joinRooms(rooms, meta) {
     if (!this.socket) {
-      this.dbg({ type: "room", action: "join", rooms: this.toArray(rooms), err: "Socket is null" });
+      this.dbg({ type: "room", phase: "join", rooms: this.toArray(rooms), err: "Socket is null" });
       throw new Error("Socket is null in joinRooms method");
     }
     if (!this.getSysEvent("sys:room_join")({
@@ -942,7 +992,7 @@ var SocketClient = class {
       socket: this.socket,
       client: this
     })) {
-      this.dbg({ type: "room", action: "join", rooms: this.toArray(rooms), err: "sys:room_join handler aborted join" });
+      this.dbg({ type: "room", phase: "join", rooms: this.toArray(rooms), err: "sys:room_join handler aborted join" });
       return;
     }
     const list = this.toArray(rooms);
@@ -961,7 +1011,7 @@ var SocketClient = class {
         this.rollbackJoinIncrement(toJoin);
         this.dbg({
           type: "room",
-          action: "join",
+          phase: "join",
           rooms: toJoin,
           err: "payload validation failed",
           details: this.getValidationDetails(payloadResult.error)
@@ -971,12 +1021,12 @@ var SocketClient = class {
       const payload = payloadResult.data;
       const normalizedRooms = this.toArray(payload.rooms);
       this.socket.emit("sys:room_join", payload);
-      this.dbg({ type: "room", action: "join", rooms: normalizedRooms });
+      this.dbg({ type: "room", phase: "join", rooms: normalizedRooms });
     }
   }
   leaveRooms(rooms, meta) {
     if (!this.socket) {
-      this.dbg({ type: "room", action: "leave", rooms: this.toArray(rooms), err: "Socket is null" });
+      this.dbg({ type: "room", phase: "leave", rooms: this.toArray(rooms), err: "Socket is null" });
       throw new Error("Socket is null in leaveRooms method");
     }
     if (!this.getSysEvent("sys:room_leave")({
@@ -985,7 +1035,7 @@ var SocketClient = class {
       socket: this.socket,
       client: this
     })) {
-      this.dbg({ type: "room", action: "leave", rooms: this.toArray(rooms), err: "sys:room_leave handler aborted leave" });
+      this.dbg({ type: "room", phase: "leave", rooms: this.toArray(rooms), err: "sys:room_leave handler aborted leave" });
       return;
     }
     const list = this.toArray(rooms);
@@ -1006,7 +1056,7 @@ var SocketClient = class {
         this.rollbackLeaveDecrement(toLeave);
         this.dbg({
           type: "room",
-          action: "leave",
+          phase: "leave",
           rooms: toLeave,
           err: "payload validation failed",
           details: this.getValidationDetails(payloadResult.error)
@@ -1016,14 +1066,14 @@ var SocketClient = class {
       const payload = payloadResult.data;
       const normalizedRooms = this.toArray(payload.rooms);
       this.socket.emit("sys:room_leave", payload);
-      this.dbg({ type: "room", action: "leave", rooms: normalizedRooms });
+      this.dbg({ type: "room", phase: "leave", rooms: normalizedRooms });
     }
   }
   on(event, handler) {
     const schema = this.events[event].message;
-    this.dbg({ type: "register", action: "register", event });
+    this.dbg({ type: "register", phase: "register", event });
     if (!this.socket) {
-      this.dbg({ type: "register", action: "register", event, err: "Socket is null" });
+      this.dbg({ type: "register", phase: "register", event, err: "Socket is null" });
       return () => {
       };
     }
@@ -1091,7 +1141,7 @@ var SocketClient = class {
         s.delete(entry);
         if (s.size === 0) this.handlerMap.delete(String(event));
       }
-      this.dbg({ type: "register", action: "unregister", event });
+      this.dbg({ type: "register", phase: "unregister", event });
     };
   }
   /**
@@ -1160,7 +1210,7 @@ var SocketClient = class {
         nsp: this.getNamespace(this.socket)
       }
     });
-    this.logSocketConfigSnapshot("update", "disconnect_call");
+    this.logSocketConfigSnapshot("disconnect_call");
   }
   connect() {
     if (!this.socket) {
@@ -1180,7 +1230,7 @@ var SocketClient = class {
         nsp: this.getNamespace(this.socket)
       }
     });
-    this.logSocketConfigSnapshot("update", "connect_call");
+    this.logSocketConfigSnapshot("connect_call");
   }
 };
 // Annotate the CommonJS export names for ESM import in node: