@dwtechs/checkard

• 概要
• 支助
• 安装
• 使用量
  • ES6 标准
  • 常见JS
  • IIFE (英语)
• API 参考
• 贡献者
• 堆栈

概要

Checkard.js (英语) 是一个开源动态类型,用于检查 Javascript, Typescript和 Node.js 的库,以测试某个变量是否是它应该是什么( ) 函数,对象, ASCii, 布尔, 整数, 字符串, json, 电子邮件... )

• 无依赖性
• 极轻重量
• 用超过3724个单位测试进行彻底测试
• 作为EcmaScrypt模块、通用JS模块和IIFE装运
• QQ 用打字符写成
• QQ 旧浏览器支持
• 在 Javascript、 Typescript 和 Node.js 中工作

支助

• 机器人: 2.2,
• 铬: 34,
• 边缘: 12,
• firefox: 11, (英语),
• ie: 9, (英语),
• 欧斯:4.2,
• 歌剧: 28,
• 萨法里: 5.1,
• 相声: 4,
• 节点.js:16

这是最古老的目标版本。 图书馆应该妥善处理旧设备,但我们不正式支持.

安装

$ npm i @dwtechs/checkard

使用量

ES6 / 类型脚本

import { 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
}

常见JS

const ch = 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
}

IIFE (英语)

<script src="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
}

API 参考

类型

type Comparator = '='|'<'|'>'|'<='|'>='|'!='|'!0'|'0';

type PasswordOptions = {
  lowerCase: boolean,
  upperCase: boolean,
  number: boolean,
  specialCharacter: boolean,
  maxLength: number,
  minLength: number
}

初级

原始方法接受任何变量作为参数来检查其类型.

/**
 * 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.
 */
