@cloudcome/utils-core 0.0.0 → 1.1.1

package/src/regexp.ts

@@ -0,0 +1,156 @@
+const specialRE = /[.*+?^=!:${}()|[\]/\\-]/g;
+
+/**
+ * 编码处理正则表达式
+ * @example
+ * ```js
+ * reEscape('/$')
+ * // => '\\/\\$'
+ * ```
+ * @param {string} string
+ * @returns {string}
+ */
+export function regexpEscape(string: string): string {
+  return string.replace(specialRE, '\\$&');
+}
+
+// 邮箱
+const EMAIL_RE = /^\w+[-+.\w]*@([a-z\d-]+\.)+[a-z]{2,5}$/i;
+/**
+ * 判断字符串是否为邮箱格式，不对邮箱真实性做验证，如域名是否正确等
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isEmail(value: string): boolean {
+  return EMAIL_RE.test(value);
+}
+
+// 手机号码
+const PHONE_RE = /^1\d{10}$/;
+/**
+ * 判断字符串是否为宽松手机格式，即首位为 1 的 11 位数字都属于手机号
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isPhone(value: string): boolean {
+  return PHONE_RE.test(value);
+}
+
+// 身份证号码
+// http://www.stats.gov.cn/tjsj/tjbz/xzqhdm/
+// ["北京市", "天津市", "河北省", "山西省", "内蒙古自治区",
+// "辽宁省", "吉林省", "黑龙江省",
+// "上海市", "江苏省", "浙江省", "安徽省", "福建省", "江西省", "山东省",
+// "河南省", "湖北省", "湖南省", "广东省", "广西壮族自治区", "海南省",
+// "重庆市", "四川省", "贵州省", "云南省", "西藏自治区",
+// "陕西省", "甘肃省", "青海省","宁夏回族自治区", "新疆维吾尔自治区",
+// "台湾省",
+// "香港特别行政区", "澳门特别行政区"]
+// ["11", "12", "13", "14", "15",
+// "21", "22", "23",
+// "31", "32", "33", "34", "35", "36", "37",
+// "41", "42", "43", "44", "45", "46",
+// "50", "51", "52", "53", "54",
+// "61", "62", "63", "64", "65",
+// "71",
+// "81", "82"]
+// 91 国外
+const IDNO_RE =
+  /^(1[1-5]|2[1-3]|3[1-7]|4[1-6]|5[0-4]|6[1-5]|7[1]|8[1-2]|9[1])\d{4}(18|19|20)\d{2}[01]\d[0123]\d{4}[\dxX]$/;
+/**
+ * 判断字符串是否为身份证号码格式
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isIDNo(value: string): boolean {
+  const isSameFormat = IDNO_RE.test(value);
+
+  if (!isSameFormat) return false;
+
+  const year = Number(value.slice(6, 10));
+  const month = Number(value.slice(10, 12));
+  const date = Number(value.slice(12, 14));
+  const d = new Date(year, month - 1, date);
+  const isSameDate = d.getFullYear() === year && d.getMonth() + 1 === month && d.getDate() === date;
+
+  if (!isSameDate) return false;
+
+  // 将身份证号码前面的17位数分别乘以不同的系数；
+  // 从第一位到第十七位的系数分别为：7－9－10－5－8－4－2－1－6－3－7－9－10－5－8－4－2
+  // 将这17位数字和系数相乘的结果相加；
+  // 用加出来和除以11，看余数是多少；
+  // 余数只可能有0－1－2－3－4－5－6－7－8－9－10这11个数字；
+  // 其分别对应的最后一位身份证的号码为1－0－X－9－8－7－6－5－4－3－2
+  // 通过上面得知如果余数是2，就会在身份证的第18位数字上出现罗马数字的Ⅹ。如果余数是10，身份证的最后一位号码就是2。
+  const coefficientList = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
+  const residueList = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
+  let sum = 0;
+
+  for (let start = 0; start < 17; start++) {
+    sum += Number(value.slice(start, start + 1)) * coefficientList[start];
+  }
+
+  return residueList[sum % 11] === value.slice(-1);
+}
+
+// url
+const URL_RE =
+  /^https?:\/\/(([a-z\d-]+\.)+[a-z]{2,5}|(\d{1,3}\.){3}\d{1,3})(:[1-9]\d{0,4})?(\/|\/[\w#!:.?+=&%@'/()-]+)?$/i;
+/**
+ * 判断字符串是否为 url 格式，仅支持 http 协议，支持域名或者 ipV4
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isURL(value: string): boolean {
+  return URL_RE.test(value);
+}
+
+// ipv4
+const IPV4_RE = /^(?:(?:\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.){3}(?:\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])$/;
+/**
+ * 判断字符串是否为 IPV4 格式，不对 ip 真实性做验证
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isIPV4(value: string): boolean {
+  return IPV4_RE.test(value);
+}
+
+const INTEGER_RE = /^(-?[1-9]\d*|0)$/;
+/**
+ * 判断字符串是否为整数（自然数），即 ...,-3,-2,-1,0,1,2,3,...
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isInteger(value: string): boolean {
+  return INTEGER_RE.test(value);
+}
+
+const FLOAT_RE = /^-?([1-9]\d*|0)\.\d+$/;
+/**
+ * 判断字符串是否为浮点数，即必须有小数点的有理数
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isFloat(value: string): boolean {
+  return FLOAT_RE.test(value);
+}
+
+/**
+ * 判断字符串是否为正确数值，包括整数和浮点数
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isNumerical(value: string): boolean {
+  return isInteger(value) || isFloat(value);
+}
+
+const DIGIT_RE = /^\d+$/;
+/**
+ * 判断字符串是否为数字，例如六位数字短信验证码（093031）
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isDigit(value: string): boolean {
+  return DIGIT_RE.test(value);
+}

package/src/string.ts

@@ -0,0 +1,146 @@
+import { numberConvert, randomNumber } from './number';
+import { isFunction, isNullish, isNumber, isObject, isString, isUndefined } from './type';
+
+export const STRING_ARABIC_NUMERALS = '0123456789';
+export const STRING_HEXADECIMALS = '0123456789abcdef';
+export const STRING_LOWERCASE_ALPHA = 'abcdefghijklmnopqrstuvwxyz';
+export const STRING_UPPERCASE_ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+export const STRING_DICT = `${STRING_ARABIC_NUMERALS + STRING_UPPERCASE_ALPHA + STRING_LOWERCASE_ALPHA}`;
+
+/**
+ * 将字符串转换为驼峰格式
+ * @param {string} string - 要转换的字符串
+ * @param {boolean} [bigger] - 是否大写第一个字母，默认为 false
+ * @returns {string} - 转换后的驼峰格式字符串
+ */
+export function stringCamelCase(string: string, bigger?: boolean): string {
+  const string2 = string.replace(/[\s_-](.)/g, (_, char) => (char as string).toUpperCase());
+  return bigger ? string2.slice(0, 1).toUpperCase() + string2.slice(1) : string2;
+}
+
+/**
+ * 将字符串转换为连字格式
+ * @param {string} string - 要转换的字符串
+ * @param {string} [separator] - 分隔符，默认是 "-"（短横线）
+ * @returns {string} - 转换后的连字格式字符串
+ */
+export function stringKebabCase(string: string, separator = '-'): string {
+  return string.replace(/[A-Z]/g, (origin) => `${separator}${origin.toLowerCase()}`);
+}
+
+/**
+ * 生成随机字符串
+ * @param {number} length - 生成的随机字符串长度
+ * @param {string} [dict] - 用于生成随机字符串的字符字典，默认为数字、小写字母和大写字母的组合
+ * @returns {string} - 生成的随机字符串
+ * @example
+ * randomString(10); // 生成一个长度为 10 的随机字符串
+ * randomString(8, 'ABCDEF'); // 生成一个长度为 8 的随机字符串，仅包含字符 'ABCDEF'
+ */
+export function randomString(length: number, dict?: string): string {
+  const dictFinal = dict || STRING_DICT;
+  const dictLength = dictFinal.length;
+
+  let result = '';
+
+  for (let i = 0; i < length; i++) {
+    result += dictFinal.charAt(randomNumber(0, dictLength - 1));
+  }
+
+  return result;
+}
+
+/**
+ * 简单的模板引擎，类似于 Python 的 `.format()` 方法
+ * 支持通过索引或对象/名称的方式传递变量
+ * 当使用对象/名称方式时，可以传递一个回退值作为第三个参数
+ *
+ * @category 字符串
+ * @example
+ * ```
+ * // 索引方式
+ * const result = stringFormat(
+ *   '你好 {0}！我的名字是 {1}。',
+ *   '张三',
+ *   '李四'
+ * ); // 你好 张三！我的名字是 李四。
+ * ```
+ *
+ * @example
+ * ```
+ * // 对象方式
+ * const result = stringFormat(
+ *   '{greet}！我的名字是 {name}。',
+ *   { greet: '你好', name: '王五' }
+ * ); // 你好！我的名字是 王五。
+ * ```
+ *
+ * @example
+ * ```
+ * // 带回退值的对象方式
+ * const result = stringFormat(
+ *   '{greet}！我的名字是 {name}。',
+ *   { greet: '你好' }, // name 未传递，因此会使用回退值
+ *   '未知'
+ * ); // 你好！我的名字是 未知。
+ * ```
+ */
+export function stringFormat(
+  str: string,
+  object: Record<string | number, unknown>,
+  fallback?: string | ((key: string) => string),
+): string;
+export function stringFormat(str: string, ...args: (string | number | bigint | undefined | null)[]): string;
+export function stringFormat(str: string, ...args: unknown[]): string {
+  const [firstArg, fallback] = args;
+
+  if (isObject(firstArg) || isUndefined(firstArg)) {
+    const vars = firstArg || {};
+    return str.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? (isFunction(fallback) ? fallback(key) : fallback) ?? key);
+  }
+
+  return str.replace(/\{(\d+)\}/g, (_, key) => {
+    const index = Number(key);
+    if (Number.isNaN(index)) return key;
+    return args[index];
+  });
+}
+
+/**
+ * 生成符合 [RFC 4122](https://www.ietf.org/rfc/rfc4122.txt) 版本 4 的 UUID 字符串
+ * @returns {string} - 生成的 UUID 字符串
+ * @example
+ * const uuid = randomUUID4();
+ * console.log(uuid); // 输出类似 '123e4567-e89b-12d3-a456-426614174000' 的 UUID 字符串
+ */
+export function randomUUID4(): string {
+  const template = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
+  let result = '';
+
+  for (let i = 0; i < template.length; i++) {
+    const t = template[i];
+
+    if (t === '-' || t === '4') {
+      result += t;
+      continue;
+    }
+
+    if (t === 'y') {
+      result += randomString(1, '89ab');
+      continue;
+    }
+
+    result += randomString(1, STRING_HEXADECIMALS);
+  }
+
+  return result;
+}
+
+/**
+ * 将值转换为字符串，若值为 null 或 undefined 则返回空字符串
+ * @param {unknown} value - 需要转换的值
+ * @returns {string} 转换后的字符串结果
+ */
+export function stringify(value: unknown) {
+  return isNullish(value) ? '' : String(value);
+}

