@zlikemario/helper 0.0.15 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# @zlikemario/helper - Agents Guide
+
+本文件是 **AI 代理的入口说明**，用于快速判断你在这个仓库中的角色，以及接下来应该阅读的文档。
+
+## 这个库是做什么的？
+
+这是一个【TypeScript 工具库，提供数字处理、常用工具函数、装饰器，以及 React/Vue 的 hooks】的库。
+AI 在参与任务前，应先明确自己的身份，再继续操作。
+
+---
+
+## 第一步：确认你的角色
+
+### 你只是**使用这个库**
+
+- 场景：调用 API、集成到项目中、写业务代码
+- 请直接阅读 👉 **[AGENTS_USE](./AGENTS_USE.md)**  
+  这里说明：
+  - 这个库解决什么问题
+  - 提供了哪些能力
+  - 正确的使用方式与约束
+
+### 你需要**修改或扩展这个库**
+
+- 场景：新增功能、调整实现、修 Bug、重构
+- 请先完整阅读 👉 **[AGENTS_CODING](./AGENTS_CODING.md)**  
+  这里定义：
+  - 代码规范与结构约定
+  - 允许与禁止的改动范围
+  - 提交前必须遵守的规则
+
+---
+
+## 重要约定
+
+在未阅读对应文档前，不要开始写代码。

package/AGENTS_USE.md

