@kubb/plugin-ts 5.0.0-beta.56 → 5.0.0-beta.64

package/src/printers/printerTs.ts

@@ -1,315 +0,0 @@
-import { extractRefName } from '@kubb/ast/utils'
-import { ast } from '@kubb/core'
-import { parserTs } from '@kubb/parser-ts'
-import type ts from 'typescript'
-import { ENUM_TYPES_WITH_KEY_SUFFIX, OPTIONAL_ADDS_QUESTION_TOKEN, OPTIONAL_ADDS_UNDEFINED } from '../constants.ts'
-import * as factory from '../factory.ts'
-import type { PluginTs, ResolverTs } from '../types.ts'
-import { buildPropertyJSDocComments } from '../utils.ts'
-
-function isNonNullable<T>(value: T | null | undefined): value is T {
-  return value !== null && value !== undefined
-}
-
-/**
- * Partial map of node-type overrides for the TypeScript printer.
- *
- * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`). The function
- * replaces the built-in handler for that node type. Use `this.transform` to
- * recurse into nested schema nodes, and `this.options` to read printer options.
- *
- * @example Override the `date` handler
- * ```ts
- * pluginTs({
- *   printer: {
- *     nodes: {
- *       date(node) {
- *         return ts.factory.createTypeReferenceNode('Date', [])
- *       },
- *     },
- *   },
- * })
- * ```
- */
-export type PrinterTsNodes = ast.PrinterPartial<ts.TypeNode, PrinterTsOptions>
-
-export type PrinterTsOptions = {
-  /**
-   * Mark parameters as optional with `?` or `| undefined`.
-   * - `'questionToken'` adds `?` to properties
-   * - `'undefined'` adds `| undefined` to types
-   *
-   * @default `'questionToken'`
-   */
-  optionalType: PluginTs['resolvedOptions']['optionalType']
-  /**
-   * Array representation style.
-   * - `'array'` uses bracket notation (`T[]`)
-   * - `'generic'` uses generic syntax (`Array<T>`)
-   *
-   * @default `'array'`
-   */
-  arrayType: PluginTs['resolvedOptions']['arrayType']
-  /**
-   * Grouped enum settings. The printer emits references to enums, not the enum declarations, so only
-   * `type` (the output format) and `typeSuffix` (the enum key reference suffix) matter here.
-   * `constCasing` and `keyCasing` are ignored.
-   */
-  enum: PluginTs['resolvedOptions']['enum']
-  /**
-   * Syntax for generated declarations.
-   * - `'type'` generates type aliases
-   * - `'interface'` generates interface declarations
-   *
-   * @default `'type'`
-   */
-  syntaxType?: PluginTs['resolvedOptions']['syntaxType']
-  /**
-   * Exported name for the type declaration.
-   * When omitted, returns only the raw type node.
-   */
-  name?: string
-
-  /**
-   * JSDoc comment to attach to the generated type.
-   */
-  description?: string
-  /**
-   * Properties to exclude using `Omit<Type, Keys>`.
-   * Forces type alias syntax regardless of `syntaxType` setting.
-   */
-  keysToOmit?: Array<string> | null
-  /**
-   * Transforms raw schema names into valid TypeScript identifiers.
-   */
-  resolver: ResolverTs
-  /**
-   * Schema names that represent enums for suffixed key references.
-   */
-  enumSchemaNames?: Set<string>
-  /**
-   * Custom handler map for node type overrides.
-   */
-  nodes?: PrinterTsNodes
-}
-
-/**
- * TypeScript printer factory options: maps `SchemaNode` → `ts.TypeNode` (raw) or `ts.Node` (full declaration).
- */
-export type PrinterTsFactory = ast.PrinterFactoryOptions<'typescript', PrinterTsOptions, ts.TypeNode, string>
-
-type PrinterTs = PrinterTsFactory
-
-/**
- * TypeScript type printer built with `definePrinter`.
- *
- * Converts a `SchemaNode` AST node into a TypeScript AST node:
- * - **`printer.print(node)`** — when `options.typeName` is set, returns a full
- *   `type Name = …` or `interface Name { … }` declaration (`ts.Node`).
- *   Without `typeName`, returns the raw `ts.TypeNode` for the schema.
- *
- * Dispatches on `node.type` to the appropriate handler in `nodes`. Options are closed
- * over per printer instance, so each call to `printerTs(options)` produces an independent printer.
- *
- * @example Raw type node (no `typeName`)
- * ```ts
- * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' } })
- * const typeNode = printer.print(schemaNode) // ts.TypeNode
- * ```
- *
- * @example Full declaration (with `typeName`)
- * ```ts
- * const printer = printerTs({ optionalType: 'questionToken', arrayType: 'array', enum: { type: 'inlineLiteral' }, typeName: 'MyType' })
- * const declaration = printer.print(schemaNode) // ts.TypeAliasDeclaration | ts.InterfaceDeclaration
- * ```
- */
-export const printerTs = ast.definePrinter<PrinterTs>((options) => {
-  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(options.optionalType)
-
-  return {
-    name: 'typescript',
-    options,
-    nodes: {
-      any: () => factory.keywordTypeNodes.any,
-      unknown: () => factory.keywordTypeNodes.unknown,
-      void: () => factory.keywordTypeNodes.void,
-      never: () => factory.keywordTypeNodes.never,
-      boolean: () => factory.keywordTypeNodes.boolean,
-      null: () => factory.keywordTypeNodes.null,
-      blob: () => factory.createTypeReferenceNode('Blob', []),
-      string: () => factory.keywordTypeNodes.string,
-      uuid: () => factory.keywordTypeNodes.string,
-      email: () => factory.keywordTypeNodes.string,
-      url: (node) => {
-        if (node.path) {
-          return factory.createUrlTemplateType(node.path)
-        }
-        return factory.keywordTypeNodes.string
-      },
-      ipv4: () => factory.keywordTypeNodes.string,
-      ipv6: () => factory.keywordTypeNodes.string,
-      datetime: () => factory.keywordTypeNodes.string,
-      number: () => factory.keywordTypeNodes.number,
-      integer: () => factory.keywordTypeNodes.number,
-      bigint: () => factory.keywordTypeNodes.bigint,
-      date: factory.dateOrStringNode,
-      time: factory.dateOrStringNode,
-      ref(node) {
-        if (!node.name) {
-          return null
-        }
-        // Parser-generated refs (with $ref) carry raw schema names that need resolving.
-        // Use the canonical name from the $ref path — node.name may have been overridden
-        // (e.g. by single-member allOf flatten using the property-derived child name).
-        // Inline refs (without $ref) from utils already carry resolved type names.
-        const refName = node.ref ? (extractRefName(node.ref) ?? node.name) : node.name
-
-        // When a Key suffix is configured, enum refs must use the suffixed name (e.g. `StatusKey`)
-        // so the reference matches what the enum file actually exports.
-        const isEnumRef =
-          node.ref && ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enum.type) && this.options.enum.typeSuffix && this.options.enumSchemaNames?.has(refName)
-
-        const name = isEnumRef
-          ? this.options.resolver.resolveEnumKeyName({ name: refName }, this.options.enum.typeSuffix)
-          : node.ref
-            ? this.options.resolver.default(refName, 'type')
-            : refName
-
-        return factory.createTypeReferenceNode(name, undefined)
-      },
-      enum(node) {
-        const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []
-
-        if (this.options.enum.type === 'inlineLiteral' || !node.name) {
-          const literalNodes = values
-            .filter((v): v is string | number | boolean => v !== null && v !== undefined)
-            .map((value) => factory.constToTypeNode(value, typeof value as 'string' | 'number' | 'boolean'))
-            .filter(isNonNullable)
-
-          return factory.createUnionDeclaration({ withParentheses: true, nodes: literalNodes }) ?? undefined
-        }
-
-        const resolvedName =
-          ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enum.type) && this.options.enum.typeSuffix
-            ? this.options.resolver.resolveEnumKeyName(node, this.options.enum.typeSuffix)
-            : this.options.resolver.default(node.name, 'type')
-
-        return factory.createTypeReferenceNode(resolvedName, undefined)
-      },
-      union(node) {
-        const members = node.members ?? []
-
-        const hasStringLiteral = members.some((m) => {
-          const enumNode = ast.narrowSchema(m, ast.schemaTypes.enum)
-          return enumNode?.primitive === 'string'
-        })
-        const hasPlainString = members.some((m) => ast.isStringType(m))
-
-        if (hasStringLiteral && hasPlainString) {
-          const memberNodes = members
-            .map((m) => {
-              if (ast.isStringType(m)) {
-                return factory.createIntersectionDeclaration({
-                  nodes: [factory.keywordTypeNodes.string, factory.createTypeLiteralNode([])],
-                  withParentheses: true,
-                })
-              }
-
-              return this.transform(m)
-            })
-            .filter(isNonNullable)
-
-          return factory.createUnionDeclaration({ withParentheses: true, nodes: memberNodes }) ?? undefined
-        }
-
-        return factory.createUnionDeclaration({ withParentheses: true, nodes: factory.buildMemberNodes(members, this.transform) }) ?? undefined
-      },
-      intersection(node) {
-        return factory.createIntersectionDeclaration({ withParentheses: true, nodes: factory.buildMemberNodes(node.members, this.transform) }) ?? null
-      },
-      array(node) {
-        const itemNodes = (node.items ?? []).map((item) => this.transform(item)).filter(isNonNullable)
-
-        return factory.createArrayDeclaration({ nodes: itemNodes, arrayType: this.options.arrayType }) ?? null
-      },
-      tuple(node) {
-        return factory.buildTupleNode(node, this.transform) ?? null
-      },
-      object(node) {
-        const { transform, options } = this
-
-        const addsQuestionToken = OPTIONAL_ADDS_QUESTION_TOKEN.has(options.optionalType)
-
-        const propertyNodes: Array<ts.TypeElement> = node.properties.map((prop) => {
-          const baseType = transform(prop.schema) ?? factory.keywordTypeNodes.unknown
-          const type = factory.buildPropertyType(prop.schema, baseType, options.optionalType)
-          const propMeta = ast.syncSchemaRef(prop.schema)
-
-          const propertyNode = factory.createPropertySignature({
-            questionToken: prop.schema.optional || prop.schema.nullish ? addsQuestionToken : false,
-            name: prop.name,
-            type,
-            readOnly: propMeta?.readOnly,
-          })
-
-          return factory.appendJSDocToNode({ node: propertyNode, comments: buildPropertyJSDocComments(prop.schema) })
-        })
-
-        const allElements = [...propertyNodes, ...factory.buildIndexSignatures(node, propertyNodes.length, transform)]
-
-        if (!allElements.length) {
-          return factory.keywordTypeNodes.object
-        }
-
-        return factory.createTypeLiteralNode(allElements)
-      },
-      ...options.nodes,
-    },
-    print(node) {
-      const { name, syntaxType = 'type', description, keysToOmit } = this.options
-
-      const transformed = this.transform(node)
-      if (!transformed) return null
-
-      // For ref nodes, structural metadata lives on node.schema rather than the ref node itself.
-      const meta = ast.syncSchemaRef(node)
-
-      // Without name, apply modifiers inline and return.
-      if (!name) {
-        const withNullable = meta.nullable ? factory.createUnionDeclaration({ nodes: [transformed, factory.keywordTypeNodes.null] }) : transformed
-        const result =
-          (meta.nullish || meta.optional) && addsUndefined
-            ? factory.createUnionDeclaration({ nodes: [withNullable, factory.keywordTypeNodes.undefined] })
-            : withNullable
-        return parserTs.print(result)
-      }
-
-      // When keysToOmit is present, wrap with Omit first, then apply nullable/optional
-      // modifiers so they are not swallowed by NonNullable inside createOmitDeclaration.
-      const inner = (() => {
-        const omitted: ts.TypeNode = keysToOmit?.length
-          ? factory.createOmitDeclaration({ keys: keysToOmit, type: transformed, nonNullable: true })
-          : transformed
-        const withNullable = meta.nullable ? factory.createUnionDeclaration({ nodes: [omitted, factory.keywordTypeNodes.null] }) : omitted
-        // For named type declarations (type aliases), optional/nullish always produces | undefined
-        // regardless of optionalType — the questionToken ? modifier only applies to object properties.
-        return meta.nullish || meta.optional ? factory.createUnionDeclaration({ nodes: [withNullable, factory.keywordTypeNodes.undefined] }) : withNullable
-      })()
-
-      const useTypeGeneration = syntaxType === 'type' || inner.kind === factory.syntaxKind.union || !!keysToOmit?.length
-
-      const typeNode = factory.createTypeDeclaration({
-        name,
-        isExportable: true,
-        type: inner,
-        syntax: useTypeGeneration ? 'type' : 'interface',
-        comments: buildPropertyJSDocComments({
-          ...meta,
-          description,
-        }),
-      })
-
-      return parserTs.print(typeNode)
-    },
-  }
-})

