@emeryld/rrroutes-client 2.6.0 → 2.6.2

package/dist/index.cjs

@@ -1593,7 +1593,9 @@ function useSocketConnection(args) {
   React.useEffect(() => {
     if (autoJoin && normalizedRooms.length > 0)
       client.joinRooms(normalizedRooms, args.joinMeta);
-    const unsubscribe = client.on(event, onMessage);
+    const unsubscribe = client.on(event, (payload, meta) => {
+      onMessage(payload, meta);
+    });
     return () => {
       unsubscribe();
       if (autoLeave && normalizedRooms.length > 0)
@@ -1618,6 +1620,92 @@ function normalizeRooms(rooms) {
   }
   return normalized;
 }
+var objectReferenceIds = /* @__PURE__ */ new WeakMap();
+var objectReferenceCounter = 0;
+function describeObjectReference(value) {
+  if (value == null) return null;
+  const valueType = typeof value;
+  if (valueType !== "object" && valueType !== "function") return null;
+  const obj = value;
+  let id = objectReferenceIds.get(obj);
+  if (!id) {
+    id = ++objectReferenceCounter;
+    objectReferenceIds.set(obj, id);
+  }
+  return `ref#${id}`;
+}
+function safeJsonKey(value) {
+  try {
+    const serialized = JSON.stringify(value ?? null);
+    return serialized ?? "null";
+  } catch {
+    return "[unserializable]";
+  }
+}
+function arrayShallowEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function roomStateEqual(prev, next) {
+  return arrayShallowEqual(prev.rooms, next.rooms) && safeJsonKey(prev.joinMeta) === safeJsonKey(next.joinMeta) && safeJsonKey(prev.leaveMeta) === safeJsonKey(next.leaveMeta);
+}
+function safeDescribeHookValue2(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}]`;
+  const ctorName = value.constructor?.name ?? "object";
+  const keys = Object.keys(value);
+  const keyPreview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  const ref = describeObjectReference(value);
+  return `[${ctorName}${ref ? ` ${ref}` : ""} keys=${keyPreview}${suffix}]`;
+}
+function createHookDebugEvent2(prev, next, phase) {
+  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: safeDescribeHookValue2(prevValue),
+        next: safeDescribeHookValue2(nextValue)
+      });
+    }
+    return acc;
+  }, []);
+  if (!changed.length) return null;
+  return { type: "hook", phase, reason, changes: changed };
+}
+function dbg2(debug, event) {
+  if (!debug?.logger) return;
+  if (!debug[event.type]) return;
+  debug.logger(event);
+}
+function trackHookTrigger2({
+  ref,
+  phase,
+  debug,
+  snapshot
+}) {
+  const prev = ref.current;
+  ref.current = snapshot;
+  if (!debug?.logger || !debug?.hook) return;
+  const event = createHookDebugEvent2(prev, snapshot, phase);
+  if (event) dbg2(debug, event);
+}
+function isSocketClientUnavailableError(err) {
+  return err instanceof Error && err.message.includes("SocketClient not found");
+}
 function mergeRoomState(prev, toRoomsResult) {
   const merged = new Set(prev.rooms);
   for (const r of normalizeRooms(toRoomsResult.rooms)) merged.add(r);
@@ -1656,84 +1744,247 @@ function roomsFromData(data, toRooms) {
   return state;
 }
 function buildSocketedRoute(options) {
-  const { built, toRooms, applySocket, useSocketClient: useSocketClient2 } = options;
+  const { built, toRooms, applySocket, useSocketClient: useSocketClient2, debug } = options;
   const { useEndpoint: useInnerEndpoint, ...rest } = built;
   const useEndpoint = (...useArgs) => {
-    const client = useSocketClient2();
+    let client = null;
+    let socketClientError = null;
+    try {
+      client = useSocketClient2();
+    } catch (err) {
+      if (!isSocketClientUnavailableError(err)) throw err;
+      socketClientError = err;
+    }
     const endpointResult = useInnerEndpoint(
       ...useArgs
     );
-    const argsKey = (0, import_react4.useMemo)(() => JSON.stringify(useArgs[0] ?? null), [useArgs]);
+    const argsKey = (0, import_react4.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
     const [roomState, setRoomState] = (0, import_react4.useState)(
       () => roomsFromData(endpointResult.data, toRooms)
     );
+    const renderCountRef = (0, import_react4.useRef)(0);
+    const clientReadyRef = (0, import_react4.useRef)(null);
+    const onReceiveEffectDebugRef = (0, import_react4.useRef)(null);
+    const deriveRoomsEffectDebugRef = (0, import_react4.useRef)(null);
+    const joinRoomsEffectDebugRef = (0, import_react4.useRef)(null);
+    const applySocketEffectDebugRef = (0, import_react4.useRef)(null);
+    renderCountRef.current += 1;
     const roomsKey = (0, import_react4.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
     const joinMetaKey = (0, import_react4.useMemo)(
-      () => JSON.stringify(roomState.joinMeta ?? null),
+      () => safeJsonKey(roomState.joinMeta ?? null),
       [roomState.joinMeta]
     );
     const leaveMetaKey = (0, import_react4.useMemo)(
-      () => JSON.stringify(roomState.leaveMeta ?? null),
+      () => safeJsonKey(roomState.leaveMeta ?? null),
       [roomState.leaveMeta]
     );
+    const hasClient = !!client;
+    if (clientReadyRef.current !== hasClient) {
+      clientReadyRef.current = hasClient;
+      dbg2(debug, {
+        type: "client",
+        phase: hasClient ? "ready" : "missing",
+        err: hasClient ? void 0 : String(socketClientError)
+      });
+    }
+    dbg2(debug, {
+      type: "render",
+      renderCount: renderCountRef.current,
+      hasClient,
+      argsKey,
+      rooms: roomState.rooms,
+      roomsKey,
+      joinMetaKey,
+      leaveMetaKey
+    });
     (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: onReceiveEffectDebugRef,
+        phase: "endpoint_on_receive_effect",
+        debug,
+        snapshot: {
+          endpointResultRef: describeObjectReference(endpointResult),
+          endpointDataRef: describeObjectReference(endpointResult.data),
+          toRoomsRef: describeObjectReference(toRooms)
+        }
+      });
       const unsubscribe = endpointResult.onReceive((data) => {
-        setRoomState(
-          (prev) => mergeRoomState(prev, toRooms(data))
-        );
+        setRoomState((prev) => {
+          const next = mergeRoomState(prev, toRooms(data));
+          return roomStateEqual(prev, next) ? prev : next;
+        });
       });
       return unsubscribe;
-    }, [endpointResult, toRooms]);
+    }, [endpointResult, toRooms, debug]);
     (0, import_react4.useEffect)(() => {
-      setRoomState(
-        roomsFromData(endpointResult.data, toRooms)
+      trackHookTrigger2({
+        ref: deriveRoomsEffectDebugRef,
+        phase: "derive_rooms_effect",
+        debug,
+        snapshot: {
+          endpointDataRef: describeObjectReference(endpointResult.data),
+          toRoomsRef: describeObjectReference(toRooms)
+        }
+      });
+      const next = roomsFromData(
+        endpointResult.data,
+        toRooms
       );
-    }, [endpointResult.data, toRooms]);
+      setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
+    }, [endpointResult.data, toRooms, debug]);
     (0, import_react4.useEffect)(() => {
-      if (roomState.rooms.length === 0) return;
+      trackHookTrigger2({
+        ref: joinRoomsEffectDebugRef,
+        phase: "join_rooms_effect",
+        debug,
+        snapshot: {
+          hasClient: !!client,
+          clientRef: describeObjectReference(client),
+          roomsKey,
+          joinMetaKey,
+          leaveMetaKey
+        }
+      });
+      if (!client) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: roomState.rooms,
+          reason: "socket_client_missing"
+        });
+        return;
+      }
+      if (roomState.rooms.length === 0) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: [],
+          reason: "no_rooms"
+        });
+        return;
+      }
       const { joinMeta, leaveMeta } = roomState;
-      if (!joinMeta || !leaveMeta) return;
+      if (!joinMeta || !leaveMeta) {
+        dbg2(debug, {
+          type: "room",
+          phase: "join_skip",
+          rooms: roomState.rooms,
+          reason: "missing_meta"
+        });
+        return;
+      }
       let active = true;
+      dbg2(debug, {
+        type: "room",
+        phase: "join_attempt",
+        rooms: roomState.rooms
+      });
       (async () => {
         try {
           await client.joinRooms(roomState.rooms, joinMeta);
-        } catch {
+        } catch (err) {
+          dbg2(debug, {
+            type: "room",
+            phase: "join_error",
+            rooms: roomState.rooms,
+            err: String(err)
+          });
         }
       })();
       return () => {
-        if (!active || roomState.rooms.length === 0) return;
+        if (!active) return;
         active = false;
-        void client.leaveRooms(roomState.rooms, leaveMeta).catch(() => {
+        if (roomState.rooms.length === 0) {
+          dbg2(debug, {
+            type: "room",
+            phase: "leave_skip",
+            rooms: [],
+            reason: "no_rooms"
+          });
+          return;
+        }
+        dbg2(debug, {
+          type: "room",
+          phase: "leave_attempt",
+          rooms: roomState.rooms
+        });
+        void client.leaveRooms(roomState.rooms, leaveMeta).catch((err) => {
+          dbg2(debug, {
+            type: "room",
+            phase: "leave_error",
+            rooms: roomState.rooms,
+            err: String(err)
+          });
         });
       };
-    }, [
-      client,
-      roomsKey,
-      roomState.joinMeta,
-      roomState.leaveMeta,
-      joinMetaKey,
-      leaveMetaKey
-    ]);
+    }, [client, roomsKey, joinMetaKey, leaveMetaKey, debug]);
     (0, import_react4.useEffect)(() => {
+      trackHookTrigger2({
+        ref: applySocketEffectDebugRef,
+        phase: "apply_socket_effect",
+        debug,
+        snapshot: {
+          hasClient: !!client,
+          clientRef: describeObjectReference(client),
+          applySocketKeys: Object.keys(applySocket).sort().join(","),
+          argsKey,
+          toRoomsRef: describeObjectReference(toRooms)
+        }
+      });
+      if (!client) return;
+      const queue = [];
+      let draining = false;
+      let active = true;
+      const drainQueue = () => {
+        if (!active || draining) return;
+        draining = true;
+        try {
+          while (active && queue.length > 0) {
+            const nextUpdate = queue.shift();
+            if (!nextUpdate) continue;
+            built.setData(
+              (prev) => {
+                const next = nextUpdate.fn(
+                  prev,
+                  nextUpdate.payload,
+                  nextUpdate.meta ? { ...nextUpdate.meta, args: useArgs } : { args: useArgs }
+                );
+                const nextRoomState = roomsFromData(
+                  next,
+                  toRooms
+                );
+                setRoomState(
+                  (prevRoomState) => roomStateEqual(prevRoomState, nextRoomState) ? prevRoomState : nextRoomState
+                );
+                return next;
+              },
+              ...useArgs
+            );
+          }
+        } finally {
+          draining = false;
+          if (active && queue.length > 0) drainQueue();
+        }
+      };
       const entries = Object.entries(applySocket).filter(
         ([_event, fn]) => typeof fn === "function"
       );
       const unsubscribes = entries.map(
         ([ev, fn]) => client.on(ev, (payload, meta) => {
-          built.setData(
-            (prev) => {
-              const next = fn(prev, payload, meta);
-              setRoomState(
-                roomsFromData(next, toRooms)
-              );
-              return next;
-            },
-            ...useArgs
-          );
+          queue.push({
+            fn,
+            payload,
+            ...meta ? { meta } : {}
+          });
+          drainQueue();
         })
       );
-      return () => unsubscribes.forEach((u) => u?.());
-    }, [client, applySocket, built, argsKey, toRooms]);
+      return () => {
+        active = false;
+        queue.length = 0;
+        unsubscribes.forEach((u) => u?.());
+      };
+    }, [client, applySocket, built, argsKey, toRooms, debug]);
     return { ...endpointResult, rooms: roomState.rooms };
   };
   return {
@@ -2245,9 +2496,9 @@ var SocketClient = class {
       };
     }
     const socket = this.socket;
-    const wrapped = (envelopeOrRaw) => {
-      const maybeEnvelope = envelopeOrRaw;
-      const rawData = maybeEnvelope?.data ?? maybeEnvelope;
+    const toStringList = (value) => Array.isArray(value) ? value.filter((entry2) => typeof entry2 === "string") : [];
+    const wrappedEnv = (envelope) => {
+      const rawData = envelope.data;
       const parsed = schema.safeParse(rawData);
       if (!parsed.success) {
         this.dbg({
@@ -2258,15 +2509,17 @@ var SocketClient = class {
         });
         return;
       }
+      const data = parsed.data;
       const receivedAt = /* @__PURE__ */ new Date();
-      const sentAt = maybeEnvelope?.sentAt ? new Date(maybeEnvelope.sentAt) : void 0;
+      const sentAt = envelope?.sentAt ? new Date(envelope.sentAt) : void 0;
       const meta = {
         envelope: {
-          eventName: maybeEnvelope?.eventName ?? event,
-          sentAt: maybeEnvelope?.sentAt ?? receivedAt.toISOString(),
-          sentTo: maybeEnvelope?.sentTo ?? [],
-          data: void 0,
-          metadata: maybeEnvelope?.metadata
+          eventName: typeof envelope?.eventName === "string" ? envelope.eventName : event,
+          sentAt: envelope?.sentAt ?? receivedAt.toISOString(),
+          sentTo: toStringList(envelope?.sentTo),
+          data,
+          metadata: envelope?.metadata,
+          rooms: toStringList(envelope?.rooms)
         },
         ctx: {
           receivedAt,
@@ -2286,22 +2539,38 @@ var SocketClient = class {
           metadata: meta.envelope.metadata
         } : void 0
       });
-      handler(parsed.data, meta);
+      handler(data, meta);
+    };
+    const wrappedDispatcher = (envelopeOrRaw) => {
+      if (typeof envelopeOrRaw === "object" && envelopeOrRaw !== null && "eventName" in envelopeOrRaw && "sentAt" in envelopeOrRaw && "sentTo" in envelopeOrRaw && "data" in envelopeOrRaw) {
+        wrappedEnv(envelopeOrRaw);
+      } else {
+        this.dbg({
+          type: "receive",
+          event,
+          envelope: void 0
+        });
+        handler(envelopeOrRaw, void 0);
+      }
     };
     const errorWrapped = (e) => {
       this.dbg({ type: "receive", event, err: String(e) });
     };
-    socket.on(String(event), wrapped);
+    socket.on(String(event), wrappedDispatcher);
     socket.on(`${String(event)}:error`, errorWrapped);
     let set = this.handlerMap.get(String(event));
     if (!set) {
       set = /* @__PURE__ */ new Set();
       this.handlerMap.set(String(event), set);
     }
-    const entry = { orig: handler, wrapped, errorWrapped };
+    const entry = {
+      orig: handler,
+      wrapped: wrappedDispatcher,
+      errorWrapped
+    };
     set.add(entry);
     return () => {
-      socket.off(String(event), wrapped);
+      socket.off(String(event), wrappedDispatcher);
       socket.off(`${String(event)}:error`, errorWrapped);
       const s = this.handlerMap.get(String(event));
       if (s) {