Type checking utilities

Description

Type checking utilities for the NodeJS development environment. It is a powerful tool to dynamically control the types of input parameters.

Installation

npm

$ npm i type-checking-utils -D

yarn

$ yarn add type-checking-utils -D

Usage

Both CommonJS and ESM are supported

const { isStrM, ifStrM } = require('type-checking-utils')
// or
import { isStrM, ifStrM } from 'type-checking-utils'

Simple usage of is-functions

import { isStrM } from 'type-checking-utils'
/* some code */
let output = ''
if (isStrM(input)) { output = input }
// if input is a not empty string
console.log(output) // => 'a not empty string'

Simple usage of if-functions

import { ifStrM } from 'type-checking-utils'
/* some code */
const output = ifStrM(input)
// if input is a not empty string
console.log(output) // => 'a not empty string'
// else
console.log(output) // => ''

Advanced usage of if-functions

See the "if-functions" paragraph.

Functions

Description

There are three sets of types:

• isBool - true and false
• isNotExists - NaN, undefined and null
• isExists- all of the rest

Until version 2.0.0, there were two collections, namely isBool was included in isExists.

Shakespeare once wrote "To be or not to be...". With this phrase he expressed an ancient philosophical concept of being. However, someone decides what exists and what does not exist. Thus, we have three entities: that which exists, that which does not exist, and that which allows us to know about it.

Based on the above, it was decided to divide all types into three sets of types.

Each of the three sets corresponds to its own function of the same name, which returns true or false. All other functions included in the isExists set were created on the basis of the isExists(input) function. All the resulting functions were named is-functions.

Note: If you were using a version lower than 2.0.0 and applied the isExists(input) function, you can simply replace it with !isNotExists(input) and everything will work as before.

is-functions of isExists

These functions can get one or two parameters. The first parameter can be of any type. The second parameter can only be for functions with the postfixes M, ME, E, LE, L. The second parameter must always be of the type "number". For Num* functions, its value can be any, for other functions it must be more than or equal to zero (>= 0). Otherwise the default value will be applied, which for functions with the postfix M, ME and E is 0, and for functions with the postfix LE and L is 1.

Postfix meanings:

• M - more than (>)
• ME - more than or equal to (>=)
• E - equal to (===)
• LE - less than or equal to (<=)
• L - less than (<)

is-functions table

Usage | Condition (When the entered value matches the condition, the value true is returned, otherwise the value false is returned.) --- | --- isBool(input) | boolean isNotExists(input) | NaN, undefined or null isExists(input) | any instead boolean, NaN, undefined and null isFunc(input) | function isSymbol(input) | symbol isRe(input) | RegExp isDate(input) | Date isPromise(input) | Promise isNum(input) | number isNumI(input) | number with input % 1 === 0 (integer) isNumM(input[, val]) | number with input > val isNumME(input[, val]) | number with input >= val isNumE(input[, val]) | number with input === val isNumLE(input[, val]) | number with input <= val isNumL(input[, val]) | number with input < val isStr(input) | string isStrM(input[, len]) | string with input.length > len isStrME(input[, len]) | string with input.length >= len isStrE(input[, len]) | string with input.length === len isStrLE(input[, len]) | string with input.length <= len isStrL(input[, len]) | string with input.length < len isArr(input) | Array isArrM(input[, len]) | Array with input.length > len isArrME(input[, len]) | Array with input.length >= len isArrE(input[, len]) | Array with input.length === len isArrLE(input[, len]) | Array with input.length <= len isArrL(input[, len]) | Array with input.length < len isSet(input) | Set isSetM(input[, size]) | Set with input.size > size isSetME(input[, size]) | Set with input.size >= size isSetE(input[, size]) | Set with input.size === size isSetLE(input[, size]) | Set with input.size <= size isSetL(input[, size]) | Set with input.size < size isMap(input) | Map isMapM(input[, size]) | Map with input.size > size isMapME(input[, size]) | Map with input.size >= size isMapE(input[, size]) | Map with input.size === size isMapLE(input[, size]) | Map with input.size <= size isMapL(input[, size]) | Map with input.size < size isObjA(input) | object (any object) isObj(input) | When isObjA(input) is true, but not boolean, RegExp, Date, Promise, number, string, Array, Set, Map isObjM(input[, len]) | When isObj(input) is true, and with input.length > len isObjME(input[, len]) | When isObj(input) is true, and with input.length >= len isObjE(input[, len]) | When isObj(input) is true, and with input.length === len isObjLE(input[, len]) | When isObj(input) is true, and with input.length <= len isObjL(input[, len]) | When isObj(input) is true, and with input.length < len

