is-what 4.0.0 → 4.1.3

package/README.md

@@ -1,5 +1,8 @@
 # is What? 🙉
 
+<a href="https://www.npmjs.com/package/is-what"><img src="https://img.shields.io/npm/v/is-what.svg" alt="Total Downloads"></a>
+<a href="https://www.npmjs.com/package/is-what"><img src="https://img.shields.io/npm/dw/is-what.svg" alt="Latest Stable Version"></a>
+
 Very simple & small JS type check functions. It's fully TypeScript supported!
 
 ```
@@ -36,6 +39,12 @@ import { isString, isDate, isPlainObject } from 'is-what'
 ### Simple type check functions
 
 ```js
+// basics
+isBoolean(true) // true
+isBoolean(false) // true
+isUndefined(undefined) // true
+isNull(null) // true
+
 // strings
 isString('') // true
 isEmptyString('') // true
@@ -43,38 +52,86 @@ isFullString('') // false
 
 // numbers
 isNumber(0) // true
-isNumber(NaN) // false
+isNumber('0') // false
+isNumber(NaN) // false *
+isPositiveNumber(1) // true
+isNegativeNumber(-1) // true
+// * see below for special NaN use cases!
+
+// arrays
+isArray([]) // true
+isEmptyArray([]) // true
+isFullArray([1]) // true
+
+// objects
+isPlainObject({}) // true *
+isEmptyObject({}) // true
+isFullObject({ a: 1 }) // true
+// * see below for special object (& class instance) use cases!
+
+// functions
+isFunction(function () {}) // true
+isFunction(() => {}) // true
 
 // dates
 isDate(new Date()) // true
 isDate(new Date('invalid date')) // false
 
+// maps & sets
+isMap(new Map()) // true
+isSet(new Set()) // true
+isWeakMap(new WeakMap()) // true
+isWeakSet(new WeakSet()) // true
+
 // others
-isBoolean(false) // true
-isFunction(function () {}) // true
-isArray([]) // true
-isUndefined(undefined) // true
-isNull(null) // true
 isRegExp(/\s/gi) // true
 isSymbol(Symbol()) // true
 isBlob(new Blob()) // true
 isFile(new File([''], '', { type: 'text/html' })) // true
+isError(new Error('')) // true
+isPromise(new Promise((resolve) => {})) // true
 
 // primitives
 isPrimitive('') // true
 // true for any of: boolean, null, undefined, number, string, symbol
 ```
 
-### Getting and checking for specific types
+### Let's talk about NaN
 
-You can check for specific types with `getType` and `isType`:
+`isNaN` is a built-in JS Function but it really makes no sense:
 
 ```js
-import { getType, isType } from 'is-what'
+// 1)
+typeof NaN === 'number' // true
+// 🤔 ("not a number" is a "number"...)
 
-getType('') // returns 'String'
-// pass a Type as second param:
-isType('', String) // returns true
+// 2)
+isNaN('1') // false
+// 🤔 the string '1' is not-"not a number"... so it's a number??
+
+// 3)
+isNaN('one') // true
+// 🤔 'one' is NaN but `NaN === 'one'` is false...
+```
+
+With is-what the way we treat NaN makes a little bit more sense:
+
+```js
+import { isNumber, isNaNValue } from 'is-what'
+
+// 1)
+isNumber(NaN) // false!
+// let's not treat NaN as a number
+
+// 2)
+isNaNValue('1') // false
+// if it's not NaN, it's not NaN!!
+
+// 3)
+isNaNValue('one') // false
+// if it's not NaN, it's not NaN!!
+
+isNaNValue(NaN) // true
 ```
 
 ### isPlainObject vs isAnyObject
@@ -109,6 +166,18 @@ getType(specialObject) // returns 'Object'
 
 > Please note that `isPlainObject` will only return `true` for normal plain JavaScript objects.
 
+### Getting and checking for specific types
+
+You can check for specific types with `getType` and `isType`:
+
+```js
+import { getType, isType } from 'is-what'
+
+getType('') // returns 'String'
+// pass a Type as second param:
+isType('', String) // returns true
+```
+
 ## 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.
@@ -141,16 +210,30 @@ if (isPlainObject(payload) && payload.id) return payload.id
 
 ### isObjectLike
 
-If you want more control over which kind of objects are allowed you can use `isObjectLike<T>`:
+If you want more control over what kind of interface/type is casted when checking for objects.
+
+To cast to a specific type while checking for `isAnyObject`, can use `isObjectLike<T>`:
 
 ```ts
 import { isObjectLike } from 'is-what'
