@orpc/tanstack-query 2.0.0-beta.3 → 2.0.0-beta.30

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { ClientContext, Client, AnyNestedClient, InferClientContext, InferClientError, ThrowableError } from '@orpc/client';
-import { AnySchema, ErrorMap, ProcedureContract, InferSchemaInput, InferSchemaOutput, ORPCErrorFromErrorMap, RouterContractClient, RouterContract, ContractCaller } from '@orpc/contract';
-import { JsonifiedValue, JsonifiedClientError, JsonifiedClient } from '@orpc/openapi';
-import { Promisable, PartialDeep, Interceptor, PromiseWithError, MaybeOptionalOptions, OrderablePlugin, Public } from '@orpc/shared';
+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 SerializableStreamedQueryOptions {
@@ -33,13 +33,19 @@ declare function serializableStreamedQuery<TQueryFnData = unknown, TQueryKey ext
 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' ? SerializableStreamedQueryOptions : never;
-};
-type OperationKey<TType extends OperationType, TInput> = [path: string[], options: OperationKeyOptions<TType, TInput>];
+/**
+ * The symbol under which TanStack Query utils attach operation details
+ * (key and operation type) to the client context.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#client-context | TanStack Query Integration - Client Context}
+ */
 declare const OPERATION_CONTEXT_SYMBOL: unique symbol;
+/**
+ * A client context automatically populated by TanStack Query utils,
+ * exposing the operation key and type of the calling operation.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#client-context | TanStack Query Integration - Client Context}
+ */
 interface OperationContext {
     [OPERATION_CONTEXT_SYMBOL]?: {
         key: QueryKey;
@@ -108,6 +114,31 @@ type MutationOptionsIn<TClientContext extends ClientContext, TInput, TOutput, TE
 }) & 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>;
+
+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;
@@ -135,7 +166,7 @@ type ProcedureUtilsMutationInterceptor<TClientContext extends ClientContext, TIn
  * 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> {
+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.
@@ -207,9 +238,17 @@ interface ProcedureUtilsOptions<TClientContext extends ClientContext, TInput, TO
      */
     mutationOptions?: ProcedureUtilsModifier<MutationOptionsIn<TClientContext, TInput, TOutput, TError, unknown>>;
 }
-declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> {
-    private readonly path;
-    private readonly options;
+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
      */
@@ -228,7 +267,7 @@ declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutp
      */
     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`.
      */
@@ -238,7 +277,7 @@ declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutp
      */
     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`.
      */
@@ -261,6 +300,11 @@ declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutp
     mutationOptions<UMutationContext>(...rest: MaybeOptionalOptions<MutationOptionsIn<TClientContext, TInput, TOutput, TError, UMutationContext>>): NoInfer<MutationOptionsOut<TInput, TOutput, TError, UMutationContext>>;
 }
 
