@emeryld/rrroutes-client 1.2.1 → 1.2.4

package/README.md

@@ -33,6 +33,27 @@ function Users() {
 }
 ```
 
+`createRouteClient` passes your `QueryClient` instance directly into every `useQuery`, `useInfiniteQuery`, and `useMutation` call. That means you can skip wrapping your app with `QueryClientProvider` if you prefer manual wiring (though it's still supported if you need context for devtools or hydration).
+
+### Debug logging
+
+You can opt into verbose logging by passing `debug` when constructing the client:
+
+```ts
+const routeClient = createRouteClient({
+  baseUrl: '/api',
+  queryClient: new QueryClient(),
+  debug: process.env.NODE_ENV !== 'production',
+  // or customize the logger:
+  // debug: {
+  //   enabled: true,
+  //   logger: (event) => console.info('[rrroutes-client]', event),
+  // },
+});
+```
+
+Events cover fetch lifecycles (`start`/`success`/`error`), cache updates, and invalidations so you can trace how RRRoutes interacts with React Query.
+
 ## Scripts
 
 ```sh

package/dist/index.cjs

@@ -27,11 +27,6 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/routesV3.client.fetch.ts
-var logger = {
-  debug: (...args) => {
-    console.log("[routesV3.client.fetch]", ...args);
-  }
-};
 var defaultFetcher = async (req) => {
   const headers = { ...req.headers ?? {} };
   const isFormData = typeof FormData !== "undefined" && req.body instanceof FormData;
@@ -39,7 +34,6 @@ var defaultFetcher = async (req) => {
     headers["Content-Type"] || (headers["Content-Type"] = "application/json");
     headers["Accept"] || (headers["Accept"] = "application/json");
   }
-  logger.debug("fetch", req.method, req.url, isFormData ? "FormData" : req.body);
   const res = await fetch(req.url, {
     method: req.method,
     headers,
@@ -95,6 +89,35 @@ function stripKey(obj, key) {
   return rest;
 }
 var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+var noopDebugLogger = () => {
+};
+var defaultDebugLogger = (event) => {
+  if (typeof console === "undefined") return;
+  const fn = console.debug ?? console.log;
+  fn?.call(console, "[rrroutes-client]", event);
+};
+function createDebugEmitter(option) {
+  const disabled = { emit: noopDebugLogger, mode: "minimal" };
+  if (!option) {
+    return disabled;
+  }
+  if (option === true || option === "minimal") {
+    return { emit: defaultDebugLogger, mode: "minimal" };
+  }
+  if (option === "complete") {
+    return { emit: defaultDebugLogger, mode: "complete" };
+  }
+  if (typeof option === "function") {
+    return { emit: option, mode: "minimal" };
+  }
+  if (option.enabled === false) {
+    return { emit: noopDebugLogger, mode: option.mode ?? "minimal" };
+  }
+  return {
+    emit: option.logger ?? defaultDebugLogger,
+    mode: option.mode ?? "minimal"
+  };
+}
 function extractArgs(args) {
   return args[0];
 }
@@ -103,7 +126,7 @@ function buildUrl(leaf, baseUrl, params, query) {
   const normalizedQuery = zParse(query, leaf.cfg.querySchema);
   const path = (0, import_rrroutes_contract.compilePath)(leaf.path, normalizedParams ?? {});
   const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
-  return { url, normalizedQuery };
+  return { url, normalizedQuery, normalizedParams };
 }
 function createRouteClient(opts) {
   const queryClient = opts.queryClient;
@@ -111,12 +134,23 @@ function createRouteClient(opts) {
   const baseUrl = opts.baseUrl;
   const cursorParam = opts.cursorParam ?? "cursor";
   const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug);
+  const isVerboseDebug = debugMode === "complete";
+  const decorateDebugEvent = (event, details) => {
+    if (!isVerboseDebug || !details) return event;
+    return { ...event, ...details };
+  };
   async function invalidate(prefix, exact = false) {
-    await queryClient.invalidateQueries({ queryKey: prefix, exact });
+    const queryKey = prefix;
+    await queryClient.invalidateQueries({ queryKey, exact });
+    emitDebug({ type: "invalidate", key: queryKey, exact });
   }
   function buildInternal(leaf, rqOpts) {
     const isGet = leaf.method === "get";
     const isFeed = !!leaf.cfg.feed;
+    const method = toUpper(leaf.method);
+    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
+    emitDebug({ type: "build", leaf: leafLabel });
     const key = (...tuple) => {
       const a = extractArgs(tuple);
       const params = a?.params;
@@ -124,7 +158,11 @@ function createRouteClient(opts) {
       const qForKey = isGet && isFeed ? stripKey(query, cursorParam) : query;
       return (0, import_rrroutes_contract.buildCacheKey)({ leaf, params, query: qForKey });
     };
-    const invalidateExact = (...tuple) => queryClient.invalidateQueries({ queryKey: key(...tuple), exact: true });
+    const invalidateExact = async (...tuple) => {
+      const queryKey = key(...tuple);
+      await queryClient.invalidateQueries({ queryKey, exact: true });
+      emitDebug({ type: "invalidate", key: queryKey, exact: true });
+    };
     const setData = (...args) => {
       const [updater, ...rest] = args;
       const k = key(...rest);
@@ -139,13 +177,15 @@ function createRouteClient(opts) {
           (prev) => typeof updater === "function" ? updater(prev) : updater
         );
       }
+      emitDebug({ type: "setData", key: k });
     };
     if (isGet && isFeed) {
       const useEndpoint2 = (...tuple) => {
+        emitDebug({ type: "useInfiniteGet", leaf: leafLabel });
         const a = extractArgs(tuple);
         const params = a?.params;
         const query = a?.query;
-        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);
+        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
         return (0, import_react_query.useInfiniteQuery)({
           ...rqOpts,
           queryKey: key(...tuple),
@@ -158,11 +198,51 @@ function createRouteClient(opts) {
               ...pageParam ? { [cursorParam]: pageParam } : {}
             };
             const { url } = buildUrl(leaf, baseUrl, params, pageQuery);
-            const out = await fetcher({ url, method: toUpper(leaf.method) });
-            return zParse(out, leaf.cfg.outputSchema);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : void 0;
+            emitDebug(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
           }
           // NOTE: TData is InfiniteData<T>, so we don't need a select here.
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -173,19 +253,60 @@ function createRouteClient(opts) {
     }
     if (isGet) {
       const useEndpoint2 = (...tuple) => {
+        emitDebug({ type: "useGet", leaf: leafLabel });
         const a = extractArgs(tuple);
         const params = a?.params;
         const query = a?.query;
-        const { url } = buildUrl(leaf, baseUrl, params, query);
+        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
         return (0, import_react_query.useQuery)({
           ...rqOpts,
           queryKey: key(...tuple),
           placeholderData: import_react_query.keepPreviousData,
           queryFn: async () => {
-            const out = await fetcher({ url, method: toUpper(leaf.method) });
-            return zParse(out, leaf.cfg.outputSchema);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+            emitDebug(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
           }
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -195,10 +316,11 @@ function createRouteClient(opts) {
       };
     }
     const useEndpoint = (...tuple) => {
+      emitDebug({ type: "useMutation", leaf: leafLabel });
       const a = extractArgs(tuple);
       const params = a?.params;
       const query = a?.query;
-      const { url } = buildUrl(leaf, baseUrl, params, query);
+      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
       return (0, import_react_query.useMutation)({
         ...rqOpts,
         mutationKey: key(...tuple),
@@ -206,10 +328,58 @@ function createRouteClient(opts) {
           const normalizedBody = zParse(body, leaf.cfg.bodySchema);
           const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;
           const payload = isMultipart ? toFormData(normalizedBody) : normalizedBody;
-          const out = await fetcher({ url, method: toUpper(leaf.method), body: payload });
-          return zParse(out, leaf.cfg.outputSchema);
+          const startedAt = Date.now();
+          const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+          emitDebug(
+            decorateDebugEvent(
+              {
+                type: "fetch",
+                stage: "start",
+                method,
+                url,
+                leaf: leafLabel,
+                body: payload
+              },
+              detail
+            )
+          );
+          try {
+            const out = await fetcher({ url, method, body: payload });
+            const parsed = zParse(out, leaf.cfg.outputSchema);
+            emitDebug(
+              decorateDebugEvent(
+                {
+                  type: "fetch",
+                  stage: "success",
+                  method,
+                  url,
+                  leaf: leafLabel,
+                  durationMs: Date.now() - startedAt
+                },
+                isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+              )
+            );
+            return parsed;
+          } catch (error) {
+            emitDebug(
+              decorateDebugEvent(
+                {
+                  type: "fetch",
+                  stage: "error",
+                  method,
+                  url,
+                  leaf: leafLabel,
+                  durationMs: Date.now() - startedAt,
+                  body: payload,
+                  error
+                },
+                detail
+              )
+            );
+            throw error;
+          }
         }
-      });
+      }, queryClient);
     };
     return {
       key,

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["/**\n * This package exports React Query hooks, so we mark it as client-only to keep Next.js happy.\n */\n'use client';\n\nexport * from './routesV3.client.types';\nexport * from './routesV3.client.fetch';\nexport * from './routesV3.client.index';\n","// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\nconst logger = {\n  debug: (...args: any[]) => {\n    // Uncomment to enable debug logging\n    console.log('[routesV3.client.fetch]', ...args);\n  },\n};\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  logger.debug('fetch', req.method, req.url, isFormData ? 'FormData' : req.body);\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL and normalized query payload.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient(opts: RouteClientOptions): RouteClient {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    await queryClient.invalidateQueries({ queryKey: prefix as unknown as QueryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = (...tuple: ArgsTuple<L>) =>\n      queryClient.invalidateQueries({ queryKey: key(...tuple), exact: true });\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const out = await fetcher<unknown>({ url, method: toUpper(leaf.method) });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        });\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const out = await fetcher<unknown>({ url, method: toUpper(leaf.method) });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          },\n        });\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n\n      const { url } = buildUrl(leaf, baseUrl, params, query);\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: async (body: InferBody<L>) => {\n          const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n          // Optional: switch to FormData if your method declares bodyFiles\n          const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n          const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n          const out = await fetcher<unknown>({ url, method: toUpper(leaf.method), body: payload });\n          return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n        },\n      });\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":"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","names":["useEndpoint"]}
+{"version":3,"sources":["../src/index.ts","../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["/**\n * This package exports React Query hooks, so we mark it as client-only to keep Next.js happy.\n */\n'use client';\n\nexport * from './routesV3.client.types';\nexport * from './routesV3.client.fetch';\nexport * from './routesV3.client.index';\n","// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  RouteClientDebugEvent,\n  RouteClientDebugLogger,\n  RouteClientDebugMode,\n  RouteClientDebugOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Debug logging --------------------------------------------------------------\nconst noopDebugLogger: RouteClientDebugLogger = () => {};\n\nconst defaultDebugLogger: RouteClientDebugLogger = (event: RouteClientDebugEvent) => {\n  if (typeof console === 'undefined') return;\n  const fn = console.debug ?? console.log;\n  fn?.call(console, '[rrroutes-client]', event);\n};\n\ntype DebugEmitter = {\n  emit: RouteClientDebugLogger;\n  mode: RouteClientDebugMode;\n};\n\nfunction createDebugEmitter(option?: RouteClientDebugOptions): DebugEmitter {\n  const disabled: DebugEmitter = { emit: noopDebugLogger, mode: 'minimal' };\n\n  if (!option) {\n    return disabled;\n  }\n  if (option === true || option === 'minimal') {\n    return { emit: defaultDebugLogger, mode: 'minimal' };\n  }\n  if (option === 'complete') {\n    return { emit: defaultDebugLogger, mode: 'complete' };\n  }\n  if (typeof option === 'function') {\n    return { emit: option, mode: 'minimal' };\n  }\n  if (option.enabled === false) {\n    return { emit: noopDebugLogger, mode: option.mode ?? 'minimal' };\n  }\n  return {\n    emit: option.logger ?? defaultDebugLogger,\n    mode: option.mode ?? 'minimal',\n  };\n}\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL plus normalized params/query payloads.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery, normalizedParams };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient(opts: RouteClientOptions): RouteClient {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug);\n  const isVerboseDebug = debugMode === 'complete';\n  const decorateDebugEvent = <T extends RouteClientDebugEvent>(\n    event: T,\n    details?: Partial<RouteClientDebugEvent>,\n  ): RouteClientDebugEvent => {\n    if (!isVerboseDebug || !details) return event;\n    return { ...event, ...details } as RouteClientDebugEvent;\n  };\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    const queryKey = prefix as unknown as QueryKey;\n    await queryClient.invalidateQueries({ queryKey, exact });\n    emitDebug({ type: 'invalidate', key: queryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n    const method = toUpper(leaf.method);\n    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;\n    emitDebug({ type: 'build', leaf: leafLabel });\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = async (...tuple: ArgsTuple<L>) => {\n      const queryKey = key(...tuple);\n      await queryClient.invalidateQueries({ queryKey, exact: true });\n      emitDebug({ type: 'invalidate', key: queryKey, exact: true });\n    };\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n      emitDebug({ type: 'setData', key: k });\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        emitDebug({ type: 'useInfiniteGet', leaf: leafLabel });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const startedAt = Date.now();\n            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : undefined;\n            emitDebug(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        emitDebug({ type: 'useGet', leaf: leafLabel });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const startedAt = Date.now();\n            const detail = isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery }\n              : undefined;\n            emitDebug(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug\n                    ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                    : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      emitDebug({ type: 'useMutation', leaf: leafLabel });\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n\n      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: async (body: InferBody<L>) => {\n          const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n          // Optional: switch to FormData if your method declares bodyFiles\n          const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n          const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n          const startedAt = Date.now();\n          const detail = isVerboseDebug\n            ? { params: normalizedParams, query: normalizedQuery }\n            : undefined;\n          emitDebug(\n            decorateDebugEvent(\n              {\n                type: 'fetch',\n                stage: 'start',\n                method,\n                url,\n                leaf: leafLabel,\n                body: payload,\n              },\n              detail,\n            ),\n          );\n          try {\n            const out = await fetcher<unknown>({ url, method, body: payload });\n            const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            emitDebug(\n              decorateDebugEvent(\n                {\n                  type: 'fetch',\n                  stage: 'success',\n                  method,\n                  url,\n                  leaf: leafLabel,\n                  durationMs: Date.now() - startedAt,\n                },\n                isVerboseDebug\n                  ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                  : undefined,\n              ),\n            );\n            return parsed;\n          } catch (error) {\n            emitDebug(\n              decorateDebugEvent(\n                {\n                  type: 'fetch',\n                  stage: 'error',\n                  method,\n                  url,\n                  leaf: leafLabel,\n                  durationMs: Date.now() - startedAt,\n                  body: payload,\n                  error,\n                },\n                detail,\n              ),\n            );\n            throw error;\n          }\n        },\n      }, queryClient);\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACSO,IAAM,iBAA0B,OAAU,QAAgC;AAC/E,QAAM,UAAkC,EAAE,GAAI,IAAI,WAAW,CAAC,EAAG;AACjE,QAAM,aAAa,OAAO,aAAa,eAAe,IAAI,gBAAgB;AAC1E,MAAI,CAAC,YAAY;AACf,0DAA4B;AAC5B,8CAAsB;AAAA,EACxB;AAEA,QAAM,MAAM,MAAM,MAAM,IAAI,KAAK;AAAA,IAC/B,QAAQ,IAAI;AAAA,IACZ;AAAA,IACA,MAAM,aAAc,IAAI,OAAe,IAAI,QAAQ,OAAO,SAAY,KAAK,UAAU,IAAI,IAAI;AAAA,EAC/F,CAAC;AAED,QAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,UAAU,KAAK,MAAM,GAAG,GAAG;AACjC,UAAM,IAAI,MAAM,IAAI,IAAI,MAAM,KAAK,IAAI,UAAU,WAAM,OAAO,EAAE;AAAA,EAClE;AAEA,MAAI;AACF,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;;;ACjCA,yBAOO;AAEP,+BAIO;AAsCP,IAAM,UAAU,CAAC,MAAyC,EAAE,YAAY;AAQxE,SAAS,OAAU,OAAgB,QAAqB;AACtD,SAAO,SAAU,OAAO,MAAM,KAAK,IAAW;AAChD;AAOA,SAAS,eAAe,OAA4C;AAClE,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,SAAS,IAAI,gBAAgB;AACnC,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,KAAK,GAAG;AAC1C,QAAI,KAAK,KAAM;AACf,QAAI,MAAM,QAAQ,CAAC,GAAG;AACpB,QAAE,QAAQ,CAAC,MAAM;AACf,YAAI,KAAK,KAAM;AACf,YAAI,OAAO,MAAM,UAAU;AACzB,iBAAO,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC;AAAA,QACpC,OAAO;AACL,iBAAO,OAAO,GAAG,OAAO,CAAC,CAAC;AAAA,QAC5B;AAAA,MACF,CAAC;AACD;AAAA,IACF;AACA,QAAI,OAAO,MAAM,UAAU;AACzB,aAAO,IAAI,GAAG,KAAK,UAAU,CAAC,CAAC;AAC/B;AAAA,IACF;AACA,WAAO,IAAI,GAAG,OAAO,CAAC,CAAC;AAAA,EACzB;AACA,QAAM,IAAI,OAAO,SAAS;AAC1B,SAAO,IAAI,IAAI,CAAC,KAAK;AACvB;AAQA,SAAS,SAAwD,KAAQ,KAAgB;AACvF,MAAI,CAAC,IAAK,QAAO;AACjB,QAAM,EAAE,CAAC,GAAG,GAAG,OAAO,GAAG,KAAK,IAAI;AAClC,SAAO;AACT;AAOA,IAAM,uBAAuB,CAAC,MAC5B,KAAK,OAAO,MAAM,YAAY,gBAAgB,IAAK,EAAU,aAAa;AAG5E,IAAM,kBAA0C,MAAM;AAAC;AAEvD,IAAM,qBAA6C,CAAC,UAAiC;AACnF,MAAI,OAAO,YAAY,YAAa;AACpC,QAAM,KAAK,QAAQ,SAAS,QAAQ;AACpC,MAAI,KAAK,SAAS,qBAAqB,KAAK;AAC9C;AAOA,SAAS,mBAAmB,QAAgD;AAC1E,QAAM,WAAyB,EAAE,MAAM,iBAAiB,MAAM,UAAU;AAExE,MAAI,CAAC,QAAQ;AACX,WAAO;AAAA,EACT;AACA,MAAI,WAAW,QAAQ,WAAW,WAAW;AAC3C,WAAO,EAAE,MAAM,oBAAoB,MAAM,UAAU;AAAA,EACrD;AACA,MAAI,WAAW,YAAY;AACzB,WAAO,EAAE,MAAM,oBAAoB,MAAM,WAAW;AAAA,EACtD;AACA,MAAI,OAAO,WAAW,YAAY;AAChC,WAAO,EAAE,MAAM,QAAQ,MAAM,UAAU;AAAA,EACzC;AACA,MAAI,OAAO,YAAY,OAAO;AAC5B,WAAO,EAAE,MAAM,iBAAiB,MAAM,OAAO,QAAQ,UAAU;AAAA,EACjE;AACA,SAAO;AAAA,IACL,MAAM,OAAO,UAAU;AAAA,IACvB,MAAM,OAAO,QAAQ;AAAA,EACvB;AACF;AAQA,SAAS,YAA+B,MAA4C;AAElF,SAAQ,KAA0B,CAAC;AACrC;AAUA,SAAS,SACP,MACA,SACA,QACA,OACA;AACA,QAAM,mBAAmB,OAAuB,QAAQ,KAAK,IAAI,YAAY;AAC7E,QAAM,kBAAkB,OAAsB,OAAO,KAAK,IAAI,WAAW;AACzE,QAAM,WAAO,sCAAuB,KAAK,MAAO,oBAAoB,CAAC,CAAS;AAC9E,QAAM,MAAM,GAAG,WAAW,EAAE,GAAG,IAAI,GAAG,eAAe,eAAsB,CAAC;AAC5E,SAAO,EAAE,KAAK,iBAAiB,iBAAiB;AAClD;AAUO,SAAS,kBAAkB,MAAuC;AACvE,QAAM,cAAc,KAAK;AACzB,QAAM,UAAU,KAAK,WAAW;AAChC,QAAM,UAAU,KAAK;AACrB,QAAM,cAAc,KAAK,eAAe;AACxC,QAAM,gBAAgB,KAAK,iBAAiB;AAC5C,QAAM,EAAE,MAAM,WAAW,MAAM,UAAU,IAAI,mBAAmB,KAAK,KAAK;AAC1E,QAAM,iBAAiB,cAAc;AACrC,QAAM,qBAAqB,CACzB,OACA,YAC0B;AAC1B,QAAI,CAAC,kBAAkB,CAAC,QAAS,QAAO;AACxC,WAAO,EAAE,GAAG,OAAO,GAAG,QAAQ;AAAA,EAChC;AAOA,iBAAe,WAAW,QAAkB,QAAQ,OAAO;AACzD,UAAM,WAAW;AACjB,UAAM,YAAY,kBAAkB,EAAE,UAAU,MAAM,CAAC;AACvD,cAAU,EAAE,MAAM,cAAc,KAAK,UAAU,MAAM,CAAC;AAAA,EACxD;AAQA,WAAS,cACP,MACA,QACiB;AACjB,UAAM,QAAQ,KAAK,WAAW;AAC9B,UAAM,SAAS,CAAC,CAAC,KAAK,IAAI;AAC1B,UAAM,SAAS,QAAQ,KAAK,MAAM;AAClC,UAAM,YAAY,GAAG,KAAK,OAAO,YAAY,CAAC,IAAI,OAAO,KAAK,IAAI,CAAC;AACnE,cAAU,EAAE,MAAM,SAAS,MAAM,UAAU,CAAC;AAG5C,UAAM,MAAM,IAAI,UAAkC;AAChD,YAAM,IAAI,YAAe,KAAK;AAC9B,YAAM,SAAU,GAAW;AAC3B,YAAM,QAAS,GAAW;AAC1B,YAAM,UAAU,SAAS,SAAS,SAAS,OAAc,WAAW,IAAK;AACzE,iBAAO,wCAAc,EAAE,MAAM,QAAuB,OAAO,QAAQ,CAAC;AAAA,IACtE;AAMA,UAAM,kBAAkB,UAAU,UAAwB;AACxD,YAAM,WAAW,IAAI,GAAG,KAAK;AAC7B,YAAM,YAAY,kBAAkB,EAAE,UAAU,OAAO,KAAK,CAAC;AAC7D,gBAAU,EAAE,MAAM,cAAc,KAAK,UAAU,OAAO,KAAK,CAAC;AAAA,IAC9D;AAMA,UAAM,UAAU,IAAI,SAAyD;AAC3E,YAAM,CAAC,SAAS,GAAG,IAAI,IAAI;AAC3B,YAAM,IAAI,IAAI,GAAI,IAAqB;AACvC,UAAI,SAAS,QAAQ;AACnB,oBAAY;AAAA,UAAuD;AAAA,UAAG,CAAC,SACrE,OAAO,YAAY,aAAc,QAAgB,IAAI,IAAK;AAAA,QAC5D;AAAA,MACF,OAAO;AACL,oBAAY;AAAA,UAAyC;AAAA,UAAG,CAAC,SACvD,OAAO,YAAY,aAAc,QAAgB,IAAI,IAAK;AAAA,QAC5D;AAAA,MACF;AACA,gBAAU,EAAE,MAAM,WAAW,KAAK,EAAE,CAAC;AAAA,IACvC;AAGA,QAAI,SAAS,QAAQ;AACnB,YAAMA,eAA+C,IAAI,UAAU;AACjE,kBAAU,EAAE,MAAM,kBAAkB,MAAM,UAAU,CAAC;AACrD,cAAM,IAAI,YAAe,KAAK;AAC9B,cAAM,SAAU,GAAW;AAC3B,cAAM,QAAS,GAAW;AAG1B,cAAM,EAAE,iBAAiB,iBAAiB,IAAI,SAAS,MAAM,SAAS,QAAQ,KAAK;AACnF,mBAAO,qCAML;AAAA,UACA,GAAI;AAAA,UACJ,UAAU,IAAI,GAAG,KAAK;AAAA,UACtB,kBAAkB;AAAA,UAClB,kBAAkB,CAAC,aAAa,cAAc,QAAQ;AAAA,UACtD,iBAAiB;AAAA,UACjB,SAAS,OAAO,EAAE,UAAU,MAAM;AAChC,kBAAM,YAAY;AAAA,cAChB,GAAI;AAAA,cACJ,GAAI,YAAY,EAAE,CAAC,WAAW,GAAG,UAAU,IAAI,CAAC;AAAA,YAClD;AACA,kBAAM,EAAE,IAAI,IAAI,SAAS,MAAM,SAAS,QAAQ,SAAS;AACzD,kBAAM,YAAY,KAAK,IAAI;AAC3B,kBAAM,SAAS,iBAAiB,EAAE,QAAQ,kBAAkB,OAAO,UAAU,IAAI;AACjF;AAAA,cACE;AAAA,gBACE,EAAE,MAAM,SAAS,OAAO,SAAS,QAAQ,KAAK,MAAM,UAAU;AAAA,gBAC9D;AAAA,cACF;AAAA,YACF;AACA,gBAAI;AACF,oBAAM,MAAM,MAAM,QAAiB,EAAE,KAAK,OAAO,CAAC;AAClD,oBAAM,SAAS,OAAuB,KAAK,KAAK,IAAI,YAAY;AAChE;AAAA,gBACE;AAAA,kBACE;AAAA,oBACE,MAAM;AAAA,oBACN,OAAO;AAAA,oBACP;AAAA,oBACA;AAAA,oBACA,MAAM;AAAA,oBACN,YAAY,KAAK,IAAI,IAAI;AAAA,kBAC3B;AAAA,kBACA,iBAAiB,EAAE,QAAQ,kBAAkB,OAAO,WAAW,QAAQ,OAAO,IAAI;AAAA,gBACpF;AAAA,cACF;AACA,qBAAO;AAAA,YACT,SAAS,OAAO;AACd;AAAA,gBACE;AAAA,kBACE;AAAA,oBACE,MAAM;AAAA,oBACN,OAAO;AAAA,oBACP;AAAA,oBACA;AAAA,oBACA,MAAM;AAAA,oBACN,YAAY,KAAK,IAAI,IAAI;AAAA,oBACzB;AAAA,kBACF;AAAA,kBACA;AAAA,gBACF;AAAA,cACF;AACA,oBAAM;AAAA,YACR;AAAA,UACF;AAAA;AAAA,QAEF,GAAG,WAAW;AAAA,MAChB;AAEA,aAAO;AAAA,QACL;AAAA,QACA,YAAY;AAAA,QACZ;AAAA,QACA,aAAAA;AAAA,MACF;AAAA,IACF;AAEA,QAAI,OAAO;AACT,YAAMA,eAA4C,IAAI,UAAU;AAC9D,kBAAU,EAAE,MAAM,UAAU,MAAM,UAAU,CAAC;AAC7C,cAAM,IAAI,YAAe,KAAK;AAC9B,cAAM,SAAU,GAAW;AAC3B,cAAM,QAAS,GAAW;AAE1B,cAAM,EAAE,KAAK,iBAAiB,iBAAiB,IAAI,SAAS,MAAM,SAAS,QAAQ,KAAK;AACxF,mBAAO,6BAA4D;AAAA,UACjE,GAAI;AAAA,UACJ,UAAU,IAAI,GAAG,KAAK;AAAA,UACtB,iBAAiB;AAAA,UACjB,SAAS,YAAY;AACnB,kBAAM,YAAY,KAAK,IAAI;AAC3B,kBAAM,SAAS,iBACX,EAAE,QAAQ,kBAAkB,OAAO,gBAAgB,IACnD;AACJ;AAAA,cACE;AAAA,gBACE,EAAE,MAAM,SAAS,OAAO,SAAS,QAAQ,KAAK,MAAM,UAAU;AAAA,gBAC9D;AAAA,cACF;AAAA,YACF;AACA,gBAAI;AACF,oBAAM,MAAM,MAAM,QAAiB,EAAE,KAAK,OAAO,CAAC;AAClD,oBAAM,SAAS,OAAuB,KAAK,KAAK,IAAI,YAAY;AAChE;AAAA,gBACE;AAAA,kBACE;AAAA,oBACE,MAAM;AAAA,oBACN,OAAO;AAAA,oBACP;AAAA,oBACA;AAAA,oBACA,MAAM;AAAA,oBACN,YAAY,KAAK,IAAI,IAAI;AAAA,kBAC3B;AAAA,kBACA,iBACI,EAAE,QAAQ,kBAAkB,OAAO,iBAAiB,QAAQ,OAAO,IACnE;AAAA,gBACN;AAAA,cACF;AACA,qBAAO;AAAA,YACT,SAAS,OAAO;AACd;AAAA,gBACE;AAAA,kBACE;AAAA,oBACE,MAAM;AAAA,oBACN,OAAO;AAAA,oBACP;AAAA,oBACA;AAAA,oBACA,MAAM;AAAA,oBACN,YAAY,KAAK,IAAI,IAAI;AAAA,oBACzB;AAAA,kBACF;AAAA,kBACA;AAAA,gBACF;AAAA,cACF;AACA,oBAAM;AAAA,YACR;AAAA,UACF;AAAA,QACF,GAAG,WAAW;AAAA,MAChB;AAEA,aAAO;AAAA,QACL;AAAA,QACA,YAAY;AAAA,QACZ;AAAA,QACA,aAAAA;AAAA,MACF;AAAA,IACF;AAGA,UAAM,cAA+C,IAAI,UAAU;AACjE,gBAAU,EAAE,MAAM,eAAe,MAAM,UAAU,CAAC;AAClD,YAAM,IAAI,YAAe,KAAK;AAC9B,YAAM,SAAU,GAAW;AAC3B,YAAM,QAAS,GAAW;AAE1B,YAAM,EAAE,KAAK,iBAAiB,iBAAiB,IAAI,SAAS,MAAM,SAAS,QAAQ,KAAK;AACxF,iBAAO,gCAA4D;AAAA,QACjE,GAAI;AAAA,QACJ,aAAa,IAAI,GAAG,KAAK;AAAA,QACzB,YAAY,OAAO,SAAuB;AACxC,gBAAM,iBAAiB,OAAqB,MAAM,KAAK,IAAI,UAAU;AAGrE,gBAAM,cAAc,MAAM,QAAQ,KAAK,IAAI,SAAS,KAAK,KAAK,IAAI,UAAU,SAAS;AACrF,gBAAM,UAAU,cAAc,WAAW,cAAqB,IAAI;AAElE,gBAAM,YAAY,KAAK,IAAI;AAC3B,gBAAM,SAAS,iBACX,EAAE,QAAQ,kBAAkB,OAAO,gBAAgB,IACnD;AACJ;AAAA,YACE;AAAA,cACE;AAAA,gBACE,MAAM;AAAA,gBACN,OAAO;AAAA,gBACP;AAAA,gBACA;AAAA,gBACA,MAAM;AAAA,gBACN,MAAM;AAAA,cACR;AAAA,cACA;AAAA,YACF;AAAA,UACF;AACA,cAAI;AACF,kBAAM,MAAM,MAAM,QAAiB,EAAE,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACjE,kBAAM,SAAS,OAAuB,KAAK,KAAK,IAAI,YAAY;AAChE;AAAA,cACE;AAAA,gBACE;AAAA,kBACE,MAAM;AAAA,kBACN,OAAO;AAAA,kBACP;AAAA,kBACA;AAAA,kBACA,MAAM;AAAA,kBACN,YAAY,KAAK,IAAI,IAAI;AAAA,gBAC3B;AAAA,gBACA,iBACI,EAAE,QAAQ,kBAAkB,OAAO,iBAAiB,QAAQ,OAAO,IACnE;AAAA,cACN;AAAA,YACF;AACA,mBAAO;AAAA,UACT,SAAS,OAAO;AACd;AAAA,cACE;AAAA,gBACE;AAAA,kBACE,MAAM;AAAA,kBACN,OAAO;AAAA,kBACP;AAAA,kBACA;AAAA,kBACA,MAAM;AAAA,kBACN,YAAY,KAAK,IAAI,IAAI;AAAA,kBACzB,MAAM;AAAA,kBACN;AAAA,gBACF;AAAA,gBACA;AAAA,cACF;AAAA,YACF;AACA,kBAAM;AAAA,UACR;AAAA,QACF;AAAA,MACF,GAAG,WAAW;AAAA,IAChB;AAEA,WAAO;AAAA,MACL;AAAA,MACA,YAAY;AAAA,MACZ;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,OAAO;AAAA,EACT;AACF;AAKA,SAAS,WAAW,MAAqC;AACvD,QAAM,KAAK,IAAI,SAAS;AACxB,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,QAAQ,CAAC,CAAC,GAAG;AAC/C,QAAI,KAAK,KAAM;AACf,QAAI,MAAM,QAAQ,CAAC,EAAG,GAAE,QAAQ,CAAC,MAAM,MAAM,GAAG,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,IAAW,CAAC;AAAA,QAC5E,IAAG,OAAO,GAAG,CAAQ;AAAA,EAC5B;AACA,SAAO;AACT;","names":["useEndpoint"]}

package/dist/index.mjs

@@ -1,11 +1,6 @@
 "use client";
 
 // src/routesV3.client.fetch.ts
-var logger = {
-  debug: (...args) => {
-    console.log("[routesV3.client.fetch]", ...args);
-  }
-};
 var defaultFetcher = async (req) => {
   const headers = { ...req.headers ?? {} };
   const isFormData = typeof FormData !== "undefined" && req.body instanceof FormData;
@@ -13,7 +8,6 @@ var defaultFetcher = async (req) => {
     headers["Content-Type"] || (headers["Content-Type"] = "application/json");
     headers["Accept"] || (headers["Accept"] = "application/json");
   }
-  logger.debug("fetch", req.method, req.url, isFormData ? "FormData" : req.body);
   const res = await fetch(req.url, {
     method: req.method,
     headers,
@@ -77,6 +71,35 @@ function stripKey(obj, key) {
   return rest;
 }
 var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+var noopDebugLogger = () => {
+};
+var defaultDebugLogger = (event) => {
+  if (typeof console === "undefined") return;
+  const fn = console.debug ?? console.log;
+  fn?.call(console, "[rrroutes-client]", event);
+};
+function createDebugEmitter(option) {
+  const disabled = { emit: noopDebugLogger, mode: "minimal" };
+  if (!option) {
+    return disabled;
+  }
+  if (option === true || option === "minimal") {
+    return { emit: defaultDebugLogger, mode: "minimal" };
+  }
+  if (option === "complete") {
+    return { emit: defaultDebugLogger, mode: "complete" };
+  }
+  if (typeof option === "function") {
+    return { emit: option, mode: "minimal" };
+  }
+  if (option.enabled === false) {
+    return { emit: noopDebugLogger, mode: option.mode ?? "minimal" };
+  }
+  return {
+    emit: option.logger ?? defaultDebugLogger,
+    mode: option.mode ?? "minimal"
+  };
+}
 function extractArgs(args) {
   return args[0];
 }
@@ -85,7 +108,7 @@ function buildUrl(leaf, baseUrl, params, query) {
   const normalizedQuery = zParse(query, leaf.cfg.querySchema);
   const path = compilePath(leaf.path, normalizedParams ?? {});
   const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
-  return { url, normalizedQuery };
+  return { url, normalizedQuery, normalizedParams };
 }
 function createRouteClient(opts) {
   const queryClient = opts.queryClient;
@@ -93,12 +116,23 @@ function createRouteClient(opts) {
   const baseUrl = opts.baseUrl;
   const cursorParam = opts.cursorParam ?? "cursor";
   const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug);
+  const isVerboseDebug = debugMode === "complete";
+  const decorateDebugEvent = (event, details) => {
+    if (!isVerboseDebug || !details) return event;
+    return { ...event, ...details };
+  };
   async function invalidate(prefix, exact = false) {
-    await queryClient.invalidateQueries({ queryKey: prefix, exact });
+    const queryKey = prefix;
+    await queryClient.invalidateQueries({ queryKey, exact });
+    emitDebug({ type: "invalidate", key: queryKey, exact });
   }
   function buildInternal(leaf, rqOpts) {
     const isGet = leaf.method === "get";
     const isFeed = !!leaf.cfg.feed;
+    const method = toUpper(leaf.method);
+    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
+    emitDebug({ type: "build", leaf: leafLabel });
     const key = (...tuple) => {
       const a = extractArgs(tuple);
       const params = a?.params;
@@ -106,7 +140,11 @@ function createRouteClient(opts) {
       const qForKey = isGet && isFeed ? stripKey(query, cursorParam) : query;
       return buildCacheKey({ leaf, params, query: qForKey });
     };
-    const invalidateExact = (...tuple) => queryClient.invalidateQueries({ queryKey: key(...tuple), exact: true });
+    const invalidateExact = async (...tuple) => {
+      const queryKey = key(...tuple);
+      await queryClient.invalidateQueries({ queryKey, exact: true });
+      emitDebug({ type: "invalidate", key: queryKey, exact: true });
+    };
     const setData = (...args) => {
       const [updater, ...rest] = args;
       const k = key(...rest);
@@ -121,13 +159,15 @@ function createRouteClient(opts) {
           (prev) => typeof updater === "function" ? updater(prev) : updater
         );
       }
+      emitDebug({ type: "setData", key: k });
     };
     if (isGet && isFeed) {
       const useEndpoint2 = (...tuple) => {
+        emitDebug({ type: "useInfiniteGet", leaf: leafLabel });
         const a = extractArgs(tuple);
         const params = a?.params;
         const query = a?.query;
-        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);
+        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
         return useInfiniteQuery({
           ...rqOpts,
           queryKey: key(...tuple),
@@ -140,11 +180,51 @@ function createRouteClient(opts) {
               ...pageParam ? { [cursorParam]: pageParam } : {}
             };
             const { url } = buildUrl(leaf, baseUrl, params, pageQuery);
-            const out = await fetcher({ url, method: toUpper(leaf.method) });
-            return zParse(out, leaf.cfg.outputSchema);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : void 0;
+            emitDebug(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
           }
           // NOTE: TData is InfiniteData<T>, so we don't need a select here.
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -155,19 +235,60 @@ function createRouteClient(opts) {
     }
     if (isGet) {
       const useEndpoint2 = (...tuple) => {
+        emitDebug({ type: "useGet", leaf: leafLabel });
         const a = extractArgs(tuple);
         const params = a?.params;
         const query = a?.query;
-        const { url } = buildUrl(leaf, baseUrl, params, query);
+        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
         return useQuery({
           ...rqOpts,
           queryKey: key(...tuple),
           placeholderData: keepPreviousData,
           queryFn: async () => {
-            const out = await fetcher({ url, method: toUpper(leaf.method) });
-            return zParse(out, leaf.cfg.outputSchema);
+            const startedAt = Date.now();
+            const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+            emitDebug(
+              decorateDebugEvent(
+                { type: "fetch", stage: "start", method, url, leaf: leafLabel },
+                detail
+              )
+            );
+            try {
+              const out = await fetcher({ url, method });
+              const parsed = zParse(out, leaf.cfg.outputSchema);
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "success",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt
+                  },
+                  isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+                )
+              );
+              return parsed;
+            } catch (error) {
+              emitDebug(
+                decorateDebugEvent(
+                  {
+                    type: "fetch",
+                    stage: "error",
+                    method,
+                    url,
+                    leaf: leafLabel,
+                    durationMs: Date.now() - startedAt,
+                    error
+                  },
+                  detail
+                )
+              );
+              throw error;
+            }
           }
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -177,10 +298,11 @@ function createRouteClient(opts) {
       };
     }
     const useEndpoint = (...tuple) => {
+      emitDebug({ type: "useMutation", leaf: leafLabel });
       const a = extractArgs(tuple);
       const params = a?.params;
       const query = a?.query;
-      const { url } = buildUrl(leaf, baseUrl, params, query);
+      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
       return useMutation({
         ...rqOpts,
         mutationKey: key(...tuple),
@@ -188,10 +310,58 @@ function createRouteClient(opts) {
           const normalizedBody = zParse(body, leaf.cfg.bodySchema);
           const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;
           const payload = isMultipart ? toFormData(normalizedBody) : normalizedBody;
-          const out = await fetcher({ url, method: toUpper(leaf.method), body: payload });
-          return zParse(out, leaf.cfg.outputSchema);
+          const startedAt = Date.now();
+          const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+          emitDebug(
+            decorateDebugEvent(
+              {
+                type: "fetch",
+                stage: "start",
+                method,
+                url,
+                leaf: leafLabel,
+                body: payload
+              },
+              detail
+            )
+          );
+          try {
+            const out = await fetcher({ url, method, body: payload });
+            const parsed = zParse(out, leaf.cfg.outputSchema);
+            emitDebug(
+              decorateDebugEvent(
+                {
+                  type: "fetch",
+                  stage: "success",
+                  method,
+                  url,
+                  leaf: leafLabel,
+                  durationMs: Date.now() - startedAt
+                },
+                isVerboseDebug ? { params: normalizedParams, query: normalizedQuery, output: parsed } : void 0
+              )
+            );
+            return parsed;
+          } catch (error) {
+            emitDebug(
+              decorateDebugEvent(
+                {
+                  type: "fetch",
+                  stage: "error",
+                  method,
+                  url,
+                  leaf: leafLabel,
+                  durationMs: Date.now() - startedAt,
+                  body: payload,
+                  error
+                },
+                detail
+              )
+            );
+            throw error;
+          }
         }
-      });
+      }, queryClient);
     };
     return {
       key,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\nconst logger = {\n  debug: (...args: any[]) => {\n    // Uncomment to enable debug logging\n    console.log('[routesV3.client.fetch]', ...args);\n  },\n};\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  logger.debug('fetch', req.method, req.url, isFormData ? 'FormData' : req.body);\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL and normalized query payload.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient(opts: RouteClientOptions): RouteClient {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    await queryClient.invalidateQueries({ queryKey: prefix as unknown as QueryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = (...tuple: ArgsTuple<L>) =>\n      queryClient.invalidateQueries({ queryKey: key(...tuple), exact: true });\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const out = await fetcher<unknown>({ url, method: toUpper(leaf.method) });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        });\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const out = await fetcher<unknown>({ url, method: toUpper(leaf.method) });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          },\n        });\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n\n      const { url } = buildUrl(leaf, baseUrl, params, query);\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: async (body: InferBody<L>) => {\n          const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n          // Optional: switch to FormData if your method declares bodyFiles\n          const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n          const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n          const out = await fetcher<unknown>({ url, method: toUpper(leaf.method), body: payload });\n          return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n        },\n      });\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":"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","names":["useEndpoint"]}
+{"version":3,"sources":["../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["// routesV3.client.fetch.ts\n\nimport { Fetcher, FetchInput } from './routesV3.client.types';\n\n/**\n * Default fetch implementation used by the route client helper.\n * @param req Normalized request information (URL, method, body, headers).\n * @returns Parsed JSON (or text fallback) from the server response.\n */\nexport const defaultFetcher: Fetcher = async <T>(req: FetchInput): Promise<T> => {\n  const headers: Record<string, string> = { ...(req.headers ?? {}) };\n  const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;\n  if (!isFormData) {\n    headers['Content-Type'] ||= 'application/json';\n    headers['Accept'] ||= 'application/json';\n  }\n\n  const res = await fetch(req.url, {\n    method: req.method,\n    headers,\n    body: isFormData ? (req.body as any) : req.body == null ? undefined : JSON.stringify(req.body),\n  });\n\n  const text = await res.text();\n  if (!res.ok) {\n    const snippet = text.slice(0, 400);\n    throw new Error(`[${res.status}] ${res.statusText} — ${snippet}`);\n  }\n\n  try {\n    return JSON.parse(text) as T;\n  } catch {\n    return text as unknown as T;\n  }\n};\n","// routesV3.client.ts\nimport {\n  keepPreviousData,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  type InfiniteData,\n  type QueryKey,\n} from '@tanstack/react-query';\nimport type { ZodType } from 'zod';\nimport {\n  HttpMethod,\n  buildCacheKey,\n  compilePath,\n} from '@emeryld/rrroutes-contract';\nimport type {\n  AnyLeaf,\n  InferBody,\n  InferOutput,\n  InferParams,\n  InferQuery,\n} from '@emeryld/rrroutes-contract';\nimport { defaultFetcher } from './routesV3.client.fetch';\nimport type {\n  ArgsFor,\n  ArgsTuple,\n  BuiltForLeaf,\n  BuiltInfinite,\n  BuiltMutation,\n  BuiltQuery,\n  Cursor,\n  DataShape,\n  InfiniteBuildOptionsFor,\n  MutationBuildOptionsFor,\n  QueryBuildOptionsFor,\n  RouteClient,\n  RouteClientOptions,\n  RouteClientDebugEvent,\n  RouteClientDebugLogger,\n  RouteClientDebugMode,\n  RouteClientDebugOptions,\n  Updater,\n} from './routesV3.client.types';\n\n// -------------------------------------------------------------------------------------\n// Tiny helpers\n// -------------------------------------------------------------------------------------\n/**\n * Convert an HTTP method to uppercase (as expected by fetch).\n * @param m Lowercase HTTP method.\n * @returns Uppercase method string.\n */\nconst toUpper = (m: HttpMethod): Uppercase<HttpMethod> => m.toUpperCase() as Uppercase<HttpMethod>;\n\n/**\n * Parse the given value with the supplied schema (if present).\n * @param value Raw value to validate.\n * @param schema Optional Zod schema used for validation/coercion.\n * @returns The validated or original value.\n */\nfunction zParse<T>(value: unknown, schema?: ZodType): T {\n  return schema ? (schema.parse(value) as T) : (value as T);\n}\n\n/**\n * Serialize a query object into a search string.\n * @param query Query params object (possibly undefined).\n * @returns Query string prefixed with `?`, or empty string.\n */\nfunction toSearchString(query: Record<string, unknown> | undefined) {\n  if (!query) return '';\n  const params = new URLSearchParams();\n  for (const [k, v] of Object.entries(query)) {\n    if (v == null) continue;\n    if (Array.isArray(v)) {\n      v.forEach((x) => {\n        if (x == null) return;\n        if (typeof x === 'object') {\n          params.append(k, JSON.stringify(x));\n        } else {\n          params.append(k, String(x));\n        }\n      });\n      continue;\n    }\n    if (typeof v === 'object') {\n      params.set(k, JSON.stringify(v));\n      continue;\n    }\n    params.set(k, String(v));\n  }\n  const s = params.toString();\n  return s ? `?${s}` : '';\n}\n\n/**\n * Remove the given key from an object (used to drop cursors from cache keys).\n * @param obj Source object.\n * @param key Property name to omit.\n * @returns Copy of the object without the specified key.\n */\nfunction stripKey<Q extends Record<string, unknown> | undefined>(obj: Q, key: string): Q {\n  if (!obj) return obj;\n  const { [key]: _omit, ...rest } = obj as any;\n  return rest as Q;\n}\n\n/**\n * Default cursor extractor used by infinite queries.\n * @param p Page result returned from the server.\n * @returns Next cursor string, if present.\n */\nconst defaultGetNextCursor = (p: unknown): Cursor =>\n  p && typeof p === 'object' && 'nextCursor' in p ? (p as any).nextCursor : undefined;\n\n// Debug logging --------------------------------------------------------------\nconst noopDebugLogger: RouteClientDebugLogger = () => {};\n\nconst defaultDebugLogger: RouteClientDebugLogger = (event: RouteClientDebugEvent) => {\n  if (typeof console === 'undefined') return;\n  const fn = console.debug ?? console.log;\n  fn?.call(console, '[rrroutes-client]', event);\n};\n\ntype DebugEmitter = {\n  emit: RouteClientDebugLogger;\n  mode: RouteClientDebugMode;\n};\n\nfunction createDebugEmitter(option?: RouteClientDebugOptions): DebugEmitter {\n  const disabled: DebugEmitter = { emit: noopDebugLogger, mode: 'minimal' };\n\n  if (!option) {\n    return disabled;\n  }\n  if (option === true || option === 'minimal') {\n    return { emit: defaultDebugLogger, mode: 'minimal' };\n  }\n  if (option === 'complete') {\n    return { emit: defaultDebugLogger, mode: 'complete' };\n  }\n  if (typeof option === 'function') {\n    return { emit: option, mode: 'minimal' };\n  }\n  if (option.enabled === false) {\n    return { emit: noopDebugLogger, mode: option.mode ?? 'minimal' };\n  }\n  return {\n    emit: option.logger ?? defaultDebugLogger,\n    mode: option.mode ?? 'minimal',\n  };\n}\n\n// Split the variadic tuple at runtime\n/**\n * Extract the optional argument object from a variadic tuple.\n * @param args Tuple passed to a built endpoint helper.\n * @returns The argument object if present.\n */\nfunction extractArgs<L extends AnyLeaf>(args: ArgsTuple<L>): ArgsFor<L> | undefined {\n  // At runtime ArgsTuple<L> is either [] or [obj]; we just pick the first if present.\n  return (args as unknown as any[])[0] as any;\n}\n\n/**\n * Normalize params and query values, then construct a request URL for the given leaf.\n * @param leaf Leaf describing the endpoint.\n * @param baseUrl Optional base URL prepended to the path.\n * @param params Route parameters supplied by the caller.\n * @param query Query parameters supplied by the caller.\n * @returns Object containing the composed URL plus normalized params/query payloads.\n */\nfunction buildUrl<L extends AnyLeaf>(\n  leaf: L,\n  baseUrl: string,\n  params: InferParams<L> | undefined,\n  query: InferQuery<L> | undefined,\n) {\n  const normalizedParams = zParse<InferParams<L>>(params, leaf.cfg.paramsSchema);\n  const normalizedQuery = zParse<InferQuery<L>>(query, leaf.cfg.querySchema);\n  const path = compilePath<L['path']>(leaf.path, (normalizedParams ?? {}) as any);\n  const url = `${baseUrl ?? ''}${path}${toSearchString(normalizedQuery as any)}`;\n  return { url, normalizedQuery, normalizedParams };\n}\n\n// -------------------------------------------------------------------------------------\n// Client factory\n// -------------------------------------------------------------------------------------\n/**\n * Construct typed React Query helpers backed by a routes-v3 registry leaf.\n * @param opts Route client configuration (query client, fetcher overrides, etc).\n * @returns Object that can build endpoint hooks/mutations from leaves.\n */\nexport function createRouteClient(opts: RouteClientOptions): RouteClient {\n  const queryClient = opts.queryClient;\n  const fetcher = opts.fetcher ?? defaultFetcher;\n  const baseUrl = opts.baseUrl;\n  const cursorParam = opts.cursorParam ?? 'cursor';\n  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;\n  const { emit: emitDebug, mode: debugMode } = createDebugEmitter(opts.debug);\n  const isVerboseDebug = debugMode === 'complete';\n  const decorateDebugEvent = <T extends RouteClientDebugEvent>(\n    event: T,\n    details?: Partial<RouteClientDebugEvent>,\n  ): RouteClientDebugEvent => {\n    if (!isVerboseDebug || !details) return event;\n    return { ...event, ...details } as RouteClientDebugEvent;\n  };\n\n  /**\n   * Invalidate a set of queries sharing the given prefix.\n   * @param prefix Key parts shared by matching endpoints.\n   * @param exact When true, invalidate only exact key matches.\n   */\n  async function invalidate(prefix: string[], exact = false) {\n    const queryKey = prefix as unknown as QueryKey;\n    await queryClient.invalidateQueries({ queryKey, exact });\n    emitDebug({ type: 'invalidate', key: queryKey, exact });\n  }\n\n  /**\n   * Build the client surface for a single leaf (query/mutation/infinite query).\n   * @param leaf Leaf describing the endpoint.\n   * @param rqOpts Optional React Query configuration.\n   * @returns Helper object exposing key/invalidate/setData/useEndpoint.\n   */\n  function buildInternal<L extends AnyLeaf>(\n    leaf: L,\n    rqOpts?: QueryBuildOptionsFor<L> | InfiniteBuildOptionsFor<L> | MutationBuildOptionsFor<L>,\n  ): BuiltForLeaf<L> {\n    const isGet = leaf.method === 'get';\n    const isFeed = !!leaf.cfg.feed;\n    const method = toUpper(leaf.method);\n    const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;\n    emitDebug({ type: 'build', leaf: leafLabel });\n\n    // --- key/invalidate/setData shared helpers ---\n    const key = (...tuple: ArgsTuple<L>): QueryKey => {\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n      const qForKey = isGet && isFeed ? stripKey(query as any, cursorParam) : (query as any);\n      return buildCacheKey({ leaf, params: params as any, query: qForKey }) as unknown as QueryKey;\n    };\n\n    /**\n     * Invalidate the React Query cache for this exact leaf invocation.\n     * @param tuple Optional params/query tuple.\n     */\n    const invalidateExact = async (...tuple: ArgsTuple<L>) => {\n      const queryKey = key(...tuple);\n      await queryClient.invalidateQueries({ queryKey, exact: true });\n      emitDebug({ type: 'invalidate', key: queryKey, exact: true });\n    };\n\n    /**\n     * Update the cache entries for this leaf.\n     * @param args Tuple whose first entry is the updater and optional params/query follow.\n     */\n    const setData = (...args: [Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => {\n      const [updater, ...rest] = args;\n      const k = key(...(rest as ArgsTuple<L>));\n      if (isGet && isFeed) {\n        queryClient.setQueryData<InfiniteData<InferOutput<L>> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      } else {\n        queryClient.setQueryData<InferOutput<L> | undefined>(k, (prev) =>\n          typeof updater === 'function' ? (updater as any)(prev) : (updater as any),\n        );\n      }\n      emitDebug({ type: 'setData', key: k });\n    };\n\n    // --- Infinite GET ---\n    if (isGet && isFeed) {\n      const useEndpoint: BuiltInfinite<L>['useEndpoint'] = (...tuple) => {\n        emitDebug({ type: 'useInfiniteGet', leaf: leafLabel });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        // Normalize once; we’ll inject the cursor per page below.\n        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useInfiniteQuery<\n          InferOutput<L>, // TQueryFnData (per page)\n          unknown, // TError\n          InfiniteData<InferOutput<L>>, // TData (returned by the hook)\n          QueryKey,\n          Cursor\n        >({\n          ...(rqOpts as InfiniteBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          initialPageParam: undefined,\n          getNextPageParam: (lastPage) => getNextCursor(lastPage),\n          placeholderData: keepPreviousData,\n          queryFn: async ({ pageParam }) => {\n            const pageQuery = {\n              ...(normalizedQuery as any),\n              ...(pageParam ? { [cursorParam]: pageParam } : {}),\n            };\n            const { url } = buildUrl(leaf, baseUrl, params, pageQuery);\n            const startedAt = Date.now();\n            const detail = isVerboseDebug ? { params: normalizedParams, query: pageQuery } : undefined;\n            emitDebug(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug ? { params: normalizedParams, query: pageQuery, output: parsed } : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n          // NOTE: TData is InfiniteData<T>, so we don't need a select here.\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n    // --- Plain GET ---\n    if (isGet) {\n      const useEndpoint: BuiltQuery<L>['useEndpoint'] = (...tuple) => {\n        emitDebug({ type: 'useGet', leaf: leafLabel });\n        const a = extractArgs<L>(tuple);\n        const params = (a as any)?.params as InferParams<L> | undefined;\n        const query = (a as any)?.query as InferQuery<L> | undefined;\n\n        const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n        return useQuery<InferOutput<L>, unknown, InferOutput<L>, QueryKey>({\n          ...(rqOpts as QueryBuildOptionsFor<L>),\n          queryKey: key(...tuple),\n          placeholderData: keepPreviousData,\n          queryFn: async () => {\n            const startedAt = Date.now();\n            const detail = isVerboseDebug\n              ? { params: normalizedParams, query: normalizedQuery }\n              : undefined;\n            emitDebug(\n              decorateDebugEvent(\n                { type: 'fetch', stage: 'start', method, url, leaf: leafLabel },\n                detail,\n              ),\n            );\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'success',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                  },\n                  isVerboseDebug\n                    ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                    : undefined,\n                ),\n              );\n              return parsed;\n            } catch (error) {\n              emitDebug(\n                decorateDebugEvent(\n                  {\n                    type: 'fetch',\n                    stage: 'error',\n                    method,\n                    url,\n                    leaf: leafLabel,\n                    durationMs: Date.now() - startedAt,\n                    error,\n                  },\n                  detail,\n                ),\n              );\n              throw error;\n            }\n          },\n        }, queryClient);\n      };\n\n      return {\n        key,\n        invalidate: invalidateExact,\n        setData: setData as any,\n        useEndpoint,\n      } as BuiltForLeaf<L>;\n    }\n\n    // --- Mutation (POST/PUT/PATCH/DELETE) ---\n    const useEndpoint: BuiltMutation<L>['useEndpoint'] = (...tuple) => {\n      emitDebug({ type: 'useMutation', leaf: leafLabel });\n      const a = extractArgs<L>(tuple);\n      const params = (a as any)?.params as InferParams<L> | undefined;\n      const query = (a as any)?.query as InferQuery<L> | undefined;\n\n      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);\n      return useMutation<InferOutput<L>, unknown, InferBody<L>, unknown>({\n        ...(rqOpts as MutationBuildOptionsFor<L>),\n        mutationKey: key(...tuple),\n        mutationFn: async (body: InferBody<L>) => {\n          const normalizedBody = zParse<InferBody<L>>(body, leaf.cfg.bodySchema);\n\n          // Optional: switch to FormData if your method declares bodyFiles\n          const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;\n          const payload = isMultipart ? toFormData(normalizedBody as any) : normalizedBody;\n\n          const startedAt = Date.now();\n          const detail = isVerboseDebug\n            ? { params: normalizedParams, query: normalizedQuery }\n            : undefined;\n          emitDebug(\n            decorateDebugEvent(\n              {\n                type: 'fetch',\n                stage: 'start',\n                method,\n                url,\n                leaf: leafLabel,\n                body: payload,\n              },\n              detail,\n            ),\n          );\n          try {\n            const out = await fetcher<unknown>({ url, method, body: payload });\n            const parsed = zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            emitDebug(\n              decorateDebugEvent(\n                {\n                  type: 'fetch',\n                  stage: 'success',\n                  method,\n                  url,\n                  leaf: leafLabel,\n                  durationMs: Date.now() - startedAt,\n                },\n                isVerboseDebug\n                  ? { params: normalizedParams, query: normalizedQuery, output: parsed }\n                  : undefined,\n              ),\n            );\n            return parsed;\n          } catch (error) {\n            emitDebug(\n              decorateDebugEvent(\n                {\n                  type: 'fetch',\n                  stage: 'error',\n                  method,\n                  url,\n                  leaf: leafLabel,\n                  durationMs: Date.now() - startedAt,\n                  body: payload,\n                  error,\n                },\n                detail,\n              ),\n            );\n            throw error;\n          }\n        },\n      }, queryClient);\n    };\n\n    return {\n      key,\n      invalidate: invalidateExact,\n      setData: setData as any,\n      useEndpoint,\n    } as BuiltForLeaf<L>;\n  }\n\n  return {\n    queryClient,\n    invalidate,\n    build: buildInternal as RouteClient['build'],\n  };\n}\n\n// -------------------------------------------------------------------------------------\n// Multipart helper\n// -------------------------------------------------------------------------------------\nfunction toFormData(body: Record<string, any>): FormData {\n  const fd = new FormData();\n  for (const [k, v] of Object.entries(body ?? {})) {\n    if (v == null) continue;\n    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item as any));\n    else fd.append(k, v as any);\n  }\n  return fd;\n}\n"],"mappings":"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","names":["useEndpoint"]}

package/dist/routesV3.client.types.d.ts

@@ -17,6 +17,40 @@ export type FetchInput = {
 };
 /** Default signature for HTTP fetch implementations. */
 export type Fetcher = <T>(req: FetchInput) => Promise<T>;
+/** Debug verbosity levels supported by the client. */
+export type RouteClientDebugMode = 'minimal' | 'complete';
+/** Discrete debug events emitted by the client internals. */
+export type RouteClientDebugEvent = {
+    type: 'fetch';
+    stage: 'start' | 'success' | 'error';
+    method: Uppercase<HttpMethod>;
+    url: string;
+    leaf: string;
+    durationMs?: number;
+    body?: unknown;
+    params?: unknown;
+    query?: unknown;
+    output?: unknown;
+    error?: unknown;
+} | {
+    type: 'invalidate';
+    key: QueryKey;
+    exact: boolean;
+} | {
+    type: 'setData';
+    key: QueryKey;
+} | {
+    type: 'build' | 'useInfiniteGet' | 'useGet' | 'useMutation';
+    leaf: string;
+};
+/** Logger signature invoked when debug logging is enabled. */
+export type RouteClientDebugLogger = (event: RouteClientDebugEvent) => void;
+/** Toggle or customize debug logging produced by the client. */
+export type RouteClientDebugOptions = boolean | RouteClientDebugLogger | RouteClientDebugMode | {
+    enabled?: boolean;
+    logger?: RouteClientDebugLogger;
+    mode?: RouteClientDebugMode;
+};
 /** Configuration passed to `createRouteClient`. */
 export type RouteClientOptions = {
     /** Base URL prepended to every route (optional). */
@@ -29,6 +63,8 @@ export type RouteClientOptions = {
     cursorParam?: string;
     /** Function that extracts the next cursor from an infinite query page. */
     getNextCursor?: (page: unknown) => Cursor;
+    /** Optional debug logger for verbose insights (supports minimal/complete modes). */
+    debug?: RouteClientDebugOptions;
 };
 type OutputOf<L extends AnyLeaf> = InferOutput<L>;
 type ParamsOf<L extends AnyLeaf> = InferParams<L>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "1.2.1",
+  "version": "1.2.4",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",