@orpc/tanstack-query 1.14.11 → 1.14.13

package/dist/index.d.ts

@@ -1,16 +1,14 @@
-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';
+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';
 
-interface SerializableStreamedQueryOptions {
+interface experimental_SerializableStreamedQueryOptions {
     /**
-     * Determines how data is handled when the query is fetched again
+     * Determines how data is handled when the query is refetched.
      *
-     * - `'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.
+     * - `'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.
      *
      * @default 'reset'
      */
@@ -28,11 +26,17 @@ interface SerializableStreamedQueryOptions {
  * - Options are serializable
  * - The output is predictable
  */
-declare function serializableStreamedQuery<TQueryFnData = unknown, TQueryKey extends QueryKey = QueryKey>(queryFn: (context: QueryFunctionContext<TQueryKey>) => Promisable<AsyncIterable<TQueryFnData>>, { refetchMode, maxChunks }?: SerializableStreamedQueryOptions): QueryFunction<TQueryFnData[], TQueryKey>;
+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>;
 
-type InferStreamedQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U[] : never;
-type InferLiveQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U : never;
+type experimental_StreamedQueryOutput<TOutput> = TOutput extends AsyncIterable<infer U> ? U[] : never;
+type experimental_LiveQueryOutput<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]?: {
@@ -44,393 +48,229 @@ 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, TInitialData> = (undefined extends TInput ? {
-    input?: TInput | SkipToken;
-} : {
-    input: TInput | SkipToken;
-}) & (object extends TClientContext ? {
+type QueryOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData> = QueryKeyOptions<TInput> & (Record<never, never> extends TClientContext ? {
     context?: TClientContext;
 } : {
     context: TClientContext;
-}) & Omit<QueryObserverOptions<TOutput, TError, TSelectData>, 'queryKey' | '_defaulted' | '_optimisticResults'> & {
-    queryKey?: QueryKey;
-    initialData?: TInitialData;
-};
-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>>;
-};
-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;
+}) & 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;
 };
-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 experimental_StreamedOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData> = QueryOptionsIn<TClientContext, TInput, TOutput, TError, TSelectData> & {
+    queryFnOptions?: experimental_SerializableStreamedQueryOptions;
 };
-type InfiniteOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TPageParam, TInitialData> = {
+interface experimental_StreamedOptionsBase<TOutput, TError> extends QueryOptionsBase<TOutput, TError> {
+}
+type InfiniteOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TError, TSelectData, TPageParam> = {
     input: ((pageParam: TPageParam) => TInput) | SkipToken;
-    initialData?: TInitialData;
-    queryKey?: QueryKey;
-} & (object extends TClientContext ? {
+} & (Record<never, never> extends TClientContext ? {
     context?: TClientContext;
 } : {
     context: 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 ? {
+}) & 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 ? {
     context?: TClientContext;
 } : {
     context: TClientContext;
-}) & MutationOptionsOut<TInput, TOutput, TError, TMutationContext>;
-type MutationOptionsOut<TInput, TOutput, TError, TMutationContext> = MutationObserverOptions<TOutput, TError, TInput, TMutationContext>;
-
-interface OperationKeyPrefixOptions {
-    /**
-     * Prepended as the first element of the key when present.
-     * Use this to avoid key conflicts when multiple router utils share the same client.
-     */
-    prefix?: string;
-}
-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>;
+}) & MutationOptions<TInput, TOutput, TError, TMutationContext>;
+type MutationOptions<TInput, TOutput, TError, TMutationContext> = MutationObserverOptions<TOutput, TError, TInput, TMutationContext>;
 
-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 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.
+ * Utils at any level (procedure or router)
  */
-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>>;
+interface GeneralUtils<TInput> {
     /**
-     * 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.
+     * 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}
      */
-    mutationOptions?: ProcedureUtilsModifier<MutationOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
+    key<TType extends OperationType>(options?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
 }
-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>;
+declare function createGeneralUtils<TInput>(path: readonly string[]): GeneralUtils<TInput>;
+
+declare function generateOperationKey<TType extends OperationType, TInput>(path: readonly string[], state?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
+
+interface ProcedureUtils<TClientContext extends ClientContext, 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<USelectData = TOutput, UInitialData = undefined>(...rest: MaybeOptionalOptions<QueryOptionsIn<TClientContext, TInput, TOutput, TError, USelectData, UInitialData>>): NoInfer<QueryOptionsOut<TOutput, TError, USelectData, UInitialData>>;
+    queryOptions<U, USelectData = TOutput>(...rest: MaybeOptionalOptions<U & QueryOptionsIn<TClientContext, TInput, TOutput, TError, USelectData>>): NoInfer<U & Omit<QueryOptionsBase<TOutput, TError>, keyof U>>;
     /**
      * 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}
      */
-    streamedKey(...rest: MaybeOptionalOptions<StreamedKeyOptions<TInput>>): DataTag<QueryKey, InferStreamedQueryOutput<TOutput>, TError>;
+    experimental_streamedKey(...rest: MaybeOptionalOptions<experimental_StreamedKeyOptions<TInput>>): DataTag<QueryKey, experimental_StreamedQueryOutput<TOutput>, TError>;
     /**
-     * Configure queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
+     * Configure queries for [Event Iterator](https://orpc.dev/docs/event-iterator).
      * 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}
      */
-    streamedOptions<USelectData = InferStreamedQueryOutput<TOutput>, UInitialData = undefined>(...rest: MaybeOptionalOptions<StreamedOptionsIn<TClientContext, TInput, InferStreamedQueryOutput<TOutput>, TError, USelectData, UInitialData>>): NoInfer<StreamedOptionsOut<InferStreamedQueryOutput<TOutput>, TError, USelectData, UInitialData>>;
+    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>>;
     /**
      * 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}
      */
-    liveKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): DataTag<QueryKey, InferLiveQueryOutput<TOutput>, TError>;
+    experimental_liveKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): DataTag<QueryKey, experimental_LiveQueryOutput<TOutput>, TError>;
     /**
-     * Configure live queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
+     * Configure live queries for [Event Iterator](https://orpc.dev/docs/event-iterator).
      * 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}
      */
-    liveOptions<USelectData = InferLiveQueryOutput<TOutput>, UInitialData = undefined>(...rest: MaybeOptionalOptions<QueryOptionsIn<TClientContext, TInput, InferLiveQueryOutput<TOutput>, TError, USelectData, UInitialData>>): NoInfer<QueryOptionsOut<InferLiveQueryOutput<TOutput>, TError, USelectData, UInitialData>>;
+    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>>;
     /**
      * 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>(optionsIn: InfiniteKeyOptions<TInput, UPageParam>): DataTag<QueryKey, InfiniteData<TOutput, UPageParam>, TError>;
+    infiniteKey<UPageParam>(options: Pick<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, InfiniteData<TOutput, UPageParam>, UPageParam>, 'input' | 'initialPageParam' | 'queryKey'>): 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<UPageParam, USelectData = InfiniteData<TOutput, UPageParam>, UInitialData = undefined>(optionsIn: InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, USelectData, UPageParam, UInitialData>): NoInfer<InfiniteOptionsOut<TOutput, TError, USelectData, UPageParam, UInitialData>>;
+    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>>;
     /**
      * 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(optionsIn?: MutationKeyOptions): DataTag<QueryKey, TOutput, TError>;
+    mutationKey(options?: Pick<MutationOptionsIn<TClientContext, TInput, TOutput, TError, any>, 'mutationKey'>): 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<MutationOptionsOut<TInput, TOutput, TError, UMutationContext>>;
+    mutationOptions<UMutationContext>(...rest: MaybeOptionalOptions<MutationOptionsIn<TClientContext, TInput, TOutput, TError, UMutationContext>>): NoInfer<MutationOptions<TInput, TOutput, TError, UMutationContext>>;
 }
-
-interface RouterUtilsPlugin<T extends AnyNestedClient> extends OrderablePlugin {
+interface experimental_ProcedureUtilsDefaults<TClientContext extends ClientContext, TInput, TOutput, TError> {
     /**
-     * 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
+     * Default options for queryKey utility
      *
-     * @example
-     * ```ts
-     * init(options) {
-     *   return {
-     *     ...options,
-     *     mutationInterceptors: [...(options.mutationInterceptors ?? []), myInterceptor]
-     *   }
-     * }
-     * ```
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    init?(options: RouterUtilsOptions<T>): RouterUtilsOptions<T>;
+    queryKey?: Partial<QueryKeyOptions<TInput>>;
     /**
-     * Initializes per-procedure router utils options and returns updated options.
-     * Called once per procedure utils instance during composition.
+     * Default options for queryOptions utility
      *
-     * 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
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-options Tanstack Query Options Utility Docs}
      */
-    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 {
+    queryOptions?: Partial<QueryOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
     /**
-     * Base path for all query keys.
+     * Default options for experimental_streamedKey utility
      *
-     * @internal
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    path?: string[] | undefined;
+    experimental_streamedKey?: Partial<experimental_StreamedKeyOptions<TInput>>;
     /**
-     * Interceptors that intercept queryFn inside .queryOptions
+     * Default options for experimental_streamedOptions utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#streamed-query-options Tanstack Streamed Query Options Utility Docs}
      */
-    queryInterceptors?: ProcedureUtilsQueryInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
+    experimental_streamedOptions?: Partial<experimental_StreamedOptionsIn<TClientContext, TInput, experimental_StreamedQueryOutput<TOutput>, TError, unknown>>;
     /**
-     * Interceptors that intercept queryFn inside .streamedOptions
+     * Default options for experimental_liveKey utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    streamedInterceptors?: ProcedureUtilsStreamedInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
+    experimental_liveKey?: Partial<QueryKeyOptions<TInput>>;
     /**
-     * Interceptors that intercept queryFn inside .liveOptions
+     * Default options for experimental_liveOptions utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#live-query-options Tanstack Live Query Options Utility Docs}
      */
-    liveInterceptors?: ProcedureUtilsLiveInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
+    experimental_liveOptions?: Partial<QueryOptionsIn<TClientContext, TInput, experimental_LiveQueryOutput<TOutput>, TError, unknown>>;
     /**
-     * Interceptors that intercept queryFn inside .infiniteOptions
+     * Default options for infiniteKey utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    infiniteInterceptors?: ProcedureUtilsInfiniteInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
+    infiniteKey?: Partial<Pick<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, InfiniteData<TOutput, unknown>, unknown>, 'input' | 'initialPageParam' | 'queryKey'>>;
     /**
-     * Interceptors that intercept mutationFn inside .mutationOptions
+     * Default options for infiniteOptions utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#infinite-query-options Tanstack Infinite Query Options Utility Docs}
      */
-    mutationInterceptors?: ProcedureUtilsMutationInterceptor<InferClientContext<T>, unknown, unknown, InferClientError<T>>[];
+    infiniteOptions?: Partial<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, unknown, unknown>>;
     /**
-     * Per-procedure options following the shape of the router.
-     * Allows fine-grained configuration of individual procedure utils
-     * without affecting the rest of the router.
+     * Default options for mutationKey utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#query-mutation-key Tanstack Query/Mutation Key Docs}
      */
-    scoped?: RouterUtilsScoped<T> | undefined;
+    mutationKey?: Partial<Pick<MutationOptionsIn<TClientContext, TInput, TOutput, TError, any>, 'mutationKey'>>;
     /**
-     * Plugins to extend router utils behavior.
+     * Default options for mutationOptions utility
+     *
+     * @see {@link https://orpc.dev/docs/integrations/tanstack-query#mutation-options Tanstack Mutation Options Docs}
      */
-    plugins?: RouterUtilsPlugin<T>[] | undefined;
+    mutationOptions?: Partial<MutationOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
 }
 /**
- * Create a router utils from a client.
- *
- * @info Both client-side and server-side clients are supported.
+ * @todo remove default generic types on v2
  */
-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'> {
+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 createContractJsonifiedUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractJsonifiedUtilsFactoryOptions<TClientContext>): ContractJsonifiedUtilsFactory<TClientContext>;
+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>;
 
-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';
-}
+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;
+};
 /**
- * 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}
+ * @todo remove default generic types on v2
  */
-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;
+interface CreateRouterUtilsOptions<T extends NestedClient<any> = NestedClient<any>> {
+    path?: readonly string[];
+    experimental_defaults?: experimental_RouterUtilsDefaults<T>;
+}
 /**
- * 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.
- *
- * 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.
+ * Create a router utils from a client.
  *
- * @see {@link https://orpc.dev/docs/integrations/tanstack-query#contract-options-plugin TanStack Query Contract Options Plugin Docs}
+ * @info Both client-side and server-side clients are supported.
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query Tanstack Query Integration}
  */
-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>>;
-}
+declare function createRouterUtils<T extends NestedClient<any>>(client: T, options?: CreateRouterUtilsOptions<T>): RouterUtils<T>;
 
-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 };
+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 };