guardex

Guardex

A very small library to create type guards for your project, it can be used either for typescript or javascript.

To install the guardex library, run the following command in the console.

  npm install guardex --save-dev

Note: All of the examples in this document uses ECMA syntax to import or export code from the library, but this supports CommonJS syntax as well.

// ECMA Syntax
import is from "guardex";

// CommonJS Syntax
const is = require("guardex");

If you are using ESM with TypeScript consider reading the following information links:

• https://github.com/TypeStrong/ts-node#node-flags-and-other-tools
• https://www.typescriptlang.org/docs/handbook/esm-node.html
• https://nodejs.org/api/esm.html

Functions

These are the functions from the is exported object that can be used as type guards.

function	guards to
undefined	undefined
null	null
trivial	null, undefined
value	{}
object	{} or T
json	{} or T
rgb	{ red: number, green: number, blue: number }
function	Function
symbol	Symbol
string	string
number	number, bigint
zero	0
positive	number, bigint, not 0
negative	number, bigint, not 0
between	number, bigint
inside	number, bigint
smaller	number, bigint
smallerOrEqual	number, bigint
bigger	number, bigint
biggerOrEqual	number, bigint
array	Array (Exotic object)
true	true
truthy	Other than false, 0, "", null, undefined
false	false
falsy	false, 0, "", null, undefined
boolean	boolean
true	true
false	false
primitive	Function, Symbol, string, number, bigint, boolean
promise	Promise, Custom Promise (Read Promises)

Descriptions

Undefined

Checks if some value is undefined..

Null

Checks if some value is null..

Trivial

Checks if some value is null or undefined..

Value

Checks if some value is not null or undefined..

Object

Checks if some value is a function.

Symbol

Checks if some value is a string.

Number

Checks if some value is a number.

Zero

Checks if some value is a number and zero.

Positive

Checks if some value is a number and is positive.

Note Includes 0 as positive value

Negative

Checks if some value is a number and is negative.

Note Not includes 0 as negative value

Between

Checks if is a number and if it is between the upper bound and lower bound.

Inside

Checks if is a number and if it is between the upper bound and lower bound or is one of those values.

Smaller

Checks if is a number and if it is before the bound.

Smaller Or Equal

Checks if is a number and if it is before the bound or is equal/

Bigger

Checks if is a number and if it is beyond the bound.

Bigger Or Equal

Checks if is a number and if it is beyond the bound or is equal.

Boolean

Checks if some value is a boolean.

True

Checks if some value is a boolean and is true.

Truthy

Checks if some value is truthy.

Note Any other value than false, 0, "", null, undefined is considered truthy.

False

Checks if some value is a boolean and is false.

Falsy

Checks if some value is falsy.

Note Any value of false, 0, "", null, undefined is considered falsy.

Primitive

Checks if some value is a JavaScript primitive.

Array

Checks a value is a valid array.

Note Only works for the exotic object Array.

Object

Checks if some value is not a primitive.

Note If using typescript the generic T works only as a type guard and not as an instance checker, for more information go to https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates

JSON

Checks if the value descends from the protoype of the {} object and is not a primitive value.

Note If using typescript the generic T works only as a type guard and not as an instance checker, for more information go to https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates

Instance Of

Checks if the passed value is a valid instance of the parent.

RGB

Checks if an object is a valid RGB where the passed object should contain the red, green, blue properties where each one should be a number from 0 to 255.

RGB String

Checks if the string starts with the character # and if after that is followed by 6 characters where each: is a value from A to F (casing is ignored) or any number from 0 to 9.

// This is a valid RGB string
const tangerine = "#e1442A";

Promises

Promises were while ago a feature only accessible with polyfills. This was somehing new that helped a lot to run in syntactic sugar way callbacks.
Currently is a fully supported feature in every modern browser or any modern JavaScript interpreter with the standarization of ES6 (https://caniuse.com/?search=es6) with even its own syntactic sugar as the async/await of JavaScript.
Because of this, when the global Promise class is found the only comparison that will be done is that is a non trivial value and the instanceof operator.

In case this function runs in an obsolete environment (i.e. Internet Explorer) that ussually uses polyfill libraries, the method will check:

• That is an object (not trivial)
• If the then, catch and finally function are available
• If its part of the protoype chain of a Promise prototype function
• If it contains the Symbol.toStringTag equals to "[object Promise]"

The custom Promise may look like the following example:

// Parent function
function Promise() {}

// All of the three standard methods
Promise.then = function () {};
Promise.catch = function (error) {};
Promise.finally = function () {};

// The symbol tag to be represented as a promise
Promise[Symbol.toStringTag] = "Promise";

// The prototype and constructor assignation
Promise.prototype = Promise;
Promise.constructor = Promise;