feat(tanstack-query): default query/mutation options (#1260)

Fixes #1051

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Experimental centralized default options for procedures and routers,
applied to queries, mutations, infinite/streamed/live operations and
overridable per call.

* **Tests**
* Added tests covering default propagation, nested/router-level
resolution, and per-call override behavior.

* **Documentation**
* Added a "Default Options" section to the TanStack Query integration
docs (duplicated in two places).

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/integrations/tanstack-query.md

@@ -226,6 +226,47 @@ const query = useQuery(computed(
 
 :::
 
+## Default Options
+
+You can configure default options for all query/mutation utilities using `experimental_defaults`. These options are [spread merged](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) with user-provided options, allowing you to set defaults while still enabling customization on a per-call basis.
+
+```ts
+const orpc = createTanstackQueryUtils(client, {
+  experimental_defaults: {
+    planet: {
+      find: {
+        queryOptions: {
+          staleTime: 60 * 1000, // 1 minute
+          retry: 3,
+        },
+      },
+      list: {
+        infiniteOptions: {
+          staleTime: 30 * 1000,
+        },
+      },
+      create: {
+        mutationOptions: {
+          onSuccess: (output, input, _, ctx) => {
+            ctx.client.invalidateQueries({ queryKey: orpc.planet.key() })
+          },
+        },
+      },
+    },
+  },
+})
+
+// These will automatically use the default options
+const query = useQuery(orpc.planet.find.queryOptions({ input: { id: 123 } }))
+const mutation = useMutation(orpc.planet.create.mutationOptions())
+
+// User-provided options override defaults
+const customQuery = useQuery(orpc.planet.find.queryOptions({
+  input: { id: 123 },
+  staleTime: 0, // overrides the default
+}))
+```
+
 ## Client Context
 
 ::: warning

packages/tanstack-query/src/procedure-utils.test-d.ts

@@ -2,7 +2,7 @@ import type { Client } from '@orpc/client'
 import type { ErrorFromErrorMap } from '@orpc/contract'
 import type { GetNextPageParamFunction, InfiniteData, InfiniteQueryObserverOptions, MutationObserverOptions, QueryFunction, QueryKey, QueryObserverOptions } from '@tanstack/query-core'
 import type { baseErrorMap } from '../../contract/tests/shared'
-import type { ProcedureUtils } from './procedure-utils'
+import type { experimental_ProcedureUtilsDefaults, ProcedureUtils } from './procedure-utils'
 import { QueryClient, skipToken } from '@tanstack/query-core'
 
 describe('ProcedureUtils', () => {
@@ -746,3 +746,194 @@ describe('ProcedureUtils', () => {
     })
   })
 })
+
+describe('ProcedureUtilsDefaults', () => {
+  type TestClientContext = { batch?: boolean }
+  type TestInput = { search?: string }
+  type TestOutput = { title: string }
+  type TestError = Error
+
+  type TestDefaults = experimental_ProcedureUtilsDefaults<TestClientContext, TestInput, TestOutput, TestError>
+
+  it('should have exact same keys as ProcedureUtils excluding call', () => {
+    // Ensures every utility method in ProcedureUtils (except 'call') has a corresponding key in ProcedureUtilsDefaults
+    type ProcedureUtilsKeys = Exclude<keyof ProcedureUtils<any, any, any, any>, 'call'>
+    type DefaultsKeys = keyof experimental_ProcedureUtilsDefaults<any, any, any, any>
+
+    expectTypeOf<DefaultsKeys>().toEqualTypeOf<ProcedureUtilsKeys>()
+  })
+
+  it('all properties should be optional', () => {
+    const emptyDefaults: TestDefaults = {}
+    expectTypeOf(emptyDefaults).toExtend<TestDefaults>()
+  })
+
+  it('queryKey should accept Partial<QueryKeyOptions>', () => {
+    const defaults: TestDefaults = {
+      queryKey: {
+        input: { search: 'test' },
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      queryKey: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('queryOptions should accept Partial<QueryOptionsIn>', () => {
+    const defaults: TestDefaults = {
+      queryOptions: {
+        input: { search: 'test' },
+        staleTime: 1000,
+        context: { batch: true },
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      queryOptions: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('experimental_streamedKey should accept Partial<experimental_StreamedKeyOptions>', () => {
+    const defaults: TestDefaults = {
+      experimental_streamedKey: {
+        input: { search: 'test' },
+        queryFnOptions: { maxChunks: 10 },
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      experimental_streamedKey: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('experimental_streamedOptions should accept Partial<StreamedOptionsIn>', () => {
+    const defaults: TestDefaults = {
+      experimental_streamedOptions: {
+        input: { search: 'test' },
+        staleTime: 1000,
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      experimental_streamedOptions: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('experimental_liveKey should accept Partial<QueryKeyOptions>', () => {
+    const defaults: TestDefaults = {
+      experimental_liveKey: {
+        input: { search: 'test' },
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      experimental_liveKey: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('experimental_liveOptions should accept Partial<StreamedOptionsIn>', () => {
+    const defaults: TestDefaults = {
+      experimental_liveOptions: {
+        input: { search: 'test' },
+        staleTime: 1000,
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      experimental_liveOptions: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('infiniteKey should accept Partial input, initialPageParam, queryKey', () => {
+    const defaults: TestDefaults = {
+      infiniteKey: {
+        initialPageParam: 0,
+        queryKey: ['custom-key'],
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      infiniteKey: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('infiniteOptions should accept Partial<InfiniteOptionsIn>', () => {
+    const defaults: TestDefaults = {
+      infiniteOptions: {
+        staleTime: 1000,
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      infiniteOptions: {
+        // @ts-expect-error - invalid input type
+        input: { invalid: 'test' },
+      },
+    }
+  })
+
+  it('mutationKey should accept Partial mutationKey', () => {
+    const defaults: TestDefaults = {
+      mutationKey: {
+        mutationKey: ['custom-mutation-key'],
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      mutationKey: {
+        // @ts-expect-error - invalid mutationKey type
+        mutationKey: 1,
+      },
+    }
+  })
+
+  it('mutationOptions should accept Partial<MutationOptionsIn>', () => {
+    const defaults: TestDefaults = {
+      mutationOptions: {
+        onSuccess: (output) => {
+          expectTypeOf(output).toEqualTypeOf<TestOutput>()
+        },
+        context: { batch: true },
+      },
+    }
+    expectTypeOf(defaults).toExtend<TestDefaults>()
+
+    const _invalid: TestDefaults = {
+      mutationOptions: {
+        // @ts-expect-error - invalid context type
+        context: { batch: 'invalid' },
+      },
+    }
+  })
+})