package/src/time/from.ts

@@ -0,0 +1,57 @@
+// @rer https://day.js.org/docs/en/durations/creating
+
+import { DATE_DAY_MS, DATE_HOUR_MS, DATE_MINUTE_MS, DATE_MONTH_MS, DATE_SECOND_MS, DATE_YEAR_MS } from '@/date';
+import { isString } from '@/type';
+import type { TTimeDuration } from './to';
+
+/**
+ * 时间转换规则数组
+ * @type {Array<[RegExp, (match: RegExpMatchArray) => number]>}
+ * @property {RegExp} 0 - 匹配时间单位正则表达式
+ * @property {function} 1 - 将匹配结果转换为毫秒数的函数
+ */
+const rules: [key: keyof TTimeDuration, time: number][] = [
+  ['years', DATE_YEAR_MS],
+  ['months', DATE_MONTH_MS],
+  ['days', DATE_DAY_MS],
+  ['hours', DATE_HOUR_MS],
+  ['minutes', DATE_MINUTE_MS],
+  ['seconds', DATE_SECOND_MS],
+];
+
+/**
+ * 将时间持续时间字符串或对象转换为毫秒数
+ *
+ * @param duration - 可以是时间持续时间字符串（如 '1d2h'）或 TTimeDuration 对象
+ * @returns 计算得到的总毫秒数
+ */
+export function timeFrom(duration: string | TTimeDuration) {
+  const td = isString(duration) ? timeParse(duration) : duration;
+  return rules.reduce((acc, [key, time]) => acc + (td[key] || 0) * time, 0);
+}
+
+const durationMatchRules: [RegExp, key: keyof TTimeDuration][] = [
+  [/(\d+)y/i, 'years'],
+  [/(\d+)M/, 'months'],
+  [/(\d+)d/i, 'days'],
+  [/(\d+)h/i, 'hours'],
+  [/(\d+)m/, 'minutes'],
+  [/(\d+)s/, 'seconds'],
+];
+
+/**
+ * 将时长字符串解析为时间对象
+ * @param duration - 时长字符串（例如 "1h30m"）
+ * @returns 包含解析后时间单位的对象（小时、分钟等）
+ */
+export function timeParse(duration: string) {
+  const result = {} as TTimeDuration;
+
+  for (const [regex, key] of durationMatchRules) {
+    const match = duration.match(regex);
+    if (match) result[key] = Number(match[1]);
+    else result[key] = 0;
+  }
+
+  return result;
+}

