isit

A Node.js module that tests a value’s type against a string like 'positive integer' or 'non-empty map'.

Installation

npm install isit --save

Usage

When calling isit(), the first argument is a space-separated string of type tests, and the second argument is the value to be tested. isit() returns true only if all tests pass.

const isit = require('isit')
isit('non-empty array', [1, 2, 3]) // true
isit('empty map', new Map()) // true
isit('positive integer', 1) // true

Available tests are listed in the “Type Tests” section below. Anything that does not match one of the available tests will be considered a class name (example: map in the above code block).

Negation

A test can be individually negated by prefixing it with non- or !, as in:

const isit = require('isit')
isit('non-empty array', [1, 2, 3]) // true
isit('array !empty', [1, 2, 3]) // true
isit('empty non-array', '') // true

Create Curried Functions

If you omit the second argument, a function is returned which runs the test provided in the first argument.

const isObject = require('isit')('non-array object')
isObject({}) // true
isObject([]) // false

Individual Test Functions

All tests are also available as member functions of isit, allowing you to run a single test like so:

const isit = require('isit')
isit.array([]) // true
 
const isString = require('isit').string
isString('test') // true

Type Tests

Here is the complete list:

• arguments / args
• array
• blank
• boolean / bool
• boolish
• buffer
• collection
• empty
• false
• falsey
• float
• finite
• function
• generator
• infinity
• integer / int
• iterable
• nan
• negative
• nil
• null
• number
• numberish
• numeric
• object
• objectbased
• plain
• positive
• primitive
• scalar
• string
• stringish
• symbol
• true
• truthy
• typedarray
• undefined / undef

Undefined & Null

Value:	undefined undef	null	nil
undefined	✔		✔
null		✔	✔

Primitives & Scalars

Value Type:	primitive	scalar
Undefined	✔
Null	✔
Boolean	✔	✔
Number	✔	✔
String	✔	✔
Symbol	✔	✔
Object
Function

Booleans

Value:	boolean bool	boolish
true	✔	✔
false	✔	✔
'true' string		✔
'false' string		✔
new Boolean(true)		✔
new Boolean(false)		✔

Value:	true	truthy
true	✔	✔
new Boolean(true)	✔	✔
'true' string	✔	✔
'false' string
1		✔
'test'		✔
[]		✔

Value:	false	falsey
false	✔	✔
new Boolean(false)	✔	✔
'false' string	✔	✔
0		✔
''		✔

Empty Values

Every empty-checker out there assesses “emptiness” a bit differently. For our purposes, an empty value is one which contains no useful information except the absence of a value. Therefore, unlike many similar functions, the empty test does not consider 0, false, or zero-parameter functions to be “empty,” because these can often be intended as actual values.

Value:	empty
undefined	✔
null	✔
NaN	✔
0
false
''	✔
{}	✔
[]	✔
() => {}
new Error()
new Map()	✔
new Set()	✔

Blank Values

The blank test is the same as empty except it also returns true for strings that consist only of whitespace.

Functions

Value:	function	generator
function () {}	✔
() => {}	✔
function* () {}	✔	✔

Numbers

Value:	number	numberish	numeric
0	✔	✔	✔
1.23	✔	✔	✔
new Number(1)		✔	✔
'1'			✔
'1e3'			✔
NaN

Value:	positive	negative
Infinity	✔
123.45	✔
0	✔
-0		✔
-123.45		✔
-Infinity		✔

JavaScript considers the number zero to be either positively or negatively signed; therefore, positive reports true for 0. If you want to exclude zero, consider using a simple x>0 test instead.

More Number Tests:

• nan
• integer / int
• float
• finite
• infinity

Objects

Although functions are technically objects in JavaScript, they are often considered a separate category because the typeof operator gives them their own type. Use objectbased if you want to include functions.

Value:	object	objectbased
{}	✔	✔
() => {}		✔

Value:	object	plain	array
new Date()	✔
{}	✔	✔
[]	✔		✔

The object test returns true for arrays, because arrays are objects in JavaScript. If you want to exclude arrays, test against 'non-array object' instead.

Arguments

arguments or args returns true if the value is an Arguments object.

Buffers

The buffer test returns true if the value is a Node.js or Browserify Buffer.

Collections

The collection test returns true if the value is an instance of one of:

• Map
• Set
• WeakMap
• WeakSet

Iterables

The iterable test returns true if for...of can be used to iterate through the value.

Typed Arrays

The typedarray test returns true if the value is an instance of one of:

• Int8Array
• Uint8Array
• Uint8ClampedArray
• Int16Array
• Uint16Array
• Int32Array
• Uint32Array
• Float32Array
• Float64Array

Strings

Value:	string	stringish
''	✔	✔
'test'	✔	✔
new String('test')		✔

Symbols

The symbol test returns true if the value is a symbol.

Class Testing

You can use isit.a or isit.an to see if an object is an instance of a given class.

You can provide the class itself or the class name as a case-insensitive string.

const isit = require('isit')
 
isit.a(Date, new Date()) // true
isit.a('date', new Date()) // true
 
isit.an(Error, new Error()) // true
isit.an('error', new Error()) // true
 
// Returns true because TypeError extends Error
isit.an(Error, new TypeError()) // true

You can also check if a given value is an instance of any one of a list of classes:

const isit = require('isit')
 
isit.a([TypeError, ReferenceError], new TypeError()) // true
isit.a('TypeError ReferenceError', new TypeError()) // true

Advanced Usage

Adding or Overriding Tests

You can add new tests, or override existing ones, by requiring isit/x and calling it as a function with the additional tests as an object argument. For example:

const isit = require('isit/x')({
  zero: value => value === 0
})
isit('negative zero', -0) // true
isit('non-zero integer', 1) // true