@kubb/plugin-client 3.0.0-alpha.0

package/src/components/Client.tsx

@@ -0,0 +1,260 @@
+import { URLPath } from '@kubb/core/utils'
+import { Parser, File, Function, useApp } from '@kubb/react'
+import { pluginTsName } from '@kubb/plugin-ts'
+import { useOperation, useOperationManager } from '@kubb/plugin-oas/hooks'
+import { getComments, getPathParams } from '@kubb/plugin-oas/utils'
+
+import { isOptional } from '@kubb/oas'
+import type { HttpMethod } from '@kubb/oas'
+import type { KubbNode, Params } from '@kubb/react'
+import type { ComponentProps, ComponentType } from 'react'
+import type { FileMeta, PluginClient } from '../types.ts'
+
+type TemplateProps = {
+  /**
+   * Name of the function
+   */
+  name: string
+  /**
+   * Parameters/options/props that need to be used
+   */
+  params: Params
+  /**
+   * Generics that needs to be added for TypeScript
+   */
+  generics?: string
+  /**
+   * ReturnType(see async for adding Promise type)
+   */
+  returnType?: string
+  /**
+   * Options for JSdocs
+   */
+  JSDoc?: {
+    comments: string[]
+  }
+  client: {
+    baseURL: string | undefined
+    generics: string | string[]
+    method: HttpMethod
+    path: URLPath
+    dataReturnType: PluginClient['options']['dataReturnType']
+    withQueryParams: boolean
+    withData: boolean
+    withHeaders: boolean
+    contentType: string
+  }
+}
+
+function Template({ name, generics, returnType, params, JSDoc, client }: TemplateProps): KubbNode {
+  const isFormData = client.contentType === 'multipart/form-data'
+  const headers = [
+    client.contentType !== 'application/json' ? `'Content-Type': '${client.contentType}'` : undefined,
+    client.withHeaders ? '...headers' : undefined,
+  ]
+    .filter(Boolean)
+    .join(', ')
+  const clientParams: Params = {
+    data: {
+      mode: 'object',
+      children: {
+        method: {
+          type: 'string',
+          value: JSON.stringify(client.method),
+        },
+        url: {
+          type: 'string',
+          value: client.path.template,
+        },
+        baseURL: client.baseURL
+          ? {
+              type: 'string',
+              value: JSON.stringify(client.baseURL),
+            }
+          : undefined,
+        params: client.withQueryParams
+          ? {
+              type: 'any',
+            }
+          : undefined,
+        data: client.withData
+          ? {
+              type: 'any',
+              value: isFormData ? 'formData' : undefined,
+            }
+          : undefined,
+        headers: headers.length
+          ? {
+              type: 'any',
+              value: headers.length ? `{ ${headers}, ...options.headers }` : undefined,
+            }
+          : undefined,
+        options: {
+          type: 'any',
+          mode: 'inlineSpread',
+        },
+      },
+    },
+  }
+
+  const formData = isFormData
+    ? `
+   const formData = new FormData()
+   if(data) {
+    Object.keys(data).forEach((key) => {
+      const value = data[key];
+      if (typeof key === "string" && (typeof value === "string" || value instanceof Blob)) {
+        formData.append(key, value);
+      }
+    })
+   }
+  `
+    : undefined
+
+  return (
+    <Function name={name} async export generics={generics} returnType={returnType} params={params} JSDoc={JSDoc}>
+      {formData || ''}
+      <Function.Call name="res" to={<Function name="client" async generics={client.generics} params={clientParams} />} />
+      <Function.Return>{client.dataReturnType === 'data' ? 'res.data' : 'res'}</Function.Return>
+    </Function>
+  )
+}
+
+type RootTemplateProps = {
+  children?: React.ReactNode
+}
+
+function RootTemplate({ children }: RootTemplateProps) {
+  const {
+    plugin: {
+      options: {
+        client: { importPath },
+        extName,
+      },
+    },
+  } = useApp<PluginClient>()
+
+  const { getSchemas, getFile } = useOperationManager()
+  const operation = useOperation()
+
+  const file = getFile(operation)
+  const fileType = getFile(operation, { pluginKey: [pluginTsName] })
+  const schemas = getSchemas(operation, { pluginKey: [pluginTsName], type: 'type' })
+
+  return (
+    <Parser language="typescript">
+      <File<FileMeta> baseName={file.baseName} path={file.path} meta={file.meta}>
+        <File.Import name={'client'} path={importPath} />
+        <File.Import name={['ResponseConfig']} path={importPath} isTypeOnly />
+        <File.Import
+          extName={extName}
+          name={[schemas.request?.name, schemas.response.name, schemas.pathParams?.name, schemas.queryParams?.name, schemas.headerParams?.name].filter(Boolean)}
+          root={file.path}
+          path={fileType.path}
+          isTypeOnly
+        />
+        <File.Source>{children}</File.Source>
+      </File>
+    </Parser>
+  )
+}
+
+const defaultTemplates = { default: Template, root: RootTemplate } as const
+
+type Templates = Partial<typeof defaultTemplates>
+
+type ClientProps = {
+  baseURL: string | undefined
+  /**
+   * This will make it possible to override the default behaviour.
+   */
+  Template?: ComponentType<ComponentProps<typeof Template>>
+}
+
+export function Client({ baseURL, Template = defaultTemplates.default }: ClientProps): KubbNode {
+  const {
+    plugin: {
+      options: { client, dataReturnType, pathParamsType },
+    },
+  } = useApp<PluginClient>()
+
+  const { getSchemas, getName } = useOperationManager()
+  const operation = useOperation()
+
+  const contentType = operation.getContentType()
+  const name = getName(operation, { type: 'function' })
+  const schemas = getSchemas(operation, { pluginKey: [pluginTsName], type: 'type' })
+
+  return (
+    <Template
+      name={name}
+      params={{
+        pathParams: {
+          mode: pathParamsType === 'object' ? 'object' : 'inlineSpread',
+          children: getPathParams(schemas.pathParams, { typed: true }),
+        },
+        data: schemas.request?.name
+          ? {
+              type: schemas.request?.name,
+              optional: isOptional(schemas.request?.schema),
+            }
+          : undefined,
+        params: schemas.queryParams?.name
+          ? {
+              type: schemas.queryParams?.name,
+              optional: isOptional(schemas.queryParams?.schema),
+            }
+          : undefined,
+        headers: schemas.headerParams?.name
+          ? {
+              type: schemas.headerParams?.name,
+              optional: isOptional(schemas.headerParams?.schema),
+            }
+          : undefined,
+        options: {
+          type: 'Partial<Parameters<typeof client>[0]>',
+          default: '{}',
+        },
+      }}
+      returnType={dataReturnType === 'data' ? `ResponseConfig<${schemas.response.name}>["data"]` : `ResponseConfig<${schemas.response.name}>`}
+      JSDoc={{
+        comments: getComments(operation),
+      }}
+      client={{
+        // only set baseURL from serverIndex(swagger) when no custom client(default) is used
+        baseURL: client.importPath === '@kubb/plugin-client/client' ? baseURL : undefined,
+        generics: [schemas.response.name, schemas.request?.name].filter(Boolean),
+        dataReturnType,
+        withQueryParams: !!schemas.queryParams?.name,
+        withData: !!schemas.request?.name,
+        withHeaders: !!schemas.headerParams?.name,
+        method: operation.method,
+        path: new URLPath(operation.path),
+        contentType,
+      }}
+    />
+  )
+}
+
+type FileProps = {
+  baseURL: string | undefined
+  /**
+   * This will make it possible to override the default behaviour.
+   */
+  templates?: Templates
+}
+
+Client.File = function ({ baseURL, ...props }: FileProps): KubbNode {
+  const templates = { ...defaultTemplates, ...props.templates }
+
+  const Template = templates.default
+  const RootTemplate = templates.root
+
+  return (
+    <RootTemplate>
+      <Client baseURL={baseURL} Template={Template} />
+    </RootTemplate>
+  )
+}
+
+Client.templates = defaultTemplates

