@kubb/adapter-oas 5.0.0-beta.2 → 5.0.0-beta.21

package/dist/index.js

@@ -1,213 +1,12 @@
 import "./chunk--u3MIqq1.js";
-import { ast, createAdapter } from "@kubb/core";
 import path from "node:path";
+import { ast, createAdapter } from "@kubb/core";
+import BaseOas from "oas";
 import { bundle, loadConfig } from "@redocly/openapi-core";
 import OASNormalize from "oas-normalize";
 import swagger2openapi from "swagger2openapi";
-import BaseOas from "oas";
 import { isRef } from "oas/types";
 import { matchesMimeType } from "oas/utils";
-//#region src/constants.ts
-/**
-* Default parser options applied when no explicit options are provided.
-*
-* @example
-* ```ts
-* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
-*
-* const parser = createOasParser(oas)
-* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
-* ```
-*/
-const DEFAULT_PARSER_OPTIONS = {
-	dateType: "string",
-	integerType: "bigint",
-	unknownType: "any",
-	emptySchemaType: "any",
-	enumSuffix: "enum"
-};
-/**
-* JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
-*
-* Used when building or parsing `$ref` strings.
-*
-* @example
-* ```ts
-* `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
-* ```
-*/
-const SCHEMA_REF_PREFIX = "#/components/schemas/";
-/**
-* OpenAPI version string written into the stub document created during multi-spec merges.
-*/
-const MERGE_OPENAPI_VERSION = "3.0.0";
-/**
-* Fallback `info.title` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_TITLE = "Merged API";
-/**
-* Fallback `info.version` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_VERSION = "1.0.0";
-/**
-* Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
-*
-* A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
-* intersection member rather than being merged into the parent.
-*
-* @example
-* ```ts
-* import { structuralKeys } from '@kubb/adapter-oas'
-*
-* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
-* // true when fragment has e.g. 'properties' or 'oneOf'
-* ```
-*/
-const structuralKeys = new Set([
-	"properties",
-	"items",
-	"additionalProperties",
-	"oneOf",
-	"anyOf",
-	"allOf",
-	"not"
-]);
-/**
-* 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.
-*
-* @example
-* ```ts
-* import { formatMap } from '@kubb/adapter-oas'
-*
-* formatMap['uuid']   // 'uuid'
-* formatMap['binary'] // 'blob'
-* formatMap['float']  // 'number'
-* ```
-*/
-const formatMap = {
-	uuid: "uuid",
-	email: "email",
-	"idn-email": "email",
-	uri: "url",
-	"uri-reference": "url",
-	url: "url",
-	ipv4: "ipv4",
-	ipv6: "ipv6",
-	hostname: "url",
-	"idn-hostname": "url",
-	binary: "blob",
-	byte: "blob",
-	int32: "integer",
-	float: "number",
-	double: "number"
-};
-/**
-* Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
-*
-* @example
-* ```ts
-* import { enumExtensionKeys } from '@kubb/adapter-oas'
-*
-* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
-* ```
-*/
-const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
-/**
-* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
-* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
-*/
-const typeOptionMap = new Map([
-	["any", ast.schemaTypes.any],
-	["unknown", ast.schemaTypes.unknown],
-	["void", ast.schemaTypes.void]
-]);
-//#endregion
-//#region src/discriminator.ts
-/**
-* Injects discriminator enum values into child schemas so they know which value identifies them.
-*
-* Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
-* enum value each union member is mapped to, then adds (or replaces) that property on the matching
-* child object schema.
-*
-* Returns a new `InputNode` — the original is never mutated.
-*
-* @example
-* ```ts
-* const { root } = parseOas(document, options)
-* const next = applyDiscriminatorInheritance(root)
-* ```
-*/
-function applyDiscriminatorInheritance(root) {
-	const childMap = /* @__PURE__ */ new Map();
-	for (const schema of root.schemas) {
-		let unionNode = ast.narrowSchema(schema, "union");
-		if (!unionNode) {
-			const intersectionMembers = ast.narrowSchema(schema, "intersection")?.members;
-			if (intersectionMembers) for (const m of intersectionMembers) {
-				const u = ast.narrowSchema(m, "union");
-				if (u) {
-					unionNode = u;
-					break;
-				}
-			}
-		}
-		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
-		const { discriminatorPropertyName, members } = unionNode;
-		for (const member of members) {
-			const intersectionNode = ast.narrowSchema(member, "intersection");
-			if (!intersectionNode?.members) continue;
-			let refNode;
-			let objNode;
-			for (const m of intersectionNode.members) {
-				refNode ??= ast.narrowSchema(m, "ref");
-				objNode ??= ast.narrowSchema(m, "object");
-			}
-			if (!refNode?.name || !objNode) continue;
-			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
-			const enumNode = prop ? ast.narrowSchema(prop.schema, "enum") : void 0;
-			if (!enumNode?.enumValues?.length) continue;
-			const enumValues = enumNode.enumValues.filter((v) => v !== null);
-			if (!enumValues.length) continue;
-			const existing = childMap.get(refNode.name);
-			if (existing) existing.enumValues.push(...enumValues);
-			else childMap.set(refNode.name, {
-				propertyName: discriminatorPropertyName,
-				enumValues: [...enumValues]
-			});
-		}
-	}
-	if (childMap.size === 0) return root;
-	return ast.transform(root, { schema(node, { parent }) {
-		if (parent?.kind !== "Input" || !node.name) return;
-		const entry = childMap.get(node.name);
-		if (!entry) return;
-		const objectNode = ast.narrowSchema(node, "object");
-		if (!objectNode) return;
-		const { propertyName, enumValues } = entry;
-		const enumSchema = ast.createSchema({
-			type: "enum",
-			enumValues
-		});
-		const newProp = ast.createProperty({
-			name: propertyName,
-			required: true,
-			schema: enumSchema
-		});
-		const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
-		const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
-		return {
-			...objectNode,
-			properties: newProperties
-		};
-	} });
-}
-//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -306,6 +105,30 @@ function mergeDeep(target, source) {
 	return result;
 }
 //#endregion