function isBoolean(
  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.
 */
function isNumber<T extends boolean = true>(
  v: unknown, 
  type: T = true as T,
  comparator: Comparator | null = null, 
  limit: number | null = null,
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isString(
  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.
 */
function isSymbol(
  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.
 */
function isNil(
  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.
 */
function isNull(
  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.
 */
function isUndefined(
  v: unknown, 
  throwErr: boolean = false
): v is undefined {}

IsString 方法的使用实例 :

import { isString } from "@dwtechs/checkard";

const str = '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
}

说明

若为 正弦 () 返回虚假, 类型标记将考虑 字符串 不是一个字符串.
所以,如果你需要检查 字符串 长度为 x 但需要被视为字符串, 即使其长度不是 x 。 您应该这样做 :

import { isString, isStringOfLength } from "@dwtechs/checkard";

const str = 'dog';

if (isString(str) && !isStringOfLength(str, 4, 4)) {
  // string is of type string even if length is not 4
}

非原始内容

非原始方法接受任何变量作为参数来检查其类型.

/**
 * 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.
 */
function isObject<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.
 */
function isArray<T = unknown>(
  v: unknown, 
  comparator: Comparator | null = null, 
  limit: number | null = null,
  throwErr: boolean = false
): v is T[] {}

/**
 * Checks if the given value is a Set and optionally compares its size.
 *
 * @template T - The type of elements in the Set.
 * @param {unknown} v - The value to check.
 * @param {Comparator | null} [comparator=null] - An optional comparator function to compare the Set size.
 * @param {number | null} [limit=null] - An optional limit to compare the Set size against.
 * @param {boolean} [throwErr=false] - If true, throws an error when value is not a Set or comparison fails. If false, returns false.
 * @returns {boolean} `true` if the value is a Set and meets the comparator and limit conditions, otherwise `false`.
 * @throws {Error} Throws an error if the value is not a Set or the comparison fails and throwErr is true.
 */
function isSet<T = unknown>(
  v: unknown, 
  comparator: Comparator | null = null, 
  limit: number | null = null,
  throwErr: boolean = false
): v is Set<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.
 */
function isJson(
  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.
 */
function isRegex(
  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.
 */
function isDate(
  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.
 */
function isFunction(
  v: unknown, 
  throwErr: boolean = false
): v is (...args: unknown[]) => unknown {}

用于Array 方法的例子 :

import { isArray } from "@dwtechs/checkard";

let arr = ['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
}

说明

注意,如果 是箭头 () 返回虚伪的打字符将考虑 错误 不是一个数组.
所以,如果你需要检查 错误 长度为x,但需要被视为一个数组,即使长度不是x,您也可以这样做:

import { isArray, isArrayOfLength } from "@dwtechs/checkard";

let arr = ['dog','cat','bird'];

if (isArray(arr) && !isArrayOfLength(arr, 4, 4)) {
  // array is of type array even if length is not 4
}

IsSet 方法的使用示例 :

import { isSet } from "@dwtechs/checkard";

let s = new Set(['dog','cat','bird']);

if (isSet(s)) {
  // check if s is a Set
}

if (isSet(s, '!0')) {
  // s is not empty
}

if (isSet(s, '=', 2)) {
  // s is a Set of size 2
}

if (isSet(s, '>=', 1)) {
  // s is a Set of size greater than or equal to 1
}

布尔

/**
 * 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.
 */
function isFalsy(
  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.
 */
function isTruthy(
  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.
 */
function isInteger<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isFloat<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isEven<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isOdd<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isOrigin<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isPositive<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isNegative<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isPowerOfTwo<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isAscii(
  v: unknown, 
  ext = true, 
  throwErr: boolean = false
): v is number | string {}

有效号码

有效数字方法将数字作为参数, 并检查数字位于正确的间隔

/**
 * 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.
 */
function isValidNumber( 
  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.
 */
function isValidInteger<T extends boolean = true>(
  v: unknown, 
  min: number = minNum, 
  max: number = maxNum,
  type: T = true as T,
  throwErr: boolean = false 
): v is T extends true ? 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.
 */
function isValidFloat<T extends boolean = true>(
  v: unknown,
  min: number = minFloat,
  max: number = maxFloat,
  type: T = true as T,
  throwErr: boolean = false 
): v is T extends true ? 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.
 */
function isStringOfLength(
  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.
 */
function isEmail(
  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.
 */
function isIpAddress(
  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.
 */
function isBase64(
  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.
 */
function isJWT(
  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.
 */
function isSlug(
  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.
 */
function isHexadecimal(
  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.
 */
function isAnsiEscapeCode(
  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.
 */
function isLocale(
  v: unknown, 
  ext: boolean = false, 
  throwErr: boolean = false
): v is string {}


const PwdDefaultOptions = {
  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
 * ```
 */
function isValidPassword(
  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.
 */
function containsUpperCase(
  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.
 */
function containsLowerCase(
  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.
 */
function containsSpecialCharacter(
  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.
 */
function containsNumber(
  s: string, 
  min = 1, 
  max: number|null = null, 
  throwErr: boolean = false
): boolean {}

用法例如: ValidPassword:

import { isValidPassword } from "@dwtechs/checkard";

const PwdOptions = {
  lowerCase: true,
  upperCase: true,
  number: true,
  specialCharacter: false,
  minLength: 12,
  maxLength: 16,
};
const password = 'teSt1234';

if (isValidPassword(password, PwdOptions)) {
  // check if password is valid compared to PwdOptions
}

日期

const minDate = new Date('1/1/1900');
const maxDate = new Date('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.
 */
function isValidDate(
  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.
 */
function isTimestamp<T extends boolean = true>(
  v: unknown, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? number : number | string {}

const minTs = -2208989361000; // 1/1/1900
const maxTs = 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.
 */
function isValidTimestamp<T extends boolean = true>(
  v: unknown, 
  min: Date | number = minTs, 
  max: Date | number = maxTs, 
  type: T = true as T, 
  throwErr: boolean = false
): v is T extends true ? 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.
 */
function isArrayOfLength<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.
 */
function isIn(
  a: unknown[], 
  v: unknown, 
  from = 0, 
  throwErr: boolean = false
): boolean {}

用法示例:

import { isIn } from "@dwtechs/checkard";

// an array of restricted values
const levels = [ "error", "warn", "info", "debug" ];

// Basic usage : 
console.log(isIn("debug", levels)); // true
console.log(isIn("debag", levels)); // false

// Typical usage : 
const defaultLvl = "warn";
function setLevel(level: Levels): Levels {
  return isIn(level, levels) ? level : defaultLvl;
}
let lvl = setLevel("error"); // lvl = "error"
let lvl = setLevel("infos"); // lvl = "warn"

设定

/**
 * Checks if the size of a Set is within the specified range.
 * Performs internal Set validation using isSet() before checking size.
 *
 * @template T - The type of elements in the Set.
 * @param {unknown} v - The value to check (performs internal Set validation).
 * @param {number} [min=0] - The minimum size of the Set (inclusive). Falls back to 0 if not a valid number (e.g. null, undefined, NaN).
 * @param {number} [max=999999999] - The maximum size of the Set (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 Set size is not within range. If false, returns false.
 * @returns {boolean} - Returns `true` if the value is a Set and its size is within the specified range, false if not (when throwErr is false).
 * @throws {Error} Throws an error if the value is not a Set or its size is not within the specified range and throwErr is true.
 */
function isSetOfLength<T = unknown>(
  v: unknown, 
  min: number = 0, 
  max: number = 999999999,
  throwErr: boolean = false
): v is Set<T> {}

用法示例:

import { isSet, isSetOfLength } from "@dwtechs/checkard";

let s = new Set(['dog','cat','bird']);

if (isSet(s) && !isSetOfLength(s, 4, 4)) {
  // s is of type Set even if size is not 4
}

对象

/**
 * 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.
 */
function isProperty<K extends PropertyKey>(
  v: unknown, 
  k: K, 
  own = true, 
  enumerable = true,
  throwErr: boolean = false
): v is Record<K, unknown> {}

用法示例:

import { isProperty } from "@dwtechs/checkard";

// an object to describe the custom type.
const levels = {
  error: 0,
  warn: 1,
  info: 2,
  debug: 3,
};

// Basic usage : 
console.log(isProperty("debug", levels)); // true
console.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.
 */
function isHtmlElement(
  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
 * ```
 */
function isHtmlEventAttribute(
  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.
 */
function isNode(
  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.
 */
function ucfirst(
  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.
 */
function normalizeNickname(
  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.
 */
function normalizeName(
  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.
 */
function normalizeEmail(
  s: string, 
  throwErr: boolean = false
): string | false {}

示例:

const ch = require("@dwtechs/checkard");

function normalizeInputs(req, res, next) {
  const users = req.body.rows;
  log.debug(`Normalize values for ${users.length} users`);

  for (const u of users) {
    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正在不断发展 我们很乐意得到所有你能提供的帮助. 捐款请改为 贡献者.md 详细安装指南.

堆栈