@zlikemario/helper 1.0.1 → 1.0.2

package/AGENTS_USE.md

@@ -1,17 +1,37 @@
-# @zlikemario/helper - Agents Guide (Use)
+# @zlikemario/helper · Agents Guide (Use)
 
-面向“使用这个库”的 AI。目标：用最少 token 快速定位方法 + 看到即用的示例。
+> 面向“**使用这个库**”的 AI。
+> 目标只有一个：**最少 token，最快定位方法，复制就能用。**
 
-## 1. 快速入口
+这不是给人类看的长文档，是给 AI 当工具箱索引用的。别抒情，直接干活。
 
-- 默认入口：`@zlikemario/helper` 等价于 `@zlikemario/helper/number`
-- 子路径入口：`/number`、`/utils`、`/decorator`、`/decorator-old`、`/react`、`/vue`、`/types`
+---
 
-## 2. 方法速查（只列名称，先定位，再看下面示例）
+## 1. 快速入口（先定位模块，再看示例）
+
+- **默认入口**：`@zlikemario/helper`
+  等价于：`@zlikemario/helper/number`
+
+- **子路径入口**：
+  - `/number`
+  - `/utils`
+  - `/decorator`
+  - `/decorator-old`
+  - `/react`
+  - `/vue`
+  - `/types`
+
+AI 使用策略：
+
+> 先判断问题属于哪个模块 → 直接跳子路径 → 找对应函数示例。
+
+---
+
+## 2. 方法速查（只列名字，用来“搜脑子”）
 
 ### number
 
-`BigNumber` `isNumber` `simplifyNumber` `readabilityNumber` `toPercentage` `formatPrecision` `readableNumber` `sum` `sumBy`
+`BigNumber` `trimFloatEndZero` `isComputableNumber` `unitFormat` `readabilityNumber` `toPercentage` `readableNumber` `sum` `sumBy`
 
 ### utils
 
@@ -35,22 +55,24 @@
 
 ### types
 
-`Numberish` `NumberString` `MaybeNull` `MaybeUndefined` `MaybePromise` `Defined` `AnyFn` `Noop`
+`IntString` `DecimalsString` `Numberish` `NumberString` `MaybeNull` `MaybeUndefined` `MaybePromise` `Defined` `AnyFn` `Noop`
+
+---
 
-## 3. 用法速览（按模块分组，一函数一用法）
+## 3. 用法速览（一函数一例，禁止废话）
 
 ### number
 
-导入路径：`@zlikemario/helper/number`
+**导入路径**：`@zlikemario/helper/number`
 
 ```ts
 import {
   BigNumber,
-  isNumber,
-  simplifyNumber,
+  trimFloatEndZero,
+  isComputableNumber,
+  unitFormat,
   readabilityNumber,
   toPercentage,
-  formatPrecision,
   readableNumber,
   sum,
   sumBy,
@@ -58,13 +80,13 @@ import {
 ```
 
 ```ts
-isNumber("123");
-isNumber("12.3", true);
+isComputableNumber("123");
+isComputableNumber("12.3", true);
 ```
 
 ```ts
-simplifyNumber(1234567); // "1.2M"
-simplifyNumber("999", 2); // "999"
+unitFormat(1234567); // "1.2M"
+unitFormat("999", 2); // "999"
 ```
 
 ```ts
@@ -77,7 +99,7 @@ toPercentage(0.1234, 1, true); // "12.3"
 ```
 
 ```ts
-formatPrecision("1.234567", 2); // "1.23"
+trimFloatEndZero("1234.100100"); // "1234.1001"
 ```
 
 ```ts
@@ -98,9 +120,11 @@ const v = new BigNumber("0.1").plus("0.2");
 v.toString(); // "0.3"
 ```
 
+---
+
 ### utils
 
-导入路径：`@zlikemario/helper/utils`
+**导入路径**：`@zlikemario/helper/utils`
 
 ```ts
 import {
@@ -160,9 +184,11 @@ await preventTimeout(fetch("/api"), { timeout: 3000 });
 computeWithDefinedParams([1, undefined], (a, b) => a + b, 0); // 0
 ```
 
-### decorator (TS 5.0 新装饰器)
+---
 
