@emeryld/rrroutes-client 2.4.0 → 2.4.2

package/dist/index.mjs

@@ -51,19 +51,16 @@ var defaultFetcher = async (req) => {
   }
 };
 
-// src/routesV3.client.index.ts
-import {
-  buildCacheKey,
-  compilePath,
-  lowProfileParse
-} from "@emeryld/rrroutes-contract";
+// src/routesV3.client.get.ts
+import { buildCacheKey, lowProfileParse as lowProfileParse2 } from "@emeryld/rrroutes-contract";
 import {
   keepPreviousData,
-  useInfiniteQuery,
-  useMutation,
   useQuery
 } from "@tanstack/react-query";
 import { useCallback, useRef } from "react";
+
+// src/routesV3.client.shared.ts
+import { compilePath, lowProfileParse } from "@emeryld/rrroutes-contract";
 var toUpper = (m) => m.toUpperCase();
 function toSearchString(query) {
   if (!query) return "";
@@ -74,34 +71,900 @@ function toSearchString(query) {
       params.append(k, v);
       continue;
     }
-    if (typeof v === "number" || typeof v === "boolean") {
-      params.append(k, String(v));
-      continue;
+    if (typeof v === "number" || typeof v === "boolean") {
+      params.append(k, String(v));
+      continue;
+    }
+    params.append(k, JSON.stringify(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) => {
+  if (!p || typeof p !== "object") return void 0;
+  const record = p;
+  if ("nextCursor" in record) {
+    return record.nextCursor;
+  }
+  if ("meta" in record) {
+    const meta = record.meta;
+    if (meta && typeof meta === "object" && "nextCursor" in meta) {
+      return meta.nextCursor;
+    }
+  }
+  return void 0;
+};
+function extractArgs(args) {
+  return args[0];
+}
+function toArgsTuple(args) {
+  return typeof args === "undefined" ? [] : [args];
+}
+function buildUrl(leaf, baseUrl, params, query) {
+  const normalizedParams = leaf.cfg.paramsSchema ? lowProfileParse(leaf.cfg.paramsSchema, params) : {};
+  const normalizedQuery = leaf.cfg.querySchema ? lowProfileParse(leaf.cfg.querySchema, query) : {};
+  const path = compilePath(
+    leaf.path,
+    normalizedParams ?? {}
+  );
+  const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
+  return { url, normalizedQuery, normalizedParams };
+}
+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;
+}
+function getPathParamNames(path) {
+  const names = /* @__PURE__ */ new Set();
+  const re = /:([A-Za-z0-9_]+)/g;
+  let match;
+  while ((match = re.exec(path)) !== null) {
+    names.add(match[1]);
+  }
+  return names;
+}
+function normalizeFlatQuery(query) {
+  if (query == null) return void 0;
+  if (typeof query !== "object" || Array.isArray(query)) {
+    throw new Error("Query must be a plain object (Record<string, string>).");
+  }
+  const result = {};
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue;
+    if (typeof v !== "string") {
+      throw new Error(
+        `Query param "${k}" must be a string; received type "${typeof v}".`
+      );
+    }
+    result[k] = v;
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function compileRawPath(path, params) {
+  const placeholders = getPathParamNames(path);
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    if (placeholders.size > 0) {
+      throw new Error(
+        `Missing path parameters for "${path}": ${[...placeholders].join(
+          ", "
+        )}`
+      );
+    }
+    return path;
+  }
+  const paramObj = params;
+  const providedNames = new Set(Object.keys(paramObj));
+  for (const name of providedNames) {
+    if (!placeholders.has(name)) {
+      throw new Error(
+        `Unexpected path parameter "${name}" for template "${path}".`
+      );
+    }
+    const value = paramObj[name];
+    if (value != null && (typeof value === "object" || Array.isArray(value))) {
+      throw new Error(
+        `Path parameter "${name}" must be a primitive; received "${typeof value}".`
+      );
+    }
+  }
+  for (const name of placeholders) {
+    if (!providedNames.has(name)) {
+      throw new Error(
+        `Missing value for path parameter "${name}" in template "${path}".`
+      );
+    }
+  }
+  if (placeholders.size === 0) {
+    return path;
+  }
+  return compilePath(path, paramObj);
+}
+
+// src/routesV3.client.get.ts
+function buildGetLeaf(leaf, rqOpts, env) {
+  const leafCfg = leaf.cfg;
+  const method = toUpper(leaf.method);
+  const expectsArgs = Boolean(leafCfg.paramsSchema || leafCfg.querySchema);
+  const {
+    baseUrl,
+    validateResponses,
+    fetcher,
+    queryClient,
+    emit,
+    decorateDebugEvent,
+    isVerboseDebug,
+    leafLabel
+  } = env;
+  emit({ type: "build", leaf: leafLabel });
+  const getQueryKeys = (...tuple) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = a?.query;
+    return buildCacheKey({
+      leaf,
+      params,
+      query
+    });
+  };
+  const invalidateExact = async (...tuple) => {
+    const queryKey = getQueryKeys(...tuple);
+    await queryClient.invalidateQueries({ queryKey, exact: true });
+    emit({ type: "invalidate", key: queryKey, exact: true });
+  };
+  const setData = (...args) => {
+    const [updater, ...rest] = args;
+    const k = getQueryKeys(...rest);
+    const next = queryClient.setQueryData(
+      k,
+      (prev) => typeof updater === "function" ? updater(prev) : updater
+    );
+    emit({ type: "setData", key: k });
+    return next;
+  };
+  const buildOnReceive = rqOpts?.onReceive ?? void 0;
+  const fetchEndpoint = async (tuple, options) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = options?.queryOverride ?? a?.query;
+    const { url, normalizedQuery, normalizedParams } = buildUrl(
+      { ...leaf, cfg: leafCfg },
+      baseUrl,
+      params,
+      query
+    );
+    let payload;
+    const acceptsBody = Boolean(leafCfg.bodySchema);
+    const requiresBody = options?.requireBody ?? (!acceptsBody ? false : true);
+    if (typeof options?.body !== "undefined") {
+      const normalizedBody = leafCfg.bodySchema ? lowProfileParse2(leafCfg.bodySchema, options.body) : void 0;
+      const isMultipart = Array.isArray(leafCfg.bodyFiles) && leafCfg.bodyFiles.length > 0;
+      if (isMultipart && normalizedBody && typeof normalizedBody === "object") {
+        payload = toFormData(normalizedBody);
+      } else {
+        payload = normalizedBody;
+      }
+    } else if (requiresBody && acceptsBody) {
+      throw new Error("Body is required when invoking a mutation fetch.");
+    }
+    const startedAt = Date.now();
+    const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+    emit(
+      decorateDebugEvent(
+        {
+          type: "fetch",
+          stage: "start",
+          method,
+          url,
+          leaf: leafLabel,
+          ...payload !== void 0 ? { body: payload } : {}
+        },
+        detail
+      )
+    );
+    try {
+      const out = await fetcher(
+        payload === void 0 ? { url, method } : { url, method, body: payload }
+      );
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "fetched",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt
+          },
+          isVerboseDebug ? {
+            params: normalizedParams,
+            query: normalizedQuery,
+            output: out
+          } : void 0
+        )
+      );
+      if (validateResponses) {
+        if (!leafCfg.outputSchema) {
+          throw new Error(
+            `No output schema defined for leaf ${leafLabel}, cannot validate response.`
+          );
+        }
+        out.data = lowProfileParse2(
+          leafCfg.outputSchema,
+          out.data
+        );
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "parsed",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            },
+            isVerboseDebug ? {
+              params: normalizedParams,
+              query: normalizedQuery,
+              output: out
+            } : void 0
+          )
+        );
+      }
+      options?.onReceive?.(out.data);
+      return out.data;
+    } catch (error) {
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "error",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt,
+            ...payload !== void 0 ? { body: payload } : {},
+            error
+          },
+          detail
+        )
+      );
+      throw error;
+    }
+  };
+  const fetchGet = (...tupleWithBody) => {
+    const acceptsBody = Boolean(leafCfg.bodySchema);
+    const tupleLength = tupleWithBody.length;
+    const maybeBodyIndex = expectsArgs ? 1 : 0;
+    const hasBodyCandidate = acceptsBody && tupleLength > maybeBodyIndex;
+    const body = hasBodyCandidate ? tupleWithBody[tupleLength - 1] : void 0;
+    const tuple = hasBodyCandidate ? tupleWithBody.slice(0, tupleLength - 1) : tupleWithBody;
+    return fetchEndpoint(tuple, {
+      body,
+      onReceive: buildOnReceive,
+      requireBody: false
+    });
+  };
+  const useEndpoint = (...useArgs) => {
+    const args = useArgs[0];
+    const tuple = toArgsTuple(args);
+    const queryKeys = getQueryKeys(...tuple);
+    emit({
+      type: "useEndpoint",
+      leaf: leafLabel,
+      variant: "get",
+      keys: queryKeys
+    });
+    const buildOptions = rqOpts ?? {};
+    const listenersRef = useRef(/* @__PURE__ */ new Set());
+    const notifyOnReceive = useCallback((data) => {
+      buildOptions?.onReceive?.(data);
+      listenersRef.current.forEach((listener) => listener(data));
+    }, []);
+    const registerOnReceive = useCallback(
+      (listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+          listenersRef.current.delete(listener);
+        };
+      },
+      []
+    );
+    const queryResult = useQuery(
+      {
+        ...buildOptions,
+        queryKey: getQueryKeys(...tuple),
+        placeholderData: keepPreviousData,
+        queryFn: () => fetchEndpoint(tuple, {
+          onReceive: notifyOnReceive
+        })
+      },
+      queryClient
+    );
+    return { ...queryResult, onReceive: registerOnReceive };
+  };
+  return {
+    getQueryKeys,
+    invalidate: invalidateExact,
+    setData,
+    useEndpoint,
+    fetch: fetchGet
+  };
+}
+
+// src/routesV3.client.infiniteGet.ts
+import { buildCacheKey as buildCacheKey2, lowProfileParse as lowProfileParse3 } from "@emeryld/rrroutes-contract";
+import {
+  keepPreviousData as keepPreviousData2,
+  useInfiniteQuery
+} from "@tanstack/react-query";
+import { useCallback as useCallback2, useRef as useRef2 } from "react";
+function mergePageOutputs(prev, next) {
+  if (prev == null) return next;
+  if (next == null) return prev;
+  if (Array.isArray(prev) && Array.isArray(next)) {
+    return [...prev, ...next];
+  }
+  if (typeof prev !== "object" || typeof next !== "object") {
+    return next;
+  }
+  const merged = { ...prev };
+  for (const key of Object.keys(next)) {
+    const pv = prev[key];
+    const nv = next[key];
+    if (Array.isArray(pv) && Array.isArray(nv)) {
+      merged[key] = [...pv, ...nv];
+      continue;
+    }
+    if (pv && typeof pv === "object" && !Array.isArray(pv) && nv && typeof nv === "object" && !Array.isArray(nv)) {
+      if (key === "meta") {
+        merged[key] = mergePageOutputs(pv, nv);
+      } else {
+        merged[key] = nv;
+      }
+      continue;
+    }
+    merged[key] = nv;
+  }
+  return merged;
+}
+function buildInfiniteGetLeaf(leaf, rqOpts, env) {
+  const leafCfg = leaf.cfg;
+  const method = toUpper(leaf.method);
+  const expectsArgs = Boolean(leafCfg.paramsSchema || leafCfg.querySchema);
+  const {
+    baseUrl,
+    validateResponses,
+    fetcher,
+    queryClient,
+    emit,
+    decorateDebugEvent,
+    isVerboseDebug,
+    leafLabel
+  } = env;
+  emit({ type: "build", leaf: leafLabel });
+  const infiniteOptions = rqOpts ?? {};
+  const {
+    cursorParam,
+    getNextPageParam,
+    initialPageParam,
+    splitPageSize,
+    splitPageSizeParam,
+    ...passthroughOptions
+  } = infiniteOptions;
+  const feedCursorParam = cursorParam ?? "pagination_cursor";
+  const feedNextPageParam = getNextPageParam ?? ((lastPage) => defaultGetNextCursor(lastPage));
+  const cursorFromPage = (page) => feedNextPageParam(page);
+  const feedInitialPageParam = typeof initialPageParam === "undefined" ? void 0 : initialPageParam;
+  const feedQueryOptions = passthroughOptions;
+  const effectiveSplitPageSize = typeof splitPageSize === "number" && splitPageSize > 0 ? splitPageSize : void 0;
+  const effectiveSplitPageSizeParam = splitPageSizeParam ?? "pageSize";
+  const getQueryKeys = (...tuple) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = a?.query;
+    const qForKey = stripKey(query, feedCursorParam);
+    return buildCacheKey2({
+      leaf,
+      params,
+      query: qForKey
+    });
+  };
+  const invalidateExact = async (...tuple) => {
+    const queryKey = getQueryKeys(...tuple);
+    await queryClient.invalidateQueries({ queryKey, exact: true });
+    emit({ type: "invalidate", key: queryKey, exact: true });
+  };
+  const setData = (...args) => {
+    const [updater, ...rest] = args;
+    const k = getQueryKeys(...rest);
+    const next = queryClient.setQueryData(
+      k,
+      (prev) => typeof updater === "function" ? updater(prev) : updater
+    );
+    emit({ type: "setData", key: k });
+    return next;
+  };
+  const buildOnReceive = rqOpts?.onReceive ?? void 0;
+  const fetchEndpoint = async (tuple, options) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = options?.queryOverride ?? a?.query;
+    const { url, normalizedQuery, normalizedParams } = buildUrl(
+      { ...leaf, cfg: leafCfg },
+      baseUrl,
+      params,
+      query
+    );
+    let payload;
+    const acceptsBody = Boolean(leafCfg.bodySchema);
+    const requiresBody = options?.requireBody ?? (!acceptsBody ? false : true);
+    if (typeof options?.body !== "undefined") {
+      const normalizedBody = leafCfg.bodySchema ? lowProfileParse3(leafCfg.bodySchema, options.body) : void 0;
+      const isMultipart = Array.isArray(leafCfg.bodyFiles) && leafCfg.bodyFiles.length > 0;
+      if (isMultipart && normalizedBody && typeof normalizedBody === "object") {
+        payload = toFormData(normalizedBody);
+      } else {
+        payload = normalizedBody;
+      }
+    } else if (requiresBody && acceptsBody) {
+      throw new Error("Body is required when invoking a mutation fetch.");
+    }
+    const startedAt = Date.now();
+    const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+    emit(
+      decorateDebugEvent(
+        {
+          type: "fetch",
+          stage: "start",
+          method,
+          url,
+          leaf: leafLabel,
+          ...payload !== void 0 ? { body: payload } : {}
+        },
+        detail
+      )
+    );
+    try {
+      const out = await fetcher(
+        payload === void 0 ? { url, method } : { url, method, body: payload }
+      );
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "fetched",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt
+          },
+          isVerboseDebug ? {
+            params: normalizedParams,
+            query: normalizedQuery,
+            output: out
+          } : void 0
+        )
+      );
+      if (validateResponses) {
+        if (!leafCfg.outputSchema) {
+          throw new Error(
+            `No output schema defined for leaf ${leafLabel}, cannot validate response.`
+          );
+        }
+        out.data = lowProfileParse3(
+          leafCfg.outputSchema,
+          out.data
+        );
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "parsed",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            },
+            isVerboseDebug ? {
+              params: normalizedParams,
+              query: normalizedQuery,
+              output: out
+            } : void 0
+          )
+        );
+      }
+      options?.onReceive?.(out.data);
+      return out.data;
+    } catch (error) {
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "error",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt,
+            ...payload !== void 0 ? { body: payload } : {},
+            error
+          },
+          detail
+        )
+      );
+      throw error;
+    }
+  };
+  const fetchGet = (...tupleWithBody) => {
+    const acceptsBody = Boolean(leafCfg.bodySchema);
+    const tupleLength = tupleWithBody.length;
+    const maybeBodyIndex = expectsArgs ? 1 : 0;
+    const hasBodyCandidate = acceptsBody && tupleLength > maybeBodyIndex;
+    const body = hasBodyCandidate ? tupleWithBody[tupleLength - 1] : void 0;
+    const tuple = hasBodyCandidate ? tupleWithBody.slice(0, tupleLength - 1) : tupleWithBody;
+    return fetchEndpoint(tuple, {
+      body,
+      onReceive: buildOnReceive,
+      requireBody: false
+    });
+  };
+  const useEndpoint = (...useArgs) => {
+    const args = useArgs[0];
+    const tuple = toArgsTuple(args);
+    const queryKeys = getQueryKeys(...tuple);
+    emit({
+      type: "useEndpoint",
+      leaf: leafLabel,
+      variant: "infiniteGet",
+      keys: queryKeys
+    });
+    const params = args?.params;
+    const query = args?.query;
+    const buildOptions = feedQueryOptions ?? {};
+    const listenersRef = useRef2(/* @__PURE__ */ new Set());
+    const notifyOnReceive = useCallback2((data) => {
+      buildOptions?.onReceive?.(data);
+      listenersRef.current.forEach((listener) => listener(data));
+    }, []);
+    const registerOnReceive = useCallback2(
+      (listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+          listenersRef.current.delete(listener);
+        };
+      },
+      []
+    );
+    const { normalizedQuery, normalizedParams } = buildUrl(
+      { ...leaf, cfg: leafCfg },
+      baseUrl,
+      params,
+      query
+    );
+    const queryResult = useInfiniteQuery(
+      {
+        ...buildOptions,
+        placeholderData: buildOptions.placeholderData ?? keepPreviousData2,
+        initialPageParam: feedInitialPageParam,
+        getNextPageParam: (lastPage) => cursorFromPage(lastPage),
+        queryKey: queryKeys,
+        queryFn: ({ pageParam }) => {
+          if (!effectiveSplitPageSize) {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...pageParam ? { [feedCursorParam]: pageParam } : {}
+            };
+            return fetchEndpoint(tuple, {
+              queryOverride: pageQuery,
+              onReceive: notifyOnReceive
+            });
+          }
+          const basePageSizeRaw = normalizedQuery?.[effectiveSplitPageSizeParam];
+          const basePageSize = typeof basePageSizeRaw === "number" ? basePageSizeRaw : basePageSizeRaw != null ? Number(basePageSizeRaw) : void 0;
+          if (!basePageSize || !Number.isFinite(basePageSize) || basePageSize <= effectiveSplitPageSize) {
+            const pageQuery = {
+              ...normalizedQuery,
+              ...pageParam ? { [feedCursorParam]: pageParam } : {}
+            };
+            return fetchEndpoint(tuple, {
+              queryOverride: pageQuery,
+              onReceive: notifyOnReceive
+            });
+          }
+          const totalTarget = basePageSize;
+          const pageParamForThisPage = pageParam;
+          const runSplitFetch = async () => {
+            let remaining = totalTarget;
+            let currentCursor = pageParam;
+            let aggregated;
+            while (remaining > 0) {
+              const thisCallSize = Math.min(remaining, effectiveSplitPageSize);
+              const splitQuery = {
+                ...normalizedQuery,
+                ...currentCursor ? { [feedCursorParam]: currentCursor } : {},
+                [effectiveSplitPageSizeParam]: thisCallSize
+              };
+              const page = await fetchEndpoint(tuple, {
+                queryOverride: splitQuery,
+                onReceive: notifyOnReceive
+              });
+              aggregated = aggregated ? mergePageOutputs(aggregated, page) : page;
+              remaining -= thisCallSize;
+              const nextCursor = cursorFromPage(page);
+              currentCursor = nextCursor;
+              const k = queryKeys;
+              queryClient.setQueryData(k, (prev) => {
+                if (!aggregated) return prev;
+                if (!prev) {
+                  return {
+                    pages: [aggregated],
+                    pageParams: [pageParamForThisPage]
+                  };
+                }
+                const idx = prev.pageParams.findIndex(
+                  (p) => p === pageParamForThisPage || p == null && pageParamForThisPage == null
+                );
+                if (idx === -1) {
+                  return {
+                    pages: [...prev.pages, aggregated],
+                    pageParams: [...prev.pageParams, pageParamForThisPage]
+                  };
+                }
+                const newPages = [...prev.pages];
+                newPages[idx] = aggregated;
+                return { ...prev, pages: newPages };
+              });
+              if (!nextCursor) {
+                break;
+              }
+            }
+            return aggregated;
+          };
+          return runSplitFetch();
+        }
+      },
+      queryClient
+    );
+    return { ...queryResult, onReceive: registerOnReceive };
+  };
+  return {
+    getQueryKeys,
+    invalidate: invalidateExact,
+    setData,
+    useEndpoint,
+    fetch: fetchGet
+  };
+}
+
+// src/routesV3.client.mutation.ts
+import { buildCacheKey as buildCacheKey3, lowProfileParse as lowProfileParse4 } from "@emeryld/rrroutes-contract";
+import {
+  useMutation
+} from "@tanstack/react-query";
+import { useCallback as useCallback3, useRef as useRef3 } from "react";
+function buildMutationLeaf(leaf, rqOpts, env) {
+  const leafCfg = leaf.cfg;
+  const method = toUpper(leaf.method);
+  const expectsArgs = Boolean(leafCfg.paramsSchema || leafCfg.querySchema);
+  const {
+    baseUrl,
+    validateResponses,
+    fetcher,
+    queryClient,
+    emit,
+    decorateDebugEvent,
+    isVerboseDebug,
+    leafLabel
+  } = env;
+  emit({ type: "build", leaf: leafLabel });
+  const getQueryKeys = (...tuple) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = a?.query;
+    return buildCacheKey3({
+      leaf,
+      params,
+      query
+    });
+  };
+  const invalidateExact = async (...tuple) => {
+    const queryKey = getQueryKeys(...tuple);
+    await queryClient.invalidateQueries({ queryKey, exact: true });
+    emit({ type: "invalidate", key: queryKey, exact: true });
+  };
+  const setData = (...args) => {
+    const [updater, ...rest] = args;
+    const k = getQueryKeys(...rest);
+    const next = queryClient.setQueryData(
+      k,
+      (prev) => typeof updater === "function" ? updater(prev) : updater
+    );
+    emit({ type: "setData", key: k });
+    return next;
+  };
+  const mutationBuildOptions = rqOpts ?? {};
+  const fetchEndpoint = async (tuple, options) => {
+    const a = extractArgs(tuple);
+    const params = a?.params;
+    const query = options?.queryOverride ?? a?.query;
+    const { url, normalizedQuery, normalizedParams } = buildUrl(
+      { ...leaf, cfg: leafCfg },
+      baseUrl,
+      params,
+      query
+    );
+    let payload;
+    const acceptsBody = Boolean(leafCfg.bodySchema);
+    const requiresBody = options?.requireBody ?? (!acceptsBody ? false : true);
+    if (typeof options?.body !== "undefined") {
+      const normalizedBody = leafCfg.bodySchema ? lowProfileParse4(leafCfg.bodySchema, options.body) : void 0;
+      const isMultipart = Array.isArray(leafCfg.bodyFiles) && leafCfg.bodyFiles.length > 0;
+      if (isMultipart && normalizedBody && typeof normalizedBody === "object") {
+        payload = toFormData(normalizedBody);
+      } else {
+        payload = normalizedBody;
+      }
+    } else if (requiresBody && acceptsBody) {
+      throw new Error("Body is required when invoking a mutation fetch.");
+    }
+    const startedAt = Date.now();
+    const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
+    emit(
+      decorateDebugEvent(
+        {
+          type: "fetch",
+          stage: "start",
+          method,
+          url,
+          leaf: leafLabel,
+          ...payload !== void 0 ? { body: payload } : {}
+        },
+        detail
+      )
+    );
+    try {
+      const out = await fetcher(
+        payload === void 0 ? { url, method } : { url, method, body: payload }
+      );
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "fetched",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt
+          },
+          isVerboseDebug ? {
+            params: normalizedParams,
+            query: normalizedQuery,
+            output: out
+          } : void 0
+        )
+      );
+      if (validateResponses) {
+        if (!leafCfg.outputSchema) {
+          throw new Error(
+            `No output schema defined for leaf ${leafLabel}, cannot validate response.`
+          );
+        }
+        out.data = lowProfileParse4(
+          leafCfg.outputSchema,
+          out.data
+        );
+        emit(
+          decorateDebugEvent(
+            {
+              type: "fetch",
+              stage: "parsed",
+              method,
+              url,
+              leaf: leafLabel,
+              durationMs: Date.now() - startedAt
+            },
+            isVerboseDebug ? {
+              params: normalizedParams,
+              query: normalizedQuery,
+              output: out
+            } : void 0
+          )
+        );
+      }
+      options?.onReceive?.(out.data);
+      return out.data;
+    } catch (error) {
+      emit(
+        decorateDebugEvent(
+          {
+            type: "fetch",
+            stage: "error",
+            method,
+            url,
+            leaf: leafLabel,
+            durationMs: Date.now() - startedAt,
+            ...payload !== void 0 ? { body: payload } : {},
+            error
+          },
+          detail
+        )
+      );
+      throw error;
+    }
+  };
+  const fetchMutation = async (...tupleWithBody) => {
+    if (tupleWithBody.length === 0) {
+      throw new Error("Body is required when invoking a mutation fetch.");
     }
-    params.append(k, JSON.stringify(v));
-  }
-  const s = params.toString();
-  return s ? `?${s}` : "";
-}
-function stripKey(obj, key) {
-  if (!obj) return obj;
-  const { [key]: _omit, ...rest } = obj;
-  return rest;
+    const bodyIndex = tupleWithBody.length - 1;
+    const tuple = tupleWithBody.slice(0, bodyIndex);
+    const body = tupleWithBody[bodyIndex];
+    const result = await fetchEndpoint(tuple, {
+      body,
+      onReceive: (data) => mutationBuildOptions?.onReceive?.(data),
+      requireBody: true
+    });
+    return result;
+  };
+  const useEndpoint = (...useArgs) => {
+    const args = useArgs[0];
+    const tuple = toArgsTuple(args);
+    const mutationKey = getQueryKeys(...tuple);
+    emit({
+      type: "useEndpoint",
+      leaf: leafLabel,
+      variant: "mutation",
+      keys: mutationKey
+    });
+    const listenersRef = useRef3(/* @__PURE__ */ new Set());
+    const notifyListeners = useCallback3((data) => {
+      listenersRef.current.forEach((listener) => listener(data));
+    }, []);
+    const registerOnReceive = useCallback3(
+      (listener) => {
+        listenersRef.current.add(listener);
+        return () => {
+          listenersRef.current.delete(listener);
+        };
+      },
+      []
+    );
+    const mutationResult = useMutation(
+      {
+        ...mutationBuildOptions ?? {},
+        mutationKey,
+        mutationFn: async (body) => {
+          const result = await fetchMutation(
+            ...[...tuple, body]
+          );
+          notifyListeners(result);
+          return result;
+        }
+      },
+      queryClient
+    );
+    return { ...mutationResult, onReceive: registerOnReceive };
+  };
+  return {
+    getQueryKeys,
+    invalidate: invalidateExact,
+    setData,
+    useEndpoint,
+    fetch: fetchMutation
+  };
 }
