@emeryld/rrroutes-client 2.6.5 → 2.6.7

package/README.md

@@ -1,7 +1,7 @@
 <!--
 Summary:
 - Added comprehensive usage for `createRouteClient`, built endpoints (GET/feeds/mutations), cache helpers, invalidation, debug modes, custom fetchers, and React Query integration.
-- Added new sections for router helpers, infinite/feeds, FormData uploads, and socket utilities (SocketClient, provider hooks, socketed routes).
+- Added new sections for router helpers, batched branches (`buildBranch`), infinite/feeds, FormData uploads, and socket utilities (SocketClient, provider hooks, socketed routes).
 - Removed the sparse README and outdated publishing script focus; future additions should cover server-side Socket.IO envelope expectations and testing recipes for hooks.
 -->
 
@@ -220,7 +220,53 @@ const listUsers = buildRoute('listUsers') // builds from routes.listUsers
 const updateUser = buildRoute('updateUser', {}, { name: 'profile' }) // debug name filtering
 ```
 
-### 8) File uploads (FormData)
+### 8) Batch multiple built endpoints (`buildBranch`)
+
+`buildBranch` lets you batch already-built endpoints behind one batch path.
+
+```ts
+const getUser = client.build(registry.byKey['GET /v1/users/:userId'])
+const updateUser = client.build(registry.byKey['PATCH /v1/users/:userId'])
+
+const userBatch = client.buildBranch(
+  { getUser, updateUser },
+  { path: '/v1/batch', method: 'post' }, // method defaults to POST
+)
+
+const result = await userBatch.fetch({
+  getUser: {
+    args: { params: { userId: 'u_1' } },
+  },
+  updateUser: {
+    args: { params: { userId: 'u_1' } },
+    body: { name: 'Emery' }, // required for mutation leaves
+  },
+})
+
+// result keys map back to your aliases:
+// { getUser: ..., updateUser: ... }
+```
+
+The request body sent to `/v1/batch` is keyed by URL-encoded leaf keys:
+
+```ts
+{
+  [encodeURIComponent('GET /v1/users/:userId')]: { params: { userId: 'u_1' } },
+  [encodeURIComponent('PATCH /v1/users/:userId')]: {
+    params: { userId: 'u_1' },
+    body: { name: 'Emery' },
+  },
+}
+```
+
+`buildBranch` also provides:
+
+- `useEndpoint(input, options?)` for a single React Query hook over the batched response.
+- `getQueryKeys(input?)` to derive per-alias keys.
+- `invalidate(input?)` to invalidate each leaf alias exactly.
+- `setData(input)` to write cache per alias.
+
+### 9) File uploads (FormData)
 
 If a leaf has `bodyFiles` set in its contract, the client automatically converts the body to `FormData`.
 For each declared file field name, pass files using `file${name}` in the input body.
@@ -251,7 +297,7 @@ await uploadAvatar.fetch(
 )
 ```
 
