@base-web-kits/base-tools-ts 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base-web-kits/base-tools-ts",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "sideEffects": false,
   "description": "Independent TS utilities package built from src/ts.",
   "keywords": [

package/src/ts/array/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 拖拽排序 (不改变原数组)
+ * @param list 原始数组
+ * @param fromIndex 要移动的元素的原始索引
+ * @param toIndex 要移动到的目标索引
+ * @returns 移动元素后的新数组
+ */
+export function arrayMove<T>(list: T[], fromIndex: number, toIndex: number) {
+  const newList = [...list]; // 创建新数组副本
+  const [removed] = newList.splice(fromIndex, 1); // 移除 fromIndex 处的元素
+  newList.splice(toIndex, 0, removed); // 插入到 toIndex 处
+  return newList;
+}

package/src/ts/async/index.ts

@@ -0,0 +1,20 @@
+/**
+ * 将 Promise 包装为 [data, error] 形式, 减少 try-catch 代码量
+ * @param p 要包装的 Promise
+ * @returns 一个 Promise，其结果为 [data, error] 形式
+ * @example
+ * const [data, err] = await toAsync(fetch('https://api.example.com/data'));
+ * if (err) {
+ *   console.error(err);
+ *   return;
+ * }
+ * console.log(data);
+ */
+export async function toAsync<T>(p: Promise<T>): Promise<[T | null, unknown]> {
+  try {
+    const data = await p;
+    return [data, null];
+  } catch (err) {
+    return [null, err];
+  }
+}

package/src/ts/bean/EventBus.ts

@@ -0,0 +1,61 @@
+import mitt, { type Emitter, type EventType } from 'mitt';
+
+type Events = Record<EventType, unknown>;
+
+/**
+ * 总线式发布订阅
+ * @example
+ * const emitter = new EventBus(); // 支持链式调用
+ * emitter.on('xx', fn); // 订阅事件 xx
+ * emitter.once('xx', fn); // 订阅事件 xx 一次
+ * emitter.emit('xx', any); // 发布事件 xx，参数任意
+ * emitter.off('xx'); // 移除事件 xx 下全部监听
+ * emitter.off('xx', fn); // 移除事件 xx 下指定监听
+ * emitter.clear(); // 移除所有事件
+ *
+ * @example 类型约束
+ * type T = { a: number; b: string };
+ * const emitter = new EventBus<{ xx: T; yy: void }>();
+ * const fn = (arg: T) => {}
+ * emitter.on('xx', fn);
+ * emitter.off('xx', fn);
+ * emitter.emit('xx', { a: 123, b: '123' });
+ * emitter.emit('yy');
+ */
+export class EventBus<T extends Events = Events> {
+  private readonly _emitter: Emitter<T> = mitt<T>();
+
+  /** 订阅 */
+  on<K extends keyof T>(type: K, fn: (event: T[K]) => void): this {
+    this._emitter.on(type, fn);
+    return this;
+  }
+
+  /** 订阅一次 */
+  once<K extends keyof T>(type: K, fn: (event: T[K]) => void): this {
+    const wrap = (event: T[K]) => {
+      this._emitter.off(type, wrap);
+      fn(event);
+    };
+    this._emitter.on(type, wrap);
+    return this;
+  }
+
+  /** 发布 */
+  emit<K extends keyof T>(type: K, event?: T[K]): this {
+    this._emitter.emit(type, event as T[K]);
+    return this;
+  }
+
+  /** 移除 */
+  off<K extends keyof T>(type: K, fn?: (event: T[K]) => void): this {
+    this._emitter.off(type, fn);
+    return this;
+  }
+
+  /** 清空 */
+  clear(): this {
+    this._emitter.all.clear();
+    return this;
+  }
+}

package/src/ts/bean/index.ts

@@ -0,0 +1 @@
+export { EventBus } from './EventBus'; // 注意内部不能写export default,因为这里是export *

package/src/ts/day/index.ts

@@ -0,0 +1,184 @@
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
+import relativeTime from 'dayjs/plugin/relativeTime';
+import advancedFormat from 'dayjs/plugin/advancedFormat';
+import 'dayjs/locale/zh-cn';
+import { zeroPad } from '../number';
+
+dayjs.extend(customParseFormat);
+dayjs.extend(utc);
+dayjs.extend(timezone);
+dayjs.extend(relativeTime);
+dayjs.extend(advancedFormat);
+dayjs.locale('zh-cn');
+
+type BaseTime = number | string | Date | dayjs.Dayjs | null | undefined;
+
+/**
+ * 创建 dayjs 实例
+ * 文档: https://day.js.org/zh-CN/
+ * @param t 各种规范或不规范的时间
+ * @returns dayjs 实例
+ * @example
+ * const d = toDayjs('2021-01-01'); // dayjs 实例
+ * d.format('YYYY-MM-DD HH:mm:ss'); // "2025-12-10 11:33:16"
+ * d.valueOf(); // 毫秒时间戳，如 1765337596913
+ * d.unix(); // 秒时间戳，如 1765337596
+ * d.millisecond(); // 毫秒 913
+ * d.second(); // 秒 16
+ * d.minute(); // 分 33
+ * d.hour(); // 时 11
+ * d.date(); // 日 10
+ * d.day(); // 星期几 5（周日=0）
+ * d.month() + 1; // 月 12
+ * d.year(); // 年 2025
+ * d.startOf('day').valueOf(); // 当日零点
+ * d.startOf('month').format('YYYY-MM-DD HH:mm:ss'); // 月初 "2025-12-01 00:00:00"
+ * d.endOf('month').format('YYYY-MM-DD HH:mm:ss'); // 月末 "2025-12-31 23:59:59"
+ * d.fromNow(); // “刚刚”、“x分钟前/后”、“x小时前/后”、“x天前/后”、“x月前/后”、“x年前/后”
+ * d.isSame(t, 'day'); // 是否与t在同一天
+ * d.diff(); // 与当前时间相差的毫秒数
+ * d.diff(t); // 与t相差的毫秒数
+ * d.diff(t, 'second'); // 与t相差的秒数
+ * d.diff(t, 'minute'); // 与t相差的分钟数
+ * d.diff(t, 'hour'); // 与t相差的小时数
+ * d.diff(t, 'day'); // 与t相差的天数
+ * d.diff(t, 'week'); // 与t相差的周数
+ * d.diff(t, 'month'); // 与t相差的月数
+ * d.diff(t, 'quarter'); // 与t相差的季度数
+ * d.diff(t, 'year'); // 与t相差的年数
+ */
+export function toDayjs(t: BaseTime, fmt?: dayjs.OptionType) {
+  if (t === null || t === undefined) return dayjs();
+  if (typeof t === 'number') {
+    const s = String(Math.trunc(t));
+    return dayjs(s.length === 10 ? t * 1000 : t, fmt);
+  }
+  if (typeof t === 'string') {
+    const s = t.trim();
+    if (/^\d{10}$/.test(s)) return dayjs(Number(s) * 1000, fmt);
+    if (/^\d{13}$/.test(s)) return dayjs(Number(s), fmt);
+    if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return dayjs(s, fmt || 'YYYY-MM-DD');
+    if (/^\d{4}\/\d{2}\/\d{2}$/.test(s)) return dayjs(s, fmt || 'YYYY/MM/DD');
+    if (/^\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}$/.test(s))
+      return dayjs(s, fmt || 'YYYY-MM-DD HH:mm:ss');
+    if (/^\d{4}\/\d{2}\/\d{2}\s+\d{2}:\d{2}:\d{2}$/.test(s))
+      return dayjs(s, fmt || 'YYYY/MM/DD HH:mm:ss');
+    return dayjs(s, fmt);
+  }
+  return dayjs(t, fmt);
+}
+
+/**
+ * 获取“前几天”的日期范围
+ * @param offset 正整数天数
+ * @param fmt 日期格式，默认 `YYYY-MM-DD`
+ * @returns `[start, end]` 日期字符串数组
+ * @example
+ * 若今天为 2025-11-19：
+ * getDateRangeBefore(1) // ['2025-11-18', '2025-11-19']
+ * getDateRangeBefore(1, 'YYYY-MM-DD HH:mm:ss') // ['2025-11-18 00:00:00', '2025-11-19 23:59:59']
+ */
+export function getDateRangeBefore(offset: number, fmt = 'YYYY-MM-DD') {
+  const now = toDayjs(Date.now());
+  const n = Math.max(0, Math.trunc(offset));
+  const hasTime = /H|h|m|s|S|A|a|x|X/.test(fmt);
+  const startDay = now.add(-n, 'day');
+  const endDay = now;
+  const start = (hasTime ? startDay.startOf('day') : startDay).format(fmt);
+  const end = (hasTime ? endDay.endOf('day') : endDay).format(fmt);
+  return [start, end];
+}
+
+/**
+ * 获取“后几天”的日期范围
+ * - 起点：今天；终点：`offset` 天后
+ * - 若 `fmt` 含时间令牌（如 `HH:mm:ss`），则返回整日范围：起点为当日零点，终点为当日末尾
+ * @param offset 正整数天数
+ * @param fmt 日期格式，默认 `YYYY-MM-DD`
+ * @returns `[start, end]` 日期字符串数组
+ * @example
+ * 若今天为 2025-11-19：
+ * getDateRangeAfter(1) // ['2025-11-19', '2025-11-20']
+ * getDateRangeAfter(1, 'YYYY-MM-DD HH:mm:ss') // ['2025-11-19 00:00:00', '2025-11-20 23:59:59']
+ */
+export function getDateRangeAfter(offset: number, fmt = 'YYYY-MM-DD') {
+  const now = toDayjs(Date.now());
+  const n = Math.max(0, Math.trunc(offset));
+  const hasTime = /H|h|m|s|S|A|a|x|X/.test(fmt);
+  const startDay = now;
+  const endDay = now.add(n, 'day');
+  const start = (hasTime ? startDay.startOf('day') : startDay).format(fmt);
+  const end = (hasTime ? endDay.endOf('day') : endDay).format(fmt);
+  return [start, end];
+}
+
+/**
+ * 获取倒计时的时间分解（零填充字符串）
+ * @param diff 毫秒差值（正数表示剩余时间，负数/0表示已到期）
+ * @returns 包含天、时、分、秒、毫秒的零填充对象
+ * @example
+ * const diff = toDayjs(t).diff(); // 毫秒差值
+ * const parts = getCountdownParts(diff); // { d: '01', h: '02', m: '03', s: '04', ms: '567' }
+ */
+export function getCountdownParts(diff: number) {
+  if (diff <= 0) return { d: '00', h: '00', m: '00', s: '00', ms: '000' };
+
+  const d = Math.floor(diff / (1000 * 60 * 60 * 24));
+  const h = Math.floor((diff / (1000 * 60 * 60)) % 24);
+  const m = Math.floor((diff / (1000 * 60)) % 60);
+  const s = Math.floor((diff / 1000) % 60);
+  const ms = diff % 1000;
+
+  return {
+    d: zeroPad(d),
+    h: zeroPad(h),
+    m: zeroPad(m),
+    s: zeroPad(s),
+    ms: zeroPad(ms, 3),
+  };
+}
+
+/**
+ * 通过出生日期计算年龄
+ * @param birthdate 生日日期，支持多种格式（会被自动解析）
+ * @returns 年龄对象，包含 `age`（年龄数值）和 `type`（年龄单位，'year' 表示年，'month' 表示月）
+ * @example
+ * // 假设当前日期为 2025-11-19
+ * getAgeByBirthdate('2025-05-10'); // { age: 6, type: 'month' }
+ * getAgeByBirthdate('2020-11-19'); // { age: 5, type: 'year' }
+ * getAgeByBirthdate('2020-12-01'); // { age: 4, type: 'year' }（生日还没到, 所以年龄是4岁）
+ */
+export function getAgeByBirthdate(birthdate: string) {
+  const birth = toDayjs(birthdate, 'YYYY-MM-DD');
+  const now = toDayjs(Date.now());
+
+  // 精确的月份计算
+  const totalMonths = (now.year() - birth.year()) * 12 + (now.month() - birth.month());
+
+  // 如果当前日期小于出生日期，月份减1
+  const adjustedMonths = now.date() < birth.date() ? totalMonths - 1 : totalMonths;
+
+  if (adjustedMonths >= 12) {
+    let age = Math.floor(adjustedMonths / 12);
+    // 检查生日是否已过
+    const birthdayThisYear = birth.add(age, 'year');
+    if (now.isBefore(birthdayThisYear)) {
+      age--;
+    }
+    return { age, type: 'year' };
+  }
+
+  return { age: adjustedMonths, type: 'month' };
+}
+
+/**
+ * 对外抛出 dayjs 以便全局配置
+ * @example
+ * 切换语言
+ * dayjs.locale('en'); // 切换为英文
+ * dayjs.locale('zh-cn'); // 切换为中文 (默认)
+ */
+export { dayjs };

