@kubb/adapter-oas 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/constants.ts

@@ -1,41 +1,83 @@
-import type { SchemaType } from '@kubb/ast/types'
-import type { HttpMethods as OASHttpMethods } from 'oas/types'
+import { ast } from '@kubb/core'
 
-// ─── Merge defaults ────────────────────────────────────────────────────────────
+/**
+ * Default parser options applied when no explicit options are provided.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+ *
+ * const parser = createOasParser(oas)
+ * const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+ * ```
+ */
+export const DEFAULT_PARSER_OPTIONS = {
+  dateType: 'string',
+  integerType: 'bigint',
+  unknownType: 'any',
+  emptySchemaType: 'any',
+  enumSuffix: 'enum',
+} as const satisfies ast.ParserOptions
+
+/**
+ * JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+ *
+ * Used when building or parsing `$ref` strings.
+ *
+ * @example
+ * ```ts
+ * `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+ * ```
+ */
+export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
 
 /**
- * OpenAPI version string written into merged document stubs.
+ * OpenAPI version string written into the stub document created during multi-spec merges.
  */
 export const MERGE_OPENAPI_VERSION = '3.0.0' as const
 
 /**
- * Fallback `info.title` used when merging multiple API documents.
+ * Fallback `info.title` placed in the stub document when merging multiple API files.
  */
 export const MERGE_DEFAULT_TITLE = 'Merged API' as const
 
 /**
- * Fallback `info.version` used when merging multiple API documents.
+ * Fallback `info.version` placed in the stub document when merging multiple API files.
  */
 export const MERGE_DEFAULT_VERSION = '1.0.0' as const
 
-// ─── Schema analysis ───────────────────────────────────────────────────────────
-
 /**
- * JSON Schema keywords that indicate structural composition.
- * A schema fragment containing any of these keys must not be inlined into its
- * parent during `allOf` flattening — it carries semantic meaning of its own.
+ * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
+ *
+ * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
+ * intersection member rather than being merged into the parent.
+ *
+ * @example
+ * ```ts
+ * import { structuralKeys } from '@kubb/adapter-oas'
+ *
+ * const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
+ * // true when fragment has e.g. 'properties' or 'oneOf'
+ * ```
  */
 export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
 
 /**
- * Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
+ * Static map from OAS `format` strings to Kubb `SchemaType` values.
+ *
+ * Only formats whose AST type differs from the OAS `type` field appear here.
+ * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
+ * in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
+ * `idn-hostname` map to `'url'` as the closest generic string-format type.
  *
- * Only formats that need a type different from the raw OAS `type` are listed.
- * `int64`, `date-time`, `date`, and `time` are handled separately because their
- * mapping depends on runtime parser options.
+ * @example
+ * ```ts
+ * import { formatMap } from '@kubb/adapter-oas'
  *
- * Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — the closest supported
- * scalar type in the Kubb AST, even though these are not strictly URLs.
+ * formatMap['uuid']   // 'uuid'
+ * formatMap['binary'] // 'blob'
+ * formatMap['float']  // 'number'
+ * ```
  */
 export const formatMap = {
   uuid: 'uuid',
@@ -44,8 +86,8 @@ export const formatMap = {
   uri: 'url',
   'uri-reference': 'url',
   url: 'url',
-  ipv4: 'url',
-  ipv6: 'url',
+  ipv4: 'ipv4',
+  ipv6: 'ipv6',
   hostname: 'url',
   'idn-hostname': 'url',
   binary: 'blob',
@@ -55,60 +97,26 @@ export const formatMap = {
   int32: 'integer',
   float: 'number',
   double: 'number',
-} as const satisfies Record<string, SchemaType>
-
-/**
- * Exhaustive list of media types that Kubb recognizes.
- */
-export const knownMediaTypes = new Set([
-  'application/json',
-  'application/xml',
-  'application/x-www-form-urlencoded',
-  'application/octet-stream',
-  'application/pdf',
-  'application/zip',
-  'application/graphql',
-  'multipart/form-data',
-  'text/plain',
-  'text/html',
-  'text/csv',
-  'text/xml',
-  'image/png',
-  'image/jpeg',
-  'image/gif',
-  'image/webp',
-  'image/svg+xml',
-  'audio/mpeg',
-  'video/mp4',
-] as const)
+} as const satisfies Record<string, ast.SchemaType>
 
 /**
- * Vendor extension keys used to attach human-readable labels to enum values.
- * Checked in priority order: the first key found wins.
+ * Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
+ *
+ * @example
+ * ```ts
+ * import { enumExtensionKeys } from '@kubb/adapter-oas'
+ *
+ * const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
+ * ```
  */
 export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
 
 /**
- * Scalar primitive schema types used for union member simplification.
- */
-export const SCALAR_PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'bigint', 'boolean'] as const)
-
-// ─── HTTP ──────────────────────────────────────────────────────────────────────
-
-/**
- * Canonical HTTP method names for the Kubb OAS layer.
- * Keys are uppercase (used in generated code); values are the lowercase strings
- * that the `oas` library uses internally.
- *
- * TODO(v5): remove — use `httpMethods` from `@kubb/ast`
+ * Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
+ * Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
  */
