@emeryld/rrroutes-client 2.6.6 → 2.6.8

package/dist/index.mjs

@@ -1,5 +1,12 @@
 "use client";
 
+// src/routesV3.client.ts
+import {
+  lowProfileParse as lowProfileParse5
+} from "@emeryld/rrroutes-contract";
+import { keepPreviousData as keepPreviousData3, useQuery as useQuery2 } from "@tanstack/react-query";
+import { useCallback as useCallback4, useRef as useRef4 } from "react";
+
 // src/routesV3.client.fetch.ts
 var HttpError = class extends Error {
   constructor({
@@ -1095,6 +1102,7 @@ function buildMutationLeaf(leaf, rqOpts, env) {
 }
 
 // src/routesV3.client.ts
+var BUILT_LEAF_META = "__rrroutesLeaf";
 var defaultDebugLogger = (event) => {
   if (typeof console === "undefined") return;
   const fn = console.debug ?? console.log;
@@ -1161,6 +1169,7 @@ function createRouteClient(opts) {
   const fetcher = opts.fetcher ?? defaultFetcher;
   const baseUrl = opts.baseUrl;
   const environment = opts.environment ?? void 0;
+  const validateResponses = opts.validateResponses ?? true;
   const { emit: emitDebug, mode: debugMode } = createDebugEmitter(
     opts.debug,
     environment
@@ -1175,13 +1184,23 @@ function createRouteClient(opts) {
     await queryClient.invalidateQueries({ queryKey, exact });
     emitDebug({ type: "invalidate", key: queryKey, exact });
   }
+  const toArgsTuple2 = (args) => typeof args === "undefined" ? [] : [args];
+  const getBuiltLeaf = (built) => {
+    const leaf = built[BUILT_LEAF_META];
+    if (!leaf) {
+      throw new Error(
+        "buildBranch(...) expects endpoints created with this route client via client.build(...)."
+      );
+    }
+    return leaf;
+  };
+  const encodeLeafKey = (leaf) => encodeURIComponent(`${leaf.method.toUpperCase()} ${leaf.path}`);
   function buildInternal(leaf, rqOpts, meta) {
     const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
     const debugName = meta?.name;
     const emit = (event) => emitDebug(event, debugName);
     const isGet = leaf.method === "get";
     const isFeed = !!leaf.cfg.feed;
-    const validateResponses = opts.validateResponses ?? true;
     const env = {
       baseUrl,
       validateResponses,
@@ -1192,25 +1211,33 @@ function createRouteClient(opts) {
       isVerboseDebug,
       leafLabel
     };
+    let built;
     if (isGet && isFeed) {
-      return buildInfiniteGetLeaf(
+      built = buildInfiniteGetLeaf(
         leaf,
         rqOpts,
         env
       );
-    }
-    if (isGet) {
-      return buildGetLeaf(
+    } else if (isGet) {
+      built = buildGetLeaf(
+        leaf,
+        rqOpts,
+        env
+      );
+    } else {
+      built = buildMutationLeaf(
         leaf,
         rqOpts,
         env
       );
     }
-    return buildMutationLeaf(
-      leaf,
-      rqOpts,
-      env
-    );
+    Object.defineProperty(built, BUILT_LEAF_META, {
+      value: leaf,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return built;
   }
   const fetchRaw = async (input) => {
     const { path, method, query, body, params } = input;
@@ -1279,11 +1306,151 @@ function createRouteClient(opts) {
       throw error;
     }
   };
+  const buildBranchInternal = (leaves, options) => {
+    const batchMethod = options.method ?? "POST";
+    const defaultHeaders = options.headers;
+    const getQueryKeys = (input) => {
+      const out = {};
+      const argsByLeaf = input ?? {};
+      for (const [alias, built] of Object.entries(leaves)) {
+        const args = argsByLeaf[alias];
+        out[alias] = built.getQueryKeys(...toArgsTuple2(args));
+      }
+      return out;
+    };
+    const invalidateBranch = async (input) => {
+      const argsByLeaf = input ?? {};
+      await Promise.all(
+        Object.entries(leaves).map(([alias, built]) => {
+          const args = argsByLeaf[alias];
+          return built.invalidate(...toArgsTuple2(args));
+        })
+      );
+    };
+    const setDataBranch = (input) => {
+      const out = {};
+      for (const [alias, def] of Object.entries(input)) {
+        if (!def) continue;
+        const built = leaves[alias];
+        if (!built) continue;
+        out[alias] = built.setData(
+          def.updater,
+          ...toArgsTuple2(def.args)
+        );
+      }
+      return out;
+    };
+    const fetchBranch = async (input) => {
+      const payload = {};
+      const keyByAlias = /* @__PURE__ */ new Map();
+      for (const [aliasRaw, built] of Object.entries(leaves)) {
+        const alias = aliasRaw;
+        const leaf = getBuiltLeaf(built);
+        const encodedLeaf = encodeLeafKey(leaf);
+        keyByAlias.set(alias, encodedLeaf);
+        const branchInput = input[alias];
+        const args = branchInput?.args;
+        const body = branchInput?.body;
+        payload[encodedLeaf] = {
+          ...args?.params !== void 0 ? { params: args.params } : {},
+          ...args?.query !== void 0 ? { query: args.query } : {},
+          ...body !== void 0 ? { body } : {}
+        };
+      }
+      const batchResponse = await fetchRaw({
+        path: options.path,
+        method: batchMethod,
+        body: payload,
+        headers: defaultHeaders
+      });
+      const rawData = batchResponse.data;
+      if (!rawData || typeof rawData !== "object" || Array.isArray(rawData)) {
+        throw new Error(
+          "Batch response must be a plain object keyed by encoded route keys."
+        );
+      }
+      const mapped = {};
+      for (const [aliasRaw, built] of Object.entries(leaves)) {
+        const alias = aliasRaw;
+        const encodedLeaf = keyByAlias.get(alias);
+        if (!encodedLeaf) {
+          throw new Error(
+            `Internal batch error: missing encoded key for alias "${String(alias)}".`
+          );
+        }
+        if (!(encodedLeaf in rawData)) {
+          throw new Error(`Batch response missing key "${encodedLeaf}".`);
+        }
+        const leaf = getBuiltLeaf(built);
+        const rawLeafData = rawData[encodedLeaf];
+        const parsedLeafData = validateResponses && leaf.cfg.outputSchema ? lowProfileParse5(leaf.cfg.outputSchema, rawLeafData) : rawLeafData;
+        if (validateResponses && !leaf.cfg.outputSchema) {
+          throw new Error(
+            `No output schema defined for leaf ${leaf.method.toUpperCase()} ${leaf.path}, cannot validate batch response.`
+          );
+        }
+        ;
+        mapped[aliasRaw] = parsedLeafData;
+      }
+      return mapped;
+    };
+    const useEndpoint = (input, rqOpts) => {
+      const queryKeys = getQueryKeys(input);
+      const branchQueryKey = [
+        "batch",
+        String(batchMethod).toLowerCase(),
+        options.path,
+        queryKeys
+      ];
+      const { onReceive, ...useQueryOptions } = rqOpts ?? {};
+      const listenersRef = useRef4(
+        /* @__PURE__ */ new Set()
+      );
+      const notifyOnReceive = useCallback4(
+        (data) => {
+          onReceive?.(data);
+          listenersRef.current.forEach((listener) => listener(data));
+        },
+        [onReceive]
+      );
+      const registerOnReceive = useCallback4(
+        (listener) => {
+          listenersRef.current.add(listener);
+          return () => {
+            listenersRef.current.delete(listener);
+          };
+        },
+        []
+      );
+      const queryResult = useQuery2(
+        {
+          ...useQueryOptions,
+          queryKey: branchQueryKey,
+          placeholderData: useQueryOptions.placeholderData ?? keepPreviousData3,
+          queryFn: async () => {
+            const result = await fetchBranch(input);
+            notifyOnReceive(result);
+            return result;
+          }
+        },
+        queryClient
+      );
+      return { ...queryResult, onReceive: registerOnReceive };
+    };
+    return {
+      fetch: fetchBranch,
+      useEndpoint,
+      getQueryKeys,
+      invalidate: invalidateBranch,
+      setData: setDataBranch
+    };
+  };
   return {
     queryClient,
     invalidate,
     fetch: fetchRaw,
-    build: buildInternal
+    build: buildInternal,
+    buildBranch: buildBranchInternal
   };
 }
 function buildRouter(routeClient, routes) {
@@ -1295,6 +1462,168 @@ function buildRouter(routeClient, routes) {
   ));
 }
 
+// src/sockets/socket.client.context.provider.tsx
+import * as React3 from "react";
+
+// src/sockets/socket.client.context.client.ts
+import * as React from "react";
+var SocketCtx = React.createContext(null);
+function useSocketClient() {
+  const ctx = React.useContext(SocketCtx);
+  if (!ctx)
+    throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
+  return ctx;
+}
+
+// src/sockets/socket.client.context.connection.ts
+import * as React2 from "react";
+function useSocketConnection(args) {
+  const {
+    event,
+    rooms,
+    onMessage,
+    onCleanup,
+    autoJoin = true,
+    autoLeave = true
+  } = args;
+  const client = useSocketClient();
+  const normalizedRooms = React2.useMemo(
+    () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
+    [rooms]
+  );
+  const reportAsyncError = React2.useCallback(
+    (phase, error) => {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`[socket] useSocketConnection ${phase} failed`, error);
+      }
+    },
+    []
+  );
+  React2.useEffect(() => {
+    if (autoJoin && normalizedRooms.length > 0)
+      void client.joinRooms(normalizedRooms, args.joinMeta).catch((error) => reportAsyncError("joinRooms", error));
+    const unsubscribe = client.on(event, (payload, meta) => {
+      onMessage(payload, meta);
+    });
+    return () => {
+      unsubscribe();
+      if (autoLeave && normalizedRooms.length > 0)
+        void client.leaveRooms(normalizedRooms, args.leaveMeta).catch((error) => reportAsyncError("leaveRooms", error));
+      if (onCleanup) onCleanup();
+    };
+  }, [
+    client,
+    event,
+    onMessage,
+    autoJoin,
+    autoLeave,
+    reportAsyncError,
+    ...normalizedRooms
+  ]);
+}
+
+// src/sockets/socket.client.context.debug.ts
+function dbg(dbgOpts, e) {
+  if (!dbgOpts?.logger) return;
+  if (!dbgOpts[e.type]) return;
+  try {
+    dbgOpts.logger(e);
+  } catch (error) {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+      console.warn("[socket] provider debug logger threw", error);
+    }
+  }
+}
+function isProbablySocket(value) {
+  if (!value || typeof value !== "object") return false;
+  const anyVal = value;
+  const ctorName = anyVal.constructor?.name;
+  if (ctorName === "Socket") return true;
+  return ("connected" in anyVal || "recovered" in anyVal) && typeof anyVal.on === "function" && typeof anyVal.emit === "function";
+}
+function describeSocketLike(value) {
+  if (!value) return null;
+  const id = value.id ?? "unknown";
+  const connected = value.connected ?? false;
+  const recovered = typeof value.recovered === "boolean" ? ` recovered=${value.recovered}` : "";
+  return `[Socket id=${id} connected=${connected}${recovered}]`;
+}
+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 (isProbablySocket(value)) return describeSocketLike(value);
+  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 summarizeEvents(events) {
+  if (!events || typeof events !== "object")
+    return safeDescribeHookValue(events);
+  const keys = Object.keys(events);
+  if (!keys.length) return "[events empty]";
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[events count=${keys.length} keys=${preview}${suffix}]`;
+}
+function summarizeBaseOptions(options) {
+  if (!options || typeof options !== "object")
+    return safeDescribeHookValue(options);
+  const obj = options;
+  const keys = Object.keys(obj);
+  if (!keys.length) return "[baseOptions empty]";
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  const hasDebug = "debug" in obj;
+  return `[baseOptions keys=${preview}${suffix} debug=${hasDebug}]`;
+}
+function summarizeMeta(meta, label) {
+  if (meta == null) return null;
+  if (typeof meta !== "object") return safeDescribeHookValue(meta);
+  const keys = Object.keys(meta);
+  if (!keys.length) return `[${label} empty]`;
+  const preview = keys.slice(0, 4).join(",");
+  const suffix = keys.length > 4 ? ",\u2026" : "";
+  return `[${label} keys=${preview}${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", phase: 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);
+}
+
 // src/sockets/socket.client.sys.ts
 import { z } from "zod";
 var roomValueSchema = z.union([z.array(z.string()), z.string()]);
@@ -2098,168 +2427,6 @@ var SocketClient = class {
   }
 };
 
-// src/sockets/socket.client.context.provider.tsx
-import * as React3 from "react";
-
-// src/sockets/socket.client.context.client.ts
-import * as React from "react";
-var SocketCtx = React.createContext(null);
-function useSocketClient() {
-  const ctx = React.useContext(SocketCtx);
-  if (!ctx)
-    throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
-  return ctx;
-}
-
-// src/sockets/socket.client.context.connection.ts
-import * as React2 from "react";
-function useSocketConnection(args) {
-  const {
-    event,
-    rooms,
-    onMessage,
-    onCleanup,
-    autoJoin = true,
-    autoLeave = true
-  } = args;
-  const client = useSocketClient();
-  const normalizedRooms = React2.useMemo(
-    () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
-    [rooms]
-  );
-  const reportAsyncError = React2.useCallback(
-    (phase, error) => {
-      if (typeof console !== "undefined" && typeof console.warn === "function") {
-        console.warn(`[socket] useSocketConnection ${phase} failed`, error);
-      }
-    },
-    []
-  );
-  React2.useEffect(() => {
-    if (autoJoin && normalizedRooms.length > 0)
-      void client.joinRooms(normalizedRooms, args.joinMeta).catch((error) => reportAsyncError("joinRooms", error));
-    const unsubscribe = client.on(event, (payload, meta) => {
-      onMessage(payload, meta);
-    });
-    return () => {
-      unsubscribe();
-      if (autoLeave && normalizedRooms.length > 0)
-        void client.leaveRooms(normalizedRooms, args.leaveMeta).catch((error) => reportAsyncError("leaveRooms", error));
-      if (onCleanup) onCleanup();
-    };
-  }, [
-    client,
-    event,
-    onMessage,
-    autoJoin,
-    autoLeave,
-    reportAsyncError,
-    ...normalizedRooms
-  ]);
-}
-
-// src/sockets/socket.client.context.debug.ts
-function dbg(dbgOpts, e) {
-  if (!dbgOpts?.logger) return;
-  if (!dbgOpts[e.type]) return;
-  try {
-    dbgOpts.logger(e);
-  } catch (error) {
-    if (typeof console !== "undefined" && typeof console.warn === "function") {
-      console.warn("[socket] provider debug logger threw", error);
-    }
-  }
-}
-function isProbablySocket(value) {
-  if (!value || typeof value !== "object") return false;
-  const anyVal = value;
-  const ctorName = anyVal.constructor?.name;
-  if (ctorName === "Socket") return true;
-  return ("connected" in anyVal || "recovered" in anyVal) && typeof anyVal.on === "function" && typeof anyVal.emit === "function";
-}
-function describeSocketLike(value) {
-  if (!value) return null;
-  const id = value.id ?? "unknown";
-  const connected = value.connected ?? false;
-  const recovered = typeof value.recovered === "boolean" ? ` recovered=${value.recovered}` : "";
-  return `[Socket id=${id} connected=${connected}${recovered}]`;
-}
-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 (isProbablySocket(value)) return describeSocketLike(value);
-  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 summarizeEvents(events) {
-  if (!events || typeof events !== "object")
-    return safeDescribeHookValue(events);
-  const keys = Object.keys(events);
-  if (!keys.length) return "[events empty]";
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  return `[events count=${keys.length} keys=${preview}${suffix}]`;
-}
-function summarizeBaseOptions(options) {
-  if (!options || typeof options !== "object")
-    return safeDescribeHookValue(options);
-  const obj = options;
-  const keys = Object.keys(obj);
-  if (!keys.length) return "[baseOptions empty]";
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  const hasDebug = "debug" in obj;
-  return `[baseOptions keys=${preview}${suffix} debug=${hasDebug}]`;
-}
-function summarizeMeta(meta, label) {
-  if (meta == null) return null;
-  if (typeof meta !== "object") return safeDescribeHookValue(meta);
-  const keys = Object.keys(meta);
-  if (!keys.length) return `[${label} empty]`;
-  const preview = keys.slice(0, 4).join(",");
-  const suffix = keys.length > 4 ? ",\u2026" : "";
-  return `[${label} keys=${preview}${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", phase: 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);
-}
-
 // src/sockets/socket.client.context.provider.tsx
 import { jsx } from "react/jsx-runtime";
 function buildSocketProvider(args) {
@@ -2402,7 +2569,7 @@ function SocketProvider(props) {
 }
 
 // src/sockets/socketedRoute/socket.client.helper.route.ts
-import { useEffect as useEffect3, useMemo as useMemo3, useRef as useRef5, useState as useState2 } from "react";
+import { useEffect as useEffect3, useMemo as useMemo3, useRef as useRef6, useState as useState2 } from "react";
 
 // src/sockets/socketedRoute/socket.client.helper.debug.ts
 var objectReferenceIds = /* @__PURE__ */ new WeakMap();
@@ -2574,13 +2741,19 @@ function buildSocketedRoute(options) {
     const [roomState, setRoomState] = useState2(
       () => roomsFromData(endpointResult.data, toRooms)
     );
-    const renderCountRef = useRef5(0);
-    const clientReadyRef = useRef5(null);
-    const onReceiveEffectDebugRef = useRef5(null);
-    const deriveRoomsEffectDebugRef = useRef5(null);
-    const joinRoomsEffectDebugRef = useRef5(null);
-    const applySocketEffectDebugRef = useRef5(null);
+    const renderCountRef = useRef6(0);
+    const clientReadyRef = useRef6(null);
+    const endpointDataRef = useRef6(
+      endpointResult.data
+    );
+    const toRoomsRef = useRef6(toRooms);
+    const onReceiveEffectDebugRef = useRef6(null);
+    const deriveRoomsEffectDebugRef = useRef6(null);
+    const joinRoomsEffectDebugRef = useRef6(null);
+    const applySocketEffectDebugRef = useRef6(null);
     renderCountRef.current += 1;
+    endpointDataRef.current = endpointResult.data;
+    toRoomsRef.current = toRooms;
     const roomsKey = useMemo3(() => roomState.rooms.join("|"), [roomState.rooms]);
     const joinMetaKey = useMemo3(
       () => safeJsonKey(roomState.joinMeta ?? null),
@@ -2615,35 +2788,31 @@ function buildSocketedRoute(options) {
         phase: "endpoint_on_receive_effect",
         debug,
         snapshot: {
-          endpointResultRef: describeObjectReference(endpointResult),
-          endpointDataRef: describeObjectReference(endpointResult.data),
-          toRoomsRef: describeObjectReference(toRooms)
+          onReceiveRef: describeObjectReference(endpointResult.onReceive)
         }
       });
       const unsubscribe = endpointResult.onReceive((data) => {
         setRoomState((prev) => {
-          const next = mergeRoomState(prev, toRooms(data));
+          const next = mergeRoomState(prev, toRoomsRef.current(data));
           return roomStateEqual(prev, next) ? prev : next;
         });
       });
       return unsubscribe;
-    }, [endpointResult, toRooms, debug]);
+    }, [endpointResult.onReceive]);
     useEffect3(() => {
       trackHookTrigger2({
         ref: deriveRoomsEffectDebugRef,
         phase: "derive_rooms_effect",
         debug,
         snapshot: {
-          endpointDataRef: describeObjectReference(endpointResult.data),
+          argsKey,
+          endpointDataRef: describeObjectReference(endpointDataRef.current),
           toRoomsRef: describeObjectReference(toRooms)
         }
       });
-      const next = roomsFromData(
-        endpointResult.data,
-        toRooms
-      );
+      const next = roomsFromData(endpointDataRef.current, toRooms);
       setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
-    }, [endpointResult.data, toRooms, debug]);
+    }, [argsKey, toRooms, debug]);
     useEffect3(() => {
       trackHookTrigger2({
         ref: joinRoomsEffectDebugRef,