@emeryld/rrroutes-client 2.8.0 → 2.8.1

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

@@ -9,5 +9,5 @@ type BuildBatchBranchDeps = {
     encodeLeafKey: (leaf: AnyLeafLowProfile) => string;
     toArgsTuple: (args: unknown) => unknown[];
 };
-export declare function buildBatchBranch<T extends BuiltLeafMap>(leaves: T, options: BranchBuildOptions, deps: BuildBatchBranchDeps): BuiltBranch<T>;
+export declare function buildBatchBranch<T extends BuiltLeafMap<TError>, TError = unknown>(leaves: T, options: BranchBuildOptions, deps: BuildBatchBranchDeps): BuiltBranch<T, TError>;
 export {};

package/dist/routesV3.client.d.ts

@@ -1,4 +1,4 @@
 import { type AnyLeafLowProfile } from '@emeryld/rrroutes-contract';
 import type { RouteClient, RouteClientOptions, RouterBuilder } from './routesV3.client.types';
-export declare function createRouteClient<Names extends string = string>(opts: RouteClientOptions<Names>): RouteClient<Names>;
-export declare function buildRouter<Routes extends Record<PropertyKey, AnyLeafLowProfile>, Names extends string = string>(routeClient: RouteClient<Names>, routes: Routes): RouterBuilder<Routes, Names>;
+export declare function createRouteClient<Names extends string = string, TError = unknown>(opts: RouteClientOptions<Names>): RouteClient<Names, TError>;
+export declare function buildRouter<Routes extends Record<PropertyKey, AnyLeafLowProfile>, Names extends string = string, TError = unknown>(routeClient: RouteClient<Names, TError>, routes: Routes): RouterBuilder<Routes, Names, TError>;

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

@@ -11,5 +11,5 @@ type GetEnv = {
     isVerboseDebug: boolean;
     leafLabel: string;
 };
-export declare function buildGetLeaf<L extends AnyLeafLowProfile>(leaf: L, rqOpts: QueryBuildOptionsFor<L> | undefined, env: GetEnv): BuiltQuery<L>;
+export declare function buildGetLeaf<L extends AnyLeafLowProfile, TError = unknown>(leaf: L, rqOpts: QueryBuildOptionsFor<L, TError> | undefined, env: GetEnv): BuiltQuery<L, TError>;
 export {};

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

@@ -11,5 +11,5 @@ type InfiniteEnv = {
     isVerboseDebug: boolean;
     leafLabel: string;
 };
-export declare function buildInfiniteGetLeaf<L extends AnyLeafLowProfile>(leaf: L, rqOpts: InfiniteBuildOptionsFor<L> | undefined, env: InfiniteEnv): BuiltInfinite<L>;
+export declare function buildInfiniteGetLeaf<L extends AnyLeafLowProfile, TError = unknown>(leaf: L, rqOpts: InfiniteBuildOptionsFor<L, TError> | undefined, env: InfiniteEnv): BuiltInfinite<L, TError>;
 export {};

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

@@ -11,5 +11,5 @@ type MutationEnv = {
     isVerboseDebug: boolean;
     leafLabel: string;
 };
-export declare function buildMutationLeaf<L extends AnyLeafLowProfile>(leaf: L, rqOpts: MutationBuildOptionsFor<L> | undefined, env: MutationEnv): BuiltMutation<L>;
+export declare function buildMutationLeaf<L extends AnyLeafLowProfile, TError = unknown>(leaf: L, rqOpts: MutationBuildOptionsFor<L, TError> | undefined, env: MutationEnv): BuiltMutation<L, TError>;
 export {};

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

@@ -153,7 +153,7 @@ export type QueryKeysFor<L extends AnyLeafLowProfile, T extends ArgsTuple<L>> =
     QueryFromArgs<L, T> extends undefined ? {} : QueryFromArgs<L, T>
 ]>;
 /** React Query build options specialized for a plain GET leaf. */
