@zdepot/utils 1.0.2 → 1.1.0

package/README.md

@@ -1,28 +1,28 @@
 # @zdepot/utils
 
-安全类型转换工具库，提供带兜底值的类型判断与转换方法，确保你的代码永远不会因类型问题而抛异常。
+Safe type conversion tool library, which provides the method of type judgment and conversion with bottom value, to ensure that your code will not throw exceptions because of type problems.
 
-## 特性
+## Features
 
-✅ **类型安全** - 基于 `Object.prototype.toString` 的精确类型判断  
-✅ **兜底保护** - 所有转换方法都有默认兜底值，避免运行时错误  
-✅ **JSON 解析** - 智能 JSON 解析，自动判断类型  
-✅ **循环引用** - 安全的 JSON 序列化，自动处理循环引用和函数
-✅ **TypeScript 支持** - 完整的 TypeScript 类型定义
-✅ **Tree-shaking** - 无副作用，支持打包器优化  
+✅ **Type Safety** - Accurate type detection based on `Object.prototype.toString`  
+✅ **Fallback Protection** - All conversion methods have default fallback values to prevent runtime errors  
+✅ **JSON Parsing** - Smart JSON parsing with automatic type detection  
+✅ **Circular References** - Safe JSON serialization with automatic circular reference and function handling  
+✅ **TypeScript Support** - Complete TypeScript type definitions  
+✅ **Tree-shaking** - Side-effect free, compatible with bundler optimization  
 
-## 安装
+## Installation
 
 ```bash
 npm install @zdepot/utils
 ```
 
-## 使用
+## Usage
 
 ```ts
 import safe from '@zdepot/utils'
 
-// 或按需引入
+// Or import only what you need
 import { safe } from '@zdepot/utils'
 ```
 
@@ -30,7 +30,7 @@ import { safe } from '@zdepot/utils'
 
 ### isSameType(a, b)
 
-判断两个值是否为相同类型，基于 `Object.prototype.toString` 精确判断。
+Checks if two values are of the same type, using `Object.prototype.toString` for precise detection.
 
 ```ts
 safe.isSameType([], [])     // true
@@ -40,7 +40,7 @@ safe.isSameType(1, '1')     // false
 
 ### array(value)
 
-确保返回数组。如果输入是数组则直接返回；如果是 JSON 字符串则自动 parse；否则返回空数组 `[]`。
+Ensures an array is returned. Returns the input directly if it's an array; parses JSON strings automatically; otherwise returns an empty array `[]`.
 
 ```ts
 safe.array([1, 2])          // [1, 2]
@@ -51,7 +51,7 @@ safe.array(null)            // []
 
 ### string(value, fallback?)
 
-确保返回字符串。如果输入是字符串则直接返回，否则返回兜底值（默认 `""`）。
+Ensures a string is returned. Returns the input directly if it's a string, otherwise returns the fallback value (default `""`).
 
 ```ts
 safe.string('hello')        // 'hello'
@@ -61,7 +61,7 @@ safe.string(123, 'default') // 'default'
 
 ### number(value, fallback?)
 
-确保返回数字。用 `Number()` 转换，如果结果为 NaN 或 Infinity 则返回兜底值（默认 `0`）。
+Ensures a number is returned. Uses `Number()` for conversion, returns fallback value (default `0`) if result is NaN or Infinity.
 
 ```ts
 safe.number(123)            // 123
@@ -73,64 +73,64 @@ safe.number(Infinity)       // 0
 
 ### jsonParse(value, fallback)
 
-带兜底值的 `JSON.parse`。解析失败或结果类型与兜底值不一致时返回兜底值。
+`JSON.parse` with fallback value. Returns fallback if parsing fails or result type doesn't match fallback type.
 
 ```ts
 safe.jsonParse('{"a":1}', {})   // { a: 1 }
-safe.jsonParse('invalid', {})   // {}
-safe.jsonParse('"hello"', [])   // []  (类型不匹配)
+safe.jsonParse('invalid', {})  // {}
+safe.jsonParse('"hello"', [])   // []  (type mismatch)
 safe.jsonParse(null, {})        // {}
 ```
 
 ### jsonParseObj(value, fallback)
 
-增强版 `jsonParse`，只处理以 `[` 或 `{` 开头的字符串（对象/数组），否则直接返回兜底值。内置长度限制防止 DoS 攻击。
+Enhanced `jsonParse` that only processes strings starting with `[` or `{` (objects/arrays), otherwise returns fallback directly. Built-in length limit prevents DoS attacks.
 
 ```ts
 safe.jsonParseObj('{"a":1}', {})    // { a: 1 }
 safe.jsonParseObj('[1,2]', [])      // [1, 2]
-safe.jsonParseObj('"hello"', {})    // {}  (不以 [ 或 { 开头)
+safe.jsonParseObj('"hello"', {})    // {}  (doesn't start with [ or {)
 safe.jsonParseObj('invalid', {})    // {}
 ```
 
 ### split(value, splitStr)
 
