@kubb/oas 4.33.5 → 4.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/oas",
-  "version": "4.33.5",
+  "version": "4.35.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.5"
+    "@kubb/ast": "4.35.0",
+    "@kubb/core": "4.35.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/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,7 +1,9 @@
+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'
 export {
+  flattenSchema,
   getDefaultValue,
   isAllOptional,
   isDiscriminator,

package/src/types.ts

@@ -20,30 +20,24 @@ export type contentType = 'application/json' | (string & {})
 
 export type SchemaObject = OASSchemaObject & {
   /**
-   * Oas 3.1 adds support for `x-nullable` to specify that a schema can be null, even if `type` does not include `null`.
+   * OAS 3.1 extension: allows marking a schema as nullable even when `type` does not include `'null'`.
    */
   'x-nullable'?: boolean
   /**
-   * Oas 3.1 adds support for `const` to specify that a schema can only have a single value, which must be equal to the value of `const`.
+   * OAS 3.1: constrains the schema to a single fixed value.
+   * Semantically equivalent to a one-item `enum`.
    */
   const?: string | number | boolean | null
   /**
-   * Oas 3.1 adds support for `contentMediaType` to specify the media type of the content being described by the schema.
+   * OAS 3.1: specifies the media type of the schema content.
+   * When set to `'application/octet-stream'` on a `string` schema, the schema is treated as binary (`blob`).
    */
   contentMediaType?: string
   $ref?: string
 }
 
-export const HttpMethods = {
-  GET: 'get',
-  POST: 'post',
-  PUT: 'put',
-  PATCH: 'patch',
-  DELETE: 'delete',
-  HEAD: 'head',
-  OPTIONS: 'options',
-  TRACE: 'trace',
-} satisfies Record<Uppercase<OASHttpMethods>, OASHttpMethods>
+/** Re-exported from `constants.ts` for backwards compatibility. */
+export { httpMethods as HttpMethods } from './constants.ts'
 
 export type HttpMethod = OASHttpMethods
 

package/src/utils.ts

@@ -9,28 +9,43 @@ import OASNormalize from 'oas-normalize'
 import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types'
 import { isPlainObject, mergeDeep } from 'remeda'
 import swagger2openapi from 'swagger2openapi'
+import { STRUCTURAL_KEYS } from './constants.ts'
 import { Oas } from './Oas.ts'
 import type { contentType, Document, SchemaObject } from './types.ts'
 
-export const STRUCTURAL_KEYS = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'])
-
-export function isOpenApiV2Document(doc: any): doc is OpenAPIV2.Document {
-  return doc && isPlainObject(doc) && !('openapi' in doc)
+/**
+ * Returns `true` when `doc` looks like a Swagger 2.0 document (no `openapi` key).
+ */
+export function isOpenApiV2Document(doc: unknown): doc is OpenAPIV2.Document {
+  return !!doc && isPlainObject(doc) && !('openapi' in doc)
 }
-export function isOpenApiV3Document(doc: any): doc is OpenAPIV3.Document {
-  return doc && isPlainObject(doc) && 'openapi' in doc
+
+/**
+ * Returns `true` when `doc` looks like an OpenAPI 3.x document (has `openapi` key).
+ */
+export function isOpenApiV3Document(doc: unknown): doc is OpenAPIV3.Document {
+  return !!doc && isPlainObject(doc) && 'openapi' in doc
 }
 
-export function isOpenApiV3_1Document(doc: any): doc is OpenAPIV3_1.Document {
-  return doc && isPlainObject<OpenAPIV3_1.Document>(doc) && 'openapi' in doc && doc.openapi.startsWith('3.1')
+/**
+ * Returns `true` when `doc` is an OpenAPI 3.1 document.
+ */
+export function isOpenApiV3_1Document(doc: unknown): doc is OpenAPIV3_1.Document {
+  return !!doc && isPlainObject(doc) && 'openapi' in (doc as object) && (doc as { openapi: string }).openapi.startsWith('3.1')
 }
 
+/**
+ * Returns `true` when `obj` is a JSON Schema object recognized by the `oas` library.
+ */
 export function isJSONSchema(obj?: unknown): obj is SchemaObject {
   return !!obj && isSchema(obj)
 }
 
+/**
+ * Returns `true` when `obj` is a parameter object (has an `in` field distinguishing it from a schema).
+ */
 export function isParameterObject(obj: ParameterObject | SchemaObject): obj is ParameterObject {
-  return obj && 'in' in obj
+  return !!obj && 'in' in obj
 }
 
 /**
@@ -56,17 +71,19 @@ export function isNullable(schema?: SchemaObject & { 'x-nullable'?: boolean }):
 }
 
 /**
- * Determines if the given object is an OpenAPI ReferenceObject.
+ * Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
  */
-export function isReference(obj?: any): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
-  return !!obj && isRef(obj)
+export function isReference(obj?: unknown): obj is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject {
+  return !!obj && isRef(obj as object)
 }
 
 /**
- * Determines if the given object is a SchemaObject with a discriminator property of type DiscriminatorObject.
+ * Returns `true` when `obj` is a schema that carries a structured `discriminator` object
+ * (as opposed to a plain string discriminator used in some older specs).
  */
-export function isDiscriminator(obj?: any): obj is SchemaObject & { discriminator: OpenAPIV3.DiscriminatorObject } {
-  return !!obj && obj?.['discriminator'] && typeof obj.discriminator !== 'string'
+export function isDiscriminator(obj?: unknown): obj is SchemaObject & { discriminator: OpenAPIV3.DiscriminatorObject } {
+  const record = obj as Record<string, unknown>
+  return !!obj && !!record['discriminator'] && typeof record['discriminator'] !== 'string'
 }
 
 /**

package/dist/chunk-OuPHjz6n.js

@@ -1,41 +0,0 @@
-import { createRequire } from "node:module";
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __name = (target, value) => __defProp(target, "name", {
-	value,
-	configurable: true
-});
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-//#endregion
-export { __require as a, __name as i, __esmMin as n, __toCommonJS as o, __exportAll as r, __toESM as s, __commonJSMin as t };