@cloudcome/utils-core 1.1.0 → 1.1.1

package/src/number.ts

@@ -0,0 +1,236 @@
+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/{dist/object/each.d.ts → src/object/each.ts}

@@ -1,4 +1,5 @@
-import { AnyObject, MaybePromise } from '../types';
+import type { AnyObject, MaybePromise } from '@/types';
+
 /**
  * 遍历对象的每个键值对，并对每个键值对执行提供的回调函数。
  *
@@ -15,7 +16,17 @@ import { AnyObject, MaybePromise } from '../types';
  * console.log(results); // [['a', 1], ['b', 2], ['c', 3]]
  * ```
  */
-export declare function objectEach<O extends AnyObject, K extends keyof O & (string | number)>(obj: O, iterator: (this: O, val: O[K], key: K) => false | unknown): void;
+export function objectEach<O extends AnyObject, K extends keyof O & (string | number)>(
+  obj: O,
+  iterator: (this: O, val: O[K], key: K) => false | unknown,
+): void {
+  for (const [key, val] of Object.entries(obj)) {
+    if (iterator.call(obj, val as O[K], key as K) === false) {
+      break;
+    }
+  }
+}
+
 /**
  * 异步遍历对象的每个键值对，并对每个键值对执行提供的回调函数。
  *
@@ -33,4 +44,13 @@ export declare function objectEach<O extends AnyObject, K extends keyof O & (str
  * console.log(results); // [['a', 1], ['b', 2], ['c', 3]]
  * ```
  */
-export declare function objectEachAsync<O extends AnyObject, K extends keyof O & (string | number)>(obj: O, iterator: (this: O, val: O[K], key: K) => MaybePromise<false | unknown>): Promise<void>;
+export async function objectEachAsync<O extends AnyObject, K extends keyof O & (string | number)>(
+  obj: O,
+  iterator: (this: O, val: O[K], key: K) => MaybePromise<false | unknown>,
+): Promise<void> {
+  for (const [key, val] of Object.entries(obj)) {
+    if ((await iterator.call(obj, val as O[K], key as K)) === false) {
+      break;
+    }
+  }
+}

package/src/object/get-set.ts

@@ -0,0 +1,273 @@
+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,
+  };
+}

package/src/object/is.ts

@@ -0,0 +1,128 @@
+import { isArray, isObject, isString, typeIs } from '@/type';
+import type { AnyArray, AnyFunction, AnyObject } from '@/types';
+
+/**
+ * 检查一个对象是否为空对象（不包含任何自有属性，包括符号属性）。
+ *
+ * @param obj - 要检查的对象
+ * @returns 如果对象没有自有属性（包括符号属性）则返回 true，否则返回 false
+ *
+ * @example
+ * ```typescript
+ * isEmptyObject({}); // true
+ * isEmptyObject({ a: 1 }); // false
+ * isEmptyObject(Object.create(null)); // true
+ * isEmptyObject({ [Symbol('key')]: 'value' }); // false
+ * ```
+ */
+export function isEmptyObject(obj: AnyObject): boolean {
+  return Object.getOwnPropertyNames(obj).length === 0 && Object.getOwnPropertySymbols(obj).length === 0;
+}
+
+/**
+ * 检查一个对象是否为纯对象（通过对象字面量或Object构造函数创建，而非其他构造函数的实例）。
+ *
+ * @param obj - 要检查的对象
+ * @returns 如果是纯对象则返回 true，否则返回 false
+ *
+ * @example
+ * ```typescript
+ * isPlainObject({}); // true
+ * isPlainObject(Object.create(null)); // true
+ * isPlainObject(new Date()); // false
+ * isPlainObject([]); // false
+ * isPlainObject(() => {}); // false
+ * ```
+ */
+export function isPlainObject(obj: AnyObject): boolean {
+  const proto: unknown = Object.getPrototypeOf(obj);
+
+  // 对象无原型
+  if (!proto) return true;
+
+  // 是否对象直接实例
+  return proto === Object.prototype;
+}
+
+// 移除，原因是，定义对象尽可能的使用 type 关键字即可避开此问题
+// /**
+//  * 精确对象，常用于联合类型判断
+//  * 相关 bug：https://l.ydr.me/Zp88vFKc
+//  */
+// // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+// export type ExactObject<T = any> = T extends AnyFunction
+//   ? never
+//   : T extends AnyArray
+//     ? never
+//     : T extends object
+//       ? T
+//       : never;
+//
+// /**
+//  * 检查值是否为精确接口对象
+//  * @param object - 传入对象，必须是一个对象与其他类型的联合
+//  * @returns 如果值为对象则返回 true，否则返回 false
+//  * @example
+//  * ```typescript
+//  * type Id = string | string[] | (() => string);
+//  *
+//  * interface Cache {
+//  *   id?: Id;
+//  * }
+//  *
+//  * type Share = {
+//  *   id?: Id;
+//  * }
+//  *
+//  * interface Options {
+//  *   cache?: Id | Cache;
+//  *   share?: Id | Share;
+//  * }
+//  *
+//  * function test(options: Options) {
+//  *   // string | string[] | (() => string) | Cache | undefined
+//  *   const cache = options.cache;
+//  *
+//  *   // Cache
+//  *   // 需要使用
+//  *   if (isExactObject(cache)) {
+//  *     cache.id;
+//  *   }
+//  *   // string[]
+//  *   else if (isArray(cache)) {
+//  *     cache.push();
+//  *   }
+//  *   // string
+//  *   else if (isString(cache)) {
+//  *     cache.charCodeAt(0);
+//  *   }
+//  *   // (() => string) | undefined
+//  *   else {
+//  *     cache?.();
+//  *   }
+//  *
+//  *   // string | string[] | (() => string) | Share | undefined
+//  *   const share = options.share;
+//  *
+//  *   // Share
+//  *   if (isObject(share)) {
+//  *     share.id;
+//  *   }
+//  *   // string[]
+//  *   else if (isArray(share)) {
+//  *     share.push();
+//  *   }
+//  *   // string
+//  *   else if (isString(share)) {
+//  *     share.charCodeAt(0);
+//  *   }
+//  *   // (() => string) | undefined
+//  *   else {
+//  *     share?.();
+//  *   }
+//  * }
+//  * ```
+//  */
+// export function isExactObject<T>(object: T): object is ExactObject<T> {
+//   return typeIs(object) === 'object';
+// }