@zdepot/utils 1.0.0

package/README.md

@@ -0,0 +1,206 @@
+# @zdepot/utils
+
+安全类型转换工具库，提供带兜底值的类型判断与转换方法，确保你的代码永远不会因类型问题而抛异常。
+
+## 特性
+
+✅ **类型安全** - 基于 `Object.prototype.toString` 的精确类型判断  
+✅ **兜底保护** - 所有转换方法都有默认兜底值，避免运行时错误  
+✅ **JSON 解析** - 智能 JSON 解析，自动判断类型  
+✅ **循环引用** - 安全的 JSON 序列化，自动处理循环引用和函数
+✅ **TypeScript 支持** - 完整的 TypeScript 类型定义
+✅ **Tree-shaking** - 无副作用，支持打包器优化  
+
+## 安装
+
+```bash
+npm install @zdepot/utils
+```
+
+## 使用
+
+```ts
+import safe from '@zdepot/utils'
+
+// 或按需引入
+import { safe } from '@zdepot/utils'
+```
+
+## API
+
+### isSameType(a, b)
+
+判断两个值是否为相同类型，基于 `Object.prototype.toString` 精确判断。
+
+```ts
+safe.isSameType([], [])     // true
+safe.isSameType({}, [])     // false
+safe.isSameType(1, '1')     // false
+```
+
+### array(value)
+
+确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+
+```ts
+safe.array([1, 2])          // [1, 2]
+safe.array('[1,2]')         // [1, 2]
+safe.array('hello')         // []
+safe.array(null)            // []
+```
+
+### string(value, fallback?)
+
+确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+
+```ts
+safe.string('hello')        // 'hello'
+safe.string(123)            // ''
+safe.string(123, 'default') // 'default'
+```
+
+### number(value, fallback?)
+
+确保返回数字。用 `Number()` 转换，如果结果为 NaN 或 Infinity 则返回兜底值（默认 `0`）。
+
+```ts
+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`。解析失败或结果类型与兜底值不一致时返回兜底值。
+
+```ts
+safe.jsonParse('{"a":1}', {})   // { a: 1 }
+safe.jsonParse('invalid', {})   // {}
+safe.jsonParse('"hello"', [])   // []  (类型不匹配)
+safe.jsonParse(null, {})        // {}
+```
+
+### jsonParseObj(value, fallback)
+
+增强版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。内置长度限制防止 DoS 攻击。
+
+```ts
+safe.jsonParseObj('{"a":1}', {})    // { a: 1 }
+safe.jsonParseObj('[1,2]', [])      // [1, 2]
+safe.jsonParseObj('"hello"', {})    // {}  (不以 [ 或 { 开头)
+safe.jsonParseObj('invalid', {})    // {}
+```
+
+### split(value, splitStr)
+
+安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+
+```ts
+safe.split('a,b,c', ',')   // ['a', 'b', 'c']
+safe.split('', ',')         // []
+safe.split(null, ',')       // []
+```
+
+### boolean(value, fallback?)
+
+确保返回布尔值。支持 `true/false` 字符串（大小写不敏感）和 `0/1` 数字。
+
+```ts
+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 对象、时间戳和日期字符串。
+
+```ts
+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?)
+
+确保返回函数。如果输入是函数则直接返回，否则返回兜底值（默认空函数）。
+
+```ts
+safe.function(fn)               // fn
+safe.function(null)             // () => undefined
+safe.function(null, () => 'hi') // () => 'hi'
+```
+
+### nonEmptyString(value, fallback?)
+
+确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+
+```ts
+safe.nonEmptyString('hello')    // 'hello'
+safe.nonEmptyString('  ')       // ''  (纯空白)
+safe.nonEmptyString('')         // ''
+safe.nonEmptyString(123, 'N/A') // 'N/A'
+```
+
+### email(value, fallback?)
+
+确保返回有效的 email 字符串。
+
+```ts
+safe.email('user@example.com')  // 'user@example.com'
+safe.email('invalid')           // ''
+safe.email('bad', 'a@b.com')    // 'a@b.com'
+```
+
+### timestamp(value, fallback?)
+
+确保返回有效的时间戳。
+
+```ts
+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 序列化。自动处理循环引用和函数，避免抛异常。
+
+```ts
+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]"}'
+```
+
+## 使用场景
+
+```ts
+// 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

