feat(tanstack-query): define base options and interceptors via contract meta (#1705)

## Summary

Define base TanStack Query options and interceptors directly on a
procedure contract via `tanstackQuery`, and apply them automatically
with the new `ContractOptionsUtilsPlugin`.

```ts
export const contract = {
  planet: {
    find: oc
      .input(z.object({ id: z.number() }))
      .meta(tanstackQuery({
        queryOptions: {
          staleTime: 60 * 1000,
        },
      })),
  },
}

const orpc = createTanstackQueryUtils(client, {
  plugins: [new ContractOptionsUtilsPlugin(contract)],
})
```

- `tanstackQuery` infers input, output, and error types from the
contract, supports all procedure utils options (keys, options,
interceptors), and merges when applied multiple times
- `ContractOptionsUtilsPlugin` applies meta options as the base layer:
utils level options override them and utils interceptors run after meta
interceptors
- Merging is consistent across all layers: interceptors concatenate,
plain option objects spread-merge, and any pair involving a function
modifier composes
- `getTanstackQueryMeta` reads the stored options for custom
integrations
- Docs cover the plugin, the reference-only nature of contract types,
and passing runtime values such as router utils through mutation meta

Author: dinwwwh

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

@@ -335,6 +335,103 @@ const orpc = createTanstackQueryUtils(client, {
 })
 ```
 
+### Contract Options Plugin
+
+Use `tanstackQuery` to define base options and interceptors directly on a [procedure contract](/docs/contract/procedure), then pass the contract to `ContractOptionsUtilsPlugin` to apply them automatically. Meta options act as the base layer: [default options](#default-options) and [interceptors](#interceptors) defined on the utils merge on top of them. Passing `undefined` explicitly for a key resets the value from lower layers instead of merging.
+
+```ts
+import { ContractOptionsUtilsPlugin, tanstackQuery } from '@orpc/tanstack-query'
+
+export const contract = {
+  planet: {
+    find: oc
+      .input(z.object({ id: z.number() }))
+      .meta(tanstackQuery({
+        queryOptions: {
+          staleTime: 60 * 1000,
+        },
+        queryInterceptors: [
+          async ({ input, next }) => {
+            // input, output, and errors are typed based on the contract
+            return await next()
+          },
+        ],
+      })),
+  },
+}
+
+const orpc = createTanstackQueryUtils(client, {
+  plugins: [new ContractOptionsUtilsPlugin(contract)],
+})
+```
+
+::: warning
+Types inferred from the contract are for reference only. The actual types depend on the client the utils are created from. For example, a `JsonifiedClient` created from [OpenAPI Link](/docs/openapi/link#typesafe-clients) returns jsonified outputs that may not match the contract schemas.
+:::
+
+::: details Passing runtime values into contract meta?
+Contracts are defined separately from your app, so anything inside `tanstackQuery` cannot import runtime values such as your router utils. Instead, [register a global meta type](https://tanstack.com/query/latest/docs/framework/react/typescript#registering-global-meta) and pass the values through the `meta` option, per hook or globally via query client default options. The example below reads router utils from `fnContext.meta` to optimistically update a query:
+
+```ts
+import type { RouterContractClient } from '@orpc/contract'
+import type { RouterUtils } from '@orpc/tanstack-query'
+
+declare module '@tanstack/react-query' {
+  interface Register {
+    mutationMeta: {
+      utils?: RouterUtils<RouterContractClient<typeof contract>>
+    }
+  }
+}
+
+export const contract = {
+  planet: {
+    find: oc.input(z.object({ id: z.number() })),
+    update: oc
+      .input(z.object({ id: z.number(), name: z.string() }))
+      .meta(tanstackQuery({
+        mutationInterceptors: [
+          async ({ input, next, fnContext }) => {
+            const utils = fnContext.meta?.utils
+
+            if (!utils) {
+              return next()
+            }
+
+            const queryKey = utils.planet.find.queryKey({ input: { id: input.id } })
+            const previous = fnContext.client.getQueryData(queryKey)
+
+            // optimistically update before the request
+            fnContext.client.setQueryData(queryKey, input)
+
+            try {
+              return await next()
+            }
+            catch (error) {
+              // roll back on error
+              fnContext.client.setQueryData(queryKey, previous)
+              throw error
+            }
+            finally {
+              fnContext.client.invalidateQueries({ queryKey })
+            }
+          },
+        ],
+      })),
+  },
+}
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    mutations: {
+      meta: { utils: orpc },
+    },
+  },
+})
+```
+
+:::
+
 ## Client Context
 
 ::: warning

packages/tanstack-query/src/index.ts

@@ -1,5 +1,7 @@
 export * from './contract-utils'
 export * from './key'
+export * from './meta'
+export * from './plugin'
 export * from './procedure-utils'
 export * from './router-utils'
 export { createRouterUtils as createTanstackQueryUtils } from './router-utils'

packages/tanstack-query/src/meta.test-d.ts

@@ -0,0 +1,47 @@
+import type { ClientContext, ORPCError } from '@orpc/client'
+import type { PromiseWithError } from '@orpc/shared'
+import type { SkipToken } from '@tanstack/query-core'
+import type { OperationContext } from './types'
+import { oc, type } from '@orpc/contract'
+import { tanstackQuery } from './meta'
+
+describe('tanstackQuery', () => {
+  it('infers input, output and error types from the contract', () => {
+    oc
+      .errors({ BAD_GATEWAY: { data: type<string, RegExp>(vi.fn()) } })
+      .input(type<string, boolean>(vi.fn()))
+      .output(type<number, Date>(vi.fn()))
+      .meta(tanstackQuery({
+        queryOptions: { staleTime: 1000 },
+        queryInterceptors: [
+          async ({ context, input, next }) => {
+            expectTypeOf(input).toEqualTypeOf<string | SkipToken>()
+            expectTypeOf(context).toEqualTypeOf<ClientContext & OperationContext>()
+
+            const result = next()
+
+            expectTypeOf(result).toEqualTypeOf<
+              PromiseWithError<Date, Error | ORPCError<'BAD_GATEWAY', RegExp>>
+            >()
+
+            return result
+          },
+        ],
+        mutationOptions: {
+          onSuccess: (data, input) => {
+            expectTypeOf(data).toEqualTypeOf<Date>()
+            expectTypeOf(input).toEqualTypeOf<string>()
+          },
+        },
+      }))
+  })
+
+  it('rejects invalid base options', () => {
+    oc.output(type<number, Date>(vi.fn())).meta(tanstackQuery({
+      queryOptions: {
+        // @ts-expect-error - staleTime must be a number
+        staleTime: 'invalid',
+      },
+    }))
+  })
+})

packages/tanstack-query/src/meta.test.ts

@@ -0,0 +1,147 @@
+import { oc } from '@orpc/contract'
+import { ContractOptionsUtilsPlugin, getTanstackQueryMeta, tanstackQuery } from './meta'
+import { createRouterUtils } from './router-utils'
+
+describe('tanstackQuery', () => {
+  it('stores options readable via getTanstackQueryMeta', () => {
+    const interceptor = vi.fn()
+    const contract = oc.meta(tanstackQuery({
+      queryOptions: { staleTime: 1000 },
+      queryInterceptors: [interceptor],
+    }))
+
+    expect(getTanstackQueryMeta(contract)).toEqual({
+      queryOptions: { staleTime: 1000 },
+      queryInterceptors: [interceptor],
+    })
+
+    expect(getTanstackQueryMeta(oc)).toBeUndefined()
+  })
+
+  it('merges options when applied multiple times', () => {
+    const interceptor1 = vi.fn()
+    const interceptor2 = vi.fn()
+    const keyModifier = vi.fn()
+
+    const contract = oc
+      .meta(tanstackQuery({
+        queryKey: keyModifier,
+        queryOptions: { staleTime: 1000, retry: 1 },
+        queryInterceptors: [interceptor1],
+      }))
+      .meta(tanstackQuery({
+        queryOptions: { retry: 2 },
+        mutationInterceptors: [interceptor2],
+      }))
+
+    expect(getTanstackQueryMeta(contract)).toEqual({
+      queryKey: keyModifier,
+      queryOptions: { staleTime: 1000, retry: 2 },
+      queryInterceptors: [interceptor1],
+      mutationInterceptors: [interceptor2],
+    })
+  })
+
+  it('propagates base meta to procedures via .router', () => {
+    const router = oc
+      .meta(tanstackQuery({ queryOptions: { staleTime: 1000 } }))
+      .router({
+        ping: oc.meta(tanstackQuery({ queryOptions: { retry: 2 } })),
+        pong: oc,
+      })
+
+    expect(getTanstackQueryMeta(router.ping)).toEqual({
+      queryOptions: { staleTime: 1000, retry: 2 },
+    })
+
+    expect(getTanstackQueryMeta(router.pong)).toEqual({
+      queryOptions: { staleTime: 1000 },
+    })
+  })
+})
+
+describe('contractMetaPlugin', () => {
+  it('leaves options unchanged when no procedure or no meta at path', () => {
+    const plugin = new ContractOptionsUtilsPlugin({ planet: { find: oc } })
+    const options = { prefix: '__prefix__' }
+
+    expect(plugin.initProcedureOptions(['unknown'], options)).toBe(options)
+    expect(plugin.initProcedureOptions(['planet'], options)).toBe(options)
+    expect(plugin.initProcedureOptions(['planet', 'find'], options)).toBe(options)
+  })
+
+  it('merges meta options as base under current options', () => {
+    const metaInterceptor = vi.fn()
+    const existingInterceptor = vi.fn()
+
+    const plugin = new ContractOptionsUtilsPlugin({
+      planet: {
+        find: oc.meta(tanstackQuery({
+          queryOptions: { staleTime: 1000, retry: 1 },
+          queryInterceptors: [metaInterceptor],
+        })),
+      },
+    })
+
+    const result = plugin.initProcedureOptions(['planet', 'find'], {
+      prefix: '__prefix__',
+      queryOptions: { retry: 2 },
+      queryInterceptors: [existingInterceptor],
+    } as any)
+
+    expect(result).toEqual({
+      prefix: '__prefix__',
+      queryOptions: { staleTime: 1000, retry: 2 },
+      queryInterceptors: [metaInterceptor, existingInterceptor],
+    })
+  })
+
+  it('applies contract meta through createRouterUtils', async () => {
+    const marks: string[] = []
+    const metaInterceptor = vi.fn(({ next }: any) => {
+      marks.push('meta')
+      return next()
+    })
+    const utilsInterceptor = vi.fn(({ next }: any) => {
+      marks.push('utils')
+      return next()
+    })
+
+    const contract = {
+      planet: {
+        find: oc.meta(tanstackQuery({
+          queryOptions: { staleTime: 1000, retry: 1 },
+          queryInterceptors: [metaInterceptor],
+        })),
+      },
+    }
+
+    const client = {
+      planet: {
+        find: vi.fn(async () => '__found__'),
+      },
+    }
+
+    const utils = createRouterUtils(client as any, {
+      queryInterceptors: [utilsInterceptor],
+      scoped: {
+        planet: {
+          find: {
+            queryOptions: { retry: 2 },
+          },
+        },
+      },
+      plugins: [new ContractOptionsUtilsPlugin(contract)],
+    }) as any
+
+    const options = utils.planet.find.queryOptions({ input: { id: 1 } })
+
+    expect(options.staleTime).toBe(1000)
+    expect(options.retry).toBe(2)
+
+    await expect(options.queryFn({ signal: undefined })).resolves.toBe('__found__')
+
+    expect(marks).toEqual(['meta', 'utils'])
+    expect(client.planet.find).toHaveBeenCalledTimes(1)
+  })
+})