+//#region ../../internals/utils/src/promise.ts
+/**
+* Returns a wrapper that caches the result of the first invocation and replays
+* it for every subsequent call, ignoring later arguments.
+*
+* Works for sync and async factories — for async, the cached value is the
+* promise itself, so concurrent callers share one in-flight execution and
+* cannot race each other.
+*
+* @example
+* ```ts
+* const loadDocument = once(async (path: string) => parse(await readFile(path)))
+* const a = loadDocument('./a.yaml') // parses
+* const b = loadDocument('./b.yaml') // returns the cached promise from the first call
+* ```
+*/
+function once(factory) {
+	let cache;
+	return (...args) => {
+		if (!cache) cache = { value: factory(...args) };
+		return cache.value;
+	};
+}
+//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * JavaScript and Java reserved words.
@@ -555,6 +378,126 @@ var URLPath = class {
 	}
 };
 //#endregion
+//#region src/constants.ts
+/**
+* Default parser options applied when no explicit options are provided.
+*
+* @example
+* ```ts
+* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+*
+* const parser = createOasParser(oas)
+* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+* ```
+*/
+const DEFAULT_PARSER_OPTIONS = {
+	dateType: "string",
+	integerType: "bigint",
+	unknownType: "any",
+	emptySchemaType: "any",
+	enumSuffix: "enum"
+};
+/**
+* JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+*
+* Used when building or parsing `$ref` strings.
+*
+* @example
+* ```ts
+* `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+* ```
+*/
+const SCHEMA_REF_PREFIX = "#/components/schemas/";
+/**
+* OpenAPI version string written into the stub document created during multi-spec merges.
+*/
+const MERGE_OPENAPI_VERSION = "3.0.0";
+/**
+* Fallback `info.title` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_TITLE = "Merged API";
+/**
+* Fallback `info.version` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_VERSION = "1.0.0";
+/**
+* Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
+*
+* A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
+* intersection member rather than being merged into the parent.
+*
+* @example
+* ```ts
+* import { structuralKeys } from '@kubb/adapter-oas'
+*
+* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
+* // true when fragment has e.g. 'properties' or 'oneOf'
+* ```
+*/
+const structuralKeys = new Set([
+	"properties",
+	"items",
+	"additionalProperties",
+	"oneOf",
+	"anyOf",
+	"allOf",
+	"not"
+]);
+/**
+* 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.
+*
+* @example
+* ```ts
+* import { formatMap } from '@kubb/adapter-oas'
+*
+* formatMap['uuid']   // 'uuid'
+* formatMap['binary'] // 'blob'
+* formatMap['float']  // 'number'
+* ```
+*/
+const formatMap = {
+	uuid: "uuid",
+	email: "email",
+	"idn-email": "email",
+	uri: "url",
+	"uri-reference": "url",
+	url: "url",
+	ipv4: "ipv4",
+	ipv6: "ipv6",
+	hostname: "url",
+	"idn-hostname": "url",
+	binary: "blob",
+	byte: "blob",
+	int32: "integer",
+	float: "number",
+	double: "number"
+};
+/**
+* Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
+*
+* @example
+* ```ts
+* import { enumExtensionKeys } from '@kubb/adapter-oas'
+*
+* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
+* ```
+*/
+const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
+/**
+* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
+* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+*/
+const typeOptionMap = new Map([
+	["any", ast.schemaTypes.any],
+	["unknown", ast.schemaTypes.unknown],
+	["void", ast.schemaTypes.void]
+]);
+//#endregion
 //#region src/guards.ts
 /**
 * Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
@@ -660,11 +603,10 @@ async function parseDocument(pathOrApi, { canBundle = true, enablePaths = true }
 * ```
 */
 async function mergeDocuments(pathOrApi) {
-	const documents = [];
-	for (const p of pathOrApi) documents.push(await parseDocument(p, {
+	const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, {
 		enablePaths: false,
 		canBundle: false
-	}));
+	})));
 	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
 	const seed = {
 		openapi: MERGE_OPENAPI_VERSION,
@@ -720,6 +662,7 @@ async function validateDocument(document, { throwOnError = false } = {}) {
 }
 //#endregion
 //#region src/refs.ts
+const _refCache = /* @__PURE__ */ new WeakMap();
 /**
 * Resolves a local JSON pointer reference from a document.
 *
@@ -735,10 +678,17 @@ function resolveRef(document, $ref) {
 	const origRef = $ref;
 	$ref = $ref.trim();
 	if ($ref === "") return null;
-	if ($ref.startsWith("#")) $ref = globalThis.decodeURIComponent($ref.substring(1));
-	else return null;
+	if (!$ref.startsWith("#")) return null;
+	$ref = globalThis.decodeURIComponent($ref.substring(1));
+	let docCache = _refCache.get(document);
+	if (!docCache) {
+		docCache = /* @__PURE__ */ new Map();
+		_refCache.set(document, docCache);
+	}
+	if (docCache.has($ref)) return docCache.get($ref);
 	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
 	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
