@cloudcome/utils-core 1.1.1 → 1.2.0

package/src/easing.ts

@@ -1,166 +0,0 @@
-/**
- * https://github.com/gre/bezier-easing
- * BezierEasing - use bezier curve for transition easing function
- * by Gaëtan Renaudeau 2014 - 2015 – MIT License
- */
-
-// These values are established by empiricism with tests (tradeoff: performance VS precision)
-const NEWTON_ITERATIONS = 4;
-const NEWTON_MIN_SLOPE = 0.001;
-const SUBDIVISION_PRECISION = 0.0000001;
-const SUBDIVISION_MAX_ITERATIONS = 10;
-
-const kSplineTableSize = 11;
-const kSampleStepSize = 1.0 / (kSplineTableSize - 1.0);
-
-const float32ArraySupported = typeof Float32Array === 'function';
-
-function A(aA1: number, aA2: number) {
-  return 1.0 - 3.0 * aA2 + 3.0 * aA1;
-}
-function B(aA1: number, aA2: number) {
-  return 3.0 * aA2 - 6.0 * aA1;
-}
-function C(aA1: number) {
-  return 3.0 * aA1;
-}
-
-// Returns x(t) given t, x1, and x2, or y(t) given t, y1, and y2.
-function calcBezier(aT: number, aA1: number, aA2: number) {
-  return ((A(aA1, aA2) * aT + B(aA1, aA2)) * aT + C(aA1)) * aT;
-}
-
-// Returns dx/dt given t, x1, and x2, or dy/dt given t, y1, and y2.
-function getSlope(aT: number, aA1: number, aA2: number) {
-  return 3.0 * A(aA1, aA2) * aT * aT + 2.0 * B(aA1, aA2) * aT + C(aA1);
-}
-
-function binarySubdivide(aX: number, aA: number, aB: number, mX1: number, mX2: number) {
-  let currentX: number;
-  let currentT: number;
-  let i = 0;
-  let aBFinal = aB;
-  let aAFinal = aA;
-
-  do {
-    currentT = aAFinal + (aBFinal - aAFinal) / 2.0;
-    currentX = calcBezier(currentT, mX1, mX2) - aX;
-    if (currentX > 0.0) {
-      aBFinal = currentT;
-    } else {
-      aAFinal = currentT;
-    }
-  } while (Math.abs(currentX) > SUBDIVISION_PRECISION && ++i < SUBDIVISION_MAX_ITERATIONS);
-  return currentT;
-}
-
-function newtonRaphsonIterate(aX: number, aGuessT: number, mX1: number, mX2: number) {
-  let aGuessTFinal = aGuessT;
-  for (let i = 0; i < NEWTON_ITERATIONS; ++i) {
-    const currentSlope = getSlope(aGuessTFinal, mX1, mX2);
-    if (currentSlope === 0.0) {
-      return aGuessTFinal;
-    }
-    const currentX = calcBezier(aGuessTFinal, mX1, mX2) - aX;
-    aGuessTFinal -= currentX / currentSlope;
-  }
-  return aGuessTFinal;
-}
-
-function LinearEasing(x: number) {
-  return x;
-}
-
-/**
- * 创建一个基于贝塞尔曲线的缓动函数。
- *
- * @param x1 - 贝塞尔曲线的第一个控制点的 X 坐标，必须在 [0, 1] 范围内。
- * @param y1 - 贝塞尔曲线的第一个控制点的 Y 坐标，必须在 [0, 1] 范围内。
- * @param x2 - 贝塞尔曲线的第二个控制点的 X 坐标，必须在 [0, 1] 范围内。
- * @param y2 - 贝塞尔曲线的第二个控制点的 Y 坐标，必须在 [0, 1] 范围内。
- * @returns 返回一个缓动函数，该函数接受一个参数 x（范围在 0 到 1 之间），并返回相应的缓动值。
- * @throws 如果 mX1 或 mX2 不在 [0, 1] 范围内，则抛出错误。
- */
-export function createEasingFn(x1: number, y1: number, x2: number, y2: number) {
-  if (!(0 <= x1 && x1 <= 1 && 0 <= x2 && x2 <= 1)) {
-    throw new Error('bezier x values must be in [0, 1] range');
-  }
-
-  if (x1 === y1 && x2 === y2) {
-    return LinearEasing;
-  }
-
-  // Precompute samples table
-  const sampleValues = float32ArraySupported ? new Float32Array(kSplineTableSize) : new Array(kSplineTableSize);
-  for (let i = 0; i < kSplineTableSize; ++i) {
-    sampleValues[i] = calcBezier(i * kSampleStepSize, x1, x2);
-  }
-
-  function getTForX(aX: number) {
-    let intervalStart = 0.0;
-    let currentSample = 1;
-    const lastSample = kSplineTableSize - 1;
-
-    for (; currentSample !== lastSample && sampleValues[currentSample] <= aX; ++currentSample) {
-      intervalStart += kSampleStepSize;
-    }
-    --currentSample;
-
-    // Interpolate to provide an initial guess for t
-    const dist = (aX - sampleValues[currentSample]) / (sampleValues[currentSample + 1] - sampleValues[currentSample]);
-    const guessForT = intervalStart + dist * kSampleStepSize;
-    const initialSlope = getSlope(guessForT, x1, x2);
-
-    if (initialSlope >= NEWTON_MIN_SLOPE) {
-      return newtonRaphsonIterate(aX, guessForT, x1, x2);
-    }
-
-    if (initialSlope === 0.0) {
-      return guessForT;
-    }
-
-    return binarySubdivide(aX, intervalStart, intervalStart + kSampleStepSize, x1, x2);
-  }
-
-  /**
-   * 贝塞尔曲线方程
-   * @param x {number} 0~1
-   */
-  return function easingFunc(x: number) {
-    // Because JavaScript number are imprecise, we should guarantee the extremes are right.
-    if (x === 0 || x === 1) {
-      return x;
-    }
-
-    return calcBezier(getTForX(x), y1, y2);
-  };
-}
-
-export const easingEase = createEasingFn(0.25, 0.1, 0.25, 1);
-export const easingLinear = createEasingFn(0, 0, 1, 1);
-export const easingSnap = createEasingFn(0, 1, 0.5, 1);
-export const easingIn = createEasingFn(0.42, 0, 1, 1);
-export const easingOut = createEasingFn(0, 0, 0.58, 1);
-export const easingInOut = createEasingFn(0.42, 0, 0.58, 1);
-export const easingInQuad = createEasingFn(0.55, 0.085, 0.68, 0.53);
-export const easingInCubic = createEasingFn(0.55, 0.055, 0.675, 0.19);
-export const easingInQuart = createEasingFn(0.895, 0.03, 0.685, 0.22);
-export const easingInQuint = createEasingFn(0.755, 0.05, 0.855, 0.06);
-export const easingInSine = createEasingFn(0.47, 0, 0.745, 0.715);
-export const easingInExpo = createEasingFn(0.95, 0.05, 0.795, 0.035);
-export const easingInCirc = createEasingFn(0.6, 0.04, 0.98, 0.335);
-export const easingInBack = createEasingFn(0.6, -0.28, 0.735, 0.045);
-export const easingOutQuad = createEasingFn(0.25, 0.46, 0.45, 0.94);
-export const easingOutCubic = createEasingFn(0.215, 0.61, 0.355, 1);
-export const easingOutQuart = createEasingFn(0.165, 0.84, 0.44, 1);
-export const easingOutQuint = createEasingFn(0.23, 1, 0.32, 1);
-export const easingOutSine = createEasingFn(0.39, 0.575, 0.565, 1);
-export const easingOutExpo = createEasingFn(0.19, 1, 0.22, 1);
-export const easingOutCirc = createEasingFn(0.075, 0.82, 0.165, 1);
-export const easingOutBack = createEasingFn(0.175, 0.885, 0.32, 1.275);
-export const easingInOutQuart = createEasingFn(0.77, 0, 0.175, 1);
-export const easingInOutQuint = createEasingFn(0.86, 0, 0.07, 1);
-export const easingInOutSine = createEasingFn(0.445, 0.05, 0.55, 0.95);
-export const easingInOutExpo = createEasingFn(1, 0, 0, 1);
-export const easingInOutCirc = createEasingFn(0.785, 0.135, 0.15, 0.86);
-export const easingInOutBack = createEasingFn(0.68, -0.55, 0.265, 1.55);

