is

Type check values

For example, is.string('🦄') //=> true

<img src="header.gif" width="182" align="right">

Highlights

• Written in TypeScript
• Extensive use of type guards
• Supports type assertions
• Aware of generic type parameters (use with caution)
• Actively maintained
• 

Install

npm install @sindresorhus/is

Usage

import is from '@sindresorhus/is';

is('🦄');
//=> 'string'

is(new Map());
//=> 'Map'

is.number(6);
//=> true

Assertions perform the same type checks, but throw an error if the type does not match.

import {assert} from '@sindresorhus/is';

assert.string(2);
//=> Error: Expected value which is `string`, received value of type `number`.

Assertions (except assertAll and assertAny) also support an optional custom error message.

import {assert} from '@sindresorhus/is';

assert.nonEmptyString(process.env.API_URL, 'The API_URL environment variable is required.');
//=> Error: The API_URL environment variable is required.

And with TypeScript:

import {assert} from '@sindresorhus/is';

assert.string(foo);
// `foo` is now typed as a `string`.

Named exports

Named exports allow tooling to perform tree-shaking, potentially reducing bundle size by including only code from the methods that are used.

Every method listed below is available as a named export. Each method is prefixed by either is or assert depending on usage.

For example:

import {assertNull, isUndefined} from '@sindresorhus/is';

API

is(value)

Returns the type of value.

Primitives are lowercase and object types are camelcase.

Example:

• 'undefined'
• 'null'
• 'string'
• 'symbol'
• 'Array'
• 'Function'
• 'Object'

This method is also exported as detect. You can import it like this:

import {detect} from '@sindresorhus/is';

Note: It will throw an error if you try to feed it object-wrapped primitives, as that's a bad practice. For example new String('foo').

is.{method}

All the below methods accept a value and return a boolean for whether the value is of the desired type.

Primitives

.undefined(value)

.null(value)

.string(value)

.number(value)

Note: is.number(NaN) returns false. This intentionally deviates from typeof behavior to increase user-friendliness of is type checks.

.boolean(value)

.symbol(value)

.bigint(value)

Built-in types

.array(value, assertion?)

Returns true if value is an array and all of its items match the assertion (if provided).

is.array(value); // Validate `value` is an array.
is.array(value, is.number); // Validate `value` is an array and all of its items are numbers.

.function(value)

.buffer(value)

[!NOTE] Prefer using Uint8Array instead of Buffer.

.blob(value)

.object(value)

Keep in mind that functions are objects too.

.numericString(value)

Returns true for a string that represents a number satisfying is.number, for example, '42' and '-8.3'.

Note: 'NaN' returns false, but 'Infinity' and '-Infinity' return true.

.regExp(value)

.date(value)

.error(value)

.nativePromise(value)

.promise(value)

Returns true for any object with a .then() and .catch() method. Prefer this one over .nativePromise() as you usually want to allow userland promise implementations too.

.generator(value)

Returns true for any object that implements its own .next() and .throw() methods and has a function definition for Symbol.iterator.

.generatorFunction(value)

.asyncFunction(value)

Returns true for any async function that can be called with the await operator.

is.asyncFunction(async () => {});
//=> true

is.asyncFunction(() => {});
//=> false

.asyncGenerator(value)

is.asyncGenerator(
	(async function * () {
		yield 4;
	})()
);
//=> true

is.asyncGenerator(
	(function * () {
		yield 4;
	})()
);
//=> false

.asyncGeneratorFunction(value)

is.asyncGeneratorFunction(async function * () {
	yield 4;
});
//=> true

is.asyncGeneratorFunction(function * () {
	yield 4;
});
//=> false

.boundFunction(value)

Returns true for any bound function.

is.boundFunction(() => {});
//=> true

is.boundFunction(function () {}.bind(null));
//=> true

is.boundFunction(function () {});
//=> false

.map(value)

.set(value)

.weakMap(value)

.weakSet(value)

.weakRef(value)

Typed arrays

.int8Array(value)

.uint8Array(value)

.uint8ClampedArray(value)

.int16Array(value)

.uint16Array(value)

.int32Array(value)

.uint32Array(value)

.float32Array(value)