+	docCache.set($ref, current);
 	return current;
 }
 /**
@@ -953,21 +903,22 @@ function extractSchemaFromContent(content, preferredContentType) {
 /**
 * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
 */
-function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
+function* collectRefs(schema) {
 	if (Array.isArray(schema)) {
-		for (const item of schema) collectRefs(item, refs);
-		return refs;
+		for (const item of schema) yield* collectRefs(item);
+		return;
 	}
 	if (schema && typeof schema === "object") for (const key in schema) {
 		const value = schema[key];
-		if (key === "$ref" && typeof value === "string") {
-			if (value.startsWith("#/components/schemas/")) {
-				const name = value.slice(21);
-				if (name) refs.add(name);
-			}
-		} else collectRefs(value, refs);
+		if (!(key === "$ref" && typeof value === "string")) {
+			yield* collectRefs(value);
+			continue;
+		}
+		if (value.startsWith("#/components/schemas/")) {
+			const name = value.slice(21);
+			if (name) yield name;
+		}
 	}
-	return refs;
 }
 /**
 * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
@@ -983,7 +934,7 @@ function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
 */
 function sortSchemas(schemas) {
 	const deps = /* @__PURE__ */ new Map();
-	for (const [name, schema] of Object.entries(schemas)) deps.set(name, Array.from(collectRefs(schema)));
+	for (const [name, schema] of Object.entries(schemas)) deps.set(name, [...new Set(collectRefs(schema))]);
 	const sorted = [];
 	const visited = /* @__PURE__ */ new Set();
 	function visit(name, stack) {
@@ -1118,7 +1069,8 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 		readOnly: schema.readOnly,
 		writeOnly: schema.writeOnly,
 		default: defaultValue,
-		example: schema.example
+		example: schema.example,
+		format: schema.format
 	};
 }
 /**
@@ -1168,7 +1120,7 @@ function normalizeArrayEnum(schema) {
 * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
 * made possible by hoisting of function declarations.
 *
-* @note Not exported; called internally by `parseOas()` and `parseSchema()`.
+* @internal
 */
 function createSchemaParser(ctx) {
 	const document = ctx.document;
@@ -1178,6 +1130,19 @@ function createSchemaParser(ctx) {
 	*/
 	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
+	* Cache of already-resolved `$ref` schemas within this parser instance.
+	*
+	* Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
+	* every time it appears as a `$ref` in a different parent schema. In heavily
+	* cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
+	* blowup — `customer` alone may be referenced from dozens of top-level schemas,
+	* each triggering a fresh recursive expansion of its entire sub-tree.
+	*
+	* Memoizing by `$ref` path reduces the overall work from O(2^depth) to O(N)
+	* where N is the number of unique schema names.
+	*/
+	const resolvedRefCache = /* @__PURE__ */ new Map();
+	/**
 	* Converts a `$ref` schema into a `RefSchemaNode`.
 	*
 	* The resolved schema is stored in `node.schema`. Usage-site sibling fields
@@ -1186,16 +1151,22 @@ function createSchemaParser(ctx) {
 	* Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
 	*/
 	function convertRef({ schema, name, nullable, defaultValue, rawOptions }) {
-		let resolvedSchema;
+		let resolvedSchema = null;
 		const refPath = schema.$ref;
-		if (refPath && !resolvingRefs.has(refPath)) try {
-			const referenced = resolveRef(document, refPath);
-			if (referenced) {
-				resolvingRefs.add(refPath);
-				resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
-				resolvingRefs.delete(refPath);
+		if (refPath && !resolvingRefs.has(refPath)) {
+			if (!resolvedRefCache.has(refPath)) {
+				try {
+					const referenced = resolveRef(document, refPath);
+					if (referenced) {
+						resolvingRefs.add(refPath);
+						resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
+						resolvingRefs.delete(refPath);
+					}
+				} catch {}
+				resolvedRefCache.set(refPath, resolvedSchema);
 			}
-		} catch {}
+			resolvedSchema = resolvedRefCache.get(refPath) ?? null;
+		}
 		return ast.createSchema({
 			...buildSchemaNode(schema, name, nullable, defaultValue),
 			type: "ref",
@@ -1228,7 +1199,8 @@ function createSchemaParser(ctx) {
 				writeOnly: schema.writeOnly ?? memberNode.writeOnly,
 				default: mergedDefault,
 				example: schema.example ?? memberNode.example,
-				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0)
+				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0),
+				format: schema.format ?? memberNode.format
 			});
 		}
 		const filteredDiscriminantValues = [];
@@ -1280,7 +1252,7 @@ function createSchemaParser(ctx) {
 		}));
 		return ast.createSchema({
 			type: "intersection",
-			members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+			members: [...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
@@ -1360,7 +1332,8 @@ function createSchemaParser(ctx) {
 			name,
 			title: schema.title,
 			description: schema.description,
-			deprecated: schema.deprecated
+			deprecated: schema.deprecated,
+			format: schema.format
 		});
 		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
 		return ast.createSchema({
@@ -1464,7 +1437,8 @@ function createSchemaParser(ctx) {
 			readOnly: schema.readOnly,
 			writeOnly: schema.writeOnly,
 			default: enumDefault,
-			example: schema.example
+			example: schema.example,
+			format: schema.format
 		};
 		const extensionKey = enumExtensionKeys.find((key) => key in schema);
 		if (extensionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
@@ -1503,15 +1477,18 @@ function createSchemaParser(ctx) {
 				schema: resolvedPropSchema,
 				name: ast.childName(name, propName)
 			}, rawOptions);
-			let schemaNode = ast.setEnumName(propNode, name, propName, options.enumSuffix);
-			const tupleNode = ast.narrowSchema(schemaNode, "tuple");
-			if (tupleNode?.items) {
-				const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix));
-				if (namedItems.some((item, i) => item !== tupleNode.items[i])) schemaNode = {
-					...tupleNode,
-					items: namedItems
-				};
-			}
+			const schemaNode = (() => {
+				const node = ast.setEnumName(propNode, name, propName, options.enumSuffix);
+				const tupleNode = ast.narrowSchema(node, "tuple");
+				if (tupleNode?.items) {
+					const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix));
+					if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
+						...tupleNode,
+						items: namedItems
+					};
+				}
+				return node;
+			})();
 			return ast.createProperty({
 				name: propName,
 				schema: {
@@ -1522,11 +1499,12 @@ function createSchemaParser(ctx) {
 			});
 		}) : [];
 		const additionalProperties = schema.additionalProperties;