if-functions

On the basis of is-functions since version 2.1.0, if-functions were created according to a single template. This means that a separate if-function has been created based on each is-function. Let's look at this template using the ifStrM function as an example. It is shown below:

function ifStrM(input, elseRn, thenCB, elseCB, len) {
    const validElseRn = isStr(elseRn) ? elseRn : ''
    if (isStrM(input, len)) {
        if (isFunc(thenCB)) {
            const thenCBRnd = thenCB(input, validElseRn)
            if (thenCBRnd === undefined) { thenCBRnd }
            else { return thenCBRnd }
        }
        return input
    }
    if (isFunc(elseCB)) {
        const elseCBRnd = elseCB(input, validElseRn)
        if (elseCBRnd === undefined) { elseCBRnd }
        else { return elseCBRnd }
    }
    return validElseRn
}

There is only one required parameter - input.

The last parameter len corresponds to the second parameter of the isStrM function, and as a consequence, the default value for it is defined by the isStrM function. If input is of type string and has length more than len, the function will return input, otherwise it will return what is defined in the elseRn parameter (by default - '').

Important Note: The default value for len can be viewed in the if-functions table.

Important Note: The type of the elseRn parameter in the if* function is determined by the corresponding is* function. The default value for elseRn can be viewed in the if-functions table.

Therefore, the type of the elseRn parameter for the ifStrM function must be string.

The parameters thenCB and elseCB must be functions, otherwise they will be ignored. The thenCB and elseCB functions pass the input and validated elseRn parameters as arguments.

Important Note: Valid elseRn as an argument was added in version 2.2.0. Before that, only input was passed as an argument to the thenCB and elseCB functions!

The thenCB function will start if input is of type string, otherwise the elseCB function will start. The thenCB and elseCB functions may or may not return values. If the thenCB function is started and returns any value, it is the value that will be returned by the ifStrM function. If the elseCB function is started and returns any value, it is the value that will be returned by the ifStrM function. The value returned by the thenCB and elseCB functions can be anything!

Important Note: This way you can make if-function return anything you want, but it will be entirely your own decision!!!

In fact, the main purpose of the thenCB and elseCB functions is not to return a value to the main ifStrM function, but to perform calculations to handle any external variables, such as objects.

if-functions were created primarily for use in two main situations.

Example for the first situation

const output = ifStrM(getSomeString())
// If getSomeString() returns 'a not empty string' then
console.log(output) // => 'a not empty string'
// else
console.log(output) // => ''

Example for the second situation

const outputObj = { someKey: '' }
ifStrM(getSomeString(), '', (v) => { outputObj.someKey = v })
// If getSomeString() returns 'a not empty string' then
console.log(outputObj) // => { someKey: 'a not empty string' }
// else
console.log(outputObj) // => { someKey: '' }

An example of combining both situations

const outputObj = { someKey: '' }
const output = ifStrM(getSomeString(), '', (v) => { outputObj.someKey = v })
// If getSomeString() returns 'a not empty string' then
console.log(output)    // => 'a not empty string'
console.log(outputObj) // => { someKey: 'a not empty string' }
// else
console.log(output)    // => ''
console.log(outputObj) // => { someKey: '' }

Using the isStrM function, the code above can be written like this:

const outputObj = { someKey: '' }
const intermediateOutput = getSomeString()
let output = ''
if (isStrM(intermediateOutput)) {
    output = intermediateOutput
    outputObj.someKey = intermediateOutput
}
// We'll get exactly the same results.

You can see that, first, you needed to create an intermediate variable to avoid executing the getSomeString() function twice. Second, getting the value for the output variable is done in two steps.

