@orval/core 8.9.1 → 8.11.0

package/dist/index.mjs

@@ -77,6 +77,10 @@ const Verbs = {
 	DELETE: "delete",
 	HEAD: "head"
 };
+/**
+* Canonical tag name used for the generated bucket that collects untagged operations.
+*/
+const DefaultTag = "default";
 const GetterPropType = {
 	PARAM: "param",
 	NAMED_PATH_PARAMS: "namedPathParams",
@@ -362,6 +366,29 @@ function createDebugger(ns, options = {}) {
 const search = String.raw`\*/`;
 const replacement = String.raw`*\/`;
 const regex$1 = new RegExp(search, "g");
+const itemValidationKeys = [
+	"minLength",
+	"maxLength",
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"minItems",
+	"maxItems",
+	"pattern"
+];
+function getItemValidationDocEntries(schema, prefix = "items", visited = /* @__PURE__ */ new WeakSet()) {
+	if (!schema) return [];
+	if (visited.has(schema)) return [];
+	visited.add(schema);
+	return [...itemValidationKeys.flatMap((key) => {
+		const value = schema[key];
+		return value === void 0 ? [] : [{
+			key: `${prefix}.${key}`,
+			value
+		}];
+	}), ...getItemValidationDocEntries(schema.items, `${prefix}.items`, visited)];
+}
 function jsDoc(schema, tryOneLine = false, context) {
 	if (context?.output.override.jsDoc) {
 		const { filter } = context.output.override.jsDoc;
@@ -369,6 +396,7 @@ function jsDoc(schema, tryOneLine = false, context) {
 	}
 	const { description, deprecated, summary, minLength, maxLength, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minItems, maxItems, pattern } = schema;
 	const isNullable = schema.type === "null" || Array.isArray(schema.type) && schema.type.includes("null");
+	const itemValidationDocEntries = getItemValidationDocEntries(schema.items);
 	const lines = (Array.isArray(description) ? description.filter((d) => !d.includes("eslint-disable")) : [description ?? ""]).map((line) => line.replaceAll(regex$1, replacement));
 	const count = [
 		description,
@@ -383,7 +411,8 @@ function jsDoc(schema, tryOneLine = false, context) {
 		minItems?.toString(),
 		maxItems?.toString(),
 		isNullable ? "null" : "",
-		pattern
+		pattern,
+		...itemValidationDocEntries.map(({ value }) => value.toString())
 	].filter(Boolean).length;
 	if (!count) return "";
 	const oneLine = count === 1 && tryOneLine;
@@ -426,6 +455,17 @@ function jsDoc(schema, tryOneLine = false, context) {
 	tryAppendNumberDocLine("maxItems", maxItems);
 	tryAppendBooleanDocLine("nullable", isNullable);
 	tryAppendStringDocLine("pattern", pattern);
+	for (const { key, value } of itemValidationDocEntries) {
+		if (typeof value === "string") {
+			tryAppendStringDocLine(key, value);
+			continue;
+		}
+		if (typeof value === "number") {
+			tryAppendNumberDocLine(key, value);
+			continue;
+		}
+		tryAppendBooleanDocLine(key, value);
+	}
 	doc += oneLine ? " " : `\n ${tryOneLine ? "  " : ""}`;
 	doc += "*/\n";
 	return doc;
@@ -1001,6 +1041,24 @@ function isSyntheticDefaultImportsAllow(config) {
 	if (!config) return true;
 	return !!(config.compilerOptions?.allowSyntheticDefaultImports ?? config.compilerOptions?.esModuleInterop);
 }
+const NODE_NEXT_MODULES = new Set(["nodenext", "node16"]);
+const NODE_NEXT_EXTENSION_MAP = [
+	[".tsx", ".jsx"],
+	[".mts", ".mjs"],
+	[".cts", ".cjs"],
+	[".ts", ".js"]
+];
+function getImportExtension(fileExtension, tsconfig) {
+	const compilerOptions = tsconfig?.compilerOptions;
+	if (compilerOptions?.allowImportingTsExtensions) return fileExtension;
+	const module = compilerOptions?.module?.toLowerCase();
+	const moduleResolution = compilerOptions?.moduleResolution?.toLowerCase();
+	if (module && NODE_NEXT_MODULES.has(module) || moduleResolution && NODE_NEXT_MODULES.has(moduleResolution)) {
+		for (const [from, to] of NODE_NEXT_EXTENSION_MAP) if (fileExtension.endsWith(from)) return `${fileExtension.slice(0, -from.length)}${to}`;
+		return fileExtension;
+	}
+	return fileExtension.replace(/\.ts$/, "") || "";
+}
 //#endregion
 //#region src/getters/enum.ts
 /**
@@ -1210,12 +1268,34 @@ function getCombinedEnumValue(inputs) {
 }
 //#endregion
 //#region src/getters/ref.ts
+/**
+* `$ref`s targeting these sections under `#/components/...` are emitted as
+* named TypeScript imports (e.g. `import type { Pet } from './model'`).
+* Refs to any other location — for example `#/paths/.../schema` produced by
+* JSON-Schema-Ref-Parser `bundle()` — have no corresponding `export type`
+* and must be inlined by the resolver. See issue #398.
+*/
+const NAMED_COMPONENT_SECTIONS = [
+	"schemas",
+	"responses",
+	"parameters",
+	"requestBodies"
+];
 const RefComponentSuffix = {
 	schemas: "",
 	responses: "Response",
 	parameters: "Parameter",
 	requestBodies: "Body"
 };
+const COMPONENT_REF_PATTERN = new RegExp(String.raw`^#\/components\/(${NAMED_COMPONENT_SECTIONS.join("|")})\/[^/]+$`);
+/**
+* True iff `ref` targets a named slot eligible for emission as a TypeScript
+* import. Used by `resolveValue` to decide between named import vs inlining
+* the resolved schema.
+*/
+function isComponentRef(ref) {
+	return COMPONENT_REF_PATTERN.test(ref);
+}
 const regex = /* @__PURE__ */ new RegExp("~1", "g");
 /**
 * Return the output type from the $ref
@@ -1358,7 +1438,34 @@ function resolveExampleRefs(examples, context) {
 //#region src/resolvers/value.ts
 function resolveValue({ schema, name, context, formDataContext }) {
 	if (isReference(schema)) {
+		const refValue = schema.$ref;
 		const { schema: schemaObject, imports } = resolveRef(schema, context);
+		if (refValue && !isComponentRef(refValue)) {
+			if (context.parents?.includes(refValue)) return {
+				value: "unknown",
+				imports: [],
+				schemas: [],
+				type: "unknown",
+				isEnum: false,
+				originalSchema: schemaObject,
+				hasReadonlyProps: false,
+				isRef: false,
+				dependencies: []
+			};
+			return {
+				...getScalar({
+					item: schemaObject,
+					name,
+					context: {
+						...context,
+						parents: [...context.parents ?? [], refValue]
+					},
+					formDataContext
+				}),
+				originalSchema: schemaObject,
+				isRef: false
+			};
+		}
 		const resolvedImport = imports[0];
 		let hasReadonlyProps = false;
 		const refName = resolvedImport.name;
@@ -1543,7 +1650,7 @@ function getArray({ schema, name, context, formDataContext }) {
 			formDataContext
 		});
 		return {
-			value: `${schema.readOnly === true && !context.output.override.suppressReadonlyModifier ? "readonly " : ""}${resolvedObject.value.includes("|") ? `(${resolvedObject.value})[]` : `${resolvedObject.value}[]`}`,
+			value: `${schema.readOnly === true && !context.output.override.suppressReadonlyModifier ? "readonly " : ""}${resolvedObject.value.includes("|") || resolvedObject.value.includes("&") ? `(${resolvedObject.value})[]` : `${resolvedObject.value}[]`}`,
 			imports: resolvedObject.imports,
 			schemas: resolvedObject.schemas,
 			dependencies: resolvedObject.dependencies,
@@ -1568,7 +1675,7 @@ function getArray({ schema, name, context, formDataContext }) {
 }
 //#endregion
 //#region src/getters/res-req-types.ts
-const getSchemaType = (s) => s.type;
+const getSchemaType$1 = (s) => s.type;
 const getSchemaCombined = (s) => s.oneOf ?? s.anyOf ?? s.allOf;
 const getSchemaOneOf = (s) => s.oneOf;
 const getSchemaAnyOf = (s) => s.anyOf;
@@ -1957,7 +2064,7 @@ function resolveSchemaPropertiesToFormData({ schema, variableName, propName, con
     ${resolvedValue}});\n`;
 				} else valueStr = "JSON.stringify(value)";
 				else {
-					const itemType = getSchemaType(itemSchema);
+					const itemType = getSchemaType$1(itemSchema);
 					if (itemType === "number" || Array.isArray(itemType) && itemType.includes("number") || itemType === "integer" || Array.isArray(itemType) && itemType.includes("integer") || itemType === "boolean" || Array.isArray(itemType) && itemType.includes("boolean")) valueStr = "value.toString()";
 				}
 			}
@@ -1965,7 +2072,7 @@ function resolveSchemaPropertiesToFormData({ schema, variableName, propName, con
 				if (!hasNonPrimitiveChild) formDataValue = `${valueKey}.forEach((value, index${depth > 0 ? depth : ""}) => ${variableName}.append(\`${keyPrefix}${key}[\${index${depth > 0 ? depth : ""}}]\`, ${valueStr}));\n`;
 			} else formDataValue = `${valueKey}.forEach(value => ${variableName}.append(\`${keyPrefix}${key}${context.output.override.formData.arrayHandling === FormDataArrayHandling.SERIALIZE_WITH_BRACKETS ? "[]" : ""}\`, ${valueStr}));\n`;
 		} else if ((() => {
-			const propType = getSchemaType(property);
+			const propType = getSchemaType$1(property);
 			return propType === "number" || Array.isArray(propType) && propType.includes("number") || propType === "integer" || Array.isArray(propType) && propType.includes("integer") || propType === "boolean" || Array.isArray(propType) && propType.includes("boolean");
 		})()) formDataValue = `${variableName}.append(\`${keyPrefix}${key}\`, ${nonOptionalValueKey}.toString())\n`;
 		else formDataValue = `${variableName}.append(\`${keyPrefix}${key}\`, ${nonOptionalValueKey});\n`;
@@ -1989,7 +2096,7 @@ function resolveSchemaPropertiesToFormData({ schema, variableName, propName, con
 			})) existSubSchemaNullable = true;
 		}
 		const isRequired = getSchemaRequired(schema)?.includes(key) && !isRequestBodyOptional;
-		const propType = getSchemaType(property);
+		const propType = getSchemaType$1(property);
 		if (property.nullable || Array.isArray(propType) && propType.includes("null") || existSubSchemaNullable) {
 			if (isRequired) {
 				formDataValues += `if(${valueKey} !== null) {\n ${formDataValue} }\n`;
@@ -2108,30 +2215,59 @@ function getKey(key) {
 }
 //#endregion
 //#region src/getters/object.ts
+function getPropertyNamesEnumKeyType(item) {
+	if (!("propertyNames" in item) || !item.propertyNames) return;
+	const propertyNames = item.propertyNames;
+	if (Array.isArray(propertyNames.enum)) {
+		const enumValues = propertyNames.enum.filter((val) => isString(val));
+		if (enumValues.length > 0) return {
+			value: enumValues.map((val) => `'${escape(val)}'`).join(" | "),
+			imports: [],
+			dependencies: []
+		};
+	}
+	if (isString(propertyNames.const)) return {
+		value: `'${escape(propertyNames.const)}'`,
+		imports: [],
+		dependencies: []
+	};
+}
 /**
-* Extract enum values from propertyNames schema (OpenAPI 3.1)
-* Handles both `enum` and `const` (treated as a single-element enum)
-* Returns undefined if propertyNames has neither
+* Resolve a narrowed key type from OpenAPI 3.1 propertyNames.
+* Supports inline enum/const and $ref string enums.
 */
-function getPropertyNamesEnum(item) {
-	if (!("propertyNames" in item) || !item.propertyNames) return;
+function getPropertyNamesKeyType(item, context) {
+	const inlineKeyType = getPropertyNamesEnumKeyType(item);
+	if (inlineKeyType) return inlineKeyType;
 	const propertyNames = item.propertyNames;
-	if (Array.isArray(propertyNames.enum)) return propertyNames.enum.filter((val) => isString(val));
-	if (isString(propertyNames.const)) return [propertyNames.const];
+	if (!propertyNames || !isReference(propertyNames)) return;
+	const resolvedValue = resolveValue({
+		schema: propertyNames,
+		context
+	});
+	const resolvedConst = resolvedValue.originalSchema.const;
+	const isStringConst = resolvedValue.type === "string" && isString(resolvedConst);
+	if (!resolvedValue.isEnum && !isStringConst) return;
+	return {
+		value: resolvedValue.value,
+		imports: resolvedValue.imports,
+		dependencies: resolvedValue.dependencies
+	};
 }
 /**
 * Generate index signature key type based on propertyNames enum or const
 * Returns union type string like "'foo' | 'bar'", "'x'", or 'string' if neither
 */
 function getIndexSignatureKey(item) {
-	const enumValues = getPropertyNamesEnum(item);
-	if (enumValues && enumValues.length > 0) return enumValues.map((val) => `'${val}'`).join(" | ");
-	return "string";
+	return getPropertyNamesEnumKeyType(item)?.value ?? "string";
 }
-function getPropertyNamesRecordType(item, valueType) {
-	const enumValues = getPropertyNamesEnum(item);
-	if (!enumValues || enumValues.length === 0) return;
-	return `Partial<Record<${enumValues.map((val) => `'${val}'`).join(" | ")}, ${valueType}>>`;
+function getPropertyNamesRecordType(item, valueType, context) {
+	const keyType = getPropertyNamesKeyType(item, context);
+	if (!keyType) return;
+	return {
+		...keyType,
+		value: `Partial<Record<${keyType.value}, ${valueType}>>`
+	};
 }
 /**
 * Return the output type from an object
@@ -2185,7 +2321,7 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 	if (itemProperties && Object.entries(itemProperties).length > 0) {
 		const entries = Object.entries(itemProperties);
 		if (context.output.propertySortOrder === PropertySortOrder.ALPHABETICAL) entries.sort((a, b) => {
-			return a[0].localeCompare(b[0]);
+			return a[0].localeCompare(b[0], "en", { numeric: true });
 		});
 		const acc = {
 			imports: [],
@@ -2224,7 +2360,7 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 			if (!index) acc.value += "{";
 			const doc = jsDoc(schema, true, context);
 			const propertyDoc = doc ? `${doc.trimEnd().split("\n").map((line) => `  ${line}`).join("\n")}\n` : "";
-			if (isReadOnly) acc.hasReadonlyProps = true;
+			if (isReadOnly || resolvedValue.hasReadonlyProps) acc.hasReadonlyProps = true;
 			const constValue = "const" in schema ? schema.const : void 0;
 			const hasConst = constValue !== void 0;
 			let constLiteral;
@@ -2257,11 +2393,13 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 			if (entries.length - 1 === index) {
 				const additionalProps = schemaItem.additionalProperties;
 				if (additionalProps) if (additionalProps === true) {
-					const recordType = getPropertyNamesRecordType(schemaItem, "unknown");
+					const recordType = getPropertyNamesRecordType(schemaItem, "unknown", context);
 					if (recordType) {
 						acc.value += "\n}";
-						acc.value += ` & ${recordType}`;
+						acc.value += ` & ${recordType.value}`;
 						acc.useTypeAlias = true;
+						acc.imports.push(...recordType.imports);
+						acc.dependencies.push(...recordType.dependencies);
 					} else {
 						const keyType = getIndexSignatureKey(schemaItem);
 						acc.value += `\n  [key: ${keyType}]: unknown;\n }`;
@@ -2272,11 +2410,13 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 						name,
 						context
 					});
-					const recordType = getPropertyNamesRecordType(schemaItem, resolvedValue.value);
+					const recordType = getPropertyNamesRecordType(schemaItem, resolvedValue.value, context);
 					if (recordType) {
 						acc.value += "\n}";
-						acc.value += ` & ${recordType}`;
+						acc.value += ` & ${recordType.value}`;
 						acc.useTypeAlias = true;
+						acc.imports.push(...recordType.imports);
+						acc.dependencies.push(...recordType.dependencies);
 					} else {
 						const keyType = getIndexSignatureKey(schemaItem);
 						acc.value += `\n  [key: ${keyType}]: ${resolvedValue.value};\n}`;
@@ -2295,17 +2435,17 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 	const readOnlyFlag = schemaItem.readOnly;
 	if (outerAdditionalProps) {
 		if (outerAdditionalProps === true) {
-			const recordType = getPropertyNamesRecordType(schemaItem, "unknown");
+			const recordType = getPropertyNamesRecordType(schemaItem, "unknown", context);
 			if (recordType) return {
-				value: recordType + nullable,
-				imports: [],
+				value: recordType.value + nullable,
+				imports: recordType.imports,
 				schemas: [],
 				isEnum: false,
 				type: "object",
 				isRef: false,
 				hasReadonlyProps: readOnlyFlag ?? false,
 				useTypeAlias: true,
-				dependencies: []
+				dependencies: recordType.dependencies
 			};
 			return {
 				value: `{ [key: ${getIndexSignatureKey(schemaItem)}]: unknown }` + nullable,
@@ -2324,17 +2464,17 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 			name,
 			context
 		});
-		const recordType = getPropertyNamesRecordType(schemaItem, resolvedValue.value);
+		const recordType = getPropertyNamesRecordType(schemaItem, resolvedValue.value, context);
 		if (recordType) return {
-			value: recordType + nullable,
-			imports: resolvedValue.imports,
+			value: recordType.value + nullable,
+			imports: [...recordType.imports, ...resolvedValue.imports],
 			schemas: resolvedValue.schemas,
 			isEnum: false,
 			type: "object",
 			isRef: false,
 			hasReadonlyProps: resolvedValue.hasReadonlyProps,
 			useTypeAlias: true,
-			dependencies: resolvedValue.dependencies
+			dependencies: [...recordType.dependencies, ...resolvedValue.dependencies]
 		};
 		return {
 			value: `{[key: ${getIndexSignatureKey(schemaItem)}]: ${resolvedValue.value}}` + nullable,
@@ -2369,17 +2509,17 @@ function getObject({ item, name, context, nullable, formDataContext }) {
 		};
 	}
 	const keyType = itemType === "object" ? getIndexSignatureKey(schemaItem) : "string";
-	const recordType = getPropertyNamesRecordType(schemaItem, "unknown");
+	const recordType = getPropertyNamesRecordType(schemaItem, "unknown", context);
 	if (itemType === "object" && recordType) return {
-		value: recordType + nullable,
-		imports: [],
+		value: recordType.value + nullable,
+		imports: recordType.imports,
 		schemas: [],
 		isEnum: false,
 		type: "object",
 		isRef: false,
 		hasReadonlyProps: readOnlyFlag ?? false,
 		useTypeAlias: true,
-		dependencies: []
+		dependencies: recordType.dependencies
 	};
 	return {
 		value: (itemType === "object" ? `{ [key: ${keyType}]: unknown }` : "unknown") + nullable,
@@ -2966,6 +3106,50 @@ const isOpenApiSchemaObject = (value) => {
 	if (!value || typeof value !== "object") return false;
 	return !("$ref" in value);
 };
+/**
+* A `$ref` schema object (e.g. array `items` or a oneOf/anyOf/allOf variant
+* pointing at a component). We don't resolve the reference here, but a query
+* parameter behind a `$ref` is virtually always a complex (object-like) type,
+* so it must be treated as non-primitive. Over-flagging is harmless: the only
+* consumer (the Angular `nonPrimitiveKeys` passthrough) is gated on a
+* configured `paramsSerializer`, which is precisely what handles raw values.
+*/
+const isRefObject = (value) => !!value && typeof value === "object" && "$ref" in value;
+const getSchemaType = (schema) => {
+	const type = schema.type;
+	if (typeof type === "string") return type;
+	if (Array.isArray(type) && type.every((variant) => typeof variant === "string")) return type;
+};
+/**
+* Detects whether a query parameter's resolved schema is non-primitive — i.e.
+* an object, an array of objects, or a composition (oneOf/anyOf/allOf) that
+* resolves to a non-primitive shape.
+*
+* Used by Angular generators so the default `filterParams` helper preserves
+* such values instead of silently dropping them. Angular's `HttpParams` only
+* accepts primitives, but a user-provided `paramsSerializer`, `mutator`, or
+* `paramsFilter` may need the raw object to flatten or stringify it.
+*/
+const isSchemaNonPrimitive = (schema) => {
+	const schemaType = getSchemaType(schema);
+	const type = Array.isArray(schemaType) ? schemaType.filter((variant) => variant !== "null") : schemaType;
+	const additionalProperties = schema.additionalProperties;
+	if (type === "object") return true;
+	if (Array.isArray(type) && type.includes("object")) return true;
+	if (type === "array" || Array.isArray(type) && type.includes("array")) {
+		const items = schema.items;
+		if (isOpenApiSchemaObject(items)) return isSchemaNonPrimitive(items);
+		return true;
+	}
+	const compositions = [
+		...Array.isArray(schema.oneOf) ? schema.oneOf : [],
+		...Array.isArray(schema.anyOf) ? schema.anyOf : [],
+		...Array.isArray(schema.allOf) ? schema.allOf : []
+	];
+	if (compositions.length > 0) return compositions.some((variant) => isOpenApiSchemaObject(variant) ? isSchemaNonPrimitive(variant) : isRefObject(variant));
+	if (!type && (schema.properties !== void 0 || additionalProperties !== void 0 && additionalProperties !== false)) return true;
+	return false;
+};
 const isSchemaNullable = (schema) => {
 	if (schema.nullable === true) return true;
 	if (schema.type === "null") return true;
@@ -3043,6 +3227,7 @@ function getQueryParams({ queryParams, operationName, context, suffix = "params"
 	const type = types.map(({ definition }) => definition).join("\n");
 	const allOptional = queryParams.every(({ parameter }) => !parameter.required);
 	const requiredNullableKeys = types.filter(({ required, originalSchema }) => required && isSchemaNullable(originalSchema)).map(({ name }) => name);
+	const nonPrimitiveKeys = types.filter(({ originalSchema }) => isSchemaNonPrimitive(originalSchema)).map(({ name }) => name);
 	return {
 		schema: {
 			name,
@@ -3051,7 +3236,8 @@ function getQueryParams({ queryParams, operationName, context, suffix = "params"
 		},
 		deps: schemas,
 		isOptional: allOptional,
-		requiredNullableKeys
+		requiredNullableKeys,
+		...nonPrimitiveKeys.length > 0 ? { nonPrimitiveKeys } : {}
 	};
 }
 //#endregion
@@ -3076,7 +3262,7 @@ function getResponse({ responses, operationName, context, contentType }) {
 			success: success || (defaultType ?? "unknown"),
 			errors: errors || (defaultType ?? "unknown")
 		},
-		isBlob: groupedByStatus.success.some((t) => !!t.contentType && isBinaryContentType(t.contentType)),
+		isBlob: groupedByStatus.success.some((t) => !!t.contentType && isBinaryContentType(t.contentType) || t.value === "Blob" && !t.isRef),
 		types: groupedByStatus,
 		contentTypes,
 		schemas,
@@ -3207,13 +3393,13 @@ function generateComponentDefinition(responses = {}, context, suffix) {
 }
 //#endregion
 //#region src/generators/imports.ts
-function generateImports({ imports, namingConvention = NamingConvention.CAMEL_CASE }) {
+function generateImports({ imports, namingConvention = NamingConvention.CAMEL_CASE, importExtension = "" }) {
 	if (imports.length === 0) return "";
 	const grouped = groupBy(uniqueWith(imports, (a, b) => a.name === b.name && a.default === b.default && a.alias === b.alias && a.values === b.values && a.isConstant === b.isConstant && a.namespaceImport === b.namespaceImport && a.syntheticDefaultImport === b.syntheticDefaultImport && a.importPath === b.importPath).map((imp) => ({
 		...imp,
-		importPath: imp.importPath ?? `./${conventionName(imp.name, namingConvention)}`
+		importPath: imp.importPath ?? `./${conventionName(imp.name, namingConvention)}${importExtension}`
 	})), (imp) => !imp.default && !imp.namespaceImport && !imp.syntheticDefaultImport && !imp.values && !imp.isConstant ? `aggregate|${imp.importPath}` : `single|${imp.importPath}|${imp.name}|${imp.alias ?? ""}|${String(imp.default)}|${String(imp.namespaceImport)}|${String(imp.syntheticDefaultImport)}|${String(imp.values)}|${String(imp.isConstant)}`);
-	return Object.entries(grouped).toSorted(([a], [b]) => a.localeCompare(b)).map(([, group]) => {
+	return Object.entries(grouped).toSorted(([a], [b]) => a.localeCompare(b, "en", { numeric: true })).map(([, group]) => {
 		const sample = group[0];
 		if (!sample.default && !sample.namespaceImport && !sample.syntheticDefaultImport && !sample.values && !sample.isConstant) return `import type { ${[...new Set(group.map(({ name, alias }) => `${name}${alias ? ` as ${alias}` : ""}`))].toSorted().join(", ")} } from '${sample.importPath}';`;
 		const { name, values, alias, isConstant, importPath } = sample;
@@ -3223,7 +3409,8 @@ function generateImports({ imports, namingConvention = NamingConvention.CAMEL_CA
 function generateMutatorImports({ mutators, implementation, oneMore }) {
 	let imports = "";
 	for (const mutator of uniqueWith(mutators, (a, b) => a.name === b.name && a.default === b.default)) {
-		const path = `${oneMore ? "../" : ""}${mutator.path}`;
+		const isRelativeImport = mutator.path.startsWith(".");
+		const path = `${oneMore && isRelativeImport ? "../" : ""}${mutator.path}`;
 		const importDefault = mutator.default ? mutator.name : `{ ${mutator.name} }`;
 		imports += `import ${importDefault} from '${path}';`;
 		imports += "\n";
@@ -3570,16 +3757,24 @@ function removeComments(file) {
 * (e.g. observe-mode branches), prefer getAngularFilteredParamsCallExpression +
 * getAngularFilteredParamsHelperBody instead.
 */
-const getAngularFilteredParamsExpression = (paramsExpression, requiredNullableParamKeys = [], preserveRequiredNullables = false) => {
-	const filteredParamValueType = `string | number | boolean${preserveRequiredNullables ? " | null" : ""} | Array<string | number | boolean>`;
+const getAngularFilteredParamsExpression = (paramsExpression, requiredNullableParamKeys = [], preserveRequiredNullables = false, nonPrimitiveKeys = []) => {
+	const hasPassthrough = nonPrimitiveKeys.length > 0;
+	const filteredParamValueType = hasPassthrough ? "unknown" : `string | number | boolean${preserveRequiredNullables ? " | null" : ""} | Array<string | number | boolean>`;
+	const passthroughBranch = hasPassthrough ? `    if (passthroughKeys.has(key)) {
+      if (value !== undefined) {
+        filteredParams[key] = value;
+      }
+      continue;
+    }
+` : "";
 	const preserveNullableBranch = preserveRequiredNullables ? `    } else if (value === null && requiredNullableParamKeys.has(key)) {
       filteredParams[key] = null;
 ` : "";
 	return `(() => {
-  const requiredNullableParamKeys = new Set<string>(${JSON.stringify(requiredNullableParamKeys)});
+${hasPassthrough ? `  const passthroughKeys = new Set<string>(${JSON.stringify(nonPrimitiveKeys)});\n` : ""}  const requiredNullableParamKeys = new Set<string>(${JSON.stringify(requiredNullableParamKeys)});
   const filteredParams: Record<string, ${filteredParamValueType}> = {};
   for (const [key, value] of Object.entries(${paramsExpression})) {
-    if (Array.isArray(value)) {
+${passthroughBranch}    if (Array.isArray(value)) {
       const filtered = value.filter(
         (item) =>
           item != null &&
@@ -3614,19 +3809,34 @@ function filterParams(
   params: Record<string, unknown>,
   requiredNullableKeys?: ReadonlySet<string>,
   preserveRequiredNullables?: false,
+  passthroughKeys?: undefined,
 ): Record<string, AngularHttpParamValue>;
 function filterParams(
   params: Record<string, unknown>,
   requiredNullableKeys: ReadonlySet<string> | undefined,
   preserveRequiredNullables: true,
+  passthroughKeys?: undefined,
 ): Record<string, AngularHttpParamValueWithNullable>;
+function filterParams(
+  params: Record<string, unknown>,
+  requiredNullableKeys: ReadonlySet<string> | undefined,
+  preserveRequiredNullables: boolean | undefined,
+  passthroughKeys: ReadonlySet<string>,
+): Record<string, unknown>;
 function filterParams(
   params: Record<string, unknown>,
   requiredNullableKeys: ReadonlySet<string> = new Set(),
   preserveRequiredNullables = false,
-): Record<string, AngularHttpParamValueWithNullable> {
-  const filteredParams: Record<string, AngularHttpParamValueWithNullable> = {};
+  passthroughKeys: ReadonlySet<string> = new Set(),
+): Record<string, unknown> {
+  const filteredParams: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(params)) {
+    if (passthroughKeys.has(key)) {
+      if (value !== undefined) {
+        filteredParams[key] = value;
+      }
+      continue;
+    }
     if (Array.isArray(value)) {
       const filtered = value.filter(
         (item) =>
@@ -3658,15 +3868,34 @@ function filterParams(
 /**
 * Returns a call expression to the `filterParams` helper function.
 */
-const getAngularFilteredParamsCallExpression = (paramsExpression, requiredNullableParamKeys = [], preserveRequiredNullables = false) => `filterParams(${paramsExpression}, new Set<string>(${JSON.stringify(requiredNullableParamKeys)})${preserveRequiredNullables ? ", true" : ""})`;
+const getAngularFilteredParamsCallExpression = (paramsExpression, requiredNullableParamKeys = [], preserveRequiredNullables = false, nonPrimitiveKeys = []) => {
+	const baseArgs = `${paramsExpression}, new Set<string>(${JSON.stringify(requiredNullableParamKeys)})`;
+	if (nonPrimitiveKeys.length > 0) return `filterParams(${baseArgs}, ${preserveRequiredNullables}, new Set<string>(${JSON.stringify(nonPrimitiveKeys)}))`;
+	return `filterParams(${baseArgs}${preserveRequiredNullables ? ", true" : ""})`;
+};
+/**
+* Returns the filter call/IIFE used to massage query params before passing
+* them to Angular's HttpParams. When the user supplied a `paramsFilter`
+* mutator, the built-in `filterParams` is bypassed entirely and the user's
+* function is called with the raw params — they own nullish-stripping and
+* any object/array handling. Otherwise the built-in filter is used (either
+* the shared helper or an inline IIFE), and callers should only pass
+* `nonPrimitiveKeys` when a downstream serializer or custom consumer can
+* legally handle raw object/array values.
+*/
+const buildAngularParamsFilterExpression = ({ paramsExpression, requiredNullableParamKeys = [], preserveRequiredNullables = false, nonPrimitiveKeys = [], paramsFilter, useSharedHelper }) => {
+	if (paramsFilter) return `${paramsFilter.name}(${paramsExpression})`;
+	if (useSharedHelper) return getAngularFilteredParamsCallExpression(paramsExpression, requiredNullableParamKeys, preserveRequiredNullables, nonPrimitiveKeys);
+	return getAngularFilteredParamsExpression(paramsExpression, requiredNullableParamKeys, preserveRequiredNullables, nonPrimitiveKeys);
+};
 function generateBodyOptions(body, isFormData, isFormUrlEncoded) {
-	if (isFormData && body.formData) return "\n      formData,";
-	if (isFormUrlEncoded && body.formUrlEncoded) return "\n      formUrlEncoded,";
-	if (body.implementation) return `\n      ${body.implementation},`;
-	return "";
+	if (isFormData && body.formData) return "formData";
+	if (isFormUrlEncoded && body.formUrlEncoded) return "formUrlEncoded";
+	if (body.implementation) return body.implementation;
 }
-function generateAxiosOptions({ response, isExactOptionalPropertyTypes, angularObserve, angularParamsRef, requiredNullableQueryParamKeys, queryParams, headers, requestOptions, hasSignal, hasSignalParam = false, isVue, isAngular, paramsSerializer, paramsSerializerOptions }) {
+function generateAxiosOptions({ response, isExactOptionalPropertyTypes, angularObserve, angularParamsRef, requiredNullableQueryParamKeys, nonPrimitiveQueryParamKeys, queryParams, headers, requestOptions, hasSignal, hasSignalParam = false, isVue, isAngular, paramsSerializer, paramsSerializerOptions, paramsFilter }) {
 	const isRequestOptions = requestOptions !== false;
+	const angularPassthroughQueryParamKeys = paramsSerializer ? nonPrimitiveQueryParamKeys : [];
 	const signalVar = hasSignalParam ? "querySignal" : "signal";
 	const signalProp = hasSignalParam ? `signal: ${signalVar}` : "signal";
 	if (!queryParams && !headers && !response.isBlob && response.definition.success !== "string") {
@@ -3680,7 +3909,14 @@ function generateAxiosOptions({ response, isExactOptionalPropertyTypes, angularO
 	let value = "";
 	if (!isRequestOptions) {
 		if (queryParams) if (isAngular) {
-			const iifeExpr = getAngularFilteredParamsExpression("params ?? {}", requiredNullableQueryParamKeys, !!paramsSerializer);
+			const iifeExpr = buildAngularParamsFilterExpression({
+				paramsExpression: "params ?? {}",
+				requiredNullableParamKeys: requiredNullableQueryParamKeys,
+				preserveRequiredNullables: !!paramsSerializer,
+				nonPrimitiveKeys: angularPassthroughQueryParamKeys,
+				paramsFilter,
+				useSharedHelper: false
+			});
 			value += paramsSerializer ? `\n        params: ${paramsSerializer.name}(${iifeExpr}),` : `\n        params: ${iifeExpr},`;
 		} else value += "\n        params,";
 		if (headers) value += "\n        headers,";
@@ -3697,10 +3933,25 @@ function generateAxiosOptions({ response, isExactOptionalPropertyTypes, angularO
 		if (queryParams) if (isVue) value += "\n        params: {...unref(params), ...options?.params},";
 		else if (isAngular && angularParamsRef) value += `\n        params: ${angularParamsRef},`;
 		else if (isAngular && paramsSerializer) {
-			const callExpr = getAngularFilteredParamsCallExpression("{...params, ...options?.params}", requiredNullableQueryParamKeys, true);
+			const callExpr = buildAngularParamsFilterExpression({
+				paramsExpression: "{...params, ...options?.params}",
+				requiredNullableParamKeys: requiredNullableQueryParamKeys,
+				preserveRequiredNullables: true,
+				nonPrimitiveKeys: angularPassthroughQueryParamKeys,
+				paramsFilter,
+				useSharedHelper: true
+			});
 			value += `\n        params: ${paramsSerializer.name}(${callExpr}),`;
-		} else if (isAngular) value += `\n        params: ${getAngularFilteredParamsCallExpression("{...params, ...options?.params}", requiredNullableQueryParamKeys)},`;
-		else value += "\n        params: {...params, ...options?.params},";
+		} else if (isAngular) {
+			const callExpr = buildAngularParamsFilterExpression({
+				paramsExpression: "{...params, ...options?.params}",
+				requiredNullableParamKeys: requiredNullableQueryParamKeys,
+				nonPrimitiveKeys: angularPassthroughQueryParamKeys,
+				paramsFilter,
+				useSharedHelper: true
+			});
+			value += `\n        params: ${callExpr},`;
+		} else value += "\n        params: {...params, ...options?.params},";
 		if (headers) value += "\n        headers: {...headers, ...options?.headers},";
 	}
 	if (!isAngular && queryParams && (paramsSerializer || paramsSerializerOptions?.qs)) {
@@ -3709,13 +3960,14 @@ function generateAxiosOptions({ response, isExactOptionalPropertyTypes, angularO
 	}
 	return value;
 }
-function generateOptions({ route, body, angularObserve, angularParamsRef, headers, queryParams, response, verb, requestOptions, isFormData, isFormUrlEncoded, isAngular, isExactOptionalPropertyTypes, hasSignal, hasSignalParam, isVue, paramsSerializer, paramsSerializerOptions }) {
-	const bodyOptions = getIsBodyVerb(verb) ? generateBodyOptions(body, isFormData, isFormUrlEncoded) : "";
+function generateOptions({ route, body, angularObserve, angularParamsRef, headers, queryParams, response, verb, requestOptions, isFormData, isFormUrlEncoded, isAngular, isExactOptionalPropertyTypes, hasSignal, hasSignalParam, isVue, paramsSerializer, paramsSerializerOptions, paramsFilter }) {
+	const bodyIdentifier = getIsBodyVerb(verb) ? generateBodyOptions(body, isFormData, isFormUrlEncoded) : void 0;
 	const axiosOptions = generateAxiosOptions({
 		response,
 		angularObserve,
 		angularParamsRef,
 		requiredNullableQueryParamKeys: queryParams?.requiredNullableKeys,
+		nonPrimitiveQueryParamKeys: queryParams?.nonPrimitiveKeys,
 		queryParams: queryParams?.schema,
 		headers: headers?.schema,
 		requestOptions,
@@ -3725,17 +3977,18 @@ function generateOptions({ route, body, angularObserve, angularParamsRef, header
 		isVue: isVue ?? false,
 		isAngular: isAngular ?? false,
 		paramsSerializer,
-		paramsSerializerOptions
+		paramsSerializerOptions,
+		paramsFilter
 	});
 	const trimmedAxiosOptions = axiosOptions.trim();
 	const isRawOptionsArgument = trimmedAxiosOptions === "options" || trimmedAxiosOptions.startsWith("(") && trimmedAxiosOptions.endsWith(")") || trimmedAxiosOptions.startsWith("{") && trimmedAxiosOptions.endsWith("}");
 	const optionsArgument = axiosOptions ? isRawOptionsArgument ? axiosOptions : `{${axiosOptions}}` : "";
 	if (verb === Verbs.DELETE) {
-		if (!bodyOptions) return `\n      \`${route}\`${optionsArgument ? `,${optionsArgument}` : ""}\n    `;
+		if (!bodyIdentifier) return `\n      \`${route}\`${optionsArgument ? `,${optionsArgument}` : ""}\n    `;
 		const deleteBodyOptions = isRawOptionsArgument ? `...${optionsArgument}` : axiosOptions;
-		return `\n      \`${route}\`,{${isAngular ? "body" : "data"}:${bodyOptions} ${axiosOptions ? deleteBodyOptions : ""}}\n    `;
+		return `\n      \`${route}\`,{${`${isAngular ? "body" : "data"}: ${bodyIdentifier}`}${axiosOptions ? `,${deleteBodyOptions}` : ""}}\n    `;
 	}
-	const bodyOrOptions = getIsBodyVerb(verb) ? bodyOptions || "undefined," : "";
+	const bodyOrOptions = getIsBodyVerb(verb) ? `\n      ${bodyIdentifier ?? "undefined"},` : "";
 	return `\n      \`${route}\`${bodyOrOptions || optionsArgument ? "," : ""}${bodyOrOptions}${optionsArgument}\n    `;
 }
 function generateBodyMutatorConfig(body, isFormData, isFormUrlEncoded) {
@@ -3744,18 +3997,26 @@ function generateBodyMutatorConfig(body, isFormData, isFormUrlEncoded) {
 	if (body.implementation) return `,\n      data: ${body.implementation}`;
 	return "";
 }
-function generateQueryParamsAxiosConfig(response, isVue, isAngular, requiredNullableQueryParamKeys, queryParams) {
+function generateQueryParamsAxiosConfig(response, isVue, isAngular, requiredNullableQueryParamKeys, queryParams, paramsFilter) {
 	if (!queryParams && !response.isBlob) return "";
 	let value = "";
 	if (queryParams) if (isVue) value += ",\n        params: unref(params)";
-	else if (isAngular) value += `,\n        params: ${getAngularFilteredParamsExpression("params ?? {}", requiredNullableQueryParamKeys)}`;
-	else value += ",\n        params";
+	else if (isAngular) {
+		const paramsExpr = buildAngularParamsFilterExpression({
+			paramsExpression: "params ?? {}",
+			requiredNullableParamKeys: requiredNullableQueryParamKeys,
+			nonPrimitiveKeys: queryParams.nonPrimitiveKeys,
+			paramsFilter,
+			useSharedHelper: false
+		});
+		value += `,\n        params: ${paramsExpr}`;
+	} else value += ",\n        params";
 	if (response.isBlob) value += `,\n        responseType: 'blob'`;
 	return value;
 }
-function generateMutatorConfig({ route, body, headers, queryParams, response, verb, isFormData, isFormUrlEncoded, hasSignal, hasSignalParam = false, isExactOptionalPropertyTypes, isVue, isAngular }) {
+function generateMutatorConfig({ route, body, headers, queryParams, response, verb, isFormData, isFormUrlEncoded, hasSignal, hasSignalParam = false, isExactOptionalPropertyTypes, isVue, isAngular, paramsFilter }) {
 	const bodyOptions = getIsBodyVerb(verb) ? generateBodyMutatorConfig(body, isFormData, isFormUrlEncoded) : "";
-	const queryParamsOptions = generateQueryParamsAxiosConfig(response, isVue ?? false, isAngular ?? false, queryParams?.requiredNullableKeys, queryParams);
+	const queryParamsOptions = generateQueryParamsAxiosConfig(response, isVue ?? false, isAngular ?? false, queryParams?.requiredNullableKeys, queryParams, paramsFilter);
 	const ignoreContentTypes = isAngular ? ["multipart/form-data"] : [];
 	const headerOptions = body.contentType && !ignoreContentTypes.includes(body.contentType) ? `,\n      headers: {'Content-Type': '${body.contentType}', ${headers ? "...headers" : ""}}` : headers ? ",\n      headers" : "";
 	const signalVar = hasSignalParam ? "querySignal" : "signal";
@@ -4068,6 +4329,13 @@ async function buildVerbOption({ verb, output, operation, route, pathRoute, verb
 			workspace: context.workspace,
 			tsconfig: context.output.tsconfig
 		}) : void 0,
+		paramsFilter: isString(override.paramsFilter) || isObject(override.paramsFilter) ? await generateMutator({
+			output: output.target,
+			name: "paramsFilter",
+			mutator: override.paramsFilter,
+			workspace: context.workspace,
+			tsconfig: context.output.tsconfig
+		}) : void 0,
 		fetchReviver: isString(override.fetch.jsonReviver) || isObject(override.fetch.jsonReviver) ? await generateMutator({
 			output: output.target,
 			name: "fetchReviver",
@@ -4232,19 +4500,12 @@ function splitSchemasByType(schemas) {
 	};
 }
 /**
-* Get the import extension from a file extension.
-* Removes `.ts` suffix since TypeScript doesn't need it in imports.
-*/
-function getImportExtension(fileExtension) {
-	return fileExtension.replace(/\.ts$/, "") || "";
-}
-/**
 * Fix cross-directory imports when schemas reference other schemas in a different directory.
 * Updates import paths to use correct relative paths between directories.
 */
-function fixSchemaImports(schemas, targetSchemaNames, fromPath, toPath, namingConvention, fileExtension) {
+function fixSchemaImports(schemas, targetSchemaNames, fromPath, toPath, namingConvention, fileExtension, tsconfig) {
 	const relativePath = relativeSafe(fromPath, toPath);
-	const importExtension = getImportExtension(fileExtension);
+	const importExtension = getImportExtension(fileExtension, tsconfig);
 	for (const schema of schemas) schema.imports = schema.imports.map((imp) => {
 		if (targetSchemaNames.has(imp.name)) {
 			const fileName = conventionName(imp.name, namingConvention);
@@ -4259,14 +4520,14 @@ function fixSchemaImports(schemas, targetSchemaNames, fromPath, toPath, namingCo
 /**
 * Fix imports in operation schemas that reference regular schemas.
 */
-function fixCrossDirectoryImports(operationSchemas, regularSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension) {
-	fixSchemaImports(operationSchemas, regularSchemaNames, operationSchemaPath, schemaPath, namingConvention, fileExtension);
+function fixCrossDirectoryImports(operationSchemas, regularSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension, tsconfig) {
+	fixSchemaImports(operationSchemas, regularSchemaNames, operationSchemaPath, schemaPath, namingConvention, fileExtension, tsconfig);
 }
 /**
 * Fix imports in regular schemas that reference operation schemas.
 */
-function fixRegularSchemaImports(regularSchemas, operationSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension) {
-	fixSchemaImports(regularSchemas, operationSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension);
+function fixRegularSchemaImports(regularSchemas, operationSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension, tsconfig) {
+	fixSchemaImports(regularSchemas, operationSchemaNames, schemaPath, operationSchemaPath, namingConvention, fileExtension, tsconfig);
 }
 function getSchemaKey(schemaPath, schemaName, namingConvention, fileExtension) {
 	return getPath(schemaPath, conventionName(schemaName, namingConvention), fileExtension).toLowerCase().replaceAll("\\", "/");
@@ -4290,14 +4551,16 @@ function getCanonicalMap(schemaGroups, schemaPath, namingConvention, fileExtensi
 		canonicalNameMap
 	};
 }
-function normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension) {
+function normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig) {
+	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 importPath = removeTSExtension(relativeSafe(schemaPath, canonical.importPath.replaceAll("\\", "/")));
+		const relative = relativeSafe(schemaPath, canonical.importPath.replaceAll("\\", "/"));
+		const importPath = `${relative.endsWith(fileExtension) ? relative.slice(0, -fileExtension.length) : relative.replace(/\.ts$/, "")}${importExtension}`;
 		return {
 			...imp,
 			importPath
@@ -4320,14 +4583,12 @@ function mergeSchemaGroup(schemas) {
 function resolveImportKey(schemaPath, importPath, fileExtension) {
 	return join(schemaPath, `${importPath}${fileExtension}`).toLowerCase().replaceAll("\\", "/");
 }
-function removeTSExtension(path) {
-	return path.endsWith(".ts") ? path.slice(0, -3) : path;
-}
-function getSchema({ schema: { imports, model }, header, namingConvention = NamingConvention.CAMEL_CASE }) {
+function getSchema({ schema: { imports, model }, header, namingConvention = NamingConvention.CAMEL_CASE, importExtension }) {
 	let file = header;
 	file += generateImports({
 		imports: imports.filter((imp) => !model.includes(`type ${imp.alias ?? imp.name} =`) && !model.includes(`interface ${imp.alias ?? imp.name} {`)),
-		namingConvention
+		namingConvention,
+		importExtension
 	});
 	file += imports.length > 0 ? "\n\n" : "\n";
 	file += model;
@@ -4344,23 +4605,24 @@ function writeModelsInline(array) {
 	for (const { model } of array) acc = writeModelInline(acc, model);
 	return acc;
 }
-async function writeSchema({ path, schema, target, namingConvention, fileExtension, header }) {
+async function writeSchema({ path, schema, target, namingConvention, fileExtension, header, tsconfig }) {
 	const name = conventionName(schema.name, namingConvention);
 	try {
 		await writeGeneratedFile(getPath(path, name, fileExtension), getSchema({
 			schema,
 			target,
 			header,
-			namingConvention
+			namingConvention,
+			importExtension: getImportExtension(fileExtension, tsconfig)
 		}));
 	} catch (error) {
 		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 }) {
+async function writeSchemas({ schemaPath, schemas, target, namingConvention, fileExtension, header, indexFiles, tsconfig }) {
 	const schemaGroups = getSchemaGroups(schemaPath, schemas, namingConvention, fileExtension);
 	const { canonicalPathMap, canonicalNameMap } = getCanonicalMap(schemaGroups, schemaPath, namingConvention, fileExtension);
-	normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension);
+	normalizeCanonicalImportPaths(schemas, canonicalPathMap, canonicalNameMap, schemaPath, namingConvention, fileExtension, tsconfig);
 	for (const groupSchemas of Object.values(schemaGroups)) {
 		if (groupSchemas.length === 1) {
 			await writeSchema({
@@ -4369,7 +4631,8 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 				target,
 				namingConvention,
 				fileExtension,
-				header
+				header,
+				tsconfig
 			});
 			continue;
 		}
@@ -4379,16 +4642,17 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 			target,
 			namingConvention,
 			fileExtension,
-			header
+			header,
+			tsconfig
 		});
 	}
 	if (indexFiles) {
 		const schemaFilePath = nodePath.join(schemaPath, `index.ts`);
 		await fs$1.ensureFile(schemaFilePath);
-		const ext = fileExtension.endsWith(".ts") ? fileExtension.slice(0, -3) : fileExtension;
+		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)).join("\n")}\n`);
+			await writeGeneratedFile(schemaFilePath, `${header}\n${[...conventionNamesSet].map((schemaName) => `export * from './${schemaName}${ext}';`).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 });
 		}
@@ -4409,7 +4673,7 @@ function generateImportsForBuilder(output, imports, relativeSchemasPath) {
 	else {
 		const importsByDependency = /* @__PURE__ */ new Map();
 		for (const schemaImport of imports.filter((i) => !i.importPath)) {
-			const dependency = joinSafe(relativeSchemasPath, `${conventionName(isZodSchemaOutput ? schemaImport.name : schemaImport.schemaName ?? schemaImport.name, output.namingConvention)}${isZodSchemaOutput ? ".zod" : ""}${output.fileExtension.replace(/\.ts$/, "") || ""}`);
+			const dependency = joinSafe(relativeSchemasPath, `${conventionName(isZodSchemaOutput ? schemaImport.name : schemaImport.schemaName ?? schemaImport.name, output.namingConvention)}${isZodSchemaOutput ? ".zod" : ""}${getImportExtension(output.fileExtension, output.tsconfig)}`);
 			if (!importsByDependency.has(dependency)) importsByDependency.set(dependency, []);
 			importsByDependency.get(dependency)?.push(schemaImport);
 		}
@@ -4451,6 +4715,7 @@ function generateTarget(builder, options) {
 		formData: [],
 		formUrlEncoded: [],
 		paramsSerializer: [],
+		paramsFilter: [],
 		fetchReviver: []
 	};
 	const operations = Object.values(builder.operations);
@@ -4466,6 +4731,7 @@ function generateTarget(builder, options) {
 		if (operation.formData) target.formData.push(operation.formData);
 		if (operation.formUrlEncoded) target.formUrlEncoded.push(operation.formUrlEncoded);
 		if (operation.paramsSerializer) target.paramsSerializer.push(operation.paramsSerializer);
+		if (operation.paramsFilter) target.paramsFilter.push(operation.paramsFilter);
 		if (operation.clientMutators) target.clientMutators.push(...operation.clientMutators);
 		if (operation.fetchReviver) target.fetchReviver.push(operation.fetchReviver);
 		if (index === operations.length - 1) {
@@ -4548,7 +4814,7 @@ async function writeSingleMode({ builder, output, projectName, header, needSchem
 			backupFilename: conventionName(builder.info.title ?? "filename", output.namingConvention),
 			extension: output.fileExtension
 		});
-		const { imports, importsMock, implementation, implementationMock, mutators, clientMutators, formData, formUrlEncoded, paramsSerializer, fetchReviver } = generateTarget(builder, output);
+		const { imports, importsMock, implementation, implementationMock, mutators, clientMutators, formData, formUrlEncoded, paramsSerializer, paramsFilter, fetchReviver } = generateTarget(builder, output);
 		let data = header;
 		const schemasPath = output.schemas ? getRelativeImportPath(path, getFileInfo(isString(output.schemas) ? output.schemas : output.schemas.path, { extension: output.fileExtension }).dirname) : void 0;
 		const isAllowSyntheticDefaultImports = isSyntheticDefaultImportsAllow(output.tsconfig);
@@ -4596,6 +4862,7 @@ async function writeSingleMode({ builder, output, projectName, header, needSchem
 		if (formData) data += generateMutatorImports({ mutators: formData });
 		if (formUrlEncoded) data += generateMutatorImports({ mutators: formUrlEncoded });
 		if (paramsSerializer) data += generateMutatorImports({ mutators: paramsSerializer });
+		if (paramsFilter) data += generateMutatorImports({ mutators: paramsFilter });
 		if (fetchReviver) data += generateMutatorImports({ mutators: fetchReviver });
 		if (implementation.includes("NonReadonly<")) {
 			data += getOrvalGeneratedTypes();
@@ -4626,7 +4893,7 @@ async function writeSplitMode({ builder, output, projectName, header, needSchema
 			backupFilename: conventionName(builder.info.title ?? "filename", output.namingConvention),
 			extension: output.fileExtension
 		});
-		const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, formUrlEncoded, paramsSerializer, fetchReviver } = generateTarget(builder, output);
+		const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, formUrlEncoded, paramsSerializer, paramsFilter, fetchReviver } = generateTarget(builder, output);
 		let implementationData = header;
 		let mockData = header;
 		const relativeSchemasPath = output.schemas ? getRelativeImportPath(targetPath, getFileInfo(isString(output.schemas) ? output.schemas : output.schemas.path, { extension: output.fileExtension }).dirname) : "./" + filename + ".schemas" + extension.replace(/\.ts$/, "");
@@ -4664,6 +4931,7 @@ async function writeSplitMode({ builder, output, projectName, header, needSchema
 		if (formData) implementationData += generateMutatorImports({ mutators: formData });
 		if (formUrlEncoded) implementationData += generateMutatorImports({ mutators: formUrlEncoded });
 		if (paramsSerializer) implementationData += generateMutatorImports({ mutators: paramsSerializer });
+		if (paramsFilter) implementationData += generateMutatorImports({ mutators: paramsFilter });
 		if (fetchReviver) implementationData += generateMutatorImports({ mutators: fetchReviver });
 		if (implementation.includes("NonReadonly<")) {
 			implementationData += getOrvalGeneratedTypes();
@@ -4691,10 +4959,16 @@ async function writeSplitMode({ builder, output, projectName, header, needSchema
 }
 //#endregion
 //#region src/writers/target-tags.ts
+/**
+* Ensures every operation has at least one tag by falling back to the
+* {@link DefaultTag} constant for untagged operations, so the tag-routing
+* logic in {@link generateTargetTags} always has a bucket to assign the
+* operation to.
+*/
 function addDefaultTagIfEmpty(operation) {
 	return {
 		...operation,
-		tags: operation.tags.length > 0 ? operation.tags : ["default"]
+		tags: operation.tags.length > 0 ? operation.tags : [DefaultTag]
 	};
 }
 function generateTargetTags(currentAcc, operation) {
@@ -4708,6 +4982,7 @@ function generateTargetTags(currentAcc, operation) {
 			formData: operation.formData ? [operation.formData] : [],
 			formUrlEncoded: operation.formUrlEncoded ? [operation.formUrlEncoded] : [],
 			paramsSerializer: operation.paramsSerializer ? [operation.paramsSerializer] : [],
+			paramsFilter: operation.paramsFilter ? [operation.paramsFilter] : [],
 			fetchReviver: operation.fetchReviver ? [operation.fetchReviver] : [],
 			implementation: operation.implementation,
 			implementationMock: {
@@ -4733,6 +5008,7 @@ function generateTargetTags(currentAcc, operation) {
 		formData: operation.formData ? [...currentOperation.formData ?? [], operation.formData] : currentOperation.formData,
 		formUrlEncoded: operation.formUrlEncoded ? [...currentOperation.formUrlEncoded ?? [], operation.formUrlEncoded] : currentOperation.formUrlEncoded,
 		paramsSerializer: operation.paramsSerializer ? [...currentOperation.paramsSerializer ?? [], operation.paramsSerializer] : currentOperation.paramsSerializer,
+		paramsFilter: operation.paramsFilter ? [...currentOperation.paramsFilter ?? [], operation.paramsFilter] : currentOperation.paramsFilter,
 		fetchReviver: operation.fetchReviver ? [...currentOperation.fetchReviver ?? [], operation.fetchReviver] : currentOperation.fetchReviver
 	};
 	return currentAcc;
@@ -4774,6 +5050,7 @@ function generateTargetForTags(builder, options) {
 					output: options,
 					verbOptions: builder.verbOptions,
 					tag,
+					isDefaultTagBucket: tag === "default" && Object.values(builder.operations).some((operation) => operation.tags.length === 0),
 					clientImplementation: target.implementation
 				});
 				transformed[tag] = {
@@ -4790,6 +5067,7 @@ function generateTargetForTags(builder, options) {
 					formData: target.formData,
 					formUrlEncoded: target.formUrlEncoded,
 					paramsSerializer: target.paramsSerializer,
+					paramsFilter: target.paramsFilter,
 					fetchReviver: target.fetchReviver
 				};
 			}
@@ -4818,7 +5096,7 @@ async function writeSplitTagsMode({ builder, output, projectName, header, needSc
 	const tagEntries = Object.entries(target);
 	const generatedFilePathsArray = await Promise.all(tagEntries.map(async ([tag, target]) => {
 		try {
-			const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, fetchReviver, formUrlEncoded, paramsSerializer } = target;
+			const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, fetchReviver, formUrlEncoded, paramsSerializer, paramsFilter } = target;
 			let implementationData = header;
 			let mockData = header;
 			const importerPath = nodePath.join(dirname, tag, tag + extension);
@@ -4886,6 +5164,10 @@ async function writeSplitTagsMode({ builder, output, projectName, header, needSc
 				mutators: paramsSerializer,
 				oneMore: true
 			});
+			if (paramsFilter) implementationData += generateMutatorImports({
+				mutators: paramsFilter,
+				oneMore: true
+			});
 			if (fetchReviver) implementationData += generateMutatorImports({
 				mutators: fetchReviver,
 				oneMore: true
@@ -4934,7 +5216,7 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 	const isAllowSyntheticDefaultImports = isSyntheticDefaultImportsAllow(output.tsconfig);
 	return (await Promise.all(Object.entries(target).map(async ([tag, target]) => {
 		try {
-			const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, formUrlEncoded, fetchReviver, paramsSerializer } = target;
+			const { imports, implementation, implementationMock, importsMock, mutators, clientMutators, formData, formUrlEncoded, fetchReviver, paramsSerializer, paramsFilter } = target;
 			let data = header;
 			const schemasPathRelative = output.schemas ? getRelativeImportPath(targetPath, getFileInfo(isString(output.schemas) ? output.schemas : output.schemas.path, { extension: output.fileExtension }).dirname) : "./" + filename + ".schemas" + extension.replace(/\.ts$/, "");
 			const normalizedImports = imports.filter((imp) => {
@@ -4982,6 +5264,7 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 			if (formData) data += generateMutatorImports({ mutators: formData });
 			if (formUrlEncoded) data += generateMutatorImports({ mutators: formUrlEncoded });
 			if (paramsSerializer) data += generateMutatorImports({ mutators: paramsSerializer });
+			if (paramsFilter) data += generateMutatorImports({ mutators: paramsFilter });
 			if (fetchReviver) data += generateMutatorImports({ mutators: fetchReviver });
 			data += "\n\n";
 			if (implementation.includes("NonReadonly<")) {
@@ -5006,6 +5289,6 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 	}))).flat();
 }
 //#endregion
-export { BODY_TYPE_NAME, EnumGeneration, ErrorWithTag, FormDataArrayHandling, GetterPropType, LogLevels, NamingConvention, OutputClient, OutputHttpClient, OutputMockType, OutputMode, PropertySortOrder, RefComponentSuffix, SchemaType, SupportedFormatter, TEMPLATE_TAG_REGEX, URL_REGEX, VERBS_WITH_BODY, Verbs, addDependency, asyncReduce, 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, getIsBodyVerb, getKey, getMockFileExtensionByTypeName, getNumberWord, getObject, getOperationId, getOrvalGeneratedTypes, getParameters, getParams, getParamsInPath, getPropertySafe, getProps, getQueryParams, getRefInfo, getResReqTypes, getResponse, getResponseTypeCategory, getRoute, getRouteAsArray, getScalar, getSuccessResponseType, getTypedResponse, getWarningCount, isBinaryContentType, isBoolean, isDirectory, isFunction, isModule, isNullish, isNumber, isNumeric, isObject, isReference, isSchema, isString, isStringLike, isSyntheticDefaultImportsAllow, isUrl, isVerb, isVerbose, jsDoc, jsStringEscape, kebab, keyValuePairsToJsDoc, log, logError, logVerbose, logWarning, 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, 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, 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, isBoolean, isComponentRef, isDirectory, isFunction, isModule, isNullish, isNumber, isNumeric, isObject, isReference, isSchema, isString, isStringLike, isSyntheticDefaultImportsAllow, isUrl, isVerb, isVerbose, jsDoc, jsStringEscape, kebab, keyValuePairsToJsDoc, log, logError, logVerbose, logWarning, 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, writeModelInline, writeModelsInline, writeSchema, writeSchemas, writeSingleMode, writeSplitMode, writeSplitTagsMode, writeTagsMode };
 
 //# sourceMappingURL=index.mjs.map