-// usage examples:
-isObjectLike<{ specificKey: string }>(payload)
-isObjectLike<object>(payload)
-// you can pass a specific type for TS to check on.
+
+const payload = { name: 'Mesqueeb' } // current type: `{ name: string }`
+
+// Without casting:
+if (isAnyObject(payload)) {
+  // in here `payload` is casted to: `Record<string | number | symbol, any>`
+  // WE LOOSE THE TYPE!
+}
+
+// With casting:
+// you can pass a specific type for TS that will be casted when the function returns
+if (isObjectLike<{ name: string }>(payload)) {
+  // in here `payload` is casted to: `{ name: string }`
+}
 ```
 
+Please note: this library will not actually check the shape of the object, you need to do that yourself.
+
 `isObjectLike<T>` works like this under the hood:
 
 ```ts

package/dist/index.cjs

@@ -0,0 +1,382 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Returns the object type of the given payload
+ *
+ * @param {*} payload
+ * @returns {string}
+ */
+function getType(payload) {
+    return Object.prototype.toString.call(payload).slice(8, -1);
+}
+/**
+ * Returns whether the payload is undefined
+ *
+ * @param {*} payload
+ * @returns {payload is undefined}
+ */
+function isUndefined(payload) {
+    return getType(payload) === 'Undefined';
+}
+/**
+ * Returns whether the payload is null
+ *
+ * @param {*} payload
+ * @returns {payload is null}
+ */
+function isNull(payload) {
+    return getType(payload) === 'Null';
+}
+/**
+ * Returns whether the payload is a plain JavaScript object (excluding special classes or objects with other prototypes)
+ *
+ * @param {*} payload
+ * @returns {payload is PlainObject}
+ */
+function isPlainObject(payload) {
+    if (getType(payload) !== 'Object')
+        return false;
+    return payload.constructor === Object && Object.getPrototypeOf(payload) === Object.prototype;
+}
+/**
+ * Returns whether the payload is a plain JavaScript object (excluding special classes or objects with other prototypes)
+ *
+ * @param {*} payload
+ * @returns {payload is PlainObject}
+ */
+function isObject(payload) {
+    return isPlainObject(payload);
+}
+/**
+ * Returns whether the payload is a an empty object (excluding special classes or objects with other prototypes)
+ *
+ * @param {*} payload
+ * @returns {payload is { [K in any]: never }}
+ */
+function isEmptyObject(payload) {
+    return isPlainObject(payload) && Object.keys(payload).length === 0;
+}
+/**
+ * Returns whether the payload is a an empty object (excluding special classes or objects with other prototypes)
+ *
+ * @param {*} payload
+ * @returns {payload is PlainObject}
+ */
+function isFullObject(payload) {
+    return isPlainObject(payload) && Object.keys(payload).length > 0;
+}
+/**
+ * Returns whether the payload is an any kind of object (including special classes or objects with different prototypes)
+ *
+ * @param {*} payload
+ * @returns {payload is PlainObject}
+ */
+function isAnyObject(payload) {
+    return getType(payload) === 'Object';
+}
+/**
+ * Returns whether the payload is an object like a type passed in < >
+ *
+ * Usage: isObjectLike<{id: any}>(payload) // will make sure it's an object and has an `id` prop.
+ *
+ * @template T this must be passed in < >
+ * @param {*} payload
+ * @returns {payload is T}
+ */
+function isObjectLike(payload) {
+    return isAnyObject(payload);
+}
+/**
+ * Returns whether the payload is a function (regular or async)
+ *
+ * @param {*} payload
+ * @returns {payload is AnyFunction}
+ */
+function isFunction(payload) {
+    return typeof payload === 'function';
+}
+/**
+ * Returns whether the payload is an array
+ *
+ * @param {any} payload
+ * @returns {payload is any[]}
+ */
+function isArray(payload) {
+    return getType(payload) === 'Array';
+}
+/**
+ * Returns whether the payload is a an array with at least 1 item
+ *
+ * @param {*} payload
+ * @returns {payload is any[]}
+ */
+function isFullArray(payload) {
+    return isArray(payload) && payload.length > 0;
+}
+/**
+ * Returns whether the payload is a an empty array
+ *
+ * @param {*} payload
+ * @returns {payload is []}
+ */
+function isEmptyArray(payload) {
+    return isArray(payload) && payload.length === 0;
+}
+/**
+ * Returns whether the payload is a string
+ *
+ * @param {*} payload
+ * @returns {payload is string}
+ */
+function isString(payload) {
+    return getType(payload) === 'String';
+}
+/**
+ * Returns whether the payload is a string, BUT returns false for ''
+ *
+ * @param {*} payload
+ * @returns {payload is string}
+ */
+function isFullString(payload) {
+    return isString(payload) && payload !== '';
+}
+/**
+ * Returns whether the payload is ''
+ *
+ * @param {*} payload
+ * @returns {payload is string}
+ */
+function isEmptyString(payload) {
+    return payload === '';
+}
+/**
+ * Returns whether the payload is a number (but not NaN)
+ *
+ * This will return `false` for `NaN`!!
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+function isNumber(payload) {
+    return getType(payload) === 'Number' && !isNaN(payload);
+}
+/**
+ * Returns whether the payload is a positive number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+function isPositiveNumber(payload) {
+    return isNumber(payload) && payload > 0;
+}
+/**
+ * Returns whether the payload is a negative number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+function isNegativeNumber(payload) {
+    return isNumber(payload) && payload < 0;
+}
+/**
+ * Returns whether the payload is a boolean
+ *
+ * @param {*} payload
+ * @returns {payload is boolean}
+ */
+function isBoolean(payload) {
+    return getType(payload) === 'Boolean';
+}
+/**
+ * Returns whether the payload is a regular expression (RegExp)
+ *
+ * @param {*} payload
+ * @returns {payload is RegExp}
+ */
+function isRegExp(payload) {
+    return getType(payload) === 'RegExp';
+}
+/**
+ * Returns whether the payload is a Map
+ *
+ * @param {*} payload
+ * @returns {payload is Map<any, any>}
+ */
+function isMap(payload) {
+    return getType(payload) === 'Map';
+}
+/**
+ * Returns whether the payload is a WeakMap
+ *
+ * @param {*} payload
+ * @returns {payload is WeakMap<any, any>}
+ */
+function isWeakMap(payload) {
+    return getType(payload) === 'WeakMap';
+}
+/**
+ * Returns whether the payload is a Set
+ *
+ * @param {*} payload
+ * @returns {payload is Set<any>}
+ */
+function isSet(payload) {
+    return getType(payload) === 'Set';
+}
+/**
+ * Returns whether the payload is a WeakSet
+ *
+ * @param {*} payload
+ * @returns {payload is WeakSet<any>}
+ */
+function isWeakSet(payload) {
+    return getType(payload) === 'WeakSet';
+}
+/**
+ * Returns whether the payload is a Symbol
+ *
+ * @param {*} payload
+ * @returns {payload is symbol}
+ */
+function isSymbol(payload) {
+    return getType(payload) === 'Symbol';
+}
+/**
+ * Returns whether the payload is a Date, and that the date is valid
+ *
+ * @param {*} payload
+ * @returns {payload is Date}
+ */
+function isDate(payload) {
+    return getType(payload) === 'Date' && !isNaN(payload);
+}
+/**
+ * Returns whether the payload is a Blob
+ *
+ * @param {*} payload
+ * @returns {payload is Blob}
+ */
+function isBlob(payload) {
+    return getType(payload) === 'Blob';
+}
+/**
+ * Returns whether the payload is a File
+ *
+ * @param {*} payload
+ * @returns {payload is File}
+ */
+function isFile(payload) {
+    return getType(payload) === 'File';
+}
+/**
+ * Returns whether the payload is a Promise
+ *
+ * @param {*} payload
+ * @returns {payload is Promise<any>}
+ */
+function isPromise(payload) {
+    return getType(payload) === 'Promise';
+}
+/**
+ * Returns whether the payload is an Error
+ *
+ * @param {*} payload
+ * @returns {payload is Error}
+ */
+function isError(payload) {
+    return getType(payload) === 'Error';
+}
+/**
+ * Returns whether the payload is literally the value `NaN` (it's `NaN` and also a `number`)
+ *
+ * @param {*} payload
+ * @returns {payload is typeof NaN}
+ */
+function isNaNValue(payload) {
+    return getType(payload) === 'Number' && isNaN(payload);
+}
+/**
+ * Returns whether the payload is a primitive type (eg. Boolean | Null | Undefined | Number | String | Symbol)
+ *
+ * @param {*} payload
+ * @returns {(payload is boolean | null | undefined | number | string | symbol)}
+ */
+function isPrimitive(payload) {
+    return (isBoolean(payload) ||
+        isNull(payload) ||
+        isUndefined(payload) ||
+        isNumber(payload) ||
+        isString(payload) ||
+        isSymbol(payload));
+}
+/**
+ * Returns true whether the payload is null or undefined
+ *
+ * @param {*} payload
+ * @returns {(payload is null | undefined)}
+ */
+const isNullOrUndefined = isOneOf(isNull, isUndefined);
+function isOneOf(a, b, c, d, e) {
+    return (value) => a(value) || b(value) || (!!c && c(value)) || (!!d && d(value)) || (!!e && e(value));
+}
+/**
+ * Does a generic check to check that the given payload is of a given type.
+ * In cases like Number, it will return true for NaN as NaN is a Number (thanks javascript!);
+ * It will, however, differentiate between object and null
+ *
+ * @template T
+ * @param {*} payload
+ * @param {T} type
+ * @throws {TypeError} Will throw type error if type is an invalid type
+ * @returns {payload is T}
+ */
+function isType(payload, type) {
+    if (!(type instanceof Function)) {
+        throw new TypeError('Type must be a function');
+    }
+    if (!Object.prototype.hasOwnProperty.call(type, 'prototype')) {
+        throw new TypeError('Type is not a class');
+    }
+    // Classes usually have names (as functions usually have names)
+    const name = type.name;
+    return getType(payload) === name || Boolean(payload && payload.constructor === type);
+}
+
+exports.getType = getType;
+exports.isAnyObject = isAnyObject;
+exports.isArray = isArray;
+exports.isBlob = isBlob;
+exports.isBoolean = isBoolean;
+exports.isDate = isDate;
+exports.isEmptyArray = isEmptyArray;
+exports.isEmptyObject = isEmptyObject;
+exports.isEmptyString = isEmptyString;
+exports.isError = isError;
+exports.isFile = isFile;
+exports.isFullArray = isFullArray;
+exports.isFullObject = isFullObject;
+exports.isFullString = isFullString;
+exports.isFunction = isFunction;
+exports.isMap = isMap;
+exports.isNaNValue = isNaNValue;
+exports.isNegativeNumber = isNegativeNumber;
+exports.isNull = isNull;
+exports.isNullOrUndefined = isNullOrUndefined;
+exports.isNumber = isNumber;
+exports.isObject = isObject;
+exports.isObjectLike = isObjectLike;
+exports.isOneOf = isOneOf;
+exports.isPlainObject = isPlainObject;
+exports.isPositiveNumber = isPositiveNumber;
+exports.isPrimitive = isPrimitive;
+exports.isPromise = isPromise;
+exports.isRegExp = isRegExp;
+exports.isSet = isSet;
+exports.isString = isString;
+exports.isSymbol = isSymbol;
+exports.isType = isType;
+exports.isUndefined = isUndefined;
+exports.isWeakMap = isWeakMap;
+exports.isWeakSet = isWeakSet;

