@cloudcome/utils-core 1.1.1 → 1.2.1

package/src/string.ts

@@ -1,146 +0,0 @@
-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

@@ -1,57 +0,0 @@
-// @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

@@ -1,106 +0,0 @@
-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/tree.ts

@@ -1,394 +0,0 @@
-import { arrayEach } from './array';
-import { isArray, isNullish, isUndefined } from './type';
-import type { AnyObject } from './types';
-
-/**
- * 表示深度遍历中的节点对象，包含子节点列表。
- */
-export type TTreeItem = AnyObject & {
-  /**
-   * 子节点列表。
-   */
-  children?: TTreeItem[];
-};
-
-/**
- * 表示深度遍历中的节点列表。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- */
-export type TTreeList<I extends TTreeItem> = I[];
-
-/**
- * 表示深度遍历中的遍历器状态。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- */
-export type TTreeWalker<I extends TTreeItem> = {
-  /**
-   * 当前层级的节点列表。
-   */
-  list: TTreeList<I>;
-
-  /**
-   * 当前节点的父节点，如果为根节点则为 `null`。
-   */
-  parent: I | null;
-
-  /**
-   * 当前节点的层级，从 1 开始计数。
-   */
-  level: number;
-
-  /**
-   * 从根节点到当前节点的路径。
-   */
-  path: TTreeList<I>;
-};
-
-/**
- * 表示深度遍历中的节点信息。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- */
-export type TTreeInfo<I extends TTreeItem> = TTreeWalker<I> & {
-  /**
-   * 当前节点。
-   */
-  item: I;
-
-  /**
-   * 当前节点在 `list` 中的索引。
-   */
-  index: number;
-};
-
-/**
- * 深度遍历的同步迭代器函数类型。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- * @param info - 当前节点的信息。
- * @returns 如果返回 `false`，则提前终止遍历。
- */
-export type TreeEachIterator<I extends TTreeItem> = (info: TTreeInfo<I>) => false | unknown;
-
-/**
- * 深度遍历的异步迭代器函数类型。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- * @param info - 当前节点的信息。
- * @returns 如果返回 `false`，则提前终止遍历。
- */
-export type TreeEachIteratorAsync<I extends TTreeItem> = (info: TTreeInfo<I>) => Promise<boolean | unknown>;
-
-/**
- * 深度遍历的同步遍历器函数类型。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- * @param walker - 遍历器状态。
- * @returns 遍历结果。
- */
-export type TreeWalk<I extends TTreeItem> = (walker: TTreeWalker<I>) => unknown;
-
-/**
- * 深度遍历的异步遍历器函数类型。
- *
- * @template I - 节点对象的类型，必须继承自 `TreeItem`。
- * @param walker - 遍历器状态。
- * @returns 异步遍历结果。
- */
-export type TreeWalkAsync<I extends TTreeItem> = (walker: TTreeWalker<I>) => Promise<unknown>;
-
-/**
- * 深度遍历数组中的每个元素，并对每个元素执行提供的回调函数。
- *
- * @param treeList - 要遍历的深度数组。
- * @param iterator - 对每个元素执行的回调函数。如果回调函数返回 `false`，则提前终止遍历。
- * @param breadthFist - 是否使用广度优先遍历，默认为 `false`（深度优先）。
- * @returns 无返回值。
- *
- * @example
- * ```typescript
- * const treeList = [
- *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
- *   { value: 4 }
- * ];
- *
- * treeEach(treeList, (item) => {
- *   console.log(item.value);
- *   if (item.value === 2) return false; // 提前终止遍历
- * });
- * ```
- */
-export function treeEach<I extends TTreeItem = TTreeItem>(
-  treeList: TTreeList<I>,
-  iterator: TreeEachIterator<I>,
-  breadthFist = false,
-): void {
-  const treeInfoList: TTreeInfo<I>[] = [];
-  let returnFalse = false;
-
-  const iterate = (info: TTreeInfo<I>) => {
-    if (iterator(info) === false) {
-      returnFalse = true;
-      return false;
-    }
-  };
-
-  const next = (info: TTreeInfo<I>, walk: TreeWalk<I>) => {
-    const { item, level, parent, path } = info;
-    const { children } = item;
-
-    if (isArray(children)) {
-      returnFalse =
-        walk({
-          ...info,
-          parent: item,
-          list: children as TTreeList<I>,
-          level: level + 1,
-        }) === false;
-    }
-  };
-
-  const walk: TreeWalk<I> = (walker) => {
-    const { list, level, parent, path } = walker;
-
-    const path2 = [...path];
-    while (parent !== null && path2.length > 0 && path2[path2.length - 1] !== parent) {
-      path2.pop();
-    }
-
-    arrayEach(list, (item, index) => {
-      if (returnFalse) return false;
-
-      const info: TTreeInfo<I> = {
-        ...walker,
-        item,
-        index,
-        path: [...path2, item],
-      };
-
-      // 广度优先
-      if (breadthFist) {
-        treeInfoList.push(info);
-      }
-      // 深度优先
-      else {
-        iterate(info);
-        if (returnFalse) return false;
-        next(info, walk);
-      }
-    });
-
-    if (breadthFist) {
-      while (!returnFalse) {
-        const info = treeInfoList.shift();
-        if (!info) break;
-
-        iterate(info);
-        if (returnFalse) break;
-
-        // 内部也会进入 walk
-        next(info, walk);
-      }
-    }
-
-    return !returnFalse;
-  };
-
-  walk({
-    list: treeList,
-    level: 1,
-    parent: null,
-    path: [],
-  });
-}
-
-/**
- * 在深度数组中查找满足条件的第一个节点信息。
- *
- * @param treeList - 要查找的深度数组。
- * @param predicate - 判断节点是否满足条件的回调函数。
- * @param breadthFist - 是否使用广度优先查找，默认为 `false`（深度优先）。
- * @returns 如果找到满足条件的节点，则返回该节点的信息；否则返回 `undefined`。
- *
- * @example
- * ```typescript
- * const treeList = [
- *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
- *   { value: 4 }
- * ];
- *
- * const found = treeFind(treeList, (info) => info.item.value === 3);
- * console.log(found);
- * // {
- * //    item: { value: 3 },
- * //    index: 1,
- * //    list: [{ value: 2 }, { value: 3 }],
- * //    parent: { value: 1, children: [{ value: 2 }, { value: 3 }] },
- * //    level: 2,
- * //    path: [{ value: 1, children: [{ value: 2 }, { value: 3 }] }, { value: 3 }]
- * // }
- * ```
- */
-export function treeFind<I extends TTreeItem>(
-  treeList: TTreeList<I>,
-  predicate: (info: TTreeInfo<I>) => boolean,
-  breadthFist = false,
-): TTreeInfo<I> | undefined {
-  let found: TTreeInfo<I> | undefined;
-
-  treeEach(
-    treeList,
-    (info) => {
-      if (predicate(info)) {
-        found = info;
-        return false;
-      }
-    },
-    breadthFist,
-  );
-
-  return found;
-}
-
-/**
- * 将深度嵌套的树形结构扁平化为一维数组，并对每个节点执行指定的转换函数。
- *
- * @template I - 树节点的类型，必须继承自 `TreeItem`。
- * @template T - 转换后的数据类型。
- * @param {TTreeList<I>} deepList - 要扁平化的深度嵌套树形结构。
- * @param {(info: TTreeInfo<I>) => T} flatten - 对每个节点执行的转换函数，返回转换后的数据。
- * @param {boolean} [breadthFist=false] - 是否使用广度优先遍历，默认为 `false`（深度优先）。
- * @returns {T[]} - 转换后的一维数组。
- * @example
- * ```typescript
- * const treeList = [
- *   { value: 1, children: [{ value: 2 }, { value: 3 }] },
- *   { value: 4 }
- * ];
- *
- * const flattened = deepFlat(treeList, (info) => info.item.value);
- * console.log(flattened); // [1, 2, 3, 4]
- * ```
- */
-export function deepFlat<I extends TTreeItem, T>(
-  deepList: TTreeList<I>,
-  flatten: (info: TTreeInfo<I>) => T,
-  breadthFist = false,
-): T[] {
-  const list2: T[] = [];
-
-  treeEach(
-    deepList,
-    (info) => {
-      list2.push(flatten(info));
-    },
-    breadthFist,
-  );
-
-  return list2;
-}
-
-type FromItemInfo<I> = {
-  selfKey: unknown;
-  parentKey: unknown;
-  item: I;
-  index: number;
-};
-
-export type TTreeFromOptions<I extends TTreeItem> = {
-  getSelfKey: (item: I, index: number) => unknown;
-  getParentKey: (item: I, index: number) => unknown;
-  appendChild: (parentInfo: FromItemInfo<I>, info: FromItemInfo<I>) => unknown;
-};
-
-/**
- * 从扁平列表构建树形结构。
- *
- * @template I - 节点对象的类型，必须继承自 `AnyObject`。
- * @param {I[]} list - 扁平化的节点列表。
- * @param {TTreeFromOptions<I>} options - 构建树形结构的配置选项。
- * @param {function} options.getSelfKey - 获取节点自身唯一标识的函数。
- * @param {function} options.getParentKey - 获取节点父节点唯一标识的函数。
- * @param {function} options.appendChild - 将子节点添加到父节点的函数。
- * @returns {I | undefined} - 构建的树形结构的根节点，如果未找到根节点则返回 `undefined`。
- *
- * @example
- * ```typescript
- * const list = [
- *   { id: 1, parentId: null, name: 'Root' },
- *   { id: 2, parentId: 1, name: 'Child 1' },
- *   { id: 3, parentId: 1, name: 'Child 2' }
- * ];
- *
- * const tree = treeFrom(list, {
- *   getSelfKey: (item) => item.id,
- *   getParentKey: (item) => item.parentId,
- *   appendChild: (parent, info) => {
- *     if (!parent.children) parent.children = [];
- *     parent.children.push(info.item);
- *   }
- * });
- *
- * console.log(tree);
- * // {
- * //   id: 1,
- * //   parentId: null,
- * //   name: 'Root',
- * //   children: [
- * //     { id: 2, parentId: 1, name: 'Child 1' },
- * //     { id: 3, parentId: 1, name: 'Child 2' }
- * //   ]
- * // }
- * ```
- */
-export function treeFrom<I extends TTreeItem>(list: I[], options: TTreeFromOptions<I>): TTreeList<I> | undefined {
-  const keyMap = new Map<unknown, FromItemInfo<I>>();
-  const freeSet = new Set<FromItemInfo<I>>();
-  const roots: TTreeList<I> = [];
-
-  // 分配节点
-  const assign = (info: FromItemInfo<I>, isFirst = false) => {
-    const { selfKey, parentKey, item, index } = info;
-
-    // 父级指向为空
-    if (isNullish(parentKey)) {
-      roots.push(item);
-    }
-    // 父级指向不为空
-    else {
-      const parent = keyMap.get(parentKey);
-
-      // 未找到父级节点
-      if (isUndefined(parent)) {
-        // 游离节点
-        if (isFirst) freeSet.add(info);
-      }
-      // 已找到父级节点
-      else {
-        options.appendChild(parent, info);
-      }
-    }
-  };
-
-  // 构建 map
-  arrayEach(list, (item, index) => {
-    const selfKey = options.getSelfKey(item, index);
-    const parentKey = options.getParentKey(item, index);
-
-    if (isNullish(selfKey)) return;
-
-    const info = { selfKey, parentKey, item, index };
-    keyMap.set(selfKey, info);
-
-    assign(info, true);
-  });
-
-  // 处理游离节点
-  for (const info of freeSet.values()) {
-    assign(info);
-  }
-
-  return roots;
-}