@txjs/bool

v1.0.6

Published

2 months ago

数据类型的校验工具，支持邮箱、手机号、URL、深度相等比较等

0High
0Medium
0Low

txjs

txjs bool boolean validation types is-type type-guard typescript

@txjs/bool

用于验证和判断数据类型的 TypeScript 函数库，支持 Node.js 和浏览器环境。

安装

# npm
npm i @txjs/bool

# pnpm
pnpm add @txjs/bool

# yarn
yarn add @txjs/bool

导入方式

// 导入全部函数
import { is, isNil, isNumber } from '@txjs/bool'

// 按需导入单个函数（优化打包体积）
import { isNil } from '@txjs/bool/dist/isNil'

函数列表

| 函数 | 说明 | |------|------| | is | 通用类型验证 | | toString | 任意值转字符串 | | isArray | 是否为数组 | | isBoolean | 是否为布尔值 | | isFunction | 是否为函数 | | isAsyncFunction | 是否为异步函数 | | isInteger | 是否为正整数（含 0） | | isNil | 是否为 null 或 undefined | | isNull | 是否为 null | | isNumber | 是否为数字（不含 NaN） | | isNumeric | 是否为数字或数字字符串 | | isString | 是否为字符串 | | isSymbol | 是否为 Symbol | | isUndefined | 是否为 undefined | | isDate | 是否为有效 Date 对象 | | isPromise | 是否为 Promise | | isPlainObject | 是否为普通对象（排除 null） | | isPhone | 是否为中国手机号（包含虚拟号段） | | isNonVirtualPhone | 是否为非虚拟手机号 | | isPhoneNumber | 是否为手机号（同 isPhone，已废弃） | | isLandline | 是否为座机号码 | | isEmail | 是否为邮箱格式 | | isHttpUrl | 是否为 HTTP/HTTPS URL | | isAbsoluteUrl | 是否为绝对 URL | | isURL | 是否为网址 URL（已废弃） | | isValidString | 是否为非空字符串（已废弃） | | isNonEmptyString | 是否为非空字符串 | | isNonEmptyObject | 是否为非空对象 | | isBlob | 是否为 Blob 对象 | | containsHTML | 是否包含 HTML 标签 | | notNil | 是否不为 null 或 undefined |

is

通用类型验证函数，通过 Object.prototype.toString 判断值的类型。

function is<T = boolean>(value: unknown, type: string): value is T

参数：

value - 要验证的值
type - 类型名称（如 'Array'、'Object'、'Number' 等）

示例：

// 基本类型判断
is(123, 'Number')           // => true
is('hello', 'String')       // => true
is(true, 'Boolean')         // => true
is(undefined, 'Undefined')   // => true
is(null, 'Null')            // => true

// 引用类型判断
is([], 'Array')             // => true
is({}, 'Object')            // => true
is(new Date(), 'Date')      // => true
is(Symbol('id'), 'Symbol')  // => true

// 错误类型判断
is('123', 'Number')         // => false
is({}, 'Array')             // => false

toString

将任意值转换为字符串，行为类似 String() 但使用 Object.prototype.toString 实现。

function toString(value: unknown): string

示例：

toString(123)              // => "123"
toString(true)             // => "true"
toString([1, 2, 3])        // => "1,2,3"
toString({ a: 1 })         // => "[object Object]"
toString(null)             // => "null"
toString(undefined)        // => "undefined"

isArray

检查值是否为数组类型。

function isArray<T>(value: T): value is T extends Array<any> ? T : never

示例：

isArray([])                // => true
isArray([1, 2, 3])         // => true
isArray(new Array())       // => true

isArray('abc')             // => false
isArray({})                // => false
isArray(null)              // => false

isBoolean

检查值是否为布尔类型。

function isBoolean(value: unknown): value is boolean

示例：

isBoolean(true)            // => true
isBoolean(false)            // => true

