@kubb/adapter-oas 5.0.0-alpha.23 → 5.0.0-alpha.25

package/src/constants.ts

@@ -56,7 +56,8 @@ 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`, `ipv6`, and `hostname` map to `'url'` as the closest supported scalar.
+ * 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
@@ -74,8 +75,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',

package/src/factory.ts

@@ -65,7 +65,10 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
  * ```
  */
 export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
-  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { enablePaths: false, canBundle: false })))
+  const documents: Document[] = []
+  for (const p of pathOrApi) {
+    documents.push(await parseDocument(p, { enablePaths: false, canBundle: false }))
+  }
 
   if (documents.length === 0) {
     throw new Error('No OAS documents provided for merging.')

package/src/parser.ts

@@ -103,22 +103,42 @@ function createSchemaParser(ctx: OasParserContext) {
 
   // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
 
+  /**
+   * Tracks `$ref` paths that are currently being resolved to prevent infinite
+   * recursion when schemas contain circular references (e.g. `Pet → parent → Pet`).
+   */
+  const resolvingRefs = new Set<string>()
+
   /**
    * Converts a `$ref` schema into a `RefSchemaNode`.
+   *
+   * The resolved schema is stored in `node.schema`. Usage-site sibling fields
+   * (description, readOnly, nullable, etc.) are stored directly on the ref node.
+   * Use `syncSchemaRef(node)` in printers to get a merged view of both.
+   * Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
    */
-  function convertRef({ schema, nullable, defaultValue }: SchemaContext): SchemaNode {
+  function convertRef({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
+    let resolvedSchema: SchemaNode | undefined
+    const refPath = schema.$ref
+    if (refPath && !resolvingRefs.has(refPath)) {
+      try {
+        const referenced = resolveRef<SchemaObject>(document, refPath)
+        if (referenced) {
+          resolvingRefs.add(refPath)
+          resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
+          resolvingRefs.delete(refPath)
+        }
+      } catch {
+        // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
+      }
+    }
+
     return createSchema({
+      ...buildSchemaNode(schema, name, nullable, defaultValue),
       type: 'ref',
       name: extractRefName(schema.$ref!),
       ref: schema.$ref,
-      nullable,
-      description: schema.description,
-      deprecated: schema.deprecated,
-      readOnly: schema.readOnly,
-      writeOnly: schema.writeOnly,
-      pattern: schema.type === 'string' ? schema.pattern : undefined,
-      example: schema.example,
-      default: defaultValue,
+      schema: resolvedSchema,
     })
   }
 
@@ -365,7 +385,16 @@ function createSchemaParser(ctx: OasParserContext) {
       return createSchema({ ...base, primitive: specialPrimitive, type: specialType })
     }
     if (specialType === 'url') {
-      return createSchema({ ...base, primitive: 'string' as const, type: 'url' })
+      return createSchema({ ...base, primitive: 'string' as const, type: 'url', min: schema.minLength, max: schema.maxLength })
+    }
+    if (specialType === 'ipv4') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'ipv4' })
+    }
+    if (specialType === 'ipv6') {
+      return createSchema({ ...base, primitive: 'string' as const, type: 'ipv6' })
+    }
+    if (specialType === 'uuid' || specialType === 'email') {
+      return createSchema({ ...base, primitive: 'string' as const, type: specialType, min: schema.minLength, max: schema.maxLength })
     }
 
     return createSchema({ ...base, primitive: specialPrimitive, type: specialType as ScalarSchemaType })
@@ -460,13 +489,13 @@ function createSchemaParser(ctx: OasParserContext) {
       : []
 
     const additionalProperties = schema.additionalProperties
-    let additionalPropertiesNode: SchemaNode | true | undefined
+    let additionalPropertiesNode: SchemaNode | boolean | undefined
     if (additionalProperties === true) {
       additionalPropertiesNode = true
     } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
       additionalPropertiesNode = parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
     } else if (additionalProperties === false) {
-      additionalPropertiesNode = undefined
+      additionalPropertiesNode = false
     } else if (additionalProperties) {
       additionalPropertiesNode = createSchema({ type: typeOptionMap.get(options.unknownType)! })
     }
@@ -490,6 +519,8 @@ function createSchemaParser(ctx: OasParserContext) {
       properties,
       additionalProperties: additionalPropertiesNode,
       patternProperties,
+      minProperties: schema.minProperties,
+      maxProperties: schema.maxProperties,
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
@@ -565,6 +596,7 @@ function createSchemaParser(ctx: OasParserContext) {
       max: schema.maximum,
       exclusiveMinimum: typeof schema.exclusiveMinimum === 'number' ? schema.exclusiveMinimum : undefined,
       exclusiveMaximum: typeof schema.exclusiveMaximum === 'number' ? schema.exclusiveMaximum : undefined,
+      multipleOf: schema.multipleOf,
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }