feat(expect, @jest/expect-utils): allow isA utility to take a type argument

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Features
 
 - `[jest-core]` Enable testResultsProcessor to be async ([#13343](https://github.com/facebook/jest/pull/13343))
+- `[expect, @jest/expect-utils]` Allow `isA` utility to take a type argument ([#13355](https://github.com/facebook/jest/pull/13355))
 
 ### Fixes
 

packages/expect-utils/__typetests__/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "skipLibCheck": true,
+
+    "types": []
+  },
+  "include": ["./**/*"]
+}

packages/expect-utils/__typetests__/utils.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {expectType} from 'tsd-lite';
+import {isA} from '@jest/expect-utils';
+
+// isA
+
+expectType<boolean>(isA('String', 'default'));
+expectType<boolean>(isA<number>('Number', 123));
+
+const sample = {} as unknown;
+
+expectType<unknown>(sample);
+
+if (isA('String', sample)) {
+  expectType<unknown>(sample);
+}
+
+if (isA<string>('String', sample)) {
+  expectType<string>(sample);
+}
+
+if (isA<number>('Number', sample)) {
+  expectType<number>(sample);
+}
+
+if (isA<Map<unknown, unknown>>('Map', sample)) {
+  expectType<Map<unknown, unknown>>(sample);
+}
+
+if (isA<Set<unknown>>('Set', sample)) {
+  expectType<Set<unknown>>(sample);
+}

packages/expect-utils/package.json

@@ -20,8 +20,10 @@
     "jest-get-type": "workspace:^"
   },
   "devDependencies": {
+    "@tsd/typescript": "~4.8.2",
     "immutable": "^4.0.0",
-    "jest-matcher-utils": "workspace:^"
+    "jest-matcher-utils": "workspace:^",
+    "tsd-lite": "^0.6.0"
   },
   "engines": {
     "node": "^14.15.0 || ^16.10.0 || >=18.0.0"

packages/expect-utils/src/jasmineUtils.ts

@@ -224,7 +224,7 @@ function hasKey(obj: any, key: string) {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
 
-export function isA(typeName: string, value: unknown) {
+export function isA<T>(typeName: string, value: unknown): value is T {
   return Object.prototype.toString.apply(value) === '[object ' + typeName + ']';
 }
 
@@ -262,10 +262,7 @@ export function isImmutableUnorderedSet(maybeSet: any) {
 }
 
 export function isImmutableList(maybeList: any) {
-  return !!(
-    maybeList &&
-    maybeList[IS_LIST_SENTINEL]
-  );
+  return !!(maybeList && maybeList[IS_LIST_SENTINEL]);
 }
 
 export function isImmutableOrderedKeyed(maybeKeyed: any) {
@@ -276,7 +273,6 @@ export function isImmutableOrderedKeyed(maybeKeyed: any) {
   );
 }
 
-
 export function isImmutableOrderedSet(maybeSet: any) {
   return !!(
     maybeSet &&
@@ -286,8 +282,5 @@ export function isImmutableOrderedSet(maybeSet: any) {
 }
 
 export function isImmutableRecord(maybeSet: any) {
-  return !!(
-    maybeSet &&
-    maybeSet[IS_RECORD_SYMBOL]
-  );
-}
+  return !!(maybeSet && maybeSet[IS_RECORD_SYMBOL]);
+}

packages/expect-utils/src/utils.ts

@@ -184,7 +184,7 @@ export const iterableEquality = (
   if (a.size !== undefined) {
     if (a.size !== b.size) {
       return false;
-    } else if (isA('Set', a) || isImmutableUnorderedSet(a)) {
+    } else if (isA<Set<unknown>>('Set', a) || isImmutableUnorderedSet(a)) {
       let allFound = true;
       for (const aValue of a) {
         if (!b.has(aValue)) {
@@ -206,7 +206,10 @@ export const iterableEquality = (
       aStack.pop();
       bStack.pop();
       return allFound;
-    } else if (isA('Map', a) || isImmutableUnorderedKeyed(a)) {
+    } else if (
+      isA<Map<unknown, unknown>>('Map', a) ||
+      isImmutableUnorderedKeyed(a)
+    ) {
       let allFound = true;
       for (const aEntry of a) {
         if (

packages/expect/src/asymmetricMatchers.ts

@@ -185,7 +185,7 @@ class ArrayContaining extends AsymmetricMatcher<Array<unknown>> {
     super(sample, inverse);
   }
 
-  asymmetricMatch(other: Array<unknown>) {
+  asymmetricMatch(other: unknown) {
     if (!Array.isArray(this.sample)) {
       throw new Error(
         `You must provide an array to ${this.toString()}, not '${typeof this
@@ -257,8 +257,8 @@ class StringContaining extends AsymmetricMatcher<string> {
     super(sample, inverse);
   }
 
-  asymmetricMatch(other: string) {
-    const result = isA('String', other) && other.includes(this.sample);
+  asymmetricMatch(other: unknown) {
+    const result = isA<string>('String', other) && other.includes(this.sample);
 
     return this.inverse ? !result : result;
   }
@@ -280,8 +280,8 @@ class StringMatching extends AsymmetricMatcher<RegExp> {
     super(new RegExp(sample), inverse);
   }
 
-  asymmetricMatch(other: string) {
-    const result = isA('String', other) && this.sample.test(other);
+  asymmetricMatch(other: unknown) {
+    const result = isA<string>('String', other) && this.sample.test(other);
 
     return this.inverse ? !result : result;
   }
@@ -297,6 +297,7 @@ class StringMatching extends AsymmetricMatcher<RegExp> {
 
 class CloseTo extends AsymmetricMatcher<number> {
   private precision: number;
+
   constructor(sample: number, precision = 2, inverse = false) {
     if (!isA('Number', sample)) {
       throw new Error('Expected is not a Number');
@@ -311,8 +312,8 @@ class CloseTo extends AsymmetricMatcher<number> {
     this.precision = precision;
   }
 
-  asymmetricMatch(other: number) {
-    if (!isA('Number', other)) {
+  asymmetricMatch(other: unknown) {
+    if (!isA<number>('Number', other)) {
       return false;
     }
     let result = false;

yarn.lock

@@ -2695,9 +2695,11 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@jest/expect-utils@workspace:packages/expect-utils"
   dependencies:
+    "@tsd/typescript": ~4.8.2
     immutable: ^4.0.0
     jest-get-type: "workspace:^"
     jest-matcher-utils: "workspace:^"
+    tsd-lite: ^0.6.0
   languageName: unknown
   linkType: soft