feat: add countThis option to max-params (#20236)

GerkinDev · web-flow · commit 7cbcbf9c3c20 · 2025-12-15T17:55:13.000+01:00
* feat: add type def

* feat: implement new option

* docs: update rule documentation

* chore: feedbacks

* test: fix

* test: restore altered tests
diff --git a/docs/src/rules/max-params.md b/docs/src/rules/max-params.md
@@ -29,9 +29,10 @@ This rule enforces a maximum number of parameters allowed in function definition
 This rule has a number or object option:
 
 * `"max"` (default `3`) enforces a maximum number of parameters in function definitions
-* `"countVoidThis"` (default `false`) counts a `this` declaration when the type is `void` (TypeScript only)
+* `"countThis"` (default `"except-void"`, possible values `"always"`, `"never"` or `"except-void"`) whether to count a `this` declaration (TypeScript only)
 
 **Deprecated:** The object property `maximum` is deprecated; please use the object property `max` instead.
+**Deprecated:** The object property `countVoidThis` is deprecated; please use `countThis: "except-void"` instead of `countVoidThis: false`, and `countThis: "always"` instead of `countVoidThis: true`.
 
 ### max
 
@@ -71,16 +72,21 @@ let foo2 = (bar, baz, qux) => {
 
 :::
 
-### countVoidThis (TypeScript only)
+### countThis (TypeScript only)
 
-This rule has a TypeScript-specific option `countVoidThis` that allows you to count a `this` declaration when the type is `void`.
+This rule has a TypeScript-specific option `countThis` that allows you to count a `this` declaration.
+Valid values are:
 
-Examples of **correct** TypeScript code for this rule with the default `{ "countVoidThis": false }` option:
+* `"always"`: any `this` type annotation will count as a parameter
+* `"never"`: `this` won't ever be counted
+* `"except-void"`: `this` will be counted only if its type is not `void`. Equivalent to the deprecated `countVoidThis: false`.
+
+Examples of **correct** TypeScript code for this rule:
 
 :::correct
 
 ```ts
-/*eslint max-params: ["error", { "max": 2, "countVoidThis": false }]*/
+/*eslint max-params: ["error", { "max": 2, "countThis": "except-void" }]*/
 
 function hasNoThis(this: void, first: string, second: string) {
 	// ...
@@ -89,42 +95,38 @@ function hasNoThis(this: void, first: string, second: string) {
 
 :::
 
-Examples of **incorrect** TypeScript code for this rule with the default `{ "countVoidThis": false }` option:
-
-:::incorrect
+:::correct
 
 ```ts
-/*eslint max-params: ["error", { "max": 2, "countVoidThis": false }]*/
+/*eslint max-params: ["error", { "max": 2, "countThis": "never" }]*/
 
-function hasNoThis(this: void, first: string, second: string, third: string) {
+function hasThis(this: unknown[], first: string, second: string) {
 	// ...
 }
 ```
 
 :::
 
-Examples of **correct** TypeScript code for this rule with the `{ "countVoidThis": true }` option:
+Examples of **incorrect** TypeScript code for this rule:
 
-:::correct
+:::incorrect
 
 ```ts
-/*eslint max-params: ["error", { "max": 2, "countVoidThis": true }]*/
+/*eslint max-params: ["error", { "max": 2, "countThis": "always" }]*/
 
-function hasNoThis(this: void, first: string) {
+function hasNoThis(this: void, first: string, second: string) {
 	// ...
 }
 ```
 
 :::
 
-Examples of **incorrect** TypeScript code for this rule with the `{ "countVoidThis": true }` option:
-
 :::incorrect
 
 ```ts
-/*eslint max-params: ["error", { "max": 2, "countVoidThis": true }]*/
+/*eslint max-params: ["error", { "max": 2, "countThis": "except-void" }]*/
 
-function hasNoThis(this: void, first: string, second: string) {
+function hasThis(this: unknown[], first: string, second: string) {
 	// ...
 }
 ```
diff --git a/lib/rules/max-params.js b/lib/rules/max-params.js
@@ -53,8 +53,14 @@ module.exports = {
 								description:
 									"Whether to count a `this` declaration when the type is `void`.",
 							},
+							countThis: {
+								enum: ["never", "except-void", "always"],
+								description:
+									"Whether to count a `this` declaration.",
+							},
 						},
 						additionalProperties: false,
+						not: { required: ["countVoidThis", "countThis"] },
 					},
 				],
 			},
@@ -68,7 +74,7 @@ module.exports = {
 		const sourceCode = context.sourceCode;
 		const option = context.options[0];
 		let numParams = 3;
-		let countVoidThis = false;
+		let countThis = "except-void";
 
 		if (typeof option === "object") {
 			if (
@@ -77,7 +83,12 @@ module.exports = {
 			) {
 				numParams = option.maximum || option.max;
 			}
-			countVoidThis = option.countVoidThis;
+
+			countThis = option.countThis;
+			if (!countThis && Object.hasOwn(option, "countVoidThis")) {
+				countThis = option.countVoidThis ? "always" : "except-void";
+			}
+			countThis ||= "except-void";
 		}
 		if (typeof option === "number") {
 			numParams = option;
@@ -90,17 +101,25 @@ module.exports = {
 		 * @private
 		 */
 		function checkFunction(node) {
-			const hasVoidThisParam =
+			const thisParam =
 				node.params.length > 0 &&
 				node.params[0].type === "Identifier" &&
-				node.params[0].name === "this" &&
-				node.params[0].typeAnnotation?.typeAnnotation.type ===
-					"TSVoidKeyword";
+				node.params[0].name === "this"
+					? node.params[0]
+					: null;
 
-			const effectiveParamCount =
-				hasVoidThisParam && !countVoidThis
-					? node.params.length - 1
-					: node.params.length;
+			let effectiveParamCount = node.params.length;
+			if (thisParam) {
+				if (countThis === "never") {
+					effectiveParamCount = node.params.length - 1;
+				} else if (
+					countThis === "except-void" &&
+					thisParam.typeAnnotation?.typeAnnotation.type ===
+						"TSVoidKeyword"
+				) {
+					effectiveParamCount = node.params.length - 1;
+				}
+			}
 
 			if (effectiveParamCount > numParams) {
 				context.report({
diff --git a/lib/types/rules.d.ts b/lib/types/rules.d.ts
@@ -1858,9 +1858,14 @@ export interface ESLintRules extends Linter.RulesRecord {
 					 */
 					max: number;
 					/**
+					 * @deprecated Replaced with `countThis'
 					 * @default false
 					 */
 					countVoidThis: boolean;
+					/**
+					 * @default "except-void"
+					 */
+					countThis: "always" | "never" | "except-void";
 			  }>,
 		]
 	>;
diff --git a/tests/lib/rules/max-params.js b/tests/lib/rules/max-params.js
@@ -232,6 +232,14 @@ ruleTesterTypeScript.run("max-params", rule, {
 		`,
 			options: [{ max: 2 }],
 		},
+		{
+			code: `function foo(this: unknown[], a, b, c) {}`,
+			options: [{ max: 3, countThis: "never" }],
+		},
+		{
+			code: `function foo(this: void, a, b, c) {}`,
+			options: [{ max: 3, countThis: "except-void" }],
+		},
 	],
 	invalid: [
 		{
@@ -268,11 +276,35 @@ ruleTesterTypeScript.run("max-params", rule, {
 			options: [{ countVoidThis: true, max: 1 }],
 			errors: [{ messageId: "exceed" }],
 		},
+		{
+			code: `
+  class Foo {
+	method(this: void, a) {}
+  }
+		`,
+			options: [{ countThis: "always", max: 1 }],
+			errors: [{ messageId: "exceed" }],
+		},
 		{
 			code: `function testD(this: void, a) {}`,
 			options: [{ countVoidThis: true, max: 1 }],
 			errors: [{ messageId: "exceed" }],
 		},
+		{
+			code: `function testD(this: void, a) {}`,
+			options: [{ countThis: "always", max: 1 }],
+			errors: [{ messageId: "exceed" }],
+		},
+		{
+			code: `const testE = function (this: void, a) {}`,
+			options: [{ countThis: "always", max: 1 }],
+			errors: [{ messageId: "exceed" }],
+		},
+		{
+			code: `function testFunction(test: void, a: number) {}`,
+			options: [{ countThis: "except-void", max: 1 }],
+			errors: [{ messageId: "exceed" }],
+		},
 		{
 			code: `const testE = function (this: void, a) {}`,
 			options: [{ countVoidThis: true, max: 1 }],
@@ -305,5 +337,15 @@ ruleTesterTypeScript.run("max-params", rule, {
 			options: [{ max: 1 }],
 			errors: [{ messageId: "exceed" }],
 		},
+		{
+			code: `function foo(this: unknown[], a, b, c) {}`,
+			options: [{ max: 3, countThis: "always" }],
+			errors: [{ messageId: "exceed" }],
+		},
+		{
+			code: `function foo(this: unknown[], a, b, c) {}`,
+			options: [{ max: 3, countThis: "except-void" }],
+			errors: [{ messageId: "exceed" }],
+		},
 	],
 });
