typescript-eslint · JoshuaKGoldberg · Mar 2, 2025 · Jul 10, 2024 · Jul 10, 2024 · Jul 10, 2024
diff --git a/packages/eslint-plugin/docs/rules/no-unnecessary-type-parameters.mdx b/packages/eslint-plugin/docs/rules/no-unnecessary-type-parameters.mdx
@@ -82,10 +82,30 @@ For example, the following `T` is used multiple times by virtue of being in an `
 declare function createStateHistory<T>(): T[];
 ```
 
-This is because the type parameter `T` relates multiple methods in the `T[]` together, making it used more than once.
+This is because the type parameter `T` relates multiple methods in `T[]` (`Array<T>`) together, making it used more than once.
 
 Therefore, this rule won't report on type parameters used as a type argument.
-That includes type arguments given to global types such as `Array` (including the `T[]` shorthand and in tuples), `Map`, and `Set`.
+This includes type arguments provided to global types such as `Array`, `Map`, and `Set` that have multiple methods and properties that can change values based on the type parameter.
+
+On the other hand, readonly and fixed array-likes such as `readonly T[]`, `ReadonlyArray`, and tuples such as `[T]` are special cases that are specifically reported on when used as input types, or as `readonly` output types.
+The following example will be reported because `T` is used only once as type argument for the `ReadonlyArray` global type:
+
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+declare function length<T>(array: ReadonlyArray<T>): number;
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
+
+```ts
+declare function length(array: ReadonlyArray<unknown>): number;
+```
+
+</TabItem>
+</Tabs>
 
 ## FAQ
 