package/src/components/Operations.tsx

@@ -0,0 +1,94 @@
+import { URLPath } from '@kubb/core/utils'
+import { useOperations } from '@kubb/plugin-oas/hooks'
+import { Const, File, Parser, useApp } from '@kubb/react'
+
+import type { HttpMethod, Operation } from '@kubb/oas'
+import type { KubbNode } from '@kubb/react'
+import type { ComponentProps, ComponentType } from 'react'
+import type { FileMeta, PluginClient } from '../types.ts'
+
+type TemplateProps = {
+  /**
+   * Name of the function
+   */
+  name: string
+  operations: Operation[]
+  baseURL: string | undefined
+}
+
+function Template({ name, operations }: TemplateProps): KubbNode {
+  const operationsObject: Record<string, { path: string; method: HttpMethod }> = {}
+
+  operations.forEach((operation) => {
+    operationsObject[operation.getOperationId()] = {
+      path: new URLPath(operation.path).URL,
+      method: operation.method,
+    }
+  })
+  return (
+    <Const name={name} export asConst>
+      {JSON.stringify(operationsObject, undefined, 2)}
+    </Const>
+  )
+}
+
+type RootTemplateProps = {
+  children?: React.ReactNode
+}
+
+function RootTemplate({ children }: RootTemplateProps) {
+  const {
+    pluginManager,
+    plugin: { key: pluginKey },
+  } = useApp<PluginClient>()
+  const file = pluginManager.getFile({ name: 'operations', extName: '.ts', pluginKey })
+
+  return (
+    <Parser language="typescript">
+      <File<FileMeta> baseName={file.baseName} path={file.path} meta={file.meta} exportable={false}>
+        <File.Source>{children}</File.Source>
+      </File>
+    </Parser>
+  )
+}
+
+const defaultTemplates = { default: Template, root: RootTemplate } as const
+
+type Templates = Partial<typeof defaultTemplates>
+
+type Props = {
+  baseURL: string | undefined
+  /**
+   * This will make it possible to override the default behaviour.
+   */
+  Template?: ComponentType<ComponentProps<typeof Template>>
+}
+
+export function Operations({ baseURL, Template = defaultTemplates.default }: Props): KubbNode {
+  const operations = useOperations()
+
+  return <Template baseURL={baseURL} name="operations" operations={operations} />
+}
+
+type FileProps = {
+  baseURL: string | undefined
+  /**
+   * This will make it possible to override the default behaviour.
+   */
+  templates?: Templates
+}
+
+Operations.File = function ({ baseURL, ...props }: FileProps): KubbNode {
+  const templates = { ...defaultTemplates, ...props.templates }
+
+  const Template = templates.default
+  const RootTemplate = templates.root
+
+  return (
+    <RootTemplate>
+      <Operations baseURL={baseURL} Template={Template} />
+    </RootTemplate>
+  )
+}
+
+Operations.templates = defaultTemplates

