@zdepot/utils

安全类型转换工具库，提供带兜底值的类型判断与转换方法，确保你的代码永远不会因类型问题而抛异常。

特性

✅ 类型安全 - 基于 Object.prototype.toString 的精确类型判断
✅ 兜底保护 - 所有转换方法都有默认兜底值，避免运行时错误
✅ JSON 解析 - 智能 JSON 解析，自动判断类型
✅ 循环引用 - 安全的 JSON 序列化，自动处理循环引用和函数 ✅ TypeScript 支持 - 完整的 TypeScript 类型定义 ✅ Tree-shaking - 无副作用，支持打包器优化

安装

npm install @zdepot/utils

使用

import safe from '@zdepot/utils'

// 或按需引入
import { safe } from '@zdepot/utils'

API

isSameType(a, b)

判断两个值是否为相同类型，基于 Object.prototype.toString 精确判断。

safe.isSameType([], [])     // true
safe.isSameType({}, [])     // false
safe.isSameType(1, '1')     // false

array(value)

确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 []。

safe.array([1, 2])          // [1, 2]
safe.array('[1,2]')         // [1, 2]
safe.array('hello')         // []
safe.array(null)            // []

string(value, fallback?)

确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 ""）。

safe.string('hello')        // 'hello'
safe.string(123)            // ''
safe.string(123, 'default') // 'default'

number(value, fallback?)

确保返回数字。用 Number() 转换，如果结果为 NaN 或 Infinity 则返回兜底值（默认 0）。

safe.number(123)            // 123
safe.number('456')          // 456
safe.number('abc')          // 0
safe.number('abc', -1)      // -1
safe.number(Infinity)       // 0

jsonParse(value, fallback)

带兜底值的 JSON.parse。解析失败或结果类型与兜底值不一致时返回兜底值。

safe.jsonParse('{"a":1}', {})   // { a: 1 }
safe.jsonParse('invalid', {})   // {}
safe.jsonParse('"hello"', [])   // []  (类型不匹配)
safe.jsonParse(null, {})        // {}

jsonParseObj(value, fallback)

增强版 jsonParse，只处理以 [ 或 { 开头的字符串（对象/数组），否则直接返回兜底值。内置长度限制防止 DoS 攻击。

safe.jsonParseObj('{"a":1}', {})    // { a: 1 }
safe.jsonParseObj('[1,2]', [])      // [1, 2]
safe.jsonParseObj('"hello"', {})    // {}  (不以 [ 或 { 开头)
safe.jsonParseObj('invalid', {})    // {}

split(value, splitStr)

安全的 String.split。空字符串返回 [] 避免 ['']，异常也返回 []。

safe.split('a,b,c', ',')   // ['a', 'b', 'c']
safe.split('', ',')         // []
safe.split(null, ',')       // []

boolean(value, fallback?)

确保返回布尔值。支持 true/false 字符串（大小写不敏感）和 0/1 数字。

safe.boolean(true)          // true
safe.boolean('TRUE')        // true
safe.boolean(1)             // true
safe.boolean('false')       // false
safe.boolean(0)             // false
safe.boolean('hello')       // false  (兜底值)

date(value, fallback?)

确保返回日期对象。支持 Date 对象、时间戳和日期字符串。

safe.date(new Date())           // 原样返回
safe.date(1700000000000)        // new Date(1700000000000)
safe.date('2023-01-01')         // new Date('2023-01-01')
safe.date('invalid')            // new Date()  (当前时间)
safe.date('invalid', fallback)  // fallback

function(value, fallback?)

确保返回函数。如果输入是函数则直接返回，否则返回兜底值（默认空函数）。

safe.function(fn)               // fn
safe.function(null)             // () => undefined
safe.function(null, () => 'hi') // () => 'hi'

nonEmptyString(value, fallback?)

确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。

safe.nonEmptyString('hello')    // 'hello'
safe.nonEmptyString('  ')       // ''  (纯空白)
safe.nonEmptyString('')         // ''
safe.nonEmptyString(123, 'N/A') // 'N/A'

email(value, fallback?)

确保返回有效的 email 字符串。

safe.email('[email protected]')  // '[email protected]'
safe.email('invalid')           // ''
safe.email('bad', '[email protected]')    // '[email protected]'

timestamp(value, fallback?)

确保返回有效的时间戳。

safe.timestamp(1700000000000)   // 1700000000000
safe.timestamp(new Date())      // date.getTime()
safe.timestamp('2023-01-01')    // 1672531200000
safe.timestamp('invalid', 0)    // 0

jsonStringify(value, indent?)

安全的 JSON 序列化。自动处理循环引用和函数，避免抛异常。

safe.jsonStringify({ a: 1 })              // '{"a":1}'
safe.jsonStringify({ fn: () => {} })      // '{"fn":"[Function]"}'

const obj: any = { name: 'test' }
obj.self = obj
safe.jsonStringify(obj)                   // '{"name":"test","self":"[Circular]"}'

使用场景

// API 响应处理
const data = safe.jsonParse(response.data, defaultValue)
const items = safe.array(data.items)

// 配置文件解析
const config = safe.jsonParseObj(fs.readFileSync('config.json', 'utf-8'), {})

// 用户输入处理
const username = safe.string(input.username, 'guest')
const age = safe.number(input.age, 0)

// 字符串分割
const parts = safe.split(input.tags, ',') // 避免 split(',a', ',') 得到 ['', 'a']

License

MIT