@kubb/adapter-oas 5.0.0-beta.58 → 5.0.0-beta.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.58",
+  "version": "5.0.0-beta.59",
   "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
@@ -46,8 +46,8 @@
     "api-ref-bundler": "0.5.1",
     "swagger2openapi": "^7.0.8",
     "yaml": "^2.9.0",
-    "@kubb/ast": "5.0.0-beta.58",
-    "@kubb/core": "5.0.0-beta.58"
+    "@kubb/ast": "5.0.0-beta.59",
+    "@kubb/core": "5.0.0-beta.59"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",

package/src/constants.ts

@@ -73,7 +73,7 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  *
  * 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
+ * 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.
  *
  * @example
@@ -126,8 +126,8 @@ export const formatMap = {
 export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
 
 /**
- * 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()`.
+ * Maps the `unknownType`/`emptySchemaType` option string to its `ScalarSchemaType` constant.
+ * A `Map` (over a plain object) lets callers test key membership with `.has()`.
  */
 export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
   ['any', ast.schemaTypes.any],

package/src/discriminator.ts

@@ -90,3 +90,43 @@ export function patchDiscriminatorNode(node: ast.SchemaNode, entry: { propertyNa
 
   return { ...objectNode, properties: newProperties }
 }
+
+/**
+ * Creates a single-property object schema used as a discriminator literal.
+ *
+ * @example
+ * ```ts
+ * createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+ * // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+ * ```
+ */
+export function createDiscriminantNode({ propertyName, value }: { propertyName: string; value: string }): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'object',
+    primitive: 'object',
+    properties: [
+      ast.factory.createProperty({
+        name: propertyName,
+        schema: ast.factory.createSchema({
+          type: 'enum',
+          primitive: 'string',
+          enumValues: [value],
+        }),
+        required: true,
+      }),
+    ],
+  })
+}
+
+/**
+ * Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
+ *
+ * @example
+ * ```ts
+ * findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
+ * ```
+ */
+export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
+  if (!mapping || !ref) return null
+  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
+}

package/src/parser.ts

@@ -1,8 +1,9 @@
 import { pascalCase } from '@internals/utils'
-import { childName, enumPropName, extractRefName, findDiscriminator } from '@kubb/ast/utils'
+import { childName, enumPropName, extractRefName } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
 import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, SCHEMA_REF_PREFIX, typeOptionMap } from './constants.ts'
 import { oasDialect, type OasDialect } from './dialect.ts'