package/src/components/__snapshots__/Client/showPetById.ts

@@ -0,0 +1,11 @@
+/**
+ * @summary Info for a specific pet
+ * @link /pets/:pet_id
+ */
+export async function showPetById(
+  { petId, testId }: { petId: ShowPetByIdPathParams['pet_id']; testId: ShowPetByIdPathParams['testId'] },
+  options: Partial<Parameters<typeof client>[0]> = {},
+): Promise<ResponseConfig<ShowPetByIdQueryResponse>['data']> {
+  const res = await client<ShowPetByIdQueryResponse>({ method: 'get', url: `/pets/${petId}`, ...options })
+  return res.data
+}

package/src/components/__snapshots__/Operations/showPetById.ts

@@ -0,0 +1,6 @@
+export const operations = {
+  showPetById: {
+    path: '/pets/:pet_id',
+    method: 'get',
+  },
+} as const

package/src/components/__snapshots__/Query/showPetById.ts

@@ -0,0 +1,15 @@
+/**
+ * @summary Info for a specific pet
+ * @link /pets/:pet_id */
+
+export async function showPetById(
+  { petId, testId }: ShowPetByIdPathParams,
+  options: Partial<Parameters<typeof client>[0]> = {},
+): Promise<ResponseConfig<ShowPetByIdQueryResponse>['data']> {
+  const res = await client<ShowPetByIdQueryResponse>({
+    method: 'get',
+    url: `/pets/${petId}`,
+    ...options,
+  })
+  return res.data
+}

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { Client } from './Client.tsx'
+export { Operations } from './Operations.tsx'