-export type QueryBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseQueryOptions<InferOutput<L>, unknown, InferOutput<L>, QueryKey>, 'queryKey' | 'queryFn'> & {
+export type QueryBuildOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseQueryOptions<InferOutput<L>, TError, InferOutput<L>, QueryKey>, 'queryKey' | 'queryFn'> & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 };
@@ -186,36 +186,36 @@ type InfiniteBuildOnlyOptionsFor = {
     splitPageSizeParam?: string;
 };
 /** Build options for feed-style GET leaves (`cfg.feed === true`). */
-export type InfiniteBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseInfiniteQueryOptions<InferOutput<L>, unknown, InfiniteData<InferOutput<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'> & InfiniteFeedCursorOptionsFor<L> & InfiniteBuildOnlyOptionsFor & {
+export type InfiniteBuildOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseInfiniteQueryOptions<InferOutput<L>, TError, InfiniteData<InferOutput<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'> & InfiniteFeedCursorOptionsFor<L> & InfiniteBuildOnlyOptionsFor & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 };
 /** Build options for mutation leaves (non-GET). */
-export type MutationBuildOptionsFor<L extends AnyLeafLowProfile> = Omit<UseMutationOptions<InferOutput<L>, unknown, InferBodyInput<L>, unknown>, 'mutationFn' | 'mutationKey'> & {
+export type MutationBuildOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseMutationOptions<InferOutput<L>, TError, InferBodyInput<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 AnyLeafLowProfile> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteBuildOptionsFor<L> : QueryBuildOptionsFor<L> : MutationBuildOptionsFor<L>;
+export type BuildOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteBuildOptionsFor<L, TError> : QueryBuildOptionsFor<L, TError> : MutationBuildOptionsFor<L, TError>;
 /** React Query call options for `useEndpoint` on plain GET leaves. */
-export type QueryUseEndpointOptionsFor<L extends AnyLeafLowProfile> = Omit<UseQueryOptions<InferOutput<L>, unknown, InferOutput<L>, QueryKey>, 'queryKey' | 'queryFn'> & {
+export type QueryUseEndpointOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseQueryOptions<InferOutput<L>, TError, InferOutput<L>, QueryKey>, 'queryKey' | 'queryFn'> & {
     onReceive?: OnReceive<L>;
 };
 /** React Query call options for `useEndpoint` on feed GET leaves. */
-export type InfiniteUseEndpointOptionsFor<L extends AnyLeafLowProfile> = Omit<UseInfiniteQueryOptions<InferOutput<L>, unknown, InfiniteData<InferOutput<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'> & {
+export type InfiniteUseEndpointOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseInfiniteQueryOptions<InferOutput<L>, TError, InfiniteData<InferOutput<L>>, QueryKey, Cursor>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'> & {
     /** Hook invoked after a successful fetch + validation. */
     onReceive?: OnReceive<L>;
 } & InfiniteFeedCursorOptionsFor<L>;
 /** React Query call options for `useEndpoint` on mutation leaves. */
-export type MutationUseEndpointOptionsFor<L extends AnyLeafLowProfile> = Omit<UseMutationOptions<InferOutput<L>, unknown, InferBodyInput<L>, unknown>, 'mutationFn' | 'mutationKey'> & {
+export type MutationUseEndpointOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = Omit<UseMutationOptions<InferOutput<L>, TError, InferBodyInput<L>, unknown>, 'mutationFn' | 'mutationKey'> & {
     onReceive?: OnReceive<L>;
 };
 /** Runtime hook options narrowed to the method/feed shape of the leaf. */
-export type UseEndpointOptionsFor<L extends AnyLeafLowProfile> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteUseEndpointOptionsFor<L> : QueryUseEndpointOptionsFor<L> : MutationUseEndpointOptionsFor<L>;
-export type UseEndpointArgs<L extends AnyLeafLowProfile> = keyof ArgsFor<L> extends never ? [options?: UseEndpointOptionsFor<L>] : [args: ArgsFor<L>, options?: UseEndpointOptionsFor<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, InferBodyInput<L>, unknown>>;
+export type UseEndpointOptionsFor<L extends AnyLeafLowProfile, TError = unknown> = L['method'] extends 'get' ? L['cfg']['feed'] extends true ? InfiniteUseEndpointOptionsFor<L, TError> : QueryUseEndpointOptionsFor<L, TError> : MutationUseEndpointOptionsFor<L, TError>;
+export type UseEndpointArgs<L extends AnyLeafLowProfile, TError = unknown> = keyof ArgsFor<L> extends never ? [options?: UseEndpointOptionsFor<L, TError>] : [args: ArgsFor<L>, options?: UseEndpointOptionsFor<L, TError>];
+export type QueryUseEndpointResultFor<L extends AnyLeafLowProfile, TError = unknown> = UseEndpointResult<L, UseQueryResult<InferOutput<L>, TError>>;
+export type InfiniteUseEndpointResultFor<L extends AnyLeafLowProfile, TError = unknown> = UseEndpointResult<L, UseInfiniteQueryResult<InfiniteData<InferOutput<L>>, TError>>;
+export type MutationUseEndpointResultFor<L extends AnyLeafLowProfile, TError = unknown> = UseEndpointResult<L, UseMutationResult<InferOutput<L>, TError, InferBodyInput<L>, unknown>>;
 /** Shared capabilities exposed by every built endpoint helper. */
 export type BuiltCommon<L extends AnyLeafLowProfile> = {
     /**
@@ -237,12 +237,12 @@ export type BuiltCommon<L extends AnyLeafLowProfile> = {
     setData: (...args: SetDataArgs<L>) => DataShape<L> | undefined;
 };
 /** Hook+helpers for a standard GET endpoint. */
-export type BuiltQuery<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
+export type BuiltQuery<L extends AnyLeafLowProfile, TError = unknown> = BuiltCommon<L> & {
     /**
      * React hook bound to the GET leaf.
      * @param args Optional params/query args, followed by optional React Query options.
      */
-    useEndpoint: (...args: UseEndpointArgs<L>) => QueryUseEndpointResultFor<L>;
+    useEndpoint: (...args: UseEndpointArgs<L, TError>) => QueryUseEndpointResultFor<L, TError>;
     /**
      * Direct fetch helper mirroring the query hook without touching the cache.
      * @param args Optional params/query tuple for the leaf.
@@ -250,12 +250,12 @@ export type BuiltQuery<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
     fetch: (...args: QueryFetchArgs<L>) => Promise<InferOutput<L>>;
 };
 /** Hook+helpers for a cursor-paginated GET endpoint. */
-export type BuiltInfinite<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
+export type BuiltInfinite<L extends AnyLeafLowProfile, TError = unknown> = BuiltCommon<L> & {
     /**
      * React hook bound to an infinite GET leaf.
      * @param args Optional params/query args, followed by optional React Query options.
      */
-    useEndpoint: (...args: UseEndpointArgs<L>) => InfiniteUseEndpointResultFor<L>;
+    useEndpoint: (...args: UseEndpointArgs<L, TError>) => InfiniteUseEndpointResultFor<L, TError>;
     /**
      * Direct fetch helper for a single page of the feed (pass cursor in query args).
      * @param args Optional params/query tuple for the leaf.
@@ -263,12 +263,12 @@ export type BuiltInfinite<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
     fetch: (...args: QueryFetchArgs<L>) => Promise<InferOutput<L>>;
 };
 /** Hook+helpers for non-GET endpoints (mutations). */
-export type BuiltMutation<L extends AnyLeafLowProfile> = BuiltCommon<L> & {
+export type BuiltMutation<L extends AnyLeafLowProfile, TError = unknown> = BuiltCommon<L> & {
     /**
      * React hook bound to a mutation leaf.
      * @param args Optional params/query args, followed by optional React Query options.
      */
-    useEndpoint: (...args: UseEndpointArgs<L>) => MutationUseEndpointResultFor<L>;
+    useEndpoint: (...args: UseEndpointArgs<L, TError>) => MutationUseEndpointResultFor<L, TError>;
     /**
      * Direct fetch helper that bypasses React Query, useful for server actions or scripts.
      * Pass params/query first (if required), followed by the body payload.
@@ -282,58 +282,58 @@ type BuiltLeafMetadata<L extends AnyLeafLowProfile> = {
     };
 };
 /** Type-safe union that resolves to the correct built helper for a leaf. */
-export type BuiltForLeaf<L extends AnyLeafLowProfile> = (L['method'] extends 'get' ? L['cfg']['feed'] extends true ? BuiltInfinite<L> : BuiltQuery<L> : BuiltMutation<L>) & BuiltLeafMetadata<L>;
+export type BuiltForLeaf<L extends AnyLeafLowProfile, TError = unknown> = (L['method'] extends 'get' ? L['cfg']['feed'] extends true ? BuiltInfinite<L, TError> : BuiltQuery<L, TError> : BuiltMutation<L, TError>) & BuiltLeafMetadata<L>;
 type LeafFromBuilt<B> = B extends BuiltForLeaf<infer L> ? L : AnyLeafLowProfile;
 type SetDataUpdaterFromBuilt<B> = B extends {
     setData: (updater: infer U, ...args: any[]) => any;
 } ? U : never;
-export type BuiltLeafLike = {
+export type BuiltLeafLike<TError = unknown> = {
     getQueryKeys: (...args: any[]) => any;
     invalidate: (...args: any[]) => Promise<void>;
     setData: (...args: any[]) => any;
     useEndpoint: (...args: any[]) => any;
     fetch: (...args: any[]) => Promise<any>;
 };
-export type BuiltLeafMap = Record<string, BuiltLeafLike>;
+export type BuiltLeafMap<TError = unknown> = Record<string, BuiltLeafLike<TError>>;
 /** Per-leaf request shape sent to the batch endpoint. */
 export type BranchFetchInputForLeaf<L extends AnyLeafLowProfile> = Prettify<(keyof ArgsFor<L> extends never ? {} : ArgsFor<L>) & (InferBodyInput<L> extends never ? {} : {
     body?: InferBodyInput<L>;
 })>;
 /** Input payload keyed by alias for branch.fetch/useEndpoint calls. */
-export type BranchFetchInput<T extends BuiltLeafMap> = {
+export type BranchFetchInput<T extends BuiltLeafMap<any>> = {
     [K in keyof T]: BranchFetchInputForLeaf<LeafFromBuilt<T[K]>>;
 };
 /** Optional args map for cache-key/invalidation helpers across a branch. */
-export type BranchArgsInput<T extends BuiltLeafMap> = Partial<{
+export type BranchArgsInput<T extends BuiltLeafMap<any>> = Partial<{
     [K in keyof T]: ArgsFor<LeafFromBuilt<T[K]>>;
 }>;
 /** Branch fetch output keyed by alias. */
-export type BranchFetchOutput<T extends BuiltLeafMap> = {
+export type BranchFetchOutput<T extends BuiltLeafMap<any>> = {
     [K in keyof T]: Awaited<ReturnType<T[K]['fetch']>>;
 };
 /** Per-leaf query keys keyed by alias. */
-export type BranchQueryKeysOutput<T extends BuiltLeafMap> = {
+export type BranchQueryKeysOutput<T extends BuiltLeafMap<any>> = {
     [K in keyof T]: ReturnType<T[K]['getQueryKeys']>;
 };
 /** Input payload for branch.setData keyed by alias. */
-export type BranchSetDataInput<T extends BuiltLeafMap> = Partial<{
+export type BranchSetDataInput<T extends BuiltLeafMap<any>> = Partial<{
     [K in keyof T]: {
         updater: SetDataUpdaterFromBuilt<T[K]>;
         args?: ArgsFor<LeafFromBuilt<T[K]>>;
     };
 }>;
 /** Output of branch.setData keyed by alias. */
-export type BranchSetDataOutput<T extends BuiltLeafMap> = Partial<{
+export type BranchSetDataOutput<T extends BuiltLeafMap<any>> = Partial<{
     [K in keyof T]: ReturnType<T[K]['setData']>;
 }>;
-type BranchOnReceive<T extends BuiltLeafMap> = (data: BranchFetchOutput<T>) => void;
-type BranchOnReceiveRegistrar<T extends BuiltLeafMap> = (listener: BranchOnReceive<T>) => () => void;
+type BranchOnReceive<T extends BuiltLeafMap<any>> = (data: BranchFetchOutput<T>) => void;
+type BranchOnReceiveRegistrar<T extends BuiltLeafMap<any>> = (listener: BranchOnReceive<T>) => () => void;
 /** React Query options for branch.useEndpoint. */
-export type BranchUseEndpointOptions<T extends BuiltLeafMap> = Omit<UseQueryOptions<BranchFetchOutput<T>, unknown, BranchFetchOutput<T>, QueryKey>, 'queryKey' | 'queryFn'> & {
+export type BranchUseEndpointOptions<T extends BuiltLeafMap<any>, TError = unknown> = Omit<UseQueryOptions<BranchFetchOutput<T>, TError, BranchFetchOutput<T>, QueryKey>, 'queryKey' | 'queryFn'> & {
     onReceive?: BranchOnReceive<T>;
 };
 /** Result returned by branch.useEndpoint. */
-export type BranchUseEndpointResult<T extends BuiltLeafMap> = UseQueryResult<BranchFetchOutput<T>, unknown> & {
+export type BranchUseEndpointResult<T extends BuiltLeafMap<any>, TError = unknown> = UseQueryResult<BranchFetchOutput<T>, TError> & {
     onReceive: BranchOnReceiveRegistrar<T>;
 };
 /** Configuration for branch helpers that call a server batch endpoint. */
@@ -346,15 +346,15 @@ export type BranchBuildOptions = {
     headers?: Record<string, string>;
 };
 /** Batched helper surface built from a record of built endpoints. */
-export type BuiltBranch<T extends BuiltLeafMap> = {
+export type BuiltBranch<T extends BuiltLeafMap<any>, TError = unknown> = {
     fetch: (input: BranchFetchInput<T>) => Promise<BranchFetchOutput<T>>;
-    useEndpoint: (input: BranchFetchInput<T>, options?: BranchUseEndpointOptions<T>) => BranchUseEndpointResult<T>;
+    useEndpoint: (input: BranchFetchInput<T>, options?: BranchUseEndpointOptions<T, TError>) => BranchUseEndpointResult<T, TError>;
     getQueryKeys: (input?: BranchArgsInput<T>) => BranchQueryKeysOutput<T>;
     invalidate: (input?: BranchArgsInput<T>) => Promise<void>;
     setData: (input: BranchSetDataInput<T>) => BranchSetDataOutput<T>;
 };
 /** Public surface returned by `createRouteClient`. */
-export type RouteClient<Names extends string = string> = {
+export type RouteClient<Names extends string = string, TError = unknown> = {
     /**
      * Invalidate by a key prefix (e.g., ['get','api','users']).
      * @param prefix Key parts shared by matching endpoints.
@@ -362,11 +362,11 @@ export type RouteClient<Names extends string = string> = {
      */
     invalidate: (prefix: string[], exact?: boolean) => Promise<void>;
     /** Build a typed endpoint from a leaf. */
-    build: <L extends AnyLeafLowProfile>(leaf: L, opts?: BuildOptionsFor<L>, 
+    build: <L extends AnyLeafLowProfile>(leaf: L, opts?: BuildOptionsFor<L, TError>, 
     /** Optional metadata (third arg) to assign a debug name for filtering via `debug.only`. */
-    meta?: BuildMeta<Names>) => BuiltForLeaf<L>;
+    meta?: BuildMeta<Names>) => BuiltForLeaf<L, TError>;
     /** Build a batched helper from already-built endpoint helpers. */
-    buildBranch: <T extends BuiltLeafMap>(leaves: T, options: BranchBuildOptions) => BuiltBranch<T>;
+    buildBranch: <T extends BuiltLeafMap<TError>>(leaves: T, options: BranchBuildOptions) => BuiltBranch<T, TError>;
     /** Underlying React Query client (exposed for advanced scenarios). */
     queryClient: QueryClient;
     /**
@@ -379,7 +379,7 @@ export type RouteClient<Names extends string = string> = {
  * 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, AnyLeafLowProfile>, 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, TError = unknown> = <K extends keyof Routes>(key: K, opts?: BuildOptionsFor<Routes[K], TError>, meta?: BuildMeta<Names>) => BuiltForLeaf<Routes[K], TError>;
 /**
  * Arguments for the low-level RouteClient.fetch helper.
  * This is intentionally NOT tied to AnyLeafLowProfile.

package/package.json

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