@emeryld/rrroutes-client 1.2.1 → 1.2.2

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,28 @@ 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) {
+  if (!option) {
+    return noopDebugLogger;
+  }
+  if (option === true) {
+    return defaultDebugLogger;
+  }
+  if (typeof option === "function") {
+    return option;
+  }
+  if (option.enabled === false) {
+    return noopDebugLogger;
+  }
+  return option.logger ?? defaultDebugLogger;
+}
 function extractArgs(args) {
   return args[0];
 }
@@ -111,12 +127,17 @@ function createRouteClient(opts) {
   const baseUrl = opts.baseUrl;
   const cursorParam = opts.cursorParam ?? "cursor";
   const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const emitDebug = createDebugEmitter(opts.debug);
   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)}`;
     const key = (...tuple) => {
       const a = extractArgs(tuple);
       const params = a?.params;
@@ -124,7 +145,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,6 +164,7 @@ function createRouteClient(opts) {
           (prev) => typeof updater === "function" ? updater(prev) : updater
         );
       }
+      emitDebug({ type: "setData", key: k });
     };
     if (isGet && isFeed) {
       const useEndpoint2 = (...tuple) => {
@@ -158,11 +184,34 @@ 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();
+            emitDebug({ type: "fetch", stage: "start", method, url, leaf: leafLabel });
+            try {
+              const out = await fetcher({ url, method });
+              emitDebug({
+                type: "fetch",
+                stage: "success",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt
+              });
+              return zParse(out, leaf.cfg.outputSchema);
+            } catch (error) {
+              emitDebug({
+                type: "fetch",
+                stage: "error",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt,
+                error
+              });
+              throw error;
+            }
           }
           // NOTE: TData is InfiniteData<T>, so we don't need a select here.
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -182,10 +231,33 @@ function createRouteClient(opts) {
           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();
+            emitDebug({ type: "fetch", stage: "start", method, url, leaf: leafLabel });
+            try {
+              const out = await fetcher({ url, method });
+              emitDebug({
+                type: "fetch",
+                stage: "success",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt
+              });
+              return zParse(out, leaf.cfg.outputSchema);
+            } catch (error) {
+              emitDebug({
+                type: "fetch",
+                stage: "error",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt,
+                error
+              });
+              throw error;
+            }
           }
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -206,10 +278,41 @@ 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();
+          emitDebug({
+            type: "fetch",
+            stage: "start",
+            method,
+            url,
+            leaf: leafLabel,
+            body: payload
+          });
+          try {
+            const out = await fetcher({ url, method, body: payload });
+            emitDebug({
+              type: "fetch",
+              stage: "success",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            });
+            return zParse(out, leaf.cfg.outputSchema);
+          } catch (error) {
+            emitDebug({
+              type: "fetch",
+              stage: "error",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt,
+              body: payload,
+              error
+            });
+            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  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\nfunction createDebugEmitter(option?: RouteClientDebugOptions): RouteClientDebugLogger {\n  if (!option) {\n    return noopDebugLogger;\n  }\n  if (option === true) {\n    return defaultDebugLogger;\n  }\n  if (typeof option === 'function') {\n    return option;\n  }\n  if (option.enabled === false) {\n    return noopDebugLogger;\n  }\n  return option.logger ?? defaultDebugLogger;\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 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  const emitDebug = createDebugEmitter(opts.debug);\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\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        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 startedAt = Date.now();\n            emitDebug({ type: 'fetch', stage: 'start', method, url, leaf: leafLabel });\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              emitDebug({\n                type: 'fetch',\n                stage: 'success',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n              });\n              return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            } catch (error) {\n              emitDebug({\n                type: 'fetch',\n                stage: 'error',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n                error,\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\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 startedAt = Date.now();\n            emitDebug({ type: 'fetch', stage: 'start', method, url, leaf: leafLabel });\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              emitDebug({\n                type: 'fetch',\n                stage: 'success',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n              });\n              return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            } catch (error) {\n              emitDebug({\n                type: 'fetch',\n                stage: 'error',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n                error,\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      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 startedAt = Date.now();\n          emitDebug({\n            type: 'fetch',\n            stage: 'start',\n            method,\n            url,\n            leaf: leafLabel,\n            body: payload,\n          });\n          try {\n            const out = await fetcher<unknown>({ url, method, body: payload });\n            emitDebug({\n              type: 'fetch',\n              stage: 'success',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n            });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          } catch (error) {\n            emitDebug({\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            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/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,28 @@ 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) {
+  if (!option) {
+    return noopDebugLogger;
+  }
+  if (option === true) {
+    return defaultDebugLogger;
+  }
+  if (typeof option === "function") {
+    return option;
+  }
+  if (option.enabled === false) {
+    return noopDebugLogger;
+  }
+  return option.logger ?? defaultDebugLogger;
+}
 function extractArgs(args) {
   return args[0];
 }
@@ -93,12 +109,17 @@ function createRouteClient(opts) {
   const baseUrl = opts.baseUrl;
   const cursorParam = opts.cursorParam ?? "cursor";
   const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  const emitDebug = createDebugEmitter(opts.debug);
   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)}`;
     const key = (...tuple) => {
       const a = extractArgs(tuple);
       const params = a?.params;
@@ -106,7 +127,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,6 +146,7 @@ function createRouteClient(opts) {
           (prev) => typeof updater === "function" ? updater(prev) : updater
         );
       }