diff --git a/packages/eslint-plugin/src/rules/no-unnecessary-type-parameters.ts b/packages/eslint-plugin/src/rules/no-unnecessary-type-parameters.ts
@@ -239,9 +239,17 @@ function isTypeParameterRepeatedInAST(
       const grandparent = skipConstituentsUpward(
         reference.identifier.parent.parent,
       );
+
       if (
         grandparent.type === AST_NODE_TYPES.TSTypeParameterInstantiation &&
-        grandparent.params.includes(reference.identifier.parent)
+        grandparent.params.includes(reference.identifier.parent) &&
+        // Array and ReadonlyArray must be handled carefully
+        // let's defer the check to the type-aware phase
+        !(
+          grandparent.parent.type === AST_NODE_TYPES.TSTypeReference &&
+          grandparent.parent.typeName.type === AST_NODE_TYPES.Identifier &&
+          ['Array', 'ReadonlyArray'].includes(grandparent.parent.typeName.name)
+        )
       ) {
         return true;
       }
@@ -281,13 +289,13 @@ function countTypeParameterUsage(
 
   if (ts.isClassLike(node)) {
     for (const typeParameter of node.typeParameters) {
-      collectTypeParameterUsageCounts(checker, typeParameter, counts);
+      collectTypeParameterUsageCounts(checker, typeParameter, counts, true);
     }
     for (const member of node.members) {
-      collectTypeParameterUsageCounts(checker, member, counts);
+      collectTypeParameterUsageCounts(checker, member, counts, true);
     }
   } else {
-    collectTypeParameterUsageCounts(checker, node, counts);
+    collectTypeParameterUsageCounts(checker, node, counts, false);
   }
 
   return counts;
@@ -302,6 +310,7 @@ function collectTypeParameterUsageCounts(
   checker: ts.TypeChecker,
   node: ts.Node,
   foundIdentifierUsages: Map<ts.Identifier, number>,
+  fromClass: boolean, // We are talking about the type parameters of a class or one of its methods
 ): void {
   const visitedSymbolLists = new Set<ts.Symbol[]>();
   const type = checker.getTypeAtLocation(node);
@@ -325,6 +334,7 @@ function collectTypeParameterUsageCounts(
   function visitType(
     type: ts.Type | undefined,
     assumeMultipleUses: boolean,
+    isReturnType = false,
   ): void {
     // Seeing the same type > (threshold=3 ** 2) times indicates a likely
     // recursive type, like `type T = { [P in keyof T]: T }`.
@@ -380,9 +390,23 @@ function collectTypeParameterUsageCounts(
 
     // Tuple types like `[K, V]`
     // Generic type references like `Map<K, V>`
-    else if (tsutils.isTupleType(type) || tsutils.isTypeReference(type)) {
+    else if (tsutils.isTypeReference(type)) {
       for (const typeArgument of type.typeArguments ?? []) {
-        visitType(typeArgument, true);
+        // currently, if we are in a "class context", everything is accepted
+        let thisAssumeMultipleUses = fromClass || assumeMultipleUses;
+
+        // special cases - readonly arrays/tuples are considered only to use the
+        // type parameter once. Mutable arrays/tuples are considered to use the
+        // type parameter multiple times if and only if they are returned.
+        // other kind of type references always count as multiple uses
+        thisAssumeMultipleUses ||= tsutils.isTupleType(type.target)
+          ? isReturnType && !type.target.readonly
+          : checker.isArrayType(type.target)
+            ? isReturnType &&
+              (type.symbol as ts.Symbol | undefined)?.getName() === 'Array'
+            : true;
+
+        visitType(typeArgument, thisAssumeMultipleUses, isReturnType);
       }
     }
 
@@ -472,6 +496,7 @@ function collectTypeParameterUsageCounts(
       checker.getTypePredicateOfSignature(signature)?.type ??
         signature.getReturnType(),
       false,
+      true,
     );
   }
 

diff --git a/...ages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unnecessary-type-parameters.shot b/...ages/eslint-plugin/tests/docs-eslint-output-snapshots/no-unnecessary-type-parameters.shot
diff --git a/packages/eslint-plugin/tests/rules/no-unnecessary-type-parameters.test.ts b/packages/eslint-plugin/tests/rules/no-unnecessary-type-parameters.test.ts
@@ -64,13 +64,6 @@ ruleTester.run('no-unnecessary-type-parameters', rule, {
         }
       }
     `,
-    `
-      class Joiner {
-        join<T extends string | number>(els: T[]) {
-          return els.map(el => '' + el).join(',');
-        }
-      }
-    `,
     `
       declare class Foo {
         getProp<T>(this: Record<'prop', T>): T;
@@ -243,8 +236,14 @@ ruleTester.run('no-unnecessary-type-parameters', rule, {
     'declare function makeSets<K>(): [Set<K>][];',
     'declare function makeMap<K, V>(): Map<K, V>;',
     'declare function makeMap<K, V>(): [Map<K, V>];',
+    'declare function makeArray<T>(): T[];',
+    'declare function makeArrayNullish<T>(): (T | null)[];',
+    'declare function makeTupleMulti<T>(): [T | null, T | null];',
+    'declare function takeTupleMulti<T>(input: [T, T]): void;',
+    'declare function takeTupleMultiNullish<T>(input: [T | null, T | null]): void;',
     'declare function arrayOfPairs<T>(): [T, T][];',
     'declare function fetchJson<T>(url: string): Promise<T>;',
+    'declare function fetchJsonTuple<T>(url: string): Promise<[T]>;',
     'declare function fn<T>(input: T): 0 extends 0 ? T : never;',
     'declare function useFocus<T extends HTMLOrSVGElement>(): [React.RefObject<T>];',
     `
@@ -447,6 +446,36 @@ const f = <T,>(
         },
       ],
     },
+    {
+      code: 'const func = <T,>(param: [T]) => null;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: 'const func = (param: [unknown]) => null;',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'const func = <T,>(param: T[]) => null;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: 'const func = (param: unknown[]) => null;',
+            },
+          ],
+        },
+      ],
+    },
     {
       code: 'const f1 = <T,>(): T => {};',
       errors: [
@@ -1249,6 +1278,139 @@ function foo(_: unknown): <T>(input: T) => T {
         },
       ],
     },
+    {
+      code: 'declare function makeReadonlyArray<T>(): readonly T[];',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output:
+                'declare function makeReadonlyArray(): readonly unknown[];',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function makeReadonlyTuple<T>(): readonly [T];',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output:
+                'declare function makeReadonlyTuple(): readonly [unknown];',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function makeReadonlyTupleNullish<T>(): readonly [T | null];',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output:
+                'declare function makeReadonlyTupleNullish(): readonly [unknown | null];',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function takeArray<T>(input: T[]): void;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: 'declare function takeArray(input: unknown[]): void;',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function takeArrayNullish<T>(input: (T | null)[]): void;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output:
+                'declare function takeArrayNullish(input: (unknown | null)[]): void;',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function takeTuple<T>(input: [T]): void;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: 'declare function takeTuple(input: [unknown]): void;',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: 'declare function takeTupleMultiUnrelated<T>(input: [T, number]): void;',
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output:
+                'declare function takeTupleMultiUnrelated(input: [unknown, number]): void;',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      code: `
+        declare function takeTupleMultiUnrelatedNullish<T>(
+          input: [T | null, null],
+        ): void;
+      `,
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: `
+        declare function takeTupleMultiUnrelatedNullish(
+          input: [unknown | null, null],
+        ): void;
+      `,
+            },
+          ],
+        },
+      ],
+    },
     {
       code: 'type Fn = <T>() => T;',
       errors: [
@@ -1555,5 +1717,32 @@ function f(x: unknown): void {
         },
       ],
     },
+    {
+      code: `
+class Joiner {
+  join<T extends number>(els: T[]) {
+    return els.map(el => '' + el).join(',');
+  }
+}
+      `,
+      errors: [
+        {
+          data: { descriptor: 'function', name: 'T', uses: 'used only once' },
+          messageId: 'sole',
+          suggestions: [
+            {
+              messageId: 'replaceUsagesWithConstraint',
+              output: `
+class Joiner {
+  join(els: number[]) {
+    return els.map(el => '' + el).join(',');
+  }
+}
+    `,
+            },
+          ],
+        },
+      ],
+    },
   ],
 });