-export const httpMethods = {
-  GET: 'get',
-  POST: 'post',
-  PUT: 'put',
-  PATCH: 'patch',
-  DELETE: 'delete',
-  HEAD: 'head',
-  OPTIONS: 'options',
-  TRACE: 'trace',
-} as const satisfies Record<Uppercase<OASHttpMethods>, OASHttpMethods>
+export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
+  ['any', ast.schemaTypes.any],
+  ['unknown', ast.schemaTypes.unknown],
+  ['void', ast.schemaTypes.void],
+])

package/src/discriminator.ts

@@ -0,0 +1,108 @@
+import { ast } from '@kubb/core'
+
+type DiscriminatorTarget = {
+  propertyName: string
+  enumValues: Array<string | number | boolean>
+}
+
+/**
+ * Injects discriminator enum values into child schemas so they know which value identifies them.
+ *
+ * Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
+ * enum value each union member is mapped to, then adds (or replaces) that property on the matching
+ * child object schema.
+ *
+ * Returns a new `InputNode` — the original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const { root } = parseOas(document, options)
+ * const next = applyDiscriminatorInheritance(root)
+ * ```
+ */
+export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNode {
+  const childMap = new Map<string, DiscriminatorTarget>()
+
+  for (const schema of root.schemas) {
+    // Case 1: top-level schema is a union (oneOf/anyOf with discriminator)
+    // Case 2: top-level schema is an intersection wrapping a union (oneOf/anyOf + shared properties)
+    let unionNode = ast.narrowSchema(schema, 'union')
+
+    if (!unionNode) {
+      const intersectionMembers = ast.narrowSchema(schema, 'intersection')?.members
+      if (intersectionMembers) {
+        for (const m of intersectionMembers) {
+          const u = ast.narrowSchema(m, 'union')
+          if (u) {
+            unionNode = u
+            break
+          }
+        }
+      }
+    }
+
+    if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue
+
+    const { discriminatorPropertyName, members } = unionNode
+
+    for (const member of members) {
+      // Members with a discriminant value are intersections: [RefSchemaNode, ObjectSchemaNode]
+      const intersectionNode = ast.narrowSchema(member, 'intersection')
+      if (!intersectionNode?.members) continue
+
+      let refNode: ReturnType<typeof ast.narrowSchema<'ref'>> | undefined
+      let objNode: ReturnType<typeof ast.narrowSchema<'object'>> | undefined
+
+      for (const m of intersectionNode.members) {
+        refNode ??= ast.narrowSchema(m, 'ref')
+        objNode ??= ast.narrowSchema(m, 'object')
+      }
+
+      if (!refNode?.name || !objNode) continue
+
+      const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName)
+      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : undefined
+      if (!enumNode?.enumValues?.length) continue
+
+      const enumValues = enumNode.enumValues.filter((v): v is string | number | boolean => v !== null)
+      if (!enumValues.length) continue
+
+      const existing = childMap.get(refNode.name)
+      if (existing) {
+        existing.enumValues.push(...enumValues)
+      } else {
+        childMap.set(refNode.name, {
+          propertyName: discriminatorPropertyName,
+          enumValues: [...enumValues],
+        })
+      }
+    }
+  }
+
+  if (childMap.size === 0) return root
+
+  return ast.transform(root, {
+    schema(node, { parent }) {
+      if (parent?.kind !== 'Input' || !node.name) return
+
+      const entry = childMap.get(node.name)
+      if (!entry) return
+
+      const objectNode = ast.narrowSchema(node, 'object')
+      if (!objectNode) return
+
+      const { propertyName, enumValues } = entry
+      const enumSchema = ast.createSchema({ type: 'enum', enumValues })
+      const newProp = ast.createProperty({
+        name: propertyName,
+        required: true,
+        schema: enumSchema,
+      })
+
+      const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName)
+      const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => (i === existingIdx ? newProp : p)) : [...objectNode.properties, newProp]
+
+      return { ...objectNode, properties: newProperties }
+    },
+  })
+}