-安全的 `String.split`。空字符串返回 `[]` 避免 `['']`，异常也返回 `[]`。
+Safe `String.split`. Empty strings return `[]` instead of `['']`, errors also return `[]`.
 
 ```ts
 safe.split('a,b,c', ',')   // ['a', 'b', 'c']
-safe.split('', ',')         // []
-safe.split(null, ',')       // []
+safe.split('', ',')        // []
+safe.split(null, ',')      // []
 ```
 
 ### boolean(value, fallback?)
 
-确保返回布尔值。支持 `true/false` 字符串（大小写不敏感）和 `0/1` 数字。
+Ensures a boolean is returned. Supports `true/false` strings (case-insensitive) and `0/1` numbers.
 
 ```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  (兜底值)
+safe.boolean('TRUE')         // true
+safe.boolean(1)              // true
+safe.boolean('false')        // false
+safe.boolean(0)              // false
+safe.boolean('hello')        // false  (fallback value)
 ```
 
 ### date(value, fallback?)
 
-确保返回日期对象。支持 Date 对象、时间戳和日期字符串。
+Ensures a Date object is returned. Supports Date objects, timestamps, and date strings.
 
 ```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
+safe.date(new Date())           // returns as-is
+safe.date(1700000000000)         // new Date(1700000000000)
+safe.date('2023-01-01')          // new Date('2023-01-01')
+safe.date('invalid')             // new Date()  (current time)
+safe.date('invalid', fallback)   // fallback
 ```
 
 ### function(value, fallback?)
 
-确保返回函数。如果输入是函数则直接返回，否则返回兜底值（默认空函数）。
+Ensures a function is returned. Returns the input directly if it's a function, otherwise returns the fallback value (default empty function).
 
 ```ts
 safe.function(fn)               // fn
@@ -140,18 +140,18 @@ safe.function(null, () => 'hi') // () => 'hi'
 
 ### nonEmptyString(value, fallback?)
 
-确保返回非空字符串。如果是非空字符串则返回，否则返回兜底值。
+Ensures a non-empty string is returned. Returns the input if it's a non-empty string, otherwise returns the fallback value.
 
 ```ts
 safe.nonEmptyString('hello')    // 'hello'
-safe.nonEmptyString('  ')       // ''  (纯空白)
+safe.nonEmptyString('  ')       // ''  (whitespace only)
 safe.nonEmptyString('')         // ''
 safe.nonEmptyString(123, 'N/A') // 'N/A'
 ```
 
 ### email(value, fallback?)
 
-确保返回有效的 email 字符串。
+Ensures a valid email string is returned.
 
 ```ts
 safe.email('user@example.com')  // 'user@example.com'
@@ -161,7 +161,7 @@ safe.email('bad', 'a@b.com')    // 'a@b.com'
 
 ### timestamp(value, fallback?)
 
-确保返回有效的时间戳。
+Ensures a valid timestamp is returned.
 
 ```ts
 safe.timestamp(1700000000000)   // 1700000000000
@@ -172,7 +172,7 @@ safe.timestamp('invalid', 0)    // 0
 
 ### jsonStringify(value, indent?)
 
-安全的 JSON 序列化。自动处理循环引用和函数，避免抛异常。
+Safe JSON serialization. Automatically handles circular references and functions without throwing.
 
 ```ts
 safe.jsonStringify({ a: 1 })              // '{"a":1}'
@@ -183,22 +183,22 @@ obj.self = obj
 safe.jsonStringify(obj)                   // '{"name":"test","self":"[Circular]"}'
 ```
 
-## 使用场景
+## Use Cases
 
 ```ts
-// API 响应处理
+// API response handling
 const data = safe.jsonParse(response.data, defaultValue)
 const items = safe.array(data.items)
 
-// 配置文件解析
+// Config file parsing
 const config = safe.jsonParseObj(fs.readFileSync('config.json', 'utf-8'), {})
 
-// 用户输入处理
+// User input processing
 const username = safe.string(input.username, 'guest')
 const age = safe.number(input.age, 0)
 