package/dist/index.d.mts

@@ -0,0 +1,103 @@
+interface SafeUtils {
+    /**
+     * 判断相同类型
+     * @param a 第一个值
+     * @param b 第二个值
+     * @returns 是否为相同类型
+     */
+    isSameType: (a: unknown, b: unknown) => boolean;
+    /**
+     * 确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+     * @param value 输入值
+     * @returns 数组或空数组
+     */
+    array: <T = unknown>(value: T) => T extends readonly unknown[] ? T : [];
+    /**
+     * 确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 字符串或空字符串
+     */
+    string: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回数字。用 `Number()` 转换，如果结果为 NaN 则返回兜底值（默认 `0`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 数字或兜底值
+     */
+    number: (value: unknown, fallback?: number) => number;
+    /**
+     * 带兜底值的 `JSON.parse`。解析失败或结果类型与兜底值不一致时返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 解析结果或兜底值
+     */
+    jsonParse: <T = unknown>(value: unknown, fallback: T) => T;
+    /**
+     * 增版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 解析结果或兜底值
+     */
+    jsonParseObj: <T extends Record<string, unknown> | unknown[]>(value: string, fallback: T) => T;
+    /**
+     * 安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+     * @param value 输入值
+     * @param splitStr 分隔符
+     * @returns 分割结果或空数组
+     */
+    split: (value: string, splitStr: string) => string[];
+    /**
+     * 确保返回布尔值。真值返回 `true`，其他情况返回兜底值（默认 `false`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 布尔值
+     */
+    boolean: (value: unknown, fallback?: boolean) => boolean;
+    /**
+     * 确保返回日期对象。如果是有效的时间戳、日期字符串或 Date 对象，返回对应的 Date，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 日期对象
+     */
+    date: (value: unknown, fallback?: Date) => Date;
+    /**
+     * 确保返回函数。如果输入是函数则直接返回，否则返回空函数。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 函数
+     */
+    function: <T extends (...args: any[]) => any>(value: unknown, fallback?: T) => T;
+    /**
+     * 确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 非空字符串
+     */
+    nonEmptyString: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回有效的 email 字符串。如果是有效 email 则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 有效的 email 字符串
+     */
+    email: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回有效的时间戳。如果是有效时间戳则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 有效的时间戳
+     */
+    timestamp: (value: unknown, fallback?: number) => number;
+    /**
+     * 安全的 JSON 序列化。处理循环引用和不可序列化的值。
+     * @param value 要序列化的值
+     * @param indent 缩进
+     * @returns 序列化后的字符串
+     */
+    jsonStringify: (value: unknown, indent?: number) => string;
+}
+
+declare const safe: SafeUtils;
+
+export { type SafeUtils, safe as default, safe };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+interface SafeUtils {
+    /**
+     * 判断相同类型
+     * @param a 第一个值
+     * @param b 第二个值
+     * @returns 是否为相同类型
+     */
+    isSameType: (a: unknown, b: unknown) => boolean;
+    /**
+     * 确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+     * @param value 输入值
+     * @returns 数组或空数组
+     */
+    array: <T = unknown>(value: T) => T extends readonly unknown[] ? T : [];
+    /**
+     * 确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 字符串或空字符串
+     */
+    string: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回数字。用 `Number()` 转换，如果结果为 NaN 则返回兜底值（默认 `0`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 数字或兜底值
+     */
+    number: (value: unknown, fallback?: number) => number;
+    /**
+     * 带兜底值的 `JSON.parse`。解析失败或结果类型与兜底值不一致时返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 解析结果或兜底值
+     */
+    jsonParse: <T = unknown>(value: unknown, fallback: T) => T;
+    /**
+     * 增版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 解析结果或兜底值
+     */
+    jsonParseObj: <T extends Record<string, unknown> | unknown[]>(value: string, fallback: T) => T;
+    /**
+     * 安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+     * @param value 输入值
+     * @param splitStr 分隔符
+     * @returns 分割结果或空数组
+     */
+    split: (value: string, splitStr: string) => string[];
+    /**
+     * 确保返回布尔值。真值返回 `true`，其他情况返回兜底值（默认 `false`）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 布尔值
+     */
+    boolean: (value: unknown, fallback?: boolean) => boolean;
+    /**
+     * 确保返回日期对象。如果是有效的时间戳、日期字符串或 Date 对象，返回对应的 Date，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 日期对象
+     */
+    date: (value: unknown, fallback?: Date) => Date;
+    /**
+     * 确保返回函数。如果输入是函数则直接返回，否则返回空函数。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 函数
+     */
+    function: <T extends (...args: any[]) => any>(value: unknown, fallback?: T) => T;
+    /**
+     * 确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 非空字符串
+     */
+    nonEmptyString: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回有效的 email 字符串。如果是有效 email 则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 有效的 email 字符串
+     */
+    email: (value: unknown, fallback?: string) => string;
+    /**
+     * 确保返回有效的时间戳。如果是有效时间戳则返回，否则返回兜底值。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 有效的时间戳
+     */
+    timestamp: (value: unknown, fallback?: number) => number;
+    /**
+     * 安全的 JSON 序列化。处理循环引用和不可序列化的值。
+     * @param value 要序列化的值
+     * @param indent 缩进
+     * @returns 序列化后的字符串
+     */
+    jsonStringify: (value: unknown, indent?: number) => string;
+}
+
+declare const safe: SafeUtils;
+
+export { type SafeUtils, safe as default, safe };

