Checkard.js is an open source dynamic type checking library for Javascript, Typescript and Node.js to test if a given variable is what it is supposed to be ( Function, object, ascii, boolean, integer, string, json, email...)
- 📦 No dependency
- 🪶 Very lightweight
- 🧪 Thoroughly tested with over 3724 Unit Tests
- 🚚 Shipped as EcmaScrypt module, CommonJS module and IIFE
- 📝 Written in Typescript
- 🌐 Old browsers support
- 💻 Works in Javascript, Typescript and Node.js
- android: 2.2,
- chrome: 34,
- edge: 12,
- firefox: 11,
- ie: 9,
- ios: 4.2,
- opera: 28,
- safari: 5.1,
- samsung: 4,
- Node.js: 14
Those are the oldest targeted versions. The library should work properly on older devices but we do not support it officially.
$ npm i @dwtechs/checkardimport{isFunction,isArray,isString}from"@dwtechs/checkard";if(isFunction(variable)){//variable is a function}if(!isArray(variable,'=',2)){//variable is not an array of length 2}if(!isString(variable)){// variable is not a string}if(isString(variable,"!0")){// variable is a string and is not empty}if(isString(variable,">",2)){// variable is a string of length greater than 2}constch=require("@dwtechs/checkard");// you may need to use "require("@dwtechs/checkard/dist/ch"); with Node.js old versions"if(ch.isFunction(variable)){//variable is a function}if(!ch.isArray(variable,'=',2)){//variable is not an array of length 2}if(!ch.isString(variable)){// variable is not a string}if(ch.isString(variable,"!0")){// variable is a string and is not empty}if(ch.isString(variable,">",2)){// variable is a string of length greater than 2}<scriptsrc="node_modules/@dwtechs/checkard/dist/ch.iife.min.js"></script>if(ch.isFunction(variable)){//variable is a function}if(!ch.isArray(variable,'=',2)){//variable is not an array of length 2}if(!ch.isString(variable)){// variable is not a string}if(ch.isString(variable,"!0")){// variable is a string and is not empty}if(ch.isString(variable,">",2)){// variable is a string of length greater than 2}typeComparator='='|'<'|'>'|'<='|'>='|'!='|'!0'|'0';typePasswordOptions={lowerCase: boolean,upperCase: boolean,number: boolean,specialCharacter: boolean,maxLength: number,minLength: number}primitive methods accept any variable as parameter in order to check its type.
/** * Checks if the given value is of type boolean. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not boolean. If false, returns false. * @returns {boolean} True if the value is a boolean, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a boolean and throwErr is true. */functionisBoolean(v: unknown,throwErr: boolean=false): v is boolean{}/** * Checks if the given value is a number and optionally performs additional checks. * If typeCheck = false values like '4', '0', '8e4', '+true', '0x44' return true * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to perform type checking. Defaults to `true`. * @param {Comparator | null} [comparator=null] - An optional comparator function to compare the value. Defaults to `null`. * @param {number | null} [limit=null] - An optional limit to compare the value against. Defaults to `null`. * @param {boolean} [throwErr=false] - If true, throws an error when comparison fails. If false, returns false. * @returns {boolean} `true` if the value is a number (or number|string if type=false) and passes all checks, otherwise `false`. * @throws {Error} Throws an error if the comparison fails and throwError is true. */functionisNumber<Textendsboolean=true>(v: unknown,type: T=trueasT,comparator: Comparator|null=null,limit: number|null=null,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if the given value is a string and optionally compares its length. * * @param {unknown} v - The value to check. * @param {Comparator | null} [comparator=null] - An optional comparator function to compare the string length. * @param {number | null} [limit=null] - An optional limit to compare the string length against. * @param {boolean} [throwErr=false] - If true, throws an error when comparison fails. If false, returns false. * @returns {boolean} `true` if the value is a string and meets the comparator and limit conditions, otherwise `false`. * @throws {Error} Throws an error if the comparison fails and throwError is true. */functionisString(v: unknown,comparator: Comparator|null=null,limit: number|null=null,throwErr: boolean=false): v is string{}/** * Checks if the provided value is a symbol. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not symbol. If false, returns false. * @returns {boolean} True if the value is a symbol, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a symbol and throwErr is true. */functionisSymbol(v: unknown,throwErr: boolean=false): v is symbol{}/** * Checks if the given value is `null` or `undefined`. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not null or undefined. If false, returns false. * @returns `true` if the value is `null` or `undefined`, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not null or undefined and throwErr is true. */functionisNil(v: unknown,throwErr: boolean=false): v is null|undefined{}/** * Checks if the given value is `null`. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not null. If false, returns false. * @returns `true` if the value is `null`, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not null and throwErr is true. */functionisNull(v: unknown,throwErr: boolean=false): v is null{}/** * Checks if the given value is `undefined`. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not undefined. If false, returns false. * @returns `true` if the value is `undefined`, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not undefined and throwErr is true. */functionisUndefined(v: unknown,throwErr: boolean=false): v is undefined{}Usage example for isString method:
import{isString}from"@dwtechs/checkard";conststr='dog';if(isString(str)){// check if str is a string}if(isString(str,'!0')){// check if str is not empty}if(isString(str,'0')){// check if str is empty}if(isString(str,'=',2)){// check if str is a string of length 2}if(isString(str,'>=',1)){// check if str is a string of length greater than or equal to 1}If isString() returns false, Typescript will consider str is not a string.
So if you need to check if str is of length x but needs to be considered as a string even if its length is not x you should do it like this:
import{isString,isStringOfLength}from"@dwtechs/checkard";conststr='dog';if(isString(str)&&!isStringOfLength(str,4,4)){// string is of type string even if length is not 4}Non-primitive methods accept any variable as parameter in order to check its type.
/** * Checks if the given value is an object and optionally if it is non-empty. * * @template T - The expected type of the object. * @param {unknown} v - The value to check. * @param {boolean} [empty=false] - If true, the function will also check if the object is non-empty. * @param {boolean} [throwErr=false] - If true, throws an error when value is not an object. If false, returns false. * @returns {v is object & T} - Returns true if the value is an object (and non-empty if specified), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an object and throwErr is true. */functionisObject<T=unknown>(v: unknown,empty=false,throwErr: boolean=false): v is object&T{}/** * Checks if the given value is an array and optionally compares its length. * * @template T - The type of elements in the array. * @param {unknown} v - The value to check. * @param {Comparator | null} [comparator=null] - An optional comparator function to compare the array length. * @param {number | null} [limit=null] - An optional limit to compare the array length against. * @param {boolean} [throwErr=false] - If true, throws an error when comparison fails. If false, returns false. * @returns {boolean} `true` if the value is an array and meets the comparator and limit conditions, otherwise `false`. * @throws {Error} Throws an error if the comparison fails and throwError is true. */functionisArray<T=unknown>(v: unknown,comparator: Comparator|null=null,limit: number|null=null,throwErr: boolean=false): v is T[]{}/** * Checks if the given input is a valid JSON string. * * @param {unknown} v - The input to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not valid JSON. If false, returns false. * @returns {boolean} `true` if the input is a valid JSON string, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not valid JSON and throwErr is true. */functionisJson(v: unknown,throwErr: boolean=false): v is JSON{}/** * Checks if the given value is a regular expression. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - If true, uses `instanceof` to check if `v` is a RegExp. If false, attempts to create a new RegExp from `v`. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a RegExp. If false, returns false. * @returns {boolean} `true` if `v` is a RegExp or can be converted to a RegExp, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a RegExp and throwErr is true. */functionisRegex(v: unknown,type=true,throwErr: boolean=false): v is RegExp{}/** * Checks if the given value is a valid Date object. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid Date. If false, returns false. * @returns {boolean} True if the value is a Date object and not NaN, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid Date and throwErr is true. */functionisDate(v: unknown,throwErr: boolean=false): v is Date{}/** * Checks if the provided value is a function. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a function. If false, returns false. * @returns {boolean} A boolean indicating whether the value is a function, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a function and throwErr is true. */functionisFunction(v: unknown,throwErr: boolean=false): v is (...args: unknown[])=>unknown{}Usage example for isArray method:
import{isArray}from"@dwtechs/checkard";letarr=['dog','cat','bird'];if(isArray(arr)){// check if arr is an array}if(isArray(arr,'!0')){// arr is not empty}if(isArray(arr,'=',2)){// arr is an array of length 2}if(isArray(arr,'>=',1)){// arr is an array of length greater than or equal to 1}Note that if isArray() returns false Typescript will consider arr is not an array.
So if you need to check arr is of length x but needs to be considered as an array even if its length is not x you can do it like this:
import{isArray,isArrayOfLength}from"@dwtechs/checkard";letarr=['dog','cat','bird'];if(isArray(arr)&&!isArrayOfLength(arr,4,4)){// array is of type array even if length is not 4}/** * Checks if a value is falsy. * * A value is considered falsy if it is : * false, * 0, * -0, * "", * null, * undefined, * NaN. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not falsy. If false, returns false. * @returns {boolean} `true` if the value is falsy, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not falsy and throwErr is true. */functionisFalsy(v: unknown,throwErr: boolean=false): boolean{}/** * Checks if a value is truthy. * * true: The boolean value true. * Non-zero numbers: Any number other than 0 or -0. * Non-empty strings: Any string with at least one character. * Objects: Any object, including empty objects and arrays. * Symbols: Any symbol. * BigInt values: Any BigInt value other than 0n. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not truthy. If false, returns false. * @returns {boolean} `true` if the value is truthy, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not truthy and throwErr is true. */functionisTruthy(v: unknown,throwErr: boolean=false): boolean{}/** * Checks if a given number is an integer. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not an integer. If false, returns false. * @returns {boolean} A boolean indicating whether the number is an integer (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an integer and throwErr is true. */functionisInteger<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is a floating-point number. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a float. If false, returns false. * @returns {boolean} A boolean indicating whether the number is a floating-point number (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a floating-point number and throwErr is true. */functionisFloat<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is even. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not an even number. If false, returns false. * @returns {boolean} A boolean indicating whether the number is even (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an even number and throwErr is true. */functionisEven<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Determines if a given number is odd. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not an odd number. If false, returns false. * @returns {boolean} A boolean indicating whether the number is odd (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an odd number and throwErr is true. */functionisOdd<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is zero. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not zero. If false, returns false. * @returns {boolean} A boolean indicating whether the number is zero (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not zero and throwErr is true. */functionisOrigin<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is positive. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not positive. If false, returns false. * @returns {boolean} A boolean indicating whether the number is positive (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not positive and throwErr is true. */functionisPositive<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is negative. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not negative. If false, returns false. * @returns {boolean} A boolean indicating whether the number is negative (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not negative and throwErr is true. */functionisNegative<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is a power of two. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - A boolean indicating whether to use strict equality (===) or loose equality (==) for the comparison. Defaults to true (strict equality). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a power of two. If false, returns false. * @returns {boolean} A boolean indicating whether the number is a power of two (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a power of two and throwErr is true. */functionisPowerOfTwo<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given number is an ASCII code. * * @param {unknown} v - The value to check. * @param {boolean} [ext=true] - Optional boolean to include extended ASCII range (0-255) or not. Defaults to true. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid ASCII code. If false, returns false. * @returns {boolean} A boolean indicating whether the number is a valid ASCII code (number|string), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid ASCII code and throwErr is true. */functionisAscii(v: unknown,ext=true,throwErr: boolean=false): v is number|string{}Valid number methods take a number as parameter and check of the number lies in the right interval
/** * Checks if a given value is a valid number within given range. * Performs internal number validation using isNumber() before checking range. * * @param {unknown} v - The value to check (performs internal number validation). * @param {number} [min=-999999999] - minimal value of the range * @param {number} [max=999999999] - maximal value of the range * @param {boolean} [type=true] - do type check * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid number in range. If false, returns false. * @returns {boolean} true if the value is a valid number within the specified range, false if not (when throwErr is false) * @throws {Error} Throws an error if the value is not a valid number or not within the specified range and throwErr is true. */functionisValidNumber(v: unknown,min=minNum,max=maxNum,type=true,throwErr: boolean=false): v is number{}/** * Checks if a given value is a valid integer within given range. * Performs internal integer validation using isInteger() before checking range. * * @param {unknown} v - The value to check (performs internal integer validation). * @param {number} [min=-999999999] - minimal value of the range * @param {number} [max=999999999] - maximal value of the range * @param {boolean} [type=true] - do type check * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid integer in range. If false, returns false. * @returns {boolean} true if the value is a valid integer within the specified range, false if not (when throwErr is false) * @throws {Error} Throws an error if the value is not a valid integer or not within the specified range and throwErr is true. */functionisValidInteger<Textendsboolean=true>(v: unknown,min: number=minNum,max: number=maxNum,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if a given value is a valid float within given range. * Performs internal float validation using isFloat() before checking range. * * @param {unknown} v - The value to check (performs internal float validation). * @param {number} [min=-999999999.9] - minimal value of the range * @param {number} [max=999999999.9] - maximal value of the range * @param {boolean} [type=true] - do type check * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid float in range. If false, returns false. * @returns {boolean} A boolean indicating whether the number is a valid float (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid float in range and throwErr is true. */functionisValidFloat<Textendsboolean=true>(v: unknown,min: number=minFloat,max: number=maxFloat,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if the length of a given string is within the specified range. * Performs internal string validation using isString() before checking email format * * @param {unknown} v - The value to check (performs internal string validation). * @param {number} [min=0] - The minimum length of the string (inclusive). Falls back to 0 if not a valid number (e.g. null, undefined, NaN). * @param {number} [max=999999999] - The maximum length of the string (inclusive). Falls back to 999999999 if not a valid number (e.g. null, undefined, NaN). * @param {boolean} [throwErr=false] - If true, throws an error when string length is not within range. If false, returns false. * @returns {boolean} `true` if the value is a string and its length is within the specified range, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a string and its length is not within the specified range and throwErr is true. */functionisStringOfLength(v: unknown,min: number=0,max: number=999999999,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid email address. * Performs internal string validation using isString() before checking email format. * * @param {unknown} v - The value to be checked (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid email. If false, returns false. * @returns {boolean} `true` if the value a valid email address, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid email address and throwErr is true. */functionisEmail(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid IP address. * Performs internal string validation using isString() before checking IP address format. * * @param {unknown} v - The value to be checked (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid IP address. If false, returns false. * @returns {boolean} `true` if the value is a valid IP address, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid IP address and throwErr is true. */functionisIpAddress(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if a given value is a valid Base64 encoded string. * Performs internal string validation using isString() before checking Base64 format. * * @param {unknown} v - The value to check (performs internal string validation). * @param {boolean} [urlEncoded=false] - Optional. If true, checks for URL-safe Base64 encoding. Defaults to false. * @param {boolean} [throwErr=false] - If true, throws an error when value is not valid Base64. If false, returns false. * @returns {boolean} True if the value is a valid Base64 encoded string, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid Base64 and throwErr is true. */functionisBase64(v: unknown,urlEncoded=false,throwErr: boolean=false): v is string{}/** * Checks if a given value is a valid JSON Web Token (JWT). * Performs internal string validation using isString() before checking JWT format. * * A valid JWT consists of three parts separated by dots ('.'): * - Header * - Payload * - Signature * * Each part must be a valid Base64 encoded string. Additionally, the header and payload * must be valid JSON objects when decoded. * * @param {unknown} v - The value to check (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid JWT. If false, returns false. * @returns {boolean} `true` if the value is a valid JWT, false if not (when throwErr is false). * @throws {Error} Throws an error if the value not a valid JWT and throwErr is true. */functionisJWT(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid slug. * Performs internal string validation using isString() before checking slug format. * * A slug is typically a URL-friendly string that contains only lowercase letters, numbers, and hyphens. * * @param {unknown} v - The value to check (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid slug. If false, returns false. * @returns {boolean} `true` if the value is a valid slug, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid slug and throwErr is true. */functionisSlug(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid hexadecimal format. * Performs internal string validation using isString() before checking hexadecimal format. * * @param {unknown} v - The value to check (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid hexadecimal format. If false, returns false. * @returns {boolean} True if the value is a valid hexadecimal format, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid hexadecimal format and throwErr is true. */functionisHexadecimal(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid ANSI escape code. * Performs internal string validation using isString() before checking ANSI format. * * @param {unknown} v - The value to be checked (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid ANSI escape code. If false, returns false. * @returns {boolean} `true` if the value is a valid ANSI escape code, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid ANSI escape code and throwErr is true. */functionisAnsiEscapeCode(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a valid locale format. * Performs internal string validation using isString() before checking locale format. * * @param {unknown} v - The value to be checked (performs internal string validation). * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid locale format. If false, returns false. * @returns {boolean} `true` if the value is a valid locale format, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid locale format and throwErr is true. */functionisLocale(v: unknown,ext: boolean=false,throwErr: boolean=false): v is string{}constPwdDefaultOptions={lowerCase: true,upperCase: true,number: true,specialCharacter: true,minLength: 12,maxLength: 64,};/** * @deprecated ⚠️ This function will be removed in v4.0.0. Use @dwtechs/passken validation function instead. * * Checks if a given password string meets the specified validation criteria. * * @param {string} s - The password string to validate. * @param {PasswordOptions} [options=defaultOptions] - Optional configuration object to specify password validation criteria. * @param {boolean} [throwErr=false] - If true, throws an error when password does not meet criteria. If false, returns false. * @returns {boolean} `true` if the password meets all the specified criteria, false if not (when throwErr is false). * @throws {Error} Throws an error if the password does not meet the specified criteria and throwErr is true. * * @example * ```typescript * const options = { * minLength: 8, * maxLength: 20, * lowerCase: true, * upperCase: true, * number: true, * specialCharacter: true * }; * const isValid = isValidPassword('Password123!', options); * console.log(isValid); // true * ``` */functionisValidPassword(s: string,options: PasswordOptions=defaultOptions,throwErr: boolean=false): boolean{}/** * Checks if the given string contains any uppercase letters. * * @param {string} s - The string to check. * @param {boolean} [throwErr=false] - If true, throws an error when string does not contain uppercase letters. If false, returns false. * @returns {boolean} `true` if the string contains at least one uppercase letter, false if not (when throwErr is false). * @throws {Error} Throws an error if the string does not contain uppercase letters and throwErr is true. */functioncontainsUpperCase(s: string,throwErr: boolean=false): boolean{}/** * Checks if the given string contains at least one lowercase letter. * * @param {string} s - The string to check. * @param {boolean} [throwErr=false] - If true, throws an error when string does not contain lowercase letters. If false, returns false. * @returns {boolean} `true` if the string contains at least one lowercase letter, false if not (when throwErr is false). * @throws {Error} Throws an error if the string does not contain lowercase letters and throwErr is true. */functioncontainsLowerCase(s: string,throwErr: boolean=false): boolean{}/** * Checks if the given string contains any special characters. * * @param {string} s - The string to be checked. * @param {boolean} [throwErr=false] - If true, throws an error when string does not contain special characters. If false, returns false. * @returns {boolean} `true` if the string contains special characters, false if not (when throwErr is false). * @throws {Error} Throws an error if the string does not contain special characters and throwErr is true. */functioncontainsSpecialCharacter(s: string,throwErr: boolean=false): boolean{}/** * Checks if a given string contains a specified number of digits. * * @param {string} s - The string to check. * @param {number} [min=1] - The minimum number of digits required in the string. Defaults to 1. * @param {number|null} [max=null] - The maximum number of digits allowed in the string. If not provided, there is no upper limit. * @param {boolean} [throwErr=false] - If true, throws an error when string does not contain the required number of digits. If false, returns false. * @returns {boolean} `true` if the string contains the required number of digits, false if not (when throwErr is false). * @throws {Error} Throws an error if the string does not contain the required number of digits and throwErr is true. */functioncontainsNumber(s: string,min=1,max: number|null=null,throwErr: boolean=false): boolean{}Usage example for isValidPassword:
import{isValidPassword}from"@dwtechs/checkard";constPwdOptions={lowerCase: true,upperCase: true,number: true,specialCharacter: false,minLength: 12,maxLength: 16,};constpassword='teSt1234';if(isValidPassword(password,PwdOptions)){// check if password is valid compared to PwdOptions}constminDate=newDate('1/1/1900');constmaxDate=newDate('1/1/2200');/** * Checks if a given date is valid within a specified range. * * @param {unknown} v - The value to be validated (performs internal date validation). * @param {Date | number} [min=minDate] - The minimum allowable date (Date object or timestamp). Defaults to `minDate`. * @param {Date | number} [max=maxDate] - The maximum allowable date (Date object or timestamp). Defaults to `maxDate`. * @param {boolean} [throwErr=false] - If true, throws an error when date is not valid. If false, returns false. * @returns {boolean} `true` if the value is a valid date within the specified range, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid date or not within the specified range and throwErr is true. */functionisValidDate(v: unknown,min: Date|number=minDate,max: Date|number=maxDate,throwErr: boolean=false): v is Date{}/** * Checks if the given value is a valid timestamp. * * @param {unknown} v - The value to check. * @param {boolean} [type=true] - An optional boolean parameter to verify the type of v. Defaults to true. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid timestamp. If false, returns false. * @returns {boolean} A boolean indicating whether the value is a timestamp, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid timestamp and throwErr is true. */functionisTimestamp<Textendsboolean=true>(v: unknown,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}constminTs=-2208989361000;// 1/1/1900constmaxTs=7258114800000;// 1/1/2200/** * Checks if a given timestamp is valid within a specified range. * * @param {unknown} v - The value to check. * @param {Date | number} [min=minTs] - The minimum allowed timestamp (Date object or timestamp). Defaults to `minTs`. * @param {Date | number} [max=maxTs] - The maximum allowed timestamp (Date object or timestamp). Defaults to `maxTs`. * @param {boolean} [type=true] - A boolean indicating the type of timestamp (default is true). * @param {boolean} [throwErr=false] - If true, throws an error when timestamp is not valid. If false, returns false. * @returns {boolean} A boolean indicating whether the value is a valid timestamp (or number|string if type=false), false if not (when throwErr is false). * @throws {Error} Throws an error if the timestamp is not valid and throwErr is true. */functionisValidTimestamp<Textendsboolean=true>(v: unknown,min: Date|number=minTs,max: Date|number=maxTs,type: T=trueasT,throwErr: boolean=false): v is Textendstrue ? number : number|string{}/** * Checks if the length of an array is within the specified range. * Performs internal array validation using isArray() before checking length. * * @template T - The type of elements in the array. * @param {unknown} v - The value to check (performs internal array validation). * @param {number} [min=0] - The minimum length of the array (inclusive). Falls back to 0 if not a valid number (e.g. null, undefined, NaN). * @param {number} [max=999999999] - The maximum length of the array (inclusive). Falls back to 999999999 if not a valid number (e.g. null, undefined, NaN). * @param {boolean} [throwErr=false] - If true, throws an error when array length is not within range. If false, returns false. * @returns {boolean} - Returns `true` if the value is an array and its length is within the specified range, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an array or its length is not within the specified range and throwErr is true. */functionisArrayOfLength<T=unknown>(v: unknown,min: number=0,max: number=999999999,throwErr: boolean=false): v is T[]{}/** * Checks if a value is present in an array starting from a specified index. * * @param {unknown[]} a - The array to search within. * @param {unknown} v - The value to search for. * @param {number} [from=0] - The index to start the search from. Defaults to 0. * @param {boolean} [throwErr=false] - If true, throws an error when value is not found in array. If false, returns false. * @returns {boolean} `true` if the value is found in the array, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not found in the array and throwErr is true. */functionisIn(a: unknown[],v: unknown,from=0,throwErr: boolean=false): boolean{}Usage example :
import{isIn}from"@dwtechs/checkard";// an array of restricted valuesconstlevels=["error","warn","info","debug"];// Basic usage : console.log(isIn("debug",levels));// trueconsole.log(isIn("debag",levels));// false// Typical usage : constdefaultLvl="warn";functionsetLevel(level: Levels): Levels{returnisIn(level,levels) ? level : defaultLvl;}letlvl=setLevel("error");// lvl = "error"letlvl=setLevel("infos");// lvl = "warn"/** * Checks if a given property exists on an object. * Performs internal object validation using isObject() before checking property. * own: boolean - whether to check inherited properties only * enumerable: boolean - whether to check enumerable properties only * * @template K - The type of the property key. * @param {unknown} v - The value to check the property on (performs internal object validation). * @param {K} k - The property key to check for. * @param {boolean} [own=true] - If true, checks if the property is an own property of the object. Defaults to true. * @param {boolean} [enumerable=true] - If true, checks if the property is enumerable. Defaults to true. * @param {boolean} [throwErr=false] - If true, throws an error when property doesn't exist. If false, returns false. * @returns {boolean} True if the value is an object and the property exists based on the specified conditions, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an object or the property doesn't exist and throwErr is true. */functionisProperty<KextendsPropertyKey>(v: unknown,k: K,own=true,enumerable=true,throwErr: boolean=false): v is Record<K,unknown>{}Usage example :
import{isProperty}from"@dwtechs/checkard";// an object to describe the custom type.constlevels={error: 0,warn: 1,info: 2,debug: 3,};// Basic usage : console.log(isProperty("debug",levels));// trueconsole.log(isProperty("debag",levels));// false/** * Checks if the given value is an HTML element. * * This function determines if the provided value is an instance of `HTMLElement`. * It first checks if `HTMLElement` is defined as an object and then verifies if * the value is an instance of `HTMLElement`. If `HTMLElement` is not defined, * it falls back to checking if the value is an object with a `nodeType` of 1 * and a `nodeName` of type string, which are characteristics of HTML elements. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not an HTML element. If false, returns false. * @returns {boolean} `true` if the value is an HTML element, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not an HTML element and throwErr is true. */functionisHtmlElement(v: unknown,throwErr: boolean=false): v is HTMLElement{}/** * Checks if a given string is a valid HTML event attribute. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a valid HTML event attribute. If false, returns false. * @returns {boolean} `true` if the string is a valid HTML event attribute, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a valid HTML event attribute and throwErr is true. * * @remarks * This function checks against a predefined list of HTML event attributes such as `onclick`, `onload`, `onerror`, etc. * * @example * ```typescript * isHtmlEventAttribute("onclick"); // returns true * isHtmlEventAttribute("onunknown"); // returns false * ``` */functionisHtmlEventAttribute(v: unknown,throwErr: boolean=false): v is string{}/** * Checks if the given value is a DOM Node. * * This function determines if the provided value is a Node by checking its type and properties. * It works by verifying if the value is an instance of Node when `Node` is an object, or by * checking the presence and types of `nodeType` and `nodeName` properties. * * @param {unknown} v - The value to check. * @param {boolean} [throwErr=false] - If true, throws an error when value is not a DOM Node. If false, returns false. * @returns {boolean} `true` if the value is a Node, false if not (when throwErr is false). * @throws {Error} Throws an error if the value is not a DOM Node and throwErr is true. */functionisNode(v: unknown,throwErr: boolean=false): v is Node{}/** * A function to capitalize the first letter of each word in a string. * * @param {string} s - The input string to capitalize. * @param {boolean} everyWords - A flag to indicate whether to capitalize every word or just the first letter of the whole string. * @return {string} The string with the first letter of each word capitalized. */functionucfirst(s: string,everyWords=true): string{}/** * Returns a normalized nickname for a user. * * If the nickname is not given, the function will create a nickname * based on the first letter of the first name and the last name. * * nickname accepts a-z - and _ characters * * @param {string} nickname - The nickname of the user. * @param {string} firstName - The first name of the user. * @param {string} lastName - The last name of the user. * @param {boolean} [throwErr=false] - If true, throws an error when normalization fails. If false, returns false. * @return {string | false} The normalized nickname, or false if normalization fails (when throwErr is false). * @throws {Error} Throws an error if normalization fails and throwErr is true. */functionnormalizeNickname(nickname: string,firstName: string,lastName: string,throwErr: boolean=false): string|false{}/** * Normalizes a first name by capitalizing the first letter of each word. * * @param {string} s - The first name to normalize. * @param {boolean} [throwErr=false] - If true, throws an error when normalization fails. If false, returns false. * @return {string | false} The normalized first name, or false if normalization fails (when throwErr is false). * @throws {Error} Throws an error if normalization fails and throwErr is true. */functionnormalizeName(s: string,throwErr: boolean=false): string|false{}/** * A function to normalize an email address. * * If the string is not a valid email address, the function will return false. * * @param {string} s - The email address to normalize. * @param {boolean} [throwErr=false] - If true, throws an error when normalization fails. If false, returns false. * @return {string | false} The normalized email address, or false if normalization fails (when throwErr is false). * @throws {Error} Throws an error if normalization fails and throwErr is true. */functionnormalizeEmail(s: string,throwErr: boolean=false): string|false{}Example :
constch=require("@dwtechs/checkard");functionnormalizeInputs(req,res,next){constusers=req.body.rows;log.debug(`Normalize values for ${users.length} users`);for(constuofusers){const{ firstName, lastName, nickname, email }=u;u.firstname=ch.normalizeName(firstName);u.lastname=ch.normalizeName(lastName);u.nickname=ch.normalizeNickname(nickname,firstName,lastName);u.email=ch.normalizeName(email);}next();}Checkard.js is under continuous development and we would be glad to get all the help you can provide. To contribute please read contributor.md for detailed installation guide.
| Purpose | Choice | Motivation |
|---|---|---|
| repository | Github | hosting for software development version control using Git |
| package manager | npm | default node.js package manager |
| language | TypeScript | static type checking along with the latest ECMAScript features |
| module bundler | Rollup | advanced module bundler for ES6 modules |
| unit testing | Jest | delightful testing with a focus on simplicity |