If you use this repo, star it
Forked from @sniptt/guards
Zero dependencies
Install
Node.js and the browser
npm install @tjmgregory/asserts
Deno
import { ... } from 'https://deno.land/x/asserts/mod.ts'
// TODO
Why the fork?
@sniptt/guards allows you to infer your types via if
statements.
asserts enables this same type inference, but without if
statements, instead by informing the compiler that we will throw if this value is not of this type, so you know for certain that it is.
Usage
Foreword on JavaScript data types and data structures
The latest ECMAScript standard defines nine types:
- Six Data Types that are primitives, checked by
typeof
operator:-
undefined
:typeof instance === "undefined"
-
Boolean
:typeof instance === "boolean"
-
Number
:typeof instance === "number"
-
String
:typeof instance === "string"
-
BigInt
:typeof instance === "bigint"
-
Symbol
:typeof instance === "symbol"
-
-
Structural Types:
-
Object
:typeof instance === "object"
. Special non-data but structural type for any constructed object instance also used as data structures: newObject
, newArray
, newMap
, newSet
, newWeakMap
, newWeakSet
, newDate
and almost everything made withnew
keyword; -
Function
non data structure, though it also answers fortypeof
operator:typeof instance === "function"
. This answer is done as a special shorthand forFunction
s, though everyFunction
constructor is derived fromObject
constructor.
-
-
Structural Root Primitive
-
null
:typeof instance === "object"
. Special primitive type having additional usage for it's value: if object is not inherited, thennull
is shown;
-
Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures
Primitives
Sample usage:
import { primitives } from '@tjmgregory/asserts';
primitives.isNumber(val);
or
import { isNumber } from '@tjmgregory/asserts';
isNumber(val);
isBigInt
import { isBigInt } from '@tjmgregory/asserts';
let val: bigint | number;
function wantsABigint(foo: bigint) {}
isBigInt(val);
// TypeScript will infer val is now a bigint, else it would have thrown
wantsABigint(val); // Compiles
isBoolean
import { isBoolean } from '@tjmgregory/asserts';
let val: boolean | number;
function wantsABoolean(foo: boolean) {}
isBoolean(val);
// TypeScript will infer val is now a boolean, else it would have thrown
wantsABoolean(val); // Compiles
isNumber
Throws for NaN
!
See also:
import { isNumber } from '@tjmgregory/asserts';
let val: number | string;
function wantsANumber(foo: number) {}
isNumber(val);
// TypeScript will infer val is now a number, else it would have thrown
wantsANumber(val); // Compiles
isString
import { isString } from '@tjmgregory/asserts';
let val: string | number;
function wantsAString(foo: string) {}
isString(val);
// TypeScript will infer val is now a string, else it would have thrown
wantsAString(val); // Compiles
isSymbol
import { isSymbol } from '@tjmgregory/asserts';
let val: symbol | string;
function wantsASymbol(foo: symbol) {}
isSymbol(val);
// TypeScript will infer val is now a symbol, else it would have thrown
wantsASymbol(val); // Compiles
isUndefined
import { isUndefined } from '@tjmgregory/asserts';
let val: undefined | null;
function wantsUndefined(foo: undefined) {}
isUndefined(val);
// TypeScript will infer val is now a undefined, else it would have thrown
wantsUndefined(val); // Compiles
Structural
Sample usage:
import { structural } from '@tjmgregory/asserts';
structural.isMap(val);
or
import { isMap } from '@tjmgregory/asserts';
isMap(val);
isNull
Answers true
if and only if value === null
.
isFunction
Answers true
if and only if typeof value === "function"
.
isObject
Answers false
to null
!
To check for array:
isArray(term);
To check for object or null:
isObjectOrNull(term);
isArray
Throws if and only if Array.isArray(value) !== true
.
isMap
Throws if and only if (value instanceof Map) !== true
.
isSet
Throws if and only if (value instanceof Set) !== true
.
isWeakMap
Throws if and only if (value instanceof WeakMap) !== true
.
isWeakSet
Throws if and only if (value instanceof WeakSet) !== true
.
isDate
Throws if and only if (value instanceof Date) !== true
.
Convenience
Sample usage:
import { convenience } from '@tjmgregory/asserts';
convenience.isNonEmptyArray(val);
or
import { isNonEmptyArray } from '@tjmgregory/asserts';
isNonEmptyArray(val);
isObjectOrNull
isNonEmptyArray
isNonEmptyString
isNumberOrNaN
isInteger
isPositiveInteger
isNonNegativeInteger
isNegativeInteger
API Docs
License
See LICENSE