@kubb/oas 4.33.4 → 4.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.33.4",
+  "version": "4.34.0",
   "description": "OpenAPI Specification (OAS) utilities and helpers for Kubb, providing parsing, normalization, and manipulation of OpenAPI/Swagger schemas.",
   "keywords": [
     "openapi",
@@ -52,20 +52,25 @@
     }
   ],
   "dependencies": {
+    "@kubb/fabric-core": "0.13.3",
     "@redocly/openapi-core": "^2.21.1",
+    "@stoplight/yaml": "^4.3.0",
     "jsonpointer": "^5.0.1",
     "oas": "^31.1.2",
     "oas-normalize": "^16.0.2",
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "4.33.4"
+    "@kubb/ast": "4.34.0",
+    "@kubb/core": "4.34.0"
   },
   "devDependencies": {
-    "@stoplight/yaml": "^4.3.0",
     "@types/swagger2openapi": "^7.0.4",
     "@internals/utils": "0.0.0"
   },
+  "peerDependencies": {
+    "@kubb/fabric-core": "0.13.3"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -75,13 +80,6 @@
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "inlinedDependencies": {
-    "tslib": "2.8.1",
-    "@stoplight/yaml-ast-parser": "0.0.50",
-    "@stoplight/yaml": "4.3.0",
-    "@stoplight/ordered-object-literal": "1.0.5",
-    "@stoplight/types": "14.1.1"
-  },
   "scripts": {
     "build": "tsdown && size-limit",
     "clean": "npx rimraf ./dist",

package/src/Oas.ts

@@ -548,7 +548,17 @@ export class Oas extends BaseOas {
     // Collect schemas from components
     if (includes.includes('schemas')) {
       const componentSchemas = (components?.schemas as Record<string, SchemaObject>) || {}
-      for (const [name, schema] of Object.entries(componentSchemas)) {
+      for (const [name, schemaObject] of Object.entries(componentSchemas)) {
+        // Resolve schema if it's a $ref (can happen when the bundler deduplicates schemas
+        // referenced from multiple external files). Without this, a $ref schema would be
+        // parsed as a reference to itself, generating `z.lazy(() => schemaName)`.
+        let schema = schemaObject
+        if (isReference(schemaObject)) {
+          const resolved = this.get<SchemaObject>(schemaObject.$ref)
+          if (resolved && !isReference(resolved)) {
+            schema = resolved
+          }
+        }
         schemasWithMeta.push({ schema, source: 'schemas', originalName: name })
       }
     }
@@ -559,7 +569,17 @@ export class Oas extends BaseOas {
         const responseObject = response as ResponseObject
         const schema = extractSchemaFromContent(responseObject.content, contentType)
         if (schema) {
-          schemasWithMeta.push({ schema, source: 'responses', originalName: name })
+          // Resolve schema if it's a $ref (can happen when the bundler deduplicates schemas
+          // referenced from multiple external files). Without this, a $ref schema would be
+          // parsed as a reference to itself, generating `z.lazy(() => schemaName)`.
+          let resolvedSchema = schema
+          if (isReference(schema)) {
+            const resolved = this.get<SchemaObject>(schema.$ref)
+            if (resolved && !isReference(resolved)) {
+              resolvedSchema = resolved
+            }
+          }
+          schemasWithMeta.push({ schema: resolvedSchema, source: 'responses', originalName: name })
         }
       }
     }
@@ -570,7 +590,17 @@ export class Oas extends BaseOas {
         const requestObject = request as { content?: Record<string, unknown> }
         const schema = extractSchemaFromContent(requestObject.content, contentType)
         if (schema) {
-          schemasWithMeta.push({ schema, source: 'requestBodies', originalName: name })
+          // Resolve schema if it's a $ref (can happen when the bundler deduplicates schemas
+          // referenced from multiple external files). Without this, a $ref schema would be
+          // parsed as a reference to itself, generating `z.lazy(() => schemaName)`.
+          let resolvedSchema = schema
+          if (isReference(schema)) {
+            const resolved = this.get<SchemaObject>(schema.$ref)
+            if (resolved && !isReference(resolved)) {
+              resolvedSchema = resolved
+            }
+          }
+          schemasWithMeta.push({ schema: resolvedSchema, source: 'requestBodies', originalName: name })
         }
       }
     }

package/src/constants.ts

@@ -0,0 +1,88 @@
+import type { MediaType, SchemaType } from '@kubb/ast/types'
+import type { HttpMethods as OASHttpMethods } from 'oas/types'
+
+/**
+ * JSON Schema keywords that indicate structural composition.
+ * Used when deciding whether an inline `allOf` fragment can be safely flattened
+ * into its parent (fragments containing any of these keys must not be inlined).
+ */
+export const STRUCTURAL_KEYS = new Set<string>(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'])
+
+/**
+ * Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
+ *
+ * Only formats that require a type different from the raw OAS `type` are listed here.
+ * `int64`, `date-time`, `date`, and `time` are handled separately because their
+ * output depends on runtime parser options and cannot live in a static map.
+ *
+ * Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — not semantically accurate,
+ * but `'url'` is the closest supported scalar type in the Kubb AST.
+ */
+export const FORMAT_MAP = {
+  uuid: 'uuid',
+  email: 'email',
+  'idn-email': 'email',
+  uri: 'url',
+  'uri-reference': 'url',
+  url: 'url',
+  ipv4: 'url',
+  ipv6: 'url',
+  hostname: 'url',
+  'idn-hostname': 'url',
+  binary: 'blob',
+  byte: 'blob',
+  // Numeric formats — format is more specific than type, so these override type.
+  // see https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
+  int32: 'integer',
+  float: 'number',
+  double: 'number',
+} as const satisfies Record<string, SchemaType>
+
+/**
+ * Exhaustive list of media types that Kubb recognizes.
+ * Kept as a module-level constant to avoid re-allocating the array on every call.
+ */
+export const KNOWN_MEDIA_TYPES = [
+  '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 satisfies ReadonlyArray<MediaType>
+
+/**
+ * Vendor extension keys used by various spec generators to attach human-readable
+ * labels to enum values. Checked in priority order: the first key found wins.
+ */
+export const ENUM_EXTENSION_KEYS = ['x-enumNames', 'x-enum-varnames'] as const
+
+/**
+ * Canonical HTTP method names used throughout the Kubb OAS layer.
+ * Keys are uppercase (as used in generated code); values are the lowercase
+ * strings that the `oas` library uses internally.
+ * @deprecated use httpMethods from @kubb/ast
+ */
+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>

package/src/index.ts

@@ -1,3 +1,4 @@
+export { ENUM_EXTENSION_KEYS, FORMAT_MAP, httpMethods, KNOWN_MEDIA_TYPES, STRUCTURAL_KEYS } from './constants.ts'
 export { KUBB_INLINE_REF_PREFIX, Oas } from './Oas.ts'
 export { resolveServerUrl } from './resolveServerUrl.ts'
 export * from './types.ts'