is What? 🙉

Very simple & small JS type check functions. It's fully TypeScript supported!

npm i is-what

Or for deno available at: "deno.land/x/is_what"

Also check out is-where 🙈

Motivation

I built is-what because the existing solutions were all too complex or too poorly built.

I was looking for:

• A simple way to check any kind of type (including non-primitives)
• Be able to check if an object is a plain object {} or a special object (like a class instance) ‼️
• Let TypeScript automatically know what type a value is when checking

And that's exactly what is-what is! (what a great wordplay 😃)

Usage

is-what is really easy to use, and most functions work just like you'd expect.

1// import functions you want to use like so:
2import { isString, isDate, isPlainObject } from 'is-what'

1. First I'll go over the simple functions available. Only isNumber and isDate have special treatment.
2. After that I'll talk about working with Objects (plain objects vs class instances etc.).
3. Lastly I'll talk about TypeScript implementation

Simple type check functions

1// basics
2isBoolean(true) // true
3isBoolean(false) // true
4isUndefined(undefined) // true
5isNull(null) // true
6
7// strings
8isString('') // true
9isEmptyString('') // true
10isFullString('') // false
11isHexDecimal('60adf084f0fbdcab42de841e') // true
12isHexDecimal('60adf084f0fbdcab42de841e', 24) // check specific length of 24 (eg. MongoDB ObjectId)
13
14// numbers
15isNumber(0) // true
16isNumber('0') // false
17isNumber(NaN) // false *
18isPositiveNumber(1) // true
19isNegativeNumber(-1) // true
20// * see below for special NaN use cases!
21
22// arrays
23isArray([]) // true
24isEmptyArray([]) // true
25isFullArray([1]) // true
26
27// objects
28isPlainObject({}) // true *
29isEmptyObject({}) // true
30isFullObject({ a: 1 }) // true
31// * see below for special object (& class instance) use cases!
32
33// functions
34isFunction(function () {}) // true
35isFunction(() => {}) // true
36
37// dates
38isDate(new Date()) // true
39isDate(new Date('invalid date')) // false
40
41// maps & sets
42isMap(new Map()) // true
43isSet(new Set()) // true
44isWeakMap(new WeakMap()) // true
45isWeakSet(new WeakSet()) // true
46
47// others
48isRegExp(/\s/gi) // true
49isSymbol(Symbol()) // true
50isBlob(new Blob()) // true
51isFile(new File([''], '', { type: 'text/html' })) // true
52isError(new Error('')) // true
53isPromise(new Promise((resolve) => {})) // true
54
55// primitives
56isPrimitive('') // true
57//     true for any of: boolean, null, undefined, number, string, symbol
58
59// iterables
60isIterable([1, 2, 3]) // true
61isIterable('hello') // true
62isIterable(new Map()) // true
63isIterable(new Set()) // true
64isIterable(function* generator() {
65  yield 1
66}) // true

Let's talk about NaN

isNaN is a built-in JS Function but it really makes no sense:

1// 1)
2typeof NaN === 'number' // true
3// 🤔 ("not a number" is a "number"...)
4
5// 2)
6isNaN('1') // false
7// 🤔 the string '1' is not-"not a number"... so it's a number??
8
9// 3)
10isNaN('one') // true
11// 🤔 'one' is NaN but `NaN === 'one'` is false...

With is-what the way we treat NaN makes a little bit more sense:

1import { isNumber, isNaNValue } from 'is-what'
2
3// 1)
4isNumber(NaN) // false!
5// let's not treat NaN as a number
6
7// 2)
8isNaNValue('1') // false
9// if it's not NaN, it's not NaN!!
10
11// 3)
12isNaNValue('one') // false
13// if it's not NaN, it's not NaN!!
14
15isNaNValue(NaN) // true

isPlainObject vs isAnyObject

Checking for a JavaScript object can be really difficult. In JavaScript you can create classes that will behave just like JavaScript objects but might have completely different prototypes. With is-what I went for this classification:

• isPlainObject will only return true on plain JavaScript objects and not on classes or others
• isAnyObject will be more loose and return true on regular objects, classes, etc.

1// define a plain object
2const plainObject = { hello: 'I am a good old object.' }
3
4// define a special object
5class SpecialObject {
6  constructor(somethingSpecial) {
7    this.speciality = somethingSpecial
8  }
9}
10const specialObject = new SpecialObject('I am a special object! I am a class instance!!!')
11
12// check the plain object
13isPlainObject(plainObject) // returns true
14isAnyObject(plainObject) // returns true
15getType(plainObject) // returns 'Object'
16
17// check the special object
18isPlainObject(specialObject) // returns false !!!!!!!!!
19isAnyObject(specialObject) // returns true
20getType(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:

1import { getType, isType } from 'is-what'
2
3getType('') // returns 'String'
4// pass a Type as second param:
5isType('', 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:

1import { isInstanceOf } from 'is-what'
2
3isInstanceOf(new XMLHttpRequest(), 'EventTarget')
4// returns true
5isInstanceOf(globalThis, ReadableStream)
6// 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.

1function isNumber(payload: unknown): payload is number {
2  // return boolean
3}
4// As you can see above, all functions return a boolean for JavaScript, but pass the payload type to TypeScript.
5
6// usage example:
7function fn(payload: string | number): number {
8  if (isNumber(payload)) {
9    // ↑ TypeScript already knows payload is a number here!
10    return payload
11  }
12  return 0
13}

isPlainObject and isAnyObject with TypeScript will declare the payload to be an object type with any props:

1function isPlainObject(payload: unknown): payload is { [key: string]: unknown }
2function isAnyObject(payload: unknown): payload is { [key: string]: unknown }
3// The reason to return `{[key: string]: unknown}` is to be able to do
4if (isPlainObject(payload) && payload.id) return payload.id
5// if isPlainObject() would return `payload is object` then it would give an error at `payload.id`

isObjectLike

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>:

1import { isObjectLike } from 'is-what'
2
3const payload = { name: 'Mesqueeb' } // current type: `{ name: string }`
4
5// Without casting:
6if (isAnyObject(payload)) {
7  // in here `payload` is casted to: `Record<string | number | symbol, unknown>`
8  // WE LOOSE THE TYPE!
9}
10
11// With casting:
12// you can pass a specific type for TS that will be casted when the function returns
13if (isObjectLike<{ name: string }>(payload)) {
14  // in here `payload` is casted to: `{ name: string }`
15}

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:

1function isObjectLike<T extends object>(payload: unknown): payload is T {
2  return isAnyObject(payload)
3}

Meet the family (more tiny utils with TS support)

• is-what 🙉
• is-where 🙈
• merge-anything 🥡
• check-anything 👁
• remove-anything ✂️
• getorset-anything 🐊
• map-anything 🗺
• filter-anything ⚔️
• copy-anything 🎭
• case-anything 🐫
• flatten-anything 🏏
• nestify-anything 🧅

Source code

It's litterally just these functions:

1function getType(payload) {
2  return Object.prototype.toString.call(payload).slice(8, -1)
3}
4function isUndefined(payload) {
5  return getType(payload) === 'Undefined'
6}
7function isString(payload) {
8  return getType(payload) === 'String'
9}
10function isAnyObject(payload) {
11  return getType(payload) === 'Object'
12}
13// etc...

See the full source code here.