fix: make isTypeParameter no longer a typeguard (#597)

Co-authored-by: Rebecca Stevens <rebecca.stevens@outlook.co.nz>

Author: kirkwaiblinger

src/types/typeGuards/single.test.ts

@@ -1,12 +1,13 @@
 import ts from "typescript";
-import { describe, expect, it } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
 
 import { createSourceFileAndTypeChecker } from "../../test/utils";
 import {
 	isConditionalType,
 	isEnumType,
 	isIntersectionType,
 	isObjectType,
+	isTypeParameter,
 	isUnionOrIntersectionType,
 	isUnionType,
 	isUniqueESSymbolType,
@@ -74,6 +75,45 @@ describe("isObjectType", () => {
 	});
 });
 
+describe("isTypeParameter", () => {
+	it("should return true for a type parameter", () => {
+		const sourceText = `type Test<TParam> = { foo: string };`;
+		const { sourceFile, typeChecker } =
+			createSourceFileAndTypeChecker(sourceText);
+
+		const testNode = sourceFile.statements.at(-1) as ts.TypeAliasDeclaration;
+		const tParamNode = testNode.typeParameters?.[0];
+		expect(tParamNode).toBeDefined();
+
+		const tParamType = typeChecker.getTypeAtLocation(tParamNode!);
+
+		const isTParamATypeParameter = isTypeParameter(tParamType);
+		// type test - see https://github.com/JoshuaKGoldberg/ts-api-utils/issues/382
+		if (isTParamATypeParameter) {
+			expectTypeOf(tParamType).toEqualTypeOf<ts.TypeParameter>();
+		} else {
+			expectTypeOf(tParamType).toEqualTypeOf<ts.Type>();
+		}
+
+		expect(isTParamATypeParameter).toBe(true);
+	});
+
+	it("should return false when not a type parameter", () => {
+		const sourceText = `type Test<T> = { foo: string };`;
+		const testType = getTypeForTypeNode(sourceText);
+
+		const isTestATypeParameter = isTypeParameter(testType);
+		// type test - see https://github.com/JoshuaKGoldberg/ts-api-utils/issues/382
+		if (isTestATypeParameter) {
+			expectTypeOf(testType).toEqualTypeOf<ts.TypeParameter>();
+		} else {
+			expectTypeOf(testType).toEqualTypeOf<ts.Type>();
+		}
+
+		expect(isTestATypeParameter).toBe(false);
+	});
+});
+
 describe("isUnionOrIntersectionType", () => {
 	it.each([
 		[false, "type Test = 1;"],

src/types/typeGuards/single.ts

@@ -168,6 +168,9 @@ export function isSubstitutionType(type: ts.Type): type is ts.SubstitutionType {
 
 /**
  * Test if a type is a `TypeParameter`.
+ *
+ * Note: It is intentional that this is not a type guard.
+ * @see https://github.com/JoshuaKGoldberg/ts-api-utils/issues/382
  * @category Types - Type Guards
  * @example
  * ```ts
@@ -178,7 +181,7 @@ export function isSubstitutionType(type: ts.Type): type is ts.SubstitutionType {
  * }
  * ```
  */
-export function isTypeParameter(type: ts.Type): type is ts.TypeParameter {
+export function isTypeParameter(type: ts.Type): boolean {
 	return isTypeFlagSet(type, ts.TypeFlags.TypeParameter);
 }