package/src/ts/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 内部统一导出, 外部快捷引入: import {xx} from 'base-tools/ts'
+ */
+export * from './array';
+export * from './async';
+export * from './bean';
+export * from './day';
+export * from './lodash';
+export * from './number';
+export * from './object';
+export * from './string';
+export * from './typing';
+export * from './url';
+export * from './validator';

package/src/ts/lodash/index.ts

@@ -0,0 +1,7 @@
+/**
+ * re-export 全量 lodash-es
+ * 文档: https://www.lodashjs.com/
+ * 目的: 从工具库统一loadsh版本，避免项目多个版本冲突
+ * 注意: 需在tsup.config.ts加入noExternal: ['lodash-es'],确保打包时不被忽略
+ */
+export * from 'lodash-es';

package/src/ts/number/big.ts

@@ -0,0 +1,192 @@
+import BigNumber from 'bignumber.js';
+
+/**
+ * 数值入参类型。
+ * 支持原生 `number`、`string`（包含小数、科学计数法等）以及 `BigNumber`。
+ */
+export type NumLike = string | number | BigNumber;
+
+/**
+ * 将任意 `NumLike` 统一转换为 `BigNumber` 实例。
+ * @param x 任意支持的数值入参。
+ * @returns `BigNumber` 实例。
+ * @example
+ * big('0.1'); // => BigNumber
+ * big(0.2);   // => BigNumber
+ */
+export function big(x: NumLike): BigNumber {
+  return x instanceof BigNumber ? x : new BigNumber(x);
+}
+
+/**
+ * 高精度加法（支持多个参数连加）。
+ * @example
+ * bigAdd(0.1, 0.2); // => 0.3
+ * bigAdd('0.1', '0.2'); // => 0.3
+ * bigAdd(1, 2, 3, 4); // => 10  // 多参数连加: 1+2+3+4
+ */
+export function bigAdd(a: NumLike, ...rest: NumLike[]) {
+  let acc = big(a);
+  for (const x of rest) acc = acc.plus(big(x));
+  return acc.toNumber();
+}
+
+/**
+ * 高精度减法（支持多个参数连减）。
+ * @example
+ * bigSub(1, 0.9); // => 0.1
+ * bigSub('1.1', '0.2'); // => 0.9
+ * bigSub(10, 1, 2, 3); // => 4  // 多参数连减: 10-1-2-3
+ */
+export function bigSub(a: NumLike, ...rest: NumLike[]) {
+  let acc = big(a);
+  for (const x of rest) acc = acc.minus(big(x));
+  return acc.toNumber();
+}
+
+/**
+ * 高精度乘法（支持多个参数连乘）。
+ * @example
+ * bigMul(0.1, 0.2); // => 0.02
+ * bigMul('1.5', '3'); // => 4.5
+ * bigMul(2, 3, 4); // => 24  // 多参数连乘: 2*3*4
+ */
+export function bigMul(a: NumLike, ...rest: NumLike[]) {
+  let acc = big(a);
+  for (const x of rest) acc = acc.times(big(x));
+  return acc.toNumber();
+}
+
+/**
+ * 高精度除法（支持多个参数连除）。
+ * @example
+ * bigDiv(1, 3); // => 0.333333...
+ * bigDiv('10', '4'); // => 2.5
+ * bigDiv(100, 5, 2); // => 10  // 多参数连除: 100/5/2
+ */
+export function bigDiv(a: NumLike, ...rest: NumLike[]) {
+  let acc = big(a);
+  for (const x of rest) acc = acc.div(big(x));
+  return acc.toNumber();
+}
+
+/**
+ * 指数运算
+ * @param x 底数。
+ * @param y 指数。
+ * @returns 计算结果。
+ * @example
+ * bigPow(2, 3); // => 8
+ * bigPow('2.5', 2); // => 6.25
+ */
+export function bigPow(x: NumLike, y: NumLike) {
+  return big(x).pow(big(y)).toNumber();
+}
+
+/**
+ * 四舍五入到指定位数
+ * @param x 需要舍入的数值。
+ * @param dp 保留的小数位数，默认 `0`（取整）。
+ * @param rm 舍入模式，默认 `ROUND_HALF_UP`（四舍五入）。
+ * @returns 舍入后的数值。
+ * @example
+ * bigRound(1.6); // => 2
+ * bigRound('1.234', 2); // => 1.23
+ * bigRound('1.235', 2); // => 1.24
+ * bigRound('1.299', 2, BigNumber.ROUND_DOWN); // => 1.29
+ */
+export function bigRound(x: NumLike, dp = 0, rm: BigNumber.RoundingMode = BigNumber.ROUND_HALF_UP) {
+  return big(x).decimalPlaces(dp, rm).toNumber();
+}
+
+/**
+ * 将数值按指定位数格式化为字符串（保留小数位）。
+ * @param x 需要格式化的数值。
+ * @param dp 保留的小数位数，默认 `2`。
+ * @param rm 舍入模式，默认 `ROUND_HALF_UP`（四舍五入）。
+ * @returns 格式化后的字符串。
+ * @example
+ * toFixed('1'); // => '1.00'
+ * +toFixed('1'); // => 1
+ * toFixed(1.2345); // => '1.23'
+ * toFixed(1.2345, 3); // => '1.235'
+ * toFixed('1.2345', 0, BigNumber.ROUND_UP); // => '2'
+ */
+export function toFixed(
+  x: NumLike,
+  dp = 2,
+  rm: BigNumber.RoundingMode = BigNumber.ROUND_HALF_UP,
+): string {
+  return big(x).toFixed(dp, rm);
+}
+
+/**
+ * 比较两个数值大小。
+ * @example
+ * bigCompare('2', '10'); // => -1
+ * bigCompare(3, 3);      // => 0
+ * bigCompare('10', 2);   // => 1
+ */
+export function bigCompare(a: NumLike, b: NumLike): -1 | 0 | 1 | null {
+  return big(a).comparedTo(big(b));
+}
+
+/**
+ * 判断两个数值是否相等。
+ * @example
+ * bigEqual('1.0', 1); // => true
+ * bigEqual(2, 1); // => false
+ */
+export function bigEqual(a: NumLike, b: NumLike): boolean {
+  return big(a).isEqualTo(big(b));
+}
+
+/**
+ * 判断 a 是否大于 b。
+ * @example
+ * bigGt(2, 1); // => true
+ * bigGt(1, 2); // => false
+ */
+export function bigGt(a: NumLike, b: NumLike): boolean {
+  return big(a).isGreaterThan(big(b));
+}
+
+/**
+ * 判断 a 是否大于等于 b。
+ * @example
+ * bigGte(2, 2); // => true
+ * bigGte(1, 2); // => false
+ */
+export function bigGte(a: NumLike, b: NumLike): boolean {
+  return big(a).isGreaterThanOrEqualTo(big(b));
+}
+
+/**
+ * 判断 a 是否小于 b。
+ * @example
+ * bigLt(1, 2); // => true
+ * bigLt(2, 1); // => false
+ */
+export function bigLt(a: NumLike, b: NumLike): boolean {
+  return big(a).isLessThan(big(b));
+}
+
+/**
+ * 判断 a 是否小于等于 b。
+ * @example
+ * bigLte(2, 2); // => true
+ * bigLte(1, 2); // => true
+ * bigLte(2, 1); // => false
+ */
+export function bigLte(a: NumLike, b: NumLike): boolean {
+  return big(a).isLessThanOrEqualTo(big(b));
+}
+
+/**
+ * 导出 BigNumber 类
+ * @example
+ * BigNumber.ROUND_HALF_UP; // 使用类型
+ * BigNumber.set(config); // 设置全局配置
+ * const bn = new BigNumber('123456.789'); // 创建实例
+ */
+export { BigNumber };