# @dwtechs/checkard 中文文档
规范地址：https://npmcn.com/package/%40dwtechs/checkard/
版本：3\.7\.0
npm 元数据更新时间：2026-09-12T06:29:26.934Z
中文译文更新时间：2026-11-13T01:37:47.014Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40dwtechs/checkard
原文对照：https://npmcn.com/package/%40dwtechs/checkard/?lang=original
项目主页：https://github.com/DWTechs/Checkard.js
源码仓库：https://github.com/DWTechs/Checkard.js
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：184 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：0 个
- 首次发布：2024-10-22T19:41:23.994Z
- 最新版本发布：2026-08-29T14:03:20.942Z
- 近 30 天下载量：6384（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 2 个）
## 中文简介
开源动态类型检查 Javascript, Typescript和 Node.js 的库,以测试一个给定的变量是否是它应该是什么 .
## 安装
```sh
npm install @dwtechs/checkard
```
也可以使用：`pnpm add @dwtechs/checkard`、`yarn add @dwtechs/checkard`、`bun add @dwtechs/checkard`
## README
[](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/@dwtechs/checkard) [](https://www.npmjs.com/package/@dwtechs/checkard) 
- [概要](https://npmcn.com/package/%40dwtechs/checkard/#readme-synopsis)
- [支助](https://npmcn.com/package/%40dwtechs/checkard/#readme-support)
- [安装](https://npmcn.com/package/%40dwtechs/checkard/#readme-installation)
- [使用量](https://npmcn.com/package/%40dwtechs/checkard/#readme-usage)
- [ES6 标准](https://npmcn.com/package/%40dwtechs/checkard/#readme-es6)
- [常见JS](https://npmcn.com/package/%40dwtechs/checkard/#readme-commonjs)
- [IIFE (英语)](https://npmcn.com/package/%40dwtechs/checkard/#readme-iife)
- [API 参考](https://npmcn.com/package/%40dwtechs/checkard/#readme-api-reference)
- [贡献者](https://npmcn.com/package/%40dwtechs/checkard/#readme-contributors)
- [堆栈](https://npmcn.com/package/%40dwtechs/checkard/#readme-stack)
## 概要
**[Checkard.js (英语)](https://github.com/DWTechs/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
这是最古老的目标版本。 图书馆应该妥善处理旧设备,但我们不正式支持.
## 安装
```bash
$ npm i @dwtechs/checkard
```
## 使用量
### ES6 / 类型脚本
```typescript
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
```javascript
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 (英语)
```html
```
```javascript
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 参考
### 类型
```javascript
type Comparator = '='|'<'|'>'|'<='|'>='|'!='|'!0'|'0';
type PasswordOptions = {
lowerCase: boolean,
upperCase: boolean,
number: boolean,
specialCharacter: boolean,
maxLength: number,
minLength: number
}
```
### 初级
* * *
原始方法接受任何变量作为参数来检查其类型.
```typescript
/**
* 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(
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 方法的使用实例 :
```javascript
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 。 您应该这样做 :
```javascript
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
}
```
### 非原始内容
* * *
非原始方法接受任何变量作为参数来检查其类型.
```typescript
/**
* 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(
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(
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(
v: unknown,
comparator: Comparator | null = null,
limit: number | null = null,
throwErr: boolean = false
): v is Set {}
/**
* 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 方法的例子 :
```typescript
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,您也可以这样做:
```javascript
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 方法的使用示例 :
```typescript
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
}
```
### 布尔
* * *
```typescript
/**
* 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 {}
```
### 数目
* * *
```typescript
/**
* 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(
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(
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(
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(
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(
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(
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(
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(
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 {}
```
### 有效号码
* * *
有效数字方法将数字作为参数, 并检查数字位于正确的间隔
```typescript
/**
* 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(
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(
v: unknown,
min: number = minFloat,
max: number = maxFloat,
type: T = true as T,
throwErr: boolean = false
): v is T extends true ? number : number | string {}
```
### 字符串
* * *
```typescript
/**
* 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:
```javascript
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
}
```
### 日期
* * *
```typescript
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(
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(
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 {}
```
### 阵列
* * *
```typescript
/**
* 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(
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 {}
```
用法示例:
```javascript
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"
```
### 设定
* * *
```typescript
/**
* 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(
v: unknown,
min: number = 0,
max: number = 999999999,
throwErr: boolean = false
): v is Set {}
```
用法示例:
```javascript
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
}
```
### 对象
* * *
```typescript
/**
* 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(
v: unknown,
k: K,
own = true,
enumerable = true,
throwErr: boolean = false
): v is Record {}
```
用法示例:
```javascript
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
```
### 电量
* * *
```typescript
/**
* 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 {}
```
### 规范化
* * *
```typescript
/**
* 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 {}
```
示例:
```javascript
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](https://github.com/DWTechs/Checkard.js/blob/main/contributor.md)** 详细安装指南.
## 堆栈
| 目的 | 选择 | 动机 |
| :-- | :-: | --: |
| 仓库 | [吉图布](https://github.com/) | 使用 Git 管理软件开发版本控制 |
| 软件包管理器 | [无](https://www.npmjs.com/get-npm) | 默认节点.js 软件包管理器 |
| 语言 | [类型脚本](https://www.typescriptlang.org/) | 静态类型检查与最新的 ECMAScript 特性 |
| 模块捆绑器 | [滚动](https://rollupjs.org/) | eS6模块高级模块捆绑器 |
| 单位测试 | [欢乐](https://jestjs.io/) | 以简单为重点进行令人愉快的测试 |
## 常见问题
### @dwtechs/checkard 是什么？
开源动态类型检查 Javascript, Typescript和 Node\.js 的库,以测试一个给定的变量是否是它应该是什么 \.
### 如何安装 @dwtechs/checkard？
在项目目录运行 npm install @dwtechs/checkard，或使用 pnpm add / yarn add / bun add。
### @dwtechs/checkard 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @dwtechs/checkard 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @dwtechs/checkard 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @dwtechs/checkard 可以商用吗？
@dwtechs/checkard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @dwtechs/checkard 的下载量有多少？
根据 npm 官方下载统计，@dwtechs/checkard 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,384 次，日均约 213 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @dwtechs/checkard 还在维护吗？
最新版本 3\.7\.0 发布于 2026/08/29（2 个月前）；至今共发布 22 个版本，其中过去 12 个月发布了 2 个；首次发布于 2024/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。