Thus, the advantage of using ifStrM is, in my opinion, obvious.

if-functions table

Usage | elseRn (default value) | len (default value) --- | --- |--- ifBool(input[, elseRn, thenCB, elseCB]) | false | - ifNotExists(input[, elseRn, thenCB, elseCB]) | false | - ifExists(input[, elseRn, thenCB, elseCB]) | false | - ifFunc(input[, elseRn, thenCB, elseCB]) | false | - ifSymbol(input[, elseRn, thenCB, elseCB]) | false | - ifRe(input[, elseRn, thenCB, elseCB]) | false | - ifDate(input[, elseRn, thenCB, elseCB]) | false | - ifPromise(input[, elseRn, thenCB, elseCB]) | false | - ifNum(input[, elseRn, thenCB, elseCB]) | 0 | - ifNumI(input[, elseRn, thenCB, elseCB]) | 0 | - ifNumM(input[, elseRn, thenCB, elseCB, len]) | 0 | 0 ifNumME(input[, elseRn, thenCB, elseCB, len]) | 0 | 0 ifNumE(input[, elseRn, thenCB, elseCB, len]) | 0 | 0 ifNumLE(input[, elseRn, thenCB, elseCB, len]) | 0 | 1 ifNumL(input[, elseRn, thenCB, elseCB, len]) | 0 | 1 ifStr(input[, elseRn, thenCB, elseCB]) | '' | - ifStrM(input[, elseRn, thenCB, elseCB, len]) | '' | 0 ifStrME(input[, elseRn, thenCB, elseCB, len]) | '' | 0 ifStrE(input[, elseRn, thenCB, elseCB, len]) | '' | 0 ifStrLE(input[, elseRn, thenCB, elseCB, len]) | '' | 1 ifStrL(input[, elseRn, thenCB, elseCB, len]) | '' | 1 ifArr(input[, elseRn, thenCB, elseCB]) | [] | - ifArrM(input[, elseRn, thenCB, elseCB, len]) | [] | 0 ifArrME(input[, elseRn, thenCB, elseCB, len]) | [] | 0 ifArrE(input[, elseRn, thenCB, elseCB, len]) | [] | 0 ifArrLE(input[, elseRn, thenCB, elseCB, len]) | [] | 1 ifArrL(input[, elseRn, thenCB, elseCB, len]) | [] | 1 ifSet(input[, elseRn, thenCB, elseCB]) | new Set() | - ifSetM(input[, elseRn, thenCB, elseCB, len]) | new Set() | 0 ifSetME(input[, elseRn, thenCB, elseCB, len]) | new Set() | 0 ifSetE(input[, elseRn, thenCB, elseCB, len]) | new Set() | 0 ifSetLE(input[, elseRn, thenCB, elseCB, len]) | new Set() | 1 ifSetL(input[, elseRn, thenCB, elseCB, len]) | new Set() | 1 ifMap(input[, elseRn, thenCB, elseCB]) | new Map() | - ifMapM(input[, elseRn, thenCB, elseCB, len]) | new Map() | 0 ifMapME(input[, elseRn, thenCB, elseCB, len]) | new Map() | 0 ifMapE(input[, elseRn, thenCB, elseCB, len]) | new Map() | 0 ifMapLE(input[, elseRn, thenCB, elseCB, len]) | new Map() | 1 ifMapL(input[, elseRn, thenCB, elseCB, len]) | new Map() | 1 ifObjA(input[, elseRn, thenCB, elseCB]) | false | - ifObj(input[, elseRn, thenCB, elseCB]) | {} | - ifObjM(input[, elseRn, thenCB, elseCB, len]) | {} | 0 ifObjME(input[, elseRn, thenCB, elseCB, len]) | {} | 0 ifObjE(input[, elseRn, thenCB, elseCB, len]) | {} | 0 ifObjLE(input[, elseRn, thenCB, elseCB, len]) | {} | 1 ifObjL(input[, elseRn, thenCB, elseCB, len]) | {} | 1

Test

All functions have full coverage with tests that can be run by downloading the source code in the repository.