@@ -0,0 +1,272 @@
+# @zlikemario/helper - Agents Guide (Use)
+
+面向“使用这个库”的 AI。目标：用最少 token 快速定位方法 + 看到即用的示例。
+
+## 1. 快速入口
+
+- 默认入口：`@zlikemario/helper` 等价于 `@zlikemario/helper/number`
+- 子路径入口：`/number`、`/utils`、`/decorator`、`/decorator-old`、`/react`、`/vue`、`/types`
+
+## 2. 方法速查（只列名称，先定位，再看下面示例）
+
+### number
+
+`BigNumber` `isNumber` `simplifyNumber` `readabilityNumber` `toPercentage` `formatPrecision` `readableNumber` `sum` `sumBy`
+
+### utils
+
+`sleep` `encrypt` `isUndefined` `isHasUndefined` `isPromise` `uint8ArrayToBase64` `base64ToUint8Array` `arrayBufferToBase64` `isDomain` `isEmail` `tryCatchAsync` `preventTimeout` `computeWithDefinedParams`
+
+### decorator
+
+`Memoize`
+
+### decorator-old
+
+`Memoize`
+
+### react
+
+`useAsyncData` `useCatchError` `useLoadingEvent` `useSyncedRef`
+
+### vue
+
+`useAsyncData` `useCatchError` `useLoadingEvent`
+
+### types
+
+`Numberish` `NumberString` `MaybeNull` `MaybeUndefined` `MaybePromise` `Defined` `AnyFn` `Noop`
+
+## 3. 用法速览（按模块分组，一函数一用法）
+
+### number
+
+导入路径：`@zlikemario/helper/number`
+
+```ts
+import {
+  BigNumber,
+  isNumber,
+  simplifyNumber,
+  readabilityNumber,
+  toPercentage,
+  formatPrecision,
+  readableNumber,
+  sum,
+  sumBy,
+} from "@zlikemario/helper/number";
+```
+
+```ts
+isNumber("123");
+isNumber("12.3", true);
+```
+
+```ts
+simplifyNumber(1234567); // "1.2M"
+simplifyNumber("999", 2); // "999"
+```
+
+```ts
+readabilityNumber(1234567.89); // "1,234,567.89"
+```
+
+```ts
+toPercentage(0.1234); // "12.34%"
+toPercentage(0.1234, 1, true); // "12.3"
+```
+
+```ts
+formatPrecision("1.234567", 2); // "1.23"
+```
+
+```ts
+readableNumber("1234.0000123", 4); // "1,234.0{4}12"
+```
+
+```ts
+sum(["0.1", 0.2, 0.3]); // "0.6"
+```
+
+```ts
+sumBy([{ n: 1 }, { n: 2 }], "n"); // "3"
+sumBy([{ n: 1 }, { n: 2 }], (item) => item.n * 2); // "6"
+```
+
+```ts
+const v = new BigNumber("0.1").plus("0.2");
+v.toString(); // "0.3"
+```
+
+### utils
+
+导入路径：`@zlikemario/helper/utils`
+
+```ts
+import {
+  sleep,
+  encrypt,
+  isUndefined,
+  isHasUndefined,
+  isPromise,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  arrayBufferToBase64,
+  isDomain,
+  isEmail,
+  tryCatchAsync,
+  preventTimeout,
+  computeWithDefinedParams,
+} from "@zlikemario/helper/utils";
+```
+
+```ts
+await sleep(1000);
+```
+
+```ts
+encrypt("1234567890", 2, 2); // "12...90"
+```
+
+```ts
+isUndefined(undefined); // true
+isHasUndefined(1, undefined, 3); // true
+```
+
+```ts
+isPromise(Promise.resolve(1)); // true
+```
+
+```ts
+uint8ArrayToBase64(new Uint8Array([1, 2, 3]));
+base64ToUint8Array("AQID");
+arrayBufferToBase64(new Uint8Array([1, 2, 3]).buffer);
+```
+
+```ts
+isDomain("example.com"); // true
+isEmail("user@example.com"); // true
+```
+
+```ts
+const data = await tryCatchAsync(fetch("/api").then((r) => r.json()));
+```
+
+```ts
+await preventTimeout(fetch("/api"), { timeout: 3000 });
+```
+
+```ts
+computeWithDefinedParams([1, undefined], (a, b) => a + b, 0); // 0
+```
+
+### decorator (TS 5.0 新装饰器)
+
+导入路径：`@zlikemario/helper/decorator`
+
+```ts
+import { Memoize } from "@zlikemario/helper/decorator";
+
+class A {
+  @Memoize(1000)
+  calc(n: number) {
+    return n * 2;
+  }
+}
+```
+
+### decorator-old (旧装饰器语法)
+
+导入路径：`@zlikemario/helper/decorator-old`
+
+```ts
+import { Memoize } from "@zlikemario/helper/decorator-old";
+
+class A {
+  @Memoize(1000)
+  calc(n: number) {
+    return n * 2;
+  }
+}
+```
+
+### react
+
+导入路径：`@zlikemario/helper/react`
+
+```ts
+import { useAsyncData, useCatchError, useLoadingEvent, useSyncedRef } from "@zlikemario/helper/react";
+```
+
+```ts
+const [data, refresh] = useAsyncData(fetcher, { defaultData: [], onError: () => [] });
+```
+
+```ts
+const run = useCatchError(exec, { target: "load", timeout: 5000, onError: console.error });
+await run("id");
+```
+
+```ts
+const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall: false });
+```
+
+```ts
+const states = useSyncedRef({ execute, options });
+```
+
+### vue
+
+导入路径：`@zlikemario/helper/vue`
+
+```ts
+import { useAsyncData, useCatchError, useLoadingEvent } from "@zlikemario/helper/vue";
+```
+
+```ts
+const [data, refresh] = useAsyncData(fetcher, { defaultData: [], onError: () => [] });
+```
+
+```ts
+const run = useCatchError(exec, { target: "load", timeout: 5000, onError: console.error });
+await run("id");
+```
+
+```ts
+const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall: false });
+```
+
+### types
+
+导入路径：`@zlikemario/helper/types`
+
+```ts
+import type {
+  Numberish,
+  NumberString,
+  MaybeNull,
+  MaybeUndefined,
+  MaybePromise,
+  Defined,
+  AnyFn,
+  Noop,
+} from "@zlikemario/helper/types";
+```
+
+## 4. 语义与行为约定
+
+- 数字类函数统一接受 `Numberish`，无效输入通常返回 `String(num)`。
+- 大数计算使用 `BigNumber`，避免浮点误差。
+- `sum`/`sumBy` 返回字符串类型（`NumberString`），方便精度控制。
+- `simplifyNumber` 的单位固定为 K/M/B，保留 1 位小数。
+- `Memoize` 默认缓存 key 为第一个参数；可通过 `computeKey` 自定义。
+
+## 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)