package/src/factory.ts

@@ -0,0 +1,162 @@
+import path from 'node:path'
+import { mergeDeep, URLPath } from '@internals/utils'
+import type { AdapterSource } from '@kubb/core'
+import { bundle, loadConfig } from '@redocly/openapi-core'
+import OASNormalize from 'oas-normalize'
+import swagger2openapi from 'swagger2openapi'
+import { MERGE_DEFAULT_TITLE, MERGE_DEFAULT_VERSION, MERGE_OPENAPI_VERSION } from './constants.ts'
+import { isOpenApiV2Document } from './guards.ts'
+import type { Document } from './types.ts'
+
+export type ParseOptions = {
+  canBundle?: boolean
+  enablePaths?: boolean
+}
+
+export type ValidateDocumentOptions = {
+  throwOnError?: boolean
+}
+
+/**
+ * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ *
+ * Accepts a file path string or an already-parsed document object. File paths are bundled via
+ * Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
+ * to OpenAPI 3.0 via `swagger2openapi`.
+ *
+ * @example
+ * ```ts
+ * const document = await parseDocument('./openapi.yaml')
+ * const document = await parse(rawDocumentObject, { canBundle: false })
+ * ```
+ */
+export async function parseDocument(pathOrApi: string | Document, { canBundle = true, enablePaths = true }: ParseOptions = {}): Promise<Document> {
+  if (typeof pathOrApi === 'string' && canBundle) {
+    const config = await loadConfig()
+    const bundleResults = await bundle({
+      ref: pathOrApi,
+      config,
+      base: pathOrApi,
+    })
+
+    return parseDocument(bundleResults.bundle.parsed as string, {
+      canBundle,
+      enablePaths,
+    })
+  }
+
+  const oasNormalize = new OASNormalize(pathOrApi, {
+    enablePaths,
+    colorizeErrors: true,
+  })
+  const document = (await oasNormalize.load()) as Document
+
+  if (isOpenApiV2Document(document)) {
+    const { openapi } = await swagger2openapi.convertObj(document, {
+      anchors: true,
+    })
+
+    return openapi as Document
+  }
+
+  return document
+}
+
+/**
+ * Deep-merges multiple OpenAPI documents into a single `Document`.
+ *
+ * Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
+ * Throws when the input array is empty.
+ *
+ * @example
+ * ```ts
+ * const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+ * ```
+ */
+export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
+  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { enablePaths: false, canBundle: false })))
+
+  if (documents.length === 0) {
+    throw new Error('No OAS documents provided for merging.')
+  }
+
+  const seed: Document = {
+    openapi: MERGE_OPENAPI_VERSION,
+    info: { title: MERGE_DEFAULT_TITLE, version: MERGE_DEFAULT_VERSION },
+    paths: {},
+    components: { schemas: {} },
+  } as Document
+
+  const merged = documents.reduce(
+    (acc, current) => mergeDeep(acc as Record<string, unknown>, current as Record<string, unknown>),
+    seed as Record<string, unknown>,
+  )
+
+  return parseDocument(merged as Document)
+}
+
+/**
+ * Creates a `Document` from an `AdapterSource`.
+ *
+ * Handles all three source types:
+ * - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
+ * - `{ type: 'paths' }` — merges multiple file paths into a single document.
+ * - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+ *
+ * @example
+ * ```ts
+ * const document = await parseFromConfig({ type: 'path', path: './openapi.yaml' })
+ * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
+ * ```
+ */
+export function parseFromConfig(source: AdapterSource): Promise<Document> {
+  if (source.type === 'data') {
+    if (typeof source.data === 'object') {
+      return parseDocument(structuredClone(source.data) as Document)
+    }
+
+    return parseDocument(source.data as string, { canBundle: false })
+  }
+
+  if (source.type === 'paths') {
+    return mergeDocuments(source.paths)
+  }
+
+  // type === 'path'
+  if (new URLPath(source.path).isURL) {
+    return parseDocument(source.path)
+  }
+
+  return parseDocument(path.resolve(path.dirname(source.path), source.path))
+}
+
+/**
+ * Validates an OpenAPI document using `oas-normalize` with colorized error output.
+ *
+ * @example
+ * ```ts
+ * await validateDocument(document)
+ * ```
+ */
+export async function validateDocument(document: Document, { throwOnError = false }: ValidateDocumentOptions = {}): Promise<void> {
+  try {
+    const oasNormalize = new OASNormalize(document, {
+      enablePaths: true,
+      colorizeErrors: true,
+    })
+
+    await oasNormalize.validate({
+      parser: {
+        validate: {
+          errors: { colorize: true },
+        },
+      },
+    })
+  } catch (error) {
+    if (throwOnError) {
+      throw error
+    }
+
+    // Validation failures are non-fatal — mirror plugin-oas behavior
+  }
+}

