is

@bearclaw/is is a set of runtime type-checking and environment-detecting functions.

Helpers

validate

Check that some assertion is true and return a ValidationException (or some provided custom error) if it is not.

function validateIsNotNil(value: unknown) {
  return validate(!isNil(value), 'isNotNil')
}
validateIsNotNil({}) // null
validateIsNotNil(null) // returns ValidationException

assert

Check that some assertion is true and throw an AssertionException (or some provided custom error) if it is not.

function assertIsNotNil(value: unknown) {
  return assert(!isNil(value), 'isNotNil')
}
assertIsNotNil({}) // void
assertIsNotNil(null) // throws AssertionException

getType

Get a value's type. Uses Object.prototype.toString so it will not work with custom classes unless [Symbol.toStringTag] is defined. See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures

getType([]) // "Array"
getType(1) // "Number"
getType('1') // "String"

Type Checking

isArray

Is the value an Array?

isArray([1]) // true
isArray(1) // false
validateArray([1]) // null
validateArray(1) // ValidationException
assertArray([1]) // void
assertArray(1) // throws AssertionException

isArrowFunction

Is the value an arrow function?

isArrowFunction(() => 'a') // true
isArrowFunction(function () {}) // false
validateArrowFunction(() => 'a') // null
validateArrowFunction(function () {}) // ValidationException
assertArrowFunction(() => 'a') // void
assertArrowFunction(function () {}) // throws AssertionException

isAsyncFunction

Is the value an async function?

isAsyncFunction(async () => 'a') // true
isAsyncFunction(() => 'a') // false
validateAsyncFunction(async () => 'a') // null
validateAsyncFunction(() => 'a') // ValidationException
assertAsyncFunction(async () => 'a') // void
assertAsyncFunction(() => 'a') // throws AssertionException

isBigInt

Is the value a BigInt?

isBigInt(BigInt(1)) // true
isBigInt(1) // false
validateBigInt(BigInt(1)) // null
validateBigInt(1) // ValidationException
assertBigInt(BigInt(1)) // void
assertBigInt(1) // throws AssertionException

isBindable

Is the value bindable? Arrow functions, constructors and functions that are already bound will not be bindable.

isBindable(function () {}) // true
isBindable(function () { return 'a'; }.bind(this)) // false
isBindable(() => 'a') // false
validateBindable(function () {}) // null
validateBindable(function () { return 'a'; }.bind(this)) // ValidationException
validateBindable(() => 'a') // ValidationException
assertBindable(function () {}) // void
assertBindable(function () { return 'a'; }.bind(this)) // throws AssertionException
assertBindable(() => 'a') // throws AssertionException

isBoolean

Is the value a boolean?

isBoolean(true) // true
isBoolean(1) // false
validateBoolean(true) // null
validateBoolean(1) // ValidationException
assertBoolean(true) // void
assertBoolean(1) // throws AssertionException

isBoundFunction

Is the value a bound function?

isBoundFunction(function () { return 'a'; }.bind(this)) // true
isBoundFunction(function () {}) // false
validateBoundFunction(function () { return 'a'; }.bind(this)) // null
validateBoundFunction(function () {}) // ValidationException
assertBoundFunction(function () { return 'a'; }.bind(this)) // void
assertBoundFunction(function () {}) // throws AssertionException

isClassCtor

Is the values a class constructor?

isClassCtor(class Person {}) // true
isClassCtor(new Person()) // false
validateClassCtor(class Person {}) // null
validateClassCtor(new Person()) // ValidationException
assertClassCtor(class Person {}) // void
assertClassCtor(new Person()) // throws AssertionException

isDateObject

Is the value a Date object?

isDateObject(new Date()) // true
isDateObject(1) // false
validateDateObject(new Date()) // null
validateDateObject(1) // ValidationException
assertDateObject(new Date()) // void
assertDateObject(1) // throws AssertionException

isEmpty

Is the value an empty string, null, undefined, NaN or an array, map, object or set with no values?

isEmpty('') // true
isEmpty([]) // true
isEmpty('example') // false
validateEmpty('') // null
validateEmpty([]) // null
validateEmpty('example') // ValidationException
assertEmpty('') // void
assertEmpty([]) // void
assertEmpty('example') // throws AssertionException

isEmptyArray

Is the value an array with no values?

isEmptyArray([]) // true
isEmptyArray(['1']) // false
validateEmptyArray([]) // null
validateEmptyArray(['1']) // ValidationException
assertEmptyArray([]) // void
assertEmptyArray(['1']) // throws AssertionException

isEmptyMap

Is the value a Map with no entries?

