@kubb/swagger-ts 2.0.0-alpha.1 → 2.0.0-alpha.11

package/src/generators/OperationGenerator.ts

@@ -0,0 +1,211 @@
+import { getRelativePath } from '@kubb/core/utils'
+import { print } from '@kubb/parser'
+import * as factory from '@kubb/parser/factory'
+import { OperationGenerator as Generator, resolve } from '@kubb/swagger'
+
+import { pascalCase } from 'change-case'
+
+import { TypeBuilder } from '../builders/index.ts'
+
+import type { KubbFile } from '@kubb/core'
+import type { FileResolver, Operation, OperationSchemas, Resolver } from '@kubb/swagger'
+import type ts from 'typescript'
+import type { FileMeta, PluginOptions } from '../types.ts'
+
+type Options = {
+  usedEnumNames: Record<string, number>
+
+  mode: KubbFile.Mode
+  enumType: NonNullable<PluginOptions['options']['enumType']>
+  dateType: NonNullable<PluginOptions['options']['dateType']>
+  optionalType: NonNullable<PluginOptions['options']['optionalType']>
+}
+
+export class OperationGenerator extends Generator<Options, PluginOptions> {
+  resolve(operation: Operation): Resolver {
+    const { pluginManager, plugin } = this.context
+
+    return resolve({
+      operation,
+      resolveName: pluginManager.resolveName,
+      resolvePath: pluginManager.resolvePath,
+      pluginKey: plugin?.key,
+    })
+  }
+
+  async all(): Promise<KubbFile.File | null> {
+    return null
+  }
+
+  #printCombinedSchema(name: string, operation: Operation, schemas: OperationSchemas): string {
+    const properties: Record<string, ts.TypeNode> = {
+      'response': factory.createTypeReferenceNode(
+        factory.createIdentifier(schemas.response.name),
+        undefined,
+      ),
+    }
+
+    if (schemas.request) {
+      properties['request'] = factory.createTypeReferenceNode(
+        factory.createIdentifier(schemas.request.name),
+        undefined,
+      )
+    }
+
+    if (schemas.pathParams) {
+      properties['pathParams'] = factory.createTypeReferenceNode(
+        factory.createIdentifier(schemas.pathParams.name),
+        undefined,
+      )
+    }
+
+    if (schemas.queryParams) {
+      properties['queryParams'] = factory.createTypeReferenceNode(
+        factory.createIdentifier(schemas.queryParams.name),
+        undefined,
+      )
+    }
+
+    if (schemas.headerParams) {
+      properties['headerParams'] = factory.createTypeReferenceNode(
+        factory.createIdentifier(schemas.headerParams.name),
+        undefined,
+      )
+    }
+
+    if (schemas.errors) {
+      properties['errors'] = factory.createUnionDeclaration({
+        nodes: schemas.errors.map(error => {
+          return factory.createTypeReferenceNode(
+            factory.createIdentifier(error.name),
+            undefined,
+          )
+        }),
+      })!
+    }
+
+    const namespaceNode = factory.createNamespaceDeclaration({
+      name: operation.method === 'get' ? `${name}Query` : `${name}Mutation`,
+      statements: Object.keys(properties).map(key => {
+        const type = properties[key]
+        if (!type) {
+          return undefined
+        }
+        return factory.createTypeAliasDeclaration({
+          modifiers: [factory.modifiers.export],
+          name: pascalCase(key),
+          type,
+        })
+      }).filter(Boolean),
+    })
+
+    return print(namespaceNode)
+  }
+
+  async get(operation: Operation, schemas: OperationSchemas, options: Options): Promise<KubbFile.File<FileMeta> | null> {
+    const { mode, enumType, dateType, optionalType, usedEnumNames } = options
+    const { pluginManager, plugin } = this.context
+
+    const type = this.resolve(operation)
+
+    const fileResolver: FileResolver = (name) => {
+      // Used when a react-query type(request, response, params) has an import of a global type
+      const root = pluginManager.resolvePath({ baseName: type.baseName, pluginKey: plugin?.key, options: { tag: operation.getTags()[0]?.name } })
+      // refs import, will always been created with the SwaggerTS plugin, our global type
+      const resolvedTypeId = pluginManager.resolvePath({
+        baseName: `${name}.ts`,
+        pluginKey: plugin?.key,
+      })
+
+      return getRelativePath(root, resolvedTypeId)
+    }
+
+    const source = new TypeBuilder({
+      usedEnumNames,
+      fileResolver: mode === 'file' ? undefined : fileResolver,
+      withJSDocs: true,
+      resolveName: (params) => pluginManager.resolveName({ ...params, pluginKey: plugin?.key }),
+      enumType,
+      optionalType,
+      dateType,
+    })
+      .add(schemas.pathParams)
+      .add(schemas.queryParams)
+      .add(schemas.headerParams)
+      .add(schemas.response)
+      .add(schemas.errors)
+      .configure()
+      .print()
+
+    const combinedSchemaSource = this.#printCombinedSchema(type.name, operation, schemas)
+
+    return {
+      path: type.path,
+      baseName: type.baseName,
+      source: [source, combinedSchemaSource].join('\n'),
+      meta: {
+        pluginKey: plugin.key,
+        tag: operation.getTags()[0]?.name,
+      },
+    }
+  }
+
+  async post(operation: Operation, schemas: OperationSchemas, options: Options): Promise<KubbFile.File<FileMeta> | null> {
+    const { mode, enumType, dateType, optionalType, usedEnumNames } = options
+    const { pluginManager, plugin } = this.context
+
+    const type = this.resolve(operation)
+
+    const fileResolver: FileResolver = (name) => {
+      // Used when a react-query type(request, response, params) has an import of a global type
+      const root = pluginManager.resolvePath({ baseName: type.baseName, pluginKey: plugin?.key, options: { tag: operation.getTags()[0]?.name } })
+      // refs import, will always been created with the SwaggerTS plugin, our global type
+      const resolvedTypeId = pluginManager.resolvePath({
+        baseName: `${name}.ts`,
+        pluginKey: plugin?.key,
+      })
+
+      return getRelativePath(root, resolvedTypeId)
+    }
+
+    const source = new TypeBuilder({
+      usedEnumNames,
+      fileResolver: mode === 'file' ? undefined : fileResolver,
+      withJSDocs: true,
+      resolveName: (params) => pluginManager.resolveName({ ...params, pluginKey: plugin?.key }),
+      enumType,
+      optionalType,
+      dateType,
+    })
+      .add(schemas.pathParams)
+      .add(schemas.queryParams)
+      .add(schemas.headerParams)
+      .add(schemas.request)
+      .add(schemas.response)
+      .add(schemas.errors)
+      .configure()
+      .print()
+
+    const combinedSchemaSource = this.#printCombinedSchema(type.name, operation, schemas)
+
+    return {
+      path: type.path,
+      baseName: type.baseName,
+      source: [source, combinedSchemaSource].join('\n'),
+      meta: {
+        pluginKey: plugin.key,
+        tag: operation.getTags()[0]?.name,
+      },
+    }
+  }
+
+  async put(operation: Operation, schemas: OperationSchemas, options: Options): Promise<KubbFile.File<FileMeta> | null> {
+    return this.post(operation, schemas, options)
+  }
+  async patch(operation: Operation, schemas: OperationSchemas, options: Options): Promise<KubbFile.File<FileMeta> | null> {
+    return this.post(operation, schemas, options)
+  }
+  async delete(operation: Operation, schemas: OperationSchemas, options: Options): Promise<KubbFile.File<FileMeta> | null> {
+    return this.post(operation, schemas, options)
+  }
+}