-### 9) Debug logging
+### 10) Debug logging
 
 ```ts
 const client = createRouteClient({

package/dist/index.cjs

@@ -44,6 +44,11 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/routesV3.client.ts
+var import_rrroutes_contract5 = require("@emeryld/rrroutes-contract");
+var import_react_query4 = require("@tanstack/react-query");
+var import_react4 = require("react");
+
 // src/routesV3.client.fetch.ts
 var HttpError = class extends Error {
   constructor({
@@ -1131,6 +1136,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;
@@ -1197,6 +1203,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
@@ -1211,13 +1218,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,
@@ -1228,25 +1245,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;
@@ -1315,11 +1340,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 ? (0, import_rrroutes_contract5.lowProfileParse)(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 = (0, import_react4.useRef)(
+        /* @__PURE__ */ new Set()
+      );
+      const notifyOnReceive = (0, import_react4.useCallback)(
+        (data) => {
+          onReceive?.(data);
+          listenersRef.current.forEach((listener) => listener(data));
+        },
+        [onReceive]
+      );
+      const registerOnReceive = (0, import_react4.useCallback)(
+        (listener) => {
+          listenersRef.current.add(listener);
+          return () => {
+            listenersRef.current.delete(listener);
+          };
+        },
+        []
+      );
+      const queryResult = (0, import_react_query4.useQuery)(
+        {
+          ...useQueryOptions,
+          queryKey: branchQueryKey,
+          placeholderData: useQueryOptions.placeholderData ?? import_react_query4.keepPreviousData,
+          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) {
@@ -2163,26 +2328,48 @@ function useSocketConnection(args) {
     () => 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)
-      client.joinRooms(normalizedRooms, args.joinMeta);
+      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)
-        client.leaveRooms(normalizedRooms, args.leaveMeta);
+        void client.leaveRooms(normalizedRooms, args.leaveMeta).catch((error) => reportAsyncError("leaveRooms", error));
       if (onCleanup) onCleanup();
     };
-  }, [client, event, onMessage, autoJoin, autoLeave, ...normalizedRooms]);
+  }, [
+    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;
-  dbgOpts.logger(e);
+  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;
@@ -2399,8 +2586,15 @@ function SocketProvider(props) {
     });
     return () => {
       if (client) {
-        client.destroy(destroyLeaveMetaRef.current);
-        dbg(providerDebugRef.current, { type: "client", phase: "destroy" });
+        void Promise.resolve(client.destroy(destroyLeaveMetaRef.current)).then(() => {
+          dbg(providerDebugRef.current, { type: "client", phase: "destroy" });
+        }).catch((error) => {
+          dbg(providerDebugRef.current, {
+            type: "resolve",
+            phase: "error",
+            err: `client.destroy failed: ${String(error)}`
+          });
+        });
       }
     };
   }, [client]);
@@ -2409,7 +2603,7 @@ function SocketProvider(props) {
 }
 
 // src/sockets/socketedRoute/socket.client.helper.route.ts
-var import_react4 = require("react");
+var import_react5 = require("react");
 
 // src/sockets/socketedRoute/socket.client.helper.debug.ts
 var objectReferenceIds = /* @__PURE__ */ new WeakMap();
@@ -2577,23 +2771,23 @@ function buildSocketedRoute(options) {
     const endpointResult = useInnerEndpoint(
       ...useArgs
     );
-    const argsKey = (0, import_react4.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
-    const [roomState, setRoomState] = (0, import_react4.useState)(
+    const argsKey = (0, import_react5.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
+    const [roomState, setRoomState] = (0, import_react5.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);
+    const renderCountRef = (0, import_react5.useRef)(0);
+    const clientReadyRef = (0, import_react5.useRef)(null);
+    const onReceiveEffectDebugRef = (0, import_react5.useRef)(null);
+    const deriveRoomsEffectDebugRef = (0, import_react5.useRef)(null);
+    const joinRoomsEffectDebugRef = (0, import_react5.useRef)(null);
+    const applySocketEffectDebugRef = (0, import_react5.useRef)(null);
     renderCountRef.current += 1;
-    const roomsKey = (0, import_react4.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
-    const joinMetaKey = (0, import_react4.useMemo)(
+    const roomsKey = (0, import_react5.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
+    const joinMetaKey = (0, import_react5.useMemo)(
       () => safeJsonKey(roomState.joinMeta ?? null),
       [roomState.joinMeta]
     );
-    const leaveMetaKey = (0, import_react4.useMemo)(
+    const leaveMetaKey = (0, import_react5.useMemo)(
       () => safeJsonKey(roomState.leaveMeta ?? null),
       [roomState.leaveMeta]
     );
@@ -2616,7 +2810,7 @@ function buildSocketedRoute(options) {
       joinMetaKey,
       leaveMetaKey
     });
-    (0, import_react4.useEffect)(() => {
+    (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: onReceiveEffectDebugRef,
         phase: "endpoint_on_receive_effect",
@@ -2635,7 +2829,7 @@ function buildSocketedRoute(options) {
       });
       return unsubscribe;
     }, [endpointResult, toRooms, debug]);
-    (0, import_react4.useEffect)(() => {
+    (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: deriveRoomsEffectDebugRef,
         phase: "derive_rooms_effect",
@@ -2651,7 +2845,7 @@ function buildSocketedRoute(options) {
       );
       setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
     }, [endpointResult.data, toRooms, debug]);
-    (0, import_react4.useEffect)(() => {
+    (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: joinRoomsEffectDebugRef,
         phase: "join_rooms_effect",
@@ -2737,7 +2931,7 @@ function buildSocketedRoute(options) {
         });
       };
     }, [client, roomsKey, joinMetaKey, leaveMetaKey, debug]);
-    (0, import_react4.useEffect)(() => {
+    (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: applySocketEffectDebugRef,
         phase: "apply_socket_effect",