package/src/index.ts

@@ -0,0 +1,2 @@
+export { pluginClient, pluginClientName } from './plugin.ts'
+export type { PluginClient } from './types.ts'

package/src/plugin.ts

@@ -0,0 +1,145 @@
+import path from 'node:path'
+
+import { FileManager, PluginManager, createPlugin } from '@kubb/core'
+import { camelCase } from '@kubb/core/transformers'
+import { renderTemplate } from '@kubb/core/utils'
+import { pluginOasName } from '@kubb/plugin-oas'
+import { getGroupedByTagFiles } from '@kubb/plugin-oas/utils'
+
+import { OperationGenerator } from './OperationGenerator.tsx'
+import { Client, Operations } from './components/index.ts'
+
+import type { Plugin } from '@kubb/core'
+import type { PluginOas as SwaggerPluginOptions } from '@kubb/plugin-oas'
+import type { PluginClient } from './types.ts'
+
+export const pluginClientName = 'plugin-client' satisfies PluginClient['name']
+
+export const pluginClient = createPlugin<PluginClient>((options) => {
+  const {
+    output = { path: 'clients' },
+    group,
+    exclude = [],
+    include,
+    override = [],
+    transformers = {},
+    dataReturnType = 'data',
+    pathParamsType = 'inline',
+    templates,
+  } = options
+
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
+
+  return {
+    name: pluginClientName,
+    options: {
+      extName: output.extName,
+      dataReturnType,
+      client: {
+        importPath: '@kubb/plugin-client/client',
+        ...options.client,
+      },
+      pathParamsType,
+      templates: {
+        operations: Operations.templates,
+        client: Client.templates,
+        ...templates,
+      },
+      baseURL: undefined,
+    },
+    pre: [pluginOasName],
+    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) {
+      const resolvedName = camelCase(name, { isFile: type === 'file' })
+
+      if (type) {
+        return transformers?.name?.(resolvedName, type) || resolvedName
+      }
+
+      return resolvedName
+    },
+    async writeFile(path, source) {
+      if (!source) {
+        return
+      }
+
+      return this.fileManager.write(path, source, { sanity: false })
+    },
+    async buildStart() {
+      const [swaggerPlugin]: [Plugin<SwaggerPluginOptions>] = PluginManager.getDependedPlugins<SwaggerPluginOptions>(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 baseURL = await swaggerPlugin.api.getBaseURL()
+
+      const operationGenerator = new OperationGenerator(
+        {
+          ...this.plugin.options,
+          baseURL,
+        },
+        {
+          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 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}}Service',
+          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,129 @@
+import type { Plugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type * as KubbFile from '@kubb/fs/types'
+
+import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
+import type { Client, Operations } from './components/index.ts'
+
+type Templates = {
+  operations?: typeof Operations.templates | false
+  client?: typeof Client.templates | false
+}
+
+export type Options = {
+  output?: {
+    /**
+     * Output to save the clients.
+     * @default `"clients"``
+     */
+    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 clients 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 clients.
+     *
+     * `{{tag}}` will be replaced by the current tagName.
+     * @example `${output}/{{tag}}Controller` => `clients/PetController`
+     * @default `${output}/{{tag}}Controller`
+     */
+    output?: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './`
+     * @default `"{{tag}}Service"`
+     */
+    exportAs?: string
+  }
+  /**
+   * 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>>
+  client?: {
+    /**
+     * Path to the client import path 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
+   */
+  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'
+  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 = {
+  extName: KubbFile.Extname | undefined
+  baseURL: string | undefined
+  client: Required<NonNullable<Options['client']>>
+  dataReturnType: NonNullable<Options['dataReturnType']>
+  pathParamsType: NonNullable<Options['pathParamsType']>
+  templates: NonNullable<Templates>
+}
+
+export type FileMeta = {
+  pluginKey?: Plugin['key']
+  tag?: string
+}
+
+export type PluginClient = PluginFactoryOptions<'plugin-client', Options, ResolvedOptions, never, ResolvePathOptions>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/plugin-client']: PluginClient
+  }
+}