@kubb/adapter-oas 5.0.0-beta.63 → 5.0.0-beta.65

package/src/refs.ts

@@ -1,86 +0,0 @@
-import { type Diagnostic, Diagnostics } from '@kubb/core'
-import { isReference } from './guards.ts'
-import type { Document } from './types.ts'
-
-const _refCache = new WeakMap<Document, Map<string, unknown>>()
-
-/**
- * Resolves a local JSON pointer reference from a document.
- *
- * Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
- * resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
- * build there is no sink to collect it, so it throws instead.
- *
- * @example
- * ```ts
- * resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
- * ```
- */
-export function resolveRef<T = unknown>(document: Document, $ref: string): T | null {
-  const origRef = $ref
-  $ref = $ref.trim()
-  if ($ref === '') {
-    return null
-  }
-  if (!$ref.startsWith('#')) return null
-  $ref = globalThis.decodeURIComponent($ref.substring(1))
-
-  let docCache = _refCache.get(document)
-  if (!docCache) {
-    docCache = new Map()
-    _refCache.set(document, docCache)
-  }
-
-  if (docCache.has($ref)) {
-    return docCache.get($ref) as T
-  }
-
-  const current = $ref
-    .split('/')
-    .filter(Boolean)
-    .reduce((obj: unknown, key: string) => (obj as Record<string, unknown>)?.[key], document as unknown)
-
-  if (!current) {
-    const diagnostic: Diagnostic = {
-      code: Diagnostics.code.refNotFound,
-      severity: 'error',
-      message: `Could not find a definition for ${origRef}.`,
-      help: 'Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.',
-      location: { kind: 'schema', pointer: origRef, ref: origRef },
-    }
-    // Report the unresolved ref into the active build and resolve to null, like any
-    // other unresolvable ref. The build collects it and keeps going. Outside a build there is no
-    // sink, so throw rather than silently returning null.
-    if (!Diagnostics.report(diagnostic)) {
-      throw new Diagnostics.Error(diagnostic)
-    }
-    return null
-  }
-
-  docCache.set($ref, current)
-  return current as T
-}
-
-/**
- * Resolves a `$ref` object while preserving the original `$ref` field on the result.
- *
- * Useful for parser flows that need both dereferenced fields and pointer
- * identity (for naming/import purposes). Non-reference values are returned as-is.
- *
- * @example
- * ```ts
- * dereferenceWithRef(document, { $ref: '#/components/schemas/Pet' })
- * // { $ref: '#/components/schemas/Pet', type: 'object', properties: { ... } }
- * ```
- */
-export function dereferenceWithRef<T = unknown>(document: Document, schema?: T): T {
-  if (isReference(schema)) {
-    return {
-      ...schema,
-      ...resolveRef(document, schema.$ref),
-      $ref: schema.$ref,
-    }
-  }
-
-  return schema as T
-}

package/src/resolvers.ts