package/dist/{index.js → index.es.js}

@@ -158,6 +158,24 @@ function isEmptyString(payload) {
 function isNumber(payload) {
     return getType(payload) === 'Number' && !isNaN(payload);
 }
+/**
+ * Returns whether the payload is a positive number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+function isPositiveNumber(payload) {
+    return isNumber(payload) && payload > 0;
+}
+/**
+ * Returns whether the payload is a negative number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+function isNegativeNumber(payload) {
+    return isNumber(payload) && payload < 0;
+}
 /**
  * Returns whether the payload is a boolean
  *
@@ -322,4 +340,4 @@ function isType(payload, type) {
     return getType(payload) === name || Boolean(payload && payload.constructor === type);
 }
 
-export { getType, isAnyObject, isArray, isBlob, isBoolean, isDate, isEmptyArray, isEmptyObject, isEmptyString, isError, isFile, isFullArray, isFullObject, isFullString, isFunction, isMap, isNaNValue, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, 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, isMap, isNaNValue, isNegativeNumber, isNull, isNullOrUndefined, isNumber, isObject, isObjectLike, isOneOf, isPlainObject, isPositiveNumber, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isType, isUndefined, isWeakMap, isWeakSet };

package/{types → dist/types}/index.d.ts

@@ -129,6 +129,20 @@ export declare function isEmptyString(payload: any): payload is string;
  * @returns {payload is number}
  */
 export declare function isNumber(payload: any): payload is number;
+/**
+ * Returns whether the payload is a positive number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+export declare function isPositiveNumber(payload: any): payload is number;
+/**
+ * Returns whether the payload is a negative number (but not 0)
+ *
+ * @param {*} payload
+ * @returns {payload is number}
+ */
+export declare function isNegativeNumber(payload: any): payload is number;
 /**
  * Returns whether the payload is a boolean
  *