@cloudcome/utils-core 1.1.1 → 1.2.0

package/src/fn.ts

@@ -1,197 +0,0 @@
-import { isNumber } from './type';
-import type { AnyFunction } from './types';
-
-/**
- * 一个空操作函数，不执行任何操作。
- *
- * @example
- * ```typescript
- * fnNoop(); // 不执行任何操作
- * ```
- */
-export function fnNoop() {
-  //
-}
-
-/**
- * 防抖函数的配置选项。
- */
-export type TDebounceOptions = {
-  /**
-   * 等待时间（毫秒）。
-   */
-  wait: number;
-  /**
-   * 是否在等待开始时立即执行一次
-   * @default false
-   */
-  leading?: boolean;
-};
-
-/**
- * 创建一个防抖函数，该函数会在指定的等待时间后执行，如果在等待时间内再次调用，则重新计时。
- *
- * @param fn - 需要防抖的函数。
- * @param wait - 等待时间（毫秒）或包含 `wait` 和 `leading` 选项的对象。
- * @returns 返回一个防抖函数，该函数具有 `cancel` 方法，用于取消防抖操作。
- *
- * @example
- * ```typescript
- * const debouncedFn = fnDebounce(() => {
- *   console.log('Debounced!');
- * }, 100);
- *
- * debouncedFn(); // 不会立即执行
- * debouncedFn(); // 重新计时
- * debouncedFn.cancel(); // 取消防抖操作
- * ```
- */
-export function fnDebounce<F extends AnyFunction>(fn: F, wait: number | TDebounceOptions) {
-  const options: TDebounceOptions = isNumber(wait) ? { wait } : wait;
-  let canceled = false;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  let timer: any;
-  let leading = false;
-
-  const debounced = function (this: unknown, ...args: Parameters<F>) {
-    if (canceled) return;
-
-    // 第一次执行
-    if (options.leading && !leading) {
-      leading = true;
-      fn.apply(this, args);
-      return;
-    }
-
-    // 最后一次执行
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      if (canceled) return;
-
-      fn.apply(this, args);
-    }, options.wait);
-  };
-
-  debounced.cancel = () => {
-    clearTimeout(timer);
-    canceled = true;
-  };
-
-  return debounced;
-}
-
-export type TThrottleOptions = {
-  /**
-   * 等待时间（毫秒）。
-   */
-  wait: number;
-
-  /**
-   * 是否在第一次调用时立即执行
-   * @default false
-   */
-  leading?: boolean;
-
-  /**
-   * 是否在调用结束后等待一段时间再执行
-   * @default false
-   */
-  trailing?: boolean;
-};
-
-/**
- * 创建一个节流函数，该函数会在指定的等待时间内最多执行一次，如果在等待时间内再次调用，则忽略后续调用。
- *
- * @param fn - 需要节流的函数。
- * @param wait - 等待时间（毫秒）或包含 `wait`、`leading` 和 `trailing` 选项的对象。
- * @returns 返回一个节流函数，该函数具有 `cancel` 方法，用于取消节流操作。
- *
- * @example
- * ```typescript
- * const throttledFn = fnThrottle(() => {
- *   console.log('Throttled!');
- * }, 100);
- *
- * throttledFn(); // 立即执行
- * throttledFn(); // 忽略
- * throttledFn.cancel(); // 取消节流操作
- * ```
- */
-export function fnThrottle<F extends AnyFunction>(fn: F, wait: number | TThrottleOptions) {
-  const options = isNumber(wait) ? { wait } : wait;
-  const waitFinal = options.wait;
-  let lastTime = 0;
-  let canceled = false;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  let timer: any;
-
-  const throttled = function (this: unknown, ...args: Parameters<F>) {
-    if (canceled) return;
-
-    const now = Date.now();
-
-    // 第一次执行
-    if (options.leading && lastTime === 0) {
-      lastTime = now;
-      fn.apply(this, args);
-    }
-
-    // 中间控频执行
-    else if (lastTime > 0 && now - lastTime >= waitFinal) {
-      lastTime = now;
-      fn.apply(this, args);
-    }
-
-    // 首次计时
-    else if (lastTime === 0) {
-      lastTime = now;
-    }
-
-    // 最后一次执行
-    if (options.trailing) {
-      clearTimeout(timer);
-      timer = setTimeout(() => {
-        fn.apply(this, args);
-      }, waitFinal);
-    }
-  };
-
-  throttled.cancel = () => {
-    canceled = true;
-    clearTimeout(timer);
-  };
-
-  return throttled;
-}
-
-/**
- * 创建一个只执行一次的函数，无论调用多少次，实际执行的函数体也只会执行一次。
- *
- * @param fn - 需要只执行一次的函数。
- * @returns 返回一个只执行一次的函数，该函数在第一次调用后会缓存结果并返回缓存的结果。
- *
- * @example
- * ```typescript
- * const onceFn = fnOnce(() => {
- *   console.log('This will be logged only once.');
- *   return 42;
- * });
- *
- * console.log(onceFn()); // 输出: This will be logged only once. 42
- * console.log(onceFn()); // 输出: 42
- * ```
- */
-export function fnOnce<F extends AnyFunction>(fn: F) {
-  let called = false;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  let result: any;
-
-  return function (this: unknown, ...args: Parameters<F>) {
-    if (!called) {
-      called = true;
-      result = fn.apply(this, args);
-    }
-
-    return result;
-  };
-}

