fix!: only accept jsonified client factories in createContractJsonifiedUtilsFactory (#2328)

## Problem

[Contract Client Factory](https://orpc.dev/docs/contract/client-factory)
tells OpenAPI Link users two things:

- create the client factory with `createContractJsonifiedClientFactory`
from `@orpc/openapi`;
- create the utils with `createContractJsonifiedUtilsFactory` from
`@orpc/tanstack-query` / `@orpc/pinia-colada`.

Following both fails, because the utils factory only accepted a plain
`ContractClientFactory`:

```ts
const createClient = createContractJsonifiedClientFactory(link, { contractRef })
const createUtils = createContractJsonifiedUtilsFactory(createClient, {})
// TS2345: Argument of type 'ContractJsonifiedClientFactory<ClientContext>' is not assignable to parameter of type
// 'ContractClientFactory<ClientContext>'. Type 'JsonifiedClient<RouterContractClient<T, ClientContext>>' is not
// assignable to type 'RouterContractClient<T, ClientContext>'.
```

## Fix

In both `@orpc/tanstack-query` and `@orpc/pinia-colada`,
`createContractJsonifiedUtilsFactory` now takes the jsonified client
factory:

```diff
- clientFactory: ContractClientFactory<TClientContext>,
+ clientFactory: ContractJsonifiedClientFactory<TClientContext>,
```

The jsonified utils factory always produces utils for `JsonifiedClient`,
so its input is now the client factory that declares jsonified clients.
This mirrors `createContractUtilsFactory`, which takes only a
`ContractClientFactory`:

| Client factory | Utils factory |
| --- | --- |
| `createContractClientFactory` (`@orpc/contract`) |
`createContractUtilsFactory` |
| `createContractJsonifiedClientFactory` (`@orpc/openapi`) |
`createContractJsonifiedUtilsFactory` |

Passing the other kind to either utils factory is now a type error.
Previously a plain client factory passed to the jsonified utils factory
was silently re-typed as jsonified.

`createContractJsonifiedClientFactory` is
`createContractClientFactory(...)` cast to
`ContractJsonifiedClientFactory`, so there is no runtime change. Neither
factory type is assignable to the other, so the restriction is enforced
in both directions.

Docs:

- **`createContractJsonifiedUtilsFactory`** gets a JSDoc block with a
`@see` link and the same `meta.path` note as
`createContractUtilsFactory`.
- **`createContractJsonifiedClientFactory`** (`@orpc/openapi`) gets a
JSDoc mirroring `createContractClientFactory`'s. It had none, and this
PR makes it the required input.
- **Docs page:** the two warnings (TanStack Query and Pinia Colada
sections) now say to pass a client factory created by
`createContractJsonifiedClientFactory`.

## Breaking change

`createContractJsonifiedUtilsFactory` no longer accepts a plain
`ContractClientFactory` (types only). Create the client factory with
`createContractJsonifiedClientFactory` from `@orpc/openapi` instead.

## Tests

In both packages, the `createContractJsonifiedUtilsFactory` cases in
`contract-utils.test-d.ts` now use a `ContractJsonifiedClientFactory`.
They cover interceptor input/output/error types and the procedure and
router utils types. Before this PR they failed with the TS2345 above.

## Verification

- `pnpm lint`, `pnpm vitest run packages/tanstack-query
packages/pinia-colada`, `pnpm type:check` (which includes the
playgrounds) and `pnpm docs:validate` pass.
- **Consumer projects**, against packed tarballs of every package from
`main` and from this branch:
- Setup: one TanStack Query consumer and one Pinia Colada consumer, each
installing only `@orpc/contract`, `@orpc/client`, `@orpc/openapi` and
the integration. They follow the docs: OpenAPI Link with `contractRef`,
a required `{ token: string }` context, and scoped options.
- Builds: `composite: true` with TS 6 (bundler and NodeNext) and TS 5.9.
- On `main`: the docs flow fails with the TS2345 above, and a plain
client factory passed to the jsonified utils factory is still accepted.
- On this branch: zero diagnostics, and passing the wrong kind of client
factory to either utils factory is a type error. The required context
reaches every interceptor and call site, jsonified output types reach
`queryOptions`/`fetchQuery`/`mutationOptions`, and the emitted JS is
byte-identical to `main`.
- **Not caused by this PR:** re-checking the emitted `.d.ts` with
`skipLibCheck: false` reports TS2304 for `dataTagSymbol` when a consumer
exports an inferred `queryKey`. This happens identically on `main` and
with `@tanstack/query-core` alone.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01U63hBfpeESmJiHXznRFzjN

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: dinwwwh

apps/content/docs/contract/client-factory.mdx

@@ -101,7 +101,7 @@ export const createUtils = createContractUtilsFactory(createClient, { /** option
 ```
 
 :::warning
-If you are using [OpenAPI Link](/docs/openapi/link), or any link that requires the client to be wrapped in `JsonifiedClient`, use `createContractJsonifiedUtilsFactory` from `@orpc/tanstack-query` instead of `createContractUtilsFactory`.
+If you are using [OpenAPI Link](/docs/openapi/link), or any link that requires the client to be wrapped in `JsonifiedClient`, use `createContractJsonifiedUtilsFactory` from `@orpc/tanstack-query` instead of `createContractUtilsFactory`, and pass it a client factory created by [`createContractJsonifiedClientFactory`](#contract-client-factory).
 :::
 
 You can then create utilities for each procedure contract:
@@ -135,7 +135,7 @@ export const createUtils = createContractUtilsFactory(createClient, { /** option
 ```
 
 :::warning
-If you are using [OpenAPI Link](/docs/openapi/link), or any link that requires the client to be wrapped in `JsonifiedClient`, use `createContractJsonifiedUtilsFactory` from `@orpc/pinia-colada` instead of `createContractUtilsFactory`.
+If you are using [OpenAPI Link](/docs/openapi/link), or any link that requires the client to be wrapped in `JsonifiedClient`, use `createContractJsonifiedUtilsFactory` from `@orpc/pinia-colada` instead of `createContractUtilsFactory`, and pass it a client factory created by [`createContractJsonifiedClientFactory`](#contract-client-factory).
 :::
 
 You can then create utilities for each procedure contract:

packages/openapi/src/client-factory.ts

@@ -20,6 +20,15 @@ export interface ContractJsonifiedClientFactoryOptions<
   contractRef?: RouterContract | undefined
 }
 
+/**
+ * Like `createContractClientFactory`, but the clients it builds are typed as `JsonifiedClient`,
+ * for links that require it, such as OpenAPI Link.
+ *
+ * @remarks
+ * **Warning**: Every procedure contract passed to the factory must define `meta.path` matching its location in the root contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/client-factory | Contract Client Factory}
+ */
 export function createContractJsonifiedClientFactory<
   TClientContext extends ClientContext,
 >(

packages/pinia-colada/src/contract-utils.test-d.ts

@@ -1,5 +1,6 @@
 import type { ORPCError } from '@orpc/client'
 import type { ContractClientFactory } from '@orpc/contract'
+import type { ContractJsonifiedClientFactory } from '@orpc/openapi'
 import type { PromiseWithError } from '@orpc/shared'
 import type { ProcedureUtils } from './procedure-utils'
 import type { SharedUtils } from './shared-utils'
@@ -18,9 +19,10 @@ const contract = {
   },
 }
 
-describe('createContractUtilsFactory', () => {
-  const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
+const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
+const jsonifiedClientFactory = {} as ContractJsonifiedClientFactory<{ cache?: boolean }>
 
+describe('createContractUtilsFactory', () => {
   it('infers interceptor input, output, errors types', () => {
     createContractUtilsFactory(clientFactory, {
       mutationInterceptors: [
@@ -98,10 +100,8 @@ describe('createContractUtilsFactory', () => {
 })
 
 describe('createContractJsonifiedUtilsFactory', () => {
-  const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
-
   it('infers interceptor input, output, errors types', () => {
-    createContractJsonifiedUtilsFactory(clientFactory, {
+    createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {
       mutationInterceptors: [
         async ({ context, next, input }) => {
           expectTypeOf(input).toEqualTypeOf<unknown>()
@@ -156,7 +156,7 @@ describe('createContractJsonifiedUtilsFactory', () => {
   })
 
   it('return jsonified general and procedure utils', () => {
-    const createUtils = createContractJsonifiedUtilsFactory(clientFactory, {})
+    const createUtils = createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {})
     const utils = createUtils(contract.nested.pong)
 
     expectTypeOf(utils).toEqualTypeOf<
@@ -165,7 +165,7 @@ describe('createContractJsonifiedUtilsFactory', () => {
   })
 
   it('returns jsonified router utils when a router contract is passed', () => {
-    const createUtils = createContractJsonifiedUtilsFactory(clientFactory, {})
+    const createUtils = createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {})
     const utils = createUtils(contract)
 
     expectTypeOf(utils.nested.pong).toEqualTypeOf<

packages/pinia-colada/src/contract-utils.ts

@@ -1,6 +1,6 @@
 import type { ClientContext } from '@orpc/client'
 import type { ContractClientFactory, RouterContract, RouterContractClient } from '@orpc/contract'
-import type { JsonifiedClient } from '@orpc/openapi'
+import type { ContractJsonifiedClientFactory, JsonifiedClient } from '@orpc/openapi'
 import type { RouterUtils, RouterUtilsOptions } from './router-utils'
 import { resolveBasePathMeta } from '@orpc/contract'
 import { get } from '@orpc/shared'
@@ -56,11 +56,22 @@ export interface ContractJsonifiedUtilsFactoryOptions<
 > extends Omit<RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>>, 'path'> {
 }
 
+/**
+ * Like `createContractUtilsFactory`, but for clients whose types are wrapped in `JsonifiedClient`,
+ * such as clients using OpenAPI Link.
+ *
+ * @remarks
+ * Takes a client factory created by `createContractJsonifiedClientFactory` from `@orpc/openapi`.
+ *
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/client-factory#pinia-colada-integration | Contract Client Factory - Pinia Colada Integration}
+ */
 export function createContractJsonifiedUtilsFactory<
   TClientContext extends ClientContext,
 >(
-  clientFactory: ContractClientFactory<TClientContext>,
+  clientFactory: ContractJsonifiedClientFactory<TClientContext>,
   options: ContractJsonifiedUtilsFactoryOptions<TClientContext>,
 ): ContractJsonifiedUtilsFactory<TClientContext> {
-  return createContractUtilsFactory(clientFactory, options) as ContractJsonifiedUtilsFactory<TClientContext>
+  return createContractUtilsFactory(clientFactory as ContractClientFactory<TClientContext>, options) as ContractJsonifiedUtilsFactory<TClientContext>
 }

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

@@ -1,5 +1,6 @@
 import type { ORPCError } from '@orpc/client'
 import type { ContractClientFactory } from '@orpc/contract'
+import type { ContractJsonifiedClientFactory } from '@orpc/openapi'
 import type { PromiseWithError } from '@orpc/shared'
 import type { ProcedureUtils } from './procedure-utils'
 import type { SharedUtils } from './shared-utils'
@@ -18,9 +19,10 @@ const contract = {
   },
 }
 
-describe('createContractUtilsFactory', () => {
-  const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
+const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
+const jsonifiedClientFactory = {} as ContractJsonifiedClientFactory<{ cache?: boolean }>
 
+describe('createContractUtilsFactory', () => {
   it('infers interceptor input, output, errors types', () => {
     createContractUtilsFactory(clientFactory, {
       mutationInterceptors: [
@@ -98,10 +100,8 @@ describe('createContractUtilsFactory', () => {
 })
 
 describe('createContractJsonifiedUtilsFactory', () => {
-  const clientFactory = {} as ContractClientFactory<{ cache?: boolean }>
-
   it('infers interceptor input, output, errors types', () => {
-    createContractJsonifiedUtilsFactory(clientFactory, {
+    createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {
       mutationInterceptors: [
         async ({ context, next, input }) => {
           expectTypeOf(input).toEqualTypeOf<unknown>()
@@ -156,7 +156,7 @@ describe('createContractJsonifiedUtilsFactory', () => {
   })
 
   it('return jsonified general and procedure utils', () => {
-    const createUtils = createContractJsonifiedUtilsFactory(clientFactory, {})
+    const createUtils = createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {})
     const utils = createUtils(contract.nested.pong)
 
     expectTypeOf(utils).toEqualTypeOf<
@@ -165,7 +165,7 @@ describe('createContractJsonifiedUtilsFactory', () => {
   })
 
   it('returns jsonified router utils when a router contract is passed', () => {
-    const createUtils = createContractJsonifiedUtilsFactory(clientFactory, {})
+    const createUtils = createContractJsonifiedUtilsFactory(jsonifiedClientFactory, {})
     const utils = createUtils(contract)
 
     expectTypeOf(utils.nested.pong).toEqualTypeOf<

packages/tanstack-query/src/contract-utils.ts

@@ -1,6 +1,6 @@
 import type { ClientContext } from '@orpc/client'
 import type { ContractClientFactory, RouterContract, RouterContractClient } from '@orpc/contract'
-import type { JsonifiedClient } from '@orpc/openapi'
+import type { ContractJsonifiedClientFactory, JsonifiedClient } from '@orpc/openapi'
 import type { RouterUtils, RouterUtilsOptions } from './router-utils'
 import { resolveBasePathMeta } from '@orpc/contract'
 import { get } from '@orpc/shared'
@@ -56,11 +56,22 @@ export interface ContractJsonifiedUtilsFactoryOptions<
 > extends Omit<RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>>, 'path'> {
 }
 
+/**
+ * Like `createContractUtilsFactory`, but for clients whose types are wrapped in `JsonifiedClient`,
+ * such as clients using OpenAPI Link.
+ *
+ * @remarks
+ * Takes a client factory created by `createContractJsonifiedClientFactory` from `@orpc/openapi`.
+ *
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/client-factory#tanstack-query-integration | Contract Client Factory - TanStack Query Integration}
+ */
 export function createContractJsonifiedUtilsFactory<
   TClientContext extends ClientContext,
 >(
-  clientFactory: ContractClientFactory<TClientContext>,
+  clientFactory: ContractJsonifiedClientFactory<TClientContext>,
   options: ContractJsonifiedUtilsFactoryOptions<TClientContext>,
 ): ContractJsonifiedUtilsFactory<TClientContext> {
-  return createContractUtilsFactory(clientFactory, options) as ContractJsonifiedUtilsFactory<TClientContext>
+  return createContractUtilsFactory(clientFactory as ContractClientFactory<TClientContext>, options) as ContractJsonifiedUtilsFactory<TClientContext>
 }