@orpc/tanstack-query 1.14.10 → 1.14.11

package/dist/index.d.mts

@@ -1,14 +1,16 @@
-import { ClientContext, Client, NestedClient } from '@orpc/client';
-import { Promisable, SetOptional, PartialDeep, MaybeOptionalOptions } from '@orpc/shared';
-import { QueryKey, QueryFunctionContext, QueryFunction, SkipToken, QueryObserverOptions, InfiniteQueryObserverOptions, MutationObserverOptions, DataTag, InfiniteData } from '@tanstack/query-core';
+import { ClientContext, Client, AnyNestedClient, InferClientContext, InferClientError } from '@orpc/client';
+import { RouterContract, RouterContractClient, ContractClientFactory, AnySchema, ErrorMap, MetaPlugin, Meta, InferSchemaInput, InferSchemaOutput, ORPCErrorFromErrorMap } from '@orpc/contract';
+import { JsonifiedClient } from '@orpc/openapi';
+import { Promisable, PartialDeep, Interceptor, PromiseWithError, MaybeOptionalOptions, OrderablePlugin, Public, ThrowableError } from '@orpc/shared';
+import { QueryKey, QueryFunctionContext, QueryFunction, SkipToken, QueryObserverOptions, InfiniteQueryObserverOptions, MutationObserverOptions, DataTag, InfiniteData, MutationFunctionContext } from '@tanstack/query-core';
 
