feat: adds class instance type guard utility

Provides type-safe checking for class instances with optional constructor validation

Supports both specific class checking and general instance detection

Excludes plain objects, primitives, arrays, and null values

Includes comprehensive test coverage for edge cases and type narrowing

Author: sillvva

README.md

@@ -59,6 +59,34 @@ const defined = values.filter(isDefined); // number[]
 console.log(defined); // [1, 2, 3]
 ```
 
+### isInstanceOfClass
+
+```typescript
+import { isInstanceOfClass } from "@sillvva/utils";
+
+class User {
+	constructor(public name: string) {}
+}
+
+const user = new User("John");
+const plainObj = { name: "Jane" };
+
+// Check specific class
+console.log(isInstanceOfClass(user, User)); // true
+console.log(isInstanceOfClass(plainObj, User)); // false
+
+// Check for any class instance
+console.log(isInstanceOfClass(user)); // true
+console.log(isInstanceOfClass(plainObj)); // false
+
+// Type narrowing
+function processUser(data: unknown) {
+	if (isInstanceOfClass(data, User)) {
+		console.log(data.name); // TypeScript knows data is User
+	}
+}
+```
+
 ### isOneOf
 
 ```typescript

src/entry.ts

@@ -1,6 +1,7 @@
 export * from "./abortable";
 export * from "./debounce";
 export * from "./isDefined";
+export * from "./isInstanceOfClass";
 export * from "./isOneOf";
 export * from "./slugify";
 export * from "./sorter";

src/isInstanceOfClass.test.ts

@@ -0,0 +1,159 @@
+import { isInstanceOfClass } from "./isInstanceOfClass";
+
+// Test classes
+class TestClass {
+	constructor(public value: string) {}
+}
+
+class AnotherClass {
+	constructor(public number: number) {}
+}
+
+class SubClass extends TestClass {
+	constructor(value: string, public extra: boolean) {
+		super(value);
+	}
+}
+
+describe("isInstanceOfClass", () => {
+	describe("with specific class constructor", () => {
+		it("returns true for instances of the specified class", () => {
+			const instance = new TestClass("test");
+			expect(isInstanceOfClass(instance, TestClass)).toBe(true);
+		});
+
+		it("returns true for instances of subclasses", () => {
+			const subInstance = new SubClass("test", true);
+			expect(isInstanceOfClass(subInstance, TestClass)).toBe(true);
+		});
+
+		it("returns false for instances of different classes", () => {
+			const instance = new TestClass("test");
+			expect(isInstanceOfClass(instance, AnotherClass)).toBe(false);
+		});
+
+		it("returns false for plain objects", () => {
+			const plainObj = { value: "test" };
+			expect(isInstanceOfClass(plainObj, TestClass)).toBe(false);
+		});
+
+		it("returns false for primitives", () => {
+			expect(isInstanceOfClass("string", TestClass)).toBe(false);
+			expect(isInstanceOfClass(123, TestClass)).toBe(false);
+			expect(isInstanceOfClass(true, TestClass)).toBe(false);
+			expect(isInstanceOfClass(Symbol(), TestClass)).toBe(false);
+		});
+
+		it("returns false for null and undefined", () => {
+			expect(isInstanceOfClass(null, TestClass)).toBe(false);
+			expect(isInstanceOfClass(undefined, TestClass)).toBe(false);
+		});
+
+		it("returns false for arrays", () => {
+			expect(isInstanceOfClass([], TestClass)).toBe(false);
+			expect(isInstanceOfClass([1, 2, 3], TestClass)).toBe(false);
+		});
+
+		it("returns false for functions", () => {
+			expect(isInstanceOfClass(() => {}, TestClass)).toBe(false);
+			expect(isInstanceOfClass(function () {}, TestClass)).toBe(false);
+		});
+
+		it("works as a type guard", () => {
+			const items = [
+				new TestClass("a"),
+				{ value: "b" }, // plain object
+				new AnotherClass(1),
+				new TestClass("c")
+			];
+
+			const testClassInstances = items.filter((item): item is TestClass => isInstanceOfClass(item, TestClass));
+
+			expect(testClassInstances).toHaveLength(2);
+			expect(testClassInstances[0]).toBeInstanceOf(TestClass);
+			expect(testClassInstances[1]).toBeInstanceOf(TestClass);
+		});
+	});
+
+	describe("without class constructor (checking for any class instance)", () => {
+		it("returns true for class instances", () => {
+			const testInstance = new TestClass("test");
+			const anotherInstance = new AnotherClass(123);
+			const subInstance = new SubClass("test", true);
+
+			expect(isInstanceOfClass(testInstance)).toBe(true);
+			expect(isInstanceOfClass(anotherInstance)).toBe(true);
+			expect(isInstanceOfClass(subInstance)).toBe(true);
+		});
+
+		it("returns false for plain objects", () => {
+			const plainObj = { value: "test" };
+			const emptyObj = {};
+
+			expect(isInstanceOfClass(plainObj)).toBe(false);
+			expect(isInstanceOfClass(emptyObj)).toBe(false);
+		});
+
+		it("returns false for primitives", () => {
+			expect(isInstanceOfClass("string")).toBe(false);
+			expect(isInstanceOfClass(123)).toBe(false);
+			expect(isInstanceOfClass(true)).toBe(false);
+			expect(isInstanceOfClass(Symbol())).toBe(false);
+		});
+
+		it("returns false for null and undefined", () => {
+			expect(isInstanceOfClass(null)).toBe(false);
+			expect(isInstanceOfClass(undefined)).toBe(false);
+		});
+
+		it("returns false for arrays", () => {
+			expect(isInstanceOfClass([])).toBe(false);
+			expect(isInstanceOfClass([1, 2, 3])).toBe(false);
+		});
+
+		it("returns false for functions", () => {
+			expect(isInstanceOfClass(() => {})).toBe(false);
+			expect(isInstanceOfClass(function () {})).toBe(false);
+		});
+
+		it("works as a type guard for any class instance", () => {
+			const items = [
+				new TestClass("a"),
+				{ value: "b" }, // plain object
+				new AnotherClass(1),
+				"string", // primitive
+				new SubClass("c", true)
+			];
+
+			const classInstances = items.filter((item): item is TestClass | AnotherClass | SubClass => isInstanceOfClass(item));
+
+			expect(classInstances).toHaveLength(3);
+			expect(classInstances[0]).toBeInstanceOf(TestClass);
+			expect(classInstances[1]).toBeInstanceOf(AnotherClass);
+			expect(classInstances[2]).toBeInstanceOf(SubClass);
+		});
+	});
+
+	describe("edge cases", () => {
+		it("handles objects created with Object.create(null)", () => {
+			const nullProtoObj = Object.create(null);
+			expect(isInstanceOfClass(nullProtoObj)).toBe(false); // Not a plain object
+			expect(isInstanceOfClass(nullProtoObj, TestClass)).toBe(false);
+		});
+
+		it("handles objects with modified prototypes", () => {
+			const obj = {};
+			Object.setPrototypeOf(obj, null);
+			expect(isInstanceOfClass(obj)).toBe(false); // Not a plain object
+		});
+
+		it("handles built-in objects", () => {
+			expect(isInstanceOfClass(new Date())).toBe(true);
+			expect(isInstanceOfClass(new Date(), Date)).toBe(true);
+			expect(isInstanceOfClass(new Date(), TestClass)).toBe(false);
+
+			expect(isInstanceOfClass(new RegExp("test"))).toBe(true);
+			expect(isInstanceOfClass(new RegExp("test"), RegExp)).toBe(true);
+		});
+	});
+});

