@kubb/adapter-oas 5.0.0-beta.6 → 5.0.0-beta.60

package/src/stream.ts

@@ -0,0 +1,283 @@
+import { containsCircularRef, findCircularSchemas } from '@kubb/ast/utils'
+import { ast } from '@kubb/core'
+import { SCHEMA_REF_PREFIX } from './constants.ts'
+import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
+import { getOperations } from './operation.ts'
+import type { SchemaParser } from './parser.ts'
+import { resolveServerUrl } from './resolvers.ts'
+import { reportSchemaDiagnostics } from './schemaDiagnostics.ts'
+import type { DiscriminatorTarget } from './discriminator.ts'
+import type { AdapterOas, Document, SchemaObject } from './types.ts'
+
+export type PreScanResult = {
+  refAliasMap: Map<string, ast.SchemaNode>
+  enumNames: Array<string>
+  circularNames: Array<string>
+  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+  dedupePlan: ast.DedupePlan | null
+}
+
+/**
+ * Builds the deduplication plan from the already-parsed top-level schema nodes plus a
+ * single extra parse pass over operations (so duplicates in request/response bodies are seen).
+ *
+ * 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.
+ */
+function createDedupePlan({
+  schemaNodes,
+  operationNodes,
+  schemaNames,
+  circularNames,
+}: {
+  schemaNodes: Array<ast.SchemaNode>
+  operationNodes: Array<ast.OperationNode>
+  schemaNames: Array<string>
+  circularNames: Array<string>
+}): ast.DedupePlan {
+  const circularSchemas = new Set(circularNames)
+  const usedNames = new Set(schemaNames)
+
+  return ast.buildDedupePlan([...schemaNodes, ...operationNodes], {
+    isCandidate: (node) => {
+      if (node.type === 'enum') return true
+      if (node.type !== 'object') return false
+      // Skip object shapes that are part of a circular chain, hoisting them would break the cycle.
+      if (node.name && circularSchemas.has(node.name)) return false
+      return !containsCircularRef(node, { circularSchemas })
+    },
+    nameFor: (node) => {
+      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
+    },
+    refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`,
+  })
+}
+
+/**
+ * Reads the server URL from the document's `servers` array at `serverIndex`,
+ * interpolating any `serverVariables` into the URL template.
+ *
+ * Returns `null` when `serverIndex` is omitted or out of range.
+ *
+ * @example Resolve the first server
+ * `resolveBaseUrl({ document, serverIndex: 0 })`
+ *
+ * @example Override a path variable
+ * `resolveBaseUrl({ document, serverIndex: 0, serverVariables: { version: 'v2' } })`
+ */
+export function resolveBaseUrl({
+  document,
+  serverIndex,
+  serverVariables,
+}: {
+  document: Document
+  serverIndex?: number
+  serverVariables?: Record<string, string>
+}): string | null {
+  const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
+  return server?.url ? resolveServerUrl(server, serverVariables) : null
+}
+
+/**
+ * Parses every schema once to build the lookup structures that streaming needs upfront.
+ *
+ * Three things happen in this single pass:
+ * - `refAliasMap` records schemas that are pure `$ref` aliases so the streaming pass can inline them.
+ * - `enumNames` collects the names of every enum schema so plugins skip re-scanning the stream.
+ * - `circularNames` runs cycle detection, which requires all nodes in memory simultaneously.
+ *   The `allNodes` array is local and drops out of scope as soon as this function returns.
+ *
+ * After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
+ * Both are proportional to the number of aliases or discriminator parents, not total schema count.
+ *
+ * Each schema is parsed again during the streaming pass. This is intentional.
+ * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
+ *
+ * @example
+ * ```ts
+ * const { refAliasMap, enumNames, circularNames } = preScan({
+ *   schemas,
+ *   parseSchema,
+ *   parserOptions,
+ *   discriminator: 'strict',
+ * })
+ * ```
+ */
+export function preScan({
+  schemas,
+  parseSchema,
+  parseOperation,
+  document,
+  parserOptions,
+  discriminator,
+  dedupe,
+}: {
+  schemas: Record<string, SchemaObject>
+  parseSchema: (entry: { schema: SchemaObject; name: string }, options: ast.ParserOptions) => ast.SchemaNode
+  parseOperation: SchemaParser['parseOperation']
+  document: Document
+  parserOptions: ast.ParserOptions
+  discriminator: AdapterOas['options']['discriminator']
+  dedupe: boolean
+}): PreScanResult {
+  const allNodes: Array<ast.SchemaNode> = []
+  const refAliasMap = new Map<string, ast.SchemaNode>()
+  const enumNames: Array<string> = []
+  const discriminatorParentNodes: Array<ast.SchemaNode> = []
+
+  for (const [name, schema] of Object.entries(schemas)) {
+    const node = parseSchema({ schema, name }, parserOptions)
+    allNodes.push(node)
+    reportSchemaDiagnostics({ node, name })
+    if (node.type === 'ref' && node.name && node.name !== name) {
+      refAliasMap.set(name, node)
+    }
+    if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) {
+      enumNames.push(node.name)
+    }
+    if (discriminator === 'inherit' && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) {
+      discriminatorParentNodes.push(node)
+    }
+  }
+
+  const circularNames = [...findCircularSchemas(allNodes)]
+  const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
+
+  let dedupePlan: ast.DedupePlan | null = null
+  if (dedupe) {
+    // One extra parse pass over operations so duplicates in request/response bodies are seen.
+    // Reuses the already-parsed `allNodes` for schemas, no second schema parse.
+    const operationNodes: Array<ast.OperationNode> = []
+    for (const operation of getOperations(document)) {
+      const operationNode = parseOperation(parserOptions, operation)
+      if (operationNode) operationNodes.push(operationNode)
+    }
+
+    dedupePlan = createDedupePlan({ schemaNodes: allNodes, operationNodes, schemaNames: Object.keys(schemas), circularNames })
+
+    for (const definition of dedupePlan.hoisted) {
+      if (definition.type === 'enum' && definition.name) enumNames.push(definition.name)
+    }
+  }
+
+  // Enum names that duplicate an earlier schema's content are never emitted, so they are not
+  // advertised to plugins either.
+  const aliasNames = dedupePlan?.aliasNames
+  const emittedEnumNames = aliasNames && aliasNames.size > 0 ? enumNames.filter((name) => !aliasNames.has(name)) : enumNames
+
+  return { refAliasMap, enumNames: emittedEnumNames, circularNames, discriminatorChildMap, dedupePlan }
+}
+
+/**
+ * Creates a lazy `InputNode<true>` from already-resolved adapter state.
+ *
+ * The schema and operation iterables each start a fresh parse pass on every
+ * `[Symbol.asyncIterator]()` call. This lets multiple plugins consume the same
+ * stream object independently without sharing a cursor or holding all nodes in memory.
+ *
+ * Ref aliases in `refAliasMap` are inlined during iteration: an alias entry is replaced
+ * with its target's parsed node (but keeps the alias name) so plugins never receive bare `ref` nodes.
+ *
+ * @example
+ * ```ts
+ * const streamNode = createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, meta })
+ * for await (const schema of streamNode.schemas) {
+ *   // each call to for-await restarts from the first schema
+ * }
+ * ```
+ */
+export function createInputStream({
+  schemas,
+  parseSchema,
+  parseOperation,
+  document,
+  parserOptions,
+  refAliasMap,
+  discriminatorChildMap,
+  dedupePlan,
+  meta,
+}: {
+  schemas: Record<string, SchemaObject>
+  parseSchema: SchemaParser['parseSchema']
+  parseOperation: SchemaParser['parseOperation']
+  document: Document
+  parserOptions: ast.ParserOptions
+  refAliasMap: Map<string, ast.SchemaNode>
+  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+  dedupePlan: ast.DedupePlan | null
+  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
+  // duplicates are collapsed while the schema's own root is preserved.
+  const rewriteTopLevelSchema = (node: ast.SchemaNode): ast.SchemaNode => {
+    if (!dedupePlan) return node
+
+    const canonical = dedupePlan.canonicalBySignature.get(ast.signatureOf(node))
+    if (canonical && canonical.name !== node.name) {
+      return ast.factory.createSchema({
+        type: 'ref',
+        name: node.name ?? null,
+        ref: canonical.ref,
+        description: node.description,
+        deprecated: node.deprecated,
+      })
+    }
+
+    return ast.applyDedupe(node, dedupePlan, true)
+  }
+
+  const schemasIterable: AsyncIterable<ast.SchemaNode> = {
+    [Symbol.asyncIterator]() {
+      return (async function* () {
+        // Hoisted canonical definitions are emitted first so the schema list owns the shared shapes.
+        if (dedupePlan) {
+          for (const definition of dedupePlan.hoisted) yield definition
+        }
+
+        for (const [name, schema] of Object.entries(schemas)) {
+          // A top-level schema whose content duplicates an earlier one is not emitted: every
+          // ref to it is repointed at the first schema with that content, so its model would
+          // be dead code.
+          if (dedupePlan?.aliasNames.has(name)) continue
+
+          // Inline ref aliases: replace the alias entry with its target's parsed node
+          // (keeping the alias name). Skip the first parse entirely for alias entries
+          // since that result is never used.
+          const alias = refAliasMap.get(name)
+          if (alias?.name && schemas[alias.name]) {
+            yield rewriteTopLevelSchema({ ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name })
+            continue
+          }
+
+          const parsed = parseSchema({ schema, name }, parserOptions)
+          const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)!) : parsed
+          yield rewriteTopLevelSchema(node)
+        }
+      })()
+    },
+  }
+
+  const operationsIterable: AsyncIterable<ast.OperationNode> = {
+    [Symbol.asyncIterator]() {
+      return (async function* () {
+        for (const operation of getOperations(document)) {
+          const node = parseOperation(parserOptions, operation)
+          if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan) : node
+        }
+      })()
+    },
+  }
+
+  return ast.factory.createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta })
+}

package/src/types.ts

@@ -1,25 +1,13 @@
-// external packages
-
 import type { AdapterFactoryOptions } from '@kubb/core'
-import { ast } from '@kubb/core'
-import type { Operation as OASOperation } from 'oas/operation'
-import type {
-  DiscriminatorObject as OASDiscriminatorObject,
-  OASDocument,
-  MediaTypeObject as OASMediaTypeObject,
-  ResponseObject as OASResponseObject,
-  SchemaObject as OASSchemaObject,
-} from 'oas/types'
-import type { OpenAPIV3 } from 'openapi-types'
+import type { ast } from '@kubb/core'
+import type { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema'
+import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+import type { Operation } from './operation.ts'
 
-/**
- * Re-exports of `openapi-types` for use by adapter consumers.
- */
-export type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
+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
@@ -41,7 +29,18 @@ export type ContentType = 'application/json' | (string & {})
  * }
  * ```
  */
-export type SchemaObject = OASSchemaObject & {
+export type SchemaObject = {
+  externalDocs?: unknown
+  xml?: unknown
+  $schema?: string
+  deprecated?: boolean
+  example?: unknown
+  examples?: Array<unknown>
+  nullable?: boolean
+  readOnly?: boolean
+  writeOnly?: boolean
+  discriminator?: DiscriminatorObject
+  'x-readme-ref-name'?: string
   /**
    * OAS 3.0 vendor extension: marks a schema as nullable without using `type: ['null', ...]`.
    */
@@ -68,44 +67,35 @@ export type SchemaObject = OASSchemaObject & {
    */
   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)
 
 /**
- * Maps uppercase HTTP method names to lowercase for backwards compatibility.
- *
- * @example
- * ```ts
- * HttpMethods['GET'] // 'get'
- * HttpMethods['POST'] // 'post'
- * ```
+ * HTTP method in the lowercase form an OpenAPI path item uses for its keys.
  */
-export const HttpMethods = Object.fromEntries(Object.entries(ast.httpMethods).map(([lower, upper]) => [upper, lower])) as Record<
-  Uppercase<ast.HttpMethod>,
-  Lowercase<ast.HttpMethod>
->
+export type HttpMethod = Lowercase<ast.HttpMethod>
 
 /**
- * HTTP method as a lowercase string (`'get' | 'post' | ...`).
+ * Normalized OpenAPI document after parsing.
  */
-export type HttpMethod = Lowercase<ast.HttpMethod>
+export type Document = (OpenAPIV3.Document | OpenAPIV3_1.Document) & Record<string, unknown>
 
 /**
- * Normalized OpenAPI document after parsing.
+ * Single operation object (the `get`/`post`/… entry on a path item) plus any vendor extensions.
  */
-export type Document = OASDocument
+export type OperationObject = (OpenAPIV3.OperationObject | OpenAPIV3_1.OperationObject) & Record<string, unknown>
 
 /**
- * API operation extracted from an OpenAPI document.
+ * Path item object holding the operations and shared parameters for a single URL path.
  */
-export type Operation = OASOperation
+export type PathItemObject = OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject
 
 /**
  * Discriminator object for `oneOf`/`anyOf` schemas in OpenAPI.
  */
-export type DiscriminatorObject = OASDiscriminatorObject
+export type DiscriminatorObject = OpenAPIV3.DiscriminatorObject | OpenAPIV3_1.DiscriminatorObject
 
 /**
  * OpenAPI reference object pointing to a schema definition via `$ref`.
@@ -113,18 +103,35 @@ export type DiscriminatorObject = OASDiscriminatorObject
 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
+
+/**
+ * OpenAPI request body object that maps content types to their media type objects.
  */
-export type ResponseObject = OASResponseObject
+export type RequestBodyObject = OpenAPIV3.RequestBodyObject | OpenAPIV3_1.RequestBodyObject
 
 /**
  * OpenAPI media type object that maps a content-type string to its schema.
  */
-export type MediaTypeObject = OASMediaTypeObject
+export type MediaTypeObject = OpenAPIV3.MediaTypeObject | OpenAPIV3_1.MediaTypeObject
+
+/**
+ * OpenAPI parameter object, narrowed so `in` is always one of the four valid locations.
+ */
+export type ParameterObject = {
+  in: 'cookie' | 'header' | 'path' | 'query'
+} & (OpenAPIV3.ParameterObject | OpenAPIV3_1.ParameterObject)
+
+/**
+ * OpenAPI server object describing a base URL and its `{variable}` substitutions.
+ */
+export type ServerObject = OpenAPIV3.ServerObject | OpenAPIV3_1.ServerObject
 
 /**
- * Configuration options for the OpenAPI adapter.
- * Controls spec validation, content-type selection, and server URL resolution.
+ * Configuration for the OpenAPI adapter: spec validation, content-type selection,
+ * server URL resolution, and how schema types are derived.
  *
  * @example
  * ```ts
@@ -138,23 +145,28 @@ export type MediaTypeObject = OASMediaTypeObject
  */
 export type AdapterOasOptions = {
   /**
-   * Validate the OpenAPI spec before parsing.
+   * Validate the OpenAPI spec with `@readme/openapi-parser` before parsing.
+   * Set to `false` only when you have a known-invalid spec you still want to
+   * generate from.
+   *
    * @default true
    */
   validate?: boolean
   /**
-   * Preferred content-type used when extracting request/response schemas.
-   * Defaults to the first valid JSON media type found in the spec.
+   * Preferred media type when an operation defines several. Defaults to the
+   * first JSON-compatible media type found in the spec.
    */
   contentType?: ContentType
   /**
-   * Index into `oas.api.servers` for computing `baseURL`.
-   * `0` → first server, `1` → second server. Omit to leave `baseURL` undefined.
+   * Index into the `servers` array from your OpenAPI spec. Used to compute the
+   * base URL for plugins that need it. Most projects pick `0` for the primary
+   * server. Omit to leave `baseURL` undefined.
    */
   serverIndex?: number
   /**
    * Override values for `{variable}` placeholders in the selected server URL.
-   * Only used when `serverIndex` is set.
+   * Only used when `serverIndex` is set. Variables you do not provide use
+   * their `default` value from the spec.
    *
    * @example
    * ```ts
@@ -165,12 +177,28 @@ export type AdapterOasOptions = {
    */
   serverVariables?: Record<string, string>
   /**
-   * How the discriminator field is interpreted.
-   * - `'strict'`  — uses `oneOf` schemas as written in the spec.
-   * - `'inherit'` — propagates discriminator values into child schemas from `discriminator.mapping`.
+   * How the `discriminator` field on `oneOf`/`anyOf` schemas is interpreted.
+   * - `'strict'` child schemas stay exactly as written. The discriminator
+   *   narrows types at the call site but child shapes are not modified.
+   * - `'inherit'` Kubb propagates the discriminator property as a literal
+   *   value into each child schema, so each branch's discriminator field is
+   *   precisely typed.
+   *
    * @default 'strict'
    */
   discriminator?: 'strict' | 'inherit'
+  /**
+   * Collapse structurally identical schemas and enums into a single shared definition.
+   *
+   * 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, 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
+   */
+  dedupe?: boolean
 } & Partial<ast.ParserOptions>
 
 /**
@@ -182,6 +210,7 @@ export type AdapterOasResolvedOptions = {
   serverIndex: AdapterOasOptions['serverIndex']
   serverVariables: AdapterOasOptions['serverVariables']
   discriminator: NonNullable<AdapterOasOptions['discriminator']>
+  dedupe: NonNullable<AdapterOasOptions['dedupe']>
   dateType: NonNullable<AdapterOasOptions['dateType']>
   integerType: NonNullable<AdapterOasOptions['integerType']>
   unknownType: NonNullable<AdapterOasOptions['unknownType']>