@orval/core 8.12.3 → 8.14.0

package/dist/index.mjs

@@ -48,6 +48,7 @@ const OutputClient = {
 	VUE_QUERY: "vue-query",
 	SWR: "swr",
 	ZOD: "zod",
+	EFFECT: "effect",
 	HONO: "hono",
 	FETCH: "fetch",
 	MCP: "mcp"
@@ -143,6 +144,16 @@ const TEMPLATE_TAG_REGEX = /\${(.+?)}/g;
 function isReference(obj) {
 	return !isNullish$1(obj) && Object.hasOwn(obj, "$ref");
 }
+/**
+* Discriminator helper for {@link OpenApiDynamicReferenceObject}.
+*
+* Returns `true` when `obj` has a `$dynamicRef` string property,
+* indicating it is an OpenAPI 3.1 dynamic reference rather than a
+* static `$ref`.
+*/
+function isDynamicReference(obj) {
+	return !isNullish$1(obj) && Object.hasOwn(obj, "$dynamicRef") && typeof obj.$dynamicRef === "string";
+}
 function isDirectory(pathValue) {
 	return !nodePath.extname(pathValue);
 }
@@ -741,13 +752,21 @@ function count(str = "", key) {
 var path_exports = /* @__PURE__ */ __exportAll({
 	getRelativeImportPath: () => getRelativeImportPath,
 	getSchemaFileName: () => getSchemaFileName,
+	isAbsolute: () => isAbsolute,
 	join: () => join,
 	joinSafe: () => joinSafe,
 	normalizeSafe: () => normalizeSafe,
 	relativeSafe: () => relativeSafe,
+	resolve: () => resolve,
 	separator: () => "/",
 	toUnix: () => toUnix
 });
+function isAbsolute(value) {
+	return nodePath.isAbsolute(value);
+}
+function resolve(...args) {
+	return toUnix(nodePath.resolve(...args));
+}
 function toUnix(value) {
 	value = value.replaceAll("\\", "/");
 	value = value.replaceAll(/(?<!^)\/+/g, "/");
@@ -1357,6 +1376,16 @@ function getRefInfo($ref, context) {
 		refPaths
 	};
 }
+/**
+* Extracts the anchor name from a fragment-only `$dynamicRef` (e.g. `#category` → `category`).
+*
+* Returns `undefined` for external-document `$dynamicRef` values (e.g. `other.json#anchor`)
+* which are not supported.
+*/
+function getDynamicAnchorName(dynamicRef) {
+	if (!dynamicRef.startsWith("#") || dynamicRef.length <= 1) return;
+	return dynamicRef.slice(1);
+}
 //#endregion
 //#region src/getters/imports.ts
 function getAliasedImports({ name, resolvedValue, context }) {
@@ -1514,7 +1543,9 @@ function combineSchemas({ name, schema, separator, context, nullable, formDataCo
 		const originalProps = resolvedValue.originalSchema.properties;
 		if (resolvedValue.type === "object" && originalProps) resolvedData.allProperties.push(...Object.keys(originalProps));
 	}
-	if (resolvedData.isEnum.every(Boolean) && name && items.length > 1 && context.output.override.enumGenerationType !== EnumGeneration.UNION) {
+	const isAllEnums = resolvedData.isEnum.every(Boolean);
+	const isNullableEnumComposition = (separator === "anyOf" || separator === "oneOf") && !isAllEnums && resolvedData.isEnum.some(Boolean) && resolvedData.isEnum.every((isEnum, index) => isEnum && !resolvedData.isRef[index] || resolvedData.types[index] === "null");
+	if (isAllEnums && name && items.length > 1 && context.output.override.enumGenerationType !== EnumGeneration.UNION) {
 		const { value: combinedEnumValue, valueImports, hasNull } = getCombinedEnumValue(resolvedData.values.map((value, index) => ({
 			value,
 			isRef: resolvedData.isRef[index],
@@ -1575,7 +1606,7 @@ function combineSchemas({ name, schema, separator, context, nullable, formDataCo
 		imports: resolvedValue ? [...resolvedData.imports, ...resolvedValue.imports] : resolvedData.imports,
 		schemas: resolvedValue ? [...resolvedData.schemas, ...resolvedValue.schemas] : resolvedData.schemas,
 		dependencies: resolvedValue ? [...resolvedData.dependencies, ...resolvedValue.dependencies] : resolvedData.dependencies,
-		isEnum: false,
+		isEnum: isNullableEnumComposition,
 		type: "object",
 		isRef: false,
 		hasReadonlyProps: resolvedData.hasReadonlyProps || (resolvedValue?.hasReadonlyProps ?? false),
@@ -2041,16 +2072,33 @@ function getScalar({ item, name, context, formDataContext }) {
 				examples: resolveExampleRefs(schemaExamples, context)
 			};
 		}
-		case "null": return {
-			value: "null",
-			isEnum: false,
-			type: "null",
-			imports: [],
-			schemas: [],
-			isRef: false,
-			hasReadonlyProps: schemaReadOnly ?? false,
-			dependencies: []
-		};
+		case "null": {
+			const itemAllOf = item.allOf;
+			const itemOneOf = item.oneOf;
+			const itemAnyOf = item.anyOf;
+			let separator;
+			if (itemAllOf?.length) separator = "allOf";
+			else if (itemOneOf?.length) separator = "oneOf";
+			else if (itemAnyOf?.length) separator = "anyOf";
+			if (separator) return combineSchemas({
+				schema: Object.fromEntries(Object.entries(item).filter(([key]) => key !== "type")),
+				name,
+				separator,
+				context,
+				nullable: nullable || " | null",
+				formDataContext
+			});
+			return {
+				value: "null",
+				isEnum: false,
+				type: "null",
+				imports: [],
+				schemas: [],
+				isRef: false,
+				hasReadonlyProps: schemaReadOnly ?? false,
+				dependencies: []
+			};
+		}
 		default: {
 			if (isArray(itemType)) return combineSchemas({
 				schema: { anyOf: itemType.map((type) => Object.assign({}, item, { type })) },
@@ -2088,6 +2136,28 @@ function getScalar({ item, name, context, formDataContext }) {
 }
 //#endregion
 //#region src/resolvers/ref.ts
+/** Convert a `$dynamicAnchor` name to a valid TypeScript generic parameter identifier. */
+function dynamicAnchorToParamName(anchor) {
+	return sanitize(anchor, {
+		underscore: "_",
+		whitespace: "_",
+		dash: "_",
+		es5keyword: true,
+		es5IdentifierName: true
+	});
+}
+function dynamicAnchorsToUniqueParamNames(anchors) {
+	const result = /* @__PURE__ */ new Map();
+	const usedNames = /* @__PURE__ */ new Map();
+	for (const anchor of anchors) {
+		const base = dynamicAnchorToParamName(anchor);
+		const count = usedNames.get(base) ?? 0;
+		usedNames.set(base, count + 1);
+		const paramName = count === 0 ? base : `${base}${count + 1}`;
+		result.set(anchor, paramName);
+	}
+	return result;
+}
 const REF_NOT_FOUND_PREFIX = "Oops... 🍻. Ref not found";
 /**
 * Recursively resolves a `$ref` in an OpenAPI document, following
@@ -2137,15 +2207,100 @@ function resolveRef(schema, context, imports = []) {
 		schemaName: originalName
 	}]);
 }
+/** Check whether a schema reference has at least one `$defs` entry with both `$dynamicAnchor` and `$ref`. */
+function isBoundAlias(schema) {
+	const defs = schema.$defs;
+	if (!defs || typeof defs !== "object") return false;
+	for (const defSchema of Object.values(defs)) {
+		if (!defSchema || typeof defSchema !== "object") continue;
+		const rec = defSchema;
+		if (typeof rec.$dynamicAnchor === "string" && typeof rec.$ref === "string") return true;
+	}
+	return false;
+}
 /**
-* Looks up a schema by its `$ref` path in the spec, applying suffix resolution.
-*
-* Preserves OpenAPI 3.0 `nullable` and 3.1 type-array (`["object", "null"]`)
-* hints from the referencing schema onto the resolved target.
-*
-* @see https://spec.openapis.org/oas/v3.0.3#fixed-fields-18 (nullable)
-* @see https://spec.openapis.org/oas/v3.1.0#schema-object (type as array)
+* Extract bound-alias information from a schema that references a generic template
+* and binds `$dynamicAnchor` entries to concrete types via `$defs`.
 */
+function extractBoundAliasInfo(schema, context) {
+	let bindingElement;
+	let extraSchemas;
+	if (isReference(schema) && isBoundAlias(schema)) bindingElement = schema;
+	else {
+		const allOf = schema.allOf;
+		if (Array.isArray(allOf)) for (let i = 0; i < allOf.length; i++) {
+			const element = allOf[i];
+			if (isReference(element) && isBoundAlias(element)) {
+				bindingElement = element;
+				extraSchemas = allOf.filter((_, j) => j !== i);
+				break;
+			}
+		}
+	}
+	if (!bindingElement) return void 0;
+	const defs = bindingElement.$defs;
+	if (!defs || typeof defs !== "object") return void 0;
+	const bindingByAnchor = /* @__PURE__ */ new Map();
+	for (const defSchema of Object.values(defs)) {
+		if (!defSchema || typeof defSchema !== "object") continue;
+		const rec = defSchema;
+		if (rec.$dynamicAnchor === void 0) continue;
+		const ref = rec.$ref;
+		if (!ref || !isComponentRef(ref)) continue;
+		const anchor = rec.$dynamicAnchor;
+		const { name, originalName } = getRefInfo(ref, context);
+		bindingByAnchor.set(anchor, {
+			typeName: name,
+			originalName
+		});
+	}
+	if (bindingByAnchor.size === 0) return void 0;
+	const refPath = bindingElement.$ref;
+	if (typeof refPath !== "string") return void 0;
+	const { name: genericName, refPaths: templateRefPaths } = getRefInfo(refPath, context);
+	const templateDefs = (templateRefPaths ? prop(context.spec, ...templateRefPaths) : void 0)?.$defs;
+	const typeArgs = [];
+	const genericParams = [];
+	const imports = [];
+	if (templateDefs && typeof templateDefs === "object") {
+		const templateAnchors = [];
+		for (const defSchema of Object.values(templateDefs)) {
+			if (!defSchema || typeof defSchema !== "object") continue;
+			const rec = defSchema;
+			if (rec.$dynamicAnchor === void 0 || rec.$ref !== void 0) continue;
+			templateAnchors.push(rec.$dynamicAnchor);
+		}
+		const uniqueNames = dynamicAnchorsToUniqueParamNames(templateAnchors);
+		for (const anchor of templateAnchors) {
+			const binding = bindingByAnchor.get(anchor);
+			if (binding) {
+				typeArgs.push(binding.typeName);
+				imports.push({
+					name: binding.typeName,
+					schemaName: binding.originalName
+				});
+			} else {
+				const paramName = uniqueNames.get(anchor) ?? dynamicAnchorToParamName(anchor);
+				typeArgs.push(paramName);
+				genericParams.push(paramName);
+			}
+		}
+	}
+	if (typeArgs.length === 0) for (const { typeName, originalName } of bindingByAnchor.values()) {
+		typeArgs.push(typeName);
+		imports.push({
+			name: typeName,
+			schemaName: originalName
+		});
+	}
+	return {
+		genericName,
+		genericParams,
+		typeArgs,
+		imports,
+		extraSchemas
+	};
+}
 function getSchema$1(schema, context) {
 	if (!schema.$ref) throw new Error(`${REF_NOT_FOUND_PREFIX}: missing $ref`);
 	const refInfo = getRefInfo(schema.$ref, context);
@@ -2172,6 +2327,108 @@ function getSchema$1(schema, context) {
 		refInfo
 	};
 }
+function encodeJsonPointerSegment(segment) {
+	return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/**
+* Build the dynamic scope for a schema: maps `$dynamicAnchor` names to concrete
+* type entries for self-referential resolution, `$defs` bindings, and sibling anchors.
+*/
+function buildDynamicScope(schemaName, schema, context) {
+	const scope = {};
+	const getSchemaScopeEntry = (name) => {
+		const refInfo = getRefInfo(`#/components/schemas/${encodeJsonPointerSegment(name)}`, context);
+		return {
+			name: refInfo.name,
+			schemaName: refInfo.originalName
+		};
+	};
+	const schemaRecord = schema;
+	if (typeof schemaRecord.$dynamicAnchor === "string") scope[schemaRecord.$dynamicAnchor] = getSchemaScopeEntry(schemaName);
+	const defs = schemaRecord.$defs;
+	if (defs && typeof defs === "object") {
+		const unboundAnchors = [];
+		for (const [, defSchema] of Object.entries(defs)) {
+			if (!defSchema || typeof defSchema !== "object") continue;
+			const defRecord = defSchema;
+			if (typeof defRecord.$dynamicAnchor === "string") {
+				const anchorName = defRecord.$dynamicAnchor;
+				const refInDef = defSchema.$ref;
+				if (refInDef?.startsWith("#/components/schemas/")) {
+					const { name, originalName } = getRefInfo(refInDef, context);
+					scope[anchorName] = {
+						name,
+						schemaName: originalName
+					};
+				} else if (!refInDef) unboundAnchors.push(anchorName);
+			}
+		}
+		if (unboundAnchors.length > 0) {
+			const uniqueNames = dynamicAnchorsToUniqueParamNames(unboundAnchors);
+			for (const anchor of unboundAnchors) {
+				const paramName = uniqueNames.get(anchor);
+				if (paramName === void 0) continue;
+				scope[anchor] = {
+					name: paramName,
+					schemaName: paramName,
+					isParameter: true
+				};
+			}
+		}
+	}
+	return scope;
+}
+/**
+* Resolve a `$dynamicRef` anchor to its concrete type using the current dynamic scope.
+* Returns `{ schema: {}, resolvedTypeName: 'unknown' }` when no scope override exists.
+*/
+function resolveDynamicRef(anchorName, context, imports = []) {
+	let scopeEntry = (context.dynamicScope ?? {})[anchorName];
+	if (!scopeEntry) {
+		const schemas = context.spec.components?.schemas;
+		if (schemas && typeof schemas === "object") {
+			const matches = [];
+			for (const [schemaName, schemaObj] of Object.entries(schemas)) {
+				if (!schemaObj || typeof schemaObj !== "object") continue;
+				if (schemaObj.$dynamicAnchor === anchorName) matches.push(schemaName);
+			}
+			const match = matches.length === 1 ? matches[0] : matches.find((m) => m === anchorName);
+			if (match) {
+				const refInfo = getRefInfo(`#/components/schemas/${encodeJsonPointerSegment(match)}`, context);
+				scopeEntry = {
+					name: refInfo.name,
+					schemaName: refInfo.originalName
+				};
+			}
+		}
+	}
+	if (!scopeEntry) return {
+		schema: {},
+		imports,
+		resolvedTypeName: "unknown"
+	};
+	if (scopeEntry.isParameter) return {
+		schema: {},
+		imports,
+		resolvedTypeName: scopeEntry.name
+	};
+	const resolvedTypeName = scopeEntry.name;
+	const schemaRef = `#/components/schemas/${encodeJsonPointerSegment(scopeEntry.schemaName)}`;
+	try {
+		const { schema: resolvedSchema, imports: resolvedImports } = resolveRef({ $ref: schemaRef }, context, imports);
+		return {
+			schema: resolvedSchema,
+			imports: resolvedImports,
+			resolvedTypeName
+		};
+	} catch {
+		return {
+			schema: {},
+			imports,
+			resolvedTypeName: "unknown"
+		};
+	}
+}
 /** Recursively resolves `$ref` entries in an examples array or record. */
 function resolveExampleRefs(examples, context) {
 	if (!examples) return;
@@ -2189,8 +2446,119 @@ function resolveExampleRefs(examples, context) {
 }
 //#endregion
 //#region src/resolvers/value.ts
+const schemaArrayKeys = [
+	"allOf",
+	"anyOf",
+	"oneOf",
+	"prefixItems"
+];
+const schemaObjectKeys = [
+	"additionalProperties",
+	"contains",
+	"else",
+	"if",
+	"items",
+	"not",
+	"propertyNames",
+	"then",
+	"unevaluatedItems",
+	"unevaluatedProperties"
+];
+const schemaMapKeys = [
+	"$defs",
+	"dependentSchemas",
+	"patternProperties",
+	"properties"
+];
+/**
+* Recursively walks a schema value and returns `true` if any nested
+* `$dynamicRef` resolves — via the current `context.dynamicScope` — to a
+* schema *other* than `refName`.
+*
+* Used by `resolveValue` to decide whether a `$ref`'d schema must be
+* instantiated with its bound type arguments rather than referenced by name.
+*
+* @param value   - The schema node (or sub-node) to inspect.
+* @param context - Current resolution context, including the dynamic scope.
+* @param refName - The resolved name of the enclosing `$ref` schema; dynamic
+*                  refs that resolve to this same name are considered
+*                  self-references and do not count as "scope-affected".
+* @param seen    - Cycle-guard; tracks already-visited objects.
+*/
+function hasScopeAffectedDynamicRef(value, context, refName, seen = /* @__PURE__ */ new WeakSet()) {
+	if (!value || typeof value !== "object") return false;
+	if (!context.dynamicScope || Object.keys(context.dynamicScope).length === 0) return false;
+	if (seen.has(value)) return false;
+	seen.add(value);
+	if (isDynamicReference(value) && value.$dynamicRef.startsWith("#")) {
+		const anchorName = getDynamicAnchorName(value.$dynamicRef);
+		if (anchorName) {
+			const scopeEntry = context.dynamicScope[anchorName];
+			if (scopeEntry && scopeEntry.name !== refName) return true;
+		}
+	}
+	const schema = value;
+	for (const key of schemaArrayKeys) {
+		const items = schema[key];
+		if (Array.isArray(items) && items.some((item) => hasScopeAffectedDynamicRef(item, context, refName, seen))) return true;
+	}
+	for (const key of schemaObjectKeys) if (hasScopeAffectedDynamicRef(schema[key], context, refName, seen)) return true;
+	for (const key of schemaMapKeys) {
+		const schemaMap = schema[key];
+		if (schemaMap && typeof schemaMap === "object" && Object.values(schemaMap).some((item) => hasScopeAffectedDynamicRef(item, context, refName, seen))) return true;
+	}
+	return false;
+}
+function makeUnknownValue(originalSchema) {
+	return {
+		value: "unknown",
+		imports: [],
+		type: "unknown",
+		isEnum: false,
+		schemas: [],
+		isRef: false,
+		hasReadonlyProps: false,
+		originalSchema,
+		dependencies: []
+	};
+}
+/**
+* Resolves an OpenAPI schema or reference object to a {@link ResolverValue}
+* that carries the TypeScript type string, required imports, and metadata.
+*
+* Handles all schema forms in priority order:
+* 1. **Bound generic alias** — a `$ref` with `$defs` overrides; emits an
+*    instantiated generic expression such as `Paginated<User>`.
+* 2. **Component `$ref`** — a named `$ref` pointing to `#/components/…`;
+*    emits the schema name as a reference import.
+* 3. **Non-component `$ref`** — an anonymous or path-level ref; inlines the
+*    resolved schema via {@link getScalar} (cycle-safe).
+* 4. **`$dynamicRef`** — resolved via the active dynamic scope; falls back to
+*    `unknown` when the anchor is absent or the ref is a bare `#`.
+* 5. **Plain schema** — delegates to {@link getScalar} for all other cases
+*    (primitives, objects, arrays, enums, …).
+*/
 function resolveValue({ schema, name, context, formDataContext }) {
 	if (isReference(schema)) {
+		const alias = extractBoundAliasInfo(schema, context);
+		if (alias) {
+			const value = `${alias.genericName}<${alias.typeArgs.join(", ")}>`;
+			const allImports = [{
+				name: alias.genericName,
+				schemaName: alias.genericName
+			}, ...alias.imports];
+			return {
+				value,
+				imports: allImports,
+				type: "object",
+				schemas: [],
+				isEnum: false,
+				originalSchema: schema,
+				hasReadonlyProps: false,
+				isRef: true,
+				dependencies: allImports.map((i) => i.name)
+			};
+		}
 		const refValue = schema.$ref;
 		const { schema: schemaObject, imports } = resolveRef(schema, context);
 		if (refValue && !isComponentRef(refValue)) {
@@ -2232,12 +2600,44 @@ function resolveValue({ schema, name, context, formDataContext }) {
 		const resolvedImport = imports[0];
 		let hasReadonlyProps = false;
 		const refName = resolvedImport.name;
-		if (!context.parents?.includes(refName)) hasReadonlyProps = getScalar({
+		let effectiveContext = context;
+		const refAnchor = schemaObject.$dynamicAnchor;
+		if (typeof refAnchor === "string" && context.dynamicScope?.[refAnchor] && context.dynamicScope[refAnchor].name !== refName && !context.dynamicScope[refAnchor].isParameter) {
+			const scopeEntry = context.dynamicScope[refAnchor];
+			const allOf = ((context.spec.components?.schemas)?.[scopeEntry.schemaName])?.allOf;
+			if (!(Array.isArray(allOf) && allOf.some((el) => {
+				if (!el || typeof el !== "object") return false;
+				const rec = el;
+				if (typeof rec.$ref !== "string" || !isComponentRef(rec.$ref)) return false;
+				const { name } = getRefInfo(rec.$ref, context);
+				return name === refName;
+			}))) {
+				const filteredScope = Object.fromEntries(Object.entries(context.dynamicScope).filter(([key]) => key !== refAnchor));
+				effectiveContext = {
+					...context,
+					dynamicScope: filteredScope
+				};
+			}
+		}
+		if (!effectiveContext.parents?.includes(refName) && hasScopeAffectedDynamicRef(schemaObject, effectiveContext, refName)) return {
+			...getScalar({
+				item: schemaObject,
+				name: name ?? refName,
+				context: {
+					...effectiveContext,
+					parents: [...effectiveContext.parents ?? [], refName]
+				},
+				formDataContext
+			}),
+			originalSchema: schemaObject,
+			isRef: false
+		};
+		if (!effectiveContext.parents?.includes(refName)) hasReadonlyProps = getScalar({
 			item: schemaObject,
 			name: refName,
 			context: {
-				...context,
-				parents: [...context.parents ?? [], refName]
+				...effectiveContext,
+				parents: [...effectiveContext.parents ?? [], refName]
 			}
 		}).hasReadonlyProps;
 		const isAnyOfNullable = schemaObject.anyOf?.some((anyOfItem) => !isReference(anyOfItem) && (anyOfItem.type === "null" || Array.isArray(anyOfItem.type) && anyOfItem.type.includes("null")));
@@ -2258,6 +2658,25 @@ function resolveValue({ schema, name, context, formDataContext }) {
 			dependencies: [resolvedImport.name]
 		};
 	}
+	if (isDynamicReference(schema)) {
+		const dynamicRef = schema.$dynamicRef;
+		if (!dynamicRef.startsWith("#")) return makeUnknownValue(schema);
+		const anchorName = getDynamicAnchorName(dynamicRef);
+		if (!anchorName) return makeUnknownValue(schema);
+		const { imports: resolvedImports, resolvedTypeName } = resolveDynamicRef(anchorName, context);
+		if (resolvedTypeName === "unknown") return makeUnknownValue(schema);
+		return {
+			value: resolvedTypeName,
+			imports: resolvedImports,
+			type: "object",
+			isEnum: false,
+			schemas: [],
+			isRef: true,
+			hasReadonlyProps: false,
+			originalSchema: schema,
+			dependencies: [resolvedTypeName]
+		};
+	}
 	return {
 		...getScalar({
 			item: schema,
@@ -2349,7 +2768,8 @@ function resolveObject({ schema, propName, combined = false, context, formDataCo
 		propName,
 		combined,
 		projectName: context.projectName ?? context.output.target,
-		formDataContext
+		formDataContext,
+		dynamicScope: context.dynamicScope
 	});
 	if (resolveObjectCacheMap.has(hashKey)) return resolveObjectCacheMap.get(hashKey);
 	const result = resolveObjectOriginal({
@@ -3018,6 +3438,61 @@ function resolveDiscriminators(schemas, context) {
 			}
 		}
 	}
+	for (const [parentName, parentSchema] of Object.entries(transformedSchemas)) {
+		if (isBoolean$1(parentSchema)) continue;
+		if (!parentSchema.oneOf || !parentSchema.discriminator?.mapping) continue;
+		const { mapping, propertyName } = parentSchema.discriminator;
+		if (!propertyName) continue;
+		const parentProperties = parentSchema.properties;
+		const parentRequired = parentSchema.required;
+		const inheritableProps = {};
+		if (parentProperties) {
+			for (const [key, value] of Object.entries(parentProperties)) if (key !== propertyName) inheritableProps[key] = value;
+		}
+		const inheritableRequired = parentRequired?.filter((key) => key !== propertyName);
+		const hasInheritableProps = Object.keys(inheritableProps).length > 0;
+		for (const mappingValue of Object.values(mapping)) {
+			let variantSchema;
+			try {
+				const { originalName } = getRefInfo(mappingValue, context);
+				variantSchema = transformedSchemas[pascal(originalName)] ?? transformedSchemas[originalName];
+			} catch {
+				variantSchema = transformedSchemas[mappingValue];
+			}
+			if (!variantSchema || isBoolean$1(variantSchema)) continue;
+			const variantAllOf = variantSchema.allOf;
+			if (!variantAllOf) continue;
+			const rewritten = [];
+			for (const item of variantAllOf) {
+				if (!isReference(item) || !item.$ref) {
+					rewritten.push(item);
+					continue;
+				}
+				let refOriginalName;
+				try {
+					refOriginalName = getRefInfo(item.$ref, context).originalName;
+				} catch {
+					refOriginalName = void 0;
+				}
+				if (!(refOriginalName === parentName || refOriginalName !== void 0 && pascal(refOriginalName) === pascal(parentName))) {
+					rewritten.push(item);
+					continue;
+				}
+				const inlinedParent = { ...parentSchema };
+				delete inlinedParent.oneOf;
+				delete inlinedParent.discriminator;
+				delete inlinedParent.allOf;
+				delete inlinedParent.anyOf;
+				if (hasInheritableProps) inlinedParent.properties = { ...inheritableProps };
+				else delete inlinedParent.properties;
+				if (inheritableRequired && inheritableRequired.length > 0) inlinedParent.required = [...inheritableRequired];
+				else delete inlinedParent.required;
+				if (Object.keys(inlinedParent).filter((key) => key !== "type").length > 0) rewritten.push(inlinedParent);
+			}
+			if (rewritten.length === 0) delete variantSchema.allOf;
+			else variantSchema.allOf = rewritten;
+		}
+	}
 	return transformedSchemas;
 }
 //#endregion
@@ -3270,7 +3745,8 @@ function getQueryParamsTypes(queryParams, operationName, context) {
 		};
 		if (resolvedValue.isEnum && !resolvedValue.isRef) {
 			const enumName = queryName;
-			const enumValue = getEnum(resolvedValue.value, enumName, getEnumNames(resolvedValue.originalSchema), context.output.override.enumGenerationType, getEnumDescriptions(resolvedValue.originalSchema), context.output.override.namingConvention.enum);
+			const parameterAsSchema = parameter;
+			const enumValue = getEnum(resolvedValue.value, enumName, getEnumNames(resolvedValue.originalSchema) ?? getEnumNames(parameterAsSchema), context.output.override.enumGenerationType, getEnumDescriptions(resolvedValue.originalSchema) ?? getEnumDescriptions(parameterAsSchema), context.output.override.namingConvention.enum);
 			return {
 				name,
 				required,
@@ -3312,6 +3788,7 @@ function getQueryParams({ queryParams, operationName, context, suffix = "params"
 		},
 		deps: schemas,
 		isOptional: allOptional,
+		paramNames: types.map(({ name }) => name),
 		requiredNullableKeys,
 		...nonPrimitiveKeys.length > 0 ? { nonPrimitiveKeys } : {}
 	};
@@ -3470,6 +3947,231 @@ function generateComponentDefinition(responses = {}, context, suffix) {
 	return generatorSchemas;
 }
 //#endregion
+//#region src/generators/factory.ts
+const circularRefCache = /* @__PURE__ */ new WeakMap();
+function getSchemasPath(context) {
+	const { schemas, target } = context.output;
+	if (schemas) return normalizeSafe(isString(schemas) ? schemas : schemas.path);
+	const { dirname, filename } = getFileInfo(target);
+	return joinSafe(dirname, filename + ".schemas");
+}
+function getSchemaImportPath(refName, context) {
+	if (context.output.factoryMethods?.mode === "single") return;
+	let outputDir = context.output.factoryMethods?.outputDirectory;
+	let schemasPath = getSchemasPath(context);
+	if (context.output.workspace) {
+		if (outputDir && !isAbsolute(outputDir)) outputDir = resolve(context.output.workspace, outputDir);
+		if (schemasPath && !isAbsolute(schemasPath)) schemasPath = resolve(context.output.workspace, schemasPath);
+	}
+	return joinSafe(outputDir ? relativeSafe(outputDir, schemasPath) : "./", conventionName(refName, context.output.namingConvention));
+}
+function isReference$1(schema) {
+	return "$ref" in schema;
+}
+function getResolvedRef(schema, context) {
+	return resolveRef(schema, context);
+}
+function getProperties(schema) {
+	return schema.properties ?? {};
+}
+function getItems(schema) {
+	return schema.items;
+}
+function getAdditionalProperties(schema) {
+	return schema.additionalProperties;
+}
+function getSchemas(schemas) {
+	return schemas;
+}
+function getExtendedProps(schema) {
+	const extended = schema;
+	return {
+		constValue: extended.const,
+		prefixItems: extended.prefixItems,
+		minItems: extended.minItems
+	};
+}
+function generateFactory(schema, name, context) {
+	if (!canGenerateSchema(schema) || !context.output.factoryMethods) return void 0;
+	const { functionNamePrefix, mode } = context.output.factoryMethods;
+	const factoryName = `${functionNamePrefix}${pascal(name)}`;
+	const imports = [];
+	const payload = buildPayload(schema, context, [name], imports);
+	if (mode !== "single") {
+		const schemaImportPath = getSchemaImportPath(name, context);
+		imports.push({
+			name,
+			importPath: schemaImportPath
+		});
+	}
+	return {
+		model: `export function ${factoryName}(): ${name} {\n  return ${payload};\n}\n`,
+		imports
+	};
+}
+function canGenerateSchema(schema) {
+	return schema.type === "object" || schema.type === "array" || !!schema.properties || !!schema.allOf || !!schema.oneOf || !!schema.anyOf || !!schema.items || !!schema.enum;
+}
+function hasCircularReference(target, sourceName, context, visited = /* @__PURE__ */ new Set()) {
+	if (isReference$1(target)) {
+		const { imports, schema } = getResolvedRef(target, context);
+		const refName = imports[0]?.name;
+		if (refName === sourceName) return true;
+		if (refName && visited.has(refName)) return false;
+		if (refName) visited.add(refName);
+		let cache = circularRefCache.get(context);
+		if (!cache) {
+			cache = /* @__PURE__ */ new Map();
+			circularRefCache.set(context, cache);
+		}
+		const cacheKey = refName ? `${sourceName}::${refName}` : void 0;
+		if (cacheKey) {
+			const cached = cache.get(cacheKey);
+			if (cached !== void 0) return cached;
+		}
+		const result = hasCircularReference(schema, sourceName, context, visited);
+		if (cacheKey) cache.set(cacheKey, result);
+		return result;
+	}
+	const check = (schemas) => schemas?.some((s) => hasCircularReference(s, sourceName, context, visited)) ?? false;
+	const items = getItems(target);
+	const additionalProperties = getAdditionalProperties(target);
+	return check(getSchemas(target.allOf)) || check(getSchemas(target.oneOf)) || check(getSchemas(target.anyOf)) || Object.values(getProperties(target)).some((s) => hasCircularReference(s, sourceName, context, visited)) || !!items && hasCircularReference(items, sourceName, context, visited) || typeof additionalProperties === "object" && hasCircularReference(additionalProperties, sourceName, context, visited);
+}
+function buildPayload(target, context, parents, imports) {
+	if (isReference$1(target)) return buildRefPayload(target, context, parents, imports);
+	const schema = target;
+	if (schema.allOf) return buildAllOfPayload(getSchemas(schema.allOf) ?? [], context, parents, imports);
+	if (schema.oneOf) return buildFirstOfPayload(getSchemas(schema.oneOf) ?? [], context, parents, imports);
+	if (schema.anyOf) return buildFirstOfPayload(getSchemas(schema.anyOf) ?? [], context, parents, imports);
+	const { constValue } = getExtendedProps(schema);
+	if (constValue !== void 0) return formatValue(constValue);
+	if (schema.default !== void 0) return buildDefaultPayload(schema, context);
+	const schemaType = inferSchemaType(schema);
+	if (schemaType === "object" || schema.properties) return buildObjectPayload(schema, context, parents, imports);
+	if (schemaType === "array") return buildArrayPayload(schema, context, parents, imports);
+	return buildPrimitivePayload(schema, schemaType, context);
+}
+function buildRefPayload(schema, context, parents, imports) {
+	const { schema: resolved, imports: refImports } = getResolvedRef(schema, context);
+	const refName = refImports[0]?.name;
+	if (!refName) return "{}";
+	if (parents.includes(refName) || hasCircularReference(resolved, parents[0], context)) {
+		imports.push({
+			name: refName,
+			importPath: getSchemaImportPath(refName, context)
+		});
+		return `{} as ${refName}`;
+	}
+	const { functionNamePrefix = "create", mode = "single" } = context.output.factoryMethods ?? {};
+	const refFactoryName = `${functionNamePrefix}${pascal(refName)}`;
+	if (mode !== "single-split") {
+		const importPath = resolveImportPath(mode, refName, context);
+		imports.push({
+			name: refFactoryName,
+			importPath,
+			isConstant: true
+		});
+	}
+	imports.push({
+		name: refName,
+		importPath: getSchemaImportPath(refName, context)
+	});
+	return `${refFactoryName}()`;
+}
+function resolveImportPath(mode, refName, context) {
+	const baseName = conventionName(refName, context.output.namingConvention);
+	switch (mode) {
+		case "split": return `./${baseName}.factory`;
+		case "single-split": return `./${conventionName("factoryMethods", context.output.namingConvention)}`;
+		case "single": return `./${baseName}`;
+	}
+}
+function buildAllOfPayload(allOf, context, parents, imports) {
+	const payloads = allOf.map((s) => buildPayload(s, context, parents, imports));
+	return payloads.length > 0 ? `Object.assign({}, ${payloads.join(", ")})` : "{}";
+}
+function buildFirstOfPayload(schemas, context, parents, imports) {
+	const first = schemas[0];
+	return first ? buildPayload(first, context, parents, imports) : "{}";
+}
+function buildObjectPayload(schema, context, parents, imports) {
+	const { includeOptionalProperty = false } = context.output.factoryMethods ?? {};
+	const props = getProperties(schema);
+	const requiredProps = schema.required ?? [];
+	const entries = Object.entries(props);
+	if (context.output.propertySortOrder === PropertySortOrder.ALPHABETICAL) entries.sort(([a], [b]) => a.localeCompare(b));
+	const includeOptional = includeOptionalProperty;
+	const lines = [];
+	for (const [key, prop] of entries) {
+		const isRequired = requiredProps.includes(key);
+		const resolved = isReference$1(prop) ? getResolvedRef(prop, context).schema : prop;
+		const isReadOnly = !!prop.readOnly || !!resolved.readOnly;
+		const isWriteOnly = !!prop.writeOnly || !!resolved.writeOnly;
+		if (!isRequired) {
+			if (isReadOnly) continue;
+			if (!isWriteOnly && !includeOptional) continue;
+		}
+		const payload = buildPayload(prop, context, parents, imports);
+		const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+		lines.push(`${safeKey}: ${payload}`);
+	}
+	return `{\n    ${lines.join(",\n    ")}\n  }`;
+}
+function buildArrayPayload(schema, context, parents, imports) {
+	const { prefixItems, minItems } = getExtendedProps(schema);
+	const items = getItems(schema);
+	if (prefixItems && prefixItems.length > 0) return `[${prefixItems.map((item) => buildPayload(item, context, parents, imports)).join(", ")}]`;
+	if (minItems && items) {
+		const MAX_MIN_ITEMS = 50;
+		if (minItems > MAX_MIN_ITEMS) logWarning(`Warning: minItems is ${minItems}, capping at ${MAX_MIN_ITEMS} to prevent massive payload.`);
+		const count = Math.min(minItems, MAX_MIN_ITEMS);
+		const itemPayload = buildPayload(items, context, parents, imports);
+		return `[${Array.from({ length: count }).fill(itemPayload).join(", ")}]`;
+	}
+	return "[]";
+}
+function inferSchemaType(schema) {
+	let type = schema.type;
+	if (Array.isArray(type)) {
+		const nonNull = type.filter((t) => t !== "null");
+		type = nonNull.length > 0 ? nonNull[0] : "null";
+	}
+	if (!type && schema.items) return "array";
+	if (!type && schema.enum) {
+		const first = schema.enum[0];
+		if (typeof first === "number") return "number";
+		if (typeof first === "boolean") return "boolean";
+		return "string";
+	}
+	return type;
+}
+function buildDefaultPayload(schema, context) {
+	if (context.output.override.useDates && typeof schema.default === "string" && (schema.format === "date" || schema.format === "date-time")) return `new Date('${schema.default}')`;
+	return formatValue(schema.default);
+}
+function buildPrimitivePayload(schema, schemaType, context) {
+	if (schemaType === "null") return "null";
+	const enumValues = schema.enum;
+	if (schemaType === "boolean") return enumValues && enumValues.length > 0 ? String(enumValues[0]) : "false";
+	if (schemaType === "number" || schemaType === "integer") return enumValues && enumValues.length > 0 ? String(enumValues[0]) : "0";
+	if (schemaType === "string") {
+		if (enumValues && enumValues.length > 0) {
+			const first = enumValues[0];
+			return typeof first === "string" ? JSON.stringify(first) : String(first);
+		}
+		if (schema.format === "date" || schema.format === "date-time") return context.output.override.useDates ? "new Date(0)" : `'${(/* @__PURE__ */ new Date(0)).toISOString()}'`;
+		return "''";
+	}
+	return "undefined as unknown";
+}
+function formatValue(val) {
+	if (val === null) return "null";
+	if (typeof val === "string") return JSON.stringify(val);
+	if (typeof val === "object") return JSON.stringify(val);
+	return String(val);
+}
+//#endregion
 //#region src/generators/imports.ts
 function generateImports({ imports, namingConvention = NamingConvention.CAMEL_CASE, importExtension = "" }) {
 	if (imports.length === 0) return "";
@@ -3721,6 +4423,9 @@ function parseFile(file, name) {
 		return;
 	}
 }
+function standardMutatorInfo() {
+	return { numberOfParams: 1 };
+}
 function parseFunction(ast, funcName) {
 	const node = ast.body.find((childNode) => {
 		if (childNode.type === "VariableDeclaration") return childNode.declarations.find((d) => d.id.type === "Identifier" && d.id.name === funcName);
@@ -3745,6 +4450,7 @@ function parseFunction(ast, funcName) {
 	const declaration = "declarations" in node ? node.declarations.find((d) => d.id.type === "Identifier" && d.id.name === funcName) : void 0;
 	if (declaration?.init) {
 		if ("name" in declaration.init) return parseFunction(ast, declaration.init.name);
+		if (declaration.init.type === "CallExpression") return standardMutatorInfo();
 		if ("body" in declaration.init && "params" in declaration.init && declaration.init.body.type === "ArrowFunctionExpression") return {
 			numberOfParams: declaration.init.params.length,
 			returnNumberOfParams: declaration.init.body.params.length
@@ -4160,7 +4866,7 @@ function generateParameterDefinition(parameters = {}, context, suffix) {
 * @param name interface name
 * @param schema
 */
-function generateInterface({ name, schema, context }) {
+function generateInterface({ name, schema, context, genericParams }) {
 	const scalar = getScalar({
 		item: schema,
 		name,
@@ -4168,6 +4874,7 @@ function generateInterface({ name, schema, context }) {
 	});
 	const isEmptyObject = scalar.value === "{}";
 	const shouldUseTypeAlias = context.output.override.useTypeOverInterfaces ?? scalar.useTypeAlias;
+	const genericSuffix = genericParams && genericParams.length > 0 ? `<${genericParams.join(", ")}>` : "";
 	let model = "";
 	model += jsDoc(schema);
 	if (isEmptyObject) model += "// eslint-disable-next-line @typescript-eslint/no-empty-interface\n";
@@ -4175,12 +4882,12 @@ function generateInterface({ name, schema, context }) {
 		const properties = schema.properties;
 		if (properties && Object.values(properties).length > 0 && Object.values(properties).every((item) => "const" in item)) {
 			const mappedScalarValue = scalar.value.replaceAll(";", ",").replaceAll("?:", ":");
-			model += `export const ${name}Value = ${mappedScalarValue} as const;\nexport type ${name} = typeof ${name}Value;\n`;
+			model += `export const ${name}Value = ${mappedScalarValue} as const;\nexport type ${name}${genericSuffix} = typeof ${name}Value;\n`;
 		} else {
 			const blankInterfaceValue = scalar.value === "unknown" ? "{}" : scalar.value;
-			model += `export interface ${name} ${blankInterfaceValue}\n`;
+			model += `export interface ${name}${genericSuffix} ${blankInterfaceValue}\n`;
 		}
-	} else model += `export type ${name} = ${scalar.value};\n`;
+	} else model += `export type ${name}${genericSuffix} = ${scalar.value};\n`;
 	const externalModulesImportsOnly = scalar.imports.filter((importName) => importName.alias ? importName.alias !== name : importName.name !== name);
 	return [...scalar.schemas, {
 		name,
@@ -4214,6 +4921,17 @@ function generateSchemasDefinition(schemas = {}, context, suffix, filters) {
 		const normalizedName = conventionName(schema.name, context.output.namingConvention);
 		if (!seenNames.has(normalizedName)) {
 			seenNames.add(normalizedName);
+			if (context.output.factoryMethods && schema.schema) {
+				const factoryData = generateFactory(schema.schema, schema.name, context);
+				if (factoryData) if (context.output.factoryMethods.mode === "single") {
+					schema.model += `\n${factoryData.model}`;
+					for (const imp of factoryData.imports) if (!schema.imports.some((existing) => existing.name === imp.name)) schema.imports.push(imp);
+				} else {
+					schema.factory = factoryData.model;
+					schema.factoryImports = factoryData.imports;
+					schema.factoryMode = context.output.factoryMethods.mode;
+				}
+			}
 			deduplicatedModels.push(schema);
 		}
 	}
@@ -4258,6 +4976,21 @@ function shouldCreateInterface(schema) {
 	const isNullable = isArray(schema.type) && schema.type.includes("null");
 	return (!schema.type || schema.type === "object") && !schema.allOf && !schema.oneOf && !schema.anyOf && isDereferenced(schema) && !schema.enum && !isNullable;
 }
+function collectGenericParams(schema) {
+	const defs = schema.$defs;
+	if (!defs || typeof defs !== "object") return [];
+	const anchors = [];
+	for (const defSchema of Object.values(defs)) {
+		if (!defSchema || typeof defSchema !== "object") continue;
+		const rec = defSchema;
+		if (rec.$dynamicAnchor !== void 0 && rec.$ref === void 0) anchors.push(rec.$dynamicAnchor);
+	}
+	const uniqueNames = dynamicAnchorsToUniqueParamNames(anchors);
+	return anchors.map((anchor) => ({
+		anchorName: anchor,
+		paramName: uniqueNames.get(anchor) ?? dynamicAnchorToParamName(anchor)
+	}));
+}
 function generateSchemaDefinitions(schemaName, schema, context, suffix) {
 	const sanitizedSchemaName = sanitize(`${pascal(schemaName)}${suffix}`, {
 		underscore: "_",
@@ -4272,22 +5005,82 @@ function generateSchemaDefinitions(schemaName, schema, context, suffix) {
 		imports: [],
 		schema
 	}];
+	const alias = extractBoundAliasInfo(schema, context);
+	if (alias) {
+		const genericParams = alias.genericParams.map((paramName) => ({
+			anchorName: paramName,
+			paramName
+		}));
+		const genericSuffix = genericParams.length > 0 ? `<${genericParams.map((p) => p.paramName).join(", ")}>` : "";
+		const typeArgsStr = alias.typeArgs.join(", ");
+		const genericPart = `${alias.genericName}<${typeArgsStr}>`;
+		const schemaType = schema.type;
+		const nullable = Array.isArray(schemaType) && schemaType.includes("null") || schema.nullable === true ? " | null" : "";
+		let model;
+		const allImports = [{
+			name: alias.genericName,
+			schemaName: alias.genericName
+		}, ...alias.imports];
+		if (alias.extraSchemas && alias.extraSchemas.length > 0) {
+			const aliasScopedContext = {
+				...context,
+				dynamicScope: buildDynamicScope(schemaName, schema, context)
+			};
+			const subSchemas = [];
+			model = `export type ${sanitizedSchemaName}${genericSuffix} = (${[genericPart, ...alias.extraSchemas.map((extraSchema) => {
+				const resolved = resolveValue({
+					schema: extraSchema,
+					name: sanitizedSchemaName,
+					context: aliasScopedContext
+				});
+				for (const imp of resolved.imports) {
+					const impSchemaName = imp.schemaName ?? imp.name;
+					if (!allImports.some((a) => a.name === imp.name && a.schemaName === impSchemaName)) allImports.push({
+						name: imp.name,
+						schemaName: impSchemaName
+					});
+				}
+				for (const sub of resolved.schemas) if (sub.name !== sanitizedSchemaName) subSchemas.push(sub);
+				return resolved.value;
+			})].join(" & ")})${nullable};\n`;
+			return [...subSchemas, {
+				name: sanitizedSchemaName,
+				model,
+				imports: allImports,
+				dependencies: allImports.map((i) => i.name),
+				schema
+			}];
+		} else model = `export type ${sanitizedSchemaName}${genericSuffix} = ${genericPart}${nullable};\n`;
+		return [{
+			name: sanitizedSchemaName,
+			model,
+			imports: allImports,
+			dependencies: allImports.map((i) => i.name),
+			schema
+		}];
+	}
+	const scopedContext = isBoolean(schema) ? context : {
+		...context,
+		dynamicScope: buildDynamicScope(schemaName, schema, context)
+	};
+	const genericParams = collectGenericParams(schema);
 	if (shouldCreateInterface(schema)) return generateInterface({
 		name: sanitizedSchemaName,
 		schema,
-		context
+		context: scopedContext,
+		genericParams: genericParams.length > 0 ? genericParams.map((p) => p.paramName) : void 0
 	});
 	const resolvedValue = resolveValue({
 		schema,
 		name: sanitizedSchemaName,
-		context
+		context: scopedContext
 	});
 	let output = "";
 	let imports = resolvedValue.imports;
 	output += jsDoc(schema);
 	if (resolvedValue.isEnum && !resolvedValue.isRef) output += getEnum(resolvedValue.value, sanitizedSchemaName, getEnumNames(resolvedValue.originalSchema), context.output.override.enumGenerationType, getEnumDescriptions(resolvedValue.originalSchema), context.output.override.namingConvention.enum);
 	else if (sanitizedSchemaName === resolvedValue.value && resolvedValue.isRef) {
-		const { schema: referredSchema } = resolveRef(schema, context);
+		const { schema: referredSchema } = resolveRef(schema, scopedContext);
 		if (!shouldCreateInterface(referredSchema)) {
 			const imp = resolvedValue.imports.find((imp) => imp.name === sanitizedSchemaName);
 			if (imp) {
@@ -4308,7 +5101,8 @@ function generateSchemaDefinitions(schemaName, schema, context, suffix) {
 			resolvedValue.dependencies.push(...schema.dependencies ?? []);
 			return false;
 		});
-		output += `export type ${sanitizedSchemaName} = ${resolvedValue.value};\n`;
+		const genericSuffix = genericParams.length > 0 ? `<${genericParams.map((p) => p.paramName).join(", ")}>` : "";
+		output += `export type ${sanitizedSchemaName}${genericSuffix} = ${resolvedValue.value};\n`;
 	}
 	return [...resolvedValue.schemas, {
 		name: sanitizedSchemaName,
@@ -4620,33 +5414,54 @@ function getCanonicalMap(schemaGroups, schemaPath, namingConvention, fileExtensi
 		canonicalNameMap
 	};
 }
-function normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig) {
+function normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig, factoryOutputDirectory) {
 	const importExtension = getImportExtension(fileExtension, tsconfig);
-	for (const schema of schemas) schema.imports = schema.imports.map((imp) => {
-		const canonicalByName = canonicalNameMap.get(imp.name);
-		const resolvedImportKey = resolveImportKey(schemaPath, imp.importPath ?? `./${conventionName(imp.name, namingConvention)}`, fileExtension);
-		const canonicalByPath = canonicalPathMap.get(resolvedImportKey);
-		const canonical = canonicalByName ?? canonicalByPath;
-		if (!canonical?.importPath) return imp;
-		const relative = relativeSafe(schemaPath, canonical.importPath.replaceAll("\\", "/"));
-		const importPath = `${relative.endsWith(fileExtension) ? relative.slice(0, -fileExtension.length) : relative.replace(/\.ts$/, "")}${importExtension}`;
-		return {
-			...imp,
-			importPath
-		};
-	});
+	const factoryDir = factoryOutputDirectory ?? schemaPath;
+	for (const schema of schemas) {
+		schema.imports = schema.imports.map((imp) => {
+			const canonicalByName = canonicalNameMap.get(imp.name);
+			const resolvedImportKey = resolveImportKey(schemaPath, imp.importPath ?? `./${conventionName(imp.name, namingConvention)}`, fileExtension);
+			const canonicalByPath = canonicalPathMap.get(resolvedImportKey);
+			const canonical = canonicalByName ?? canonicalByPath;
+			if (!canonical?.importPath) return imp;
+			const relative = relativeSafe(schemaPath, canonical.importPath.replaceAll("\\", "/"));
+			const importPath = `${relative.endsWith(fileExtension) ? relative.slice(0, -fileExtension.length) : relative.replace(/\.ts$/, "")}${importExtension}`;
+			return {
+				...imp,
+				importPath
+			};
+		});
+		if (schema.factoryImports) schema.factoryImports = schema.factoryImports.map((imp) => {
+			const canonicalByName = canonicalNameMap.get(imp.name);
+			const resolvedImportKey = resolveImportKey(factoryDir, imp.importPath ?? `./${conventionName(imp.name, namingConvention)}`, fileExtension);
+			const canonicalByPath = canonicalPathMap.get(resolvedImportKey);
+			const canonical = canonicalByName ?? canonicalByPath;
+			if (!canonical?.importPath) return imp;
+			const relative = relativeSafe(factoryDir, canonical.importPath.replaceAll("\\", "/"));
+			const importPath = `${relative.endsWith(fileExtension) ? relative.slice(0, -fileExtension.length) : relative.replace(/\.ts$/, "")}${importExtension}`;
+			return {
+				...imp,
+				importPath
+			};
+		});
+	}
 }
 function mergeSchemaGroup(schemas) {
 	const baseSchemaName = schemas[0].name;
 	const baseSchema = schemas[0].schema;
 	const mergedImports = [...new Map(schemas.flatMap((schema) => schema.imports).map((imp) => [JSON.stringify(imp), imp])).values()];
 	const mergedDependencies = [...new Set(schemas.flatMap((schema) => schema.dependencies ?? []))];
+	const mergedFactory = schemas.map((s) => s.factory).filter(Boolean).join("\n");
+	const mergedFactoryImports = [...new Map(schemas.flatMap((schema) => schema.factoryImports ?? []).map((imp) => [JSON.stringify(imp), imp])).values()];
 	return {
 		name: baseSchemaName,
 		schema: baseSchema,
 		model: schemas.map((schema) => schema.model).join("\n"),
 		imports: mergedImports,
-		dependencies: mergedDependencies
+		dependencies: mergedDependencies,
+		factory: mergedFactory || void 0,
+		factoryImports: mergedFactoryImports,
+		factoryMode: schemas[0].factoryMode
 	};
 }
 function resolveImportKey(schemaPath, importPath, fileExtension) {
@@ -4688,10 +5503,39 @@ async function writeSchema({ path, schema, target, namingConvention, fileExtensi
 		throw new Error(`Oups... 🍻. An Error occurred while writing schema ${name} => ${String(error)}`, { cause: error });
 	}
 }
-async function writeSchemas({ schemaPath, schemas, target, namingConvention, fileExtension, header, indexFiles, tsconfig }) {
+async function emitFactoryForSchema(schema, namingConvention, header, factoryDir, fileExtension, helpers) {
+	if (schema.factory && schema.factoryMode) {
+		const mode = schema.factoryMode;
+		if (mode === "split") {
+			const factoryName = `${conventionName(schema.name, namingConvention)}.factory`;
+			helpers.separateFactoryNames.push(factoryName);
+			const factoryFile = `${header}\n${generateImports({
+				imports: schema.factoryImports ?? [],
+				namingConvention
+			})}\n\n${schema.factory}`;
+			await writeGeneratedFile(getPath(factoryDir, factoryName, fileExtension), factoryFile);
+		} else if (mode === "single-split") {
+			helpers.isCombined.value = true;
+			helpers.combinedFactoryContent.value += `${schema.factory}\n`;
+			helpers.combinedFactoryImports.push(...schema.factoryImports ?? []);
+		}
+	}
+}
+async function writeSchemas({ schemaPath, schemas, target, namingConvention, fileExtension, header, indexFiles, tsconfig, factoryOutputDirectory }) {
 	const schemaGroups = getSchemaGroups(schemaPath, schemas, namingConvention, fileExtension);
 	const { canonicalPathMap, canonicalNameMap } = getCanonicalMap(schemaGroups, schemaPath, namingConvention, fileExtension);
-	normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig);
+	normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig, factoryOutputDirectory);
+	const factoryDir = factoryOutputDirectory ?? schemaPath;
+	const combinedFactoryContent = { value: "" };
+	const combinedFactoryImports = [];
+	const isCombined = { value: false };
+	const separateFactoryNames = [];
+	const factoryHelpers = {
+		separateFactoryNames,
+		combinedFactoryContent,
+		combinedFactoryImports,
+		isCombined
+	};
 	for (const groupSchemas of Object.values(schemaGroups)) {
 		if (groupSchemas.length === 1) {
 			await writeSchema({
@@ -4703,17 +5547,29 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 				header,
 				tsconfig
 			});
+			const singleSchema = groupSchemas[0];
+			await emitFactoryForSchema(singleSchema, namingConvention, header, factoryDir, fileExtension, factoryHelpers);
 			continue;
 		}
+		const mergedSchema = mergeSchemaGroup(groupSchemas);
 		await writeSchema({
 			path: schemaPath,
-			schema: mergeSchemaGroup(groupSchemas),
+			schema: mergedSchema,
 			target,
 			namingConvention,
 			fileExtension,
 			header,
 			tsconfig
 		});
+		await emitFactoryForSchema(mergedSchema, namingConvention, header, factoryDir, fileExtension, factoryHelpers);
+	}
+	if (isCombined.value) {
+		const factoryFileName = conventionName("factoryMethods", namingConvention);
+		const factoryFile = `${header}\n${generateImports({
+			imports: combinedFactoryImports,
+			namingConvention
+		})}\n\n${combinedFactoryContent.value}`;
+		await writeGeneratedFile(getPath(factoryDir, factoryFileName, fileExtension), factoryFile);
 	}
 	if (indexFiles) {
 		const schemaFilePath = nodePath.join(schemaPath, `index.ts`);
@@ -4721,7 +5577,25 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 		const ext = getImportExtension(fileExtension, tsconfig);
 		const conventionNamesSet = new Set(Object.values(schemaGroups).map((group) => conventionName(group[0].name, namingConvention)));
 		try {
-			await writeGeneratedFile(schemaFilePath, `${header}\n${[...conventionNamesSet].map((schemaName) => `export * from './${schemaName}${ext}';`).toSorted((a, b) => a.localeCompare(b, "en", { numeric: true })).join("\n")}\n`);
+			const currentExports = [...conventionNamesSet].map((schemaName) => `export * from './${schemaName}${ext}';`);
+			if (factoryOutputDirectory && normalizeSafe(factoryOutputDirectory) !== normalizeSafe(schemaPath) && (isCombined.value || separateFactoryNames.length > 0)) {
+				const factoryIndexFilePath = nodePath.join(factoryOutputDirectory, `index.ts`);
+				await fs$1.ensureFile(factoryIndexFilePath);
+				const factoryExports = [];
+				if (isCombined.value) {
+					const factoryFileName = conventionName("factoryMethods", namingConvention);
+					factoryExports.push(`export * from './${factoryFileName}${ext}';`);
+				}
+				for (const fName of separateFactoryNames) factoryExports.push(`export * from './${fName}${ext}';`);
+				await writeGeneratedFile(factoryIndexFilePath, `${header}\n${factoryExports.join("\n")}\n`);
+			} else {
+				if (isCombined.value) {
+					const factoryFileName = conventionName("factoryMethods", namingConvention);
+					currentExports.push(`export * from './${factoryFileName}${ext}';`);
+				}
+				for (const fName of separateFactoryNames) currentExports.push(`export * from './${fName}${ext}';`);
+			}
+			await writeGeneratedFile(schemaFilePath, `${header}\n${[...new Set(currentExports)].toSorted((a, b) => a.localeCompare(b, "en", { numeric: true })).join("\n")}\n`);
 		} catch (error) {
 			throw new Error(`Oups... 🍻. An Error occurred while writing schema index file ${schemaFilePath} => ${String(error)}`, { cause: error });
 		}
@@ -4731,6 +5605,13 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 //#region src/writers/generate-imports-for-builder.ts
 function generateImportsForBuilder(output, imports, relativeSchemasPath) {
 	const isZodSchemaOutput = isObject(output.schemas) && output.schemas.type === "zod";
+	const schemaFactoryImports = imports.filter((i) => i.schemaFactory);
+	const schemaFactoryImportExtension = getImportExtension(output.fileExtension, output.tsconfig);
+	const schemaFactoryDeps = schemaFactoryImports.length > 0 ? [{
+		exports: uniqueBy(schemaFactoryImports, (entry) => `${entry.name}|${entry.alias ?? ""}`),
+		dependency: joinSafe(relativeSchemasPath, `index.faker${schemaFactoryImportExtension}`)
+	}] : [];
+	imports = imports.filter((i) => !i.schemaFactory);
 	let schemaImports;
 	if (output.indexFiles) schemaImports = isZodSchemaOutput ? [{
 		exports: imports.filter((i) => !i.importPath),
@@ -4757,7 +5638,11 @@ function generateImportsForBuilder(output, imports, relativeSchemasPath) {
 			dependency: i.importPath
 		};
 	});
-	return [...schemaImports, ...otherImports];
+	return [
+		...schemaImports,
+		...schemaFactoryDeps,
+		...otherImports
+	];
 }
 //#endregion
 //#region src/writers/mock-outputs.ts
@@ -5475,6 +6360,6 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 	}))).flat();
 }
 //#endregion
-export { BODY_TYPE_NAME, DefaultTag, EnumGeneration, ErrorWithTag, FormDataArrayHandling, GetterPropType, LogLevels, NAMED_COMPONENT_SECTIONS, NamingConvention, OutputClient, OutputHttpClient, OutputMockType, OutputMode, PropertySortOrder, RefComponentSuffix, SchemaType, SupportedFormatter, TEMPLATE_TAG_REGEX, URL_REGEX, VERBS_WITH_BODY, Verbs, addDependency, asyncReduce, buildAngularParamsFilterExpression, camel, collectReferencedComponents, combineSchemas, compareVersions, conventionName, count, createDebugger, createLogger, createSuccessMessage, createTypeAliasIfNeeded, dedupeUnionType, dynamicImport, escape, escapeRegExp, filterByContentType, filteredVerbs, fixCrossDirectoryImports, fixRegularSchemaImports, generalJSTypes, generalJSTypesWithArray, generateAxiosOptions, generateBodyMutatorConfig, generateBodyOptions, generateComponentDefinition, generateDependencyImports, generateFormDataAndUrlEncodedFunction, generateImports, generateModelInline, generateModelsInline, generateMutator, generateMutatorConfig, generateMutatorImports, generateMutatorRequestOptions, generateOptions, generateParameterDefinition, generateQueryParamsAxiosConfig, generateSchemasDefinition, generateTarget, generateTargetForTags, generateVerbImports, generateVerbOptions, generateVerbsOptions, getAngularFilteredParamsCallExpression, getAngularFilteredParamsExpression, getAngularFilteredParamsHelperBody, getArray, getBaseUrlRuntimeImports, getBodiesByContentType, getBody, getCombinedEnumValue, getDefaultContentType, getEnum, getEnumDescriptions, getEnumImplementation, getEnumNames, getEnumUnionFromSchema, getExtension, getFileInfo, getFormDataFieldFileType, getFullRoute, getImportExtension, getIsBodyVerb, getKey, getMockFileExtensionByTypeName, getNumberWord, getObject, getOperationId, getOrvalGeneratedTypes, getParameters, getParams, getParamsInPath, getPropertySafe, getProps, getQueryParams, getRefInfo, getResReqTypes, getResponse, getResponseTypeCategory, getRoute, getRouteAsArray, getScalar, getSuccessResponseType, getTypedResponse, getWarningCount, isBinaryContentType, isBinaryScalarSchema, isBoolean, isComponentRef, isDirectory, isFakerMock, isFunction, isModule, isMswMock, isNullish, isNumber, isNumeric, isObject, isReference, isSchema, isString, isStringLike, isSyntheticDefaultImportsAllow, isUrl, isVerb, isVerbose, jsDoc, jsStringEscape, kebab, keyValuePairsToJsDoc, log, logError, logVerbose, logWarning, makeRouteSafe, mergeDeep, mismatchArgsMessage, pascal, removeFilesAndEmptyFolders, resetWarnings, resolveDiscriminators, resolveExampleRefs, resolveInstalledVersion, resolveInstalledVersions, resolveObject, resolveRef, resolveValue, sanitize, setVerbose, snake, sortByPriority, splitSchemasByType, startMessage, stringify, toObjectString, path_exports as upath, upper, wrapRouteParameters, writeModelInline, writeModelsInline, writeSchema, writeSchemas, writeSingleMode, writeSplitMode, writeSplitTagsMode, writeTagsMode };
+export { BODY_TYPE_NAME, DefaultTag, EnumGeneration, ErrorWithTag, FormDataArrayHandling, GetterPropType, LogLevels, NAMED_COMPONENT_SECTIONS, NamingConvention, OutputClient, OutputHttpClient, OutputMockType, OutputMode, PropertySortOrder, RefComponentSuffix, SchemaType, SupportedFormatter, TEMPLATE_TAG_REGEX, URL_REGEX, VERBS_WITH_BODY, Verbs, addDependency, asyncReduce, buildAngularParamsFilterExpression, buildDynamicScope, camel, collectReferencedComponents, combineSchemas, compareVersions, conventionName, count, createDebugger, createLogger, createSuccessMessage, createTypeAliasIfNeeded, dedupeUnionType, dynamicAnchorToParamName, dynamicAnchorsToUniqueParamNames, dynamicImport, escape, escapeRegExp, extractBoundAliasInfo, filterByContentType, filteredVerbs, fixCrossDirectoryImports, fixRegularSchemaImports, generalJSTypes, generalJSTypesWithArray, generateAxiosOptions, generateBodyMutatorConfig, generateBodyOptions, generateComponentDefinition, generateDependencyImports, generateFactory, generateFormDataAndUrlEncodedFunction, generateImports, generateModelInline, generateModelsInline, generateMutator, generateMutatorConfig, generateMutatorImports, generateMutatorRequestOptions, generateOptions, generateParameterDefinition, generateQueryParamsAxiosConfig, generateSchemasDefinition, generateTarget, generateTargetForTags, generateVerbImports, generateVerbOptions, generateVerbsOptions, getAngularFilteredParamsCallExpression, getAngularFilteredParamsExpression, getAngularFilteredParamsHelperBody, getArray, getBaseUrlRuntimeImports, getBodiesByContentType, getBody, getCombinedEnumValue, getDefaultContentType, getDynamicAnchorName, getEnum, getEnumDescriptions, getEnumImplementation, getEnumNames, getEnumUnionFromSchema, getExtension, getFileInfo, getFormDataFieldFileType, getFullRoute, getImportExtension, getIsBodyVerb, getKey, getMockFileExtensionByTypeName, getNumberWord, getObject, getOperationId, getOrvalGeneratedTypes, getParameters, getParams, getParamsInPath, getPropertySafe, getProps, getQueryParams, getRefInfo, getResReqTypes, getResponse, getResponseTypeCategory, getRoute, getRouteAsArray, getScalar, getSuccessResponseType, getTypedResponse, getWarningCount, isBinaryContentType, isBinaryScalarSchema, isBoolean, isComponentRef, isDirectory, isDynamicReference, isFakerMock, isFunction, isModule, isMswMock, isNullish, isNumber, isNumeric, isObject, isReference, isSchema, isString, isStringLike, isSyntheticDefaultImportsAllow, isUrl, isVerb, isVerbose, jsDoc, jsStringEscape, kebab, keyValuePairsToJsDoc, log, logError, logVerbose, logWarning, makeRouteSafe, mergeDeep, mismatchArgsMessage, pascal, removeFilesAndEmptyFolders, resetWarnings, resolveDiscriminators, resolveDynamicRef, resolveExampleRefs, resolveInstalledVersion, resolveInstalledVersions, resolveObject, resolveRef, resolveValue, sanitize, setVerbose, snake, sortByPriority, splitSchemasByType, startMessage, stringify, toObjectString, path_exports as upath, upper, wrapRouteParameters, writeGeneratedFile, writeModelInline, writeModelsInline, writeSchema, writeSchemas, writeSingleMode, writeSplitMode, writeSplitTagsMode, writeTagsMode };
 
 //# sourceMappingURL=index.mjs.map