package/src/index.ts

@@ -1 +0,0 @@
-export const VERSION = PKG_VERSION;

package/src/number.ts

@@ -1,236 +0,0 @@
-import { objectDefaults } from './object';
-import { STRING_DICT } from './string';
-
-export type NumberFixedOptions = {
-  /**
-   * 保留的小数位数
-   * @default 0
-   */
-  precision?: number;
-
-  /**
-   * 舍入方法，0 为四舍五入，1 为向上取整，-1 为向下取整
-   * @default 0
-   */
-  round?: 0 | 1 | -1;
-};
-
-/**
- * 对数字进行精确小数位数处理并按规则舍入
- * @param number 需要处理的原始数值
- * @param options 可选配置参数
- * @returns 处理后的数值（number类型）
- * @example
- * // 四舍五入示例
- * numberFixed(3.1415, { precision: 2 }); // 3.14
- * // 向上取整示例
- * numberFixed(3.1415, { precision: 2, round: 1 }); // 3.15
- * // 向下取整示例
- * numberFixed(3.9999, { precision: 1, round: -1 }); // 3.9
- */
-export function numberFixed(number: number, options?: NumberFixedOptions) {
-  const { precision = 0, round = 0 } = options || {};
-  const scale = 10 ** precision;
-
-  if (round === 1) {
-    return Math.ceil(number * scale) / scale;
-  }
-
-  if (round === -1) {
-    return Math.floor(number * scale) / scale;
-  }
-
-  return Math.round(number * scale) / scale;
-}
-
-/**
- * 生成指定范围内的随机整数
- * @param {number} min - 随机数的最小值（包含）
- * @param {number} max - 随机数的最大值（包含）
- * @returns {number} - 生成的随机整数
- * @example
- * // 生成 1 到 10 之间的随机整数
- * randomNumber(1, 10); // 可能返回 7
- */
-export function randomNumber(min: number, max: number): number {
-  const [minFinal, maxFinal] = min > max ? [max, min] : [min, max];
-  return Math.floor(Math.random() * (maxFinal - minFinal + 1) + minFinal);
-}
-
-/**
- * 数字缩写选项
- */
-export type NumberAbbrOptions = {
-  /**
-   * 进制基数，用于计算单位进阶（如 1000 表示千进制）
-   * @default 1000
-   */
-  base?: number;
-
-  /**
-   * 数值保留的小数位数
-   * @default 0
-   */
-  precision?: number;
-};
-
-/**
- * 将数字转换为带单位缩写的字符串表示
- *
- * @param {number} number - 需要转换的原始数值
- * @param {Array<string>} units - 单位数组，按从小到大顺序排列（如['B','KB','MB']），不能为空
- * @param {NumberAbbrOptions} [options] - 可选配置参数
- * @returns {string} - 转换后的带单位字符串（如"1.2KB"）
- * @example
- * // 基础用法
- * numberAbbr(1500, ['', 'K', 'M'], { base: 1000 }); // "1.5K"
- * @example
- * // 自定义小数位
- * numberAbbr(123456, ['B','KB','MB'], { precision: 1 }); // "0.1MB"
- * @example
- * // 处理不足基数的情况
- * numberAbbr(500, ['B','KB']); // "500B"
- */
-export function numberAbbr(number: number, units: Array<string>, options?: NumberAbbrOptions): string {
-  const { base = 1000, precision = 0 } = options || {};
-  const { length } = units;
-
-  if (length === 0) throw new Error('数字单位组不能为空');
-
-  let numberFinal = number;
-  let step = 0;
-
-  while (numberFinal >= base && step < length - 1) {
-    numberFinal = numberFinal / base;
-    step++;
-  }
-
-  const value = numberFixed(numberFinal, { precision, round: -1 });
-  const unit = units[step];
-
-  return `${value}${unit}`;
-}
-
-/**
- * 将文件大小转换为带单位缩写的字符串表示
- *
- * @param {number} number - 需要转换的文件大小数值
- * @param {number} [precision=0] - 数值保留的小数位数
- * @returns {string} - 转换后的带单位字符串（如"1.2KB"）
- * @example
- * // 基础用法
- * fileSizeAbbr(1024); // "1KB"
- * @example
- * // 自定义小数位
- * fileSizeAbbr(123456, 1); // "0.1MB"
- */
-export function fileSizeAbbr(number: number, precision = 0) {
-  return numberAbbr(number, ['B', 'KB', 'MB', 'GB', 'TB'], {
-    base: 1024,
-    precision,
-  });
-}
-
-/**
- * 将十进制数转换为指定进制的字符串表示
- *
- * @param {number | bigint} decimal - 需要转换的十进制数，可以是任意长度的数字或大整数
- * @param {string} [dict] - 用于表示进制的字符字典，默认为数字、小写字母和大写字母的组合（62 进制）
- * @returns {string} - 转换后的指定进制字符串
- * @throws {Error} - 如果字符字典的长度小于 2，将抛出错误
- * @example
- * // 默认 62 进制
- * numberConvert(123456789); // "8M0kX"
- * @example
- * // 自定义 16 进制
- * numberConvert(255, '0123456789ABCDEF'); // "FF"
- * @example
- * // 处理大整数
- * numberConvert(9007199254740991n); // "2gosa7pa2GV"
- */
-export function numberConvert(decimal: number | bigint, dict?: string): string {
-  const dictFinal = dict || STRING_DICT;
-
-  if (dictFinal.length < 2) throw new Error('进制转换字典长度不能小于 2');
-
-  let bigInt = BigInt(decimal);
-  const symbol = bigInt < 0n ? '-' : '';
-  bigInt = bigInt < 0n ? -bigInt : bigInt;
-  const result: Array<string> = [];
-  const { length } = dictFinal;
-  const bigLength = BigInt(length);
-  const calculate = (): void => {
-    const y = Number(bigInt % bigLength);
-
-    bigInt = bigInt / bigLength;
-    result.unshift(dictFinal[y]);
-
-    if (bigInt > 0) {
-      calculate();
-    }
-  };
-
-  calculate();
-
-  return symbol + result.join('');
-}
-
-/**
- * 数字格式化配置选项
- */
-export type NumberFormatOptions = {
-  /**
-   * 分隔符字符，用于数字分隔
-   * @default ','
-   * @example 使用 '_' 分隔符时，123456 会格式化为 '123_456'
-   */
-  separator?: string;
-
-  /**
-   * 分隔步长，即每隔多少位添加分隔符
-   * @default 3
-   * @example 步长为 2 时，123456 会格式化为 '12,34,56'
-   */
-  step?: number;
-};
-
-/**
- * 数字格式化
- * @param [number] {number} 数字
- * @param options {NumberFormatOptions} 格式化配置
- * @returns {string} 分割后的字符串
- * @example
- * // 使用默认分隔符和步长
- * numberFormat(123456.789); // => "123,456.789"
- * // 自定义分隔符
- * numberFormat(123456.789, '_'); // => "123_456.789"
- * // 自定义步长
- * numberFormat(123456.789, 2); // => "12,34,56.789"
- * // 使用对象配置
- * numberFormat(123456.789, { separator: '.', step: 4 }); // => "12.3456.789"
- */
-export function numberFormat(number: number, options: NumberFormatOptions): string;
-export function numberFormat(number: number, separator: string): string;
-export function numberFormat(number: number, step: number): string;
-export function numberFormat(number: number): string;
-export function numberFormat(number: number, options?: NumberFormatOptions | string | number) {
-  let optionsFinal: Required<NumberFormatOptions> = {
-    separator: ',',
-    step: 3,
-  };
-
-  if (typeof options === 'string') {
-    optionsFinal.separator = options;
-  } else if (typeof options === 'number') {
-    optionsFinal.step = options;
-  } else {
-    optionsFinal = objectDefaults(options || {}, optionsFinal) as Required<NumberFormatOptions>;
-  }
-
-  const { separator, step } = optionsFinal;
-  const arr = String(number).split('.');
-  const re = new RegExp(`(\\d)(?=(\\d{${step}})+(?!\\d))`, 'g');
-  const p1 = arr[0].replace(re, `$1${separator}`);
-
-  return p1 + (arr[1] ? `.${arr[1]}` : '');
-}

