@kubb/plugin-react-query 3.0.0-alpha.0

package/src/plugin.ts

@@ -0,0 +1,183 @@
+import path from 'node:path'
+
+import { FileManager, PluginManager, createPlugin } from '@kubb/core'
+import { camelCase, pascalCase } from '@kubb/core/transformers'
+import { renderTemplate } from '@kubb/core/utils'
+import { pluginOasName } from '@kubb/plugin-oas'
+import { getGroupedByTagFiles } from '@kubb/plugin-oas/utils'
+import { pluginTsName } from '@kubb/plugin-ts'
+import { pluginZodName } from '@kubb/plugin-zod'
+
+import { OperationGenerator } from './OperationGenerator.tsx'
+import { Mutation, Operations, Query, QueryKey, QueryOptions } from './components/index.ts'
+
+import type { Plugin } from '@kubb/core'
+import type { PluginOas } from '@kubb/plugin-oas'
+import { QueryImports } from './components/QueryImports.tsx'
+import type { PluginReactQuery } from './types.ts'
+
+export const pluginReactQueryName = 'plugin-react-query' satisfies PluginReactQuery['name']
+
+export const pluginReactQuery = createPlugin<PluginReactQuery>((options) => {
+  const {
+    output = { path: 'hooks' },
+    group,
+    exclude = [],
+    include,
+    override = [],
+    parser,
+    suspense = {},
+    infinite,
+    transformers = {},
+    dataReturnType = 'data',
+    pathParamsType = 'inline',
+    mutate = {},
+    query = {},
+    queryOptions = {},
+    templates,
+  } = options
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
+
+  return {
+    name: pluginReactQueryName,
+    options: {
+      client: {
+        importPath: '@kubb/plugin-client/client',
+        ...options.client,
+      },
+      dataReturnType,
+      pathParamsType,
+      infinite: infinite
+        ? {
+            queryParam: 'id',
+            initialPageParam: 0,
+            cursorParam: undefined,
+            ...infinite,
+          }
+        : false,
+      suspense,
+      query: query
+        ? {
+            queryKey: (key: unknown[]) => key,
+            methods: ['get'],
+            importPath: '@tanstack/react-query',
+            ...query,
+          }
+        : false,
+      queryOptions,
+      mutate: mutate
+        ? {
+            variablesType: 'hook',
+            methods: ['post', 'put', 'patch', 'delete'],
+            ...mutate,
+          }
+        : false,
+      templates: {
+        mutation: Mutation.templates,
+        query: Query.templates,
+        queryOptions: QueryOptions.templates,
+        queryKey: QueryKey.templates,
+        queryImports: QueryImports.templates,
+        operations: Operations.templates,
+        ...templates,
+      },
+      parser,
+    },
+    pre: [pluginOasName, pluginTsName, parser === 'zod' ? pluginZodName : undefined].filter(Boolean),
+    resolvePath(baseName, pathMode, options) {
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = pathMode ?? FileManager.getMode(path.resolve(root, output.path))
+
+      if (mode === 'single') {
+        /**
+         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
+         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
+         */
+        return path.resolve(root, output.path)
+      }
+
+      if (options?.tag && group?.type === 'tag') {
+        const tag = camelCase(options.tag)
+
+        return path.resolve(root, renderTemplate(template, { tag }), baseName)
+      }
+
+      return path.resolve(root, output.path, baseName)
+    },
+    resolveName(name, type) {
+      let resolvedName = camelCase(name)
+
+      if (type === 'file' || type === 'function') {
+        resolvedName = camelCase(name, {
+          prefix: 'use',
+          isFile: type === 'file',
+        })
+      }
+      if (type === 'type') {
+        resolvedName = pascalCase(name)
+      }
+
+      if (type) {
+        return transformers?.name?.(resolvedName, type) || resolvedName
+      }
+
+      return resolvedName
+    },
+    async buildStart() {
+      const [swaggerPlugin]: [Plugin<PluginOas>] = PluginManager.getDependedPlugins<PluginOas>(this.plugins, [pluginOasName])
+
+      const oas = await swaggerPlugin.api.getOas()
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = FileManager.getMode(path.resolve(root, output.path))
+
+      const operationGenerator = new OperationGenerator(this.plugin.options, {
+        oas,
+        pluginManager: this.pluginManager,
+        plugin: this.plugin,
+        contentType: swaggerPlugin.api.contentType,
+        exclude,
+        include,
+        override,
+        mode,
+      })
+
+      const files = await operationGenerator.build()
+      await this.addFile(...files)
+    },
+    async writeFile(path, source) {
+      if (!path.endsWith('.ts') || !source) {
+        return
+      }
+
+      return this.fileManager.write(path, source, { sanity: false })
+    },
+    async buildEnd() {
+      if (this.config.output.write === false) {
+        return
+      }
+
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      if (group?.type === 'tag') {
+        const rootFiles = await getGroupedByTagFiles({
+          logger: this.logger,
+          files: this.fileManager.files,
+          plugin: this.plugin,
+          template,
+          exportAs: group.exportAs || '{{tag}}Hooks',
+          root,
+          output,
+        })
+
+        await this.addFile(...rootFiles)
+      }
+
+      await this.fileManager.addIndexes({
+        root,
+        output,
+        meta: { pluginKey: this.plugin.key },
+        logger: this.logger,
+      })
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,240 @@
+import type { Plugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type * as KubbFile from '@kubb/fs/types'
+
+import type { HttpMethod } from '@kubb/oas'
+import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
+import type { Mutation } from './components/Mutation.tsx'
+import type { Operations } from './components/Operations.tsx'
+import type { Query as QueryTemplate } from './components/Query.tsx'
+import type { QueryImports } from './components/QueryImports.tsx'
+import type { QueryKey } from './components/QueryKey.tsx'
+import type { QueryOptions as QueryOptionsTemplate } from './components/QueryOptions.tsx'
+
+type Templates = {
+  operations?: typeof Operations.templates | false
+  mutation?: typeof Mutation.templates | false
+  query?: typeof QueryTemplate.templates | false
+  queryOptions?: typeof QueryOptionsTemplate.templates | false
+  queryKey?: typeof QueryKey.templates | false
+}
+
+export type Suspense = object
+
+export type Query = {
+  /**
+   * Customize the queryKey, here you can specify a suffix.
+   */
+  queryKey: (key: unknown[]) => unknown[]
+  /**
+   * Define which HttpMethods can be used for queries
+   * @default ['get']
+   */
+  methods: Array<HttpMethod>
+  /**
+   * Path to the useQuery that will be used to do the useQuery functionality.
+   * It will be used as `import { useQuery } from '${importPath}'`.
+   * It allows both relative and absolute path.
+   * the path will be applied as is, so relative path should be based on the file being generated.
+   * @default '@tanstack/react-query'
+   */
+  importPath?: string
+}
+
+export type QueryOptions = object
+
+export type Mutate = {
+  /**
+   * Define the way of passing through the queryParams, headerParams and data.
+   * @default `'hook'`
+   */
+  variablesType: 'mutate' | 'hook'
+  /**
+   * Define which HttpMethods can be used for mutations
+   * @default ['post', 'put', 'delete']
+   */
+  methods: Array<HttpMethod>
+  /**
+   * Path to the useQuery that will be used to do the useQuery functionality.
+   * It will be used as `import { useQuery } from '${importPath}'`.
+   * It allows both relative and absolute path.
+   * the path will be applied as is, so relative path should be based on the file being generated.
+   * @default '@tanstack/react-query'
+   */
+  importPath?: string
+}
+
+export type Infinite = {
+  /**
+   * Specify the params key used for `pageParam`.
+   * Used inside `useInfiniteQuery`, `createInfiniteQueries`, `createInfiniteQuery`
+   * @default `'id'`
+   */
+  queryParam: string
+  /**
+   * Which field of the data will be used, set it to undefined when no cursor is known.
+   */
+  cursorParam?: string | undefined
+  /**
+   * The initial value, the value of the first page.
+   * @default `0`
+   */
+  initialPageParam: unknown
+}
+
+export type Options = {
+  output?: {
+    /**
+     * Output to save the @tanstack/query hooks.
+     * @default `"hooks"`
+     */
+    path: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './'`
+     */
+    exportAs?: string
+    /**
+     * Add an extension to the generated imports and exports, default it will not use an extension
+     */
+    extName?: KubbFile.Extname
+    /**
+     * Define what needs to exported, here you can also disable the export of barrel files
+     * @default `'barrel'`
+     */
+    exportType?: 'barrel' | 'barrelNamed' | false
+  }
+  /**
+   * Group the @tanstack/query hooks based on the provided name.
+   */
+  group?: {
+    /**
+     * Tag will group based on the operation tag inside the Swagger file
+     */
+    type: 'tag'
+    /**
+     * Relative path to save the grouped @tanstack/query hooks.
+     *
+     * `{{tag}}` will be replaced by the current tagName.
+     * @example `${output}/{{tag}}Controller` => `hooks/PetController`
+     * @default `${output}/{{tag}}Controller`
+     */
+    output?: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './`
+     * @default `"{{tag}}Hooks"`
+     */
+    exportAs?: string
+  }
+
+  client?: {
+    /**
+     * Path to the client that will be used to do the API calls.
+     * It will be used as `import client from '${client.importPath}'`.
+     * It allows both relative and absolute path.
+     * the path will be applied as is, so relative path should be based on the file being generated.
+     * @default '@kubb/plugin-client/client'
+     */
+    importPath?: string
+  }
+  /**
+   * ReturnType that needs to be used when calling client().
+   *
+   * `Data` will return ResponseConfig[data].
+   *
+   * `Full` will return ResponseConfig.
+   * @default `'data'`
+   * @private
+   */
+  /**
+   * ReturnType that needs to be used when calling client().
+   *
+   * `Data` will return ResponseConfig[data].
+   *
+   * `Full` will return ResponseConfig.
+   * @default `'data'`
+   * @private
+   */
+  dataReturnType?: 'data' | 'full'
+  /**
+   * How to pass your pathParams.
+   *
+   * `object` will return the pathParams as an object.
+   *
+   * `inline` will return the pathParams as comma separated params.
+   * @default `'inline'`
+   * @private
+   */
+  pathParamsType?: 'object' | 'inline'
+  /**
+   * Which parser can be used before returning the data to `@tanstack/query`.
+   * `'zod'` will use `@kubb/plugin-zod` to parse the data.
+   */
+  parser?: 'zod'
+  /**
+   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   */
+  exclude?: Array<Exclude>
+  /**
+   * Array containing include parameters to include tags/operations/methods/paths.
+   */
+  include?: Array<Include>
+  /**
+   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   */
+  override?: Array<Override<ResolvedOptions>>
+  /**
+   * When set, an infiniteQuery hooks will be added.
+   */
+  infinite?: Partial<Infinite> | false
+  /**
+   * When set, a suspenseQuery hooks will be added.
+   */
+  suspense?: Partial<Suspense> | false
+  /**
+   * Override some useQuery behaviours.
+   */
+  query?: Partial<Query> | false
+  queryOptions?: Partial<QueryOptions> | false
+  /**
+   * Override some useMutation behaviours.
+   */
+  mutate?: Mutate | false
+  transformers?: {
+    /**
+     * Customize the names based on the type that is provided by the plugin.
+     */
+    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+  }
+  /**
+   * Make it possible to override one of the templates
+   */
+  templates?: Partial<Templates>
+}
+
+type ResolvedOptions = {
+  client: Required<NonNullable<PluginReactQuery['options']['client']>>
+  dataReturnType: NonNullable<PluginReactQuery['options']['dataReturnType']>
+  pathParamsType: NonNullable<PluginReactQuery['options']['pathParamsType']>
+  parser: PluginReactQuery['options']['parser']
+  /**
+   * Only used of infinite
+   */
+  infinite: Infinite | false
+  suspense: Suspense | false
+  query: Query | false
+  queryOptions: QueryOptions | false
+  mutate: Mutate | false
+  templates: NonNullable<Templates>
+}
+
+export type FileMeta = {
+  pluginKey?: Plugin['key']
+  tag?: string
+}
+
+export type PluginReactQuery = PluginFactoryOptions<'plugin-react-query', Options, ResolvedOptions, never, ResolvePathOptions>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/plugin-react-query']: PluginReactQuery
+  }
+}

package/src/utils.ts

@@ -0,0 +1,96 @@
+import { PackageManager } from '@kubb/core'
+
+export const reactQueryDepRegex = /@tanstack\/(react|solid|vue|svelte)-query/
+
+export function getImportNames() {
+  const isV5 = new PackageManager().isValidSync(reactQueryDepRegex, '>=5')
+
+  return {
+    mutation: {
+      react: {
+        path: '@tanstack/react-query',
+        hookName: 'useMutation',
+        optionsType: 'UseMutationOptions',
+        resultType: 'UseMutationResult',
+      },
+      solid: {
+        path: '@tanstack/solid-query',
+        hookName: 'createMutation',
+        optionsType: 'CreateMutationOptions',
+        resultType: 'CreateMutationResult',
+      },
+      svelte: {
+        path: '@tanstack/svelte-query',
+        hookName: 'createMutation',
+        optionsType: 'CreateMutationOptions',
+        resultType: 'CreateMutationResult',
+      },
+      vue: {
+        path: '@tanstack/vue-query',
+        hookName: 'useMutation',
+        optionsType: isV5 ? 'UseMutationOptions' : 'VueMutationObserverOptions',
+        resultType: 'UseMutationReturnType',
+      },
+    },
+    query: {
+      react: {
+        path: '@tanstack/react-query',
+        hookName: 'useQuery',
+        optionsType: isV5 ? 'QueryObserverOptions' : 'UseBaseQueryOptions',
+        resultType: 'UseQueryResult',
+      },
+      solid: {
+        path: '@tanstack/solid-query',
+        hookName: 'createQuery',
+        optionsType: 'CreateBaseQueryOptions',
+        resultType: 'CreateQueryResult',
+      },
+      svelte: {
+        path: '@tanstack/svelte-query',
+        hookName: 'createQuery',
+        optionsType: 'CreateBaseQueryOptions',
+        resultType: 'CreateQueryResult',
+      },
+      vue: {
+        path: '@tanstack/vue-query',
+        hookName: 'useQuery',
+        optionsType: isV5 ? 'QueryObserverOptions' : 'VueQueryObserverOptions',
+        resultType: isV5 ? 'UseQueryReturnType' : 'UseQueryReturnType',
+      },
+    },
+    queryInfinite: {
+      react: {
+        path: '@tanstack/react-query',
+        hookName: 'useInfiniteQuery',
+        optionsType: isV5 ? 'InfiniteQueryObserverOptions' : 'UseInfiniteQueryOptions',
+        resultType: 'UseInfiniteQueryResult',
+      },
+      solid: {
+        path: '@tanstack/solid-query',
+        hookName: 'createInfiniteQuery',
+        optionsType: 'CreateInfiniteQueryOptions',
+        resultType: 'CreateInfiniteQueryResult',
+      },
+      svelte: {
+        path: '@tanstack/svelte-query',
+        hookName: 'createInfiniteQuery',
+        optionsType: 'CreateInfiniteQueryOptions',
+        resultType: 'CreateInfiniteQueryResult',
+      },
+      vue: {
+        path: '@tanstack/vue-query',
+        hookName: 'useInfiniteQuery',
+        optionsType: isV5 ? 'UseInfiniteQueryOptions' : 'VueInfiniteQueryObserverOptions',
+        resultType: isV5 ? 'UseInfiniteQueryReturnType' : 'VueInfiniteQueryObserverOptions',
+      },
+    },
+    querySuspense: {
+      react: {
+        path: '@tanstack/react-query',
+        hookName: 'useSuspenseQuery',
+        optionsType: 'UseSuspenseQueryOptions',
+        resultType: 'UseSuspenseQueryResult',
+      },
+    },
+  } as const
+}