@orval/core 8.10.0 → 8.11.0

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { createRequire } from "node:module";
 import { entries, groupBy, isArray, isBoolean, isBoolean as isBoolean$1, isEmptyish, isFunction, isNullish, isNullish as isNullish$1, isNumber, isString, isString as isString$1, prop, unique, uniqueBy, uniqueWith } from "remeda";
 import { keyword } from "esutils";
-import path from "node:path";
+import nodePath from "node:path";
 import { compare } from "compare-versions";
 import debug from "debug";
 import { pathToFileURL } from "node:url";
@@ -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",
@@ -137,7 +141,7 @@ function isReference(obj) {
 	return !isNullish$1(obj) && Object.hasOwn(obj, "$ref");
 }
 function isDirectory(pathValue) {
-	return !path.extname(pathValue);
+	return !nodePath.extname(pathValue);
 }
 function isObject(x) {
 	return Object.prototype.toString.call(x) === "[object Object]";
@@ -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;
@@ -450,8 +490,8 @@ async function dynamicImport(toImport, from = process.cwd(), takeDefault = true)
 	if (!toImport) return toImport;
 	try {
 		if (isString(toImport)) {
-			const filePath = path.resolve(from, toImport);
-			const extension = path.extname(filePath);
+			const filePath = nodePath.resolve(from, toImport);
+			const extension = nodePath.extname(filePath);
 			if (TS_MODULE_EXTENSIONS.has(extension)) {
 				const data = await createJiti(from, { interopDefault: true }).import(filePath);
 				if (takeDefault && (isObject(data) || isModule(data)) && data.default) return data.default;
@@ -476,14 +516,14 @@ function getExtension(path) {
 //#region src/utils/file.ts
 function getFileInfo(target = "", { backupFilename = "filename", extension = ".ts" } = {}) {
 	const isDir = isDirectory(target);
-	const filePath = isDir ? path.join(target, backupFilename + extension) : target;
+	const filePath = isDir ? nodePath.join(target, backupFilename + extension) : target;
 	return {
 		path: filePath,
 		pathWithoutExtension: filePath.replace(/\.[^/.]+$/, ""),
 		extension,
 		isDirectory: isDir,
-		dirname: path.dirname(filePath),
-		filename: path.basename(filePath, extension.startsWith(".") ? extension : `.${extension}`)
+		dirname: nodePath.dirname(filePath),
+		filename: nodePath.basename(filePath, extension.startsWith(".") ? extension : `.${extension}`)
 	};
 }
 async function removeFilesAndEmptyFolders(patterns, dir) {
@@ -691,13 +731,13 @@ function toUnix(value) {
 	return value;
 }
 function join(...args) {
-	return toUnix(path.join(...args.map((a) => toUnix(a))));
+	return toUnix(nodePath.join(...args.map((a) => toUnix(a))));
 }
 /**
 * Behaves exactly like `path.relative(from, to)`, but keeps the first meaningful "./"
 */
 function relativeSafe(from, to) {
-	return normalizeSafe(`./${toUnix(path.relative(toUnix(from), toUnix(to)))}`);
+	return normalizeSafe(`./${toUnix(nodePath.relative(toUnix(from), toUnix(to)))}`);
 }
 function getSchemaFileName(path) {
 	return path.replace(`.${getExtension(path)}`, "").slice(path.lastIndexOf("/") + 1);
@@ -705,13 +745,13 @@ function getSchemaFileName(path) {
 function normalizeSafe(value) {
 	let result;
 	value = toUnix(value);
-	result = toUnix(path.normalize(value));
+	result = toUnix(nodePath.normalize(value));
 	if (value.startsWith("./") && !result.startsWith("./") && !result.startsWith("..")) result = "./" + result;
 	else if (value.startsWith("//") && !result.startsWith("//")) result = value.startsWith("//./") ? "//." + result : "/" + result;
 	return result;
 }
 function joinSafe(...values) {
-	let result = toUnix(path.join(...values.map((v) => toUnix(v))));
+	let result = toUnix(nodePath.join(...values.map((v) => toUnix(v))));
 	if (values.length > 0) {
 		const firstValue = toUnix(values[0]);
 		if (firstValue.startsWith("./") && !result.startsWith("./") && !result.startsWith("..")) result = "./" + result;
@@ -742,14 +782,14 @@ function joinSafe(...values) {
 * @returns The relative import path string.
 */
 function getRelativeImportPath(importerFilePath, exporterFilePath, includeFileExtension = false) {
-	if (!path.isAbsolute(importerFilePath)) throw new Error(`'importerFilePath' is not an absolute path. "${importerFilePath}"`);
-	if (!path.isAbsolute(exporterFilePath)) throw new Error(`'exporterFilePath' is not an absolute path. "${exporterFilePath}"`);
-	const importerDir = path.dirname(importerFilePath);
-	const relativePath = path.relative(importerDir, exporterFilePath);
-	let posixPath = path.posix.join(...relativePath.split(path.sep));
+	if (!nodePath.isAbsolute(importerFilePath)) throw new Error(`'importerFilePath' is not an absolute path. "${importerFilePath}"`);
+	if (!nodePath.isAbsolute(exporterFilePath)) throw new Error(`'exporterFilePath' is not an absolute path. "${exporterFilePath}"`);
+	const importerDir = nodePath.dirname(importerFilePath);
+	const relativePath = nodePath.relative(importerDir, exporterFilePath);
+	let posixPath = nodePath.posix.join(...relativePath.split(nodePath.sep));
 	if (!posixPath.startsWith("./") && !posixPath.startsWith("../")) posixPath = `./${posixPath}`;
 	if (!includeFileExtension) {
-		const ext = path.extname(posixPath);
+		const ext = nodePath.extname(posixPath);
 		if (ext && posixPath.endsWith(ext)) posixPath = posixPath.slice(0, -ext.length);
 	}
 	return posixPath;
@@ -758,20 +798,20 @@ function getRelativeImportPath(importerFilePath, exporterFilePath, includeFileEx
 //#region src/utils/resolve-version.ts
 function resolveInstalledVersion(packageName, fromDir) {
 	try {
-		const require = createRequire(path.join(fromDir, "noop.js"));
+		const require = createRequire(nodePath.join(fromDir, "noop.js"));
 		try {
 			return require(`${packageName}/package.json`).version;
 		} catch (directError) {
 			if (directError instanceof Error && "code" in directError && directError.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
 				const entryPath = require.resolve(packageName);
-				let dir = path.dirname(entryPath);
-				while (dir !== path.parse(dir).root) {
-					const pkgPath = path.join(dir, "package.json");
+				let dir = nodePath.dirname(entryPath);
+				while (dir !== nodePath.parse(dir).root) {
+					const pkgPath = nodePath.join(dir, "package.json");
 					if (existsSync(pkgPath)) {
 						const pkgData = JSON.parse(readFileSync(pkgPath, "utf8"));
 						if (pkgData.name === packageName) return pkgData.version;
 					}
-					dir = path.dirname(dir);
+					dir = nodePath.dirname(dir);
 				}
 				return;
 			}
@@ -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;
@@ -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`;
@@ -2253,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;
@@ -2999,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;
@@ -3076,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,
@@ -3084,7 +3236,8 @@ function getQueryParams({ queryParams, operationName, context, suffix = "params"
 		},
 		deps: schemas,
 		isOptional: allOptional,
-		requiredNullableKeys
+		requiredNullableKeys,
+		...nonPrimitiveKeys.length > 0 ? { nonPrimitiveKeys } : {}
 	};
 }
 //#endregion
@@ -3240,11 +3393,11 @@ 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, "en", { numeric: true })).map(([, group]) => {
 		const sample = group[0];
@@ -3256,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";
@@ -3603,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 &&
@@ -3647,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) =>
@@ -3691,14 +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 "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") {
@@ -3712,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,";
@@ -3729,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)) {
@@ -3741,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 }) {
+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,
@@ -3757,7 +3977,8 @@ 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("}");
@@ -3776,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";
@@ -4100,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",
@@ -4264,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);
@@ -4291,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("\\", "/");
@@ -4322,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
@@ -4352,21 +4583,19 @@ 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;
 	return file;
 }
-function getPath(path$1, name, fileExtension) {
-	return path.join(path$1, `${name}${fileExtension}`);
+function getPath(path, name, fileExtension) {
+	return nodePath.join(path, `${name}${fileExtension}`);
 }
 function writeModelInline(acc, model) {
 	return acc + `${model}\n`;
@@ -4376,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({
@@ -4401,7 +4631,8 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 				target,
 				namingConvention,
 				fileExtension,
-				header
+				header,
+				tsconfig
 			});
 			continue;
 		}
@@ -4411,13 +4642,14 @@ async function writeSchemas({ schemaPath, schemas, target, namingConvention, fil
 			target,
 			namingConvention,
 			fileExtension,
-			header
+			header,
+			tsconfig
 		});
 	}
 	if (indexFiles) {
-		const schemaFilePath = path.join(schemaPath, `index.ts`);
+		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, "en", { numeric: true })).join("\n")}\n`);
@@ -4441,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);
 		}
@@ -4483,6 +4715,7 @@ function generateTarget(builder, options) {
 		formData: [],
 		formUrlEncoded: [],
 		paramsSerializer: [],
+		paramsFilter: [],
 		fetchReviver: []
 	};
 	const operations = Object.values(builder.operations);
@@ -4498,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) {
@@ -4580,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);
@@ -4628,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();
@@ -4658,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$/, "");
@@ -4686,7 +4921,7 @@ async function writeSplitMode({ builder, output, projectName, header, needSchema
 			isAllowSyntheticDefaultImports,
 			options: isFunction(output.mock) ? void 0 : output.mock
 		});
-		const schemasPath = !output.schemas && needSchema ? path.join(dirname, filename + ".schemas" + extension) : void 0;
+		const schemasPath = !output.schemas && needSchema ? nodePath.join(dirname, filename + ".schemas" + extension) : void 0;
 		if (schemasPath) await writeGeneratedFile(schemasPath, generateSchemasInline ? header + generateSchemasInline() : header + generateModelsInline(builder.schemas));
 		if (mutators) implementationData += generateMutatorImports({
 			mutators,
@@ -4696,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();
@@ -4708,9 +4944,9 @@ async function writeSplitMode({ builder, output, projectName, header, needSchema
 		implementationData += `\n${implementation}`;
 		mockData += `\n${implementationMock}`;
 		const implementationFilename = filename + (OutputClient.ANGULAR === output.client ? ".service" : "") + extension;
-		const implementationPath = path.join(dirname, implementationFilename);
+		const implementationPath = nodePath.join(dirname, implementationFilename);
 		await writeGeneratedFile(implementationPath, implementationData);
-		const mockPath = output.mock ? path.join(dirname, filename + "." + getMockFileExtensionByTypeName(output.mock) + extension) : void 0;
+		const mockPath = output.mock ? nodePath.join(dirname, filename + "." + getMockFileExtensionByTypeName(output.mock) + extension) : void 0;
 		if (mockPath) await writeGeneratedFile(mockPath, mockData);
 		return [
 			implementationPath,
@@ -4723,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) {
@@ -4740,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: {
@@ -4765,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;
@@ -4806,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] = {
@@ -4822,6 +5067,7 @@ function generateTargetForTags(builder, options) {
 					formData: target.formData,
 					formUrlEncoded: target.formUrlEncoded,
 					paramsSerializer: target.paramsSerializer,
+					paramsFilter: target.paramsFilter,
 					fetchReviver: target.fetchReviver
 				};
 			}
@@ -4845,27 +5091,27 @@ async function writeSplitTagsMode({ builder, output, projectName, header, needSc
 	const target = generateTargetForTags(builder, output);
 	const isAllowSyntheticDefaultImports = isSyntheticDefaultImportsAllow(output.tsconfig);
 	const mockOption = output.mock && !isFunction(output.mock) ? output.mock : void 0;
-	const indexFilePath = mockOption?.indexMockFiles ? path.join(dirname, "index." + getMockFileExtensionByTypeName(mockOption) + extension) : void 0;
+	const indexFilePath = mockOption?.indexMockFiles ? nodePath.join(dirname, "index." + getMockFileExtensionByTypeName(mockOption) + extension) : void 0;
 	if (indexFilePath) await fs$1.outputFile(indexFilePath, "");
 	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 = path.join(dirname, tag, tag + extension);
+			const importerPath = nodePath.join(dirname, tag, tag + extension);
 			const relativeSchemasPath = output.schemas ? getRelativeImportPath(importerPath, getFileInfo(isString(output.schemas) ? output.schemas : output.schemas.path, { extension: output.fileExtension }).dirname) : "../" + filename + ".schemas" + extension.replace(/\.ts$/, "");
 			const tagNames = new Set(tagEntries.map(([t]) => t));
 			const serviceSuffix = OutputClient.ANGULAR === output.client ? ".service" : "";
 			const importsForBuilder = generateImportsForBuilder(output, imports.map((imp) => {
 				if (!imp.importPath) return imp;
 				if (!imp.importPath.startsWith(".")) return imp;
-				const resolvedPath = path.resolve(dirname, imp.importPath);
-				const targetBasename = path.basename(resolvedPath);
+				const resolvedPath = nodePath.resolve(dirname, imp.importPath);
+				const targetBasename = nodePath.basename(resolvedPath);
 				let targetFile;
 				if (tagNames.has(targetBasename)) {
 					const tagFilename = targetBasename + serviceSuffix + extension;
-					targetFile = path.join(resolvedPath, tagFilename);
+					targetFile = nodePath.join(resolvedPath, tagFilename);
 				} else targetFile = resolvedPath + extension;
 				const adjustedPath = getRelativeImportPath(importerPath, targetFile);
 				return {
@@ -4895,7 +5141,7 @@ async function writeSplitTagsMode({ builder, output, projectName, header, needSc
 				isAllowSyntheticDefaultImports,
 				options: isFunction(output.mock) ? void 0 : output.mock
 			});
-			const schemasPath = !output.schemas && needSchema ? path.join(dirname, filename + ".schemas" + extension) : void 0;
+			const schemasPath = !output.schemas && needSchema ? nodePath.join(dirname, filename + ".schemas" + extension) : void 0;
 			if (schemasPath) await writeGeneratedFile(schemasPath, generateSchemasInline ? header + generateSchemasInline() : header + generateModelsInline(builder.schemas));
 			if (mutators) implementationData += generateMutatorImports({
 				mutators,
@@ -4918,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
@@ -4933,9 +5183,9 @@ async function writeSplitTagsMode({ builder, output, projectName, header, needSc
 			implementationData += `\n${implementation}`;
 			mockData += `\n${implementationMock}`;
 			const implementationFilename = tag + (OutputClient.ANGULAR === output.client ? ".service" : "") + extension;
-			const implementationPath = path.join(dirname, tag, implementationFilename);
+			const implementationPath = nodePath.join(dirname, tag, implementationFilename);
 			await writeGeneratedFile(implementationPath, implementationData);
-			const mockPath = output.mock ? path.join(dirname, tag, tag + "." + getMockFileExtensionByTypeName(output.mock) + extension) : void 0;
+			const mockPath = output.mock ? nodePath.join(dirname, tag, tag + "." + getMockFileExtensionByTypeName(output.mock) + extension) : void 0;
 			if (mockPath) await writeGeneratedFile(mockPath, mockData);
 			return [
 				implementationPath,
@@ -4966,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) => {
@@ -5004,7 +5254,7 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 					options: isFunction(output.mock) ? void 0 : output.mock
 				});
 			}
-			const schemasPath = !output.schemas && needSchema ? path.join(dirname, filename + ".schemas" + extension) : void 0;
+			const schemasPath = !output.schemas && needSchema ? nodePath.join(dirname, filename + ".schemas" + extension) : void 0;
 			if (schemasPath) await writeGeneratedFile(schemasPath, generateSchemasInline ? header + generateSchemasInline() : header + generateModelsInline(builder.schemas));
 			if (mutators) data += generateMutatorImports({
 				mutators,
@@ -5014,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<")) {
@@ -5029,7 +5280,7 @@ async function writeTagsMode({ builder, output, projectName, header, needSchema,
 				data += "\n\n";
 				data += implementationMock;
 			}
-			const implementationPath = path.join(dirname, `${kebab(tag)}${extension}`);
+			const implementationPath = nodePath.join(dirname, `${kebab(tag)}${extension}`);
 			await writeGeneratedFile(implementationPath, data);
 			return [implementationPath, ...schemasPath ? [schemasPath] : []];
 		} catch (error) {
@@ -5038,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