package/src/guards.ts

@@ -0,0 +1,68 @@
+import { isPlainObject } from '@internals/utils'
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+import type { DiscriminatorObject, SchemaObject } from './types.ts'
+
+/**
+ * Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
+ *
+ * @example
+ * ```ts
+ * if (isOpenApiV2Document(doc)) {
+ *   // doc is OpenAPIV2.Document
+ * }
+ * ```
+ */
+export function isOpenApiV2Document(doc: unknown): doc is OpenAPIV2.Document {
+  return !!doc && isPlainObject(doc) && !('openapi' in doc)
+}
+
+/**
+ * Returns `true` when a schema should be treated as nullable.
+ *
+ * Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+ * `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+ *
+ * @example
+ * ```ts
+ * isNullable({ type: 'string', nullable: true }) // true
+ * isNullable({ type: ['string', 'null'] })       // true
+ * isNullable({ type: 'string' })                 // false
+ * ```
+ */
+export function isNullable(schema?: SchemaObject & { 'x-nullable'?: boolean }): boolean {
+  const explicitNullable = schema?.nullable ?? schema?.['x-nullable']
+  if (explicitNullable === true) return true
+
+  const schemaType = schema?.type
+  if (schemaType === 'null') return true
+  if (Array.isArray(schemaType)) return schemaType.includes('null')
+
+  return false
+}
+
+/**
+ * Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+ *
+ * @example
+ * ```ts
+ * isReference({ $ref: '#/components/schemas/Pet' }) // true
+ * isReference({ type: 'string' })                   // false
+ * ```
+ */
+export function isReference(obj?: unknown): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
+  return !!obj && typeof obj === 'object' && '$ref' in obj
+}
+
+/**
+ * Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+ *
+ * @example
+ * ```ts
+ * isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
+ * isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
+ * ```
+ */
+export function isDiscriminator(obj?: unknown): obj is SchemaObject & { discriminator: DiscriminatorObject } {
+  const record = obj as Record<string, unknown>
+  return !!obj && !!record['discriminator'] && typeof record['discriminator'] !== 'string'
+}

package/src/index.ts

@@ -1 +1,18 @@
 export { adapterOas, adapterOasName } from './adapter.ts'
+export type { ValidateDocumentOptions } from './factory.ts'
+export { mergeDocuments } from './factory.ts'
+export type {
+  AdapterOas,
+  AdapterOasOptions,
+  AdapterOasResolvedOptions,
+  ContentType,
+  DiscriminatorObject,
+  Document,
+  HttpMethod,
+  MediaTypeObject,
+  Operation,
+  ReferenceObject,
+  ResponseObject,
+  SchemaObject,
+} from './types.ts'
+export { HttpMethods } from './types.ts'