@cloudcome/utils-core 0.0.0 → 1.1.1

package/src/enum.ts

@@ -0,0 +1,171 @@
+import type { AnyObject, MergeIntersection, UnionToIntersection, UnionToTuple } from './types';
+
+export type EnumKey = string;
+export type EnumValue = number | string;
+export type EnumMetaAppend = {
+  key?: string;
+  value?: string | number;
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  [key: string]: any;
+};
+export type EnumMeta<A extends EnumMetaAppend> = A & {
+  value: EnumValue;
+};
+export type EnumDescription<A extends EnumMetaAppend> = Record<EnumKey, EnumMeta<A>>;
+
+const enumError = Symbol('enumKeyError');
+
+type _StartWithDollarSign<T extends string> = T extends `$${infer R}` ? R : never;
+
+type _CheckDefinition<O extends AnyObject> = {
+  // [K in keyof O & string]: K extends Capitalize<K> ? O[K] : `错误：枚举键名 ${K} 必须大写字母开头`;
+  [K in keyof O & string]: K extends Capitalize<K>
+    ? K extends `$${infer R}`
+      ? O[K] & { [enumError]: `错误：枚举键名 ${K} 不能以 $ 符号开头` }
+      : O[K]
+    : O[K] & { [enumError]: `错误：枚举键名 ${K} 必须以大写字母开头` };
+};
+
+type _ToOriginDefProp<T extends AnyObject> = {
+  [K in keyof T as `$${K & string}`]: MergeIntersection<T[K] & { readonly key: K }>;
+};
+
+type _KVRecord<T> = T extends Record<string, AnyObject>
+  ? {
+      readonly [K in keyof T]: T[K]['value'];
+    }
+  : never;
+
+type _VKRecord<T> = T extends Record<string, AnyObject>
+  ? MergeIntersection<
+      UnionToIntersection<
+        {
+          [K in keyof T]: {
+            [P in keyof T[K] as P extends 'value' ? T[K][P] & (string | number) : never]: K;
+          };
+        }[keyof T]
+      >
+    >
+  : never;
+
+export type EnumExpose<A extends EnumMetaAppend, E extends EnumDescription<A>> = _ToOriginDefProp<E> &
+  _KVRecord<E> & {
+    readonly definition: E;
+    readonly descriptions: MergeIntersection<A & { key: keyof E }>[];
+    readonly keys: UnionToTuple<keyof E>;
+    readonly length: UnionToTuple<keyof E>['length'];
+    readonly values: UnionToTuple<E[keyof E]['value']>;
+    readonly kvRecord: _KVRecord<E>;
+    readonly vkRecord: _VKRecord<E>;
+    toKeyRecord: <P extends keyof A>(prop: P) => Record<keyof E, A[P]>;
+    toValueRecord: <P extends keyof A>(prop: P) => Record<E[keyof E]['value'], A[P]>;
+  };
+
+/**
+ * 定义一个枚举类型，如果需要类型提示，需要使用 declareEnum 函数定义枚举。
+ * @template A - 枚举元数据附加类型，扩展自 EnumMetaAppend
+ * @template E - 枚举描述类型，键为枚举键名，值为枚举元数据
+ * @param {_CheckDefinition<E>} definition - 枚举定义对象
+ * @returns {EnumExpose<A, E>} 返回枚举的完整暴露对象
+ * @example
+ * ```typescript
+ * const Status = defineEnum({
+ *   Pending: { value: 0, label: '待处理' },
+ *   Approved: { value: 1, label: '已批准' }
+ * });
+ * ```
+ *
+ * @property {E} definition - 原始枚举定义对象
+ * @property {Array<MergeIntersection<A & { key: keyof E }>>} descriptions - 枚举项的完整描述数组
+ * @property {UnionToTuple<keyof E>} keys - 枚举键名的元组
+ * @property {"UnionToTuple<keyof E>[\"length\"]"} length - 枚举项的数量
+ * @property {UnionToTuple<E[keyof E]["value"]>} values - 枚举值的元组
+ * @property {Record<keyof E, E[keyof E]["value"]>} kvRecord - 键到值的映射记录
+ * @property {Record<E[keyof E]["value"], E[keyof E]>} vkRecord - 值到键的映射记录
+ * @property {function} toKeyRecord - 根据属性名创建键到属性值的映射记录
+ * @property {function} toValueRecord - 根据属性名创建值到属性值的映射记录
+ */
+function defineEnum<A extends EnumMetaAppend, const E extends EnumDescription<A>>(
+  definition: _CheckDefinition<E>,
+): EnumExpose<A, E> {
+  const keys = Object.keys(definition);
+
+  return {
+    ...[...Object.entries(definition)].reduce((acc, [key, dfn]) => {
+      if (key[0].toUpperCase() !== key[0]) {
+        throw new Error(`错误：枚举键名 ${key} 必须以大写字母开头`);
+      }
+
+      if (key.startsWith('$')) {
+        throw new Error(`错误：枚举键名 ${key} 不能以 $ 符号开头`);
+      }
+
+      // @ts-ignore
+      acc[key] = dfn.value;
+      // @ts-ignore
+      acc[`$${key}`] = { key, ...dfn };
+      return acc;
+    }, {}),
+    definition,
+    descriptions: keys.map((key) => ({
+      key,
+      ...definition[key],
+    })),
+    keys,
+    length: keys.length,
+    values: keys.map((key) => definition[key as keyof E].value),
+    kvRecord: keys.reduce((acc, key) => {
+      // @ts-ignore
+      acc[key] = definition[key].value;
+      return acc;
+    }, {}),
+    vkRecord: keys.reduce((acc, key) => {
+      // @ts-ignore
+      acc[definition[key].value] = key;
+      return acc;
+    }, {}),
+    toKeyRecord<P extends keyof A>(prop: P) {
+      return keys.reduce((acc, key) => {
+        // @ts-ignore
+        acc[key] = definition[key][prop];
+        return acc;
+      }, {});
+    },
+    toValueRecord<P extends keyof A>(prop: P) {
+      return keys.reduce(
+        (acc, key) => {
+          // @ts-ignore
+          acc[definition[key].value] = definition[key][prop];
+          return acc;
+        },
+        {} as Record<E[keyof E]['value'], A[P]>,
+      );
+    },
+  } as unknown as EnumExpose<A, E>;
+}
+
+/**
+ * 声明一个枚举工厂函数
+ * @template A - 枚举元数据附加类型，扩展自 EnumMetaAppend
+ * @returns {Object} 返回包含 define 方法的对象
+ *
+ * @property {function} define - 定义枚举的函数
+ *   @template E - 枚举描述类型
+ *   @param {_CheckDefinition<E>} definition - 枚举定义对象
+ *   @returns {EnumExpose<A, E>} 返回枚举的完整暴露对象
+ *   @example
+ *   ```typescript
+ *   const createStatusEnum = declareEnum<{ label: string }>();
+ *   const Status = createStatusEnum.define({
+ *     Pending: { value: 0, label: '待处理' },
+ *     Approved: { value: 1, label: '已批准' }
+ *   });
+ *   ```
+ */
+export function declareEnum<A extends EnumMetaAppend>() {
+  return {
+    define<const E extends EnumDescription<A>>(definition: _CheckDefinition<E>): EnumExpose<A, E> {
+      return defineEnum(definition);
+    },
+  };
+}