+      emitDebug({ type: "setData", key: k });
     };
     if (isGet && isFeed) {
       const useEndpoint2 = (...tuple) => {
@@ -140,11 +166,34 @@ 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();
+            emitDebug({ type: "fetch", stage: "start", method, url, leaf: leafLabel });
+            try {
+              const out = await fetcher({ url, method });
+              emitDebug({
+                type: "fetch",
+                stage: "success",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt
+              });
+              return zParse(out, leaf.cfg.outputSchema);
+            } catch (error) {
+              emitDebug({
+                type: "fetch",
+                stage: "error",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt,
+                error
+              });
+              throw error;
+            }
           }
           // NOTE: TData is InfiniteData<T>, so we don't need a select here.
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -164,10 +213,33 @@ function createRouteClient(opts) {
           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();
+            emitDebug({ type: "fetch", stage: "start", method, url, leaf: leafLabel });
+            try {
+              const out = await fetcher({ url, method });
+              emitDebug({
+                type: "fetch",
+                stage: "success",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt
+              });
+              return zParse(out, leaf.cfg.outputSchema);
+            } catch (error) {
+              emitDebug({
+                type: "fetch",
+                stage: "error",
+                method,
+                url,
+                leaf: leafLabel,
+                durationMs: Date.now() - startedAt,
+                error
+              });
+              throw error;
+            }
           }
-        });
+        }, queryClient);
       };
       return {
         key,
@@ -188,10 +260,41 @@ 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();
+          emitDebug({
+            type: "fetch",
+            stage: "start",
+            method,
+            url,
+            leaf: leafLabel,
+            body: payload
+          });
+          try {
+            const out = await fetcher({ url, method, body: payload });
+            emitDebug({
+              type: "fetch",
+              stage: "success",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            });
+            return zParse(out, leaf.cfg.outputSchema);
+          } catch (error) {
+            emitDebug({
+              type: "fetch",
+              stage: "error",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt,
+              body: payload,
+              error
+            });
+            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  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\nfunction createDebugEmitter(option?: RouteClientDebugOptions): RouteClientDebugLogger {\n  if (!option) {\n    return noopDebugLogger;\n  }\n  if (option === true) {\n    return defaultDebugLogger;\n  }\n  if (typeof option === 'function') {\n    return option;\n  }\n  if (option.enabled === false) {\n    return noopDebugLogger;\n  }\n  return option.logger ?? defaultDebugLogger;\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 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  const emitDebug = createDebugEmitter(opts.debug);\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\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        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 startedAt = Date.now();\n            emitDebug({ type: 'fetch', stage: 'start', method, url, leaf: leafLabel });\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              emitDebug({\n                type: 'fetch',\n                stage: 'success',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n              });\n              return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            } catch (error) {\n              emitDebug({\n                type: 'fetch',\n                stage: 'error',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n                error,\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\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 startedAt = Date.now();\n            emitDebug({ type: 'fetch', stage: 'start', method, url, leaf: leafLabel });\n            try {\n              const out = await fetcher<unknown>({ url, method });\n              emitDebug({\n                type: 'fetch',\n                stage: 'success',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n              });\n              return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n            } catch (error) {\n              emitDebug({\n                type: 'fetch',\n                stage: 'error',\n                method,\n                url,\n                leaf: leafLabel,\n                durationMs: Date.now() - startedAt,\n                error,\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      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 startedAt = Date.now();\n          emitDebug({\n            type: 'fetch',\n            stage: 'start',\n            method,\n            url,\n            leaf: leafLabel,\n            body: payload,\n          });\n          try {\n            const out = await fetcher<unknown>({ url, method, body: payload });\n            emitDebug({\n              type: 'fetch',\n              stage: 'success',\n              method,\n              url,\n              leaf: leafLabel,\n              durationMs: Date.now() - startedAt,\n            });\n            return zParse<InferOutput<L>>(out, leaf.cfg.outputSchema);\n          } catch (error) {\n            emitDebug({\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            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,31 @@ export type FetchInput = {
 };
 /** Default signature for HTTP fetch implementations. */
 export type Fetcher = <T>(req: FetchInput) => Promise<T>;
+/** 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;
+    error?: unknown;
+} | {
+    type: 'invalidate';
+    key: QueryKey;
+    exact: boolean;
+} | {
+    type: 'setData';
+    key: QueryKey;
+};
+/** 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 | {
+    enabled?: boolean;
+    logger?: RouteClientDebugLogger;
+};
 /** Configuration passed to `createRouteClient`. */
 export type RouteClientOptions = {
     /** Base URL prepended to every route (optional). */
@@ -29,6 +54,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. */
+    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.2",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",