isBoolean(1)                // => false
isBoolean('true')           // => false
isBoolean(Boolean(true))    // => false (Boolean 返回对象，不是 boolean)

isFunction

检查值是否为函数类型。

function isFunction(value: unknown): value is (...args: any[]) => any

示例：

isFunction(() => {})                   // => true
isFunction(function () {})             // => true
isFunction(Math.max)                   // => true
isFunction(async function () {})        // => true

isFunction({})                         // => false
isFunction(null)                       // => false

isAsyncFunction

检查值是否为异步函数。

function isAsyncFunction(value: unknown): value is (...args: any[]) => Promise

示例：

const asyncFunc = async () => {}
isAsyncFunction(asyncFunc)             // => true

isAsyncFunction(() => {})              // => false
isAsyncFunction(function () {})        // => false

isInteger

检查值是否为正整数（含 0）。支持数字和数字字符串。

function isInteger(value: unknown): value is number

示例：

// 数字
isInteger(0)                // => true
isInteger(10)               // => true
isInteger(999)              // => true

// 数字字符串
isInteger('0')              // => true
isInteger('10')             // => true
isInteger('122')            // => true

// 非整数
isInteger(3.14)             // => false
isInteger(-10)              // => false
isInteger('3.14')           // => false
isInteger('abc')            // => false

isNil

检查值是否为 null 或 undefined。

function isNil(value: unknown): value is null | undefined

示例：

isNil(null)                 // => true
isNil(undefined)            // => true
isNil(void 0)               // => true

isNil(0)                    // => false
isNil('')                   // => false
isNil(false)                // => false
isNil({})                   // => false

isNull

检查值是否为 null。

function isNull(value: unknown): value is null

示例：

isNull(null)                // => true

isNull(undefined)           // => false
isNull(0)                   // => false
isNull('')                  // => false
isNull(false)               // => false

isNumber

检查值是否为数字类型（不包括 NaN）。

function isNumber(value: unknown): value is number

示例：

isNumber(0)                 // => true
isNumber(3)                 // => true
isNumber(3.14)              // => true
isNumber(-100)              // => true
isNumber(Infinity)          // => true

isNumber('3')               // => false
isNumber(NaN)               // => false
isNumber(null)              // => false

isNumeric

检查值是否为数字或数字字符串，常用于表单验证。

function isNumeric(value: unknown): value is number | string

示例：

isNumeric(3)                // => true
isNumeric(3.14)             // => true
isNumeric('3')              // => true
isNumeric('3.14')           // => true
isNumeric('100')            // => true

isNumeric('abc')            // => false
isNumeric('')               // => false
isNumeric(null)             // => false

isString

检查值是否为字符串类型。

function isString(value: unknown): value is string

示例：

isString('')                // => true
isString('hello')           // => true
isString('123')             // => true

isString(123)               // => false
isString(true)              // => false
isString(null)              // => false

isSymbol

检查值是否为 Symbol 类型。

function isSymbol(value: unknown): value is symbol

示例：

const key = Symbol('key')
isSymbol(key)               // => true
isSymbol(Symbol())           // => true

isSymbol('key')              // => false
isSymbol(123)                // => false

isUndefined

检查值是否为 undefined。

function isUndefined(value: unknown): value is undefined

示例：

isUndefined(undefined)       // => true
isUndefined(void 0)          // => true

isUndefined(null)            // => false
isUndefined(0)               // => false
isUndefined('')              // => false

isDate

检查值是否为有效的 Date 对象。

function isDate(value: unknown): value is Date

示例：

isDate(new Date())                      // => true
isDate(new Date('2023-06-12'))          // => true
isDate(new Date('invalid'))             // => false (Invalid Date)

isDate('2023-06-12')                    // => false (字符串)
isDate(123456)                          // => false (时间戳)

isPromise

检查值是否为 Promise 对象。

function isPromise<T>(value: T): value is T extends Promise<any> ? T : never

示例：

isPromise(Promise.resolve())            // => true
isPromise(new Promise(() => {}))        // => true