isEmptyMap(new Map()) // true
isEmptyMap(new Map([['foo', 'bar']])) // false
validateEmptyMap(new Map()) // null
validateEmptyMap(new Map([['foo', 'bar']])) // ValidationException
assertEmptyMap(new Map()) // void
assertEmptyMap(new Map([['foo', 'bar']])) // throws AssertionException

isEmptyObject

Is the value a plain object with no entries?

isEmptyObject({}) // true
isEmptyObject({ foo: 'bar' }) // false
validateEmptyObject({}) // null
validateEmptyObject({ foo: 'bar' }) // ValidationException
assertEmptyObject({}) // void
assertEmptyObject({ foo: 'bar' }) // throws AssertionException

isEmptyPrimitive

Is the value an empty string, null, undefined or NaN?

isEmptyPrimitive('') // true
isEmptyPrimitive('example') // false
validateEmptyPrimitive('') // null
validateEmptyPrimitive('example') // ValidationException
assertEmptyPrimitive('') // void
assertEmptyPrimitive('example') // throws AssertionException

isEmptySet

Is the value a Set with no values?

isEmptySet(new Set()) // true
isEmptySet(new Set([1])) // false
validateEmptySet(new Set()) // null
validateEmptySet(new Set([1])) // ValidationException
assertEmptySet(new Set()) // void
assertEmptySet(new Set([1])) // throws AssertionException

isEmptyString

Is the value a string with no characters?

isEmptyString('') // true
isEmptyString('1') // false
validateEmptyString('') // null
validateEmptyString('1') // ValidationException
assertEmptyString('') // void
assertEmptyString('1') // throws AssertionException

isEmptyStructural

Is the value an array, map, object or set with no values?

isEmptyStructural([]) // true
isEmptyStructural(['example']) // false
validateEmptyStructural([]) // null
validateEmptyStructural(['example']) // ValidtionException
assertEmptyStructural([]) // void
assertEmptyStructural(['example']) // throws AssertionException

isFalsy

Is the value falsy?

isFalsy(0) // true
isFalsy(1) // false
validateFalsy(0) // null
validateFalsy(1) // ValidationException
assertFalsy(0) // void
assertFalsy(1) // throws AssertionException

isFunction

Is the value a function?

isFunction(() => {}) // true
isFunction(1) // false
validateFunction(() => {}) // null
validateFunction(1) // ValidationException
assertFunction(() => {}) // void
assertFunction(1) // throws AssertionException

isGeneratorFunction

Is the value a generator function?

isGeneratorFunction(function* () { yield 'a' }) // true
isGeneratorFunction(() => 'a') // false
validateGeneratorFunction(function* () { yield 'a' }) // null
validateGeneratorFunction(() => 'a') // ValidationException
assertGeneratorFunction(function* () { yield 'a' }) // void
assertGeneratorFunction(() => 'a') // throws AssertionException

isImmutable

Is the value immutable?

isImmutable(1) // true
isImmutable(Object.freeze({})) // true
isImmutable({}) // false
validateImmutable(1) // null
validateImmutable(Object.freeze({})) // null
validateImmutable({}) // ValidationException
assertImmutable(1) // void
assertImmutable(Object.freeze({})) // void
assertImmutable({}) // throws AssertionException

isInstanceOf

Is the value an instance of the provided constructor?

isInstanceOf(Number, 1) // true
isInstanceOf(String, 1) // false
validateInstanceOf(Number, 1) // null
validateInstanceOf(String, 1) // ValidationException
assertInstanceOf(Number, 1) // void
assertInstanceOf(String, 1) // throws AssertionException

isJSON

Is the value a valid JSON value?

isJSON({ 'foo': 'bar' }) // true
isJSON(new Map()) // false
validateJSON({ 'foo': 'bar' }) // null
validateJSON(new Map()) // ValidationException
assertJSON({ 'foo': 'bar' }) // void
assertJSON(new Map()) // throws AssertionException

isMap

Is the value a Map?

isMap(new Map()) // true
isMap({}) // false
validateMap(new Map()) // null
validateMap({}) // ValidationException
assertMap(new Map()) // void
assertMap({}) // throws AssertionException

isNull

Is the value null?

isNull(null) // true
isNull(1) // false
validateNull(null) // null
validateNull(1) // ValidationException
assertNull(null) // void
assertNull(1) // throws AssertionException

isNil

Is the value null or undefined?

isNil(null) // true
isNil(undefined) // true
isNil(1) // false
validateNil(null) // null
validateNil(undefined) // null
validateNil(1) // ValidationException
assertNil(null) // void
assertNil(undefined) // void
assertNil(1) // throws AssertionException

isNumber

Is the value a number?

