feat(query, vue-colada)!: update utils options (#209)

* strategy options

* router query utils options

* sync tests

* procedure utils options

Author: dinwwwh

apps/content/docs/pinia-colada.md

@@ -61,8 +61,12 @@ orpc.planet.find.queryOptions({ input: { id: 123 } })
 Prevent key conflicts by passing a unique base key when creating your utils:
 
 ```ts
-const userORPC = createORPCVueColadaUtils(userClient, ['user'])
-const postORPC = createORPCVueColadaUtils(postClient, ['post'])
+const userORPC = createORPCVueColadaUtils(userClient, {
+  path: ['user']
+})
+const postORPC = createORPCVueColadaUtils(postClient, {
+  path: ['post']
+})
 ```
 
 ## Query Options Utility

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

@@ -57,8 +57,12 @@ orpc.planet.find.queryOptions({ input: { id: 123 } })
 Prevent key conflicts by passing a unique base key when creating your utils:
 
 ```ts
-const userORPC = createORPCReactQueryUtils(userClient, ['user'])
-const postORPC = createORPCReactQueryUtils(postClient, ['post'])
+const userORPC = createORPCReactQueryUtils(userClient, {
+  path: ['user']
+})
+const postORPC = createORPCReactQueryUtils(postClient, {
+  path: ['post']
+})
 ```
 
 ## Using React Context

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

@@ -57,6 +57,10 @@ orpc.planet.find.queryOptions({ input: { id: 123 } })
 Prevent key conflicts by passing a unique base key when creating your utils:
 
 ```ts
-const userORPC = createORPCVueQueryUtils(userClient, ['user'])
-const postORPC = createORPCVueQueryUtils(postClient, ['post'])
+const userORPC = createORPCVueQueryUtils(userClient, {
+  path: ['user']
+})
+const postORPC = createORPCVueQueryUtils(postClient, {
+  path: ['post']
+})
 ```

packages/openapi/src/openapi-generator.ts

@@ -85,8 +85,8 @@ export class OpenAPIGenerator {
       ref.requestBody = {
         required: true,
         content: toOpenAPIEventIteratorContent(
-          this.converter.convert(details.yields, 'input'),
-          this.converter.convert(details.returns, 'input'),
+          this.converter.convert(details.yields, { strategy: 'input' }),
+          this.converter.convert(details.returns, { strategy: 'input' }),
         ),
       }
 
@@ -95,7 +95,7 @@ export class OpenAPIGenerator {
 
     const dynamicParams = getDynamicParams(def.route.path)
     const inputStructure = fallbackContractConfig('defaultInputStructure', def.route.inputStructure)
-    let [required, schema] = this.converter.convert(def.inputSchema, 'input')
+    let [required, schema] = this.converter.convert(def.inputSchema, { strategy: 'input' })
 
     if (isAnySchema(schema) && !dynamicParams?.length) {
       return
@@ -203,15 +203,15 @@ export class OpenAPIGenerator {
       ref.responses[status] = {
         description,
         content: toOpenAPIEventIteratorContent(
-          this.converter.convert(eventIteratorSchemaDetails.yields, 'output'),
-          this.converter.convert(eventIteratorSchemaDetails.returns, 'output'),
+          this.converter.convert(eventIteratorSchemaDetails.yields, { strategy: 'output' }),
+          this.converter.convert(eventIteratorSchemaDetails.returns, { strategy: 'output' }),
         ),
       }
 
       return
     }
 
-    const [_, json] = this.converter.convert(outputSchema, 'output')
+    const [_, json] = this.converter.convert(outputSchema, { strategy: 'output' })
 
     ref.responses ??= {}
     ref.responses[status] = {
@@ -267,7 +267,7 @@ export class OpenAPIGenerator {
       const status = fallbackORPCErrorStatus(code, config.status)
       const message = fallbackORPCErrorMessage(code, config.message)
 
-      const [dataRequired, dataSchema] = this.converter.convert(config.data, 'output')
+      const [dataRequired, dataSchema] = this.converter.convert(config.data, { strategy: 'output' })
 
       errors[status] ??= []
       errors[status].push({

packages/openapi/src/schema-converter.test.ts

@@ -24,25 +24,25 @@ describe('compositeSchemaConverter', () => {
   const schema = z.object({})
 
   it('fallback to any if no condition is matched', () => {
-    expect(converter.convert(schema, 'input')).toEqual([false, {}])
+    expect(converter.convert(schema, { strategy: 'input' })).toEqual([false, {}])
 
     expect(converter1.condition).toBeCalledTimes(1)
-    expect(converter1.condition).toBeCalledWith(schema, 'input')
+    expect(converter1.condition).toBeCalledWith(schema, { strategy: 'input' })
     expect(converter1.convert).not.toHaveBeenCalled()
     expect(converter2.condition).toBeCalledTimes(1)
-    expect(converter2.condition).toBeCalledWith(schema, 'input')
+    expect(converter2.condition).toBeCalledWith(schema, { strategy: 'input' })
     expect(converter2.convert).not.toHaveBeenCalled()
   })
 
   it('return result of first converter if condition is matched', () => {
     converter1.condition.mockReturnValue(true)
     converter1.convert.mockReturnValue('__MATCHED__')
 
-    expect(converter.convert(schema, 'input')).toEqual('__MATCHED__')
+    expect(converter.convert(schema, { strategy: 'input' })).toEqual('__MATCHED__')
 
     expect(converter1.condition).toBeCalledTimes(1)
     expect(converter1.convert).toHaveBeenCalled()
-    expect(converter1.convert).toBeCalledWith(schema, 'input')
+    expect(converter1.convert).toBeCalledWith(schema, { strategy: 'input' })
 
     expect(converter2.condition).not.toHaveBeenCalled()
     expect(converter2.convert).not.toHaveBeenCalled()

packages/openapi/src/schema-converter.ts

@@ -1,14 +1,16 @@
 import type { Schema } from '@orpc/contract'
 import type { JSONSchema } from './schema'
 
-export type SchemaConvertStrategy = 'input' | 'output'
+export interface SchemaConvertOptions {
+  strategy: 'input' | 'output'
+}
 
 export interface SchemaConverter {
-  convert(schema: Schema, strategy: SchemaConvertStrategy): [required: boolean, jsonSchema: JSONSchema]
+  convert(schema: Schema, options: SchemaConvertOptions): [required: boolean, jsonSchema: JSONSchema]
 }
 
 export interface ConditionalSchemaConverter extends SchemaConverter {
-  condition(schema: Schema, strategy: SchemaConvertStrategy): boolean
+  condition(schema: Schema, options: SchemaConvertOptions): boolean
 }
 
 export class CompositeSchemaConverter implements SchemaConverter {
@@ -18,10 +20,10 @@ export class CompositeSchemaConverter implements SchemaConverter {
     this.converters = converters
   }
 
-  convert(schema: Schema, strategy: SchemaConvertStrategy): [required: boolean, jsonSchema: JSONSchema] {
+  convert(schema: Schema, options: SchemaConvertOptions): [required: boolean, jsonSchema: JSONSchema] {
     for (const converter of this.converters) {
-      if (converter.condition(schema, strategy)) {
-        return converter.convert(schema, strategy)
+      if (converter.condition(schema, options)) {
+        return converter.convert(schema, options)
       }
     }
 

packages/react-query/src/procedure-utils.test.ts

@@ -11,7 +11,7 @@ describe('createProcedureUtils', () => {
   const controller = new AbortController()
   const signal = controller.signal
   const client = vi.fn().mockResolvedValue('__output__')
-  const utils = createProcedureUtils(client, ['ping'])
+  const utils = createProcedureUtils(client, { path: ['ping'] })
 
   it('.call', () => {
     expect(utils.call).toBe(client)

packages/react-query/src/procedure-utils.ts

@@ -22,36 +22,40 @@ export interface ProcedureUtils<TClientContext extends ClientContext, TInput, TO
   ): MutationOptions<TInput, TOutput, TError, UMutationContext>
 }
 
+export interface CreateProcedureUtilsOptions {
+  path: string[]
+}
+
 export function createProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError extends Error>(
   client: Client<TClientContext, TInput, TOutput, TError>,
-  path: string[],
+  options: CreateProcedureUtilsOptions,
 ): ProcedureUtils<TClientContext, TInput, TOutput, TError> {
   return {
     call: client,
 
-    queryOptions(...[options = {} as any]) {
+    queryOptions(...[optionsIn = {} as any]) {
       return {
-        queryKey: buildKey(path, { type: 'query', input: options.input }),
-        queryFn: ({ signal }) => client(options.input, { signal, context: options.context }),
-        ...options,
+        queryKey: buildKey(options.path, { type: 'query', input: optionsIn.input }),
+        queryFn: ({ signal }) => client(optionsIn.input, { signal, context: optionsIn.context }),
+        ...optionsIn,
       }
     },
 
-    infiniteOptions(options) {
+    infiniteOptions(optionsIn) {
       return {
-        queryKey: buildKey(path, { type: 'infinite', input: options.input(options.initialPageParam) as any }),
+        queryKey: buildKey(options.path, { type: 'infinite', input: optionsIn.input(optionsIn.initialPageParam) as any }),
         queryFn: ({ pageParam, signal }) => {
-          return client(options.input(pageParam as any), { signal, context: options.context as any })
+          return client(optionsIn.input(pageParam as any), { signal, context: optionsIn.context as any })
         },
-        ...(options as any),
+        ...(optionsIn as any),
       }
     },
 
-    mutationOptions(...[options = {} as any]) {
+    mutationOptions(...[optionsIn = {} as any]) {
       return {
-        mutationKey: buildKey(path, { type: 'mutation' }),
-        mutationFn: input => client(input, { context: options.context }),
-        ...(options as any),
+        mutationKey: buildKey(options.path, { type: 'mutation' }),
+        mutationFn: input => client(input, { context: optionsIn.context }),
+        ...(optionsIn as any),
       }
     },
   }

packages/react-query/src/router-utils.test.ts

@@ -15,12 +15,14 @@ describe('createRouterUtils', () => {
   client.key.pong = vi.fn()
 
   it('works', () => {
-    const utils = createRouterUtils(client, ['__base__']) as any
+    const utils = createRouterUtils(client, {
+      path: ['__base__'],
+    }) as any
 
     expect(generalUtilsSpy).toHaveBeenCalledTimes(1)
     expect(generalUtilsSpy).toHaveBeenCalledWith(['__base__'])
     expect(procedureUtilsSpy).toHaveBeenCalledTimes(1)
-    expect(procedureUtilsSpy).toHaveBeenCalledWith(client, ['__base__'])
+    expect(procedureUtilsSpy).toHaveBeenCalledWith(client, { path: ['__base__'] })
 
     expect(utils.key()).toEqual(generalUtilsSpy.mock.results[0]!.value.key())
     expect(utils.queryOptions().queryKey).toEqual(procedureUtilsSpy.mock.results[0]!.value.queryOptions().queryKey)
@@ -31,7 +33,7 @@ describe('createRouterUtils', () => {
     expect(generalUtilsSpy).toHaveBeenCalledTimes(1)
     expect(generalUtilsSpy).toHaveBeenCalledWith(['__base__', 'key'])
     expect(procedureUtilsSpy).toHaveBeenCalledTimes(1)
-    expect(procedureUtilsSpy).toHaveBeenCalledWith(client.key, ['__base__', 'key'])
+    expect(procedureUtilsSpy).toHaveBeenCalledWith(client.key, { path: ['__base__', 'key'] })
 
     expect(keyUtils.key()).toEqual(generalUtilsSpy.mock.results[0]!.value.key())
     expect(keyUtils.queryOptions().queryKey).toEqual(procedureUtilsSpy.mock.results[0]!.value.queryOptions().queryKey)
@@ -44,15 +46,17 @@ describe('createRouterUtils', () => {
     expect(generalUtilsSpy).toHaveBeenNthCalledWith(2, ['__base__', 'key', 'pong'])
 
     expect(procedureUtilsSpy).toHaveBeenCalledTimes(2)
-    expect(procedureUtilsSpy).toHaveBeenNthCalledWith(1, client.key, ['__base__', 'key'])
-    expect(procedureUtilsSpy).toHaveBeenNthCalledWith(2, client.key.pong, ['__base__', 'key', 'pong'])
+    expect(procedureUtilsSpy).toHaveBeenNthCalledWith(1, client.key, { path: ['__base__', 'key'] })
+    expect(procedureUtilsSpy).toHaveBeenNthCalledWith(2, client.key.pong, { path: ['__base__', 'key', 'pong'] })
 
     expect(pongUtils.key()).toEqual(generalUtilsSpy.mock.results[1]!.value.key())
     expect(pongUtils.queryOptions().queryKey).toEqual(procedureUtilsSpy.mock.results[1]!.value.queryOptions().queryKey)
   })
 
   it('not recursive on symbol', async () => {
-    const utils = createRouterUtils(client, ['__base__']) as any
+    const utils = createRouterUtils(client, {
+      path: ['__base__'],
+    }) as any
 
     expect(utils[Symbol.for('a')]).toBe(undefined)
   })

packages/react-query/src/router-utils.ts

@@ -9,16 +9,18 @@ export type RouterUtils<T extends NestedClient<any>> =
       [K in keyof T]: T[K] extends NestedClient<any> ? RouterUtils<T[K]> : never
     } & GeneralUtils<unknown>
 
-/**
- * @param client - Any kind of oRPC clients: `createRouterClient`, `createORPCClient`, ...
- * @param path - The base path for query key, when it it will be prefix to all keys
- */
+export interface CreateRouterUtilsOptions {
+  path?: string[]
+}
+
 export function createRouterUtils<T extends NestedClient<any>>(
   client: T,
-  path: string[] = [],
+  options: CreateRouterUtilsOptions = {},
 ): RouterUtils<T> {
+  const path = options.path ?? []
+
   const generalUtils = createGeneralUtils(path)
-  const procedureUtils = createProcedureUtils(client as any, path)
+  const procedureUtils = createProcedureUtils(client as any, { path })
 
   const recursive = new Proxy({
     ...generalUtils,
@@ -31,7 +33,7 @@ export function createRouterUtils<T extends NestedClient<any>>(
         return value
       }
 
-      const nextUtils = createRouterUtils((client as any)[prop], [...path, prop])
+      const nextUtils = createRouterUtils((client as any)[prop], { ...options, path: [...path, prop] })
 
       if (typeof value !== 'function') {
         return nextUtils