package/src/generators/TypeGenerator.ts

@@ -0,0 +1,378 @@
+import { SchemaGenerator } from '@kubb/core'
+import { getUniqueName } from '@kubb/core/utils'
+import * as factory from '@kubb/parser/factory'
+import { isReference } from '@kubb/swagger/utils'
+
+import { camelCase } from 'change-case'
+
+import type { PluginContext } from '@kubb/core'
+import type { ts } from '@kubb/parser'
+import type { OpenAPIV3, Refs } from '@kubb/swagger'
+import type { Options as CaseOptions } from 'change-case'
+
+// based on https://github.com/cellular/oazapfts/blob/7ba226ebb15374e8483cc53e7532f1663179a22c/src/codegen/generate.ts#L398
+
+type Options = {
+  usedEnumNames: Record<string, number>
+
+  withJSDocs?: boolean
+  resolveName: PluginContext['resolveName']
+  enumType: 'enum' | 'asConst' | 'asPascalConst'
+  dateType: 'string' | 'date'
+  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+}
+export class TypeGenerator extends SchemaGenerator<Options, OpenAPIV3.SchemaObject, ts.Node[]> {
+  refs: Refs = {}
+
+  extraNodes: ts.Node[] = []
+
+  aliases: ts.TypeAliasDeclaration[] = []
+
+  // Keep track of already used type aliases
+  #usedAliasNames: Record<string, number> = {}
+
+  #caseOptions: CaseOptions = {
+    delimiter: '',
+    stripRegexp: /[^A-Z0-9$]/gi,
+  }
+
+  constructor(
+    options: Options = {
+      usedEnumNames: {},
+      withJSDocs: true,
+      resolveName: ({ name }) => name,
+      enumType: 'asConst',
+      dateType: 'string',
+      optionalType: 'questionToken',
+    },
+  ) {
+    super(options)
+
+    return this
+  }
+
+  build({
+    schema,
+    baseName,
+    description,
+    keysToOmit,
+  }: {
+    schema: OpenAPIV3.SchemaObject
+    baseName: string
+    description?: string
+    keysToOmit?: string[]
+  }): ts.Node[] {
+    const nodes: ts.Node[] = []
+    const type = this.#getTypeFromSchema(schema, baseName)
+
+    if (!type) {
+      return this.extraNodes
+    }
+
+    const node = factory.createTypeAliasDeclaration({
+      modifiers: [factory.modifiers.export],
+      name: this.options.resolveName({ name: baseName }) || baseName,
+      type: keysToOmit?.length ? factory.createOmitDeclaration({ keys: keysToOmit, type, nonNullable: true }) : type,
+    })
+
+    if (description) {
+      nodes.push(
+        factory.appendJSDocToNode({
+          node,
+          comments: [`@description ${description}`],
+        }),
+      )
+    } else {
+      nodes.push(node)
+    }
+
+    // filter out if the export name is the same as one that we already defined in extraNodes(see enum)
+    const filterdNodes = nodes.filter(
+      (node: ts.Node) =>
+        !this.extraNodes.some(
+          (extraNode: ts.Node) => (extraNode as ts.TypeAliasDeclaration)?.name?.escapedText === (node as ts.TypeAliasDeclaration)?.name?.escapedText,
+        ),
+    )
+
+    return [...this.extraNodes, ...filterdNodes]
+  }
+
+  /**
+   * Creates a type node from a given schema.
+   * Delegates to getBaseTypeFromSchema internally and
+   * optionally adds a union with null.
+   */
+  #getTypeFromSchema(schema?: OpenAPIV3.SchemaObject, name?: string): ts.TypeNode | null {
+    const type = this.#getBaseTypeFromSchema(schema, name)
+
+    if (!type) {
+      return null
+    }
+
+    if (schema && !schema.nullable) {
+      return type
+    }
+
+    return factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
+  }
+
+  /**
+   * Recursively creates a type literal with the given props.
+   */
+  #getTypeFromProperties(baseSchema?: OpenAPIV3.SchemaObject, baseName?: string) {
+    const { optionalType } = this.options
+    const properties = baseSchema?.properties || {}
+    const required = baseSchema?.required
+    const additionalProperties = baseSchema?.additionalProperties
+
+    const members: Array<ts.TypeElement | null> = Object.keys(properties).map((name) => {
+      const schema = properties[name] as OpenAPIV3.SchemaObject
+
+      const isRequired = required && required.includes(name)
+      let type = this.#getTypeFromSchema(schema, this.options.resolveName({ name: `${baseName || ''} ${name}` }))
+
+      if (!type) {
+        return null
+      }
+
+      if (!isRequired && ['undefined', 'questionTokenAndUndefined'].includes(optionalType)) {
+        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
+      }
+      const propertySignature = factory.createPropertySignature({
+        questionToken: ['questionToken', 'questionTokenAndUndefined'].includes(optionalType) && !isRequired,
+        name,
+        type: type as ts.TypeNode,
+        readOnly: schema.readOnly,
+      })
+      if (this.options.withJSDocs) {
+        return factory.appendJSDocToNode({
+          node: propertySignature,
+          comments: [
+            schema.description ? `@description ${schema.description}` : undefined,
+            schema.type ? `@type ${schema.type}${isRequired ? '' : ' | undefined'} ${schema.format || ''}` : undefined,
+            schema.example ? `@example ${schema.example as string}` : undefined,
+            schema.deprecated ? `@deprecated` : undefined,
+            schema.default !== undefined && typeof schema.default === 'string' ? `@default '${schema.default}'` : undefined,
+            schema.default !== undefined && typeof schema.default !== 'string' ? `@default ${schema.default as string}` : undefined,
+          ].filter(Boolean),
+        })
+      }
+
+      return propertySignature
+    })
+    if (additionalProperties) {
+      const type = additionalProperties === true ? factory.keywordTypeNodes.any : this.#getTypeFromSchema(additionalProperties as OpenAPIV3.SchemaObject)
+
+      if (type) {
+        members.push(factory.createIndexSignature(type))
+      }
+    }
+    return factory.createTypeLiteralNode(members.filter(Boolean))
+  }
+
+  /**
+   * Create a type alias for the schema referenced by the given ReferenceObject
+   */
+  #getRefAlias(obj: OpenAPIV3.ReferenceObject, _baseName?: string) {
+    const { $ref } = obj
+    let ref = this.refs[$ref]
+
+    if (ref) {
+      return factory.createTypeReferenceNode(ref.propertyName, undefined)
+    }
+
+    const originalName = getUniqueName($ref.replace(/.+\//, ''), this.#usedAliasNames)
+    const propertyName = this.options.resolveName({ name: originalName }) || originalName
+
+    ref = this.refs[$ref] = {
+      propertyName,
+      originalName,
+    }
+
+    return factory.createTypeReferenceNode(ref.propertyName, undefined)
+  }
+
+  /**
+   * This is the very core of the OpenAPI to TS conversion - it takes a
+   * schema and returns the appropriate type.
+   */
+  #getBaseTypeFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined, baseName?: string): ts.TypeNode | null {
+    if (!schema) {
+      return factory.keywordTypeNodes.any
+    }
+
+    if (isReference(schema)) {
+      return this.#getRefAlias(schema, baseName)
+    }
+
+    if (schema.oneOf) {
+      // union
+      const schemaWithoutOneOf = { ...schema, oneOf: undefined }
+
+      const union = factory.createUnionDeclaration({
+        withParentheses: true,
+        nodes: schema.oneOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutOneOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutOneOf, baseName), union].filter(Boolean),
+        })
+      }
+
+      return union
+    }
+
+    if (schema.anyOf) {
+      const schemaWithoutAnyOf = { ...schema, anyOf: undefined }
+
+      const union = factory.createUnionDeclaration({
+        withParentheses: true,
+        nodes: schema.anyOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutAnyOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutAnyOf, baseName), union].filter(Boolean),
+        })
+      }
+
+      return union
+    }
+    if (schema.allOf) {
+      // intersection/add
+      const schemaWithoutAllOf = { ...schema, allOf: undefined }
+
+      const and = factory.createIntersectionDeclaration({
+        withParentheses: true,
+        nodes: schema.allOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutAllOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutAllOf, baseName), and].filter(Boolean),
+        })
+      }
+
+      return and
+    }
+
+    /**
+     * Enum will be defined outside the baseType(hints the baseName check)
+     */
+    if (schema.enum && baseName) {
+      const enumName = getUniqueName(baseName, this.options.usedEnumNames)
+
+      let enums: [key: string, value: string | number][] = [...new Set(schema.enum)].map((key) => [key, key])
+
+      if ('x-enumNames' in schema) {
+        enums = [...new Set(schema['x-enumNames'] as string[])].map((key: string, index) => {
+          return [key, schema.enum?.[index]]
+        })
+      }
+
+      this.extraNodes.push(
+        ...factory.createEnumDeclaration({
+          name: camelCase(enumName, this.#caseOptions),
+          typeName: this.options.resolveName({ name: enumName }),
+          enums,
+          type: this.options.enumType,
+        }),
+      )
+      return factory.createTypeReferenceNode(this.options.resolveName({ name: enumName }), undefined)
+    }
+
+    if (schema.enum) {
+      return factory.createUnionDeclaration({
+        nodes: schema.enum.map((name: string) => {
+          return factory.createLiteralTypeNode(typeof name === 'number' ? factory.createNumericLiteral(name) : factory.createStringLiteral(`${name}`))
+        }) as unknown as Array<ts.TypeNode>,
+      })
+    }
+
+    if ('items' in schema) {
+      // items -> array
+      const node = this.#getTypeFromSchema(schema.items as OpenAPIV3.SchemaObject, baseName)
+      if (node) {
+        return factory.createArrayTypeNode(node)
+      }
+    }
+    /**
+     * OpenAPI 3.1
+     * @link https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation
+     */
+    if ('prefixItems' in schema) {
+      const prefixItems = schema.prefixItems as OpenAPIV3.SchemaObject[]
+
+      return factory.createTupleDeclaration({
+        nodes: prefixItems.map((item) => {
+          // no baseType so we can fall back on an union when using enum
+          return this.#getBaseTypeFromSchema(item, undefined)
+        }) as Array<ts.TypeNode>,
+      })
+    }
+
+    if (schema.properties || schema.additionalProperties) {
+      // properties -> literal type
+      return this.#getTypeFromProperties(schema, baseName)
+    }
+
+    if (schema.type) {
+      if (Array.isArray(schema.type)) {
+        // OPENAPI v3.1.0: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
+        const [type, nullable] = schema.type as Array<OpenAPIV3.NonArraySchemaObjectType>
+
+        return factory.createUnionDeclaration({
+          nodes: [
+            this.#getBaseTypeFromSchema(
+              {
+                ...schema,
+                type,
+              },
+              baseName,
+            ),
+            nullable ? factory.createLiteralTypeNode(factory.createNull()) : undefined,
+          ].filter(Boolean),
+        })
+      }
+
+      if (this.options.dateType === 'date' && ['date', 'date-time'].some((item) => item === schema.format)) {
+        return factory.createTypeReferenceNode(factory.createIdentifier('Date'))
+      }
+
+      // string, boolean, null, number
+      if (schema.type in factory.keywordTypeNodes) {
+        return factory.keywordTypeNodes[schema.type as keyof typeof factory.keywordTypeNodes]
+      }
+    }
+
+    if (schema.format === 'binary') {
+      return factory.createTypeReferenceNode('Blob', [])
+    }
+
+    // detect assertion "const" and define the type property as a Literal
+    if ('const' in schema && schema['const'] !== undefined && typeof schema['const'] === 'string') {
+      return factory.createLiteralTypeNode(factory.createStringLiteral(schema['const']))
+    }
+
+    return factory.keywordTypeNodes.any
+  }
+}

package/src/generators/index.ts

@@ -0,0 +1,2 @@
+export * from './OperationGenerator.ts'
+export * from './TypeGenerator.ts'

package/src/index.ts

@@ -0,0 +1,6 @@
+import { definePlugin } from './plugin.ts'
+
+export { definePlugin, pluginKey, pluginName } from './plugin.ts'
+export * from './types.ts'
+
+export default definePlugin