+import { createDiscriminantNode, findDiscriminator } from './discriminator.ts'
 import { getOperationId, getOperations, getRequestContentType, getResponseByStatusCode, getResponseStatusCodes } from './operation.ts'
 import {
   buildSchemaNode,
@@ -66,11 +67,17 @@ type SchemaContext = {
  * that is not convertible falls through to plain `type` handling).
  */
 type SchemaRule = {
-  /** Identifies the rule when reading the table or debugging which branch ran. */
+  /**
+   * Identifies the rule when reading the table or debugging which branch ran.
+   */
   name: string
-  /** Returns `true` when this rule is responsible for the given context. */
+  /**
+   * Returns `true` when this rule is responsible for the given context.
+   */
   match: (context: SchemaContext) => boolean
-  /** Produces a node for the context, or `null` to fall through to the next rule. */
+  /**
+   * Produces a node for the context, or `null` to fall through to the next rule.
+   */
   convert: (context: SchemaContext) => ast.SchemaNode | null
 }
 
@@ -78,9 +85,9 @@ type SchemaRule = {
  * Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
  *
  * This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
- * from the array to its items sub-schema, making them valid for downstream processing.
+ * from the array to its items sub-schema, so they are valid for downstream processing.
  *
- * @note This is a defensive measure for robustness with non-compliant specs.
+ * @note A defensive measure for non-compliant specs.
  */
 function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
@@ -98,7 +105,7 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
  *
  * Returns closures that share mutable state (`resolvingRefs` set for cycle detection).
  * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
- * made possible by hoisting of function declarations.
+ * which works because function declarations hoist.
  *
  * @internal
  */
@@ -264,7 +271,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     }
 
     for (const { propertyName, value } of filteredDiscriminantValues) {
-      allOfMembers.push(ast.factory.createDiscriminantNode({ propertyName, value }))
+      allOfMembers.push(createDiscriminantNode({ propertyName, value }))
     }
 
     return ast.factory.createSchema({
@@ -337,7 +344,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
           members: [
             memberNode,
             narrowedDiscriminatorNode ??
-              ast.factory.createDiscriminantNode({
+              createDiscriminantNode({
                 propertyName: discriminator.propertyName,
                 value: discriminatorValue,
               }),
@@ -1048,10 +1055,11 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 /**
  * Parses a single OpenAPI `SchemaObject` into a `SchemaNode`.
  *
- * Use this for targeted schema parsing when you don't need the full spec.
- * For complete spec parsing, use `parseOas()` instead which handles operations and all schemas together.
+ * Reach for this when you only need one schema, not the whole spec. To parse a full spec
+ * with its operations and schemas, call `parseOas()`.
  *
- * @note Circular schema references are tracked via internal state and resolve appropriately.
+ * @note Internal state tracks `$ref` paths under resolution, so circular schemas stop
+ * recursing instead of looping.
  *
  * @example
  * ```ts
@@ -1072,7 +1080,8 @@ export function parseSchema(
  * Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
  *
  * This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
- * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here,  * the tree is a pure data structure representing all schemas and operations.
+ * that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here.
+ * The tree is a pure data structure of all schemas and operations.
  *
  * Returns the AST root and a `nameMapping` for resolving schema references.
  *

package/src/resolvers.ts

@@ -470,7 +470,7 @@ export function getSchemas(document: Document, { contentType }: GetSchemasOption
 
 /**
  * Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
- * Returns `null` when `dateType: false`, signalling the format should fall through to `string`.
+ * Returns `null` when `dateType: false`, so the format falls through to `string`.
  */
 export function getDateType(
   options: ast.ParserOptions,

package/src/stream.ts

@@ -23,7 +23,7 @@ export type PreScanResult = {
  *
  * Only enums and objects are candidates, and object shapes that reference a circular schema are
  * rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
- * name (collision-resolved against existing component names); shapes without a name stay inline.
+ * name (collision-resolved against existing component names). Shapes without a name stay inline.
  */
 function createDedupePlan({
   schemaNodes,
@@ -218,7 +218,7 @@ export function createInputStream({
   meta: ast.InputMeta
 }): ast.InputNode<true> {
   // Rewrites a top-level schema against the dedupe plan: a structurally identical sibling
-  // becomes a `ref` alias to the canonical one (keeping its own name); otherwise nested
+  // becomes a `ref` alias to the canonical one (keeping its own name). Otherwise nested
   // duplicates are collapsed while the schema's own root is preserved.
   const rewriteTopLevelSchema = (node: ast.SchemaNode): ast.SchemaNode => {
     if (!dedupePlan) return node

package/src/types.ts

@@ -7,8 +7,7 @@ import type { Operation } from './operation.ts'
 export type { Operation }
 
 /**
- * Content-type string for selecting request/response schemas from an OpenAPI spec.
- * Supports `'application/json'` or any other media type.
+ * Media type used to pick a schema from an operation's request or response.
  *
  * @example
  * ```ts
@@ -68,13 +67,13 @@ export type SchemaObject = {
    */
   items?: SchemaObject | ReferenceObject
   /**
-   * Enum values for this schema (narrowed from `unknown[]`).
+   * Allowed values for this schema.
    */
   enum?: Array<string | number | boolean | null>
 } & (OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject | JSONSchema4 | JSONSchema6 | JSONSchema7)
 
 /**
- * HTTP method as a lowercase string (`'get' | 'post' | ...`).
+ * HTTP method in the lowercase form an OpenAPI path item uses for its keys.
  */
 export type HttpMethod = Lowercase<ast.HttpMethod>
 
@@ -104,7 +103,7 @@ export type DiscriminatorObject = OpenAPIV3.DiscriminatorObject | OpenAPIV3_1.Di
 export type ReferenceObject = OpenAPIV3.ReferenceObject
 
 /**
- * OpenAPI response object from a spec that contains schema, status code, and headers.
+ * OpenAPI response object holding the content and headers for one status code.
  */
 export type ResponseObject = OpenAPIV3.ResponseObject | OpenAPIV3_1.ResponseObject
 
@@ -131,9 +130,8 @@ export type ParameterObject = {
 export type ServerObject = OpenAPIV3.ServerObject | OpenAPIV3_1.ServerObject
 
 /**
- * Configuration options for the OpenAPI adapter. Controls spec validation,
- * content-type selection, server URL resolution, and how types are derived
- * from the spec.
+ * Configuration for the OpenAPI adapter: spec validation, content-type selection,
+ * server URL resolution, and how schema types are derived.
  *
  * @example
  * ```ts
@@ -194,9 +192,9 @@ export type AdapterOasOptions = {
    *
    * Duplicated inline shapes (especially enums repeated across many properties) are hoisted
    * into one named schema. Every other occurrence, and any structurally identical top-level
-   * component, becomes a `ref` to it. Equality is shape-only: documentation such as
-   * `description` and `example` is ignored. Enabled by default. Set to `false` to keep every
-   * occurrence inline and produce byte-for-byte identical output to earlier versions.
+   * component, becomes a `ref` to it. Equality is shape-only, so documentation such as
+   * `description` and `example` is ignored. Set to `false` to keep every occurrence inline
+   * and produce byte-for-byte identical output to earlier versions.
    *
    * @default true
    */