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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.62",
+  "version": "5.0.0-beta.63",
   "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.62",
-    "@kubb/core": "5.0.0-beta.62"
+    "@kubb/ast": "5.0.0-beta.63",
+    "@kubb/core": "5.0.0-beta.63"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",

package/src/adapter.ts

@@ -10,7 +10,7 @@ import { collect, narrowSchema } from '@kubb/ast'
 import { extractRefName } from '@kubb/ast/utils'
 
 /**
- * Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
+ * The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
  */
 export const adapterOasName = 'oas' satisfies AdapterOas['name']
 

package/src/constants.ts

@@ -5,10 +5,9 @@ import { ast } from '@kubb/core'
  *
  * @example
  * ```ts
- * import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+ * import { DEFAULT_PARSER_OPTIONS, parseOas } from '@kubb/adapter-oas'
  *
- * const parser = createOasParser(oas)
- * const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+ * const { root } = parseOas(document, { ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
  * ```
  */
 export const DEFAULT_PARSER_OPTIONS = {
@@ -68,13 +67,21 @@ export const MERGE_DEFAULT_VERSION = '1.0.0' as const
  */
 export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
 
+/**
+ * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+ * `int64` and the date/time family. Keep this in sync with the `convertFormat`
+ * special-cases in `parser.ts`. `isHandledFormat` reads it so the
+ * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+ */
+export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
+
 /**
  * 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.
+ * 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.
  *
  * @example
  * ```ts
@@ -85,14 +92,6 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  * formatMap['float']  // 'number'
  * ```
  */
-/**
- * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
- * `int64` and the date/time family. Keep this in sync with the `convertFormat`
- * special-cases in `parser.ts`. `isHandledFormat` reads it so the
- * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
- */
-export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
-
 export const formatMap = {
   uuid: 'uuid',
   email: 'email',

package/src/dedupe.ts

@@ -0,0 +1,237 @@
+import { containsCircularRef, extractRefName } from '@kubb/ast/utils'
+import { ast } from '@kubb/core'
+import { SCHEMA_REF_PREFIX } from './constants.ts'
+
+/**
+ * The destination a deduplicated shape points at: the shared schema name and the
+ * synthetic `$ref` path stored on the generated `ref` nodes.
+ */
+type Target = {
+  name: string
+  ref: string
+}
+
+/**
+ * The result of {@link plan}: the shared definitions to prepend to the schema list, plus the
+ * rewriting behavior that repoints duplicate shapes at their shared target. The lookup maps stay
+ * private to the closure, so callers interact with one object instead of three collections.
+ */
+export type Plan = {
+  /**
+   * New top-level schema definitions created for inline shapes that had no existing named
+   * component. Nested duplicates inside each definition are already collapsed.
+   */
+  extracted: Array<ast.SchemaNode>
+  /**
+   * Rewrites an operation or nested schema, replacing every duplicate sub-schema with a `ref` to
+   * its shared target. Replacing a node prunes its subtree, so nested duplicates inside a replaced
+   * shape are not visited again. A `ref` to a duplicate top-level schema is repointed at the first
+   * schema with the same content.
+   */
+  apply<T extends ast.Node>(node: T): T
+  /**
+   * Rewrites a top-level schema. A schema whose content duplicates a different shared one becomes a
+   * `ref` alias to it (keeping its own name and docs). Otherwise its nested duplicates collapse
+   * while its own root is preserved.
+   */
+  applyTopLevel(node: ast.SchemaNode): ast.SchemaNode
+  /**
+   * Whether a top-level name duplicates an earlier schema with the same content. Such a schema is
+   * never emitted, since every reference to it is repointed at the first schema with that content.
+   */
+  isAlias(name: string): boolean
+}
+
+/**
+ * Runtime state {@link plan} reads from the current parse: schema names that take part in a
+ * circular chain (never extracted, extracting them would break the cycle) and the names already in
+ * use (so extracted definitions resolve collisions).
+ */
+export type DedupeContext = {
+  circularSchemas: ReadonlySet<string>
+  usedNames: Set<string>
+}
+
+/**
+ * Minimum occurrences before a shape is deduplicated.
+ */
+const MIN_OCCURRENCES = 2
+
+/**
+ * Builds the shared `ref` replacement for a duplicate occurrence, carrying the
+ * usage-slot and documentation fields that are not part of the shared type.
+ */
+function createRefNode(node: ast.SchemaNode, target: Target): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'ref',
+    name: target.name,
+    ref: target.ref,
+    optional: node.optional,
+    nullish: node.nullish,
+    readOnly: node.readOnly,
+    writeOnly: node.writeOnly,
+    deprecated: node.deprecated,
+    description: node.description,
+    default: node.default,
+    example: node.example,
+  })
+}
+
+/**
+ * Strips usage-slot flags from an extracted definition and applies its name.
+ * A standalone definition is never optional, so `optional`/`nullish` are cleared.
+ */
+function cleanDefinition(node: ast.SchemaNode, name: string): ast.SchemaNode {
+  return { ...node, name, optional: undefined, nullish: undefined }
+}
+
+/**
+ * Returns `true` when a node is eligible for deduplication. Only enums and objects qualify, and
+ * object shapes that take part in a circular chain are rejected so recursive structures are not
+ * extracted (which would break the cycle).
+ */
+function isCandidate(node: ast.SchemaNode, circularSchemas: ReadonlySet<string>): boolean {
+  if (node.type === 'enum') return true
+  if (node.type !== 'object') return false
+  if (node.name && circularSchemas.has(node.name)) return false
+  return !containsCircularRef(node, { circularSchemas })
+}
+
+/**
+ * Produces the name for an inline shape with no existing named component, resolving
+ * collisions against `usedNames`. Returns `null` for an unnamed shape, which stays inline.
+ */
+function nameFor(node: ast.SchemaNode, usedNames: Set<string>): string | null {
+  const base = node.name
+  if (!base) return null
+
+  let name = base
+  let counter = 2
+  while (usedNames.has(name)) {
+    name = `${base}${counter++}`
+  }
+  usedNames.add(name)
+  return name
+}
+
+/**
+ * Scans a forest of schema and operation nodes and produces a {@link Plan}.
+ *
+ * A shape that occurs at least {@link MIN_OCCURRENCES} times is deduplicated: if any occurrence is
+ * a named top-level schema, the first one becomes the target (so other top-level duplicates and
+ * inline copies turn into references to it). Other top-level names with the same content are
+ * recorded as aliases. Otherwise a new definition is extracted using {@link nameFor}. The returned
+ * plan rewrites nodes against those decisions.
+ *
+ * @example
+ * ```ts
+ * const dedupePlan = plan([...schemaNodes, ...operationNodes], { circularSchemas, usedNames })
+ * ```
+ */
+export function plan(roots: ReadonlyArray<ast.Node>, context: DedupeContext): Plan {
+  const { circularSchemas, usedNames } = context
+
+  const topLevelNodes = new Set<ast.SchemaNode>()
+
+  type Group = {
+    count: number
+    representative: ast.SchemaNode
+    topLevelNames: Array<string>
+  }
+  const groups = new Map<string, Group>()
+
+  for (const root of roots) {
+    if (root.kind === 'Schema') topLevelNodes.add(root)
+    for (const schemaNode of ast.collect<ast.SchemaNode>(root, { schema: (node) => node })) {
+      if (!isCandidate(schemaNode, circularSchemas)) continue
+
+      const signature = ast.signatureOf(schemaNode)
+      const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name
+      const group = groups.get(signature)
+      if (group) {
+        group.count++
+        if (isTopLevel) group.topLevelNames.push(schemaNode.name!)
+      } else {
+        groups.set(signature, { count: 1, representative: schemaNode, topLevelNames: isTopLevel ? [schemaNode.name!] : [] })
+      }
+    }
+  }
+
+  const bySignature = new Map<string, Target>()
+  const byName = new Map<string, Target>()
+  const pendingExtractions: Array<{ name: string; representative: ast.SchemaNode }> = []
+
+  for (const [signature, group] of groups) {
+    if (group.count < MIN_OCCURRENCES) continue
+
+    const [firstName, ...duplicateNames] = group.topLevelNames
+    if (firstName) {
+      const target: Target = { name: firstName, ref: `${SCHEMA_REF_PREFIX}${firstName}` }
+      bySignature.set(signature, target)
+      for (const duplicate of duplicateNames) {
+        byName.set(duplicate, target)
+      }
+      continue
+    }
+
+    const name = nameFor(group.representative, usedNames)
+    if (!name) continue
+
+    bySignature.set(signature, { name, ref: `${SCHEMA_REF_PREFIX}${name}` })
+    pendingExtractions.push({ name, representative: group.representative })
+  }
+
+  // Rewrites a node against the resolved targets. `skipRootMatch` keeps a definition's own root from
+  // turning into a reference to itself. Nested duplicates are still collapsed.
+  function rewrite<T extends ast.Node>(node: T, skipRootMatch: boolean): T {
+    if (bySignature.size === 0 && byName.size === 0) return node
+
+    const root = node
+
+    return ast.transform(node, {
+      schema(schemaNode) {
+        if (schemaNode.type === 'ref') {
+          const refName = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name
+          const target = refName ? byName.get(refName) : undefined
+
+          return target ? { ...schemaNode, name: target.name, ref: target.ref } : undefined
+        }
+
+        if (skipRootMatch && schemaNode === root) return undefined
+
+        const target = bySignature.get(ast.signatureOf(schemaNode))
+        if (!target) return undefined
+
+        return createRefNode(schemaNode, target)
+      },
+    }) as T
+  }
+
+  // Build extracted definitions only after every target name is known, so nested
+  // duplicates inside a definition also resolve to refs.
+  const extracted = pendingExtractions.map(({ name, representative }) => cleanDefinition(rewrite(representative, true), name))
+
+  return {
+    extracted,
+    apply<T extends ast.Node>(node: T): T {
+      return rewrite(node, false)
+    },
+    applyTopLevel(node: ast.SchemaNode): ast.SchemaNode {
+      const target = bySignature.get(ast.signatureOf(node))
+      if (target && target.name !== node.name) {
+        return ast.factory.createSchema({
+          type: 'ref',
+          name: node.name ?? null,
+          ref: target.ref,
+          description: node.description,
+          deprecated: node.deprecated,
+        })
+      }
+
+      return rewrite(node, true)
+    },
+    isAlias(name: string): boolean {
+      return byName.has(name)
+    },
+  }
+}