isPromise({ then: () => {} })           // => false (类似 Promise 的对象)
isPromise(() => {})                      // => false
isPromise(null)                          // => false

isPlainObject

检查值是否为普通对象（不包括 null），即通过 {} 或 new Object() 创建的对象。

function isPlainObject<T>(value: T): value is T extends Record<any, any> ? T : never

示例：

isPlainObject({})                       // => true
isPlainObject(new Object())             // => true
isPlainObject({ a: 1, b: 2 })           // => true

isPlainObject(null)                     // => false
isPlainObject([])                       // => false
isPlainObject(new Date())               // => false
isPlainObject(new Map())                 // => false

isPhone

检查值是否为有效的中国手机号码（包含虚拟号段 170/171/177/178/190）。

function isPhone(value: unknown): value is string

支持的号段：

13xxx - 139xxx（中国电信）
14xxx - 149xxx（中国移动）
15xxx - 153xxx（中国移动/电信）
16xxx - 166xxx（中国移动/联通/电信）
17xxx - 179xxx（中国移动/联通/电信/虚拟）
18xxx - 189xxx（中国移动/联通/电信）
19xxx - 199xxx（中国电信/移动/联通）

示例：

isPhone('13566667777')       // => true
isPhone('13812345678')       // => true
isPhone('19912345678')       // => true
isPhone('17012345678')       // => true (虚拟号段)
isPhone('17712345678')       // => true (虚拟号段)

isPhone('134666565')         // => false (位数不足)
isPhone('12345678901')       // => false (位数超限)
isPhone('abc')               // => false
isPhone(13566667777)         // => false (数字类型)

isNonVirtualPhone

检查值是否为非虚拟号段的中国手机号码，排除 170/171/177/178/190 开头的号码。

function isNonVirtualPhone(value: unknown): value is string

示例：

isNonVirtualPhone('13566667777')     // => true
isNonVirtualPhone('13987654321')     // => true
isNonVirtualPhone('13812345678')     // => true

isNonVirtualPhone('17012345678')     // => false (虚拟号段)
isNonVirtualPhone('17112345678')     // => false (虚拟号段)
isNonVirtualPhone('17712345678')     // => false (虚拟号段)
isNonVirtualPhone('17812345678')     // => false (虚拟号段)
isNonVirtualPhone('19012345678')     // => false (虚拟号段)

isPhoneNumber

检查值是否为手机号码，与 isPhone 功能相同。该函数已废弃，建议使用 isPhone。

function isPhoneNumber(value: unknown): value is string

isLandline

检查值是否为有效的座机号码，支持带区号和不带区号的格式。

function isLandline(value: unknown): value is string

支持的格式：

010-12345678 - 区号-号码
0592-5966633 - 3位区号-7/8位号码
0592-5966633-123 - 带分机号

示例：

isLandline('0592-5966633')           // => true
isLandline('0592-5966633-123')        // => true
isLandline('010-12345678')           // => true
isLandline('800-8888888')             // => true (400/800 客服电话)

isLandline('13215666')               // => false (位数不足)
isLandline('123-4567890')            // => false (格式不符)
isLandline('abc')                     // => false

isEmail

检查值是否为有效的邮箱地址。

function isEmail(value: unknown): boolean

支持的邮箱格式：

普通邮箱：[email protected]
带点号的邮箱：[email protected]
带加号的邮箱：[email protected]
带域名前缀的邮箱：[email protected]

示例：

isEmail('[email protected]')          // => true
isEmail('[email protected]')           // => true
isEmail('[email protected]')         // => true
isEmail('[email protected]') // => true

isEmail('example.com')                // => false (无 @)
isEmail('@example.com')               // => false (无用户名)
isEmail('[email protected]')                  // => false (域名格式错误)

isHttpUrl

检查值是否为以 http:// 或 https:// 开头的 URL。

function isHttpUrl(value: unknown): value is string

示例：

