@kubb/plugin-ts 3.0.0-alpha.0

package/src/parser/index.ts

@@ -0,0 +1,263 @@
+import transformers from '@kubb/core/transformers'
+import * as factory from '@kubb/parser-ts/factory'
+import { isKeyword, schemaKeywords } from '@kubb/plugin-oas'
+
+import type { ts } from '@kubb/parser-ts'
+import type { Schema, SchemaKeywordMapper, SchemaMapper } from '@kubb/plugin-oas'
+
+export const typeKeywordMapper = {
+  any: () => factory.keywordTypeNodes.any,
+  unknown: () => factory.keywordTypeNodes.unknown,
+  number: () => factory.keywordTypeNodes.number,
+  integer: () => factory.keywordTypeNodes.number,
+  object: (nodes?: ts.TypeElement[]) => {
+    if (!nodes || !nodes.length) {
+      return factory.keywordTypeNodes.object
+    }
+
+    return factory.createTypeLiteralNode(nodes)
+  },
+  string: () => factory.keywordTypeNodes.string,
+  boolean: () => factory.keywordTypeNodes.boolean,
+  undefined: () => factory.keywordTypeNodes.undefined,
+  nullable: undefined,
+  null: () => factory.keywordTypeNodes.null,
+  nullish: undefined,
+  array: (nodes?: ts.TypeNode[]) => {
+    if (!nodes) {
+      return undefined
+    }
+
+    return factory.createArrayDeclaration({ nodes })
+  },
+  tuple: (nodes?: ts.TypeNode[]) => {
+    if (!nodes) {
+      return undefined
+    }
+
+    return factory.createTupleTypeNode(nodes)
+  },
+  enum: (name?: string) => {
+    if (!name) {
+      return undefined
+    }
+
+    return factory.createTypeReferenceNode(name, undefined)
+  },
+  union: (nodes?: ts.TypeNode[]) => {
+    if (!nodes) {
+      return undefined
+    }
+
+    return factory.createUnionDeclaration({
+      withParentheses: true,
+      nodes,
+    })
+  },
+  const: (name?: string | number, format?: 'string' | 'number') => {
+    if (!name) {
+      return undefined
+    }
+
+    if (format === 'number') {
+      return factory.createLiteralTypeNode(factory.createNumericLiteral(name))
+    }
+
+    return factory.createLiteralTypeNode(factory.createStringLiteral(name.toString()))
+  },
+  datetime: () => factory.keywordTypeNodes.string,
+  date: (type: 'date' | 'string' = 'string') =>
+    type === 'string' ? factory.keywordTypeNodes.string : factory.createTypeReferenceNode(factory.createIdentifier('Date')),
+  time: (type: 'date' | 'string' = 'string') =>
+    type === 'string' ? factory.keywordTypeNodes.string : factory.createTypeReferenceNode(factory.createIdentifier('Date')),
+  uuid: undefined,
+  url: undefined,
+  strict: undefined,
+  default: undefined,
+  and: (nodes?: ts.TypeNode[]) => {
+    if (!nodes) {
+      return undefined
+    }
+
+    return factory.createIntersectionDeclaration({
+      withParentheses: true,
+      nodes,
+    })
+  },
+  describe: undefined,
+  min: undefined,
+  max: undefined,
+  optional: undefined,
+  matches: undefined,
+  email: undefined,
+  firstName: undefined,
+  lastName: undefined,
+  password: undefined,
+  phone: undefined,
+  readOnly: undefined,
+  ref: (propertyName?: string) => {
+    if (!propertyName) {
+      return undefined
+    }
+
+    return factory.createTypeReferenceNode(propertyName, undefined)
+  },
+  blob: () => factory.createTypeReferenceNode('Blob', []),
+  deprecated: undefined,
+  example: undefined,
+  schema: undefined,
+  catchall: undefined,
+  name: undefined,
+} satisfies SchemaMapper<ts.Node | null | undefined>
+
+type ParserOptions = {
+  name: string
+  typeName?: string
+  description?: string
+  /**
+   * @default `'questionToken'`
+   */
+  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+  /**
+   * @default `'asConst'`
+   */
+  enumType: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal'
+  keysToOmit?: string[]
+  mapper?: Record<string, ts.PropertySignature>
+}
+
+export function parse(parent: Schema | undefined, current: Schema, options: ParserOptions): ts.Node | null | undefined {
+  const value = typeKeywordMapper[current.keyword as keyof typeof typeKeywordMapper]
+
+  if (!value) {
+    return undefined
+  }
+
+  if (isKeyword(current, schemaKeywords.union)) {
+    return typeKeywordMapper.union(current.args.map((schema) => parse(current, schema, options)).filter(Boolean) as ts.TypeNode[])
+  }
+
+  if (isKeyword(current, schemaKeywords.and)) {
+    return typeKeywordMapper.and(current.args.map((schema) => parse(current, schema, options)).filter(Boolean) as ts.TypeNode[])
+  }
+
+  if (isKeyword(current, schemaKeywords.array)) {
+    return typeKeywordMapper.array(current.args.items.map((schema) => parse(current, schema, options)).filter(Boolean) as ts.TypeNode[])
+  }
+
+  if (isKeyword(current, schemaKeywords.enum)) {
+    return typeKeywordMapper.enum(current.args.typeName)
+  }
+
+  if (isKeyword(current, schemaKeywords.ref)) {
+    return typeKeywordMapper.ref(current.args.name)
+  }
+
+  if (isKeyword(current, schemaKeywords.blob)) {
+    return value()
+  }
+
+  if (isKeyword(current, schemaKeywords.tuple)) {
+    return typeKeywordMapper.tuple(current.args.items.map((schema) => parse(current, schema, options)).filter(Boolean) as ts.TypeNode[])
+  }
+
+  if (isKeyword(current, schemaKeywords.const)) {
+    return typeKeywordMapper.const(current.args.name, current.args.format)
+  }
+
+  if (isKeyword(current, schemaKeywords.object)) {
+    const properties = Object.entries(current.args?.properties || {})
+      .filter((item) => {
+        const schemas = item[1]
+        return schemas && typeof schemas.map === 'function'
+      })
+      .map(([name, schemas]) => {
+        const nameSchema = schemas.find((schema) => schema.keyword === schemaKeywords.name) as SchemaKeywordMapper['name']
+        const mappedName = nameSchema?.args || name
+
+        // custom mapper(pluginOptions)
+        if (options.mapper?.[mappedName]) {
+          return options.mapper?.[mappedName]
+        }
+
+        const isNullish = schemas.some((schema) => schema.keyword === schemaKeywords.nullish)
+        const isNullable = schemas.some((schema) => schema.keyword === schemaKeywords.nullable)
+        const isOptional = schemas.some((schema) => schema.keyword === schemaKeywords.optional)
+        const isReadonly = schemas.some((schema) => schema.keyword === schemaKeywords.readOnly)
+        const describeSchema = schemas.find((schema) => schema.keyword === schemaKeywords.describe) as SchemaKeywordMapper['describe'] | undefined
+        const deprecatedSchema = schemas.find((schema) => schema.keyword === schemaKeywords.deprecated) as SchemaKeywordMapper['deprecated'] | undefined
+        const defaultSchema = schemas.find((schema) => schema.keyword === schemaKeywords.default) as SchemaKeywordMapper['default'] | undefined
+        const exampleSchema = schemas.find((schema) => schema.keyword === schemaKeywords.example) as SchemaKeywordMapper['example'] | undefined
+        const schemaSchema = schemas.find((schema) => schema.keyword === schemaKeywords.schema) as SchemaKeywordMapper['schema'] | undefined
+
+        let type = schemas.map((schema) => parse(current, schema, options)).filter(Boolean)[0] as ts.TypeNode
+
+        if (isNullable) {
+          type = factory.createUnionDeclaration({
+            nodes: [type, factory.keywordTypeNodes.null],
+          }) as ts.TypeNode
+        }
+
+        if (isNullish && ['undefined', 'questionTokenAndUndefined'].includes(options.optionalType as string)) {
+          type = factory.createUnionDeclaration({
+            nodes: [type, factory.keywordTypeNodes.undefined],
+          }) as ts.TypeNode
+        }
+
+        if (isOptional && ['undefined', 'questionTokenAndUndefined'].includes(options.optionalType as string)) {
+          type = factory.createUnionDeclaration({
+            nodes: [type, factory.keywordTypeNodes.undefined],
+          }) as ts.TypeNode
+        }
+
+        const propertySignature = factory.createPropertySignature({
+          questionToken: isOptional || isNullish ? ['questionToken', 'questionTokenAndUndefined'].includes(options.optionalType as string) : false,
+          name: mappedName,
+          type,
+          readOnly: isReadonly,
+        })
+
+        return factory.appendJSDocToNode({
+          node: propertySignature,
+          comments: [
+            describeSchema ? `@description ${transformers.jsStringEscape(describeSchema.args)}` : undefined,
+            deprecatedSchema ? '@deprecated' : undefined,
+            defaultSchema ? `@default ${defaultSchema.args}` : undefined,
+            exampleSchema ? `@example ${exampleSchema.args}` : undefined,
+            schemaSchema?.args?.type || schemaSchema?.args?.format
+              ? [`@type ${schemaSchema?.args?.type || 'unknown'}${!isOptional ? '' : ' | undefined'}`, schemaSchema?.args?.format].filter(Boolean).join(', ')
+              : undefined,
+          ].filter(Boolean),
+        })
+      })
+
+    const additionalProperties = current.args?.additionalProperties?.length
+      ? factory.createIndexSignature(
+          current.args.additionalProperties
+            .map((schema) => parse(current, schema, options))
+            .filter(Boolean)
+            .at(0) as ts.TypeNode,
+        )
+      : undefined
+
+    return typeKeywordMapper.object([...properties, additionalProperties].filter(Boolean))
+  }
+
+  if (isKeyword(current, schemaKeywords.datetime)) {
+    return typeKeywordMapper.datetime()
+  }
+
+  if (isKeyword(current, schemaKeywords.date)) {
+    return typeKeywordMapper.date(current.args.type)
+  }
+
+  if (isKeyword(current, schemaKeywords.time)) {
+    return typeKeywordMapper.time(current.args.type)
+  }
+
+  if (current.keyword in typeKeywordMapper) {
+    return value()
+  }
+
+  return undefined
+}

