What is @sindresorhus/is?
The @sindresorhus/is npm package is a type-checking library that provides a variety of functions to assert the type of a given value. It can be used to check primitive types, built-in objects, and to perform environment checks.
What are @sindresorhus/is's main functionalities?
Primitive type checking
Check if a value is a string.
const is = require('@sindresorhus/is');
console.log(is.string('Hello World')); // true
Built-in object checking
Check if a value is a Promise.
const is = require('@sindresorhus/is');
console.log(is.promise(new Promise(resolve => resolve()))); // true
Environment checking
Check if the current environment is Node.js.
const is = require('@sindresorhus/is');
console.log(is.nodejs); // true or false depending on the environment
Array checking
Check if a value is an Array.
const is = require('@sindresorhus/is');
console.log(is.array([1, 2, 3])); // true
Object checking
Check if a value is an Object.
const is = require('@sindresorhus/is');
console.log(is.object({foo: 'bar'})); // true
Other packages similar to @sindresorhus/is
type-check
Type-check offers a more granular and customizable approach to type checking, allowing users to define custom type expressions and check values against them. It is more flexible but also more complex than @sindresorhus/is.
check-types
Check-types is a library that provides a set of predicates for type checking. It is similar to @sindresorhus/is but offers a slightly different API and additional functions for assertions and throwing errors.
is
Type check values: is.string('🦄') //=> true
Install
$ npm install @sindresorhus/is
Usage
const is = require('@sindresorhus/is');
is('🦄');
is(new Map());
is.number(6);
API
is(value)
Returns the type of value
.
Primitives are lowercase and object types are camelcase.
Example:
'undefined'
'null'
'string'
'symbol'
'Array'
'Function'
'Object'
Note: It will throw 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 returns a boolean for whether the value is of the desired type.
Primitives
.undefined(value)
.null(value)
.string(value)
.number(value)
.boolean(value)
.symbol(value)
Built-in types
.array(value)
.function(value)
.buffer(value)
.object(value)
Keep in mind that functions are objects too.
.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)
.map(value)
.set(value)
.weakMap(value)
.weakSet(value)
Typed arrays
.int8Array(value)
.uint8Array(value)
.uint8ClampedArray(value)
.int16Array(value)
.uint16Array(value)
.int32Array(value)
.uint32Array(value)
.float32Array(value)
.float64Array(value)
Structured data
.arrayBuffer(value)
.sharedArrayBuffer(value)
.dataView(value)
Miscellaneous
.nan(value)
.nullOrUndefined(value)
.primitive(value)
JavaScript primitives are as follows: null
, undefined
, string
, number
, boolean
, symbol
.
.integer(value)
.plainObject(value)
An object is plain if it's created by either {}
, new Object()
, or Object.create(null)
.
.iterable(value)
.class(value)
Returns true
for instances created by a ES2015 class.
.typedArray(value)
.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.
is.inRange(3, [0, 5]);
is.inRange(3, [5, 0]);
is.inRange(0, [-2, 2]);
.inRange(value, upperBound)
Check if value
(number) is in the range of 0
to upperBound
.
is.inRange(3, 10);
FAQ
Why yet another type checking module?
There are hundreds of type checking modules on npm, unfortunately, I couldn't find any that fit my needs:
- Includes both type methods and ability to get the type
- Types of primitives returned as lowercase and object types as camelcase
- Covers all built-ins
- Unsurprising behavior
- Well-maintained
- Comprehensive test suite
For the ones I found, pick 3 of these.
The most common mistakes I noticed in these modules was using instanceof
for type checking, forgetting that functions are objects, and omitting symbol
as a primitive.
Related
Created by
License
MIT