isHttpUrl('http://example.com')       // => true
isHttpUrl('https://example.com')      // => true
isHttpUrl('https://example.com/path')  // => true

isHttpUrl('ftp://example.com')        // => false
isHttpUrl('www.example.com')          // => false
isHttpUrl('/path/to/resource')        // => false

isAbsoluteUrl

检查值是否为绝对 URL（包含协议前缀）。

function isAbsoluteUrl(value: unknown): boolean

示例：

isAbsoluteUrl('https://www.example.com')  // => true
isAbsoluteUrl('http://example.com')       // => true
isAbsoluteUrl('file:///path/to/file')     // => true
isAbsoluteUrl('ftp://ftp.example.com')    // => true

isAbsoluteUrl('www.example.com')          // => false
isAbsoluteUrl('/path/to/resource')        // => false
isAbsoluteUrl('./local/path')             // => false
isAbsoluteUrl('c:\\path\\to\\file')       // => false (Windows 路径)

isURL

检查值是否为有效的网址 URL。该函数已废弃，建议使用 isHttpUrl 或 isAbsoluteUrl。

function isURL(value: unknown): value is string

isValidString

检查值是否为非空字符串（不含纯空白）。该函数已废弃，建议使用 isNonEmptyString。

function isValidString(value: unknown): value is string

isNonEmptyString

检查值是否为非空字符串。空白字符会被 trim() 后再判断。

function isNonEmptyString(value: unknown): value is string

示例：

isNonEmptyString('hello')             // => true
isNonEmptyString('  hello  ')         // => true (首尾空白会被 trim)

isNonEmptyString('')                  // => false
isNonEmptyString('   ')               // => false (纯空白)
isNonEmptyString(null)                // => false

isNonEmptyObject

检查值是否为非空对象。

function isNonEmptyObject<T>(value: T): value is T extends Record<any, any> ? T : never

示例：

isNonEmptyObject({ a: 1 })            // => true
isNonEmptyObject({ name: 'test' })    // => true

isNonEmptyObject({})                  // => false
isNonEmptyObject(null)                // => false
isNonEmptyObject([])                  // => false

isBlob

检查值是否为 Blob 对象。

function isBlob(value: unknown): value is Blob

示例：

isBlob(new Blob())                     // => true
isBlob(new Blob(['hello'], { type: 'text/plain' })) // => true

isBlob({})                            // => false
isBlob(null)                          // => false
isBlob('blob')                         // => false

containsHTML

检查字符串值是否包含 HTML 标签。

function containsHTML(value: unknown): value is string

示例：

containsHTML('<div>Test</div>')               // => true
containsHTML('<img src="image.jpg" />')        // => true
containsHTML('<p class="text">hello</p>')     // => true
containsHTML('<input type="text" />')          // => true

containsHTML('</>')                           // => false (不完整的标签)
containsHTML('1 < 2 && 3 > 4')                // => false (数学表达式)
containsHTML('hello world')                   // => false (纯文本)
containsHTML('<')                              // => false (单个尖括号)

notNil

检查值是否不为 null 或 undefined，与 isNil 相反。

function notNil<T>(value: T): value is T extends null | undefined ? never : T

示例：

notNil(0)                    // => true
notNil('')                   // => true
notNil(false)                // => true
notNil({})                   // => true
notNil([])                   // => true
notNil('hello')              // => true
notNil(123)                  // => true

notNil(null)                 // => false
notNil(undefined)            // => false

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@txjs/bool

安装

导入方式

函数列表

is

toString

isArray

isBoolean

isFunction

isAsyncFunction

isInteger

isNil

isNull

isNumber

isNumeric

isString

isSymbol

isUndefined

isDate

isPromise

isPlainObject

isPhone

isNonVirtualPhone

isPhoneNumber

isLandline

isEmail

isHttpUrl

isAbsoluteUrl

isURL

isValidString

isNonEmptyString

isNonEmptyObject

isBlob

containsHTML

notNil