package/src/object/get-set.ts

@@ -1,273 +0,0 @@
-import { isArray, isObject, isUndefined } from '@/type';
-import type { AnyArray, AnyObject } from '@/types';
-
-// @ref https://stackoverflow.com/a/67609485
-
-type Idx<T, K> = K extends keyof T
-  ? T[K]
-  : number extends keyof T
-    ? K extends `${number}`
-      ? T[number]
-      : never
-    : never;
-
-type Join<K, P> = K extends string | number
-  ? P extends string | number
-    ? `${K}${'' extends P ? '' : '.'}${P}`
-    : never
-  : never;
-
-type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, ...0[]];
-
-export type ObjectPath<O, D extends number = 4> = [D] extends [never]
-  ? never
-  : O extends object
-    ? {
-        [K in keyof O]-?: K extends string | number ? `${K}` | Join<K, ObjectPath<O[K], Prev[D]>> : never;
-      }[keyof O]
-    : '';
-
-export type ObjectLeafPath<O, D extends number = 4> = [D] extends [never]
-  ? never
-  : O extends object
-    ? {
-        [K in keyof O]-?: K extends string | number
-          ? O[K] extends string | number
-            ? `${K}` | Join<K, ObjectLeafPath<O[K], Prev[D]>>
-            : Join<K, ObjectLeafPath<O[K], Prev[D]>>
-          : never;
-      }[keyof O]
-    : '';
-
-export type ObjectPathValue<O, P extends ObjectPath<O, 4>> = P extends `${infer Key}.${infer Rest}`
-  ? Rest extends ObjectPath<Idx<O, Key>, 4>
-    ? ObjectPathValue<Idx<O, Key>, Rest>
-    : never
-  : Idx<O, P>;
-
-function pathToKeys(path: string | string[]) {
-  // 下文用到该数组时会进行修改操作，因此复制一份
-  if (isArray(path)) return [...path];
-
-  let pathFinal = path.replace(/\[(\w+)\]/g, '.$1');
-  pathFinal = pathFinal.replace(/^\./, '');
-  return pathFinal.split('.');
-}
-
-function isObjectOrArray(v: unknown) {
-  return isObject(v) || isArray(v);
-}
-
-/**
- * 表示对象节点的信息。
- *
- * @template V - 键值的类型。
- */
-export type TObjectNode<V = unknown | undefined> = {
-  /**
-   * 当前节点的父级对象。
-   */
-  parent: unknown | undefined;
-
-  /**
-   * 当前节点的键名路径。
-   */
-  keys: string[];
-
-  /**
-   * 当前节点的键名。
-   */
-  key: string | undefined;
-
-  /**
-   * 当前节点的键值。
-   */
-  value: V;
-};
-
-/**
- * 根据属性路径获取属性值
- * @param {O} obj
- * @param {string | string[] | P} path
- * @returns {TObjectNode<O>}
- * 根据属性路径获取属性值。
- *
- * @template O - 目标对象的类型。
- * @template P - 属性路径的类型。
- * @param {O} obj - 要操作的目标对象。
- * @param {P | string | string[]} path - 属性路径，可以是字符串或字符串数组。支持点分隔符（如 "a.b.c"）或数组形式（如 ["a", "b", "c"]）。
- * @returns {TObjectNode<O>} 返回一个包含父级、键名路径、键名和键值的对象节点。
- *
- * @example
- * ```typescript
- * const obj = { a: { b: { c: 42 } } };
- * const result = objectGet(obj, 'a.b.c');
- * console.log(result.value); // 输出 42
- * ```
- */
-export function objectGet<O extends AnyObject, P extends ObjectPath<O>>(
-  obj: O,
-  path: P | string | string[],
-): TObjectNode<O> {
-  const keys = pathToKeys(path);
-  const lastKey = keys.pop();
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  let parent: any = obj;
-  const keysFinal: string[] = [];
-
-  for (let i = 0; i < keys.length; i++) {
-    const key = keys[i];
-
-    keysFinal.push(key);
-    if (!isObjectOrArray(parent)) break;
-
-    // @ts-ignore
-    parent = parent[key];
-  }
-
-  return {
-    parent: parent,
-    keys: keysFinal,
-    key: lastKey,
-    // @ts-ignore
-    value: isObjectOrArray(parent) && lastKey ? parent[lastKey] : undefined,
-  };
-}
-
-// /**
-//  * 根据路径获取对象叶子节点值
-//  * @param {O} obj
-//  * @param {P} path
-//  * @returns {ObjectNode<O>}
-//  */
-// export function objectLeaf<O extends AnyObject, P extends ObjectLeafPath<O>>(obj: O, path: P) {
-//   return objectGet(obj, path);
-// }
-
-/**
- * 配置选项，用于控制 `objectSet` 的行为。
- *
- * @template O - 目标对象的类型。
- */
-export type TObjectSetOptions<O extends AnyObject> = {
-  /**
-   * 在设置值之前调用的钩子函数。
-   * 如果返回 `false`，则阻止设置值。
-   *
-   * @param {TObjectNode<O> & { key: string }} node - 当前节点信息。
-   * @returns {boolean | undefined | void} 返回 `false` 时阻止设置值。
-   */
-  // biome-ignore lint/suspicious/noConfusingVoidType: <explanation>
-  beforeSet(node: TObjectNode<O> & { key: string }): boolean | undefined | void;
-
-  /**
-   * 当遇到未定义的中间节点时调用的钩子函数。
-   * 返回值将用于创建中间节点。
-   *
-   * @param {TObjectNode<O>} node - 当前节点信息。
-   * @returns {AnyObject | AnyArray | undefined | void} 返回值将用于创建中间节点。
-   */
-  // biome-ignore lint/suspicious/noConfusingVoidType: <explanation>
-  undefinedSet(node: TObjectNode<O>): AnyObject | AnyArray | undefined | void;
-};
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
-const defaultObjectSetOptions: TObjectSetOptions<any> = {
-  beforeSet: () => true,
-  undefinedSet: () => ({}),
-};
-
-/**
- * 根据属性路径设置属性值
- * @param {AnyObject} obj
- * @param {string} path
- * @param {V} val
- * @param {Partial<TObjectSetOptions<O>>} options
- * @returns {TObjectNode<O, V>}
- * 根据属性路径设置属性值。
- *
- * @template O - 目标对象的类型。
- * @template V - 要设置的值的类型。
- * @param {O} obj - 要操作的目标对象。
- * @param {string | string[]} path - 属性路径，可以是字符串或字符串数组。支持点分隔符（如 "a.b.c"）或数组形式（如 ["a", "b", "c"]）。
- * @param {V} val - 要设置的值。
- * @param {Partial<TObjectSetOptions<O>>} [options] - 可选配置项，用于控制设置行为。
- * @returns {TObjectNode<V>} 返回一个包含父级、键名路径、键名和键值的对象节点。
- *
- * @example
- * ```typescript
- * const obj = {};
- * objectSet(obj, 'a.b.c', 42);
- * console.log(obj); // 输出 { a: { b: { c: 42 } } }
- *
- * objectSet(obj, 'a.b.c', 100, {
- *   beforeSet: (node) => node.key === 'c',
- * });
- * console.log(obj); // 输出 { a: { b: { c: 100 } } }
- * ```
- */
-export function objectSet<O extends AnyObject, V>(
-  obj: O,
-  path: string | string[],
-  val: V,
-  options?: Partial<TObjectSetOptions<O>>,
-): TObjectNode<V> {
-  const { beforeSet, undefinedSet } = Object.assign({}, defaultObjectSetOptions, options);
-  const keys = pathToKeys(path);
-  const lastKey = keys.pop();
-  let parent = obj;
-  let stopped = false;
-  const keysFinal: string[] = [];
-
-  for (const key of keys) {
-    let val = parent[key];
-    keysFinal.push(key);
-
-    if (isUndefined(val)) {
-      const seted = undefinedSet({
-        parent: parent,
-        keys: keysFinal,
-        key: key,
-        value: val,
-      });
-
-      if (!seted) {
-        stopped = true;
-        break;
-      }
-
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      val = parent[key] = seted;
-    }
-
-    // @ts-ignore
-    parent = val;
-  }
-
-  if (!stopped && !isUndefined(lastKey)) {
-    keysFinal.push(lastKey);
-
-    if (
-      beforeSet({
-        parent: parent,
-        keys: keysFinal,
-        key: lastKey,
-        value: parent[lastKey],
-      })
-    ) {
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      parent[lastKey] = val;
-    }
-  }
-
-  return {
-    keys: keysFinal,
-    parent: parent,
-    key: lastKey,
-    value: val,
-  };
-}