src/isInstanceOfClass.ts

@@ -0,0 +1,79 @@
+/**
+ * Type guard function that checks if a value is an instance of a class
+ * @module
+ */
+
+/**
+ * Type guard function that checks if a value is an instance of a class
+ * @param obj The value to check
+ * @param ClassConstructor Optional class constructor to check against
+ * @returns True if the value is an instance of the specified class (or any class if no constructor provided), false otherwise
+ *
+ * @example Basic usage with specific class
+ * import { isInstanceOfClass } from "@sillvva/utils";
+ *
+ * class MyClass {}
+ * const instance = new MyClass();
+ * const plainObj = {};
+ *
+ * console.log(isInstanceOfClass(instance, MyClass)); // true
+ * console.log(isInstanceOfClass(plainObj, MyClass)); // false
+ *
+ * @example Type narrowing with specific class
+ * import { isInstanceOfClass } from "@sillvva/utils";
+ *
+ * class User {
+ *   constructor(public name: string) {}
+ * }
+ *
+ * function processUser(data: unknown) {
+ *   if (isInstanceOfClass(data, User)) {
+ *     // TypeScript knows data is User here
+ *     console.log(data.name);
+ *   }
+ * }
+ *
+ * @example Checking for any class instance
+ * import { isInstanceOfClass } from "@sillvva/utils";
+ *
+ * class MyClass {}
+ * const instance = new MyClass();
+ * const plainObj = {};
+ * const primitive = "string";
+ *
+ * console.log(isInstanceOfClass(instance)); // true (instance of MyClass)
+ * console.log(isInstanceOfClass(plainObj)); // false (plain object)
+ * console.log(isInstanceOfClass(primitive)); // false (primitive)
+ * console.log(isInstanceOfClass(null)); // false (null)
+ *
+ * @example Filtering class instances from mixed arrays
+ * import { isInstanceOfClass } from "@sillvva/utils";
+ *
+ * class Animal {
+ *   constructor(public name: string) {}
+ * }
+ *
+ * const items = [
+ *   new Animal("Dog"),
+ *   { name: "Cat" }, // plain object
+ *   "Bird", // primitive
+ *   new Animal("Fish")
+ * ];
+ *
+ * const animals = items.filter((item): item is Animal => isInstanceOfClass(item, Animal));
+ * console.log(animals); // [Animal { name: "Dog" }, Animal { name: "Fish" }]
+ */
+export function isInstanceOfClass<T extends object>(obj: unknown, ClassConstructor?: new (...args: any[]) => T): obj is T {
+	// Exclude null and non-objects
+	if (obj === null || typeof obj !== "object") return false;
+
+	// If a specific class constructor is provided, check if obj is an instance of that class
+	if (ClassConstructor) {
+		return obj instanceof ClassConstructor;
+	}
+
+	// Otherwise, check if it's an instance of any class (exclude plain objects and arrays)
+	const prototype = Object.getPrototypeOf(obj);
+	if (prototype === null) return false;
+	return prototype !== Object.prototype && prototype !== Array.prototype;
+}