package/src/time/to.ts

@@ -0,0 +1,106 @@
+import { DATE_DAY_MS, DATE_HOUR_MS, DATE_MINUTE_MS, DATE_SECOND_MS } from '../date';
+
+export type TTimeDuration = {
+  years: number;
+  months: number;
+  /** 天数 */
+  days: number;
+  /** 小时数 */
+  hours: number;
+  /** 分钟数 */
+  minutes: number;
+  /** 秒数 */
+  seconds: number;
+  /** 毫秒数 */
+  milliseconds: number;
+};
+
+type _TTimeParsePoint = 'D' | 'h' | 'm' | 's' | 'S';
+
+/**
+ * 解析时间毫秒数为绝对时间对象
+ * @param timeMs 时间毫秒数
+ * @param maxPoint 最大时间单位（决定分解的起始单位）
+ * @returns 包含时间单位分解结果的对象
+ * @example
+ * ```typescript
+ * // 默认以天为最大单位分解
+ * timeInDay(123456789);
+ * // { days: 1, hours: 10, minutes: 17, seconds: 36, milliseconds: 789 }
+ *
+ * // 指定最大单位为分钟，分解到分钟及以下单位
+ * timeInMinute(123456789);
+ * // { days: 0, hours: 0, minutes: 2057, seconds: 36, milliseconds: 789 }
+ * ```
+ */
+function _timeAbsolute(timeMs: number, maxPoint: _TTimeParsePoint): TTimeDuration {
+  const minPoint: _TTimeParsePoint = 'S';
+
+  const defines: [point: _TTimeParsePoint, key: keyof TTimeDuration, base: number][] = [
+    ['D', 'days', DATE_DAY_MS],
+    ['h', 'hours', DATE_HOUR_MS],
+    ['m', 'minutes', DATE_MINUTE_MS],
+    ['s', 'seconds', DATE_SECOND_MS],
+    ['S', 'milliseconds', 1],
+  ] as const;
+
+  const minIndex = defines.findIndex((item) => item[0] === maxPoint);
+  const maxIndex = defines.findIndex((item) => item[0] === minPoint);
+
+  let timeMsFinal = timeMs;
+  const dao: TTimeDuration = {
+    years: 0,
+    months: 0,
+    days: 0,
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+    milliseconds: 0,
+  };
+
+  for (let i = minIndex; i <= maxIndex; i++) {
+    const mode = defines[i];
+    const base = mode[2];
+    const value = Math.floor(timeMsFinal / base);
+    timeMsFinal = timeMsFinal - value * base;
+    dao[mode[1]] = value;
+  }
+
+  return dao;
+}
+
+/**
+ * 将时间毫秒数解析为以天为最大单位的绝对时间对象
+ * @param timeMs 时间毫秒数
+ * @returns 包含天/小时/分钟/秒/毫秒分解结果的对象
+ */
+export function timeToDays(timeMs: number) {
+  return _timeAbsolute(timeMs, 'D');
+}
+
+/**
+ * 将时间毫秒数解析为以小时为最大单位的绝对时间对象
+ * @param timeMs 时间毫秒数
+ * @returns 包含小时/分钟/秒/毫秒分解结果的对象
+ */
+export function timeToHours(timeMs: number) {
+  return _timeAbsolute(timeMs, 'h');
+}
+
+/**
+ * 将时间毫秒数解析为以分钟为最大单位的绝对时间对象
+ * @param timeMs 时间毫秒数
+ * @returns 包含分钟/秒/毫秒分解结果的对象
+ */
+export function timeToMinutes(timeMs: number) {
+  return _timeAbsolute(timeMs, 'm');
+}
+
+/**
+ * 将时间毫秒数解析为以秒为最大单位的绝对时间对象
+ * @param timeMs 时间毫秒数
+ * @returns 包含秒/毫秒分解结果的对象
+ */
+export function timeToSeconds(timeMs: number) {
+  return _timeAbsolute(timeMs, 's');
+}