-var defaultGetNextCursor = (p) => {
-  if (!p || typeof p !== "object") return void 0;
-  const record = p;
-  if ("nextCursor" in record) {
-    return record.nextCursor;
-  }
-  if ("meta" in record) {
-    const meta = record.meta;
-    if (meta && typeof meta === "object" && "nextCursor" in meta) {
-      return meta.nextCursor;
-    }
-  }
-  return void 0;
-};
+
+// src/routesV3.client.ts
 var defaultDebugLogger = (event) => {
   if (typeof console === "undefined") return;
   const fn = console.debug ?? console.log;
@@ -163,22 +1026,6 @@ function createDebugEmitter(option, environment) {
   }
   return disabled;
 }
-function extractArgs(args) {
-  return args[0];
-}
-function toArgsTuple(args) {
-  return typeof args === "undefined" ? [] : [args];
-}
-function buildUrl(leaf, baseUrl, params, query) {
-  const normalizedParams = leaf.cfg.paramsSchema ? lowProfileParse(leaf.cfg.paramsSchema, params) : {};
-  const normalizedQuery = leaf.cfg.querySchema ? lowProfileParse(leaf.cfg.querySchema, query) : {};
-  const path = compilePath(
-    leaf.path,
-    normalizedParams ?? {}
-  );
-  const url = `${baseUrl ?? ""}${path}${toSearchString(normalizedQuery)}`;
-  return { url, normalizedQuery, normalizedParams };
-}
 function createRouteClient(opts) {
   const queryClient = opts.queryClient;
   const fetcher = opts.fetcher ?? defaultFetcher;
@@ -199,365 +1046,41 @@ function createRouteClient(opts) {
     emitDebug({ type: "invalidate", key: queryKey, exact });
   }
   function buildInternal(leaf, rqOpts, meta) {
-    const isGet = leaf.method === "get";
-    const isFeed = !!leaf.cfg.feed;
-    const leafCfg = leaf.cfg;
-    const validateResponses = opts.validateResponses ?? true;
-    const method = toUpper(leaf.method);
-    const expectsArgs = Boolean(leafCfg.paramsSchema || leafCfg.querySchema);
     const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
     const debugName = meta?.name;
     const emit = (event) => emitDebug(event, debugName);
-    emit({ type: "build", leaf: leafLabel });
-    let feedCursorParam = "pagination_cursor";
-    let feedNextPageParam;
-    let feedInitialPageParam;
-    let feedQueryOptions;
+    const isGet = leaf.method === "get";
+    const isFeed = !!leaf.cfg.feed;
+    const validateResponses = opts.validateResponses ?? true;
+    const env = {
+      baseUrl,
+      validateResponses,
+      fetcher,
+      queryClient,
+      emit,
+      decorateDebugEvent,
+      isVerboseDebug,
+      leafLabel
+    };
     if (isGet && isFeed) {
-      const infiniteOptions = rqOpts ?? {};
-      const {
-        cursorParam,
-        getNextPageParam,
-        initialPageParam,
-        ...passthroughOptions
-      } = infiniteOptions;
-      feedCursorParam = cursorParam ?? "pagination_cursor";
-      feedNextPageParam = getNextPageParam ?? ((lastPage) => defaultGetNextCursor(lastPage));
-      feedInitialPageParam = typeof initialPageParam === "undefined" ? void 0 : initialPageParam;
-      feedQueryOptions = passthroughOptions;
-    }
-    const getQueryKeys = (...tuple) => {
-      const a = extractArgs(tuple);
-      const params = a?.params;
-      const query = a?.query;
-      const qForKey = isGet && isFeed ? stripKey(query, feedCursorParam) : query;
-      return buildCacheKey({
+      return buildInfiniteGetLeaf(
         leaf,
-        params,
-        query: qForKey
-      });
-    };
-    const invalidateExact = async (...tuple) => {
-      const queryKey = getQueryKeys(...tuple);
-      await queryClient.invalidateQueries({ queryKey, exact: true });
-      emit({ type: "invalidate", key: queryKey, exact: true });
-    };
-    const setData = (...args) => {
-      const [updater, ...rest] = args;
-      const k = getQueryKeys(...rest);
-      let next;
-      if (isGet && isFeed) {
-        next = queryClient.setQueryData(
-          k,
-          (prev) => typeof updater === "function" ? updater(prev) : updater
-        );
-      } else {
-        next = queryClient.setQueryData(
-          k,
-          (prev) => typeof updater === "function" ? updater(prev) : updater
-        );
-      }
-      emit({ type: "setData", key: k });
-      return next;
-    };
-    const buildOnReceive = rqOpts?.onReceive;
-    const fetchEndpoint = async (tuple, options) => {
-      const a = extractArgs(tuple);
-      const params = a?.params;
-      const query = options?.queryOverride ?? a?.query;
-      const { url, normalizedQuery, normalizedParams } = buildUrl(
-        { ...leaf, cfg: leafCfg },
-        baseUrl,
-        params,
-        query
-      );
-      let payload;
-      const acceptsBody = Boolean(leafCfg.bodySchema);
-      const requiresBody = options?.requireBody ?? (!isGet && acceptsBody);
-      if (typeof options?.body !== "undefined") {
-        const normalizedBody = leafCfg.bodySchema ? lowProfileParse(leafCfg.bodySchema, options.body) : void 0;
-        const isMultipart = Array.isArray(leafCfg.bodyFiles) && leafCfg.bodyFiles.length > 0;
-        if (isMultipart && normalizedBody && typeof normalizedBody === "object") {
-          payload = toFormData(normalizedBody);
-        } else {
-          payload = normalizedBody;
-        }
-      } else if (requiresBody) {
-        throw new Error("Body is required when invoking a mutation fetch.");
-      }
-      const startedAt = Date.now();
-      const detail = isVerboseDebug ? { params: normalizedParams, query: normalizedQuery } : void 0;
-      emit(
-        decorateDebugEvent(
-          {
-            type: "fetch",
-            stage: "start",
-            method,
-            url,
-            leaf: leafLabel,
-            ...payload !== void 0 ? { body: payload } : {}
-          },
-          detail
-        )
+        rqOpts,
+        env
       );
-      try {
-        const out = await fetcher(
-          payload === void 0 ? { url, method } : { url, method, body: payload }
-        );
-        emit(
-          decorateDebugEvent(
-            {
-              type: "fetch",
-              stage: "fetched",
-              method,
-              url,
-              leaf: leafLabel,
-              durationMs: Date.now() - startedAt
-            },
-            isVerboseDebug ? {
-              params: normalizedParams,
-              query: normalizedQuery,
-              output: out
-            } : void 0
-          )
-        );
-        if (validateResponses) {
-          if (!leafCfg.outputSchema) {
-            throw new Error(
-              `No output schema defined for leaf ${leafLabel}, cannot validate response.`
-            );
-          }
-          out.data = lowProfileParse(
-            leafCfg.outputSchema,
-            out.data
-          );
-          emit(
-            decorateDebugEvent(
-              {
-                type: "fetch",
-                stage: "parsed",
-                method,
-                url,
-                leaf: leafLabel,
-                durationMs: Date.now() - startedAt
-              },
-              isVerboseDebug ? {
-                params: normalizedParams,
-                query: normalizedQuery,
-                output: out
-              } : void 0
-            )
-          );
-        }
-        options?.onReceive?.(out.data);
-        return out.data;
-      } catch (error) {
-        emit(
-          decorateDebugEvent(
-            {
-              type: "fetch",
-              stage: "error",
-              method,
-              url,
-              leaf: leafLabel,
-              durationMs: Date.now() - startedAt,
-              ...payload !== void 0 ? { body: payload } : {},
-              error
-            },
-            detail
-          )
-        );
-        throw error;
-      }
-    };
-    const fetchGet = (...tupleWithBody) => {
-      const acceptsBody = Boolean(leafCfg.bodySchema);
-      const tupleLength = tupleWithBody.length;
-      const maybeBodyIndex = expectsArgs ? 1 : 0;
-      const hasBodyCandidate = acceptsBody && tupleLength > maybeBodyIndex;
-      const body = hasBodyCandidate ? tupleWithBody[tupleLength - 1] : void 0;
-      const tuple = hasBodyCandidate ? tupleWithBody.slice(0, tupleLength - 1) : tupleWithBody;
-      return fetchEndpoint(tuple, {
-        body,
-        onReceive: buildOnReceive,
-        requireBody: false
-      });
-    };
-    if (isGet && isFeed) {
-      const useEndpoint2 = (...useArgs) => {
-        const args = useArgs[0];
-        const tuple = toArgsTuple(args);
-        const queryKeys = getQueryKeys(...tuple);
-        emit({
-          type: "useEndpoint",
-          leaf: leafLabel,
-          variant: "infiniteGet",
-          keys: queryKeys
-        });
-        const params = args?.params;
-        const query = args?.query;
-        const buildOptions = feedQueryOptions ?? {};
-        const listenersRef = useRef(/* @__PURE__ */ new Set());
-        const notifyOnReceive = useCallback((data) => {
-          buildOptions?.onReceive?.(data);
-          listenersRef.current.forEach((listener) => listener(data));
-        }, []);
-        const registerOnReceive = useCallback(
-          (listener) => {
-            listenersRef.current.add(listener);
-            return () => {
-              listenersRef.current.delete(listener);
-            };
-          },
-          []
-        );
-        const { normalizedQuery, normalizedParams } = buildUrl(
-          { ...leaf, cfg: leafCfg },
-          baseUrl,
-          params,
-          query
-        );
-        const queryResult = useInfiniteQuery(
-          {
-            ...buildOptions,
-            placeholderData: buildOptions.placeholderData ?? keepPreviousData,
-            initialPageParam: feedInitialPageParam,
-            getNextPageParam: (lastPage) => (feedNextPageParam ?? defaultGetNextCursor)(lastPage),
-            queryKey: queryKeys,
-            queryFn: ({ pageParam }) => {
-              const pageQuery = {
-                ...normalizedQuery,
-                ...pageParam ? { [feedCursorParam]: pageParam } : {}
-              };
-              return fetchEndpoint(tuple, {
-                queryOverride: pageQuery,
-                onReceive: notifyOnReceive
-              });
-            }
-            // NOTE: TData is InfiniteData<T>, so we don't need a select here.
-          },
-          queryClient
-        );
-        return { ...queryResult, onReceive: registerOnReceive };
-      };
-      return {
-        getQueryKeys,
-        invalidate: invalidateExact,
-        setData,
-        useEndpoint: useEndpoint2,
-        fetch: fetchGet
-      };
     }
     if (isGet) {
-      const useEndpoint2 = (...useArgs) => {
-        const args = useArgs[0];
-        const tuple = toArgsTuple(args);
-        const queryKeys = getQueryKeys(...tuple);
-        emit({
-          type: "useEndpoint",
-          leaf: leafLabel,
-          variant: "get",
-          keys: queryKeys
-        });
-        const params = args?.params;
-        const query = args?.query;
-        const buildOptions = rqOpts ?? {};
-        const listenersRef = useRef(/* @__PURE__ */ new Set());
-        const notifyOnReceive = useCallback((data) => {
-          buildOptions?.onReceive?.(data);
-          listenersRef.current.forEach((listener) => listener(data));
-        }, []);
-        const registerOnReceive = useCallback(
-          (listener) => {
-            listenersRef.current.add(listener);
-            return () => {
-              listenersRef.current.delete(listener);
-            };
-          },
-          []
-        );
-        const queryResult = useQuery(
-          {
-            ...buildOptions,
-            queryKey: getQueryKeys(...tuple),
-            placeholderData: keepPreviousData,
-            queryFn: () => fetchEndpoint(tuple, {
-              onReceive: notifyOnReceive
-            })
-          },
-          queryClient
-        );
-        return { ...queryResult, onReceive: registerOnReceive };
-      };
-      return {
-        getQueryKeys,
-        invalidate: invalidateExact,
-        setData,
-        useEndpoint: useEndpoint2,
-        fetch: fetchGet
-      };
-    }
-    const mutationBuildOptions = rqOpts ?? {};
-    const fetchMutation = async (...tupleWithBody) => {
-      if (tupleWithBody.length === 0) {
-        throw new Error("Body is required when invoking a mutation fetch.");
-      }
-      const bodyIndex = tupleWithBody.length - 1;
-      const tuple = tupleWithBody.slice(0, bodyIndex);
-      const body = tupleWithBody[bodyIndex];
-      const result = await fetchEndpoint(tuple, {
-        body,
-        onReceive: (data) => mutationBuildOptions?.onReceive?.(data),
-        requireBody: true
-      });
-      return result;
-    };
-    const useEndpoint = (...useArgs) => {
-      const args = useArgs[0];
-      const tuple = toArgsTuple(args);
-      const mutationKey = getQueryKeys(...tuple);
-      emit({
-        type: "useEndpoint",
-        leaf: leafLabel,
-        variant: "mutation",
-        keys: mutationKey
-      });
-      const listenersRef = useRef(/* @__PURE__ */ new Set());
-      const notifyListeners = useCallback((data) => {
-        listenersRef.current.forEach((listener) => listener(data));
-      }, []);
-      const registerOnReceive = useCallback(
-        (listener) => {
-          listenersRef.current.add(listener);
-          return () => {
-            listenersRef.current.delete(listener);
-          };
-        },
-        []
-      );
-      const mutationResult = useMutation(
-        {
-          ...mutationBuildOptions,
-          mutationKey,
-          mutationFn: async (body) => {
-            const result = await fetchMutation(
-              ...[...tuple, body]
-            );
-            notifyListeners(result);
-            return result;
-          }
-        },
-        queryClient
+      return buildGetLeaf(
+        leaf,
+        rqOpts,
+        env
       );
-      return { ...mutationResult, onReceive: registerOnReceive };
-    };
-    return {
-      getQueryKeys,
-      invalidate: invalidateExact,
-      setData,
-      useEndpoint,
-      fetch: fetchMutation
-    };
+    }
+    return buildMutationLeaf(
+      leaf,
+      rqOpts,
+      env
+    );
   }
   const fetchRaw = async (input) => {
     const { path, method, query, body, params } = input;
@@ -641,81 +1164,6 @@ function buildRouter(routeClient, routes) {
     meta
   ));
 }
-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;
-}
-function getPathParamNames(path) {
-  const names = /* @__PURE__ */ new Set();
-  const re = /:([A-Za-z0-9_]+)/g;
-  let match;
-  while ((match = re.exec(path)) !== null) {
-    names.add(match[1]);
-  }
-  return names;
-}
-function normalizeFlatQuery(query) {
-  if (query == null) return void 0;
-  if (typeof query !== "object" || Array.isArray(query)) {
-    throw new Error("Query must be a plain object (Record<string, string>).");
-  }
-  const result = {};
-  for (const [k, v] of Object.entries(query)) {
-    if (v == null) continue;
-    if (typeof v !== "string") {
-      throw new Error(
-        `Query param "${k}" must be a string; received type "${typeof v}".`
-      );
-    }
-    result[k] = v;
-  }
-  return Object.keys(result).length > 0 ? result : void 0;
-}
-function compileRawPath(path, params) {
-  const placeholders = getPathParamNames(path);
-  if (!params || typeof params !== "object" || Array.isArray(params)) {
-    if (placeholders.size > 0) {
-      throw new Error(
-        `Missing path parameters for "${path}": ${[...placeholders].join(
-          ", "
-        )}`
-      );
-    }
-    return path;
-  }
-  const paramObj = params;
-  const providedNames = new Set(Object.keys(paramObj));
-  for (const name of providedNames) {
-    if (!placeholders.has(name)) {
-      throw new Error(
-        `Unexpected path parameter "${name}" for template "${path}".`
-      );
-    }
-    const value = paramObj[name];
-    if (value != null && (typeof value === "object" || Array.isArray(value))) {
-      throw new Error(
-        `Path parameter "${name}" must be a primitive; received "${typeof value}".`
-      );
-    }
-  }
-  for (const name of placeholders) {
-    if (!providedNames.has(name)) {
-      throw new Error(
-        `Missing value for path parameter "${name}" in template "${path}".`
-      );
-    }
-  }
-  if (placeholders.size === 0) {
-    return path;
-  }
-  return compilePath(path, paramObj);
-}
 
 // src/sockets/socket.client.sys.ts
 import { z } from "zod";