-// 字符串分割
-const parts = safe.split(input.tags, ',') // 避免 split(',a', ',') 得到 ['', 'a']
+// String splitting
+const parts = safe.split(input.tags, ',') // avoids split(',a', ',') returning ['', 'a']
 ```
 
 ## License

package/dist/index.d.ts

@@ -96,6 +96,20 @@ interface SafeUtils {
      * @returns 序列化后的字符串
      */
     jsonStringify: (value: unknown, indent?: number) => string;
+    /**
+     * 确保返回正数。如果输入是正数则返回，否则返回兜底值（默认 1）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 正数或兜底值
+     */
+    positive: (value: unknown, fallback?: number) => number;
+    /**
+     * 确保返回有效的 URL 字符串。如果是有效 URL 则返回，否则返回兜底值（默认 ""）。
+     * @param value 输入值
+     * @param fallback 兜底值
+     * @returns 有效的 URL 字符串
+     */
+    url: (value: unknown, fallback?: string) => string;
 }
 
 declare const safe: SafeUtils;

package/dist/index.global.js

@@ -0,0 +1 @@
+"use strict";var safeUtils=(()=>{var u=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var d=(n,t)=>{for(var r in t)u(n,r,{get:t[r],enumerable:!0})},N=(n,t,r,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of y(t))!m.call(n,e)&&e!==r&&u(n,e,{get:()=>t[e],enumerable:!(s=T(t,e))||s.enumerable});return n};var S=n=>N(u({},"__esModule",{value:!0}),n);var R={};d(R,{default:()=>P,safe:()=>p});var k=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,a=/^[\[{]/,h=()=>{},c=n=>Object.prototype.toString.call(n),o=(n,t)=>c(n)===c(t),g=(n,t)=>{if(n==null)return t;try{let r=JSON.parse(n);return o(r,t)?r:t}catch{return t}},x=(n,t)=>{if(typeof n!="string"||n.length>10485760||n.length<2)return t;try{if(!a.test(n))throw new Error;let r=JSON.parse(n);return o(r,t)?r:t}catch{return t}},E=n=>o(n,[])?n:o(n,"")?g(n,[]):[],i=(n,t="")=>typeof n=="string"?n:t??"",f=(n,t=0)=>{let r=Number(n);return Number.isFinite(r)?r:Number.isFinite(t)?t:0},O=(n,t)=>typeof n!="string"||n===""?[]:n.split(t),D=(n,t=!1)=>{if(n===!0||n===1)return!0;if(n===!1||n===0)return!1;let r=String(n).toLowerCase();return r==="true"?!0:r==="false"?!1:t},w=(n,t)=>{if(n instanceof Date)return n;if(typeof n=="number"||typeof n=="string"){let r=new Date(n);return isNaN(r.getTime())?t??new Date:r}return t??new Date},_=(n,t=h)=>typeof n=="function"?n:t,b=(n,t="")=>{let r=i(n,t);return r.trim()!==""?r:t},J=(n,t="")=>{let r=i(n,t);return k.test(r)?r:t},j=(n,t=Date.now())=>w(n,new Date(t)).getTime(),F=(n,t)=>{let r=new WeakSet;try{return JSON.stringify(n,(s,e)=>{if(typeof e=="function")return"[Function]";if(typeof e=="object"&&e!==null){if(r.has(e))return"[Circular]";r.add(e)}return e},t)}catch{return"{}"}},L=(n,t=1)=>{let r=f(n,NaN);return r>0?r:t},M=(n,t="")=>{let r=i(n,t);try{let s=new URL(r);return s.protocol==="http:"||s.protocol==="https:"?r:t}catch{return t}},p={isSameType:o,array:E,string:i,number:f,jsonParse:g,jsonParseObj:x,split:O,boolean:D,date:w,function:_,nonEmptyString:b,email:J,timestamp:j,jsonStringify:F,positive:L,url:M},P=p;return S(R);})();

package/dist/index.js

@@ -1 +1 @@
-"use strict";var o=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var a=(e,n)=>{for(var t in n)o(e,t,{get:n[t],enumerable:!0})},p=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let s of g(n))!y.call(e,s)&&s!==t&&o(e,s,{get:()=>n[s],enumerable:!(r=c(n,s))||r.enumerable});return e};var T=e=>p(o({},"__esModule",{value:!0}),e);var d={};a(d,{default:()=>S,safe:()=>f});module.exports=T(d);var m=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,w=/^[\[{]/;function u(e){return Object.prototype.toString.call(e)}var f={isSameType:function(n,t){return u(n)===u(t)},array:function(n){return this.isSameType(n,[])?n:this.isSameType(n,"")?this.jsonParse(n,[]):[]},string:function(n,t=""){return typeof n=="string"?n:t??""},number:function(n,t=0){let r=Number(n);return Number.isFinite(r)?r:Number.isFinite(t)?t:0},jsonParse:function(n,t){if(n==null)return t;try{let r=JSON.parse(n);return this.isSameType(r,t)?r:t}catch{return t}},jsonParseObj:function(n,t){if(typeof n!="string"||n.length>10485760||n.length<2)return t;try{if(!w.test(n))throw new Error;let r=JSON.parse(n);return this.isSameType(r,t)?r:t}catch{return t}},split:function(n,t){if(typeof n!="string"||n==="")return[];try{return n.split(t)}catch{return[]}},boolean:function(n,t=!1){return n===!0||String(n).toLowerCase()==="true"||n===1?!0:n===!1||String(n).toLowerCase()==="false"||n===0?!1:t},date:function(n,t){let r=t??new Date;if(n instanceof Date)return n;if(typeof n=="number"||typeof n=="string"){let s=new Date(n);return isNaN(s.getTime())?r:s}return r},function:function(e,n=(()=>{})){return typeof e=="function"?e:n},nonEmptyString:function(n,t=""){let r=this.string(n,t);return r.trim()!==""?r:t},email:function(n,t=""){let r=this.string(n,t);return m.test(r)?r:t},timestamp:function(n,t=Date.now()){return this.date(n,new Date(t)).getTime()},jsonStringify:function(n,t){let r=new WeakSet;try{return JSON.stringify(n,(s,i)=>{if(typeof i=="function")return"[Function]";if(typeof i=="object"&&i!==null){if(r.has(i))return"[Circular]";r.add(i)}return i},t)}catch{return"{}"}}},S=f;0&&(module.exports={safe});
+"use strict";var u=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var d=(n,t)=>{for(var r in t)u(n,r,{get:t[r],enumerable:!0})},N=(n,t,r,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of y(t))!m.call(n,e)&&e!==r&&u(n,e,{get:()=>t[e],enumerable:!(s=T(t,e))||s.enumerable});return n};var S=n=>N(u({},"__esModule",{value:!0}),n);var R={};d(R,{default:()=>P,safe:()=>p});module.exports=S(R);var k=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,a=/^[\[{]/,h=()=>{},c=n=>Object.prototype.toString.call(n),o=(n,t)=>c(n)===c(t),g=(n,t)=>{if(n==null)return t;try{let r=JSON.parse(n);return o(r,t)?r:t}catch{return t}},x=(n,t)=>{if(typeof n!="string"||n.length>10485760||n.length<2)return t;try{if(!a.test(n))throw new Error;let r=JSON.parse(n);return o(r,t)?r:t}catch{return t}},E=n=>o(n,[])?n:o(n,"")?g(n,[]):[],i=(n,t="")=>typeof n=="string"?n:t??"",f=(n,t=0)=>{let r=Number(n);return Number.isFinite(r)?r:Number.isFinite(t)?t:0},O=(n,t)=>typeof n!="string"||n===""?[]:n.split(t),D=(n,t=!1)=>{if(n===!0||n===1)return!0;if(n===!1||n===0)return!1;let r=String(n).toLowerCase();return r==="true"?!0:r==="false"?!1:t},w=(n,t)=>{if(n instanceof Date)return n;if(typeof n=="number"||typeof n=="string"){let r=new Date(n);return isNaN(r.getTime())?t??new Date:r}return t??new Date},_=(n,t=h)=>typeof n=="function"?n:t,b=(n,t="")=>{let r=i(n,t);return r.trim()!==""?r:t},J=(n,t="")=>{let r=i(n,t);return k.test(r)?r:t},j=(n,t=Date.now())=>w(n,new Date(t)).getTime(),F=(n,t)=>{let r=new WeakSet;try{return JSON.stringify(n,(s,e)=>{if(typeof e=="function")return"[Function]";if(typeof e=="object"&&e!==null){if(r.has(e))return"[Circular]";r.add(e)}return e},t)}catch{return"{}"}},L=(n,t=1)=>{let r=f(n,NaN);return r>0?r:t},M=(n,t="")=>{let r=i(n,t);try{let s=new URL(r);return s.protocol==="http:"||s.protocol==="https:"?r:t}catch{return t}},p={isSameType:o,array:E,string:i,number:f,jsonParse:g,jsonParseObj:x,split:O,boolean:D,date:w,function:_,nonEmptyString:b,email:J,timestamp:j,jsonStringify:F,positive:L,url:M},P=p;0&&(module.exports={safe});

package/dist/index.mjs

@@ -1 +1 @@
-var u=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,f=/^[\[{]/;function o(e){return Object.prototype.toString.call(e)}var c={isSameType:function(n,t){return o(n)===o(t)},array:function(n){return this.isSameType(n,[])?n:this.isSameType(n,"")?this.jsonParse(n,[]):[]},string:function(n,t=""){return typeof n=="string"?n:t??""},number:function(n,t=0){let r=Number(n);return Number.isFinite(r)?r:Number.isFinite(t)?t:0},jsonParse:function(n,t){if(n==null)return t;try{let r=JSON.parse(n);return this.isSameType(r,t)?r:t}catch{return t}},jsonParseObj:function(n,t){if(typeof n!="string"||n.length>10485760||n.length<2)return t;try{if(!f.test(n))throw new Error;let r=JSON.parse(n);return this.isSameType(r,t)?r:t}catch{return t}},split:function(n,t){if(typeof n!="string"||n==="")return[];try{return n.split(t)}catch{return[]}},boolean:function(n,t=!1){return n===!0||String(n).toLowerCase()==="true"||n===1?!0:n===!1||String(n).toLowerCase()==="false"||n===0?!1:t},date:function(n,t){let r=t??new Date;if(n instanceof Date)return n;if(typeof n=="number"||typeof n=="string"){let i=new Date(n);return isNaN(i.getTime())?r:i}return r},function:function(e,n=(()=>{})){return typeof e=="function"?e:n},nonEmptyString:function(n,t=""){let r=this.string(n,t);return r.trim()!==""?r:t},email:function(n,t=""){let r=this.string(n,t);return u.test(r)?r:t},timestamp:function(n,t=Date.now()){return this.date(n,new Date(t)).getTime()},jsonStringify:function(n,t){let r=new WeakSet;try{return JSON.stringify(n,(i,s)=>{if(typeof s=="function")return"[Function]";if(typeof s=="object"&&s!==null){if(r.has(s))return"[Circular]";r.add(s)}return s},t)}catch{return"{}"}}},g=c;export{g as default,c as safe};
+var w=/^[^\s@]+@[^\s@]+\.[^\s@]+$/,p=/^[\[{]/,T=()=>{},u=n=>Object.prototype.toString.call(n),s=(n,t)=>u(n)===u(t),c=(n,t)=>{if(n==null)return t;try{let r=JSON.parse(n);return s(r,t)?r:t}catch{return t}},y=(n,t)=>{if(typeof n!="string"||n.length>10485760||n.length<2)return t;try{if(!p.test(n))throw new Error;let r=JSON.parse(n);return s(r,t)?r:t}catch{return t}},m=n=>s(n,[])?n:s(n,"")?c(n,[]):[],o=(n,t="")=>typeof n=="string"?n:t??"",g=(n,t=0)=>{let r=Number(n);return Number.isFinite(r)?r:Number.isFinite(t)?t:0},d=(n,t)=>typeof n!="string"||n===""?[]:n.split(t),N=(n,t=!1)=>{if(n===!0||n===1)return!0;if(n===!1||n===0)return!1;let r=String(n).toLowerCase();return r==="true"?!0:r==="false"?!1:t},f=(n,t)=>{if(n instanceof Date)return n;if(typeof n=="number"||typeof n=="string"){let r=new Date(n);return isNaN(r.getTime())?t??new Date:r}return t??new Date},S=(n,t=T)=>typeof n=="function"?n:t,k=(n,t="")=>{let r=o(n,t);return r.trim()!==""?r:t},a=(n,t="")=>{let r=o(n,t);return w.test(r)?r:t},h=(n,t=Date.now())=>f(n,new Date(t)).getTime(),x=(n,t)=>{let r=new WeakSet;try{return JSON.stringify(n,(i,e)=>{if(typeof e=="function")return"[Function]";if(typeof e=="object"&&e!==null){if(r.has(e))return"[Circular]";r.add(e)}return e},t)}catch{return"{}"}},E=(n,t=1)=>{let r=g(n,NaN);return r>0?r:t},O=(n,t="")=>{let r=o(n,t);try{let i=new URL(r);return i.protocol==="http:"||i.protocol==="https:"?r:t}catch{return t}},D={isSameType:s,array:m,string:o,number:g,jsonParse:c,jsonParseObj:y,split:d,boolean:N,date:f,function:S,nonEmptyString:k,email:a,timestamp:h,jsonStringify:x,positive:E,url:O},_=D;export{_ as default,D as safe};

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@zdepot/utils",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "安全类型转换工具库，提供带兜底值的类型判断与转换方法",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
+  "browser": "dist/index.iife.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "browser": "./dist/index.iife.js",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
@@ -43,7 +45,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dalongzhu/z-tools.git",
+    "url": "https://gitee.com/DLwebweb/zdepot-utils",
     "directory": ""
   },
   "devDependencies": {