package/dist/react/useAsyncData.d.ts

@@ -1,4 +1,14 @@
 import type { MaybeUndefined } from "../types";
+/**
+ * 用于加载异步数据并提供手动刷新能力的 React hook。
+ *
+ * 用法：
+ * const [data, refresh] = useAsyncData(fetcher, { defaultData, onError });
+ *
+ * - 组件挂载时调用一次 `fetcher`
+ * - 返回最新数据与刷新函数
+ * - 若提供 `onError`，其返回值会作为数据
+ */
 declare const useAsyncData: <R>(getDataFunc: () => Promise<R>, options?: Partial<{
     defaultData: R;
     onError: (error: unknown) => any;

package/dist/react/useCatchError.d.ts

@@ -1,4 +1,14 @@
 import type { MaybePromise, MaybeUndefined } from "../types";
+/**
+ * 包装异步/同步任务，统一超时与错误处理。
+ *
+ * 用法：
+ * const run = useCatchError(exec, { target, timeout, isThrowError, onError });
+ *
+ * - 支持超时控制
+ * - 可选择是否继续抛错
+ * - onError 可用于埋点或兜底处理
+ */
 declare const useCatchError: <Args extends any[], R, IsThrowError extends boolean = false>(execute: (...args: Args) => MaybePromise<R>, options?: Partial<{
     target: string;
     timeout: number;

package/dist/react/useLoadingEvent.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 包装异步执行函数，返回带 loading 状态的调用器。
+ *
+ * 用法：
+ * const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall });
+ *
+ * - 默认不允许并发，重复调用会复用上一次 Promise
+ * - 可通过 isAllowMulticall 允许并发调用
+ */
 declare const useLoadingEvent: <Args extends any[], R extends any>(execute: (...args: Args) => Promise<R>, options?: Partial<{
     isAllowMulticall: boolean;
 }>) => [(...args: Args) => Promise<R>, boolean];

package/dist/react/useSyncedRef.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 创建一个只读 ref，并始终同步最新的值。
+ *
+ * 用法：
+ * const states = useSyncedRef({ execute, options });
+ */
 declare const useSyncedRef: <T>(value: T) => Readonly<{
     readonly current: T;
 }>;

package/dist/utils.cjs

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

package/dist/utils.js

@@ -1,62 +1,66 @@
-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 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 o = (e) => e === void 0, y = (...e) => e.some(o), d = (e) => !!e && typeof e?.then == "function" && typeof e?.catch == "function";
-function f(e) {
-  let n = "";
-  for (let r = 0; r < e.length; r++)
-    n += String.fromCharCode(e[r]);
-  return btoa(n);
+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);
 }
 function g(e) {
-  const n = atob(e), r = new Uint8Array(n.length);
-  for (let t = 0; t < n.length; t++)
-    r[t] = n.charCodeAt(t);
-  return r;
+  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));
+  return c(new Uint8Array(e));
 }
-function c(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 n = e.split(".");
-  return !(n.length < 2 || n.some((r) => !r.length) || n[n.length - 1].length < 2);
+  const r = e.split(".");
+  return !(r.length < 2 || r.some((n) => !n.length) || r[r.length - 1].length < 2);
 }
 function w(e) {
-  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 (!c(t)) return !1;
+  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 (!l(t)) return !1;
   return !0;
 }
-const P = async (e, n) => {
+const P = async (e, r) => {
   try {
     return await e;
-  } catch (r) {
-    return n?.(r);
+  } catch (n) {
+    return r?.(n);
   }
 };
-async function T(e, n) {
-  const { errorMessage: r = "Timeout", timeoutError: t, timeout: s = 15e3 } = n || {}, i = typeof e == "function" ? e() : e, u = new Promise(
-    (l, a) => setTimeout(() => a(t || new Error(r)), s)
-  );
-  return Promise.race([i, u]);
+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)
+  ) : null;
+  try {
+    return Promise.race(i ? [s, i] : [s]);
+  } catch (u) {
+    throw u;
+  }
 }
