@emeryld/rrroutes-client 2.7.2 → 2.7.4

package/README.md

@@ -468,20 +468,21 @@ import { buildSocketedRoute } from '@emeryld/rrroutes-client';
 import { useSocketClient } from './socketProvider';
 
 const listRooms = client.build(registry.byKey['GET /v1/rooms'], { staleTime: 120_000 });
+const useAppSocketContext = () => ({ workspaceId: 'acme' });
 
 const socketedRooms = buildSocketedRoute({
   built: listRooms,
-  toRooms: (page) => ({
-    rooms: page.items.map((r) => r.id), // derive rooms from data (feeds supported)
+  useContext: useAppSocketContext, // optional app-level context for hooks
+  toRooms: ({ data, meta }) => ({
+    rooms: data.items.map((r) => `${meta?.appContext?.workspaceId}:${r.id}`), // derive rooms from data (feeds supported)
     joinMeta: { source: 'rooms:list' },
     leaveMeta: { source: 'rooms:list' },
   }),
   useSocketClient,
   applySocket: {
-    'chat:message': (prev, payload, meta) => {
+    'chat:message': ({ prev, payload, args, meta }) => {
       if (!prev) return null; // explicit no-op update
-      const [args] = meta.args;
-      console.debug('socket patch args', args);
+      console.debug('socket patch args', args, meta.appContext?.workspaceId, meta.ctx?.socketId);
       // Example: bump unread count in cache
       const apply = (items: any[]) =>
         items.map((room) =>
@@ -505,7 +506,11 @@ function RoomList() {
 }
 ```
 
-`buildSocketedRoute(...)` returns a built endpoint object with `useEndpoint()` plus the original built helpers. `applySocket` receives `{ envelope?, ctx?, args }` and can return `null` to skip cache updates.
+`buildSocketedRoute(...)` returns a built endpoint object with `useEndpoint()` plus the original built helpers.
+
+- `toRooms` receives `{ data, args, meta }` where `meta.appContext` comes from `useContext` (if provided).
+- `applySocket` handlers receive `{ prev, payload, args, meta }`, where `meta` contains `envelope?`, `ctx?`, and `appContext?`.
+- Return `null` from `applySocket` to skip cache updates.
 
 ---
 

package/dist/index.cjs

@@ -300,6 +300,16 @@ function buildUrl(leaf, baseUrl, params, query) {
   const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
   return { url, normalizedQuery, normalizedParams };
 }
+function areEndpointArgsComplete(leaf, args) {
+  const params = args?.params;
+  const query = args?.query;
+  try {
+    buildUrl(leaf, "", params, query);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isBlobLike(value) {
   return typeof Blob !== "undefined" && value instanceof Blob;
 }
@@ -643,6 +653,7 @@ function buildGetLeaf(leaf, rqOpts, env) {
   const useEndpoint = (...useArgs) => {
     const args = expectsArgs ? useArgs[0] : void 0;
     const useEndpointOptions = expectsArgs ? useArgs[1] : useArgs[0];
+    const hasCompleteArgs = !expectsArgs || areEndpointArgsComplete(leaf, args);
     const tuple = toArgsTuple(args);
     const queryKeys = getQueryKeys(...tuple);
     emit({
@@ -657,6 +668,8 @@ function buildGetLeaf(leaf, rqOpts, env) {
       ...buildQueryOptions,
       ...runtimeQueryOptions
     };
+    const mergedEnabled = mergedQueryOptions.enabled;
+    const guardedEnabled = hasCompleteArgs && (typeof mergedEnabled === "undefined" ? true : mergedEnabled);
     const listenersRef = (0, import_react2.useRef)(/* @__PURE__ */ new Set());
     const notifyOnReceive = (0, import_react2.useCallback)((data) => {
       buildOnReceive2?.(data);
@@ -675,11 +688,17 @@ function buildGetLeaf(leaf, rqOpts, env) {
     const queryResult = (0, import_react_query2.useQuery)(
       {
         ...mergedQueryOptions,
+        enabled: guardedEnabled,
         queryKey: getQueryKeys(...tuple),
         placeholderData: mergedQueryOptions.placeholderData ?? import_react_query2.keepPreviousData,
-        queryFn: () => fetchEndpoint(tuple, {
-          onReceive: notifyOnReceive
-        })
+        queryFn: () => {
+          if (!hasCompleteArgs) {
+            return Promise.resolve(void 0);
+          }
+          return fetchEndpoint(tuple, {
+            onReceive: notifyOnReceive
+          });
+        }
       },
       queryClient
     );
@@ -923,6 +942,7 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
   const useEndpoint = (...useArgs) => {
     const args = expectsArgs ? useArgs[0] : void 0;
     const useEndpointOptions = expectsArgs ? useArgs[1] : useArgs[0];
+    const hasCompleteArgs = !expectsArgs || areEndpointArgsComplete(leaf, args);
     const tuple = toArgsTuple(args);
     const queryKeys = getQueryKeys(...tuple);
     emit({
@@ -940,6 +960,8 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
       ...buildInfiniteQueryOptions,
       ...runtimeInfiniteQueryOptions
     };
+    const mergedEnabled = mergedInfiniteQueryOptions.enabled;
+    const guardedEnabled = hasCompleteArgs && (typeof mergedEnabled === "undefined" ? true : mergedEnabled);
     const listenersRef = (0, import_react3.useRef)(/* @__PURE__ */ new Set());
     const notifyOnReceive = (0, import_react3.useCallback)((data) => {
       buildOnReceive2?.(data);
@@ -955,20 +977,22 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
       },
       []
     );
-    const { normalizedQuery, normalizedParams } = buildUrl(
-      { ...leaf, cfg: leafCfg },
-      baseUrl,
-      params,
-      query
-    );
+    const { normalizedQuery, normalizedParams } = hasCompleteArgs ? buildUrl({ ...leaf, cfg: leafCfg }, baseUrl, params, query) : {
+      normalizedQuery: query ?? {},
+      normalizedParams: params ?? {}
+    };
     const queryResult = (0, import_react_query3.useInfiniteQuery)(
       {
         ...mergedInfiniteQueryOptions,
+        enabled: guardedEnabled,
         placeholderData: mergedInfiniteQueryOptions.placeholderData ?? import_react_query3.keepPreviousData,
         initialPageParam: feedInitialPageParam,
         getNextPageParam: (lastPage) => cursorFromPage(lastPage),
         queryKey: queryKeys,
         queryFn: ({ pageParam }) => {
+          if (!hasCompleteArgs) {
+            return Promise.resolve(void 0);
+          }
           if (!effectiveSplitPageSize) {
             const pageQuery = {
               ...normalizedQuery,
@@ -2752,12 +2776,15 @@ function mergeRoomState(prev, toRoomsResult) {
     leaveMeta: toRoomsResult.leaveMeta ?? prev.leaveMeta
   };
 }
-function roomsFromData(data, args, toRooms) {
+function roomsFromData(data, args, toRooms, meta) {
   if (data == null) return { rooms: [] };
   let state = { rooms: [] };
   const add = (input) => {
     const mergeForValue = (value) => {
-      state = mergeRoomState(state, toRooms(value, args));
+      state = mergeRoomState(
+        state,
+        toRooms({ data: value, args, meta })
+      );
     };
     if (Array.isArray(input)) {
       input.forEach((entry) => mergeForValue(entry));
@@ -2792,8 +2819,21 @@ function parseUseEndpointArgs(useArgs) {
   const endpointArgsTuple = typeof endpointArgs === "undefined" ? [] : [endpointArgs];
   return { endpointArgs, endpointArgsTuple };
 }
+function useDefaultSocketedRouteContext() {
+  return void 0;
+}
+function createToRoomsMeta(appContext) {
+  return { appContext };
+}
 function buildSocketedRoute(options) {
-  const { built, toRooms, applySocket, useSocketClient: useSocketClient2, debug } = options;
+  const {
+    built,
+    toRooms,
+    applySocket,
+    useSocketClient: useSocketClient2,
+    useContext: useRouteContext = useDefaultSocketedRouteContext,
+    debug
+  } = options;
   const { useEndpoint: useInnerEndpoint, ...rest } = built;
   const useEndpoint = (...useArgs) => {
     const client = useSocketClient2();
@@ -2801,6 +2841,11 @@ function buildSocketedRoute(options) {
     const endpointResult = useInnerEndpoint(
       ...useArgs
     );
+    const appContext = useRouteContext();
+    const toRoomsMeta = (0, import_react5.useMemo)(
+      () => createToRoomsMeta(appContext),
+      [appContext]
+    );
     const { endpointArgs, endpointArgsTuple } = parseUseEndpointArgs(useArgs);
     const argsKey = (0, import_react5.useMemo)(
       () => safeJsonKey(endpointArgs ?? null),
@@ -2810,7 +2855,8 @@ function buildSocketedRoute(options) {
       () => roomsFromData(
         endpointResult.data,
         endpointArgs,
-        toRooms
+        toRooms,
+        toRoomsMeta
       )
     );
     const renderCountRef = (0, import_react5.useRef)(0);
@@ -2819,6 +2865,7 @@ function buildSocketedRoute(options) {
       endpointResult.data
     );
     const toRoomsRef = (0, import_react5.useRef)(toRooms);
+    const toRoomsMetaRef = (0, import_react5.useRef)(toRoomsMeta);
     const onReceiveEffectDebugRef = (0, import_react5.useRef)(null);
     const deriveRoomsEffectDebugRef = (0, import_react5.useRef)(null);
     const joinRoomsEffectDebugRef = (0, import_react5.useRef)(null);
@@ -2826,6 +2873,7 @@ function buildSocketedRoute(options) {
     renderCountRef.current += 1;
     endpointDataRef.current = endpointResult.data;
     toRoomsRef.current = toRooms;
+    toRoomsMetaRef.current = toRoomsMeta;
     const roomsKey = (0, import_react5.useMemo)(() => roomState.rooms.join("|"), [roomState.rooms]);
     const joinMetaKey = (0, import_react5.useMemo)(
       () => safeJsonKey(roomState.joinMeta ?? null),
@@ -2867,7 +2915,11 @@ function buildSocketedRoute(options) {
         setRoomState((prev) => {
           const next = mergeRoomState(
             prev,
-            toRoomsRef.current(data, endpointArgs)
+            toRoomsRef.current({
+              data,
+              args: endpointArgs,
+              meta: toRoomsMetaRef.current
+            })
           );
           return roomStateEqual(prev, next) ? prev : next;
         });
@@ -2885,9 +2937,14 @@ function buildSocketedRoute(options) {
           toRoomsRef: describeObjectReference(toRooms)
         }
       });
-      const next = roomsFromData(endpointDataRef.current, endpointArgs, toRooms);
+      const next = roomsFromData(
+        endpointDataRef.current,
+        endpointArgs,
+        toRooms,
+        toRoomsMeta
+      );
       setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
-    }, [argsKey, toRooms, debug]);
+    }, [argsKey, toRooms, toRoomsMeta, debug]);
     (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: joinRoomsEffectDebugRef,
@@ -3005,7 +3062,10 @@ function buildSocketedRoute(options) {
                   prev,
                   payload: nextUpdate.payload,
                   args: endpointArgs,
-                  meta: nextUpdate.meta ?? {}
+                  meta: {
+                    ...nextUpdate.meta ?? {},
+                    appContext: toRoomsMetaRef.current.appContext
+                  }
                 });
                 if (next === null) return prev;
                 if (shouldWarnSocketMutationGuard() && isSameObjectReference(prev, next) && !sameRefWarnedEvents.has(nextUpdate.event)) {
@@ -3017,7 +3077,8 @@ function buildSocketedRoute(options) {
                 const nextRoomState = roomsFromData(
                   next,
                   endpointArgs,
-                  toRooms
+                  toRooms,
+                  toRoomsMetaRef.current
                 );
                 setRoomState(
                   (prevRoomState) => roomStateEqual(prevRoomState, nextRoomState) ? prevRoomState : nextRoomState