A comprehensive, platform-agnostic collection of type guards for TypeScript and JavaScript.
Inspired by Elixir/Erlang Guards.
npm install @hqoss/guards
ES2018
and the library uses commonjs
module resolution. Read more in the Node version support section.
From https://developer.mozilla.org/en-US/docs/Web/JavaScript/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"
null
:typeof instance === "object"
. Special primitive type having additional usage for it's value: if object is not inherited, thennull
is shown;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.
BigInt
support requires targeting ES2020.
let val: boolean | number
if (isBoolean(val)) {
// TypeScript will infer val: boolean
} else {
// TypeScript will infer val: number
}
true
to NaN
!
See also:
let val: number | string
if (isNumber(val)) {
// TypeScript will infer val: number
} else {
// TypeScript will infer val: string
}
let val: string | number
if (isString(val)) {
// TypeScript will infer val: string
} else {
// TypeScript will infer val: number
}
let val: symbol | string
if (isSymbol(val)) {
// TypeScript will infer val: symbol
} else {
// TypeScript will infer val: string
}
let val: undefined | null
if (isUndefined(val)) {
// TypeScript will infer val: undefined
} else {
// TypeScript will infer val: null
}
Answers true
if and only if value === null
.
Full TypeScript (type inference) support.
Answers true
if and only if typeof value === "function"
.
Full TypeScript (type inference) support.
Answers true
if and only if:
isNull(value) === false
; andtypeof value === "object"
To check for "plain" object (excluding array):
isObject(term) && !isArray(term)
To check for array:
isArray(term)
Full TypeScript (type inference) support.
Answers true
if and only if Array.isArray(value) === true
.
Full TypeScript (type inference) support.
Answers true
if and only if (value instanceof Map) === true
.
Full TypeScript (type inference) support.
Answers true
if and only if (value instanceof Set) === true
.
Full TypeScript (type inference) support.
Answers true
if and only if (value instanceof WeakMap) === true
.
Full TypeScript (type inference) support.
Answers true
if and only if (value instanceof WeakSet) === true
.
Full TypeScript (type inference) support.
Answers true
if and only if (value instanceof Date) === true
.
Full TypeScript (type inference) support.
test("isNonEmptyArray", (t) => {
t.is(convenience.isNonEmptyArray([1, 2]), true);
t.is(convenience.isNonEmptyArray([1]), true);
t.is(convenience.isNonEmptyArray([]), false);
});
Full TypeScript (type inference) support.
test("isNonEmptyString", (t) => {
t.is(convenience.isNonEmptyString("a"), true);
t.is(convenience.isNonEmptyString(""), false);
});
Full TypeScript (type inference) support.
test("isValidNumber", (t) => {
t.is(convenience.isValidNumber(0), true);
t.is(convenience.isValidNumber(42), true);
t.is(convenience.isValidNumber(-42), true);
t.is(convenience.isValidNumber(3.14), true);
t.is(convenience.isValidNumber(-3.14), true);
t.is(convenience.isValidNumber(Infinity), true);
t.is(convenience.isValidNumber(-Infinity), true);
t.is(convenience.isValidNumber(Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isValidNumber(-Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isValidNumber(NaN), false);
});
Full TypeScript (type inference) support.
test("isInteger", (t) => {
t.is(convenience.isInteger(0), true);
t.is(convenience.isInteger(42), true);
t.is(convenience.isInteger(-42), true);
t.is(convenience.isInteger(3.14), false);
t.is(convenience.isInteger(-3.14), false);
t.is(convenience.isInteger(Infinity), false);
t.is(convenience.isInteger(-Infinity), false);
t.is(convenience.isInteger(Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isInteger(-Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isInteger(NaN), false);
});
Full TypeScript (type inference) support.
test("isPositiveInteger", (t) => {
t.is(convenience.isPositiveInteger(0), false);
t.is(convenience.isPositiveInteger(42), true);
t.is(convenience.isPositiveInteger(-42), false);
t.is(convenience.isPositiveInteger(3.14), false);
t.is(convenience.isPositiveInteger(-3.14), false);
t.is(convenience.isPositiveInteger(Infinity), false);
t.is(convenience.isPositiveInteger(-Infinity), false);
t.is(convenience.isPositiveInteger(Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isPositiveInteger(-Number.MAX_SAFE_INTEGER), false);
t.is(convenience.isPositiveInteger(NaN), false);
});
Full TypeScript (type inference) support.
test("isNonNegativeInteger", (t) => {
t.is(convenience.isNonNegativeInteger(0), true);
t.is(convenience.isNonNegativeInteger(42), true);
t.is(convenience.isNonNegativeInteger(-42), false);
t.is(convenience.isNonNegativeInteger(3.14), false);
t.is(convenience.isNonNegativeInteger(-3.14), false);
t.is(convenience.isNonNegativeInteger(Infinity), false);
t.is(convenience.isNonNegativeInteger(-Infinity), false);
t.is(convenience.isNonNegativeInteger(Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isNonNegativeInteger(-Number.MAX_SAFE_INTEGER), false);
t.is(convenience.isNonNegativeInteger(NaN), false);
});
Full TypeScript (type inference) support.
test("isNegativeInteger", (t) => {
t.is(convenience.isNegativeInteger(0), false);
t.is(convenience.isNegativeInteger(42), false);
t.is(convenience.isNegativeInteger(-42), true);
t.is(convenience.isNegativeInteger(3.14), false);
t.is(convenience.isNegativeInteger(-3.14), false);
t.is(convenience.isNegativeInteger(Infinity), false);
t.is(convenience.isNegativeInteger(-Infinity), false);
t.is(convenience.isNegativeInteger(Number.MAX_SAFE_INTEGER), false);
t.is(convenience.isNegativeInteger(-Number.MAX_SAFE_INTEGER), true);
t.is(convenience.isNegativeInteger(NaN), false);
});
Full TypeScript (type inference) support.
See full API Documentation here.
-
Code quality; This package may end up being used in mission-critical software, so it's important that the code is performant, secure, and battle-tested.
-
Developer experience; Developers must be able to use this package with no significant barriers to entry. It has to be easy-to-find, well-documented, and pleasant to use.
-
Modularity & Configurability; It's important that users can compose and easily change the ways in which they consume and work with this package.
The project is configured to target ES2018. In practice, this means consumers should run on Node 12 or higher, unless additional compilation/transpilation steps are in place to ensure compatibility with the target runtime.
Please see https://node.green/#ES2018 for reference.
Firstly, according to the official Node release schedule, Node 12.x entered LTS on 2019-10-21 and is scheduled to enter Maintenance on 2020-10-20. With the End-of-Life scheduled for April 2022, we are confident that most users will now be running 12.x or higher.
Secondly, the 7.3 release of V8 (ships with Node 12.x or higher) includes "zero-cost async stack traces".
From the release notes:
We are turning on the --async-stack-traces flag by default. Zero-cost async stack traces make it easier to diagnose problems in production with heavily asynchronous code, as the error.stack property that is usually sent to log files/services now provides more insight into what caused the problem.
Ava, Jest, and Tape were considered. Ava was chosen as it balances simplicity, speed, and modernity very well.
A quick and dirty tech debt tracker before we move to Issues.
- Write a Contributing guide
- Describe scripts and usage, add best practices
- Describe security best practices, e.g.
npm doctor
,npm audit
,npm outdated
,ignore-scripts
in.npmrc
, etc. - Add "Why should I use this" section