@@ -1,590 +0,0 @@
-import { pascalCase } from '@internals/utils'
-import { Diagnostics } from '@kubb/core'
-import type { ast } from '@kubb/core'
-import { formatMap, SCHEMA_REF_PREFIX, specialCasedFormats, structuralKeys } from './constants.ts'
-import { isReference } from './guards.ts'
-import { isJsonMimeType } from './mime.ts'
-import { getRequestContent, getResponseByStatusCode } from './operation.ts'
-import { dereferenceWithRef, resolveRef } from './refs.ts'
-import type { ContentType, Document, MediaTypeObject, Operation, ParameterObject, ResponseObject, SchemaObject, ServerObject } from './types.ts'
-
-/**
- * Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
- * Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
- * Throws if an override value is not in the variable's `enum` list.
- *
- * @example
- * ```ts
- * resolveServerUrl(
- *   { url: 'https://{env}.api.example.com', variables: { env: { default: 'dev', enum: ['dev', 'prod'] } } },
- *   { env: 'prod' },
- * )
- * // 'https://prod.api.example.com'
- * ```
- */
-export function resolveServerUrl(server: ServerObject, overrides?: Record<string, string>): string {
-  if (!server.variables) {
-    return server.url
-  }
-
-  let url = server.url
-  for (const [key, variable] of Object.entries(server.variables)) {
-    const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : undefined)
-    if (value === undefined) {
-      continue
-    }
-
-    if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) {
-      throw new Diagnostics.Error({
-        code: Diagnostics.code.invalidServerVariable,
-        severity: 'error',
-        message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(', ')}.`,
-        help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
-        location: { kind: 'document', pointer: '#/servers' },
-      })
-    }
-
-    url = url.replaceAll(`{${key}}`, value)
-  }
-
-  return url
-}
-
-/**
- * Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
- * Formats not in `formatMap` (e.g., `int64`, `date-time`) are handled separately by parser options.
- */
-export function getSchemaType(format: string): ast.SchemaType | null {
-  return formatMap[format as keyof typeof formatMap] ?? null
-}
-
-/**
- * Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
- * `specialCasedFormats` that `convertFormat` handles directly. False means the format falls back to
- * the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
- * diagnostic in step with the parser as `formatMap` grows.
- */
-export function isHandledFormat(format: string): boolean {
-  return getSchemaType(format) !== null || specialCasedFormats.has(format)
-}
-
-/**
- * Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
- * Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
- */
-export function getPrimitiveType(type: string | undefined): ast.PrimitiveSchemaType {
-  if (type === 'number' || type === 'integer' || type === 'bigint') return type
-  if (type === 'boolean') return 'boolean'
-
-  return 'string'
-}
-
-export type OperationsOptions = {
-  contentType?: ContentType
-}
-
-/**
- * Returns all parameters for an operation, merging path-level and operation-level entries.
- * Operation-level parameters override path-level ones with the same `in:name` key.
- * Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
- *
- * @example
- * ```ts
- * getParameters(document, operation)
- * // [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }]
- * ```
- */
-export function getParameters(document: Document, operation: Operation): Array<ParameterObject> {
-  const resolveParams = (params: Array<unknown>): Array<ParameterObject> =>
-    params.map((p) => dereferenceWithRef(document, p)).filter((p): p is ParameterObject => !!p && typeof p === 'object' && 'in' in p && 'name' in p)
-
-  const operationParams = resolveParams(operation.schema?.parameters || [])
-  const pathItem = document.paths?.[operation.path]
-  const pathLevelParams = resolveParams(pathItem && !isReference(pathItem) && pathItem.parameters ? pathItem.parameters : [])
-
-  const paramMap = new Map<string, ParameterObject>()
-  for (const p of pathLevelParams) {
-    if (p.name && p.in) {
-      paramMap.set(`${p.in}:${p.name}`, p)
-    }
-  }
-  for (const p of operationParams) {
-    if (p.name && p.in) {
-      paramMap.set(`${p.in}:${p.name}`, p)
-    }
-  }
-
-  return Array.from(paramMap.values())
-}
-
-function getResponseBody(responseBody: boolean | ResponseObject, contentType?: string): MediaTypeObject | false | [string, MediaTypeObject, ...Array<string>] {
-  if (!responseBody) return false
-  if (isReference(responseBody)) return false
-
-  const body = responseBody as ResponseObject
-  if (!body.content) return false
-
-  if (contentType) {
-    if (!(contentType in body.content)) return false
-    return body.content[contentType]!
-  }
-
-  let availableContentType: string | undefined
-  const contentTypes = Object.keys(body.content)
-  for (const mt of contentTypes) {
-    if (isJsonMimeType(mt)) {
-      availableContentType = mt
-      break
-    }
-  }
-
-  if (!availableContentType) {
-    availableContentType = contentTypes[0]
-  }
-
-  if (availableContentType) {
-    return [availableContentType, body.content[availableContentType]!, ...(body.description ? [body.description] : [])]
-  }
-
-  return false
-}
-
-/**
- * Returns the response schema for a given operation and HTTP status code.
- *
- * Returns an empty object `{}` when no response body schema is available.
- *
- * @example
- * ```ts
- * getResponseSchema(document, operation, 200)         // SchemaObject
- * getResponseSchema(document, operation, '4XX')       // {}
- * ```
- */
-export function getResponseSchema(document: Document, operation: Operation, statusCode: string | number, options: OperationsOptions = {}): SchemaObject {
-  if (operation.schema.responses) {
-    const responses = operation.schema.responses
-    for (const key in responses) {
-      const schema = responses[key]
-      if (schema && isReference(schema)) {
-        responses[key] = resolveRef<any>(document, schema.$ref)
-      }
-    }
-  }
-
-  const responseBody = getResponseBody(getResponseByStatusCode({ document, operation, statusCode }), options.contentType)
-
-  if (responseBody === false) {
-    return {}
-  }
-
-  const schema = Array.isArray(responseBody) ? responseBody[1].schema : responseBody.schema
-
-  if (!schema) {
-    return {}
-  }
-
-  return dereferenceWithRef(document, schema)
-}
-
-/**
- * Returns the request body schema for an operation, or `null` when absent.
- *
- * @example
- * ```ts
- * getRequestSchema(document, operation) // SchemaObject | null
- * ```
- */
-export function getRequestSchema(document: Document, operation: Operation, options: OperationsOptions = {}): SchemaObject | null {
-  if (operation.schema.requestBody) {
-    operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody)
-  }
-
-  const requestBody = getRequestContent({ document, operation, mediaType: options.contentType })
-
-  if (requestBody === false) {
-    return null
-  }
-
-  const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema
-
-  if (!schema) {
-    return null
-  }
-
-  return dereferenceWithRef(document, schema)
-}
-
-/**
- * The three component sections Kubb reads schemas from.
- */
-type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
-
-/**
- * A schema annotated with its component section source and original name. `getSchemas` uses this
- * to resolve name collisions across sources.
- */
-type SchemaWithMetadata = {
-  schema: SchemaObject
-  source: SchemaSourceMode
-  originalName: string
-}
-
-export type GetSchemasOptions = {
-  contentType?: ContentType
-}
-
-export type GetSchemasResult = {
-  schemas: Record<string, SchemaObject>
-  /**
-   * Maps each original component pointer (`#/components/<source>/<name>`) to the
-   * collision-resolved unique name used as the key in `schemas`.
-   */
-  nameMapping: Map<string, string>
-}
-
-/**
- * Flattens a keyword-only `allOf` into its parent schema.
- *
- * Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
- * (see `structuralKeys`). Outer schema values take precedence over fragment values.
- * Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
- *
- * @example
- * ```ts
- * flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
- * // { type: 'object', properties: {}, description: 'A pet' }
- * ```
- *
- * @example
- * ```ts
- * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
- * // returned unchanged, contains a $ref
- * ```
- */
-/**
- * Returns `true` when `fragment` carries any JSON Schema keyword that makes it
- * structurally significant on its own (see `structuralKeys`).
- *
- * A fragment with a structural keyword can't be safely merged into a parent schema.
- */
-function hasStructuralKeywords(fragment: SchemaObject): boolean {
-  for (const key in fragment) {
-    if (structuralKeys.has(key as 'properties')) return true
-  }
-  return false
-}
-
-export function flattenSchema(schema: SchemaObject | null): SchemaObject | null {
-  if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null
-
-  const allOfFragments = schema.allOf as Array<SchemaObject>
-  if (allOfFragments.some((item) => isReference(item))) return schema
-  if (allOfFragments.some(hasStructuralKeywords)) return schema
-
-  const merged: SchemaObject = { ...schema }
-  delete merged.allOf
-
-  for (const fragment of allOfFragments) {
-    for (const [key, value] of Object.entries(fragment)) {
-      if (merged[key as keyof typeof merged] === undefined) {
-        merged[key as keyof typeof merged] = value
-      }
-    }
-  }
-
-  return merged
-}
-
-/**
- * Extracts the inline schema from a media-type `content` map.
- *
- * Prefers `preferredContentType` when given, otherwise uses the first key in the map.
- * Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
- *
- * @example
- * ```ts
- * extractSchemaFromContent(operation.content, 'application/json')
- * // SchemaObject | null
- * ```
- */
-export function extractSchemaFromContent(content: Record<string, unknown> | undefined, preferredContentType?: ContentType): SchemaObject | null {
-  if (!content) return null
-
-  const firstContentType = Object.keys(content)[0] ?? 'application/json'
-  const targetContentType = preferredContentType ?? firstContentType
-  const contentSchema = content[targetContentType] as { schema?: SchemaObject } | undefined
-  const schema = contentSchema?.schema
-
-  if (schema && '$ref' in schema) return null
-  return schema ?? null
-}
-
-/**
- * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
- */
-function* collectRefs(schema: unknown): Generator<string, void, undefined> {
-  if (Array.isArray(schema)) {
-    for (const item of schema) yield* collectRefs(item)
-    return
-  }
-
-  if (schema && typeof schema === 'object') {
-    for (const key in schema) {
-      const value = (schema as Record<string, unknown>)[key]
-      if (!(key === '$ref' && typeof value === 'string')) {
-        yield* collectRefs(value)
-        continue
-      }
-      if (value.startsWith(SCHEMA_REF_PREFIX)) {
-        const name = value.slice(SCHEMA_REF_PREFIX.length)
-        if (name) yield name
-      }
-    }
-  }
-}
-
-/**
- * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
- *
- * Referenced schemas appear before the schemas that depend on them, so code generators
- * can emit types in the correct order. Cycles are silently skipped.
- *
- * @example
- * ```ts
- * const sorted = sortSchemas({ Order: orderSchema, Pet: petSchema })
- * // Pet appears before Order when Order.$ref points at Pet
- * ```
- */
-export function sortSchemas(schemas: Record<string, SchemaObject>): Record<string, SchemaObject> {
-  const deps = new Map<string, Array<string>>()
-
-  for (const [name, schema] of Object.entries(schemas)) {
-    deps.set(name, [...new Set(collectRefs(schema))])
-  }
-
-  const sorted: Array<string> = []
-  const visited = new Set<string>()
-
-  function visit(name: string, stack: Set<string>) {
-    if (visited.has(name) || stack.has(name)) return
-    stack.add(name)
-    for (const child of deps.get(name) ?? []) {
-      if (deps.has(child)) visit(child, stack)
-    }
-    stack.delete(name)
-    visited.add(name)
-    sorted.push(name)
-  }
-
-  for (const name of Object.keys(schemas)) {
-    visit(name, new Set())
-  }
-
-  const result: Record<string, SchemaObject> = {}
-  for (const name of sorted) result[name] = schemas[name]!
-  return result
-}
-
-const semanticSuffixes: Record<SchemaSourceMode, string> = {
-  schemas: 'Schema',
-  responses: 'Response',
-  requestBodies: 'Request',
-}
-
-function getSemanticSuffix(source: SchemaSourceMode): string {
-  return semanticSuffixes[source]
-}
-
-function resolveSchemaRef(document: Document, schema: SchemaObject): SchemaObject {
-  if (!isReference(schema)) return schema
-  const resolved = resolveRef<SchemaObject>(document, schema.$ref)
-  return resolved && !isReference(resolved) ? resolved : schema
-}
-
-/**
- * Collects component schemas from one or more sources and resolves name collisions.
- *
- * Sources default to `['schemas', 'requestBodies', 'responses']`. Returned schemas are
- * topologically sorted by `$ref` dependency so generators emit types in the correct order.
- *
- * When two or more schemas normalize to the same PascalCase name:
- * - Same source → numeric suffix (`2`, `3`, …).
- * - Different sources → semantic suffix (`Schema`, `Response`, `Request`).
- *
- * @example
- * ```ts
- * const { schemas, nameMapping } = getSchemas(document, { contentType: 'application/json' })
- * ```
- */
-export function getSchemas(document: Document, { contentType }: GetSchemasOptions): GetSchemasResult {
-  const components = document.components
-
-  const candidates: Array<SchemaWithMetadata> = [
-    ...Object.entries((components?.schemas as Record<string, SchemaObject>) ?? {}).map(([name, schema]) => ({
-      schema: resolveSchemaRef(document, schema),
-      source: 'schemas' as const,
-      originalName: name,
-    })),
-    ...(['responses', 'requestBodies'] as const).flatMap((source) =>
-      Object.entries(components?.[source] ?? {}).flatMap(([name, item]) => {
-        const schema = extractSchemaFromContent((item as { content?: Record<string, unknown> }).content, contentType)
-        return schema
-          ? [
-              {
-                schema: resolveSchemaRef(document, schema),
-                source,
-                originalName: name,
-              },
-            ]
-          : []
-      }),
-    ),
-  ]
-
-  const normalizedNames = new Map<string, Array<SchemaWithMetadata>>()
-  for (const item of candidates) {
-    const key = pascalCase(item.originalName)
-    const bucket = normalizedNames.get(key) ?? []
-    bucket.push(item)
-    normalizedNames.set(key, bucket)
-  }
-
-  const schemas: Record<string, SchemaObject> = {}
-  const nameMapping = new Map<string, string>()
-
-  for (const [, items] of normalizedNames) {
-    const isSingle = items.length === 1
-    let hasMultipleSources = false
-    if (!isSingle) {
-      const firstSource = items[0]!.source
-      for (let i = 1; i < items.length; i++) {
-        if (items[i]!.source !== firstSource) {
-          hasMultipleSources = true
-          break
-        }
-      }
-    }
-
-    items.forEach((item, index) => {
-      const suffix = isSingle ? '' : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? '' : String(index + 1)
-      const uniqueName = item.originalName + suffix
-      schemas[uniqueName] = item.schema
-      nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName)
-    })
-  }
-
-  return { schemas: sortSchemas(schemas), nameMapping }
-}
-
-/**
- * Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
- * Returns `null` when `dateType: false`, so the format falls through to `string`.
- */
-export function getDateType(
-  options: ast.ParserOptions,
-  format: 'date-time' | 'date' | 'time',
-): { type: 'datetime'; offset?: boolean; local?: boolean } | { type: 'date' | 'time'; representation: 'date' | 'string' } | null {
-  if (!options.dateType) {
-    return null
-  }
-
-  if (format === 'date-time') {
-    if (options.dateType === 'date') {
-      return { type: 'date', representation: 'date' }
-    }
-    if (options.dateType === 'stringOffset') {
-      return { type: 'datetime', offset: true }
-    }
-    if (options.dateType === 'stringLocal') {
-      return { type: 'datetime', local: true }
-    }
-    return { type: 'datetime', offset: false }
-  }
-
-  if (format === 'date') {
-    return {
-      type: 'date',
-      representation: options.dateType === 'date' ? 'date' : 'string',
-    }
-  }
-
-  // time
-  return {
-    type: 'time',
-    representation: options.dateType === 'date' ? 'date' : 'string',
-  }
-}
-
-/**
- * Collects the shared metadata fields passed to every `createSchema` call.
- */
-export function buildSchemaNode(schema: SchemaObject, name: string | null | undefined, nullable: true | undefined, defaultValue: unknown) {
-  return {
-    name,
-    nullable,
-    title: schema.title,
-    description: schema.description,
-    deprecated: schema.deprecated,
-    readOnly: schema.readOnly,
-    writeOnly: schema.writeOnly,
-    default: defaultValue,
-    example: schema.example,
-    format: schema.format,
-  } as const
-}
-
-/**
- * Returns all request body content type keys for an operation.
- *
- * The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
- * `getRequestSchema` already performs), so the returned list accurately reflects the
- * available content types even for referenced bodies.
- *
- * @example
- * ```ts
- * getRequestBodyContentTypes(document, operation)
- * // ['application/json', 'multipart/form-data']
- * ```
- */
-export function getRequestBodyContentTypes(document: Document, operation: Operation): Array<string> {
-  if (operation.schema.requestBody) {
-    operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody)
-  }
-
-  const body = operation.schema.requestBody as { content?: Record<string, unknown> } | undefined
-  if (!body) return []
-
-  // dereferenceWithRef keeps $ref but spreads all resolved fields (including `content`).
-  // Do not bail out on isReference, the content is already present on the merged object.
-  return body.content ? Object.keys(body.content) : []
-}
-
-/**
- * Returns all response content type keys for an operation at a given status code.
- *
- * Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
- * so the returned list reflects the available content types even for referenced responses.
- *
- * @example
- * ```ts
- * getResponseBodyContentTypes(document, operation, 200)
- * // ['application/json', 'application/xml']
- * ```
- */
-export function getResponseBodyContentTypes(document: Document, operation: Operation, statusCode: string | number): Array<string> {
-  if (operation.schema.responses) {
-    const responses = operation.schema.responses
-    for (const key in responses) {
-      const schema = responses[key]
-      if (schema && isReference(schema)) {
-        responses[key] = resolveRef<any>(document, schema.$ref)
-      }
-    }
-  }
-
-  const responseObj = getResponseByStatusCode({ document, operation, statusCode })
-  if (!responseObj || typeof responseObj !== 'object' || isReference(responseObj)) return []
-
-  const body = responseObj as { content?: Record<string, unknown> }
-  return body.content ? Object.keys(body.content) : []
-}