-interface experimental_SerializableStreamedQueryOptions {
+interface SerializableStreamedQueryOptions {
     /**
-     * Determines how data is handled when the query is refetched.
+     * Determines how data is handled when the query is fetched again
      *
-     * - `'reset'`: Clears existing data and sets the query back to a pending state.
-     * - `'append'`: Appends new data chunks to the existing data.
-     * - `'replace'`: Collects all streamed data and replaces the cache once the stream finishes.
+     * - `'reset'`: Clears existing data and returns the query to a pending state.
+     * - `'append'`: Adds new streamed chunks to the existing data.
+     * - `'replace'`: Buffers streamed data and replaces the cache after the stream completes.
      *
      * @default 'reset'
      */
@@ -26,17 +28,11 @@ interface experimental_SerializableStreamedQueryOptions {
  * - Options are serializable
  * - The output is predictable
  */
-declare function experimental_serializableStreamedQuery<TQueryFnData = unknown, TQueryKey extends QueryKey = QueryKey>(queryFn: (context: QueryFunctionContext<TQueryKey>) => Promisable<AsyncIterable<TQueryFnData>>, { refetchMode, maxChunks }?: experimental_SerializableStreamedQueryOptions): QueryFunction<Array<TQueryFnData>, TQueryKey>;
+declare function serializableStreamedQuery<TQueryFnData = unknown, TQueryKey extends QueryKey = QueryKey>(queryFn: (context: QueryFunctionContext<TQueryKey>) => Promisable<AsyncIterable<TQueryFnData>>, { refetchMode, maxChunks }?: SerializableStreamedQueryOptions): QueryFunction<TQueryFnData[], TQueryKey>;
 
-type experimental_StreamedQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U[] : never;
-type experimental_LiveQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U : never;
+type InferStreamedQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U[] : never;
+type InferLiveQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U : never;
 type OperationType = 'query' | 'streamed' | 'live' | 'infinite' | 'mutation';
-type OperationKeyOptions<TType extends OperationType, TInput> = {
-    type?: TType;
-    input?: TType extends 'mutation' ? never : PartialDeep<TInput>;
-    fnOptions?: TType extends 'streamed' ? experimental_SerializableStreamedQueryOptions : never;
-};
-type OperationKey<TType extends OperationType, TInput> = [path: readonly string[], options: OperationKeyOptions<TType, TInput>];
 declare const OPERATION_CONTEXT_SYMBOL: unique symbol;
 interface OperationContext {
     [OPERATION_CONTEXT_SYMBOL]?: {
@@ -48,229 +44,393 @@ type QueryKeyOptions<TInput> = (undefined extends TInput ? {
     input?: TInput | SkipToken;
 } : {
     input: TInput | SkipToken;
-}) & {
-    queryKey?: QueryKey;
+}) | {
+    queryKey: QueryKey;
 };
-type QueryOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData> = QueryKeyOptions<TInput> & (Record<never, never> extends TClientContext ? {
+type QueryOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TInitialData> = (undefined extends TInput ? {
+    input?: TInput | SkipToken;
+} : {
+    input: TInput | SkipToken;
+}) & (object extends TClientContext ? {
     context?: TClientContext;
 } : {
     context: TClientContext;
-}) & Omit<QueryObserverOptions<TOutput, TError, TSelectData>, 'queryKey'>;
-interface QueryOptionsBase<TOutput, TError> {
-    queryKey: DataTag<QueryKey, TOutput, TError>;
-    queryFn: QueryFunction<TOutput>;
-    throwOnError?: (error: TError) => boolean;
-    retryDelay?: (count: number, error: TError) => number;
-    enabled?: boolean;
-}
-type experimental_StreamedKeyOptions<TInput> = QueryKeyOptions<TInput> & {
-    queryFnOptions?: experimental_SerializableStreamedQueryOptions;
+}) & Omit<QueryObserverOptions<TOutput, TError, TSelectData>, 'queryKey' | '_defaulted' | '_optimisticResults'> & {
+    queryKey?: QueryKey;
+    initialData?: TInitialData;
 };
-type experimental_StreamedOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData> = QueryOptionsIn<TClientContext, TInput, TOutput, TError, TSelectData> & {
-    queryFnOptions?: experimental_SerializableStreamedQueryOptions;
+type QueryOptionsOut<TOutput, TError, TSelectData, TInitialData> = Pick<QueryObserverOptions<TOutput, TError, TSelectData, TOutput, DataTag<QueryKey, TOutput, TError>>, 'queryKey' | 'throwOnError' | 'select' | 'retryDelay'> & (undefined extends TInitialData ? object : {
+    initialData: TInitialData;
+}) & {
+    queryFn: QueryFunction<TOutput, DataTag<QueryKey, TOutput, TError>>;
 };
-interface experimental_StreamedOptionsBase<TOutput, TError> extends QueryOptionsBase<TOutput, TError> {
-}
-type InfiniteOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TPageParam> = {
+type StreamedKeyOptions<TInput> = ((undefined extends TInput ? {
+    input?: TInput | SkipToken;
+} : {
+    input: TInput | SkipToken;
+}) & {
+    queryFnOptions?: SerializableStreamedQueryOptions;
+}) | {
+    queryKey: QueryKey;
+};
+type StreamedOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TInitialData> = QueryOptionsIn<TClientContext, TInput, TOutput, TError, TSelectData, TInitialData> & {
+    queryFnOptions?: SerializableStreamedQueryOptions;
+};
+type StreamedOptionsOut<TOutput, TError, TSelectData, TInitialData> = QueryOptionsOut<TOutput, TError, TSelectData, TInitialData>;
+type InfiniteKeyOptions<TInput, TPageParam> = Pick<InfiniteOptionsIn<any, TInput, any, any, any, TPageParam, any>, 'input' | 'initialPageParam'> | {
+    queryKey: QueryKey;
+};
+type InfiniteOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TPageParam, TInitialData> = {
     input: ((pageParam: TPageParam) => TInput) | SkipToken;
-} & (Record<never, never> extends TClientContext ? {
+    initialData?: TInitialData;
+    queryKey?: QueryKey;
+} & (object extends TClientContext ? {
     context?: TClientContext;
 } : {
     context: TClientContext;
-}) & SetOptional<InfiniteQueryObserverOptions<TOutput, TError, TSelectData, QueryKey, TPageParam>, 'queryKey'>;
-interface InfiniteOptionsBase<TOutput, TError, TPageParam> {
-    queryKey: DataTag<QueryKey, InfiniteData<TOutput, TPageParam>, TError>;
-    queryFn: QueryFunction<TOutput, QueryKey, TPageParam>;
-    select?(): InfiniteData<TOutput, TPageParam>;
-    throwOnError?: (error: TError) => boolean;
-    retryDelay?: (count: number, error: TError) => number;
-    enabled?: boolean;
-}
-type MutationOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TMutationContext> = (Record<never, never> extends TClientContext ? {
+}) & Omit<InfiniteQueryObserverOptions<TOutput, TError, TSelectData, QueryKey, TPageParam>, 'queryKey' | '_defaulted' | '_optimisticResults'>;
+type InfiniteOptionsOut<TOutput, TError, TSelectData, TPageParam, TInitialData> = Pick<InfiniteQueryObserverOptions<TOutput, TError, TSelectData, DataTag<QueryKey, InfiniteData<TOutput, TPageParam>, TError>, TPageParam>, 'queryKey' | 'select' | 'throwOnError' | 'retryDelay' | 'initialPageParam' | 'getNextPageParam' | 'getPreviousPageParam'> & (undefined extends TInitialData ? object : {
+    initialData: TInitialData;
+}) & {
+    queryFn: QueryFunction<TOutput, DataTag<QueryKey, InfiniteData<TOutput, TPageParam>, TError>, TPageParam>;
+};
+type MutationKeyOptions = Pick<MutationOptionsIn<any, any, any, any, any>, 'mutationKey'>;
+type MutationOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TMutationContext> = (object extends TClientContext ? {
     context?: TClientContext;
 } : {
     context: TClientContext;
-}) & MutationOptions<TInput, TOutput, TError, TMutationContext>;
-type MutationOptions<TInput, TOutput, TError, TMutationContext> = MutationObserverOptions<TOutput, TError, TInput, TMutationContext>;
+}) & MutationOptionsOut<TInput, TOutput, TError, TMutationContext>;
+type MutationOptionsOut<TInput, TOutput, TError, TMutationContext> = MutationObserverOptions<TOutput, TError, TInput, TMutationContext>;
 
-/**
- * Utils at any level (procedure or router)
- */
-interface GeneralUtils<TInput> {
+interface OperationKeyPrefixOptions {
     /**
-     * Generate a **partial matching** key for actions like revalidating queries, checking mutation status, etc.
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * Prepended as the first element of the key when present.
+     * Use this to avoid key conflicts when multiple router utils share the same client.
      */
-    key<TType extends OperationType>(options?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
+    prefix?: string;
 }
-declare function createGeneralUtils<TInput>(path: readonly string[]): GeneralUtils<TInput>;
+type OperationKeyOptions<TType extends OperationType, TInput> = OperationKeyPrefixOptions & {
+    type?: TType;
+    input?: TType extends 'mutation' ? never : PartialDeep<TInput>;
+    fnOptions?: TType extends 'streamed' ? SerializableStreamedQueryOptions : never;
+};
+type OperationKey<TType extends OperationType, TInput> = [path: string[], options: Omit<OperationKeyOptions<TType, TInput>, 'prefix'>] | [prefix: string, path: string[], options: Omit<OperationKeyOptions<TType, TInput>, 'prefix'>];
+declare function generateOperationKey<TType extends OperationType, TInput>(path: string[], options?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
 
-declare function generateOperationKey<TType extends OperationType, TInput>(path: readonly string[], state?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
+declare class SharedUtils<TInput> {
+    protected readonly path: string[];
+    protected readonly options: OperationKeyPrefixOptions;
+    constructor(path: string[], options: OperationKeyPrefixOptions);
+    /**
+     * Generate a **partial matching** key for actions like revalidating queries, checking mutation status, etc.
+     */
+    key<TType extends OperationType>(options?: Omit<OperationKeyOptions<TType, TInput>, 'prefix'>): OperationKey<TType, TInput>;
+}
 
-interface ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> {
+interface ProcedureUtilsQueryInterceptorOptions<TClientContext extends ClientContext, TInput> {
+    path: string[];
+    context: TClientContext & OperationContext;
+    input: TInput | SkipToken;
+    fnContext: QueryFunctionContext;
+}
+type ProcedureUtilsQueryInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
+interface ProcedureUtilsStreamedInterceptorOptions<TClientContext extends ClientContext, TInput> extends ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput> {
+}
+type ProcedureUtilsStreamedInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsStreamedInterceptorOptions<TClientContext, TInput>, PromiseWithError<InferStreamedQueryOutput<TOutput>, TError>>;
+interface ProcedureUtilsLiveInterceptorOptions<TClientContext extends ClientContext, TInput> extends ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput> {
+}
+type ProcedureUtilsLiveInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsLiveInterceptorOptions<TClientContext, TInput>, PromiseWithError<InferLiveQueryOutput<TOutput>, TError>>;
+interface ProcedureUtilsInfiniteInterceptorOptions<TClientContext extends ClientContext, TInput> extends ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput> {
+    fnContext: QueryFunctionContext<QueryKey, any>;
+}
+type ProcedureUtilsInfiniteInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsInfiniteInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
+interface ProcedureUtilsMutationInterceptorOptions<TClientContext extends ClientContext, TInput> extends Omit<ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput>, 'input' | 'fnContext'> {
+    input: TInput;
+    fnContext: MutationFunctionContext;
+}
+type ProcedureUtilsMutationInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsMutationInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
+/**
+ * Can be partial options for spread-merged options,
+ * or a function that receives per-call options and returns overridden this.options.
+ */
+type ProcedureUtilsModifier<T extends object> = Partial<T> | ((options: T) => T);
+interface ProcedureUtilsOptions<TClientContext extends ClientContext, TInput, TOutput, TError> extends OperationKeyPrefixOptions {
+    /**
+     * Key options modifier for .queryKey and .queryOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    queryKey?: ProcedureUtilsModifier<QueryKeyOptions<TInput>>;
+    /**
+     * Interceptors that intercept queryFn inside .queryOptions, guaranteed to be executed.
+     */
+    queryInterceptors?: ProcedureUtilsQueryInterceptor<TClientContext, TInput, TOutput, TError>[];
+    /**
+     * Options modifier for .queryOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    queryOptions?: ProcedureUtilsModifier<QueryOptionsIn<TClientContext, TInput, TOutput, TError, unknown, unknown>>;
+    /**
+     * Key options modifier for .streamedKey and .streamedOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    streamedKey?: ProcedureUtilsModifier<StreamedKeyOptions<TInput>>;
+    /**
+     * Interceptors that intercept queryFn inside .streamedOptions, guaranteed to be executed.
+     */
+    streamedInterceptors?: ProcedureUtilsStreamedInterceptor<TClientContext, TInput, TOutput, TError>[];
+    /**
+     * Options modifier for .streamedOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    streamedOptions?: ProcedureUtilsModifier<StreamedOptionsIn<TClientContext, TInput, InferStreamedQueryOutput<TOutput>, TError, unknown, unknown>>;
+    /**
+     * Key options modifier for .liveKey and .liveOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    liveKey?: ProcedureUtilsModifier<QueryKeyOptions<TInput>>;
+    /**
+     * Interceptors that intercept queryFn inside .liveOptions, guaranteed to be executed.
+     */
+    liveInterceptors?: ProcedureUtilsLiveInterceptor<TClientContext, TInput, TOutput, TError>[];
+    /**
+     * Options modifier for .liveOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    liveOptions?: ProcedureUtilsModifier<QueryOptionsIn<TClientContext, TInput, InferLiveQueryOutput<TOutput>, TError, unknown, unknown>>;
+    /**
+     * Key options modifier for .infiniteKey and .infiniteOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    infiniteKey?: ProcedureUtilsModifier<InfiniteKeyOptions<TInput, unknown>>;
+    /**
+     * Interceptors that intercept queryFn inside .infiniteOptions, guaranteed to be executed.
+     */
+    infiniteInterceptors?: ProcedureUtilsInfiniteInterceptor<TClientContext, TInput, TOutput, TError>[];
+    /**
+     * Options modifier for .infiniteOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    infiniteOptions?: ProcedureUtilsModifier<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, unknown, unknown, unknown>>;
+    /**
+     * Key options modifier for .mutationKey and .mutationOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    mutationKey?: ProcedureUtilsModifier<MutationKeyOptions>;
+    /**
+     * Interceptors that intercept mutationFn inside .mutationOptions, guaranteed to be executed.
+     */
+    mutationInterceptors?: ProcedureUtilsMutationInterceptor<TClientContext, TInput, TOutput, TError>[];
+    /**
+     * Options modifier for .mutationOptions
+     * Can be partial options or a function that receives per-call options and returns override this.options.
+     */
+    mutationOptions?: ProcedureUtilsModifier<MutationOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
+}
+declare function isProcedureUtilsOptions(value: unknown): value is ProcedureUtilsOptions<any, any, any, any>;
+/**
+ * Merge two procedure utils options where `override` takes priority.
+ * A key explicitly set to `undefined` in `override` resets the base value.
+ * When both sides define a key: interceptors are concatenated (base ones run first),
+ * modifiers are spread-merged when both are plain objects and composed (base applied
+ * first) otherwise, with plain objects applied as regular spread merges.
+ */
+declare function mergeProcedureUtilsOptions<TClientContext extends ClientContext, TInput, TOutput, TError>(base: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>, override: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>): ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>;
+declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> extends SharedUtils<TInput> {
+    protected readonly options: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>;
     /**
      * Calling corresponding procedure client
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#calling-clients Tanstack Calling Procedure Client Docs}
      */
     call: Client<TClientContext, TInput, TOutput, TError>;
+    constructor(path: string[], client: Client<TClientContext, TInput, TOutput, TError>, options?: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>);
     /**
      * Generate a **full matching** key for [Query Options](https://orpc.dev/docs/integrations/tanstack-query#query-options).
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
     queryKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): DataTag<QueryKey, TOutput, TError>;
     /**
      * Generate options used for useQuery/useSuspenseQuery/prefetchQuery/...
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-options Tanstack Query Options Utility Docs}
      */
-    queryOptions<U, USelectData = TOutput>(...rest: MaybeOptionalOptions<U & QueryOptionsIn<TClientContext, TInput, TOutput, TError, USelectData>>): NoInfer<U & Omit<QueryOptionsBase<TOutput, TError>, keyof U>>;
+    queryOptions<USelectData = TOutput, UInitialData = undefined>(...rest: MaybeOptionalOptions<QueryOptionsIn<TClientContext, TInput, TOutput, TError, USelectData, UInitialData>>): NoInfer<QueryOptionsOut<TOutput, TError, USelectData, UInitialData>>;
     /**
      * Generate a **full matching** key for [Streamed Query Options](https://orpc.dev/docs/integrations/tanstack-query#streamed-query-options).
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    experimental_streamedKey(...rest: MaybeOptionalOptions<experimental_StreamedKeyOptions<TInput>>): DataTag<QueryKey, experimental_StreamedQueryOutput<TOutput>, TError>;
+    streamedKey(...rest: MaybeOptionalOptions<StreamedKeyOptions<TInput>>): DataTag<QueryKey, InferStreamedQueryOutput<TOutput>, TError>;
     /**
-     * Configure queries for [Event Iterator](https://orpc.dev/docs/event-iterator).
+     * Configure queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
      * This is built on [TanStack Query streamedQuery](https://tanstack.com/query/latest/docs/reference/streamedQuery)
      * and works with hooks like `useQuery`, `useSuspenseQuery`, or `prefetchQuery`.
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#streamed-query-options Tanstack Streamed Query Options Utility Docs}
      */
-    experimental_streamedOptions<U, USelectData = experimental_StreamedQueryOutput<TOutput>>(...rest: MaybeOptionalOptions<U & experimental_StreamedOptionsIn<TClientContext, TInput, experimental_StreamedQueryOutput<TOutput>, TError, USelectData>>): NoInfer<U & Omit<experimental_StreamedOptionsBase<experimental_StreamedQueryOutput<TOutput>, TError>, keyof U>>;
+    streamedOptions<USelectData = InferStreamedQueryOutput<TOutput>, UInitialData = undefined>(...rest: MaybeOptionalOptions<StreamedOptionsIn<TClientContext, TInput, InferStreamedQueryOutput<TOutput>, TError, USelectData, UInitialData>>): NoInfer<StreamedOptionsOut<InferStreamedQueryOutput<TOutput>, TError, USelectData, UInitialData>>;
     /**
      * Generate a **full matching** key for [Live Query Options](https://orpc.dev/docs/integrations/tanstack-query#live-query-options).
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    experimental_liveKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): DataTag<QueryKey, experimental_LiveQueryOutput<TOutput>, TError>;
+    liveKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): DataTag<QueryKey, InferLiveQueryOutput<TOutput>, TError>;
     /**
-     * Configure live queries for [Event Iterator](https://orpc.dev/docs/event-iterator).
+     * Configure live queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
      * Unlike `.streamedOptions` which accumulates chunks, live queries replace the entire result with each new chunk received.
      * Works with hooks like `useQuery`, `useSuspenseQuery`, or `prefetchQuery`.
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#live-query-options Tanstack Live Query Options Utility Docs}
      */
-    experimental_liveOptions<U, USelectData = experimental_LiveQueryOutput<TOutput>>(...rest: MaybeOptionalOptions<U & QueryOptionsIn<TClientContext, TInput, experimental_LiveQueryOutput<TOutput>, TError, USelectData>>): NoInfer<U & Omit<QueryOptionsBase<experimental_LiveQueryOutput<TOutput>, TError>, keyof U>>;
+    liveOptions<USelectData = InferLiveQueryOutput<TOutput>, UInitialData = undefined>(...rest: MaybeOptionalOptions<QueryOptionsIn<TClientContext, TInput, InferLiveQueryOutput<TOutput>, TError, USelectData, UInitialData>>): NoInfer<QueryOptionsOut<InferLiveQueryOutput<TOutput>, TError, USelectData, UInitialData>>;
     /**
      * Generate a **full matching** key for [Infinite Query Options](https://orpc.dev/docs/integrations/tanstack-query#infinite-query-options).
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    infiniteKey<UPageParam>(options: Pick<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, InfiniteData<TOutput, UPageParam>, UPageParam>, 'input' | 'initialPageParam' | 'queryKey'>): DataTag<QueryKey, InfiniteData<TOutput, UPageParam>, TError>;
+    infiniteKey<UPageParam>(optionsIn: InfiniteKeyOptions<TInput, UPageParam>): DataTag<QueryKey, InfiniteData<TOutput, UPageParam>, TError>;
     /**
      * Generate options used for useInfiniteQuery/useSuspenseInfiniteQuery/prefetchInfiniteQuery/...
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#infinite-query-options Tanstack Infinite Query Options Utility Docs}
      */
-    infiniteOptions<U, UPageParam, USelectData = InfiniteData<TOutput, UPageParam>>(options: U & InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, USelectData, UPageParam>): NoInfer<U & Omit<InfiniteOptionsBase<TOutput, TError, UPageParam>, keyof U>>;
+    infiniteOptions<UPageParam, USelectData = InfiniteData<TOutput, UPageParam>, UInitialData = undefined>(optionsIn: InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, USelectData, UPageParam, UInitialData>): NoInfer<InfiniteOptionsOut<TOutput, TError, USelectData, UPageParam, UInitialData>>;
     /**
      * Generate a **full matching** key for [Mutation Options](https://orpc.dev/docs/integrations/tanstack-query#mutation-options).
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    mutationKey(options?: Pick<MutationOptionsIn<TClientContext, TInput, TOutput, TError, any>, 'mutationKey'>): DataTag<QueryKey, TOutput, TError>;
+    mutationKey(optionsIn?: MutationKeyOptions): DataTag<QueryKey, TOutput, TError>;
     /**
      * Generate options used for useMutation/...
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#mutation-options Tanstack Mutation Options Docs}
      */
-    mutationOptions<UMutationContext>(...rest: MaybeOptionalOptions<MutationOptionsIn<TClientContext, TInput, TOutput, TError, UMutationContext>>): NoInfer<MutationOptions<TInput, TOutput, TError, UMutationContext>>;
+    mutationOptions<UMutationContext>(...rest: MaybeOptionalOptions<MutationOptionsIn<TClientContext, TInput, TOutput, TError, UMutationContext>>): NoInfer<MutationOptionsOut<TInput, TOutput, TError, UMutationContext>>;
 }
-interface experimental_ProcedureUtilsDefaults<TClientContext extends ClientContext, TInput, TOutput, TError> {
+
+interface RouterUtilsPlugin<T extends AnyNestedClient> extends OrderablePlugin {
     /**
-     * Default options for queryKey utility
+     * Initializes the router utils plugin and returns updated router utils options.
+     * Called once per plugin instance during composition.
+     *
+     * This method allows plugins to wrap, extend, or transform router utils options,
+     * such as interceptors or configuration.
+     *
+     * @param options - The current router utils options from previous plugins or base configuration
+     * @returns Transformed router utils options with this plugin's modifications applied
      *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * @example
+     * ```ts
+     * init(options) {
+     *   return {
+     *     ...options,
+     *     mutationInterceptors: [...(options.mutationInterceptors ?? []), myInterceptor]
+     *   }
+     * }
+     * ```
      */
-    queryKey?: Partial<QueryKeyOptions<TInput>>;
+    init?(options: RouterUtilsOptions<T>): RouterUtilsOptions<T>;
     /**
-     * Default options for queryOptions utility
+     * Initializes per-procedure router utils options and returns updated options.
+     * Called once per procedure utils instance during composition.
      *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-options Tanstack Query Options Utility Docs}
+     * This method allows plugins to customize merged procedure-specific defaults,
+     * such as query or mutation options, for the current path.
+     *
+     * @param path - The current procedure path
+     * @param options - The merged procedure utils options for the current procedure
+     * @returns Transformed procedure utils options with this plugin's modifications applied
      */
-    queryOptions?: Partial<QueryOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
+    initProcedureOptions?(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
+}
+declare class CompositeRouterUtilsPlugin<T extends AnyNestedClient> implements RouterUtilsPlugin<T> {
+    protected readonly plugins: RouterUtilsPlugin<T>[];
+    readonly name = "~composite";
+    constructor(plugins?: RouterUtilsPlugin<T>[]);
+    init(options: RouterUtilsOptions<T>): RouterUtilsOptions<T>;
+    initProcedureOptions(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
+}
+
+type RouterUtils<T extends AnyNestedClient> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? Public<ProcedureUtils<UClientContext, UInput, UOutput, UError>> : {
+    [K in keyof T]: T[K] extends AnyNestedClient ? RouterUtils<T[K]> : never;
+} & Public<SharedUtils<unknown>>;
+type RouterUtilsScoped<T extends AnyNestedClient> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? ProcedureUtilsOptions<UClientContext, UInput, UOutput, UError> : {
+    [K in keyof T]?: T[K] extends AnyNestedClient ? RouterUtilsScoped<T[K]> : never;
+};
+interface RouterUtilsOptions<T extends AnyNestedClient> extends OperationKeyPrefixOptions {
     /**
-     * Default options for experimental_streamedKey utility
+     * Base path for all query keys.
      *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * @internal
      */
-    experimental_streamedKey?: Partial<experimental_StreamedKeyOptions<TInput>>;
+    path?: string[] | undefined;
     /**
-     * Default options for experimental_streamedOptions utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#streamed-query-options Tanstack Streamed Query Options Utility Docs}
+     * Interceptors that intercept queryFn inside .queryOptions
      */
-    experimental_streamedOptions?: Partial<experimental_StreamedOptionsIn<TClientContext, TInput, experimental_StreamedQueryOutput<TOutput>, TError, unknown>>;
+    queryInterceptors?: ProcedureUtilsQueryInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
     /**
-     * Default options for experimental_liveKey utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * Interceptors that intercept queryFn inside .streamedOptions
      */
-    experimental_liveKey?: Partial<QueryKeyOptions<TInput>>;
+    streamedInterceptors?: ProcedureUtilsStreamedInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
     /**
-     * Default options for experimental_liveOptions utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#live-query-options Tanstack Live Query Options Utility Docs}
+     * Interceptors that intercept queryFn inside .liveOptions
      */
-    experimental_liveOptions?: Partial<QueryOptionsIn<TClientContext, TInput, experimental_LiveQueryOutput<TOutput>, TError, unknown>>;
+    liveInterceptors?: ProcedureUtilsLiveInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
     /**
-     * Default options for infiniteKey utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * Interceptors that intercept queryFn inside .infiniteOptions
      */
-    infiniteKey?: Partial<Pick<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, InfiniteData<TOutput, unknown>, unknown>, 'input' | 'initialPageParam' | 'queryKey'>>;
+    infiniteInterceptors?: ProcedureUtilsInfiniteInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
     /**
-     * Default options for infiniteOptions utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#infinite-query-options Tanstack Infinite Query Options Utility Docs}
+     * Interceptors that intercept mutationFn inside .mutationOptions
      */
-    infiniteOptions?: Partial<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, unknown, unknown>>;
+    mutationInterceptors?: ProcedureUtilsMutationInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
     /**
-     * Default options for mutationKey utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
+     * Per-procedure options following the shape of the router.
+     * Allows fine-grained configuration of individual procedure utils
+     * without affecting the rest of the router.
      */
-    mutationKey?: Partial<Pick<MutationOptionsIn<TClientContext, TInput, TOutput, TError, any>, 'mutationKey'>>;
+    scoped?: RouterUtilsScoped<T> | undefined;
     /**
-     * Default options for mutationOptions utility
-     *
-     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#mutation-options Tanstack Mutation Options Docs}
+     * Plugins to extend router utils behavior.
      */
-    mutationOptions?: Partial<MutationOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
+    plugins?: RouterUtilsPlugin<T>[] | undefined;
 }
 /**
- * @todo remove default generic types on v2
+ * Create a router utils from a client.
+ *
+ * @info Both client-side and server-side clients are supported.
  */
-interface CreateProcedureUtilsOptions<TClientContext extends ClientContext = ClientContext, TInput = unknown, TOutput = unknown, TError = unknown> {
-    path: readonly string[];
-    experimental_defaults?: experimental_ProcedureUtilsDefaults<TClientContext, TInput, TOutput, TError>;
+declare function createRouterUtils<T extends AnyNestedClient>(client: T, options?: NoInfer<RouterUtilsOptions<T>>): RouterUtils<T>;
+
+interface ContractUtilsFactory<TClientContext extends ClientContext> {
+    <T extends RouterContract>(contract: T): RouterUtils<RouterContractClient<T, TClientContext>>;
+}
+interface ContractUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<RouterContractClient<RouterContract, TClientContext>>, 'path'> {
+}
+declare function createContractUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractUtilsFactoryOptions<TClientContext>): ContractUtilsFactory<TClientContext>;
+interface ContractJsonifiedUtilsFactory<TClientContext extends ClientContext> {
+    <T extends RouterContract>(contract: T): RouterUtils<JsonifiedClient<RouterContractClient<T, TClientContext>>>;
+}
+interface ContractJsonifiedUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>>, 'path'> {
 }
-declare function createProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError>(client: Client<TClientContext, TInput, TOutput, TError>, options: CreateProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>): ProcedureUtils<TClientContext, TInput, TOutput, TError>;
+declare function createContractJsonifiedUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractJsonifiedUtilsFactoryOptions<TClientContext>): ContractJsonifiedUtilsFactory<TClientContext>;
 
-type RouterUtils<T extends NestedClient<any>> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? ProcedureUtils<UClientContext, UInput, UOutput, UError> & GeneralUtils<UInput> : {
-    [K in keyof T]: T[K] extends NestedClient<any> ? RouterUtils<T[K]> : never;
-} & GeneralUtils<unknown>;
-type experimental_RouterUtilsDefaults<T extends NestedClient<any>> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? experimental_ProcedureUtilsDefaults<UClientContext, UInput, UOutput, UError> : {
-    [K in keyof T]?: T[K] extends NestedClient<any> ? experimental_RouterUtilsDefaults<T[K]> : never;
-};
+type TanstackQueryMetaOptions<TClientContext extends ClientContext, TInput, TOutput, TError> = Omit<ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>, 'prefix'>;
+interface TanstackQueryMetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> extends MetaPlugin<TInputSchema, TOutputSchema, TErrorMap> {
+    name: '~tanstack-query';
+}
 /**
- * @todo remove default generic types on v2
+ * Define base TanStack Query options and interceptors on a procedure contract.
+ * Applied multiple times, later options are spread-merged with higher priority
+ * while interceptors are concatenated. A key explicitly set to `undefined`
+ * resets the value from earlier applications instead of merging.
+ *
+ * Apply them to router utils with {@link ContractOptionsUtilsPlugin}.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#contract-options-plugin TanStack Query Contract Options Plugin Docs}
  */
-interface CreateRouterUtilsOptions<T extends NestedClient<any> = NestedClient<any>> {
-    path?: readonly string[];
-    experimental_defaults?: experimental_RouterUtilsDefaults<T>;
-}
+declare function tanstackQuery<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(options: TanstackQueryMetaOptions<ClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>): TanstackQueryMetaPlugin<TInputSchema, TOutputSchema, TErrorMap>;
+declare function getTanstackQueryMeta(procedureOrLazy: {
+    '~orpc': {
+        meta: Meta;
+    };
+}): TanstackQueryMetaOptions<ClientContext, unknown, unknown, ThrowableError> | undefined;
 /**
- * Create a router utils from a client.
+ * Router utils plugin that applies base options defined via {@link tanstackQuery}
+ * on the given router contract. Meta options act as the base layer: options defined
+ * on the utils override them, and utils interceptors run after meta interceptors.
  *
- * @info Both client-side and server-side clients are supported.
- * @see {@link https://orpc.dev/docs/integrations/tanstack-query Tanstack Query Integration}
+ * The contract shape must match the client the utils are created from,
+ * so pass the root router contract when utils paths start from the root.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#contract-options-plugin TanStack Query Contract Options Plugin Docs}
  */
-declare function createRouterUtils<T extends NestedClient<any>>(client: T, options?: CreateRouterUtilsOptions<T>): RouterUtils<T>;
+declare class ContractOptionsUtilsPlugin<T extends AnyNestedClient = AnyNestedClient> implements RouterUtilsPlugin<T> {
+    private readonly contract;
+    readonly name = "~contract-options";
+    constructor(contract: RouterContract);
+    initProcedureOptions(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
+}
 
-export { OPERATION_CONTEXT_SYMBOL, OPERATION_CONTEXT_SYMBOL as TANSTACK_QUERY_OPERATION_CONTEXT_SYMBOL, createGeneralUtils, createProcedureUtils, createRouterUtils, createRouterUtils as createTanstackQueryUtils, experimental_serializableStreamedQuery, generateOperationKey };
-export type { CreateProcedureUtilsOptions, CreateRouterUtilsOptions, GeneralUtils, InfiniteOptionsBase, InfiniteOptionsIn, MutationOptions, MutationOptionsIn, OperationContext, OperationKey, OperationKeyOptions, OperationType, ProcedureUtils, QueryKeyOptions, QueryOptionsBase, QueryOptionsIn, RouterUtils, OperationContext as TanstackQueryOperationContext, experimental_LiveQueryOutput, experimental_ProcedureUtilsDefaults, experimental_RouterUtilsDefaults, experimental_SerializableStreamedQueryOptions, experimental_StreamedKeyOptions, experimental_StreamedOptionsBase, experimental_StreamedOptionsIn, experimental_StreamedQueryOutput };
+export { CompositeRouterUtilsPlugin, ContractOptionsUtilsPlugin, OPERATION_CONTEXT_SYMBOL, ProcedureUtils, SharedUtils, OPERATION_CONTEXT_SYMBOL as TANSTACK_QUERY_OPERATION_CONTEXT_SYMBOL, createContractJsonifiedUtilsFactory, createContractUtilsFactory, createRouterUtils, createRouterUtils as createTanstackQueryUtils, generateOperationKey, getTanstackQueryMeta, isProcedureUtilsOptions, mergeProcedureUtilsOptions, serializableStreamedQuery, tanstackQuery };
+export type { ContractJsonifiedUtilsFactory, ContractJsonifiedUtilsFactoryOptions, ContractUtilsFactory, ContractUtilsFactoryOptions, InferLiveQueryOutput, InferStreamedQueryOutput, InfiniteKeyOptions, InfiniteOptionsIn, InfiniteOptionsOut, MutationKeyOptions, MutationOptionsIn, MutationOptionsOut, OperationContext, OperationKey, OperationKeyOptions, OperationKeyPrefixOptions, OperationType, ProcedureUtilsInfiniteInterceptor, ProcedureUtilsInfiniteInterceptorOptions, ProcedureUtilsLiveInterceptor, ProcedureUtilsLiveInterceptorOptions, ProcedureUtilsModifier, ProcedureUtilsMutationInterceptor, ProcedureUtilsMutationInterceptorOptions, ProcedureUtilsOptions, ProcedureUtilsQueryInterceptor, ProcedureUtilsQueryInterceptorOptions, ProcedureUtilsStreamedInterceptor, ProcedureUtilsStreamedInterceptorOptions, QueryKeyOptions, QueryOptionsIn, QueryOptionsOut, RouterUtils, RouterUtilsOptions, RouterUtilsPlugin, RouterUtilsScoped, SerializableStreamedQueryOptions, StreamedKeyOptions, StreamedOptionsIn, StreamedOptionsOut, TanstackQueryMetaOptions, TanstackQueryMetaPlugin, OperationContext as TanstackQueryOperationContext };