-导入路径：`@zlikemario/helper/decorator`
+### decorator（TS 5.x 新装饰器）
+
+**导入路径**：`@zlikemario/helper/decorator`
 
 ```ts
 import { Memoize } from "@zlikemario/helper/decorator";
@@ -175,9 +201,11 @@ class A {
 }
 ```
 
-### decorator-old (旧装饰器语法)
+---
+
+### decorator-old（旧装饰器语法）
 
-导入路径：`@zlikemario/helper/decorator-old`
+**导入路径**：`@zlikemario/helper/decorator-old`
 
 ```ts
 import { Memoize } from "@zlikemario/helper/decorator-old";
@@ -190,20 +218,30 @@ class A {
 }
 ```
 
+---
+
 ### react
 
-导入路径：`@zlikemario/helper/react`
+**导入路径**：`@zlikemario/helper/react`
 
 ```ts
 import { useAsyncData, useCatchError, useLoadingEvent, useSyncedRef } from "@zlikemario/helper/react";
 ```
 
 ```ts
-const [data, refresh] = useAsyncData(fetcher, { defaultData: [], onError: () => [] });
+const [data, refresh] = useAsyncData(fetcher, {
+  defaultData: [],
+  onError: () => [],
+});
 ```
 
 ```ts
-const run = useCatchError(exec, { target: "load", timeout: 5000, onError: console.error });
+const run = useCatchError(exec, {
+  target: "load",
+  timeout: 5000,
+  onError: console.error,
+});
+
 await run("id");
 ```
 
@@ -215,20 +253,30 @@ const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall: false });
 const states = useSyncedRef({ execute, options });
 ```
 
+---
+
 ### vue
 
-导入路径：`@zlikemario/helper/vue`
+**导入路径**：`@zlikemario/helper/vue`
 
 ```ts
 import { useAsyncData, useCatchError, useLoadingEvent } from "@zlikemario/helper/vue";
 ```
 
 ```ts
-const [data, refresh] = useAsyncData(fetcher, { defaultData: [], onError: () => [] });
+const [data, refresh] = useAsyncData(fetcher, {
+  defaultData: [],
+  onError: () => [],
+});
 ```
 
 ```ts
-const run = useCatchError(exec, { target: "load", timeout: 5000, onError: console.error });
+const run = useCatchError(exec, {
+  target: "load",
+  timeout: 5000,
+  onError: console.error,
+});
+
 await run("id");
 ```
 
@@ -236,12 +284,16 @@ await run("id");
 const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall: false });
 ```
 
+---
+
 ### types
 
-导入路径：`@zlikemario/helper/types`
+**导入路径**：`@zlikemario/helper/types`
 
 ```ts
 import type {
+  IntString,
+  DecimalsString,
   Numberish,
   NumberString,
   MaybeNull,
@@ -253,20 +305,32 @@ import type {
 } from "@zlikemario/helper/types";
 ```
 
-## 4. 语义与行为约定
+---
+
+## 4. 语义与行为约定（AI 必须遵守）
+
+- 数字相关函数统一接受 `Numberish`
+- 非法数字输入通常 **直接返回 `String(input)`**，不抛异常
+- 所有高精度计算基于 `BigNumber`
+- `sum` / `sumBy` **始终返回字符串**（`NumberString`）
+- `unitFormat` 单位固定：`K / M / B`
+- `Memoize`：
+  - 默认 key = 第一个参数
+  - 支持自定义 `computeKey`
+
+---
+
+## 5. 源码位置索引（用于深挖）
 
-- 数字类函数统一接受 `Numberish`，无效输入通常返回 `String(num)`。
-- 大数计算使用 `BigNumber`，避免浮点误差。
-- `sum`/`sumBy` 返回字符串类型（`NumberString`），方便精度控制。
-- `simplifyNumber` 的单位固定为 K/M/B，保留 1 位小数。
-- `Memoize` 默认缓存 key 为第一个参数；可通过 `computeKey` 自定义。
+- `src/number.ts`
+- `src/utils.ts`
+- `src/decorator.ts`
+- `src/decorator-old.ts`
+- `src/react/*`
+- `src/vue/*`
+- `src/types.ts`
 
