@emeryld/rrroutes-client 1.1.0

package/README.md

@@ -0,0 +1,51 @@
+# @emeryld/rrroutes-client
+
+React Query helpers that sit on top of an RRRoutes contract. This package consumes finalized leaves from `@emeryld/rrroutes-contract` and produces typed fetch helpers (`useEndpoint`, `useInfinite`, `useMutation`, cache key utilities, etc.).
+
+## Installation
+
+```sh
+pnpm add @emeryld/rrroutes-client @tanstack/react-query
+# or
+npm install @emeryld/rrroutes-client @tanstack/react-query
+```
+
+The client already depends on `@emeryld/rrroutes-contract` and `zod`. You only need to provide React Query as a peer dependency.
+
+## Usage
+
+```ts
+import { createRouteClient } from '@emeryld/rrroutes-client';
+import { QueryClient } from '@tanstack/react-query';
+import { registry } from '../routes';
+
+const routeClient = createRouteClient({
+  queryClient: new QueryClient(),
+  baseUrl: '/api',
+});
+
+const listUsers = routeClient.build(registry.byKey['GET /v1/users']);
+
+function Users() {
+  const { data, isLoading } = listUsers.useEndpoint({ query: { search: 'emery' } });
+  if (isLoading) return <p>Loading…</p>;
+  return <pre>{JSON.stringify(data)}</pre>;
+}
+```
+
+## Scripts
+
+```sh
+pnpm install
+pnpm --filter @emeryld/rrroutes-client build
+pnpm --filter @emeryld/rrroutes-client test
+```
+
+## Publishing
+
+```sh
+cd packages/client
+npm publish --access public
+```
+
+Always bump `packages/client/package.json` before publishing so consumers can pick up the new release.

package/dist/index.cjs