package/dist/index.js

@@ -0,0 +1,218 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  safe: () => safe
+});
+module.exports = __toCommonJS(index_exports);
+var MAX_JSON_LENGTH = 10 * 1024 * 1024;
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var JSON_OBJ_PREFIX = /^[\[{]/;
+function getTypeTag(value) {
+  return Object.prototype.toString.call(value);
+}
+var safe = {
+  /**
+   * 判断相同类型
+   * @param a 第一个值
+   * @param b 第二个值
+   * @returns 是否为相同类型
+   */
+  isSameType: function isSameType(a, b) {
+    return getTypeTag(a) === getTypeTag(b);
+  },
+  /**
+   * 确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+   * @param value 输入值
+   * @returns 数组或空数组
+   */
+  array: function array(value) {
+    if (this.isSameType(value, [])) return value;
+    if (this.isSameType(value, ""))
+      return this.jsonParse(value, []);
+    return [];
+  },
+  /**
+   * 确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 字符串或空字符串
+   */
+  string: function string(value, fallback = "") {
+    if (typeof value === "string") return value;
+    return fallback != null ? fallback : "";
+  },
+  /**
+   * 确保返回数字。用 `Number()` 转换，如果结果为 NaN 则返回兜底值（默认 `0`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 数字或兜底值
+   */
+  number: function number(value, fallback = 0) {
+    const result = Number(value);
+    if (!Number.isFinite(result)) return Number.isFinite(fallback) ? fallback : 0;
+    return result;
+  },
+  /**
+   * 带兜底值的 `JSON.parse`。解析失败或结果类型与兜底值不一致时返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 解析结果或兜底值
+   */
+  jsonParse: function jsonParse(value, fallback) {
+    if (value == null) return fallback;
+    try {
+      const result = JSON.parse(value);
+      return this.isSameType(result, fallback) ? result : fallback;
+    } catch (error) {
+      return fallback;
+    }
+  },
+  /**
+   * 增版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 解析结果或兜底值
+   */
+  jsonParseObj: function jsonParseObj(value, fallback) {
+    if (typeof value !== "string" || value.length > MAX_JSON_LENGTH || value.length < 2) {
+      return fallback;
+    }
+    try {
+      if (!JSON_OBJ_PREFIX.test(value)) throw new Error();
+      const result = JSON.parse(value);
+      return this.isSameType(result, fallback) ? result : fallback;
+    } catch (error) {
+      return fallback;
+    }
+  },
+  /**
+   * 安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+   * @param value 输入值
+   * @param splitStr 分隔符
+   * @returns 分割结果或空数组
+   */
+  split: function split(value, splitStr) {
+    if (typeof value !== "string" || value === "") return [];
+    try {
+      return value.split(splitStr);
+    } catch (error) {
+      return [];
+    }
+  },
+  /**
+   * 确保返回布尔值。真值返回 `true`，其他情况返回兜底值（默认 `false`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 布尔值
+   */
+  boolean: function boolean(value, fallback = false) {
+    if (value === true || String(value).toLowerCase() === "true" || value === 1) return true;
+    if (value === false || String(value).toLowerCase() === "false" || value === 0) return false;
+    return fallback;
+  },
+  /**
+   * 确保返回日期对象。如果是有效的时间戳、日期字符串或 Date 对象，返回对应的 Date，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 日期对象
+   */
+  date: function date(value, fallback) {
+    const actualFallback = fallback != null ? fallback : /* @__PURE__ */ new Date();
+    if (value instanceof Date) return value;
+    if (typeof value === "number" || typeof value === "string") {
+      const d = new Date(value);
+      return isNaN(d.getTime()) ? actualFallback : d;
+    }
+    return actualFallback;
+  },
+  /**
+   * 确保返回函数。如果输入是函数则直接返回，否则返回空函数。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 函数
+   */
+  function: function(value, fallback = (() => void 0)) {
+    if (typeof value === "function") return value;
+    return fallback;
+  },
+  /**
+   * 确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 非空字符串
+   */
+  nonEmptyString: function nonEmptyString(value, fallback = "") {
+    const str = this.string(value, fallback);
+    return str.trim() !== "" ? str : fallback;
+  },
+  /**
+   * 确保返回有效的 email 字符串。如果是有效 email 则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 有效的 email 字符串
+   */
+  email: function email(value, fallback = "") {
+    const str = this.string(value, fallback);
+    return EMAIL_REGEX.test(str) ? str : fallback;
+  },
+  /**
+   * 确保返回有效的时间戳。如果是有效时间戳则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 有效的时间戳
+   */
+  timestamp: function timestamp(value, fallback = Date.now()) {
+    const date2 = this.date(value, new Date(fallback));
+    return date2.getTime();
+  },
+  /**
+   * 安全的 JSON 序列化。处理循环引用和不可序列化的值。
+   * @param value 要序列化的值
+   * @param indent 缩进
+   * @returns 序列化后的字符串
+   */
+  jsonStringify: function jsonStringify(value, indent) {
+    const seen = /* @__PURE__ */ new WeakSet();
+    try {
+      return JSON.stringify(
+        value,
+        (key, val) => {
+          if (typeof val === "function") return "[Function]";
+          if (typeof val === "object" && val !== null) {
+            if (seen.has(val)) return "[Circular]";
+            seen.add(val);
+          }
+          return val;
+        },
+        indent
+      );
+    } catch (error) {
+      return "{}";
+    }
+  }
+};
+var index_default = safe;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  safe
+});