package/src/time.ts

@@ -0,0 +1,2 @@
+export * from './time/from';
+export * from './time/to';

package/src/timer.ts

@@ -0,0 +1,226 @@
+/**
+ * 定时器状态接口
+ */
+export type TTimerState = {
+  /**
+   * 执行次数
+   */
+  times: number;
+  /**
+   * 开始时间戳
+   */
+  startAt: number;
+  /**
+   * 停止时间戳
+   */
+  stopAt: number;
+  /**
+   * 暂停时间戳
+   */
+  pauseAt: number;
+  /**
+   * 恢复时间戳
+   */
+  resumeAt: number;
+  /**
+   * 当前时间戳
+   */
+  currentAt: number;
+  /**
+   * 总耗时（包括暂停时间）
+   */
+  elapsedTime: number;
+  /**
+   * 实际运行时间（不包括暂停时间）
+   */
+  runningTime: number;
+  /**
+   * 当前间隔时间
+   */
+  intervalTime: number;
+};
+
+export type TTimerHandler = {
+  /**
+   * 开始
+   */
+  start: () => void;
+  /**
+   * 暂停
+   */
+  pause: () => void;
+  /**
+   * 恢复
+   */
+  resume: (immediate?: boolean) => void;
+  /**
+   * 停止
+   */
+  stop: () => void;
+};
+
+const STATUS_READY = 0;
+const STATUS_START = 1;
+const STATUS_PAUSE = 2;
+const STATUS_STOP = 3;
+
+/**
+ * 创建间隔定时器核心函数
+ *
+ * @param nextTime - 用于安排下一次执行的函数
+ * @param effect - 每次执行的回调函数，接收定时器状态和可选的next函数
+ * @returns 返回包含控制方法的对象
+ */
+export function makeInterval(
+  nextTime: (call: () => void) => void,
+  effect: (timer: TTimerState, next?: () => void) => unknown,
+) {
+  let startAt = 0;
+  let lastAt = 0;
+  let stopAt = 0;
+  let pauseAt = 0;
+  let resumeAt = 0;
+  let times = 0;
+  let status = STATUS_READY;
+  let runningTime = 0;
+
+  const execute = () => {
+    if (status >= STATUS_PAUSE) return;
+
+    const now = Date.now();
+    const intervalTime = lastAt > 0 ? now - lastAt : 0;
+    runningTime += intervalTime;
+    lastAt = now;
+    const state: TTimerState = {
+      times: ++times,
+      startAt,
+      stopAt,
+      pauseAt,
+      resumeAt,
+      currentAt: now,
+      elapsedTime: startAt > 0 ? now - startAt : 0,
+      runningTime,
+      intervalTime,
+    };
+
+    if (effect.length === 2) {
+      effect(state, () => {
+        nextTime(execute);
+      });
+    } else {
+      effect(state);
+      nextTime(execute);
+    }
+  };
+
+  const canStart = () => status === STATUS_READY;
+  const start = () => {
+    if (!canStart()) return;
+    status = STATUS_START;
+    startAt = Date.now();
+    execute();
+  };
+
+  const canStop = () => status === STATUS_START;
+  const stop = () => {
+    if (!canStop()) return;
+    status = STATUS_STOP;
+    stopAt = Date.now();
+  };
+
+  const canPause = () => status === STATUS_START;
+  const pause = () => {
+    if (!canPause()) return;
+    status = STATUS_PAUSE;
+    pauseAt = Date.now();
+  };
+
+  const canResume = () => status === STATUS_PAUSE;
+  const resume = () => {
+    if (!canResume()) return;
+    status = STATUS_START;
+    resumeAt = Date.now();
+    lastAt = resumeAt;
+    execute();
+  };
+
+  return {
+    canStart,
+    canStop,
+    canPause,
+    canResume,
+    start,
+    stop,
+    pause,
+    resume,
+    execute,
+  };
+}
+
+export type TTimerOptions = {
+  /**
+   * 是否在定时器开始时立即执行回调
+   */
+  leading?: boolean;
+  /**
+   * 是否在定时器停止时执行最后一次回调
+   */
+  trailing?: boolean;
+};
+
+/**
+ * 创建一个基于 `setTimeout` 的间隔定时器
+ *
+ * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
+ * @param interval - 间隔时间，单位为毫秒
+ * @param options - 配置选项
+ * @returns {TTimerHandler}
+ */
+export function timeInterval(
+  callback: (state: TTimerState, next?: () => void) => unknown,
+  interval: number,
+  options?: TTimerOptions,
+): TTimerHandler {
+  let timeId: number | NodeJS.Timeout;
+  const { canStart, canStop, canPause, canResume, start, stop, pause, resume, execute } = makeInterval((call) => {
+    timeId = setTimeout(call, interval);
+  }, callback);
+
+  return {
+    start() {
+      if (!canStart()) return;
+
+      if (options?.leading) {
+        start();
+      } else {
+        timeId = setTimeout(start, interval);
+      }
+    },
+
+    stop() {
+      if (!canStop()) return;
+      if (options?.trailing) execute();
+
+      clearTimeout(timeId);
+      stop();
+    },
+
+    pause() {
+      if (!canPause()) return;
+      if (options?.trailing) execute();
+
+      clearTimeout(timeId);
+      pause();
+    },
+
+    resume(immediate?: boolean) {
+      if (!canResume()) return;
+
+      if (immediate || options?.leading) {
+        resume();
+      } else {
+        timeId = setTimeout(resume, interval);
+      }
+    },
+  };
+}