@dalongzhu/utils

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

特性

✅ 类型安全 - 基于 Object.prototype.toString 的精确类型判断
✅ 兜底保护 - 所有转换方法都有默认兜底值，避免运行时错误
✅ JSON 解析 - 智能 JSON 解析，自动判断类型
✅ TypeScript 支持 - 完整的 TypeScript 类型定义

安装

npm install @dalongzhu/utils

使用

import safe from '@dalongzhu/utils'

// 或按需引入
import { safe } from '@dalongzhu/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 则返回兜底值（默认 0）。

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

jsonParse(value, fallback)

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

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

jsonParseObj(value, fallback)

增强版 jsonParse，只处理以 [ 或 { 开头的字符串（对象/数组），否则直接返回兜底值。

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, ',')       // []

使用场景

// 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