package/dist/index.mjs

@@ -0,0 +1,193 @@
+// src/index.ts
+var MAX_JSON_LENGTH = 10 * 1024 * 1024;
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var JSON_OBJ_PREFIX = /^[\[{]/;
+function getTypeTag(value) {
+  return Object.prototype.toString.call(value);
+}
+var safe = {
+  /**
+   * 判断相同类型
+   * @param a 第一个值
+   * @param b 第二个值
+   * @returns 是否为相同类型
+   */
+  isSameType: function isSameType(a, b) {
+    return getTypeTag(a) === getTypeTag(b);
+  },
+  /**
+   * 确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+   * @param value 输入值
+   * @returns 数组或空数组
+   */
+  array: function array(value) {
+    if (this.isSameType(value, [])) return value;
+    if (this.isSameType(value, ""))
+      return this.jsonParse(value, []);
+    return [];
+  },
+  /**
+   * 确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 字符串或空字符串
+   */
+  string: function string(value, fallback = "") {
+    if (typeof value === "string") return value;
+    return fallback != null ? fallback : "";
+  },
+  /**
+   * 确保返回数字。用 `Number()` 转换，如果结果为 NaN 则返回兜底值（默认 `0`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 数字或兜底值
+   */
+  number: function number(value, fallback = 0) {
+    const result = Number(value);
+    if (!Number.isFinite(result)) return Number.isFinite(fallback) ? fallback : 0;
+    return result;
+  },
+  /**
+   * 带兜底值的 `JSON.parse`。解析失败或结果类型与兜底值不一致时返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 解析结果或兜底值
+   */
+  jsonParse: function jsonParse(value, fallback) {
+    if (value == null) return fallback;
+    try {
+      const result = JSON.parse(value);
+      return this.isSameType(result, fallback) ? result : fallback;
+    } catch (error) {
+      return fallback;
+    }
+  },
+  /**
+   * 增版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 解析结果或兜底值
+   */
+  jsonParseObj: function jsonParseObj(value, fallback) {
+    if (typeof value !== "string" || value.length > MAX_JSON_LENGTH || value.length < 2) {
+      return fallback;
+    }
+    try {
+      if (!JSON_OBJ_PREFIX.test(value)) throw new Error();
+      const result = JSON.parse(value);
+      return this.isSameType(result, fallback) ? result : fallback;
+    } catch (error) {
+      return fallback;
+    }
+  },
+  /**
+   * 安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+   * @param value 输入值
+   * @param splitStr 分隔符
+   * @returns 分割结果或空数组
+   */
+  split: function split(value, splitStr) {
+    if (typeof value !== "string" || value === "") return [];
+    try {
+      return value.split(splitStr);
+    } catch (error) {
+      return [];
+    }
+  },
+  /**
+   * 确保返回布尔值。真值返回 `true`，其他情况返回兜底值（默认 `false`）。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 布尔值
+   */
+  boolean: function boolean(value, fallback = false) {
+    if (value === true || String(value).toLowerCase() === "true" || value === 1) return true;
+    if (value === false || String(value).toLowerCase() === "false" || value === 0) return false;
+    return fallback;
+  },
+  /**
+   * 确保返回日期对象。如果是有效的时间戳、日期字符串或 Date 对象，返回对应的 Date，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 日期对象
+   */
+  date: function date(value, fallback) {
+    const actualFallback = fallback != null ? fallback : /* @__PURE__ */ new Date();
+    if (value instanceof Date) return value;
+    if (typeof value === "number" || typeof value === "string") {
+      const d = new Date(value);
+      return isNaN(d.getTime()) ? actualFallback : d;
+    }
+    return actualFallback;
+  },
+  /**
+   * 确保返回函数。如果输入是函数则直接返回，否则返回空函数。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 函数
+   */
+  function: function(value, fallback = (() => void 0)) {
+    if (typeof value === "function") return value;
+    return fallback;
+  },
+  /**
+   * 确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 非空字符串
+   */
+  nonEmptyString: function nonEmptyString(value, fallback = "") {
+    const str = this.string(value, fallback);
+    return str.trim() !== "" ? str : fallback;
+  },
+  /**
+   * 确保返回有效的 email 字符串。如果是有效 email 则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 有效的 email 字符串
+   */
+  email: function email(value, fallback = "") {
+    const str = this.string(value, fallback);
+    return EMAIL_REGEX.test(str) ? str : fallback;
+  },
+  /**
+   * 确保返回有效的时间戳。如果是有效时间戳则返回，否则返回兜底值。
+   * @param value 输入值
+   * @param fallback 兜底值
+   * @returns 有效的时间戳
+   */
+  timestamp: function timestamp(value, fallback = Date.now()) {
+    const date2 = this.date(value, new Date(fallback));
+    return date2.getTime();
+  },
+  /**
+   * 安全的 JSON 序列化。处理循环引用和不可序列化的值。
+   * @param value 要序列化的值
+   * @param indent 缩进
+   * @returns 序列化后的字符串
+   */
+  jsonStringify: function jsonStringify(value, indent) {
+    const seen = /* @__PURE__ */ new WeakSet();
+    try {
+      return JSON.stringify(
+        value,
+        (key, val) => {
+          if (typeof val === "function") return "[Function]";
+          if (typeof val === "object" && val !== null) {
+            if (seen.has(val)) return "[Circular]";
+            seen.add(val);
+          }
+          return val;
+        },
+        indent
+      );
+    } catch (error) {
+      return "{}";
+    }
+  }
+};
+var index_default = safe;
+export {
+  index_default as default,
+  safe
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@zdepot/utils",
+  "version": "1.0.0",
+  "description": "安全类型转换工具库，提供带兜底值的类型判断与转换方法",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:report": "vitest run --coverage --reporter=text --reporter=html",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "keywords": [
+    "utils",
+    "safe",
+    "type-check",
+    "fallback",
+    "json-parse",
+    "type-conversion",
+    "typescript",
+    "ts"
+  ],
+  "author": "dalongzhu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dalongzhu/z-tools.git",
+    "directory": ""
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.0.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}