package/src/env.ts

@@ -0,0 +1,62 @@
+import { isNullish } from './type';
+
+/**
+ * 判断当前环境是否为浏览器环境
+ * @returns 如果是浏览器环境返回 true，否则返回 false
+ */
+export function isBrowser() {
+  if (IS_TEST) return TEST_MOCK.IS_BROWSER || false;
+
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+/**
+ * 判断当前环境是否为 Node.js 环境
+ * @returns 如果是 Node.js 环境返回 true，否则返回 false
+ */
+export function isNode() {
+  if (IS_TEST) return TEST_MOCK.IS_NODE || false;
+
+  return typeof process !== 'undefined' && !isNullish(process.versions) && !isNullish(process.versions.node);
+}
+
+/**
+ * 判断当前环境是否为 Web Worker 环境
+ * @returns 如果是 Web Worker 环境返回 true，否则返回 false
+ * @remarks
+ * 使用 @ts-ignore 忽略 self 的类型检查，因为 self 在 Web Worker 中可用但在其他环境中可能未定义
+ */
+export function isWorker() {
+  // @ts-ignore
+  return typeof self !== 'undefined' && self.importScripts != null;
+}
+
+/**
+ * 判断当前操作系统是否为 macOS
+ * @returns 如果是 macOS 返回 true，否则返回 false
+ * @remarks
+ * 在浏览器环境中通过 navigator.platform 检测，在 Node.js 环境中通过 process.platform 检测
+ */
+export function isMacOS() {
+  return isBrowser() ? /^mac/i.test(navigator.platform) : isNode() ? /^darwin/i.test(process.platform) : false;
+}
+
+/**
+ * 判断当前操作系统是否为 Linux
+ * @returns 如果是 Linux 返回 true，否则返回 false
+ * @remarks
+ * 在浏览器环境中通过 navigator.platform 检测，在 Node.js 环境中通过 process.platform 检测
+ */
+export function isLinux() {
+  return isBrowser() ? /^linux/i.test(navigator.platform) : isNode() ? /^linux/i.test(process.platform) : false;
+}
+
+/**
+ * 判断当前操作系统是否为 Windows
+ * @returns 如果是 Windows 返回 true，否则返回 false
+ * @remarks
+ * 在浏览器环境中通过 navigator.platform 检测，在 Node.js 环境中通过 process.platform 检测
+ */
+export function isWindows() {
+  return isBrowser() ? /^win/i.test(navigator.platform) : isNode() ? /^win/i.test(process.platform) : false;
+}

package/src/error.ts

@@ -0,0 +1,31 @@
+import { isError, isNullish } from './type';
+import type { AnyObject } from './types';
+
+/**
+ * 标准化处理 Error 对象，适用于 try-catch
+ * @param throwError 接收抛出的错误字符串或者 Error 对象或字符串
+ * @returns {Error}
+ * @example
+ * const error = errorNormalize('这是一个错误');
+ * console.log(error.message); // 输出: 这是一个错误
+ */
+export function errorNormalize<E extends Error | unknown = unknown>(throwError: E) {
+  return (
+    isError(throwError) ? throwError : new Error(String(isNullish(throwError) ? '' : throwError))
+  ) as E extends Error ? E : Error;
+}
+
+/**
+ * 分配对象到 Error 对象上，适用于扩展 Error 实例，不影响原型和构造函数
+ * @param {Error} error
+ * @param {E} source
+ * @returns {Error & E}
+ * @example
+ * const error = new Error('原始错误');
+ * const extendedError = errorAssign(error, { code: 404, message: '未找到资源' });
+ * console.log(extendedError.code); // 输出: 404
+ * console.log(extendedError.message); // 输出: 未找到资源
+ */
+export function errorAssign<E extends AnyObject>(error: Error, source: E): Error & E {
+  return Object.assign(error, source) as Error & E;
+}

package/src/exception.ts

@@ -0,0 +1,68 @@
+import { objectDefaults } from './object';
+import type { AnyObject } from './types';
+
+/**
+ * 构建异常选项
+ */
+export type BuildExceptionOptions = {
+  /**
+   * 自定义错误消息格式函数
+   * @param name 错误名称
+   * @param message 原始错误消息
+   * @returns 格式化后的错误消息
+   * @example
+   * (name, message) => `${name}::${message}`
+   */
+  format?: (name: string, message: string) => string;
+};
+
+/**
+ * 默认的异常构建选项
+ */
+const defaults: BuildExceptionOptions = {
+  /**
+   * 默认消息格式函数
+   * @default (name, message) => `[${name}] ${message}`
+   */
+  format: (name, message) => `[${name}] ${message}`,
+};
+
+/**
+ * 构建自定义异常类
+ * @template T 额外属性的类型
+ * @param name 异常类名称
+ * @param options 构建选项
+ * @returns 自定义异常类
+ * @example
+ * const MyException = buildException<{ code: number }>('MyException');
+ * const err = new MyException('error', { code: 404 });
+ *
+ * @example
+ * const SimpleException = buildException('SimpleException');
+ * const err = new SimpleException('error', undefined);
+ */
+export function buildException<T = void>(name: string, options?: BuildExceptionOptions) {
+  const { format } = objectDefaults(options || {}, defaults) as Required<BuildExceptionOptions>;
+
+  return class extends Error {
+    constructor(message: string, extra: T) {
+      super(format(name, message));
+      this.name = name;
+      Object.assign(this, extra);
+    }
+  } as unknown as {
+    new (message: string, extra: T): Error & T;
+  };
+}
+
+// const MyException = buildException<{ foo: string; bar: number }>('MyException: ');
+// const myException = new MyException('bar', { foo: '1', bar: 1 });
+// myException.foo;
+// myException.bar;
+// myException.name;
+// myException.message;
+// myException.stack;
+// myException.cause;
+
+// const MyException2 = buildException('MyException2: ');
+// const myException2 = new MyException2('bar');

package/src/fn.ts

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

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