@zlikemario/helper 0.0.1

package/README.md

@@ -0,0 +1,79 @@
+# @zlikemario/helper
+
+A utility library with number operations and common helper functions.
+
+## Installation
+
+```bash
+npm install @zlikemario/helper
+# or
+yarn add @zlikemario/helper
+# or
+pnpm add @zlikemario/helper
+```
+
+## Usage
+
+### Number Operations
+
+```typescript
+import { BigNumber, isNumber, simplifyNumber } from '@zlikemario/helper/number'
+
+// Check if a value is a number
+console.log(isNumber('123')) // true
+
+// Simplify large numbers
+console.log(simplifyNumber(1234567)) // "1.2M"
+
+// Use BigNumber for precise calculations
+const result = new BigNumber('0.1').plus('0.2')
+console.log(result.toString()) // "0.3"
+```
+
+### Utility Functions
+
+```typescript
+import { sleep, encrypt, isEmail } from '@zlikemario/helper/utils'
+
+// Sleep function
+await sleep(1000) // Wait for 1 second
+
+// Encrypt sensitive data
+console.log(encrypt('1234567890', 2, 2)) // "12****90"
+
+// Validate email
+console.log(isEmail('user@example.com')) // true
+```
+
+## API Reference
+
+### 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)
+- `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
+
+### Utils Module (`@zlikemario/helper/utils`)
+
+- `sleep(interval?)` - Async sleep function
+- `encrypt(text, prefix?, suffix?, placeholder?)` - Mask sensitive data
+- `isUndefined(v)` - Check if value is undefined
+- `isHasUndefined(...vs)` - Check if any value is undefined
+- `isPromise(v)` - Check if value is a Promise
+- `uint8ArrayToBase64(array)` - Convert Uint8Array to Base64
+- `base64ToUint8Array(base64)` - Convert Base64 to Uint8Array
+- `arrayBufferToBase64(buffer)` - Convert ArrayBuffer to Base64
+- `isDomain(text)` - Validate domain name
+- `isEmail(text)` - Validate email address
+- `tryCatchAsync(p, catchFn?)` - Async try-catch wrapper
+- `preventTimeout(callback, options?)` - Execute with timeout protection
+
+## License
+
+MIT

package/dist/number.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("bignumber.js");i.config({EXPONENTIAL_AT:99});function s(e,t=!1){if(!["string","number","bigint"].includes(typeof e))return!1;try{e=i(e).toFixed()}catch{return!1}return t?/^-?\d+$/.test(e):/^-?\d+(\.\d+)?$/.test(e)}function l(e,t=3,n=i.ROUND_HALF_UP){if(!s(e))return String(e);const r=1e3;let o=i(e);if(o.abs().lt(r))return o.toFixed(t,n).replace(/\.0+$/,"");const u=["","K","M","B"];let a=0;for(;++a<u.length&&(o=o.div(r),!o.abs().lt(r)););return o.toFixed(1,n)+u[a]}function c(e){return s(e)?i(e).toFormat({decimalSeparator:".",groupSeparator:",",groupSize:3}):String(e)}function f(e,t=2,n=!1){if(!s(e))return String(e);const r=i(e).times(100).toFixed(t);return parseFloat(r)+(n?"":"%")}function g(e,t=4){return s(e)?i(e).dp(t).toString():String(e)}const d=(e,t=4)=>{if(!s(e))return String(e);const n=i(e).toFixed().match(/(-?)(\d+)\.(0+)(\d+)/);if(!n)return c(i(e).dp(t).toFixed());const[,r,o,u,a]=n;return u.length>3?`${r}${c(o)}.0{${u.length}}${a.slice(0,t-2).replace(/0+$/,"")}`:`${r}${c(o)}.${u}${a.slice(0,t-2).replace(/0+$/,"")}`},b=e=>e.reduce((t,n)=>t.plus(n),i(0)).toString();function p(e,t){const n=typeof t=="function"?r=>t(r):r=>r?.[t]??"0";return e.reduce((r,o)=>r.plus(n(o)),i(0)).toString()}exports.BigNumber=i;exports.default=i;exports.formatPrecision=g;exports.isNumber=s;exports.readabilityNumber=c;exports.readableNumber=d;exports.simplifyNumber=l;exports.sum=b;exports.sumBy=p;exports.toPercentage=f;

package/dist/number.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 数字相关工具函数
+ */
+import BigNumber from "bignumber.js";
+export { BigNumber };
+export default BigNumber;
+export type Numberish = string | number | bigint | BigNumber;
+export type NumberString = string;
+export type MaybeUndefined<T> = T | undefined;
+/**
+ * 判断是否为有效数字
+ * @param num - 待判断的值
+ * @param isInt - 是否要求为整数
+ * @returns 是否为数字
+ */
+export declare function isNumber(num: any, isInt?: boolean): boolean;
+/**
+ * 数字简化显示（如 1.2K, 3.4M）
+ * @param num - 数字
+ * @param decimal - 保留小数位
+ * @param rm - 舍入模式
+ * @returns 简化后的字符串
+ */
+export declare function simplifyNumber(num: Numberish, decimal?: number, rm?: BigNumber.RoundingMode): string;
+/**
+ * 数字千分位分隔显示
+ * @param num - 数字
+ * @returns 格式化后的字符串
+ */
+export declare function readabilityNumber(num: Numberish): string;
+/**
+ * 转为百分比字符串
+ * @param num - 数字
+ * @param precision - 保留小数位
+ * @param isHiddenUnit - 是否隐藏百分号
+ * @returns 百分比字符串
+ */
+export declare function toPercentage(num: Numberish, precision?: number, isHiddenUnit?: boolean): string;
+/**
+ * 保留指定精度
+ * @param num - 数字
+ * @param precision - 保留小数位
+ * @returns 格式化后的字符串
+ */
+export declare function formatPrecision(num: Numberish, precision?: number): string;
+/**
+ * 高级可读性数字格式化（如 1,234.0{4}1）
+ * @param number - 数字
+ * @param decimals - 保留小数位
+ * @returns 格式化后的字符串
+ */
+export declare const readableNumber: (number: Numberish, decimals?: number) => string;
+/**
+ * 数组求和
+ * @param data - 数字数组
+ * @returns 求和结果字符串
+ */
+export declare const sum: (data: Array<Numberish>) => string;
+/**
+ * 按 key 或函数求和
+ * @param data - 对象数组
+ * @param key - 属性名或函数
+ * @returns 求和结果字符串
+ */
+export declare function sumBy<T, K extends keyof T>(data: T[], key: T[K] extends MaybeUndefined<Numberish> ? K : never): NumberString;
+export declare function sumBy<T>(data: T[], key: (item: T) => Numberish): NumberString;

package/dist/number.js

@@ -0,0 +1,65 @@
+import o from "bignumber.js";
+import { default as N, default as x } from "bignumber.js";
+o.config({ EXPONENTIAL_AT: 99 });
+function a(t, e = !1) {
+  if (!["string", "number", "bigint"].includes(typeof t)) return !1;
+  try {
+    t = o(t).toFixed();
+  } catch {
+    return !1;
+  }
+  return e ? /^-?\d+$/.test(t) : /^-?\d+(\.\d+)?$/.test(t);
+}
+function l(t, e = 3, i = o.ROUND_HALF_UP) {
+  if (!a(t)) return String(t);
+  const r = 1e3;
+  let n = o(t);
+  if (n.abs().lt(r)) return n.toFixed(e, i).replace(/\.0+$/, "");
+  const s = ["", "K", "M", "B"];
+  let u = 0;
+  for (; ++u < s.length && (n = n.div(r), !n.abs().lt(r)); )
+    ;
+  return n.toFixed(1, i) + s[u];
+}
+function c(t) {
+  return a(t) ? o(t).toFormat({
+    decimalSeparator: ".",
+    groupSeparator: ",",
+    groupSize: 3
+  }) : String(t);
+}
+function g(t, e = 2, i = !1) {
+  if (!a(t)) return String(t);
+  const r = o(t).times(100).toFixed(e);
+  return parseFloat(r) + (i ? "" : "%");
+}
+function d(t, e = 4) {
+  return a(t) ? o(t).dp(e).toString() : String(t);
+}
+const p = (t, e = 4) => {
+  if (!a(t)) return String(t);
+  const i = o(t).toFixed().match(/(-?)(\d+)\.(0+)(\d+)/);
+  if (!i)
+    return c(o(t).dp(e).toFixed());
+  const [, r, n, s, u] = i;
+  return s.length > 3 ? `${r}${c(n)}.0{${s.length}}${u.slice(0, e - 2).replace(/0+$/, "")}` : `${r}${c(n)}.${s}${u.slice(0, e - 2).replace(/0+$/, "")}`;
+}, $ = (t) => t.reduce((e, i) => e.plus(i), o(0)).toString();
+function b(t, e) {
+  const i = typeof e == "function" ? (r) => e(r) : (r) => r?.[e] ?? "0";
+  return t.reduce(
+    (r, n) => r.plus(i(n)),
+    o(0)
+  ).toString();
+}
+export {
+  N as BigNumber,
+  x as default,
+  d as formatPrecision,
+  a as isNumber,
+  c as readabilityNumber,
+  p as readableNumber,
+  l as simplifyNumber,
+  $ as sum,
+  b as sumBy,
+  g as toPercentage
+};

package/dist/utils.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=(e=1500)=>new Promise(n=>setTimeout(n,e));function l(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),m=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 d(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 h(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 g(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 p=async(e,n)=>{try{return await e}catch(r){return n?.(r)}};async function T(e,n){const{errorMessage:r="Timeout",duration:t=15e3}=n||{},a=typeof e=="function"?e():e,u=new Promise((A,f)=>setTimeout(()=>f(new Error(r)),t));return Promise.race([a,u])}exports.arrayBufferToBase64=h;exports.base64ToUint8Array=d;exports.encrypt=l;exports.isDomain=o;exports.isEmail=g;exports.isHasUndefined=y;exports.isPromise=m;exports.isUndefined=i;exports.preventTimeout=T;exports.sleep=c;exports.tryCatchAsync=p;exports.uint8ArrayToBase64=s;

package/dist/utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Utility functions for common operations.
+ */
+/**
+ * Sleep for a specified interval (ms).
+ * @param interval - Time in milliseconds to sleep. Default: 1500ms.
+ */
+export declare const sleep: (interval?: number) => Promise<void>;
+/**
+ * Encrypts a string by masking the middle part.
+ * @param text - The input string.
+ * @param prefix - Number of characters to keep at the start.
+ * @param suffix - Number of characters to keep at the end.
+ * @param placeholder - Masking string. Default: '...'.
+ * @returns Masked string.
+ */
+export declare function encrypt(text: string, prefix?: number, suffix?: number, placeholder?: string): string;
+/**
+ * Checks if a value is undefined.
+ * @param v - Value to check.
+ */
+export declare const isUndefined: (v: unknown) => v is undefined;
+/**
+ * Checks if any of the provided values are undefined.
+ * @param vs - Values to check.
+ */
+export declare const isHasUndefined: (...vs: unknown[]) => boolean;
+/**
+ * Checks if a value is a Promise.
+ * @param v - Value to check.
+ */
+export declare const isPromise: <T = any>(v: unknown) => v is Promise<T>;
+/**
+ * Converts a Uint8Array to a Base64 string.
+ * @param array - Uint8Array to convert.
+ */
+export declare function uint8ArrayToBase64(array: Uint8Array): string;
+/**
+ * Converts a Base64 string to a Uint8Array.
+ * @param base64 - Base64 string to convert.
+ */
+export declare function base64ToUint8Array(base64: string): Uint8Array;
+/**
+ * Converts an ArrayBuffer to a Base64 string.
+ * @param buffer - ArrayBuffer to convert.
+ */
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+/**
+ * Validates a domain name.
+ * Rules:
+ * 1. Only numbers, letters, and hyphens allowed.
+ * 2. Composed of one or more parts separated by dots.
+ * 3. Last part must be at least two characters.
+ * 4. Cannot start or end with a hyphen.
+ * 5. No consecutive hyphens or hyphen-dot/dot-hyphen.
+ * @param text - Domain string to validate.
+ */
+export declare function isDomain(text: string): boolean;
+/**
+ * Validates an email address.
+ * Rules:
+ * 1. Account part: letters, numbers, _, -, . allowed.
+ * 2. No leading/trailing dot.
+ * 3. No consecutive special characters.
+ * 4. Special character must be followed by at least one letter/number.
+ * 5. Domain part must be valid.
+ * @param text - Email string to validate.
+ */
+export declare function isEmail(text: string): boolean;
+/**
+ * Async try-catch wrapper.
+ * @param p - Promise to execute.
+ * @param catchFn - Optional error handler.
+ */
+export declare const tryCatchAsync: <T, F extends ((error: unknown) => any) | undefined = undefined>(p: Promise<T>, catchFn?: F) => Promise<T | (F extends (...args: any) => any ? ReturnType<F> : undefined)>;
+/**
+ * Executes a callback or promise and ensures it completes within a specified timeout duration.
+ * If the operation does not finish in time, the returned promise is rejected with a timeout error.
+ *
+ * @template R The type of the resolved value.
+ * @param callback - A function returning a promise or a promise to execute.
+ * @param options - Optional settings for timeout behavior.
+ * @param options.errorMessage - Custom error message for timeout rejection. Defaults to "Timeout".
+ * @param options.duration - Timeout duration in milliseconds. Defaults to 15000 ms.
+ * @returns A promise that resolves with the result of the callback or rejects if the timeout is reached.
+ */
+export declare function preventTimeout<R>(callback: (() => Promise<R>) | Promise<R>, options?: {
+    errorMessage?: string;
+    duration?: number;
+}): Promise<R>;

package/dist/utils.js

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

package/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@zlikemario/helper",
+  "version": "0.0.1",
+  "description": "A utility library with number operations and common helper functions",
+  "keywords": [
+    "utility",
+    "number",
+    "helper",
+    "typescript"
+  ],
+  "author": "zlikemario",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zlikemario/helper.git"
+  },
+  "homepage": "https://github.com/zlikemario/helper#readme",
+  "bugs": {
+    "url": "https://github.com/zlikemario/helper/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "preview": "vite preview",
+    "test": "vitest",
+    "prepublishOnly": "yarn build",
+    "publish": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "bignumber.js": "^9.3.1",
+    "dayjs": "^1.11.18",
+    "node": "^24.8.0",
+    "typescript": "~5.8.3",
+    "vite": "^7.1.2",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "exports": {
+    "./number": {
+      "types": "./dist/number.d.ts",
+      "import": "./dist/number.js",
+      "require": "./dist/number.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js",
+      "require": "./dist/utils.cjs"
+    }
+  },
+  "packageManager": "yarn@4.9.4+sha512.7b1cb0b62abba6a537b3a2ce00811a843bea02bcf53138581a6ae5b1bf563f734872bd47de49ce32a9ca9dcaff995aa789577ffb16811da7c603dcf69e73750b",
+  "peerDependencies": {
+    "bignumber.js": "*",
+    "dayjs": "*"
+  }
+}