@emeryld/rrroutes-client 2.6.12 → 2.7.0

package/README.md

@@ -47,7 +47,7 @@ export function Users() {
 
 - `createRouteClient` wires your `QueryClient`, base URL, optional custom fetcher, and debug settings.
 - `build(leaf, options?, meta?)` returns a helper that exposes:
-  - `useEndpoint(args?)` — React hook for GET/feeds/mutations (typed params/query/body/output).
+  - `useEndpoint(args?, options?)` — React hook for GET/feeds/mutations (typed params/query/body/output) with optional per-call TanStack options.
   - `fetch(...)` — direct fetcher (no cache). Mutations require the body as the last argument.
   - `getQueryKeys(...)` — deterministic cache key used by React Query + invalidation.
   - `invalidate(...)` — invalidate this exact endpoint instance.

package/dist/index.cjs

@@ -641,7 +641,8 @@ function buildGetLeaf(leaf, rqOpts, env) {
     });
   };
   const useEndpoint = (...useArgs) => {
-    const args = useArgs[0];
+    const args = expectsArgs ? useArgs[0] : void 0;
+    const useEndpointOptions = expectsArgs ? useArgs[1] : useArgs[0];
     const tuple = toArgsTuple(args);
     const queryKeys = getQueryKeys(...tuple);
     emit({
@@ -650,12 +651,18 @@ function buildGetLeaf(leaf, rqOpts, env) {
       variant: "get",
       keys: queryKeys
     });
-    const buildOptions = rqOpts ?? {};
+    const { onReceive: buildOnReceive2, ...buildQueryOptions } = rqOpts ?? {};
+    const { onReceive: useOnReceive, ...runtimeQueryOptions } = useEndpointOptions ?? {};
+    const mergedQueryOptions = {
+      ...buildQueryOptions,
+      ...runtimeQueryOptions
+    };
     const listenersRef = (0, import_react2.useRef)(/* @__PURE__ */ new Set());
     const notifyOnReceive = (0, import_react2.useCallback)((data) => {
-      buildOptions?.onReceive?.(data);
+      buildOnReceive2?.(data);
+      useOnReceive?.(data);
       listenersRef.current.forEach((listener) => listener(data));
-    }, []);
+    }, [buildOnReceive2, useOnReceive]);
     const registerOnReceive = (0, import_react2.useCallback)(
       (listener) => {
         listenersRef.current.add(listener);
@@ -667,9 +674,9 @@ function buildGetLeaf(leaf, rqOpts, env) {
     );
     const queryResult = (0, import_react_query2.useQuery)(
       {
-        ...buildOptions,
+        ...mergedQueryOptions,
         queryKey: getQueryKeys(...tuple),
-        placeholderData: import_react_query2.keepPreviousData,
+        placeholderData: mergedQueryOptions.placeholderData ?? import_react_query2.keepPreviousData,
         queryFn: () => fetchEndpoint(tuple, {
           onReceive: notifyOnReceive
         })
@@ -914,7 +921,8 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
     });
   };
   const useEndpoint = (...useArgs) => {
-    const args = useArgs[0];
+    const args = expectsArgs ? useArgs[0] : void 0;
+    const useEndpointOptions = expectsArgs ? useArgs[1] : useArgs[0];
     const tuple = toArgsTuple(args);
     const queryKeys = getQueryKeys(...tuple);
     emit({
@@ -926,11 +934,18 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
     const params = args?.params;
     const query = args?.query;
     const buildOptions = feedQueryOptions ?? {};
+    const { onReceive: buildOnReceive2, ...buildInfiniteQueryOptions } = buildOptions;
+    const { onReceive: useOnReceive, ...runtimeInfiniteQueryOptions } = useEndpointOptions ?? {};
+    const mergedInfiniteQueryOptions = {
+      ...buildInfiniteQueryOptions,
+      ...runtimeInfiniteQueryOptions
+    };
     const listenersRef = (0, import_react3.useRef)(/* @__PURE__ */ new Set());
     const notifyOnReceive = (0, import_react3.useCallback)((data) => {
-      buildOptions?.onReceive?.(data);
+      buildOnReceive2?.(data);
+      useOnReceive?.(data);
       listenersRef.current.forEach((listener) => listener(data));
-    }, []);
+    }, [buildOnReceive2, useOnReceive]);
     const registerOnReceive = (0, import_react3.useCallback)(
       (listener) => {
         listenersRef.current.add(listener);
@@ -948,8 +963,8 @@ function buildInfiniteGetLeaf(leaf, rqOpts, env) {
     );
     const queryResult = (0, import_react_query3.useInfiniteQuery)(
       {
-        ...buildOptions,
-        placeholderData: buildOptions.placeholderData ?? import_react_query3.keepPreviousData,
+        ...mergedInfiniteQueryOptions,
+        placeholderData: mergedInfiniteQueryOptions.placeholderData ?? import_react_query3.keepPreviousData,
         initialPageParam: feedInitialPageParam,
         getNextPageParam: (lastPage) => cursorFromPage(lastPage),
         queryKey: queryKeys,
@@ -1086,6 +1101,7 @@ function buildMutationLeaf(leaf, rqOpts, env) {
     return next;
   };
   const mutationBuildOptions = rqOpts ?? {};
+  const { onReceive: mutationBuildOnReceive, ...mutationBuildQueryOptions } = mutationBuildOptions;
   const fetchEndpoint = async (tuple, options) => {
     const a = extractArgs(tuple);
     const params = a?.params;
@@ -1217,13 +1233,14 @@ function buildMutationLeaf(leaf, rqOpts, env) {
     const body = tupleWithBody[bodyIndex];
     const result = await fetchEndpoint(tuple, {
       body,
-      onReceive: (data) => mutationBuildOptions?.onReceive?.(data),
+      onReceive: (data) => mutationBuildOnReceive?.(data),
       requireBody: true
     });
     return result;
   };
   const useEndpoint = (...useArgs) => {
-    const args = useArgs[0];
+    const args = expectsArgs ? useArgs[0] : void 0;
+    const useEndpointOptions = expectsArgs ? useArgs[1] : useArgs[0];
     const tuple = toArgsTuple(args);
     const mutationKey = getQueryKeys(...tuple);
     emit({
@@ -1232,6 +1249,11 @@ function buildMutationLeaf(leaf, rqOpts, env) {
       variant: "mutation",
       keys: mutationKey
     });
+    const { onReceive: useOnReceive, ...runtimeMutationOptions } = useEndpointOptions ?? {};
+    const mergedMutationOptions = {
+      ...mutationBuildQueryOptions,
+      ...runtimeMutationOptions
+    };
     const listenersRef = (0, import_react4.useRef)(/* @__PURE__ */ new Set());
     const notifyListeners = (0, import_react4.useCallback)((data) => {
       listenersRef.current.forEach((listener) => listener(data));
@@ -1247,12 +1269,13 @@ function buildMutationLeaf(leaf, rqOpts, env) {
     );
     const mutationResult = (0, import_react_query4.useMutation)(
       {
-        ...mutationBuildOptions ?? {},
+        ...mergedMutationOptions,
         mutationKey,
         mutationFn: async (body) => {
           const result = await fetchMutation(
             ...[...tuple, body]
           );
+          useOnReceive?.(result);
           notifyListeners(result);
           return result;
         }
@@ -2759,6 +2782,16 @@ function roomsFromData(data, args, toRooms) {
 }
 
 // src/sockets/socketedRoute/socket.client.helper.route.ts
+function parseUseEndpointArgs(useArgs) {
+  const firstArg = useArgs[0];
+  const firstArgRecord = firstArg && typeof firstArg === "object" ? firstArg : void 0;
+  const hasRouteArgs = Boolean(
+    firstArgRecord && (Object.prototype.hasOwnProperty.call(firstArgRecord, "params") || Object.prototype.hasOwnProperty.call(firstArgRecord, "query"))
+  );
+  const endpointArgs = hasRouteArgs ? firstArg : void 0;
+  const endpointArgsTuple = typeof endpointArgs === "undefined" ? [] : [endpointArgs];
+  return { endpointArgs, endpointArgsTuple };
+}
 function buildSocketedRoute(options) {
   const { built, toRooms, applySocket, useSocketClient: useSocketClient2, debug } = options;
   const { useEndpoint: useInnerEndpoint, ...rest } = built;
@@ -2768,11 +2801,15 @@ function buildSocketedRoute(options) {
     const endpointResult = useInnerEndpoint(
       ...useArgs
     );
-    const argsKey = (0, import_react5.useMemo)(() => safeJsonKey(useArgs[0] ?? null), [useArgs]);
+    const { endpointArgs, endpointArgsTuple } = parseUseEndpointArgs(useArgs);
+    const argsKey = (0, import_react5.useMemo)(
+      () => safeJsonKey(endpointArgs ?? null),
+      [endpointArgs]
+    );
     const [roomState, setRoomState] = (0, import_react5.useState)(
       () => roomsFromData(
         endpointResult.data,
-        useArgs[0],
+        endpointArgs,
         toRooms
       )
     );
@@ -2830,13 +2867,13 @@ function buildSocketedRoute(options) {
         setRoomState((prev) => {
           const next = mergeRoomState(
             prev,
-            toRoomsRef.current(data, useArgs[0])
+            toRoomsRef.current(data, endpointArgs)
           );
           return roomStateEqual(prev, next) ? prev : next;
         });
       });
       return unsubscribe;
-    }, [endpointResult.onReceive]);
+    }, [endpointResult.onReceive, argsKey]);
     (0, import_react5.useEffect)(() => {
       trackHookTrigger2({
         ref: deriveRoomsEffectDebugRef,
@@ -2848,7 +2885,7 @@ function buildSocketedRoute(options) {
           toRoomsRef: describeObjectReference(toRooms)
         }
       });
-      const next = roomsFromData(endpointDataRef.current, useArgs[0], toRooms);
+      const next = roomsFromData(endpointDataRef.current, endpointArgs, toRooms);
       setRoomState((prev) => roomStateEqual(prev, next) ? prev : next);
     }, [argsKey, toRooms, debug]);
     (0, import_react5.useEffect)(() => {
@@ -2964,11 +3001,12 @@ function buildSocketedRoute(options) {
             if (!nextUpdate) continue;
             built.setData(
               (prev) => {
-                const next = nextUpdate.fn(
+                const next = nextUpdate.fn({
                   prev,
-                  nextUpdate.payload,
-                  nextUpdate.meta ? { ...nextUpdate.meta, args: useArgs } : { args: useArgs }
-                );
+                  payload: nextUpdate.payload,
+                  args: endpointArgs,
+                  meta: nextUpdate.meta ?? {}
+                });
                 if (next === null) return prev;
                 if (shouldWarnSocketMutationGuard() && isSameObjectReference(prev, next) && !sameRefWarnedEvents.has(nextUpdate.event)) {
                   sameRefWarnedEvents.add(nextUpdate.event);
@@ -2978,7 +3016,7 @@ function buildSocketedRoute(options) {
                 }
                 const nextRoomState = roomsFromData(
                   next,
-                  useArgs[0],
+                  endpointArgs,
                   toRooms
                 );
                 setRoomState(
@@ -2986,7 +3024,7 @@ function buildSocketedRoute(options) {
                 );
                 return next;
               },
-              ...useArgs
+              ...endpointArgsTuple
             );
           }
         } finally {