@@ -0,0 +1,240 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRouteClient: () => createRouteClient,
+  defaultFetcher: () => defaultFetcher
+});
+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;
+  if (!isFormData) {
+    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,
+    body: isFormData ? req.body : req.body == null ? void 0 : JSON.stringify(req.body)
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const snippet = text.slice(0, 400);
+    throw new Error(`[${res.status}] ${res.statusText} \u2014 ${snippet}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+// src/routesV3.client.index.ts
+var import_react_query = require("@tanstack/react-query");
+var import_rrroutes_contract = require("@emeryld/rrroutes-contract");
+var toUpper = (m) => m.toUpperCase();
+function zParse(value, schema) {
+  return schema ? schema.parse(value) : value;
+}
+function toSearchString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue;
+    if (Array.isArray(v)) {
+      v.forEach((x) => {
+        if (x == null) return;
+        if (typeof x === "object") {
+          params.append(k, JSON.stringify(x));
+        } else {
+          params.append(k, String(x));
+        }
+      });
+      continue;
+    }
+    if (typeof v === "object") {
+      params.set(k, JSON.stringify(v));
+      continue;
+    }
+    params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+function stripKey(obj, key) {
+  if (!obj) return obj;
+  const { [key]: _omit, ...rest } = obj;
+  return rest;
+}
+var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+function extractArgs(args) {
+  return args[0];
+}
+function buildUrl(leaf, baseUrl, params, query) {
+  const normalizedParams = zParse(params, leaf.cfg.paramsSchema);
+  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 };
+}
+function createRouteClient(opts) {
+  const queryClient = opts.queryClient;
+  const fetcher = opts.fetcher ?? defaultFetcher;
+  const baseUrl = opts.baseUrl;
+  const cursorParam = opts.cursorParam ?? "cursor";
+  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  async function invalidate(prefix, exact = false) {
+    await queryClient.invalidateQueries({ queryKey: prefix, exact });
+  }
+  function buildInternal(leaf, rqOpts) {
+    const isGet = leaf.method === "get";
+    const isFeed = !!leaf.cfg.feed;
+    const key = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      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 setData = (...args) => {
+      const [updater, ...rest] = args;
+      const k = key(...rest);
+      if (isGet && isFeed) {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      } else {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      }
+    };
+    if (isGet && isFeed) {
+      const useEndpoint2 = (...tuple) => {
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);
+        return (0, import_react_query.useInfiniteQuery)({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          initialPageParam: void 0,
+          getNextPageParam: (lastPage) => getNextCursor(lastPage),
+          placeholderData: import_react_query.keepPreviousData,
+          queryFn: async ({ pageParam }) => {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...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);
+          }
+          // NOTE: TData is InfiniteData<T>, so we don't need a select here.
+        });
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    if (isGet) {
+      const useEndpoint2 = (...tuple) => {
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { url } = 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);
+          }
+        });
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    const useEndpoint = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      const { url } = buildUrl(leaf, baseUrl, params, query);
+      return (0, import_react_query.useMutation)({
+        ...rqOpts,
+        mutationKey: key(...tuple),
+        mutationFn: async (body) => {
+          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);
+        }
+      });
+    };
+    return {
+      key,
+      invalidate: invalidateExact,
+      setData,
+      useEndpoint
+    };
+  }
+  return {
+    queryClient,
+    invalidate,
+    build: buildInternal
+  };
+}
+function toFormData(body) {
+  const fd = new FormData();
+  for (const [k, v] of Object.entries(body ?? {})) {
+    if (v == null) continue;
+    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item));
+    else fd.append(k, v);
+  }
+  return fd;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRouteClient,
+  defaultFetcher
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/routesV3.client.fetch.ts","../src/routesV3.client.index.ts"],"sourcesContent":["export * 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"]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './routesV3.client.types';
+export * from './routesV3.client.fetch';
+export * from './routesV3.client.index';

package/dist/index.js

@@ -0,0 +1,220 @@
+// 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;
+  if (!isFormData) {
+    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,
+    body: isFormData ? req.body : req.body == null ? void 0 : JSON.stringify(req.body)
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const snippet = text.slice(0, 400);
+    throw new Error(`[${res.status}] ${res.statusText} \u2014 ${snippet}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+// src/routesV3.client.index.ts
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery
+} from "@tanstack/react-query";
+import {
+  buildCacheKey,
+  compilePath
+} from "@emeryld/rrroutes-contract";
+var toUpper = (m) => m.toUpperCase();
+function zParse(value, schema) {
+  return schema ? schema.parse(value) : value;
+}
+function toSearchString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue;
+    if (Array.isArray(v)) {
+      v.forEach((x) => {
+        if (x == null) return;
+        if (typeof x === "object") {
+          params.append(k, JSON.stringify(x));
+        } else {
+          params.append(k, String(x));
+        }
+      });
+      continue;
+    }
+    if (typeof v === "object") {
+      params.set(k, JSON.stringify(v));
+      continue;
+    }
+    params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : "";
+}
+function stripKey(obj, key) {
+  if (!obj) return obj;
+  const { [key]: _omit, ...rest } = obj;
+  return rest;
+}
+var defaultGetNextCursor = (p) => p && typeof p === "object" && "nextCursor" in p ? p.nextCursor : void 0;
+function extractArgs(args) {
+  return args[0];
+}
+function buildUrl(leaf, baseUrl, params, query) {
+  const normalizedParams = zParse(params, leaf.cfg.paramsSchema);
+  const normalizedQuery = zParse(query, leaf.cfg.querySchema);
+  const path = compilePath(leaf.path, normalizedParams ?? {});
+  const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
+  return { url, normalizedQuery };
+}
+function createRouteClient(opts) {
+  const queryClient = opts.queryClient;
+  const fetcher = opts.fetcher ?? defaultFetcher;
+  const baseUrl = opts.baseUrl;
+  const cursorParam = opts.cursorParam ?? "cursor";
+  const getNextCursor = opts.getNextCursor ?? defaultGetNextCursor;
+  async function invalidate(prefix, exact = false) {
+    await queryClient.invalidateQueries({ queryKey: prefix, exact });
+  }
+  function buildInternal(leaf, rqOpts) {
+    const isGet = leaf.method === "get";
+    const isFeed = !!leaf.cfg.feed;
+    const key = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      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 setData = (...args) => {
+      const [updater, ...rest] = args;
+      const k = key(...rest);
+      if (isGet && isFeed) {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      } else {
+        queryClient.setQueryData(
+          k,
+          (prev) => typeof updater === "function" ? updater(prev) : updater
+        );
+      }
+    };
+    if (isGet && isFeed) {
+      const useEndpoint2 = (...tuple) => {
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { normalizedQuery } = buildUrl(leaf, baseUrl, params, query);
+        return useInfiniteQuery({
+          ...rqOpts,
+          queryKey: key(...tuple),
+          initialPageParam: void 0,
+          getNextPageParam: (lastPage) => getNextCursor(lastPage),
+          placeholderData: keepPreviousData,
+          queryFn: async ({ pageParam }) => {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...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);
+          }
+          // NOTE: TData is InfiniteData<T>, so we don't need a select here.
+        });
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    if (isGet) {
+      const useEndpoint2 = (...tuple) => {
+        const a = extractArgs(tuple);
+        const params = a?.params;
+        const query = a?.query;
+        const { url } = 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);
+          }
+        });
+      };
+      return {
+        key,
+        invalidate: invalidateExact,
+        setData,
+        useEndpoint: useEndpoint2
+      };
+    }
+    const useEndpoint = (...tuple) => {
+      const a = extractArgs(tuple);
+      const params = a?.params;
+      const query = a?.query;
+      const { url } = buildUrl(leaf, baseUrl, params, query);
+      return useMutation({
+        ...rqOpts,
+        mutationKey: key(...tuple),
+        mutationFn: async (body) => {
+          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);
+        }
+      });
+    };
+    return {
+      key,
+      invalidate: invalidateExact,
+      setData,
+      useEndpoint
+    };
+  }
+  return {
+    queryClient,
+    invalidate,
+    build: buildInternal
+  };
+}
+function toFormData(body) {
+  const fd = new FormData();
+  for (const [k, v] of Object.entries(body ?? {})) {
+    if (v == null) continue;
+    if (Array.isArray(v)) v.forEach((item, i) => fd.append(`${k}[${i}]`, item));
+    else fd.append(k, v);
+  }
+  return fd;
+}
+export {
+  createRouteClient,
+  defaultFetcher
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

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

@@ -0,0 +1,7 @@
+import { Fetcher } from './routesV3.client.types';
+/**
+ * Default fetch implementation used by the route client helper.
+ * @param req Normalized request information (URL, method, body, headers).
+ * @returns Parsed JSON (or text fallback) from the server response.
+ */
+export declare const defaultFetcher: Fetcher;

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

@@ -0,0 +1,7 @@
+import type { RouteClient, RouteClientOptions } from './routesV3.client.types';
+/**
+ * Construct typed React Query helpers backed by a routes-v3 registry leaf.
+ * @param opts Route client configuration (query client, fetcher overrides, etc).
+ * @returns Object that can build endpoint hooks/mutations from leaves.
+ */
+export declare function createRouteClient(opts: RouteClientOptions): RouteClient;

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

@@ -0,0 +1,128 @@
+import type { InfiniteData, QueryClient, QueryKey, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+import type { AnyLeaf, HttpMethod, InferBody, InferOutput, InferParams, InferQuery } from '@emeryld/rrroutes-contract';
+/** Helper type used when setting React Query cache data. */
+export type Updater<T> = T | ((prev: T | undefined) => T);
+/** Cursor string extracted from paginated endpoints. */
+export type Cursor = string | undefined;
+/** Runtime request details consumed by a `Fetcher` implementation. */
+export type FetchInput = {
+    /** Fully qualified URL that will be requested. */
+    url: string;
+    /** HTTP method (always uppercase). */
+    method: Uppercase<HttpMethod>;
+    /** Optional request body (already normalized by the client). */
+    body?: unknown;
+    /** Additional headers merged into the request. */
+    headers?: Record<string, string>;
+};
+/** Default signature for HTTP fetch implementations. */
+export type Fetcher = <T>(req: FetchInput) => Promise<T>;
+/** Configuration passed to `createRouteClient`. */
+export type RouteClientOptions = {
+    /** Base URL prepended to every route (optional). */
+    baseUrl: string;
+    /** Custom fetch implementation; defaults to `defaultFetcher`. */
+    fetcher?: Fetcher;
+    /** Shared React Query client used for caching/invalidation. */
+    queryClient: QueryClient;
+    /** Query string key used for pagination cursors (default: "cursor"). */
+    cursorParam?: string;
+    /** Function that extracts the next cursor from an infinite query page. */
+    getNextCursor?: (page: unknown) => Cursor;
+};
+type OutputOf<L extends AnyLeaf> = InferOutput<L>;
+type ParamsOf<L extends AnyLeaf> = InferParams<L>;
+type QueryOf<L extends AnyLeaf> = InferQuery<L>;
+type BodyOf<L extends AnyLeaf> = InferBody<L>;
+/** Object shape the user passes to hooks and helpers (params/query are optional). */
+export type ArgsFor<L extends AnyLeaf> = (ParamsOf<L> extends never ? {} : {
+    params: ParamsOf<L>;
+}) & (QueryOf<L> extends never ? {} : {
+    query: QueryOf<L>;
+});
+/** Variadic tuple representation that omits the argument entirely when not needed. */
+export type ArgsTuple<L extends AnyLeaf> = keyof ArgsFor<L> extends never ? [] : [args: ArgsFor<L>];
+/** Cache data shape for setData(...) */
+export type DataShape<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteData<OutputOf<L>> : OutputOf<L> : OutputOf<L>;
+/** React Query build options specialized for a plain GET leaf. */
+export type QueryBuildOptionsFor<L extends AnyLeaf> = Omit<UseQueryOptions<OutputOf<L>, unknown, OutputOf<L>, QueryKey>, 'queryKey' | 'queryFn'>;
+/** Build options for feed-style GET leaves (`cfg.feed === true`). */
+export type InfiniteBuildOptionsFor<L extends AnyLeaf> = Omit<UseInfiniteQueryOptions<OutputOf<L>, unknown, InfiniteData<OutputOf<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'initialPageParam' | 'getNextPageParam'>;
+/** Build options for mutation leaves (non-GET). */
+export type MutationBuildOptionsFor<L extends AnyLeaf> = Omit<UseMutationOptions<OutputOf<L>, unknown, BodyOf<L>, unknown>, 'mutationFn' | 'mutationKey'>;
+/** Shared capabilities exposed by every built endpoint helper. */
+export type BuiltCommon<L extends AnyLeaf> = {
+    /**
+     * Deterministic key (infinite keys omit the cursor by design).
+     * @param args Optional params/query tuple for the leaf.
+     * @returns Query key tuple.
+     */
+    key: (...args: ArgsTuple<L>) => QueryKey;
+    /**
+     * Invalidate exactly this endpoint instance.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    invalidate: (...args: ArgsTuple<L>) => Promise<void>;
+    /**
+     * Directly update the cache for this endpoint. Handles infinite vs regular.
+     * @param updater New value or function applied to existing cache data.
+     * @param rest Optional params/query tuple for the leaf.
+     */
+    setData: (...args: [updater: Updater<DataShape<L>>, ...rest: ArgsTuple<L>]) => void;
+};
+/** Hook+helpers for a standard GET endpoint. */
+export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to the GET leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseQueryResult<OutputOf<L>, unknown>;
+};
+/** Hook+helpers for a cursor-paginated GET endpoint. */
+export type BuiltInfinite<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to an infinite GET leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseInfiniteQueryResult<InfiniteData<OutputOf<L>>, unknown>;
+};
+/** Hook+helpers for non-GET endpoints (mutations). */
+export type BuiltMutation<L extends AnyLeaf> = BuiltCommon<L> & {
+    /**
+     * React hook bound to a mutation leaf.
+     * @param args Optional params/query tuple for the leaf.
+     */
+    useEndpoint: (...args: ArgsTuple<L>) => UseMutationResult<OutputOf<L>, unknown, BodyOf<L>, unknown>;
+};
+/** Type-safe union that resolves to the correct built helper for a leaf. */
+export type BuiltForLeaf<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L> : BuiltMutation<L>;
+/** Public surface returned by `createRouteClient`. */
+export type RouteClient = {
+    /**
+     * Invalidate by a key prefix (e.g., ['get','api','users']).
+     * @param prefix Key parts shared by matching endpoints.
+     * @param exact When true, invalidate only exact key matches.
+     */
+    invalidate: (prefix: string[], exact?: boolean) => Promise<void>;
+    /** Build a typed endpoint from a leaf. */
+    build: {
+        <L extends AnyLeaf & {
+            method: 'get';
+            cfg: {
+                feed: true;
+            };
+        }>(leaf: L, opts?: InfiniteBuildOptionsFor<L>): BuiltInfinite<L>;
+        <L extends AnyLeaf & {
+            method: 'get';
+            cfg: {
+                feed?: false | undefined;
+            };
+        }>(leaf: L, opts?: QueryBuildOptionsFor<L>): BuiltQuery<L>;
+        <L extends AnyLeaf & {
+            method: Exclude<HttpMethod, 'get'>;
+        }>(leaf: L, opts?: MutationBuildOptionsFor<L>): BuiltMutation<L>;
+    };
+    /** Underlying React Query client (exposed for advanced scenarios). */
+    queryClient: QueryClient;
+};
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@emeryld/rrroutes-client",
+  "version": "1.1.0",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@emeryld/rrroutes-contract": "^1.0.1",
+    "zod": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.87.4"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm run clean && pnpm run build:js && pnpm run build:types",
+    "build:js": "tsup src/index.ts --sourcemap --format esm,cjs --out-dir dist",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}