@emeryld/rrroutes-client 2.2.14 → 2.2.16

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

@@ -1,5 +1,5 @@
+import type { AnyLeafLowProfile, HttpMethod, InferBody, InferOutput, InferParams, InferQuery, Prettify } from '@emeryld/rrroutes-contract';
 import type { InfiniteData, QueryClient, QueryKey, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
-import type { AnyLeaf, HttpMethod, InferBody, InferOutput, InferParams, InferQuery, Prettify } from '@emeryld/rrroutes-contract';
 /** Helper type used when setting React Query cache data. */
 export type Updater<T> = T | ((prev: T | undefined) => T | undefined) | undefined;
 /** Cursor string extracted from paginated endpoints. */
@@ -97,21 +97,20 @@ export type RouteClientOptions<Names extends string = string> = {
      */
     environment?: RouteClientEnvironment;
 };
-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>;
-type OnReceive<L extends AnyLeaf> = (data: OutputOf<L>) => void;
-type OnReceiveRegistrar<L extends AnyLeaf> = (listener: OnReceive<L>) => () => void;
-type UseEndpointResult<L extends AnyLeaf, Result> = Result & {
+type OnReceive<L extends AnyLeafLowProfile> = (data: InferOutput<L>) => void;
+type OnReceiveRegistrar<L extends AnyLeafLowProfile> = (listener: OnReceive<L>) => () => void;
+type UseEndpointResult<L extends AnyLeafLowProfile, Result> = Result & {
     onReceive: OnReceiveRegistrar<L>;
 };
 /** Variadic args consumed by the direct fetch helper: optional args + body. */
-export type MutationFetchArgs<L extends AnyLeaf> = Prettify<[...ArgsTuple<L>, BodyOf<L>]>;
+export type MutationFetchArgs<L extends AnyLeafLowProfile> = Prettify<[
+    ...ArgsTuple<L>,
+    InferBody<L>
+]>;
 /** Signature for the fetch helper returned by mutation builds. */
-export type MutationFetcher<L extends AnyLeaf> = (...args: MutationFetchArgs<L>) => Promise<OutputOf<L>>;
+export type MutationFetcher<L extends AnyLeafLowProfile> = (...args: MutationFetchArgs<L>) => Promise<InferOutput<L>>;
 /** Fetch args for GET endpoints (optionally include a body when a schema exists). */
-type QueryFetchArgs<L extends AnyLeaf> = BodyOf<L> extends never ? ArgsTuple<L> : Prettify<ArgsTuple<L> | [...ArgsTuple<L>, BodyOf<L>]>;
+type QueryFetchArgs<L extends AnyLeafLowProfile> = InferBody<L> extends never ? ArgsTuple<L> : Prettify<ArgsTuple<L> | [...ArgsTuple<L>, InferBody<L>]>;
 /** Optional metadata provided when building a helper (used for debug filtering). */
 export type BuildMeta<Names extends string = string> = {
     /**
@@ -121,57 +120,60 @@ export type BuildMeta<Names extends string = string> = {
     name?: Names;
 };
 /** Object shape the user passes to hooks and helpers (params/query are optional). */
-export type ArgsFor<L extends AnyLeaf> = Prettify<(ParamsOf<L> extends never ? {} : {
-    params: ParamsOf<L>;
-}) & (QueryOf<L> extends never ? {} : {
-    query: QueryOf<L>;
+export type ArgsFor<L extends AnyLeafLowProfile> = Prettify<(InferParams<L> extends never ? {} : {
+    params: InferParams<L>;
+}) & (InferQuery<L> extends never ? {} : {
+    query: InferQuery<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>];
+export type ArgsTuple<L extends AnyLeafLowProfile> = 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>;
-type ArgsFromTuple<L extends AnyLeaf, T extends ArgsTuple<L>> = T extends [infer A] ? A : undefined;
-type ParamsFromArgs<L extends AnyLeaf, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
+export type DataShape<L extends AnyLeafLowProfile> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteData<InferOutput<L>> : InferOutput<L> : InferOutput<L>;
+type ArgsFromTuple<L extends AnyLeafLowProfile, T extends ArgsTuple<L>> = T extends [infer A] ? A : undefined;
+type ParamsFromArgs<L extends AnyLeafLowProfile, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
     params: infer P;
 } ? P : undefined;
-type SetDataArgs<L extends AnyLeaf> = Prettify<[updater: Updater<DataShape<L>>, ...ArgsTuple<L>]>;
-type QueryFromArgs<L extends AnyLeaf, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
+type SetDataArgs<L extends AnyLeafLowProfile> = Prettify<[
+    updater: Updater<DataShape<L>>,
+    ...ArgsTuple<L>
+]>;
+type QueryFromArgs<L extends AnyLeafLowProfile, T extends ArgsTuple<L>> = ArgsFromTuple<L, T> extends {
     query: infer Q;
 } ? Q : undefined;
 /** Typed query key array derived from the leaf plus the specific args passed in. */
 type SplitUrl<L extends string> = L extends `/${infer A}` ? SplitUrl<A> : L extends `${infer A}/${infer B}` ? [A, ...SplitUrl<B>] : [L];
-type MapParams<P extends any[], Params> = P extends [infer A, ...infer Rest] ? A extends `:${infer Key}` ? [Params extends Record<Key, infer V> ? string extends V ? A : V : A, ...MapParams<Rest, Params>] : [
-    A,
+type MapParams<P extends any[], Params> = P extends [infer A, ...infer Rest] ? A extends `:${infer Key}` ? [
+    Params extends Record<Key, infer V> ? (string extends V ? A : V) : A,
     ...MapParams<Rest, Params>
-] : [];
-export type QueryKeysFor<L extends AnyLeaf, T extends ArgsTuple<L>> = Prettify<readonly [
+] : [A, ...MapParams<Rest, Params>] : [];
+export type QueryKeysFor<L extends AnyLeafLowProfile, T extends ArgsTuple<L>> = Prettify<readonly [
     L['method'],
     ...MapParams<SplitUrl<L['path']>, ParamsFromArgs<L, T>>,
     QueryFromArgs<L, T> extends undefined ? {} : QueryFromArgs<L, T>
 ]>;
 /** 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'> & {
+export type QueryBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseQueryOptions<InferOutput<L>, unknown, InferOutput<L>, QueryKey>, 'queryKey' | 'queryFn'> & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 };
 /** 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'> & {
+export type InfiniteBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseInfiniteQueryOptions<InferOutput<L>, unknown, InfiniteData<InferOutput<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'initialPageParam' | 'getNextPageParam'> & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 };
 /** Build options for mutation leaves (non-GET). */
-export type MutationBuildOptionsFor<L extends AnyLeaf> = Omit<UseMutationOptions<OutputOf<L>, unknown, BodyOf<L>, unknown>, 'mutationFn' | 'mutationKey'> & {
+export type MutationBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseMutationOptions<InferOutput<L>, unknown, InferBody<L>, unknown>, 'mutationFn' | 'mutationKey'> & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 };
 /** Build options narrowed to the method/feed shape of the leaf. */
-export type BuildOptionsFor<L extends AnyLeaf> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteBuildOptionsFor<L> : QueryBuildOptionsFor<L> : MutationBuildOptionsFor<L>;
-export type UseEndpointArgs<L extends AnyLeaf> = ArgsTuple<L>;
-export type QueryUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseQueryResult<OutputOf<L>, unknown>>;
-export type InfiniteUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseInfiniteQueryResult<InfiniteData<OutputOf<L>>, unknown>>;
-export type MutationUseEndpointResultFor<L extends AnyLeaf> = UseEndpointResult<L, UseMutationResult<OutputOf<L>, unknown, BodyOf<L>, unknown>>;
+export type BuildOptionsFor<L extends AnyLeafLowProfile> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteBuildOptionsFor<L> : QueryBuildOptionsFor<L> : MutationBuildOptionsFor<L>;
+export type UseEndpointArgs<L extends AnyLeafLowProfile> = ArgsTuple<L>;
+export type QueryUseEndpointResultFor<L extends AnyLeafLowProfile> = UseEndpointResult<L, UseQueryResult<InferOutput<L>, unknown>>;
+export type InfiniteUseEndpointResultFor<L extends AnyLeafLowProfile> = UseEndpointResult<L, UseInfiniteQueryResult<InfiniteData<InferOutput<L>>, unknown>>;
+export type MutationUseEndpointResultFor<L extends AnyLeafLowProfile> = UseEndpointResult<L, UseMutationResult<InferOutput<L>, unknown, InferBody<L>, unknown>>;
 /** Shared capabilities exposed by every built endpoint helper. */
-export type BuiltCommon<L extends AnyLeaf> = {
+export type BuiltCommon<L extends AnyLeafLowProfile> = {
     /**
      * Deterministic key (infinite keys omit the cursor by design).
      * @param args Optional params/query tuple for the leaf.
@@ -191,7 +193,7 @@ export type BuiltCommon<L extends AnyLeaf> = {
     setData: (...args: SetDataArgs<L>) => DataShape<L> | undefined;
 };
 /** Hook+helpers for a standard GET endpoint. */
-export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
+export type BuiltQuery<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
     /**
      * React hook bound to the GET leaf.
      * @param args Optional params/query tuple for the leaf.
@@ -201,10 +203,10 @@ export type BuiltQuery<L extends AnyLeaf> = BuiltCommon<L> & {
      * Direct fetch helper mirroring the query hook without touching the cache.
      * @param args Optional params/query tuple for the leaf.
      */
-    fetch: (...args: QueryFetchArgs<L>) => Promise<OutputOf<L>>;
+    fetch: (...args: QueryFetchArgs<L>) => Promise<InferOutput<L>>;
 };
 /** Hook+helpers for a cursor-paginated GET endpoint. */
-export type BuiltInfinite<L extends AnyLeaf> = BuiltCommon<L> & {
+export type BuiltInfinite<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
     /**
      * React hook bound to an infinite GET leaf.
      * @param args Optional params/query tuple for the leaf.
@@ -214,10 +216,10 @@ export type BuiltInfinite<L extends AnyLeaf> = BuiltCommon<L> & {
      * Direct fetch helper for a single page of the feed (pass cursor in query args).
      * @param args Optional params/query tuple for the leaf.
      */
-    fetch: (...args: QueryFetchArgs<L>) => Promise<OutputOf<L>>;
+    fetch: (...args: QueryFetchArgs<L>) => Promise<InferOutput<L>>;
 };
 /** Hook+helpers for non-GET endpoints (mutations). */
-export type BuiltMutation<L extends AnyLeaf> = BuiltCommon<L> & {
+export type BuiltMutation<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
     /**
      * React hook bound to a mutation leaf.
      * @param args Optional params/query tuple for the leaf.
@@ -230,7 +232,7 @@ export type BuiltMutation<L extends AnyLeaf> = BuiltCommon<L> & {
     fetch: MutationFetcher<L>;
 };
 /** 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>;
+export type BuiltForLeaf<L extends AnyLeafLowProfile> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L> : BuiltMutation<L>;
 /** Public surface returned by `createRouteClient`. */
 export type RouteClient<Names extends string = string> = {
     /**
@@ -240,15 +242,56 @@ export type RouteClient<Names extends string = string> = {
      */
     invalidate: (prefix: string[], exact?: boolean) => Promise<void>;
     /** Build a typed endpoint from a leaf. */
-    build: <L extends AnyLeaf>(leaf: L, opts?: BuildOptionsFor<L>, 
+    build: <L extends AnyLeafLowProfile>(leaf: L, opts?: BuildOptionsFor<L>, 
     /** Optional metadata (third arg) to assign a debug name for filtering via `debug.only`. */
     meta?: BuildMeta<Names>) => BuiltForLeaf<L>;
     /** Underlying React Query client (exposed for advanced scenarios). */
     queryClient: QueryClient;
+    /**
+     * Low-level fetch helper that does not depend on a leaf definition.
+     * Handles path param interpolation and enforces flat string query objects.
+     */
+    fetch: RouteClientFetch;
 };
 /**
  * Helper signature returned by `buildRouter`, enabling lookups by name instead of leaves.
  * Accepts the same build options/meta the underlying client does, narrowed per leaf shape.
  */
-export type RouterBuilder<Routes extends Record<PropertyKey, AnyLeaf>, Names extends string = string> = <K extends keyof Routes>(key: K, opts?: BuildOptionsFor<Routes[K]>, meta?: BuildMeta<Names>) => BuiltForLeaf<Routes[K]>;
+export type RouterBuilder<Routes extends Record<PropertyKey, AnyLeafLowProfile>, Names extends string = string> = <K extends keyof Routes>(key: K, opts?: BuildOptionsFor<Routes[K]>, meta?: BuildMeta<Names>) => BuiltForLeaf<Routes[K]>;
+/**
+ * Arguments for the low-level RouteClient.fetch helper.
+ * This is intentionally NOT tied to AnyLeafLowProfile.
+ */
+export type RouteClientFetchArgs = {
+    /**
+     * Route template or concrete path, e.g. "/api/users/:id".
+     * Params from `params` will be interpolated into any `:name` segments.
+     */
+    path: string;
+    /**
+     * HTTP method. Can be provided as lowercase (HttpMethod) or uppercase;
+     * the client normalizes it to uppercase internally.
+     */
+    method: HttpMethod | Uppercase<HttpMethod>;
+    /**
+     * Flat query string object. Only string values are allowed.
+     * Nested objects/arrays will cause a runtime error in the client.
+     */
+    query?: Record<string, string>;
+    /**
+     * Path parameters used to fill `:name` segments in the `path`.
+     * Extra keys that do not match a path segment, or non-primitive values,
+     * will cause a runtime error in the client.
+     */
+    params?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * Optional request body (already normalized by the caller).
+     */
+    body?: unknown;
+};
+/**
+ * Signature of the low-level RouteClient.fetch helper.
+ * Callers may specify a response type parameter if desired.
+ */
+export type RouteClientFetch = (args: RouteClientFetchArgs) => Promise<any>;
 export {};

package/dist/sockets/socket.client.index.d.ts

@@ -1,6 +1,6 @@
-import type { EventMap, SocketConnectionConfigOutput, Payload, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
-import type { MaybeSocket, SysEventMap } from './socket.client.sys';
+import type { EventMap, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import { SocketClientDebugEvent } from './socket.client.debug';
+import type { MaybeSocket, SysEventMap } from './socket.client.sys';
 export type ServerEnvelope<T extends EventMap, K extends keyof T & string> = {
     eventName: K;
     sentAt: string | Date;

package/dist/sockets/socketedRoute/socket.client.helper.d.ts

@@ -1,12 +1,12 @@
-import type { AnyLeaf, EventMap, InferOutput, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
+import type { AnyLeafLowProfile, EventMap, InferOutput, Payload, SocketConnectionConfigOutput, SocketSchemaOutput } from '@emeryld/rrroutes-contract';
 import type { BuiltInfinite, BuiltQuery, DataShape, InfiniteUseEndpointResultFor, QueryUseEndpointResultFor, UseEndpointArgs } from '../../routesV3.client.types';
 import type { ClientCtx, ServerEnvelope, SocketClient } from '../socket.client.index';
 type RoomsInput = string | string[] | undefined | null;
-type SocketedBuilt<L extends AnyLeaf> = L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L>;
-type SocketedRouteResult<L extends AnyLeaf> = (L['cfg']['feed'] extends true ? InfiniteUseEndpointResultFor<L> : QueryUseEndpointResultFor<L>) & {
+type SocketedBuilt<L extends AnyLeafLowProfile> = L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L>;
+type SocketedRouteResult<L extends AnyLeafLowProfile> = (L['cfg']['feed'] extends true ? InfiniteUseEndpointResultFor<L> : QueryUseEndpointResultFor<L>) & {
     rooms: string[];
 };
-export type SocketedRouteOptions<L extends AnyLeaf, Events extends EventMap, C extends SocketConnectionConfigOutput> = {
+export type SocketedRouteOptions<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput> = {
     built: SocketedBuilt<L>;
     toRooms: (data: InferOutput<L>) => {
         rooms: RoomsInput;
@@ -26,5 +26,5 @@ export type SocketedRouteOptions<L extends AnyLeaf, Events extends EventMap, C e
  * - joins/leaves rooms derived from the endpoint data
  * - subscribes to a socket event and applies messages to the cache
  */
-export declare function buildSocketedRoute<L extends AnyLeaf, Events extends EventMap, C extends SocketConnectionConfigOutput>(options: SocketedRouteOptions<L, Events, C>): (...useArgs: UseEndpointArgs<L>) => SocketedRouteResult<L>;
+export declare function buildSocketedRoute<L extends AnyLeafLowProfile, Events extends EventMap, C extends SocketConnectionConfigOutput>(options: SocketedRouteOptions<L, Events, C>): (...useArgs: UseEndpointArgs<L>) => SocketedRouteResult<L>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emeryld/rrroutes-client",
-  "version": "2.2.14",
+  "version": "2.2.16",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@emeryld/rrroutes-contract": "^2.1.9",
-    "zod": "^4.1.12"
+    "@emeryld/rrroutes-contract": "^2.3.9",
+    "zod": "^4.1.13"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.87.4",