-		let additionalPropertiesNode;
-		if (additionalProperties === true) additionalPropertiesNode = true;
-		else if (additionalProperties && Object.keys(additionalProperties).length > 0) additionalPropertiesNode = parseSchema({ schema: additionalProperties }, rawOptions);
-		else if (additionalProperties === false) additionalPropertiesNode = false;
-		else if (additionalProperties) additionalPropertiesNode = ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		const additionalPropertiesNode = (() => {
+			if (additionalProperties === true) return true;
+			if (additionalProperties === false) return false;
+			if (additionalProperties && Object.keys(additionalProperties).length > 0) return parseSchema({ schema: additionalProperties }, rawOptions);
+			if (additionalProperties) return ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		})();
 		const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
 		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? ast.createSchema({ type: typeOptionMap.get(options.unknownType) }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
 		const objectNode = ast.createSchema({
@@ -1573,7 +1551,7 @@ function createSchemaParser(ctx) {
 	*/
 	function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }) {
 		const rawItems = schema.items;
-		const itemName = rawItems?.enum?.length && name ? ast.enumPropName(void 0, name, options.enumSuffix) : void 0;
+		const itemName = rawItems?.enum?.length && name ? ast.enumPropName(null, name, options.enumSuffix) : void 0;
 		const items = rawItems ? [parseSchema({
 			schema: rawItems,
 			name: itemName
@@ -1637,7 +1615,8 @@ function createSchemaParser(ctx) {
 			title: schema.title,
 			description: schema.description,
 			deprecated: schema.deprecated,
-			nullable
+			nullable,
+			format: schema.format
 		});
 	}
 	/**
@@ -1715,7 +1694,8 @@ function createSchemaParser(ctx) {
 			type: emptyType,
 			name,
 			title: schema.title,
-			description: schema.description
+			description: schema.description,
+			format: schema.format
 		});
 	}
 	/**
@@ -1762,13 +1742,13 @@ function createSchemaParser(ctx) {
 	* `$ref` entries are skipped since their flags live on the dereferenced target.
 	*/
 	function collectPropertyKeysByFlag(schema, flag) {
-		if (!schema?.properties) return void 0;
+		if (!schema?.properties) return null;
 		const keys = [];
 		for (const key in schema.properties) {
 			const prop = schema.properties[key];
 			if (prop && !isReference(prop) && prop[flag]) keys.push(key);
 		}
-		return keys.length ? keys : void 0;
+		return keys.length ? keys : null;
 	}
 	/**
 	* Converts an OAS `Operation` into an `OperationNode`.
@@ -1825,48 +1805,202 @@ function createSchemaParser(ctx) {
 		parseParameter
 	};
 }
+//#endregion
+//#region src/discriminator.ts
+/**
+* Builds a map of child schema names → discriminator patch data by scanning the given
+* top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
+*
+* Extracted from `applyDiscriminatorInheritance` so the streaming path can call it on a
+* small pre-parsed subset of schemas (only the discriminator parents) rather than on all
+* schemas at once.
+*/
+function buildDiscriminatorChildMap(schemas) {
+	const childMap = /* @__PURE__ */ new Map();
+	for (const schema of schemas) {
+		let unionNode = ast.narrowSchema(schema, "union");
+		if (!unionNode) {
+			const intersectionMembers = ast.narrowSchema(schema, "intersection")?.members;
+			if (intersectionMembers) for (const m of intersectionMembers) {
+				const u = ast.narrowSchema(m, "union");
+				if (u) {
+					unionNode = u;
+					break;
+				}
+			}
+		}
+		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
+		const { discriminatorPropertyName, members } = unionNode;
+		for (const member of members) {
+			const intersectionNode = ast.narrowSchema(member, "intersection");
+			if (!intersectionNode?.members) continue;
+			let refNode = null;
+			let objNode = null;
+			for (const m of intersectionNode.members) {
+				refNode ??= ast.narrowSchema(m, "ref");
+				objNode ??= ast.narrowSchema(m, "object");
+			}
+			if (!refNode?.name || !objNode) continue;
+			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
+			const enumNode = prop ? ast.narrowSchema(prop.schema, "enum") : null;
+			if (!enumNode?.enumValues?.length) continue;
+			const enumValues = enumNode.enumValues.filter((v) => v !== null);
+			if (!enumValues.length) continue;
+			const existing = childMap.get(refNode.name);
+			if (!existing) {
+				childMap.set(refNode.name, {
+					propertyName: discriminatorPropertyName,
+					enumValues: [...enumValues]
+				});
+				continue;
+			}
+			existing.enumValues.push(...enumValues);
+		}
+	}
+	return childMap;
+}
+/**
+* Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+* the discriminant property). Used by the streaming path to apply patches inline per yield
+* without buffering all schemas.
+*/
+function patchDiscriminatorNode(node, entry) {
+	const objectNode = ast.narrowSchema(node, "object");
+	if (!objectNode) return node;
+	const { propertyName, enumValues } = entry;
+	const enumSchema = ast.createSchema({
+		type: "enum",
+		enumValues
+	});
+	const newProp = ast.createProperty({
+		name: propertyName,
+		required: true,
+		schema: enumSchema
+	});
+	const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
+	const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
+	return {
+		...objectNode,
+		properties: newProperties
+	};
+}
+//#endregion
+//#region src/stream.ts
+/**
+* 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' } })`
+*/
+function resolveBaseUrl({ document, serverIndex, serverVariables }) {
+	const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
+	return server?.url ? resolveServerUrl(server, serverVariables) : null;
+}
 /**
-* Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
+* Parses every schema once to build the lookup structures that streaming needs upfront.
 *
-* This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
-* that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
-* the tree is a pure data structure representing all schemas and operations.
+* 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.
 *
-* Returns the AST root and a `nameMapping` for resolving schema references.
+* 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
-* import { parseOas } from '@kubb/adapter-oas'
-*
-* const document = await parseFromConfig(config)
-* const { root, nameMapping } = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+* const { refAliasMap, enumNames, circularNames } = preScan({
+*   schemas,
+*   parseSchema,
+*   parserOptions,
+*   discriminator: 'strict',
+* })
 * ```
 */
-function parseOas(document, options = {}) {
-	const { contentType, ...parserOptions } = options;
-	const mergedOptions = {
-		...DEFAULT_PARSER_OPTIONS,
-		...parserOptions
-	};
-	const { schemas: schemaObjects, nameMapping } = getSchemas(document, { contentType });
-	const { parseSchema: _parseSchema, parseOperation: _parseOperation } = createSchemaParser({
-		document,
-		contentType
-	});
-	const schemas = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({
-		schema,
-		name
-	}, mergedOptions));
-	const paths = new BaseOas(document).getPaths();
-	const operations = Object.entries(paths).flatMap(([_path, methods]) => Object.entries(methods).map(([, operation]) => operation ? _parseOperation(mergedOptions, operation) : null).filter((op) => op !== null));
+function preScan({ schemas, parseSchema, parserOptions, discriminator }) {
+	const allNodes = [];
+	const refAliasMap = /* @__PURE__ */ new Map();
+	const enumNames = [];
+	const discriminatorParentNodes = [];
+	for (const [name, schema] of Object.entries(schemas)) {
+		const node = parseSchema({
+			schema,
+			name
+		}, parserOptions);
+		allNodes.push(node);
+		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);
+	}
 	return {
-		root: ast.createInput({
-			schemas,
-			operations
-		}),
-		nameMapping
+		refAliasMap,
+		enumNames,
+		circularNames: [...ast.findCircularSchemas(allNodes)],
+		discriminatorChildMap: discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
 	};
 }
+/**
+* Creates a lazy `InputStreamNode` 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, baseOas, parserOptions, refAliasMap, discriminatorChildMap, meta })
+* for await (const schema of streamNode.schemas) {
+*   // each call to for-await restarts from the first schema
+* }
+* ```
+*/
+function createInputStream({ schemas, parseSchema, parseOperation, baseOas, parserOptions, refAliasMap, discriminatorChildMap, meta }) {
+	const schemasIterable = { [Symbol.asyncIterator]() {
+		return (async function* () {
+			for (const [name, schema] of Object.entries(schemas)) {
+				const alias = refAliasMap.get(name);
+				if (alias?.name && schemas[alias.name]) {
+					yield {
+						...parseSchema({
+							schema: schemas[alias.name],
+							name: alias.name
+						}, parserOptions),
+						name
+					};
+					continue;
+				}
+				const parsed = parseSchema({
+					schema,
+					name
+				}, parserOptions);
+				yield discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed;
+			}
+		})();
+	} };
+	const operationsIterable = { [Symbol.asyncIterator]() {
+		return (async function* () {
+			for (const methods of Object.values(baseOas.getPaths())) for (const operation of Object.values(methods)) {
+				if (!operation) continue;
+				const node = parseOperation(parserOptions, operation);
+				if (node) yield node;
+			}
+		})();
+	} };
+	return ast.createStreamInput(schemasIterable, operationsIterable, meta);
+}
 //#endregion
 //#region src/adapter.ts
 /**
@@ -1894,9 +2028,65 @@ const adapterOasName = "oas";
 */
 const adapterOas = createAdapter((options) => {
 	const { validate = true, contentType, serverIndex, serverVariables, discriminator = "strict", dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
+	const parserOptions = {
+		...DEFAULT_PARSER_OPTIONS,
+		dateType,
+		integerType,
+		unknownType,
+		emptySchemaType,
+		enumSuffix
+	};
 	let nameMapping = /* @__PURE__ */ new Map();
-	let parsedDocument;
-	let inputNode;
+	let parsedDocument = null;
+	const ensureDocument = once(async (source) => {
+		const fresh = await parseFromConfig(source);
+		if (validate) await validateDocument(fresh);
+		parsedDocument = fresh;
+		return fresh;
+	});
+	const ensureSchemas = once(async (document) => {
+		const result = getSchemas(document, { contentType });
+		nameMapping = result.nameMapping;
+		return result.schemas;
+	});
+	const ensureBaseOas = once((document) => new BaseOas(document));
+	const ensureSchemaParser = once((document) => createSchemaParser({
+		document,
+		contentType
+	}));
+	const ensurePreScan = once((schemas, parseSchema) => preScan({
+		schemas,
+		parseSchema,
+		parserOptions,
+		discriminator
+	}));
+	async function createStream(source) {
+		const document = await ensureDocument(source);
+		const schemas = await ensureSchemas(document);
+		const { parseSchema, parseOperation } = ensureSchemaParser(document);
+		const { refAliasMap, enumNames, circularNames, discriminatorChildMap } = ensurePreScan(schemas, parseSchema);
+		return createInputStream({
+			schemas,
+			parseSchema,
+			parseOperation,
+			baseOas: ensureBaseOas(document),
+			parserOptions,
+			refAliasMap,
+			discriminatorChildMap,
+			meta: {
+				title: document.info?.title,
+				description: document.info?.description,
+				version: document.info?.version,
+				baseURL: resolveBaseUrl({
+					document,
+					serverIndex,
+					serverVariables
+				}),
+				circularNames,
+				enumNames
+			}
+		});
+	}
 	return {
 		name: "oas",
 		get options() {
@@ -1917,8 +2107,8 @@ const adapterOas = createAdapter((options) => {
 		get document() {
 			return parsedDocument;
 		},
-		get inputNode() {
-			return inputNode;
+		async validate(input, options) {
+			await validateDocument(await parseDocument(input), options);
 		},
 		getImports(node, resolve) {
 			return ast.collectImports({
@@ -1926,7 +2116,7 @@ const adapterOas = createAdapter((options) => {
 				nameMapping,
 				resolve: (schemaName) => {
 					const result = resolve(schemaName);
-					if (!result) return;
+					if (!result) return null;
 					return ast.createImport({
 						name: [result.name],
 						path: result.path
@@ -1935,32 +2125,20 @@ const adapterOas = createAdapter((options) => {
 			});
 		},
 		async parse(source) {
-			const document = await parseFromConfig(source);
-			if (validate) await validateDocument(document);
-			const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
-			const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : void 0;
-			const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-				contentType,
-				dateType,
-				integerType,
-				unknownType,
-				emptySchemaType,
-				enumSuffix
-			});
-			const node = discriminator === "inherit" ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot;
-			nameMapping = parsedNameMapping;
-			parsedDocument = document;
-			inputNode = ast.createInput({
-				...node,
-				meta: {
-					title: document.info?.title,
-					description: document.info?.description,
-					version: document.info?.version,
-					baseURL
-				}
+			const streamNode = await createStream(source);
+			const collect = async (iter) => {
+				const out = [];
+				for await (const item of iter) out.push(item);
+				return out;
+			};
+			const [schemas, operations] = await Promise.all([collect(streamNode.schemas), collect(streamNode.operations)]);
+			return ast.createInput({
+				schemas,
+				operations,
+				meta: streamNode.meta
 			});
-			return inputNode;
-		}
+		},
+		stream: createStream
 	};
 });
 //#endregion
@@ -1976,6 +2154,6 @@ const adapterOas = createAdapter((options) => {
 */
 const HttpMethods = Object.fromEntries(Object.entries(ast.httpMethods).map(([lower, upper]) => [upper, lower]));
 //#endregion
-export { HttpMethods, adapterOas, adapterOasName, mergeDocuments, parseDocument, parseFromConfig, validateDocument };
+export { HttpMethods, adapterOas, adapterOasName, mergeDocuments };
 
 //# sourceMappingURL=index.js.map