is-what 4.1.11 → 4.1.12

package/README.md

@@ -180,6 +180,18 @@ getType('') // returns 'String'
 isType('', String) // returns true
 ```
 
+If you just want to make sure your object _inherits_ from a particular class or
+`toStringTag` value, you can use `isInstanceOf()` like this:
+
+```js
+import { isInstanceOf } from 'is-what'
+
+isInstanceOf(new XMLHttpRequest(), "EventTarget")
+// returns true
+isInstanceOf(globalThis, ReadableStream)
+// returns false
+```
+
 ## TypeScript
 
 is-what makes TypeScript know the type during if statements. This means that a check returns the type of the payload for TypeScript users.

package/dist/cjs/index.cjs

@@ -13,7 +13,7 @@ function isPlainObject(payload) {
   if (getType(payload) !== "Object")
     return false;
   const prototype = Object.getPrototypeOf(payload);
-  return prototype.constructor === Object && prototype === Object.prototype;
+  return !!prototype && prototype.constructor === Object && prototype === Object.prototype;
 }
 function isObject(payload) {
   return isPlainObject(payload);
@@ -116,6 +116,23 @@ function isType(payload, type) {
   const name = type.name;
   return getType(payload) === name || Boolean(payload && payload.constructor === type);
 }
+function isInstanceOf(value, classOrClassName) {
+  if (typeof classOrClassName === "function") {
+    for (let p = value; p; p = Object.getPrototypeOf(p)) {
+      if (isType(p, classOrClassName)) {
+        return true;
+      }
+    }
+    return false;
+  } else {
+    for (let p = value; p; p = Object.getPrototypeOf(p)) {
+      if (getType(p) === classOrClassName) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
 
 exports.getType = getType;
 exports.isAnyObject = isAnyObject;
@@ -132,6 +149,7 @@ exports.isFullArray = isFullArray;
 exports.isFullObject = isFullObject;
 exports.isFullString = isFullString;
 exports.isFunction = isFunction;
+exports.isInstanceOf = isInstanceOf;
 exports.isMap = isMap;
 exports.isNaNValue = isNaNValue;
 exports.isNegativeNumber = isNegativeNumber;

package/dist/cjs/index.d.cts

@@ -248,9 +248,53 @@ declare function isPrimitive(payload: any): payload is boolean | null | undefine
  * @returns {(payload is null | undefined)}
  */
 declare const isNullOrUndefined: TypeGuard<any, null | undefined>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>): TypeGuard<A, B | C>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>): TypeGuard<A, B | C | D>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>, d: TypeGuard<A, E>): TypeGuard<A, B | C | D | E>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A, F extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>, d: TypeGuard<A, E>, e: TypeGuard<A, F>): TypeGuard<A, B | C | D | E | F>;
 /**
  * Does a generic check to check that the given payload is of a given type.
@@ -264,5 +308,27 @@ declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A,
  * @returns {payload is T}
  */
 declare function isType<T extends AnyFunction | AnyClass>(payload: any, type: T): payload is T;
+type GlobalClassName = {
+    [K in keyof typeof globalThis]: (typeof globalThis)[K] extends AnyClass ? K : never;
+}[keyof typeof globalThis];
+/**
+ * Checks if a value is an instance of a class or a class name. Useful when you
+ * want to check if a value is an instance of a class that may not be defined in
+ * the current scope. For example, if you want to check if a value is an
+ * `OffscreenCanvas` instance, you might not want to do the song and dance of
+ * using `typeof OffscreenCanvas !== 'undefined'` and then shimming
+ * `OffscreenCanvas` if the types aren't around.
+ *
+ * @example
+ * if (isInstanceOf(value, 'OffscreenCanvas')) {
+ *  // value is an OffscreenCanvas
+ * }
+ *
+ * @param value The value to recursively check
+ * @param class_ A string or class that the value should be an instance of
+ */
+declare function isInstanceOf<T extends AnyClass>(value: unknown, class_: T): value is T;
+declare function isInstanceOf<K extends GlobalClassName>(value: unknown, className: K): value is (typeof globalThis)[K];
+declare function isInstanceOf(value: unknown, className: string): value is object;
 
-export { AnyAsyncFunction, AnyClass, AnyFunction, PlainObject, getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };
+export { AnyAsyncFunction, AnyClass, AnyFunction, PlainObject, getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isInstanceOf, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };

package/dist/index.d.ts

@@ -248,9 +248,53 @@ declare function isPrimitive(payload: any): payload is boolean | null | undefine
  * @returns {(payload is null | undefined)}
  */
 declare const isNullOrUndefined: TypeGuard<any, null | undefined>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>): TypeGuard<A, B | C>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>): TypeGuard<A, B | C | D>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>, d: TypeGuard<A, E>): TypeGuard<A, B | C | D | E>;
+/**
+ * A factory function that creates a function to check if the payload is one of the given types.
+ * @example
+ * import { isOneOf, isNull, isUndefined } from 'is-what'
+ *
+ * const isNullOrUndefined = isOneOf(isNull, isUndefined)
+ *
+ * isNullOrUndefined(null) // true
+ * isNullOrUndefined(undefined) // true
+ * isNullOrUndefined(123) // false
+ */
 declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A, F extends A>(a: TypeGuard<A, B>, b: TypeGuard<A, C>, c: TypeGuard<A, D>, d: TypeGuard<A, E>, e: TypeGuard<A, F>): TypeGuard<A, B | C | D | E | F>;
 /**
  * Does a generic check to check that the given payload is of a given type.
@@ -264,5 +308,27 @@ declare function isOneOf<A, B extends A, C extends A, D extends A, E extends A,
  * @returns {payload is T}
  */
 declare function isType<T extends AnyFunction | AnyClass>(payload: any, type: T): payload is T;
+type GlobalClassName = {
+    [K in keyof typeof globalThis]: (typeof globalThis)[K] extends AnyClass ? K : never;
+}[keyof typeof globalThis];
+/**
+ * Checks if a value is an instance of a class or a class name. Useful when you
+ * want to check if a value is an instance of a class that may not be defined in
+ * the current scope. For example, if you want to check if a value is an
+ * `OffscreenCanvas` instance, you might not want to do the song and dance of
+ * using `typeof OffscreenCanvas !== 'undefined'` and then shimming
+ * `OffscreenCanvas` if the types aren't around.
+ *
+ * @example
+ * if (isInstanceOf(value, 'OffscreenCanvas')) {
+ *  // value is an OffscreenCanvas
+ * }
+ *
+ * @param value The value to recursively check
+ * @param class_ A string or class that the value should be an instance of
+ */
+declare function isInstanceOf<T extends AnyClass>(value: unknown, class_: T): value is T;
+declare function isInstanceOf<K extends GlobalClassName>(value: unknown, className: K): value is (typeof globalThis)[K];
+declare function isInstanceOf(value: unknown, className: string): value is object;
 
-export { AnyAsyncFunction, AnyClass, AnyFunction, PlainObject, getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };
+export { AnyAsyncFunction, AnyClass, AnyFunction, PlainObject, getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isInstanceOf, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };

package/dist/index.js

@@ -11,7 +11,7 @@ function isPlainObject(payload) {
   if (getType(payload) !== "Object")
     return false;
   const prototype = Object.getPrototypeOf(payload);
-  return prototype.constructor === Object && prototype === Object.prototype;
+  return !!prototype && prototype.constructor === Object && prototype === Object.prototype;
 }
 function isObject(payload) {
   return isPlainObject(payload);
@@ -114,5 +114,22 @@ function isType(payload, type) {
   const name = type.name;
   return getType(payload) === name || Boolean(payload && payload.constructor === type);
 }
+function isInstanceOf(value, classOrClassName) {
+  if (typeof classOrClassName === "function") {
+    for (let p = value; p; p = Object.getPrototypeOf(p)) {
+      if (isType(p, classOrClassName)) {
+        return true;
+      }
+    }
+    return false;
+  } else {
+    for (let p = value; p; p = Object.getPrototypeOf(p)) {
+      if (getType(p) === classOrClassName) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
 
-export { getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };
+export { getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isInstanceOf, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "is-what",
-  "version": "4.1.11",
+  "version": "4.1.12",
   "description": "JS type check (TypeScript supported) functions like `isPlainObject() isArray()` etc. A simple & small integration.",
   "type": "module",
   "sideEffects": false,
@@ -29,6 +29,7 @@
     "test": "vitest run",
     "lint": "tsc --noEmit && eslint ./src --ext .ts",
     "build": "rollup -c ./rollup.config.js",
+    "build:docs": "typedoc",
     "release": "npm run lint && del dist && npm run build && np"
   },
   "repository": {
@@ -76,7 +77,8 @@
     "rollup-plugin-dts": "^5.3.0",
     "rollup-plugin-esbuild": "^5.0.0",
     "typescript": "^5.0.4",
-    "vitest": "^0.31.1"
+    "vitest": "^0.31.1",
+    "typedoc": "^0.24.7"
   },
   "ava": {
     "extensions": {