@emeryld/rrroutes-client 2.7.12 → 2.8.0

package/dist/index.cjs

@@ -39,8 +39,7 @@ __export(index_exports, {
   buildSocketedRoute: () => buildSocketedRoute,
   createRouteClient: () => createRouteClient,
   defaultFetcher: () => defaultFetcher,
-  useSocketClient: () => useSocketClient,
-  useSocketConnection: () => useSocketConnection
+  useSocketClient: () => useSocketClient
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1479,6 +1478,12 @@ function createRouteClient(opts) {
       configurable: false,
       writable: false
     });
+    Object.defineProperty(built, "metadata", {
+      value: { leaf },
+      enumerable: true,
+      configurable: false,
+      writable: false
+    });
     return built;
   }
   const fetchRaw = async (input) => {
@@ -1589,25 +1594,76 @@ function useSocketClient() {
 
 // src/sockets/socket.client.context.connection.ts
 var React2 = __toESM(require("react"), 1);
-function useSocketConnection(args) {
+function normalizeRooms(rooms) {
+  if (rooms == null) return [];
+  return Array.isArray(rooms) ? rooms : [rooms];
+}
+function safeSerialize(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function derivePayloadIdentity(payload) {
+  if (!payload || typeof payload !== "object") return void 0;
+  const record = payload;
+  const idCandidate = record.id ?? record._id ?? record.notificationId ?? record.uuid ?? record.key;
+  if (typeof idCandidate === "string" || typeof idCandidate === "number" || typeof idCandidate === "bigint") {
+    return String(idCandidate);
+  }
+  return void 0;
+}
+function useLatestRef(value) {
+  const ref = React2.useRef(value);
+  React2.useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+}
+function useDebugEmitter(debug) {
+  const debugRef = useLatestRef(debug);
+  return React2.useCallback((event) => {
+    const dbg3 = debugRef.current;
+    if (!dbg3?.enabled) return;
+    if (dbg3[event.type] === false) return;
+    const logger = dbg3.logger;
+    if (logger) {
+      try {
+        logger(event);
+      } catch (error) {
+        if (typeof console !== "undefined" && typeof console.warn === "function") {
+          console.warn("[socket] debug logger threw", error);
+        }
+      }
+      return;
+    }
+    if (typeof console !== "undefined" && typeof console.log === "function") {
+      console.log("[socket]", event);
+    }
+  }, []);
+}
+function useSocketRooms(args) {
   const {
-    event,
     rooms,
-    onMessage,
-    onCleanup,
     autoJoin = true,
     autoLeave = true,
+    enabled = true,
+    onCleanup,
     debug
   } = args;
   const client = useSocketClient();
-  const normalizedRooms = React2.useMemo(
-    () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
-    [rooms]
-  );
+  const normalizedRooms = React2.useMemo(() => normalizeRooms(rooms), [rooms]);
   const normalizedRoomsKey = React2.useMemo(
     () => normalizedRooms.join("
"),
     [normalizedRooms]
   );
+  const joinMetaRef = useLatestRef(args.joinMeta);
+  const leaveMetaRef = useLatestRef(args.leaveMeta);
+  const onCleanupRef = useLatestRef(onCleanup);
+  const debugRef = useLatestRef(debug);
+  const emitDebug = useDebugEmitter(debug);
+  const missingClientWarnedRef = React2.useRef(false);
   const joinMetaKey = React2.useMemo(
     () => JSON.stringify(args.joinMeta ?? null),
     [args.joinMeta]
@@ -1616,107 +1672,48 @@ function useSocketConnection(args) {
     () => JSON.stringify(args.leaveMeta ?? null),
     [args.leaveMeta]
   );
-  const missingClientWarnedRef = React2.useRef(false);
-  const onMessageRef = React2.useRef(onMessage);
-  const onCleanupRef = React2.useRef(onCleanup);
-  const joinMetaRef = React2.useRef(args.joinMeta);
-  const leaveMetaRef = React2.useRef(args.leaveMeta);
-  const debugRef = React2.useRef(debug);
-  React2.useEffect(() => {
-    onMessageRef.current = onMessage;
-  }, [onMessage]);
-  React2.useEffect(() => {
-    onCleanupRef.current = onCleanup;
-  }, [onCleanup]);
-  React2.useEffect(() => {
-    joinMetaRef.current = args.joinMeta;
-  }, [args.joinMeta]);
-  React2.useEffect(() => {
-    leaveMetaRef.current = args.leaveMeta;
-  }, [args.leaveMeta]);
-  React2.useEffect(() => {
-    debugRef.current = debug;
-  }, [debug]);
-  const emitDebug = React2.useCallback(
-    (event2) => {
-      const dbg3 = debugRef.current;
-      if (!dbg3?.enabled) return;
-      if (dbg3[event2.type] === false) return;
-      const logger = dbg3.logger;
-      if (logger) {
-        try {
-          logger(event2);
-        } catch (error) {
-          if (typeof console !== "undefined" && typeof console.warn === "function") {
-            console.warn("[socket] useSocketConnection debug logger threw", error);
-          }
-        }
-        return;
-      }
-      if (typeof console !== "undefined" && typeof console.log === "function") {
-        console.log("[socket] useSocketConnection", event2);
-      }
-    },
-    []
-  );
-  const reportAsyncError = React2.useCallback(
-    (phase, error) => {
-      if (typeof console !== "undefined" && typeof console.warn === "function") {
-        console.warn(`[socket] useSocketConnection ${phase} failed`, error);
-      }
-    },
-    []
-  );
   React2.useEffect(() => {
     emitDebug({
       type: "lifecycle",
       phase: "effect_start",
-      event,
       rooms: normalizedRooms,
       autoJoin,
       autoLeave
     });
+    if (!enabled) {
+      emitDebug({
+        type: "room",
+        phase: "join_skip",
+        rooms: normalizedRooms,
+        reason: "disabled"
+      });
+      return;
+    }
     if (!client) {
       emitDebug({
         type: "lifecycle",
         phase: "client_missing",
-        event,
         rooms: normalizedRooms,
         autoJoin,
         autoLeave
       });
-      if (debugRef.current?.throwIfClientMissing) {
-        throw new Error(
-          `useSocketConnection("${event}") missing SocketClient. Wrap with <SocketProvider>.`
-        );
-      }
       if (debugRef.current?.warnIfClientMissing && !missingClientWarnedRef.current && typeof console !== "undefined" && typeof console.warn === "function") {
         missingClientWarnedRef.current = true;
-        console.warn(
-          `[socket] useSocketConnection("${event}") skipped because SocketClient is null.`
-        );
+        console.warn("[socket] useSocketRooms skipped because SocketClient is null.");
       }
       return;
     }
     missingClientWarnedRef.current = false;
-    emitDebug({ type: "subscription", phase: "register", event });
     if (autoJoin && normalizedRooms.length > 0) {
-      emitDebug({
-        type: "room",
-        phase: "join_attempt",
-        rooms: normalizedRooms
-      });
-      void client.joinRooms(normalizedRooms, joinMetaRef.current).then(() => {
-        emitDebug({ type: "room", phase: "join_ok", rooms: normalizedRooms });
-      }).catch((error) => {
-        emitDebug({
+      emitDebug({ type: "room", phase: "join_attempt", rooms: normalizedRooms });
+      void client.joinRooms(normalizedRooms, joinMetaRef.current).then(() => emitDebug({ type: "room", phase: "join_ok", rooms: normalizedRooms })).catch(
+        (error) => emitDebug({
           type: "room",
           phase: "join_error",
           rooms: normalizedRooms,
           err: String(error)
-        });
-        reportAsyncError("joinRooms", error);
-      });
+        })
+      );
     } else {
       emitDebug({
         type: "room",
@@ -1725,30 +1722,23 @@ function useSocketConnection(args) {
         reason: autoJoin ? "no_rooms" : "auto_disabled"
       });
     }
-    const unsubscribe = client.on(event, (payload, meta) => {
-      emitDebug({ type: "subscription", phase: "message", event });
-      onMessageRef.current(payload, meta);
-    });
     return () => {
-      emitDebug({ type: "subscription", phase: "unregister", event });
-      unsubscribe();
       if (autoLeave && normalizedRooms.length > 0) {
         emitDebug({
           type: "room",
           phase: "leave_attempt",
           rooms: normalizedRooms
         });
-        void client.leaveRooms(normalizedRooms, leaveMetaRef.current).then(() => {
-          emitDebug({ type: "room", phase: "leave_ok", rooms: normalizedRooms });
-        }).catch((error) => {
-          emitDebug({
+        void client.leaveRooms(normalizedRooms, leaveMetaRef.current).then(
+          () => emitDebug({ type: "room", phase: "leave_ok", rooms: normalizedRooms })
+        ).catch(
+          (error) => emitDebug({
             type: "room",
             phase: "leave_error",
             rooms: normalizedRooms,
             err: String(error)
-          });
-          reportAsyncError("leaveRooms", error);
-        });
+          })
+        );
       } else {
         emitDebug({
           type: "room",
@@ -1757,11 +1747,10 @@ function useSocketConnection(args) {
           reason: autoLeave ? "no_rooms" : "auto_disabled"
         });
       }
-      if (onCleanupRef.current) onCleanupRef.current();
+      onCleanupRef.current?.();
       emitDebug({
         type: "lifecycle",
         phase: "effect_cleanup",
-        event,
         rooms: normalizedRooms,
         autoJoin,
         autoLeave
@@ -1769,16 +1758,79 @@ function useSocketConnection(args) {
     };
   }, [
     client,
-    event,
+    enabled,
     autoJoin,
     autoLeave,
-    emitDebug,
-    reportAsyncError,
     normalizedRoomsKey,
     joinMetaKey,
-    leaveMetaKey
+    leaveMetaKey,
+    emitDebug
   ]);
 }
+function useSocketEvent(args) {
+  const {
+    event,
+    onMessage,
+    onCleanup,
+    enabled = true,
+    messageDeduplication,
+    debug
+  } = args;
+  const client = useSocketClient();
+  const onMessageRef = useLatestRef(onMessage);
+  const onCleanupRef = useLatestRef(onCleanup);
+  const messageDeduplicationRef = useLatestRef(messageDeduplication);
+  const debugRef = useLatestRef(debug);
+  const emitDebug = useDebugEmitter(debug);
+  const missingClientWarnedRef = React2.useRef(false);
+  const seenMessageKeysRef = React2.useRef(/* @__PURE__ */ new Map());
+  React2.useEffect(() => {
+    emitDebug({ type: "lifecycle", phase: "effect_start", event });
+    if (!enabled) return;
+    if (!client) {
+      emitDebug({ type: "lifecycle", phase: "client_missing", event });
+      if (debugRef.current?.warnIfClientMissing && !missingClientWarnedRef.current && typeof console !== "undefined" && typeof console.warn === "function") {
+        missingClientWarnedRef.current = true;
+        console.warn(`[socket] useSocketEvent("${event}") skipped because SocketClient is null.`);
+      }
+      return;
+    }
+    missingClientWarnedRef.current = false;
+    emitDebug({ type: "subscription", phase: "register", event });
+    const unsubscribe = client.on(event, (payload, meta) => {
+      const dedupeCfg = messageDeduplicationRef.current;
+      if (dedupeCfg !== false) {
+        const ttlMs = Math.max(0, dedupeCfg?.ttlMs ?? 2500);
+        const now = Date.now();
+        const payloadId = derivePayloadIdentity(payload);
+        const dedupeKey = dedupeCfg?.key?.(payload, meta) ?? (payloadId ? `${event}|payload:${payloadId}` : void 0) ?? (meta?.envelope ? `${event}|${String(meta.envelope.eventName)}|${String(meta.envelope.sentAt)}|${safeSerialize(payload)}` : `${event}|${safeSerialize(payload)}`);
+        const prev = seenMessageKeysRef.current.get(dedupeKey);
+        if (typeof prev === "number" && now - prev <= ttlMs) {
+          emitDebug({
+            type: "subscription",
+            phase: "message_dropped_duplicate",
+            event,
+            dedupeKey
+          });
+          return;
+        }
+        seenMessageKeysRef.current.set(dedupeKey, now);
+      }
+      emitDebug({ type: "subscription", phase: "message", event });
+      onMessageRef.current(payload, meta);
+    });
+    return () => {
+      emitDebug({ type: "subscription", phase: "unregister", event });
+      unsubscribe();
+      onCleanupRef.current?.();
+      emitDebug({ type: "lifecycle", phase: "effect_cleanup", event });
+    };
+  }, [client, enabled, event, emitDebug]);
+}
+function useSocketConnection(roomsArgs, eventArgs) {
+  useSocketRooms(roomsArgs);
+  useSocketEvent(eventArgs);
+}
 
 // src/sockets/socket.client.context.debug.ts
 function dbg(dbgOpts, e) {
@@ -2700,7 +2752,9 @@ function buildSocketProvider(args) {
       }
     ),
     useSocketClient: () => useSocketClient(),
-    useSocketConnection: (p) => useSocketConnection(p)
+    useSocketRooms: (p) => useSocketRooms(p),
+    useSocketEvent: (p) => useSocketEvent(p),
+    useSocketConnection: (...args2) => useSocketConnection(...args2)
   };
 }
 function SocketProvider(props) {
@@ -2915,7 +2969,7 @@ function trackHookTrigger2({
 }
 
 // src/sockets/socketedRoute/socket.client.helper.rooms.ts
-function normalizeRooms(rooms) {
+function normalizeRooms2(rooms) {
   if (rooms == null) return [];
   const list = Array.isArray(rooms) ? rooms : [rooms];
   const seen = /* @__PURE__ */ new Set();
@@ -2940,7 +2994,7 @@ function roomStateEqual(prev, next) {
 }
 function mergeRoomState(prev, toRoomsResult) {
   const merged = new Set(prev.rooms);
-  for (const r of normalizeRooms(toRoomsResult.rooms)) merged.add(r);
+  for (const r of normalizeRooms2(toRoomsResult.rooms)) merged.add(r);
   return {
     rooms: Array.from(merged),
     joinMeta: toRoomsResult.joinMeta ?? prev.joinMeta,
@@ -3301,7 +3355,6 @@ function buildSocketedRoute(options) {
   buildSocketedRoute,
   createRouteClient,
   defaultFetcher,
-  useSocketClient,
-  useSocketConnection
+  useSocketClient
 });
 //# sourceMappingURL=index.cjs.map