@cloudcome/utils-core 1.1.0 → 1.1.1

package/src/date/timezone.ts

@@ -0,0 +1,220 @@
+import { isNumber } from '../type';
+import { dateFormat } from './core';
+
+export type TTzDateOptions = {
+  /**
+   * 时间戳
+   * @default Date.now()
+   */
+  timestamp?: number;
+
+  /**
+   * 日期值
+   */
+  value?: readonly [
+    year?: number,
+    month?: number,
+    day?: number,
+    hours?: number,
+    minutes?: number,
+    seconds?: number,
+    milliseconds?: number,
+  ];
+
+  /**
+   * 时区偏移量，单位为分钟，默认为当前时区
+   */
+  offset?: number;
+};
+
+const TZ_OFFSET_MS = 60 * 1000;
+
+export class TzDate {
+  #timestamp: number;
+  #targetDate: Date;
+  #utcDate: Date;
+
+  #localTZOffset = TzDate.getOffset();
+  #localTzOffsetMS = this.#localTZOffset * TZ_OFFSET_MS;
+
+  #targetTzOffset = 0;
+  #targetTzOffsetMS = 0;
+
+  #options: TTzDateOptions;
+
+  constructor(options?: TTzDateOptions | TzDate) {
+    this.#options = (options instanceof TzDate ? options.#options : options) || {};
+    const { offset, timestamp, value } = this.#options;
+    this.#targetTzOffset = isNumber(offset) ? offset : this.#localTZOffset;
+    this.#targetTzOffsetMS = this.#targetTzOffset * TZ_OFFSET_MS;
+
+    if (Array.isArray(value) && value.length > 0) {
+      const [fullYear, month, day, hours, minutes, seconds, milliseconds] = value;
+      const timestamp = Date.UTC(
+        fullYear ?? 0,
+        month ?? 0,
+        day ?? 1,
+        hours ?? 0,
+        minutes ?? 0,
+        seconds ?? 0,
+        milliseconds ?? 0,
+      );
+
+      this.#timestamp = timestamp + this.#targetTzOffsetMS;
+    } else {
+      this.#timestamp = timestamp || Date.now();
+    }
+
+    this.#targetDate = new Date(this.#timestamp + this.#localTzOffsetMS - this.#targetTzOffsetMS);
+    this.#utcDate = new Date(this.#timestamp + this.#localTzOffsetMS);
+  }
+
+  #updateTimestamp() {
+    this.#timestamp = this.#targetDate.getTime() + this.#targetTzOffsetMS - this.#localTzOffsetMS;
+    this.#utcDate = new Date(this.#timestamp + this.#localTzOffsetMS);
+  }
+
+  getTimezoneOffset() {
+    return this.#targetTzOffset;
+  }
+
+  getTimezoneOrder() {
+    return TzDate.getOrder(this.#targetTzOffset);
+  }
+
+  getFullYear() {
+    return this.#targetDate.getFullYear();
+  }
+
+  getMonth() {
+    return this.#targetDate.getMonth();
+  }
+
+  getDate() {
+    return this.#targetDate.getDate();
+  }
+
+  getHours() {
+    return this.#targetDate.getHours();
+  }
+
+  getMinutes() {
+    return this.#targetDate.getMinutes();
+  }
+
+  getSeconds() {
+    return this.#targetDate.getSeconds();
+  }
+
+  getMilliseconds() {
+    return this.#targetDate.getMilliseconds();
+  }
+
+  setFullYear(year: number, month?: number, date?: number) {
+    this.#targetDate.setFullYear(year);
+    this.#updateTimestamp();
+
+    if (isNumber(month)) this.setMonth(month);
+    if (isNumber(date)) this.setDate(date);
+
+    return this.getTime();
+  }
+
+  setMonth(month: number, date?: number) {
+    this.#targetDate.setMonth(month);
+    this.#updateTimestamp();
+
+    if (isNumber(date)) this.setDate(date);
+
+    return this.getTime();
+  }
+
+  setDate(date: number) {
+    this.#targetDate.setDate(date);
+    this.#updateTimestamp();
+
+    return this.getTime();
+  }
+
+  setHours(hours: number, minutes?: number, seconds?: number, milliseconds?: number) {
+    this.#targetDate.setHours(hours);
+    this.#updateTimestamp();
+
+    if (isNumber(minutes)) this.setMinutes(minutes);
+    if (isNumber(seconds)) this.setSeconds(seconds);
+    if (isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+
+    return this.getTime();
+  }
+
+  setMinutes(minutes: number, seconds?: number, milliseconds?: number) {
+    this.#targetDate.setMinutes(minutes);
+    this.#updateTimestamp();
+
+    if (isNumber(seconds)) this.setSeconds(seconds);
+    if (isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+
+    return this.getTime();
+  }
+
+  setSeconds(seconds: number, milliseconds?: number) {
+    this.#targetDate.setSeconds(seconds);
+    this.#updateTimestamp();
+
+    if (isNumber(milliseconds)) this.setMilliseconds(milliseconds);
+
+    return this.getTime();
+  }
+
+  setMilliseconds(milliseconds: number) {
+    this.#targetDate.setMilliseconds(milliseconds);
+    this.#updateTimestamp();
+
+    return this.getTime();
+  }
+
+  getTime() {
+    return this.#timestamp;
+  }
+
+  getDay() {
+    return this.#targetDate.getDay();
+  }
+
+  toISOString() {
+    return dateFormat(this.#utcDate, 'YYYY-MM-DDTHH:mm:ss.SSSZ');
+  }
+
+  /**
+   * 创建一个 TzDate 对象
+   * @param td - 需要转换的日期对象
+   * @param offset - 目标时区分钟偏移量，默认为当前时区
+   * @returns 返回一个 TzDate 对象
+   * @example
+   * ```js
+   * const tzDate = TzDate.from(new TzDate());
+   * ```
+   */
+  static from(td: TzDate, offset = TzDate.getOffset()) {
+    return new TzDate({
+      offset: offset,
+      timestamp: td.getTime(),
+    });
+  }
+
+  /**
+   * 获取时区序号
+   * @param offset - 默认使用当前时区分钟偏移量
+   */
+  static getOrder(offset = TzDate.getOffset()) {
+    return offset / -60;
+  }
+
+  /**
+   * 获取时区分钟偏移量
+   * @param gmtOrder - 默认使用当前时区序号
+   */
+  static getOffset(gmtOrder?: number) {
+    return isNumber(gmtOrder) ? gmtOrder * -60 : new Date().getTimezoneOffset();
+  }
+}

package/src/date/weeks.ts

@@ -0,0 +1,100 @@
+import { DATE_DAY_MS } from './const';
+import { type TDateValue, dateParse } from './core';
+
+export enum EWeekStart {
+  /**
+   * 周日作为一周的起始日
+   */
+  sunday = 0,
+  /**
+   * 周一作为一周的起始日
+   */
+  monday = 1,
+  /**
+   * 周二作为一周的起始日
+   */
+  tuesday = 2,
+  /**
+   * 周三作为一周的起始日
+   */
+  wednesday = 3,
+  /**
+   * 周四作为一周的起始日
+   */
+  thursday = 4,
+  /**
+   * 周五作为一周的起始日
+   */
+  friday = 5,
+  /**
+   * 周六作为一周的起始日
+   */
+  saturday = 6,
+  // /**
+  //  * 1号所在的周为第一周
+  //  */
+  // firstDate = 7,
+  // /**
+  //  * 完整7天表示第一周
+  //  */
+  // firstFullWeek = 8,
+}
+
+/**
+ * 计算指定日期所在年份或月份的周数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param type - 计算范围，'Y' 表示年份，'M' 表示月份
+ * @param weekStart - 一周的起始日，默认为 0（周日）
+ * @returns 返回指定日期所在年份或月份的周数
+ * @example
+ * ```typescript
+ * const date = new Date(2023, 0, 1); // 2023-01-01
+ * _dateWeeks(date, 'Y'); // 1 (计算年份的周数)
+ * _dateWeeks(date, 'M'); // 1 (计算月份的周数)
+ * _dateWeeks(date, 'Y', 1); // 1 (周一作为一周的起始日，计算年份的周数)
+ * ```
+ */
+export function _dateWeeks(dateValue: TDateValue, type: 'Y' | 'M', weekStart: EWeekStart = 0) {
+  const date = dateParse(dateValue);
+
+  const year = date.getFullYear();
+  const month = date.getMonth();
+
+  const firstDate = type === 'Y' ? new Date(year, 0, 1) : new Date(year, month, 1);
+  const firstWeek = firstDate.getDay();
+  const days = Math.ceil((date.getTime() - firstDate.getTime()) / DATE_DAY_MS);
+
+  return Math.ceil((firstWeek + days - weekStart) / 7);
+}
+
+/**
+ * 计算指定日期所在年份的周数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param weekStart - 一周的起始日，默认为 0（周日）
+ * @returns 返回指定日期所在年份的周数
+ * @example
+ * ```typescript
+ * const date = new Date(2023, 0, 1); // 2023-01-01
+ * weeksOfYear(date); // 1
+ * weeksOfYear(date, 1); // 1 (周一作为一周的起始日)
+ * ```
+ */
+export function weeksOfYear(dateValue: TDateValue, weekStart: EWeekStart = 0) {
+  return _dateWeeks(dateValue, 'Y', weekStart);
+}
+
+/**
+ * 计算指定日期所在月份的周数
+ * @param dateValue - 可以是数值、字符串或 Date 对象
+ * @param weekStart - 一周的起始日，默认为 0（周日）
+ * @returns 返回指定日期所在月份的周数
+ * @example
+ * ```typescript
+ * const date = new Date(2023, 0, 1); // 2023-01-01
+ * weeksOfMonth(date); // 1
+ * weeksOfMonth(date, 1); // 1 (周一作为一周的起始日)
+ * ```
+ */
+export function weeksOfMonth(dateValue: TDateValue, weekStart: EWeekStart = 0) {
+  return _dateWeeks(dateValue, 'M', weekStart);
+}

package/src/dts/global.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file global.d.ts
+ */
+
+/**
+ * package.json name
+ */
+declare const PKG_NAME: string;
+
+/**
+ * package.json version
+ */
+declare const PKG_VERSION: string;
+
+/**
+ * package.json description
+ */
+declare const PKG_DESCRIPTION: string;
+
+declare const IS_TEST: string;
+
+interface TEST_MOCK {
+  IS_BROWSER: boolean;
+  IS_NODE: boolean;
+}
+
+declare const TEST_MOCK: TEST_MOCK;

package/src/easing.ts

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

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