feat(assertion): Add .toBeInstanceOf(Constructor) matcher

src/lib/Assertion.ts

@@ -217,6 +217,36 @@ export class Assertion<T> {
     });
   }
 
+  /**
+   * Check if the value is an instance of the the provided constructor.
+   *
+   * @example
+   * ```
+   * expect(pontiac).toBeInstanceOf(Car);
+   *
+   * expect(today).toBeInstanceOf(Date);
+   * ```
+   *
+   * @param Expected the constructor the value should be an instance
+   * @returns the assertion instance
+   */
+  public toBeInstanceOf(Expected: new (...args: any[]) => any): this {
+    const error = new AssertionError({
+      actual: this.actual,
+      message: `Expected value to be an instance of <${Expected.name}>`
+    });
+    const invertedError = new AssertionError({
+      actual: this.actual,
+      message: `Expected value NOT to be an instance of <${Expected.name}>`
+    });
+
+    return this.execute({
+      assertWhen: this.actual instanceof Expected,
+      error,
+      invertedError
+    });
+  }
+
   /**
    * Check if the value is deep equal to another value.
    *

src/lib/ObjectAssertion.ts

@@ -3,7 +3,7 @@ import { isDeepStrictEqual } from "util";
 
 import { Assertion } from "./Assertion";
 
-export type JSObject = Record<keyof any, unknown>;
+export type JSObject = Record<keyof any, any>;
 
 export type Entry<T, K = keyof T> = K extends keyof T
   ? [K, T[K]]

test/lib/Assertion.test.ts

@@ -52,6 +52,19 @@ const BASE_DIFFS = [
   ["date", TODAY, new Date("2021-12-10T00:00:00.001Z")]
 ];
 
+class Car {
+
+  private readonly model: string;
+
+  constructor(model: string) {
+    this.model = model;
+  }
+
+  public showModel(): string {
+    return this.model;
+  }
+}
+
 function truthyAsText(value: typeof TRUTHY_VALUES[number]): string {
   if (Array.isArray(value) && value.length === 0) {
     return "Empty array";
@@ -263,6 +276,40 @@ describe("[Unit] Assertion.test.ts", () => {
     });
   });
 
+  describe.only(".toBeInstanceOf", () => {
+    context("when the value is an instance of the constructor", () => {
+      const variants = [
+        [new Date(), Date],
+        [new Error("failed!"), Error],
+        [new Car("Pontiac GT-37"), Car]
+      ] as const;
+
+      variants.forEach(([value, Constructor]) => {
+        it(`[Instance: ${Constructor.name}]: returns the assertion instance`, () => {
+          const test = new Assertion(value);
+
+          assert.deepStrictEqual(test.toBeInstanceOf(Constructor), test);
+          assert.throws(() => test.not.toBeInstanceOf(Constructor), {
+            message: `Expected value NOT to be an instance of <${Constructor.name}>`,
+            name: AssertionError.name
+          });
+        });
+      });
+    });
+
+    context("when the vlaue in not an instance of the constructor", () => {
+      it("throws an assertion error", () => {
+        const test = new Assertion(new Date());
+
+        assert.throws(() => test.toBeInstanceOf(Car), {
+          message: "Expected value to be an instance of <Car>",
+          name: AssertionError.name
+        });
+        assert.deepStrictEqual(test.not.toBeInstanceOf(Car), test);
+      });
+    });
+  });
+
   describe(".toBeEqual", () => {
     context("when the value is referentially, shallow, and deep equal", () => {
       [