-## 5. 代码位置索引 (src)
+---
 
-- [src/number.ts](src/number.ts)
-- [src/utils.ts](src/utils.ts)
-- [src/decorator.ts](src/decorator.ts)
-- [src/decorator-old.ts](src/decorator-old.ts)
-- [src/react](src/react)
-- [src/vue](src/vue)
-- [src/types.ts](src/types.ts)
+> 给 AI 的最后一句话：
+> **别猜。按模块进，照例子抄。**

package/README.md

@@ -17,13 +17,13 @@ pnpm add @zlikemario/helper
 ### Number Operations
 
 ```typescript
-import { BigNumber, isNumber, simplifyNumber } from '@zlikemario/helper/number'
+import { BigNumber, isComputableNumber, unitFormat } from '@zlikemario/helper/number'
 
 // Check if a value is a number
-console.log(isNumber('123')) // true
+console.log(isComputableNumber('123')) // true
 
 // Simplify large numbers
-console.log(simplifyNumber(1234567)) // "1.2M"
+console.log(unitFormat(1234567)) // "1.2M"
 
 // Use BigNumber for precise calculations
 const result = new BigNumber('0.1').plus('0.2')
@@ -50,11 +50,11 @@ console.log(isEmail('user@example.com')) // true
 ### Number Module (`@zlikemario/helper/number`)
 
 - `BigNumber` - BigNumber.js instance for precise calculations
-- `isNumber(num, isInt?)` - Check if value is a number
-- `simplifyNumber(num, decimal?, rm?)` - Simplify large numbers (1.2K, 3.4M)
+- `trimFloatEndZero(num)` - Remove trailing zeros from decimal strings
+- `isComputableNumber(num, isInt?)` - Check if value is a computable number
+- `unitFormat(num, decimals?, rm?)` - Simplify large numbers (1.2K, 3.4M)
 - `readabilityNumber(num)` - Add thousand separators
 - `toPercentage(num, precision?, isHiddenUnit?)` - Convert to percentage
-- `formatPrecision(num, precision?)` - Format with specific precision
 - `readableNumber(num, decimals?)` - Advanced readable formatting
 - `sum(data)` - Sum array of numbers
 - `sumBy(data, key)` - Sum by object property or function

package/dist/utils.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=(e=1500)=>new Promise(r=>setTimeout(r,e));function y(e,r=4,n=4,t="..."){return!e||e.length<=r+n?e:e.slice(0,r)+t+(n?e.slice(-n):"")}const i=e=>e===void 0,h=(...e)=>e.some(i),d=e=>!!e&&typeof e?.then=="function"&&typeof e?.catch=="function";function f(e){let r="";for(let n=0;n<e.length;n++)r+=String.fromCharCode(e[n]);return btoa(r)}function g(e){const r=atob(e),n=new Uint8Array(r.length);for(let t=0;t<r.length;t++)n[t]=r.charCodeAt(t);return n}function p(e){return f(new Uint8Array(e))}function c(e){if(typeof e!="string"||(e=e.toLowerCase(),!/^[0-9a-z.\-]+$/.test(e))||e.includes("--")||e.includes("-.")||e.includes(".-")||e.startsWith("-")||e.endsWith("-"))return!1;const r=e.split(".");return!(r.length<2||r.some(n=>!n.length)||r[r.length-1].length<2)}function T(e){const[r,...n]=e.toLowerCase().split("@");if(!r||!n.length||!/^[a-z0-9._-]+$/.test(r)||/^\.|\.$/.test(r)||/[.\-_]{2,}/.test(r)||/[.\-_](?![a-z0-9])/.test(r))return!1;for(const t of n)if(!c(t))return!1;return!0}const P=async(e,r)=>{try{return await e}catch(n){return r?.(n)}};async function w(e,r){const{errorMessage:n="Timeout",timeoutError:t,timeout:s=15e3}=r||{},o=typeof e=="function"?e():e,a=s>0?new Promise((u,l)=>setTimeout(()=>l(t||new Error(n)),s)):null;try{return Promise.race(a?[o,a]:[o])}catch(u){throw u}}const A=(e,r,n)=>e.some(i)?n:r(...e);exports.arrayBufferToBase64=p;exports.base64ToUint8Array=g;exports.computeWithDefinedParams=A;exports.encrypt=y;exports.isDomain=c;exports.isEmail=T;exports.isHasUndefined=h;exports.isPromise=d;exports.isUndefined=i;exports.preventTimeout=w;exports.sleep=m;exports.tryCatchAsync=P;exports.uint8ArrayToBase64=f;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=(e=1500)=>new Promise(r=>setTimeout(r,e));function y(e,r=4,n=4,t="..."){return!e||e.length<=r+n?e:e.slice(0,r)+t+(n?e.slice(-n):"")}const i=e=>e===void 0,h=(...e)=>e.some(i),d=e=>!!e&&typeof e?.then=="function"&&typeof e?.catch=="function";function f(e){let r="";for(let n=0;n<e.length;n++)r+=String.fromCharCode(e[n]);return btoa(r)}function g(e){const r=atob(e),n=new Uint8Array(r.length);for(let t=0;t<r.length;t++)n[t]=r.charCodeAt(t);return n}function p(e){return f(new Uint8Array(e))}function c(e){if(typeof e!="string"||(e=e.toLowerCase(),!/^[0-9a-z.\-]+$/.test(e))||e.includes("--")||e.includes("-.")||e.includes(".-")||e.startsWith("-")||e.endsWith("-"))return!1;const r=e.split(".");return!(r.length<2||r.some(n=>!n.length)||r[r.length-1].length<2)}function T(e){const[r,...n]=e.toLowerCase().split("@");if(!r||!n.length||!/^[a-z0-9._-]+$/.test(r)||/^\.|\.$/.test(r)||/[.\-_]{2,}/.test(r)||/[.\-_](?![a-z0-9])/.test(r))return!1;for(const t of n)if(!c(t))return!1;return!0}const P=async(e,r)=>{try{return await(typeof e=="function"?e():e)}catch(n){return r?.(n)}};async function w(e,r){const{errorMessage:n="Timeout",timeoutError:t,timeout:o=15e3}=r||{},s=typeof e=="function"?e():e,a=o>0?new Promise((u,l)=>setTimeout(()=>l(t||new Error(n)),o)):null;try{return Promise.race(a?[s,a]:[s])}catch(u){throw u}}const A=(e,r,n)=>e.some(i)?n:r(...e);exports.arrayBufferToBase64=p;exports.base64ToUint8Array=g;exports.computeWithDefinedParams=A;exports.encrypt=y;exports.isDomain=c;exports.isEmail=T;exports.isHasUndefined=h;exports.isPromise=d;exports.isUndefined=i;exports.preventTimeout=w;exports.sleep=m;exports.tryCatchAsync=P;exports.uint8ArrayToBase64=f;

package/dist/utils.d.ts

@@ -1,7 +1,7 @@
 /**
  * 常用操作的工具函数集合
  */
-import type { MaybeUndefined } from "./types";
+import type { MaybePromise, MaybeUndefined } from "./types";
 /**
  * 延迟指定的时间间隔（毫秒）
  * @param interval - 延迟的毫秒数，默认 1500ms
@@ -70,10 +70,10 @@ export declare function isDomain(text: string): boolean;
 export declare function isEmail(text: string): boolean;
 /**
  * 异步 try-catch 包装器
- * @param p - 要执行的 Promise
+ * @param p - 要执行的 Promise ｜ (() => any)
  * @param catchFn - 可选的错误处理函数
  */
-export declare const tryCatchAsync: <T, FR = any, F extends ((error: unknown) => FR) | undefined = undefined>(p: Promise<T>, catchFn?: F) => Promise<T | (F extends Function ? FR : undefined)>;
+export declare const tryCatchAsync: <T, FR = any, F extends ((error: unknown) => FR) | undefined = undefined>(p: (() => MaybePromise<T>) | MaybePromise<T>, catchFn?: F) => Promise<T | (F extends Function ? FR : undefined)>;
 /**
  * 执行回调函数或 Promise，并确保在指定的超时时间内完成
  * 如果操作未能及时完成，返回的 Promise 将以超时错误被拒绝

package/dist/utils.js

@@ -1,19 +1,19 @@
-const m = (e = 1500) => new Promise((r) => setTimeout(r, e));
-function h(e, r = 4, n = 4, t = "...") {
-  return !e || e.length <= r + n ? e : e.slice(0, r) + t + (n ? e.slice(-n) : "");
+const m = (e = 1500) => new Promise((n) => setTimeout(n, e));
+function h(e, n = 4, r = 4, t = "...") {
+  return !e || e.length <= n + r ? e : e.slice(0, n) + t + (r ? e.slice(-r) : "");
 }
 const a = (e) => e === void 0, y = (...e) => e.some(a), d = (e) => !!e && typeof e?.then == "function" && typeof e?.catch == "function";
 function c(e) {
-  let r = "";
-  for (let n = 0; n < e.length; n++)
-    r += String.fromCharCode(e[n]);
-  return btoa(r);
+  let n = "";
+  for (let r = 0; r < e.length; r++)
+    n += String.fromCharCode(e[r]);
+  return btoa(n);
 }
 function g(e) {
-  const r = atob(e), n = new Uint8Array(r.length);
-  for (let t = 0; t < r.length; t++)
-    n[t] = r.charCodeAt(t);
-  return n;
+  const n = atob(e), r = new Uint8Array(n.length);
+  for (let t = 0; t < n.length; t++)
+    r[t] = n.charCodeAt(t);
+  return r;
 }
 function p(e) {
   return c(new Uint8Array(e));
@@ -21,34 +21,34 @@ function p(e) {
 function l(e) {
   if (typeof e != "string" || (e = e.toLowerCase(), !/^[0-9a-z.\-]+$/.test(e)) || e.includes("--") || e.includes("-.") || e.includes(".-") || e.startsWith("-") || e.endsWith("-"))
     return !1;
-  const r = e.split(".");
-  return !(r.length < 2 || r.some((n) => !n.length) || r[r.length - 1].length < 2);
+  const n = e.split(".");
+  return !(n.length < 2 || n.some((r) => !r.length) || n[n.length - 1].length < 2);
 }
 function w(e) {
-  const [r, ...n] = e.toLowerCase().split("@");
-  if (!r || !n.length || !/^[a-z0-9._-]+$/.test(r) || /^\.|\.$/.test(r) || /[.\-_]{2,}/.test(r) || /[.\-_](?![a-z0-9])/.test(r)) return !1;
-  for (const t of n)
+  const [n, ...r] = e.toLowerCase().split("@");
+  if (!n || !r.length || !/^[a-z0-9._-]+$/.test(n) || /^\.|\.$/.test(n) || /[.\-_]{2,}/.test(n) || /[.\-_](?![a-z0-9])/.test(n)) return !1;
+  for (const t of r)
     if (!l(t)) return !1;
   return !0;
 }
-const P = async (e, r) => {
+const P = async (e, n) => {
   try {
-    return await e;
-  } catch (n) {
-    return r?.(n);
+    return await (typeof e == "function" ? e() : e);
+  } catch (r) {
+    return n?.(r);
   }
 };
-async function T(e, r) {
-  const { errorMessage: n = "Timeout", timeoutError: t, timeout: o = 15e3 } = r || {}, s = typeof e == "function" ? e() : e, i = o > 0 ? new Promise(
-    (u, f) => setTimeout(() => f(t || new Error(n)), o)
+async function T(e, n) {
+  const { errorMessage: r = "Timeout", timeoutError: t, timeout: o = 15e3 } = n || {}, i = typeof e == "function" ? e() : e, s = o > 0 ? new Promise(
+    (u, f) => setTimeout(() => f(t || new Error(r)), o)
   ) : null;
   try {
-    return Promise.race(i ? [s, i] : [s]);
+    return Promise.race(s ? [i, s] : [i]);
   } catch (u) {
     throw u;
   }
 }
-const A = (e, r, n) => e.some(a) ? n : r(...e);
+const A = (e, n, r) => e.some(a) ? r : n(...e);
 export {
   p as arrayBufferToBase64,
   g as base64ToUint8Array,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlikemario/helper",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A utility library with number operations and common helper functions",
   "keywords": [
     "utility",