feat(pinia-colada): define base options and interceptors via contract meta (#1718)

## Summary

Port of #1705 to `@orpc/pinia-colada`. Define base Pinia Colada options
and interceptors directly on a procedure contract via `piniaColada`, and
apply them automatically with the new `ContractOptionsUtilsPlugin`.

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

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

- `piniaColada` 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, any pair involving a function
modifier composes, and a key explicitly set to `undefined` resets the
value from lower layers
- `getPiniaColadaMeta` reads the stored options for custom integrations
- `UseMutationFnContext` now matches the runtime merged mutation
context, so values provided by a global `onMutate` are typed inside
mutation interceptors via `UseMutationContextCommon` augmentation
- Docs cover the plugin, the reference-only nature of contract types,
and passing runtime values such as router utils through a global
`onMutate` hook for optimistic updates

Author: dinwwwh

apps/content/docs/integrations/pinia-colada.md

@@ -288,6 +288,104 @@ const orpc = createPiniaColadaUtils(client, {
 })
 ```
 
+### Contract Options Plugin
+
+Use `piniaColada` 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, piniaColada } from '@orpc/pinia-colada'
+
+export const contract = {
+  planet: {
+    find: oc
+      .input(z.object({ id: z.number() }))
+      .meta(piniaColada({
+        queryOptions: {
+          staleTime: 60 * 1000,
+        },
+        queryInterceptors: [
+          async ({ input, next }) => {
+            // input, output, and errors are typed based on the contract
+            return await next()
+          },
+        ],
+      })),
+  },
+}
+
+const orpc = createPiniaColadaUtils(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 `piniaColada` cannot import runtime values such as your router utils. Instead, augment [`UseMutationContextCommon`](https://pinia-colada.esm.dev/api/@pinia/colada/interfaces/UseMutationContextCommon.html) and provide the values through a global `onMutate` hook, which merges them into the `fnContext` of every mutation. The example below reads router utils and the query cache from `fnContext` to optimistically update a query:
+
+```ts
+import type { RouterContractClient } from '@orpc/contract'
+import type { RouterUtils } from '@orpc/pinia-colada'
+import type { QueryCache } from '@pinia/colada'
+
+declare module '@pinia/colada' {
+  interface UseMutationContextCommon {
+    utils: RouterUtils<RouterContractClient<typeof contract>>
+    queryCache: QueryCache
+  }
+}
+
+export const contract = {
+  planet: {
+    find: oc.input(z.object({ id: z.number() })),
+    update: oc
+      .input(z.object({ id: z.number(), name: z.string() }))
+      .meta(piniaColada({
+        mutationInterceptors: [
+          async ({ input, next, fnContext }) => {
+            const { utils, queryCache } = fnContext
+
+            if (!utils || !queryCache) {
+              return next()
+            }
+
+            const queryKey = utils.planet.find.queryKey({ input: { id: input.id } })
+            const previous = queryCache.getQueryData(queryKey)
+
+            // optimistically update before the request
+            queryCache.setQueryData(queryKey, input)
+
+            try {
+              return await next()
+            }
+            catch (error) {
+              // roll back on error
+              queryCache.setQueryData(queryKey, previous)
+              throw error
+            }
+            finally {
+              queryCache.invalidateQueries({ key: queryKey })
+            }
+          },
+        ],
+      })),
+  },
+}
+
+app.use(PiniaColada, {
+  mutationOptions: {
+    onMutate: () => ({
+      utils: orpc,
+      queryCache: useQueryCache(pinia),
+    }),
+  },
+})
+```
+
+:::
+
 ## Client Context
 
 When a client is invoked through the Pinia Colada integration, an **operation context** is automatically added to the [client context](/docs/client/client-side#client-context). You can use this context to configure request behavior, such as selecting the HTTP method for [RPC Link](/docs/rpc/link#request-method).

packages/pinia-colada/src/index.ts

@@ -1,6 +1,7 @@
 export * from './contract-utils'
 export * from './key'
 export * from './live-query'
+export * from './meta'
 export * from './plugin'
 export * from './procedure-utils'
 export * from './router-utils'

packages/pinia-colada/src/meta.test-d.ts

@@ -0,0 +1,46 @@
+import type { ClientContext, ORPCError } from '@orpc/client'
+import type { PromiseWithError } from '@orpc/shared'
+import type { OperationContext } from './types'
+import { oc, type } from '@orpc/contract'
+import { piniaColada } from './meta'
+
+describe('piniaColada', () => {
+  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(piniaColada({
+        queryOptions: { staleTime: 1000 },
+        queryInterceptors: [
+          async ({ context, input, next }) => {
+            expectTypeOf(input).toEqualTypeOf<string>()
+            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(piniaColada({
+      queryOptions: {
+        // @ts-expect-error - staleTime must be a number
+        staleTime: 'invalid',
+      },
+    }))
+  })
+})

packages/pinia-colada/src/meta.test.ts

@@ -0,0 +1,147 @@
+import { oc } from '@orpc/contract'
+import { ContractOptionsUtilsPlugin, getPiniaColadaMeta, piniaColada } from './meta'
+import { createRouterUtils } from './router-utils'
+
+describe('piniaColada', () => {
+  it('stores options readable via getPiniaColadaMeta', () => {
+    const interceptor = vi.fn()
+    const contract = oc.meta(piniaColada({
+      queryOptions: { staleTime: 1000 },
+      queryInterceptors: [interceptor],
+    }))
+
+    expect(getPiniaColadaMeta(contract)).toEqual({
+      queryOptions: { staleTime: 1000 },
+      queryInterceptors: [interceptor],
+    })
+
+    expect(getPiniaColadaMeta(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(piniaColada({
+        queryKey: keyModifier,
+        queryOptions: { staleTime: 1000, gcTime: 1 },
+        queryInterceptors: [interceptor1],
+      }))
+      .meta(piniaColada({
+        queryOptions: { gcTime: 2 },
+        mutationInterceptors: [interceptor2],
+      }))
+
+    expect(getPiniaColadaMeta(contract)).toEqual({
+      queryKey: keyModifier,
+      queryOptions: { staleTime: 1000, gcTime: 2 },
+      queryInterceptors: [interceptor1],
+      mutationInterceptors: [interceptor2],
+    })
+  })
+
+  it('propagates base meta to procedures via .router', () => {
+    const router = oc
+      .meta(piniaColada({ queryOptions: { staleTime: 1000 } }))
+      .router({
+        ping: oc.meta(piniaColada({ queryOptions: { gcTime: 2 } })),
+        pong: oc,
+      })
+
+    expect(getPiniaColadaMeta(router.ping)).toEqual({
+      queryOptions: { staleTime: 1000, gcTime: 2 },
+    })
+
+    expect(getPiniaColadaMeta(router.pong)).toEqual({
+      queryOptions: { staleTime: 1000 },
+    })
+  })
+})
+
+describe('contractOptionsUtilsPlugin', () => {
+  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(piniaColada({
+          queryOptions: { staleTime: 1000, gcTime: 1 },
+          queryInterceptors: [metaInterceptor],
+        })),
+      },
+    })
+
+    const result = plugin.initProcedureOptions(['planet', 'find'], {
+      prefix: '__prefix__',
+      queryOptions: { gcTime: 2 },
+      queryInterceptors: [existingInterceptor],
+    } as any)
+
+    expect(result).toEqual({
+      prefix: '__prefix__',
+      queryOptions: { staleTime: 1000, gcTime: 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(piniaColada({
+          queryOptions: { staleTime: 1000, gcTime: 1 },
+          queryInterceptors: [metaInterceptor],
+        })),
+      },
+    }
+
+    const client = {
+      planet: {
+        find: vi.fn(async () => '__found__'),
+      },
+    }
+
+    const utils = createRouterUtils(client as any, {
+      queryInterceptors: [utilsInterceptor],
+      scoped: {
+        planet: {
+          find: {
+            queryOptions: { gcTime: 2 },
+          },
+        },
+      },
+      plugins: [new ContractOptionsUtilsPlugin(contract)],
+    }) as any
+
+    const options = utils.planet.find.queryOptions({ input: { id: 1 } })
+
+    expect(options.staleTime).toBe(1000)
+    expect(options.gcTime).toBe(2)
+
+    await expect(options.query({ signal: undefined })).resolves.toBe('__found__')
+
+    expect(marks).toEqual(['meta', 'utils'])
+    expect(client.planet.find).toHaveBeenCalledTimes(1)
+  })
+})