-const A = (e, n, r) => e.some(o) ? r : n(...e);
+const A = (e, r, n) => e.some(a) ? n : r(...e);
 export {
   p as arrayBufferToBase64,
   g as base64ToUint8Array,
   A as computeWithDefinedParams,
   h as encrypt,
-  c as isDomain,
+  l as isDomain,
   w as isEmail,
   y as isHasUndefined,
   d as isPromise,
-  o as isUndefined,
+  a as isUndefined,
   T as preventTimeout,
   m as sleep,
   P as tryCatchAsync,
-  f as uint8ArrayToBase64
+  c as uint8ArrayToBase64
 };

package/dist/vue/useAsyncData.d.ts

@@ -1,5 +1,15 @@
 import { type ComputedRef, type MaybeRef } from "vue";
 import type { MaybeUndefined } from "../types";
+/**
+ * 用于加载异步数据并提供手动刷新能力的 Vue hook。
+ *
+ * 用法：
+ * const [data, refresh] = useAsyncData(fetcher, { defaultData, onError });
+ *
+ * - 立即执行一次 `fetcher`
+ * - 返回计算属性与刷新函数
+ * - 若提供 `onError`，其返回值会作为数据
+ */
 declare const useAsyncData: <R>(getDataFunc: () => Promise<R>, options?: Partial<{
     defaultData: MaybeRef<R>;
     onError: (error: unknown) => any;

package/dist/vue/useCatchError.d.ts

@@ -1,4 +1,14 @@
 import type { MaybePromise, MaybeUndefined } from "../types";
+/**
+ * 包装异步/同步任务，统一超时与错误处理。
+ *
+ * 用法：
+ * const run = useCatchError(exec, { target, timeout, isThrowError, onError });
+ *
+ * - 支持超时控制
+ * - 可选择是否继续抛错
+ * - onError 可用于埋点或兜底处理
+ */
 declare const useCatchError: <Args extends any[], R, IsThrowError extends boolean = false>(execute: (...args: Args) => MaybePromise<R>, options?: Partial<{
     target: string;
     timeout: number;

package/dist/vue/useLoadingEvent.d.ts

@@ -1,4 +1,13 @@
 import { type ComputedRef } from "vue";
+/**
+ * 包装异步执行函数，返回带 loading 状态的调用器。
+ *
+ * 用法：
+ * const [run, isLoading] = useLoadingEvent(exec, { isAllowMulticall });
+ *
+ * - 默认不允许并发，重复调用会复用上一次 Promise
+ * - 可通过 isAllowMulticall 允许并发调用
+ */
 declare const useLoadingEvent: <Args extends any[], R extends any>(execute: (...args: Args) => Promise<R>, options?: Partial<{
     isAllowMulticall: boolean;
 }>) => [(...args: Args) => Promise<R>, ComputedRef<boolean>];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlikemario/helper",
-  "version": "0.0.15",
+  "version": "1.0.0",
   "description": "A utility library with number operations and common helper functions",
   "keywords": [
     "utility",
@@ -13,7 +13,9 @@
   "type": "module",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "AGENTS_USE.md"
   ],
   "repository": {
     "type": "git",
@@ -86,7 +88,6 @@
   },
   "packageManager": "yarn@4.9.4+sha512.7b1cb0b62abba6a537b3a2ce00811a843bea02bcf53138581a6ae5b1bf563f734872bd47de49ce32a9ca9dcaff995aa789577ffb16811da7c603dcf69e73750b",
   "dependencies": {
-    "bignumber.js": "^9.3.1",
-    "dayjs": "^1.11.18"
+    "bignumber.js": "^9.3.1"
   }
 }