+/**
+ * Plugin that packages reusable defaults and interceptors for router utils.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#plugins | TanStack Query Integration - Plugins}
+ */
 interface RouterUtilsPlugin<T extends AnyNestedClient> extends OrderablePlugin {
     /**
      * Initializes the router utils plugin and returns updated router utils options.
@@ -296,25 +340,31 @@ interface RouterUtilsPlugin<T extends AnyNestedClient> extends OrderablePlugin {
      */
     initProcedureOptions?(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
 }
-
-declare class SharedRouterUtils<TInput> {
-    private readonly path;
-    constructor(path: string[]);
-    /**
-     * Generate a **partial matching** key for actions like revalidating queries, checking mutation status, etc.
-     */
-    key<TType extends OperationType>(options?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
+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>> & Public<SharedRouterUtils<UInput>> : {
+
+/**
+ * The utils shape derived from a client: procedure clients map to procedure
+ * utils, and routers map recursively to nested utils.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query | TanStack Query Integration}
+ */
+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<SharedRouterUtils<unknown>>;
+} & 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> {
+interface RouterUtilsOptions<T extends AnyNestedClient> extends OperationKeyPrefixOptions {
     /**
-     * Base path for all query keys. Use this to avoid conflicts when mounting
-     * multiple router utils instances.
+     * Base path for all query keys.
+     *
+     * @internal
      */
     path?: string[] | undefined;
     /**
@@ -349,26 +399,75 @@ interface RouterUtilsOptions<T extends AnyNestedClient> {
     plugins?: RouterUtilsPlugin<T>[] | undefined;
 }
 /**
- * Create a router utils from a client.
+ * Creates TanStack Query utils from a client, exposing query/mutation
+ * option builders for every procedure in the router.
  *
- * @info Both client-side and server-side clients are supported.
+ * @remarks
+ * **Note**: Both client-side and server-side clients are supported.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query | TanStack Query Integration}
  */
 declare function createRouterUtils<T extends AnyNestedClient>(client: T, options?: NoInfer<RouterUtilsOptions<T>>): RouterUtils<T>;
 
 interface ContractUtilsFactory<TClientContext extends ClientContext> {
-    <TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(procedure: ProcedureContract<TInputSchema, TOutputSchema, TErrorMap>): Public<SharedRouterUtils<InferSchemaInput<TInputSchema>>> & Public<ProcedureUtils<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>>;
+    <T extends RouterContract>(contract: T): RouterUtils<RouterContractClient<T, TClientContext>>;
 }
-interface ContractUtilsFactoryOptions<TClientContext extends ClientContext> extends RouterUtilsOptions<RouterContractClient<RouterContract, TClientContext>> {
+interface ContractUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<RouterContractClient<RouterContract, TClientContext>>, 'path'> {
 }
-declare function createContractUtilsFactory<TClientContext extends ClientContext>(caller: ContractCaller<TClientContext>, options: ContractUtilsFactoryOptions<TClientContext>): ContractUtilsFactory<TClientContext>;
+/**
+ * Creates a factory that builds TanStack Query utils directly from a contract,
+ * using the given contract client factory. Useful for scaling large projects
+ * where each part only needs a slice of the router.
+ *
+ * @remarks
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects#tanstack-query-integration | Scaling Large Projects - TanStack Query Integration}
+ */
+declare function createContractUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractUtilsFactoryOptions<TClientContext>): ContractUtilsFactory<TClientContext>;
 interface ContractJsonifiedUtilsFactory<TClientContext extends ClientContext> {
-    <TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(procedure: ProcedureContract<TInputSchema, TOutputSchema, TErrorMap>): SharedRouterUtils<InferSchemaInput<TInputSchema>> & ProcedureUtils<TClientContext, InferSchemaInput<TInputSchema>, JsonifiedValue<InferSchemaOutput<TOutputSchema>>, JsonifiedClientError<ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>>;
+    <T extends RouterContract>(contract: T): RouterUtils<JsonifiedClient<RouterContractClient<T, TClientContext>>>;
 }
-interface ContractJsonifiedUtilsFactoryOptions<TClientContext extends ClientContext> extends RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>> {
+interface ContractJsonifiedUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>>, 'path'> {
 }
-declare function createContractJsonifiedUtilsFactory<TClientContext extends ClientContext>(caller: ContractCaller<TClientContext>, options: ContractJsonifiedUtilsFactoryOptions<TClientContext>): ContractJsonifiedUtilsFactory<TClientContext>;
+declare function createContractJsonifiedUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractJsonifiedUtilsFactoryOptions<TClientContext>): ContractJsonifiedUtilsFactory<TClientContext>;
 
-declare function generateOperationKey<TType extends OperationType, TInput>(path: string[], state?: OperationKeyOptions<TType, TInput>): OperationKey<TType, TInput>;
+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';
+}
+/**
+ * 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 Integration - Contract Options Plugin}
+ */
+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;
+/**
+ * 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.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/tanstack-query#contract-options-plugin | TanStack Query Integration - Contract Options Plugin}
+ */
+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, ProcedureUtils, SharedRouterUtils, OPERATION_CONTEXT_SYMBOL as TANSTACK_QUERY_OPERATION_CONTEXT_SYMBOL, createContractJsonifiedUtilsFactory, createContractUtilsFactory, createRouterUtils, createRouterUtils as createTanstackQueryUtils, generateOperationKey, serializableStreamedQuery };
-export type { ContractJsonifiedUtilsFactory, ContractJsonifiedUtilsFactoryOptions, ContractUtilsFactory, ContractUtilsFactoryOptions, InferLiveQueryOutput, InferStreamedQueryOutput, InfiniteKeyOptions, InfiniteOptionsIn, InfiniteOptionsOut, MutationKeyOptions, MutationOptionsIn, MutationOptionsOut, OperationContext, OperationKey, OperationKeyOptions, OperationType, ProcedureUtilsInfiniteInterceptor, ProcedureUtilsInfiniteInterceptorOptions, ProcedureUtilsLiveInterceptor, ProcedureUtilsLiveInterceptorOptions, ProcedureUtilsModifier, ProcedureUtilsMutationInterceptor, ProcedureUtilsMutationInterceptorOptions, ProcedureUtilsOptions, ProcedureUtilsQueryInterceptor, ProcedureUtilsQueryInterceptorOptions, ProcedureUtilsStreamedInterceptor, ProcedureUtilsStreamedInterceptorOptions, QueryKeyOptions, QueryOptionsIn, QueryOptionsOut, RouterUtils, RouterUtilsOptions, RouterUtilsScoped, SerializableStreamedQueryOptions, StreamedKeyOptions, StreamedOptionsIn, StreamedOptionsOut, OperationContext as TanstackQueryOperationContext };
+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 };