package/src/dialect.ts

@@ -1,27 +1,9 @@
 import { ast } from '@kubb/core'
+import { plan } from './dedupe.ts'
 import { isDiscriminator, isNullable, isReference } from './guards.ts'
 import { resolveRef } from './refs.ts'
 import type { SchemaObject } from './types.ts'
 
-/**
- * Derives a schema's `optional`/`nullish` flags from a parent's `required` value and the
- * schema's own `nullable`. How "required" and "nullable" combine is OpenAPI-specific, so it
- * lives in the dialect.
- *
- * - Non-required + non-nullable → `optional: true`.
- * - Non-required + nullable → `nullish: true`.
- * - Required → both flags cleared.
- */
-function optionality(schema: ast.SchemaNode, required: boolean): ast.SchemaNode {
-  const nullable = schema.nullable ?? false
-
-  return {
-    ...schema,
-    optional: !required && !nullable ? true : undefined,
-    nullish: !required && nullable ? true : undefined,
-  }
-}
-
 /**
  * The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
  *
@@ -49,8 +31,8 @@ export const oasDialect = ast.defineDialect({
     isDiscriminator,
     isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
     resolveRef,
-    optionality,
   },
+  dedupe: { plan },
 })
 
 /**

package/src/discriminator.ts

@@ -7,7 +7,7 @@ export type DiscriminatorTarget = {
 }
 
 /**
- * Builds a map of child schema names → discriminator patch data by scanning the given
+ * Maps each child schema name to its discriminator patch data by scanning the given
  * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
  *
  * The streaming path calls this on a small pre-parsed subset of schemas (only the

package/src/factory.ts

@@ -18,7 +18,7 @@ export type ValidateDocumentOptions = {
 }
 
 /**
- * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ * Loads and bundles an OpenAPI document, returning the raw `Document`.
  *
  * Accepts a file path string or an already-parsed document object. File paths and URLs are
  * bundled via `api-ref-bundler`, hoisting external file schemas into named `components.schemas`

package/src/mime.ts

@@ -1,9 +1,8 @@
 /**
  * MIME type fragments that mark a media type as JSON-like.
  *
- * Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
- * JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
- * `application/vnd.api+json`.
+ * A content type is JSON when it contains any of these substrings. The `+json` entry catches
+ * structured-syntax suffixes such as `application/vnd.api+json`.
  */
 const jsonMimeFragments = ['application/json', 'application/x-json', 'text/json', 'text/x-json', '+json'] as const
 