package/src/resolvers/resolverTs.ts

@@ -1,69 +0,0 @@
-import { ensureValidVarName, pascalCase, toFilePath } from '@internals/utils'
-import { defineResolver } from '@kubb/core'
-import type { PluginTs } from '../types.ts'
-
-/**
- * Default resolver used by `@kubb/plugin-ts`. Decides the names and file paths
- * for every generated TypeScript type. Import this in other plugins that need
- * to reference the exact names `plugin-ts` produces without duplicating the
- * casing/file-layout rules.
- *
- * The `default` method is supplied by `defineResolver`. It uses PascalCase for
- * type names and PascalCase file paths (dotted names become `/`-joined) for files.
- *
- * @example Resolve a type and file name
- * ```ts
- * import { resolverTs } from '@kubb/plugin-ts'
- *
- * resolverTs.default('list pets', 'type')        // 'ListPets'
- * resolverTs.resolvePathName('list pets', 'file') // 'ListPets'
- * resolverTs.resolveResponseStatusName(node, 200) // 'ListPetsStatus200'
- * ```
- */
-export const resolverTs = defineResolver<PluginTs>(() => {
-  return {
-    name: 'default',
-    pluginName: 'plugin-ts',
-    default(name, type) {
-      if (type === 'file') return toFilePath(name, pascalCase)
-      return ensureValidVarName(pascalCase(name))
-    },
-    resolveTypeName(name) {
-      return ensureValidVarName(pascalCase(name))
-    },
-    resolvePathName(name, type) {
-      if (type === 'file') return toFilePath(name, pascalCase)
-      return ensureValidVarName(pascalCase(name))
-    },
-    resolveParamName(node, param) {
-      return this.resolveTypeName(`${node.operationId} ${param.in} ${param.name}`)
-    },
-    resolveResponseStatusName(node, statusCode) {
-      return this.resolveTypeName(`${node.operationId} Status ${statusCode}`)
-    },
-    resolveDataName(node) {
-      return this.resolveTypeName(`${node.operationId} Data`)
-    },
-    resolveRequestConfigName(node) {
-      return this.resolveTypeName(`${node.operationId} RequestConfig`)
-    },
-    resolveResponsesName(node) {
-      return this.resolveTypeName(`${node.operationId} Responses`)
-    },
-    resolveResponseName(node) {
-      return this.resolveTypeName(`${node.operationId} Response`)
-    },
-    resolveEnumKeyName(node, enumTypeSuffix = 'key') {
-      return `${this.resolveTypeName(node.name ?? '')}${enumTypeSuffix}`
-    },
-    resolvePathParamsName(node, param) {
-      return this.resolveParamName(node, param)
-    },
-    resolveQueryParamsName(node, param) {
-      return this.resolveParamName(node, param)
-    },
-    resolveHeaderParamsName(node, param) {
-      return this.resolveParamName(node, param)
-    },
-  }
-})