isNumber(1) // true
isNumber('') // false
validateNumber(1) // null
validateNumber('') // ValidationException
assertNumber(1) // void
assertNumber('') // throws AssertionException

isObject

Is the value a non-null object?

isObject({}) // true
isObject(1) // false
validateObject({}) // null
validateObject(1) // ValidationException
assertObject({}) // void
assertObject(1) // throws AssertionException

isPlainObject

Is the value a plain object?

isPlainObject({}) // true
isPlainObject(new Person()) // false
validatePlainObject({}) // null
validatePlainObject(new Person()) // ValidationException
assertPlainObject({}) // void
assertPlainObject(new Person()) // throws AssertionException

isPrimitive

Is the value one of the primitive types?

isPrimitive(1) // true
isPrimitive({}) // false
validatePrimitive(1) // null
validatePrimitive({}) // ValidationException
assertPrimitive(1) // void
assertPrimitive({}) // throws AssertionException

isPromise

Is the value a Promise?

isPromise(Promise.resolve(a)) // true
isPromise(() => 'a') // false
validatePromise(Promise.resolve(a)) // null
validatePromise(() => 'a') // ValidationException
assertPromise(Promise.resolve(a)) // void
assertPromise(() => 'a') // throws AssertionException

isSet

Is the value a Set?

isSet(new Set()) // true
isSet([]) // false
validateSet(new Set()) // null
validateSet([]) // ValidationException
assertSet(new Set()) // void
assertSet([]) // throws AssertionException

isString

Is the value a string?

isString('') // true
isString(1) // false
validateString('') // null
validateString(1) // ValidationException
assertString('') // void
assertString(1) // throws AssertionException

isStructural

Is the value a structural type (object)?

isStructural({}) // true
isStructural(1) // false
validateStructural({}) // null
validateStructural(1) // ValidationException
assertStructural({}) // void
assertStructural(1) // throws AssertionException

isSymbol

Is the value a Symbol?

isSymbol(Symbol('')) // true
isSymbol('') // false
validateSymbol(Symbol('')) // null
validateSymbol('') // ValidationException
assertSymbol(Symbol('')) // void
assertSymbol('') // throws AssertionException

isTruthy

Is the value truthy?

isTruthy(1) // true
isTruthy(0) // false
validateTruthy(1) // null
validateTruthy(0) // ValidationException
assertTruthy(1) // void
assertTruthy(0) // throws AssertionException

isType

Is the value the provided type? Uses Object.prototype.toString so it will not work with custom classes unless [Symbol.toStringTag] is defined.

isType('Number', 1) // true
isType('String', 1) // false
validateType('Number', 1) // null
validateType('String', 1) // ValidationException
assertType('Number', 1) // void
assertType('String', 1) // throws AssertionException

isUndefined

Is the value undefined?

isUndefined(undefined) // true
isUndefined(1) // false
validateUndefined(undefined) // null
validateUndefined(1) // ValidationException
assertUndefined(undefined) // void
assertUndefined(1) // throws AssertionException

isWeakMap

Is the value a WeakMap?

isWeakMap(new WeakMap()) // true
isWeakMap({}) // false
validateWeakMap(new WeakMap()) // null
validateWeakMap({}) // ValidationException
assertWeakMap(new WeakMap()) // void
assertWeakMap({}) // throws AssertionException

isWeakSet

Is the value a WeakSet?

isWeakSet(new WeakSet()) // true
isWeakSet([]) // false
validateWeakSet(new WeakSet()) // null
validateWeakSet([]) // ValidationException
assertWeakSet(new WeakSet()) // void
assertWeakSet([]) // throws AssertionException

Environment Detection

isBrowserContext

Is this function being invoked in a browser context?

isBrowserContext() // true in a browser, false everywhere else
validateBrowserContext() // null in a browser, ValidationException everywhere else
assertBrowserContext() // void in a browser, throws AssertionException everywhere else

isDenoContext

Is this function being invoked in a Deno context?

isDenoContext() // true in Deno, false everywhere else
validateDenoContext() // null in Deno, ValidationException everywhere else
assertDenoContext() // void in Deno, throws AssertionException everywhere else

isNodeContext

Is this function being invoked in a Node.js context?

isNodeContext() // true in Node, false everywhere else
validateNodeContext() // null in Node, ValidationException everywhere else
assertNodeContext() // void in Node, throws AssertionException everywhere else

isWebWorkerContext

Is this function being invoked in a WebWorker context?

isWebWorkerContext() // true in a WebWorker, false everywhere else
validateWebWorkerContext() // null in a WebWorker, ValidationException everywhere else
assertWebWorkerContext() // void in a WebWorker, throws AssertionException everywhere else

Contributing

Running unit tests

Run nx test is to execute the unit tests via Jest.