package/src/emitter.ts

@@ -1,117 +0,0 @@
-import type { AnyFunction, AnyObject } from './types';
-
-/**
- * 事件类型映射，key 为事件名称，value 为事件参数类型数组
- */
-export type EmitterMap = Record<string, unknown[]>;
-
-/**
- * 事件监听器函数类型
- * @template E - EmitterMap 类型
- * @template K - 事件名称类型
- */
-export type EmitterListener<E extends EmitterMap, K extends keyof E> = (...payloads: E[K]) => false | unknown;
-
-/**
- * 事件发射器类，用于管理事件监听和触发
- * @template E - 事件类型映射
- *
- * @example
- * type MyEvents = {
- *   'click': [x: number, y: number];
- *   'change': [value: string];
- * };
- *
- * const emitter = new Emitter<MyEvents>();
- * emitter.on('click', (x, y) => {
- *   console.log(`Clicked at (${x}, ${y})`);
- * });
- * emitter.emit('click', 10, 20);
- */
-export class Emitter<E extends EmitterMap> {
-  #events: Map<keyof E, Set<AnyFunction>> = new Map();
-
-  /**
-   * 注册事件监听器
-   * @param event - 要监听的事件名称
-   * @param listener - 事件监听器函数
-   * @example
-   * emitter.on('click', (x, y) => {
-   *   console.log(`Clicked at (${x}, ${y})`);
-   * });
-   */
-  on<K extends keyof E>(event: K, listener: EmitterListener<E, K>) {
-    const listeners = this.#events.get(event);
-    if (listeners) {
-      listeners.add(listener);
-    } else {
-      this.#events.set(event, new Set([listener]));
-    }
-  }
-
-  /**
-   * 移除事件监听器，有三种使用方式：
-   * 1. 移除特定事件的特定监听器
-   * 2. 移除特定事件的所有监听器
-   * 3. 移除所有事件的所有监听器
-   * @param event - 要移除的事件名称（可选）
-   * @param listener - 要移除的监听器函数（可选）
-   * @example
-   * // 移除特定事件的特定监听器
-   * emitter.off('click', clickHandler);
-   *
-   * // 移除特定事件的所有监听器
-   * emitter.off('click');
-   *
-   * // 移除所有事件的所有监听器
-   * emitter.off();
-   */
-  off<K extends keyof E>(event?: K, listener?: EmitterListener<E, K>) {
-    if (event && listener) {
-      this.#offListener(event, listener);
-    } else if (event) {
-      this.#offEvent(event);
-    } else {
-      this.#offAll();
-    }
-  }
-
-  #offAll() {
-    this.#events.clear();
-  }
-
-  #offEvent<K extends keyof E>(event: K) {
-    this.#events.delete(event);
-  }
-
-  #offListener<K extends keyof E>(event: K, listener: EmitterListener<E, K>) {
-    const listeners = this.#events.get(event);
-
-    if (listeners) {
-      listeners.delete(listener);
-    }
-  }
-
-  /**
-   * 触发指定事件，调用所有注册的监听器
-   * @param event - 要触发的事件名称
-   * @param payloads - 传递给监听器的参数
-   * @remarks
-   * 监听器会按照注册的顺序依次执行，如果某个监听器返回 false，
-   * 则后续监听器将不会被执行
-   * @example
-   * emitter.emit('click', 10, 20);
-   */
-  emit<K extends keyof E>(event: K, ...payloads: Parameters<EmitterListener<E, K>>) {
-    const listeners = this.#events.get(event) as Set<EmitterListener<E, K>> | undefined;
-
-    if (!listeners) return;
-
-    // 避免在 emit、on 的过程中改变 listeners 从而影响本次 emit
-    for (const listener of [...listeners]) {
-      if (listener(...payloads) === false) {
-        break;
-      }
-    }
-  }
-}

package/src/enum.ts

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

@@ -1,68 +0,0 @@
-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');