.float64Array(value)

.bigInt64Array(value)

.bigUint64Array(value)

Structured data

.arrayBuffer(value)

.sharedArrayBuffer(value)

.dataView(value)

.enumCase(value, enum)

TypeScript-only. Returns true if value is a member of enum.

enum Direction {
	Ascending = 'ascending',
	Descending = 'descending'
}

is.enumCase('ascending', Direction);
//=> true

is.enumCase('other', Direction);
//=> false

Emptiness

.emptyString(value)

Returns true if the value is a string and the .length is 0.

.emptyStringOrWhitespace(value)

Returns true if is.emptyString(value) or if it's a string that is all whitespace.

.nonEmptyString(value)

Returns true if the value is a string and the .length is more than 0.

.nonEmptyStringAndNotWhitespace(value)

Returns true if the value is a string that is not empty and not whitespace.

const values = ['property1', '', null, 'property2', '    ', undefined];

values.filter(is.nonEmptyStringAndNotWhitespace);
//=> ['property1', 'property2']

.emptyArray(value)

Returns true if the value is an Array and the .length is 0.

.nonEmptyArray(value)

Returns true if the value is an Array and the .length is more than 0.

.emptyObject(value)

Returns true if the value is an Object and Object.keys(value).length is 0.

Please note that Object.keys returns only own enumerable properties. Hence something like this can happen:

const object1 = {};

Object.defineProperty(object1, 'property1', {
	value: 42,
	writable: true,
	enumerable: false,
	configurable: true
});

is.emptyObject(object1);
//=> true

.nonEmptyObject(value)

Returns true if the value is an Object and Object.keys(value).length is more than 0.

.emptySet(value)

Returns true if the value is a Set and the .size is 0.

.nonEmptySet(Value)

Returns true if the value is a Set and the .size is more than 0.

.emptyMap(value)

Returns true if the value is a Map and the .size is 0.

.nonEmptyMap(value)

Returns true if the value is a Map and the .size is more than 0.

Miscellaneous

.directInstanceOf(value, class)

Returns true if value is a direct instance of class.

is.directInstanceOf(new Error(), Error);
//=> true

class UnicornError extends Error {}

is.directInstanceOf(new UnicornError(), Error);
//=> false

.urlInstance(value)

Returns true if value is an instance of the URL class.

const url = new URL('https://example.com');

is.urlInstance(url);
//=> true

.urlString(value)

Returns true if value is a URL string.

Note: this only does basic checking using the URL class constructor.

const url = 'https://example.com';

is.urlString(url);
//=> true

is.urlString(new URL(url));
//=> false

.truthy(value)

Returns true for all values that evaluate to true in a boolean context:

is.truthy('🦄');
//=> true

is.truthy(undefined);
//=> false

.falsy(value)

Returns true if value is one of: false, 0, '', null, undefined, NaN.

.nan(value)

.nullOrUndefined(value)

.primitive(value)

JavaScript primitives are as follows:

• null
• undefined
• string
• number
• boolean
• symbol
• bigint

.integer(value)

.safeInteger(value)

Returns true if value is a safe integer.

.plainObject(value)

An object is plain if it's created by either {}, new Object(), or Object.create(null).

.iterable(value)

.asyncIterable(value)

.class(value)

Returns true if the value is a class constructor.

.typedArray(value)

.arrayLike(value)

A value is array-like if it is not a function and has a value.length that is a safe integer greater than or equal to 0.

is.arrayLike(document.forms);
//=> true

function foo() {
	is.arrayLike(arguments);
	//=> true
}
foo();

.tupleLike(value, guards)

A value is tuple-like if it matches the provided guards array both in .length and in types.

is.tupleLike([1], [is.number]);
//=> true

function foo() {
	const tuple = [1, '2', true];
	if (is.tupleLike(tuple, [is.number, is.string, is.boolean])) {
		tuple // [number, string, boolean]
	}
}

foo();

.positiveNumber(value)

Check if value is a number and is more than 0.

.negativeNumber(value)

Check if value is a number and is less than 0.

.inRange(value, range)

Check if value (number) is in the given range. The range is an array of two values, lower bound and upper bound, in no specific order.

i