package/src/operation.ts

@@ -125,8 +125,8 @@ export function getRequestContent({
 }
 
 /**
- * Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
- * matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+ * Returns the primary request content type. Prefers a JSON-like media type (the last one wins
+ * when several are declared), then the first declared one, defaulting to `'application/json'`.
  */
 export function getRequestContentType({ document, operation }: OperationContext): string {
   const content = getRequestBodyContent({ document, operation })

package/src/parser.ts

@@ -606,17 +606,14 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
           const schemaNode = nameEnums(propNode, { parentName: name, propName, enumSuffix: options.enumSuffix })
 
-          return ast.factory.createProperty(
-            {
-              name: propName,
-              schema: {
-                ...schemaNode,
-                nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
-              },
-              required,
+          return ast.factory.createProperty({
+            name: propName,
+            schema: {
+              ...schemaNode,
+              nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
             },
-            dialect,
-          )
+            required,
+          })
         })
       : []
 
@@ -894,18 +891,15 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ? parseSchema({ schema: param['schema'] as SchemaObject, name: schemaName }, options)
       : ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType)! })
 
-    return ast.factory.createParameter(
-      {
-        name: paramName,
-        in: param['in'] as ast.ParameterLocation,
-        schema: {
-          ...schema,
-          description: (param['description'] as string | undefined) ?? schema.description,
-        },
-        required,
+    return ast.factory.createParameter({
+      name: paramName,
+      in: param['in'] as ast.ParameterLocation,
+      schema: {
+        ...schema,
+        description: (param['description'] as string | undefined) ?? schema.description,
       },
-      dialect,
-    )
+      required,
+    })
   }
 
   /**
@@ -984,7 +978,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       return [
         ast.factory.createContent({
           contentType: ct,
-          schema: dialect.schema.optionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
+          schema: ast.optionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
           keysToOmit: collectPropertyKeysByFlag(schema, 'readOnly'),
         }),
       ]

package/src/refs.ts

@@ -7,12 +7,13 @@ const _refCache = new WeakMap<Document, Map<string, unknown>>()
 /**
  * Resolves a local JSON pointer reference from a document.
  *
- * Accepts `#/...` refs. Returns `null` for empty or non-local refs.
- * Throws when the pointer cannot be resolved.
+ * 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') // SchemaObject | null
+ * resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
  * ```
  */
 export function resolveRef<T = unknown>(document: Document, $ref: string): T | null {

package/src/resolvers.ts

@@ -59,9 +59,9 @@ export function getSchemaType(format: string): ast.SchemaType | null {
 }
 
 /**
- * Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
- * `specialCasedFormats` `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
+ * 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 {
@@ -86,7 +86,7 @@ export type OperationsOptions = {
 /**
  * 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.
- * `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
+ * Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
  *
  * @example
  * ```ts
@@ -220,7 +220,8 @@ export function getRequestSchema(document: Document, operation: Operation, optio
 type SchemaSourceMode = 'schemas' | 'responses' | 'requestBodies'
 
 /**
- * A schema annotated with its component section source and original name. Used by `resolveNameCollisions` for cross-source collision resolution.
+ * A schema annotated with its component section source and original name. `getSchemas` uses this
+ * to resolve name collisions across sources.
  */
 type SchemaWithMetadata = {
   schema: SchemaObject
@@ -234,6 +235,10 @@ export type GetSchemasOptions = {
 
 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>
 }
 
@@ -248,7 +253,10 @@ export type GetSchemasResult = {
  * ```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
  * ```