package/src/plugin.ts

@@ -0,0 +1,138 @@
+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 { OperationGenerator } from './OperationGenerator.tsx'
+import { SchemaGenerator } from './SchemaGenerator.tsx'
+
+import type { Plugin } from '@kubb/core'
+import type { PluginOas as SwaggerPluginOptions } from '@kubb/plugin-oas'
+import type { PluginTs } from './types.ts'
+
+export const pluginTsName = 'plugin-ts' satisfies PluginTs['name']
+
+export const pluginTs = createPlugin<PluginTs>((options) => {
+  const {
+    output = { path: 'types' },
+    group,
+    exclude = [],
+    include,
+    override = [],
+    enumType = 'asConst',
+    enumSuffix = '',
+    dateType = 'string',
+    unknownType = 'any',
+    optionalType = 'questionToken',
+    transformers = {},
+    oasType = false,
+    mapper = {},
+  } = options
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
+
+  return {
+    name: pluginTsName,
+    options: {
+      extName: output.extName,
+      transformers,
+      dateType,
+      optionalType,
+      oasType,
+      enumType,
+      enumSuffix,
+      // keep the used enumnames between SchemaGenerator and OperationGenerator per plugin(pluginKey)
+      usedEnumNames: {},
+      unknownType,
+      override,
+      mapper,
+    },
+    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 = pascalCase(name, { isFile: type === 'file' })
+
+      if (type) {
+        return transformers?.name?.(resolvedName, type) || resolvedName
+      }
+
+      return resolvedName
+    },
+    async writeFile(path, source) {
+      if (!path.endsWith('.ts') || !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 schemaGenerator = new SchemaGenerator(this.plugin.options, {
+        oas,
+        pluginManager: this.pluginManager,
+        plugin: this.plugin,
+        contentType: swaggerPlugin.api.contentType,
+        include: undefined,
+        override,
+        mode,
+        output: output.path,
+      })
+
+      const schemaFiles = await schemaGenerator.build()
+      await this.addFile(...schemaFiles)
+
+      const operationGenerator = new OperationGenerator(this.plugin.options, {
+        oas,
+        pluginManager: this.pluginManager,
+        plugin: this.plugin,
+        contentType: swaggerPlugin.api.contentType,
+        exclude,
+        include,
+        override,
+        mode,
+      })
+
+      const operationFiles = await operationGenerator.build()
+      await this.addFile(...operationFiles)
+    },
+    async buildEnd() {
+      if (this.config.output.write === false) {
+        return
+      }
+
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      await this.fileManager.addIndexes({
+        root,
+        output,
+        meta: { pluginKey: this.plugin.key },
+        logger: this.logger,
+      })
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,138 @@
+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 { ts } from '@kubb/parser-ts'
+
+export type Options = {
+  output?: {
+    /**
+     * Relative path to save the TypeScript types.
+     * When output is a file it will save all models inside that file else it will create a file per schema item.
+     * @default 'types'
+     */
+    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 TypeScript types 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 TypeScript Types.
+     *
+     * `{{tag}}` will be replaced by the current tagName.
+     * @example `${output}/{{tag}}Controller` => `models/PetController`
+     * @default `${output}/{{tag}}Controller`
+     */
+    output?: 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>>
+  /**
+   * Choose to use `enum` or `as const` for enums
+   * @default 'asConst'
+   */
+  enumType?: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal'
+  /**
+   * Set a suffix for the generated enums.
+   * @default ''
+   * Default will be `'enum'` in version 3 of Kubb
+   */
+  enumSuffix?: string
+
+  /**
+   * Choose to use `date` or `datetime` as JavaScript `Date` instead of `string`.
+   * @default 'string'
+   */
+  dateType?: 'string' | 'date'
+  /**
+   * Which type to use when the Swagger/OpenAPI file is not providing more information.
+   * @default 'any'
+   */
+  unknownType?: 'any' | 'unknown'
+  /**
+   * Choose what to use as mode for an optional value.
+   * @examples 'questionToken': type?: string
+   * @examples 'undefined': type: string | undefined
+   * @examples 'questionTokenAndUndefined': type?: string | undefined
+   * @default 'questionToken'
+   */
+  optionalType?: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+  transformers?: {
+    /**
+     * Customize the names based on the type that is provided by the plugin.
+     */
+    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+  }
+  /**
+   * Export an Oas object as Oas type with `import type { Infer } from '@kubb/oas'`
+   */
+  oasType?: 'infer' | false
+  /**
+   * @example
+   * Use https://ts-ast-viewer.com to generate factory code(see createPropertySignature)
+   * category: factory.createPropertySignature(
+   *   undefined,
+   *   factory.createIdentifier("category"),
+   *   factory.createToken(ts.SyntaxKind.QuestionToken),
+   *   factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+   * )
+   */
+  mapper?: Record<string, ts.PropertySignature>
+}
+
+type ResolvedOptions = {
+  extName: KubbFile.Extname | undefined
+  enumType: NonNullable<Options['enumType']>
+  enumSuffix: NonNullable<Options['enumSuffix']>
+  dateType: NonNullable<Options['dateType']>
+  unknownType: NonNullable<Options['unknownType']>
+  optionalType: NonNullable<Options['optionalType']>
+  override: NonNullable<Options['override']>
+  transformers: NonNullable<Options['transformers']>
+  oasType: NonNullable<Options['oasType']>
+  usedEnumNames: Record<string, number>
+  mapper: Record<string, any>
+}
+
+export type FileMeta = {
+  pluginKey?: Plugin['key']
+  name?: string
+  tag?: string
+}
+
+export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/plugin-ts']: PluginTs
+  }
+}
+// external packages
+export * as Oas from './oas/index.ts'