donar 0.0.1

package/src/utils/event-emitter/helpers.ts

@@ -0,0 +1,80 @@
+import type { RecordTypedMap } from '../record-typed-map';
+
+/**
+ * @author sonion
+ * @description 判断对象自身是否有指定属性
+ * @param obj 要判断的对象
+ * @param property 属性名
+ * @returns {boolean} - 是否有指定属性
+ */
+export const hasOwnProperty = <T extends Partial<Record<keyof T, unknown>>>(
+  obj: T,
+  property: string
+) => Object.prototype.hasOwnProperty.call(obj, property);
+
+/** 事件处理函数类型 */
+export type EventHandler<P> = undefined extends P
+  ? (payload?: P) => void
+  : (payload: P) => void;
+
+/** 事件处理函数配置类型 */
+export type EventHandlerOptions = {
+  /** 是否仅触发一次 */
+  once?: boolean;
+  /** 取消信号 */
+  signal?: AbortSignal;
+};
+
+/** 事件处理函数集合 */
+export type EventCollection<P> = Map<
+  EventHandler<P>,
+  EventHandlerOptions | undefined
+>;
+
+/**
+ * @author sonion
+ * @description 创建事件处理集合，同名事件的集合
+ * 泛型 A，事件处理韩式参数类型
+ * @returns 事件处理函数集合
+ */
+export const createEventCollection = <
+  K extends keyof T,
+  T extends Record<string, unknown>,
+>(): EventCollection<T[K]> => new Map() satisfies EventCollection<T[K]>;
+
+/** 事件中心数据类型 `Map<事件名, Map<事件处理函数, 配置参数>>` */
+export type EventCenter<T extends Record<string, unknown>> = RecordTypedMap<{
+  [K in keyof T]: EventCollection<T[K]>;
+}>;
+
+export type EventOptionExecutor<T extends Record<string, unknown>> = Record<
+  keyof EventHandlerOptions,
+  <K extends keyof T>(
+    events: EventCenter<T>,
+    eventName: K,
+    // 在emit工程中传入，因为是引用类型，可用于控制执行过程。如signal信号终止不再运行，就删除处理函数
+    eventExecutorParams: [EventHandler<T[K]>, EventHandlerOptions | undefined]
+  ) => void
+>;
+
+export const createEventOptionExecutor = <
+  T extends Record<string, unknown>,
+>() =>
+  ({
+    // 删除事件中心的任务，但当次还要运行
+    once: (events, eventName, eventExecutorParams) => {
+      events.get(eventName)?.delete(eventExecutorParams[0]);
+      events.get(eventName)?.size || events.delete(eventName); // 如果没有任务了，就删除该事件集合
+    },
+    signal: (events, eventName, eventExecutorParams) => {
+      if (!(eventExecutorParams[1]?.signal instanceof AbortSignal))
+        throw new TypeError(
+          '参数 signal 类型错误。必须是一个 AbortSignal 对象'
+        );
+      if (eventExecutorParams[1].signal.aborted) {
+        events.get(eventName)?.delete(eventExecutorParams[0]); // 删除事件中心的任务，且不再执行当次任务
+        events.get(eventName)?.size || events.delete(eventName); // 如果没有任务了，就删除该事件集合
+        Reflect.deleteProperty(eventExecutorParams, 0); // 索引不变
+      }
+    },
+  }) satisfies EventOptionExecutor<T>;

package/src/utils/event-emitter/index.ts

@@ -0,0 +1,171 @@
+import {
+  type EventHandler,
+  type EventHandlerOptions,
+  type EventOptionExecutor,
+  type EventCenter,
+  createEventCollection,
+  createEventOptionExecutor,
+  hasOwnProperty,
+} from './helpers';
+import { createMicroQueueScheduler } from '../micro-queue-scheduler';
+import { RecordTypedMap } from '../record-typed-map';
+
+// 定义一个排除函数的类型
+type NonFunction =
+  | null
+  | undefined
+  | number
+  | string
+  | boolean
+  | symbol
+  | bigint
+  | { [key: string]: unknown };
+
+/** 返回包含 undefined 类型的键 */
+type KeysWithUndefined<T> = {
+  // 遍历 T 的所有键 K，如可选会是和 undefined 的联合类型
+  // 所以用 undefined extends T[K] 来判断是否包含 undefined
+  [K in keyof T]: undefined extends T[K] ? K : never;
+}[keyof T];
+
+/** 返回不包含 undefined 类型的键 */
+type KeysWithoutUndefined<T> = {
+  [K in keyof T]: undefined extends T[K] ? never : K;
+}[keyof T];
+
+/**
+ * @author sonion
+ * @description 自定义事件中心。
+ * @example
+ * const eventCenter = new EventEmitter();
+ * eventCenter.on('onChange', data=>console.log('没有配置的事件。参数：', data));
+ * eventCenter.on('onTest', data=>console.log('once 配置为 true 的事件。参数：', data), {once: true});
+ * const controller = new AbortController(); // 创建取消信号
+ * eventCenter.on('tap', data=>console.log('配置了 signal 的事件。参数：', data), {signal: controller.signal})
+ * controller.abort() // 取消
+ * eventCenter.emit('onChange', {happy: true});
+ */
+export class EventEmitter<T extends Record<string, NonFunction>> {
+  /** Map<事件名, Map<事件处理函数, 配置参数>> */
+  private events: EventCenter<T> = new RecordTypedMap();
+
+  /** 配置对象执行器，不同配置参数的不同处理。在emit中执行 */
+  private eventOptionExecutor: EventOptionExecutor<T>;
+
+  /** 自定义调度器，怎么执行事件处理函数 */
+  private scheduler: (eventHandel: () => void) => void;
+
+  constructor(scheduler?: (eventHandel: () => void) => void) {
+    this.scheduler = scheduler ?? createMicroQueueScheduler();
+    // 事件处理 options 执行器。如需添加处理参数，直接扩展 createEventOptionExecutor 返回对象属性
+    this.eventOptionExecutor = createEventOptionExecutor<T>();
+  }
+
+  /**
+   * @author sonion
+   * @description 注册事件
+   * @param eventName 事件名
+   * @param callback 事件处理函数
+   * @param options 配置对象。once：是否只运行一次, signal取消信号
+   */
+  addEventListener<K extends keyof T>(
+    eventName: K,
+    callback: EventHandler<T[K]>,
+    options?: EventHandlerOptions
+  ): void {
+    if (options) {
+      const keys = Object.keys(this.eventOptionExecutor);
+      if (typeof options !== 'object' || Array.isArray(options)) {
+        throw new TypeError(
+          '参数 options 类型错误。options 应该为一个配置对象。'
+        );
+      } else if (!keys.some((key) => hasOwnProperty(options, key))) {
+        throw new TypeError(`options 仅支持 ${keys.join('、')} 参数`);
+      }
+    }
+    // events 为用class 包装的 Map 类型更友好
+    this.events.has(eventName) ||
+      this.events.set(eventName, createEventCollection<K, T>());
+    const collection = this.events.get(eventName);
+    collection?.set(callback, options);
+  }
+
+  /**
+   * @author sonion
+   * @description 移除事件
+   * @param eventName 事件名
+   * @param callback 事件处理函数
+   */
+  removeEventListener<K extends keyof T>(
+    eventName: K,
+    callback: EventHandler<T[K]>
+  ) {
+    if (!this.events.has(eventName)) return;
+    this.events.get(eventName)?.delete(callback);
+  }
+
+  // 添加事件 别名
+  on<K extends keyof T>(
+    eventName: K,
+    callback: EventHandler<T[K]>,
+    options?: EventHandlerOptions
+  ) {
+    this.addEventListener(eventName, callback, options);
+  }
+
+  // 移除事件 别名
+  off<K extends keyof T>(eventName: K, callback: EventHandler<T[K]>) {
+    this.removeEventListener(eventName, callback);
+  }
+
+  /**
+   * @author sonion
+   * @description 清空事件列表
+   * @param {string | void} [eventName] - 要清除的事件名。不传就清空所有事件列表
+   */
+  clear(eventName?: keyof T) {
+    if (eventName) {
+      return this.events.delete(eventName);
+    }
+    return this.events.clear() ?? true;
+  }
+
+  /**
+   * @author sonion
+   * @description 发布事件
+   * @param eventName 事件名
+   * @param data 事件参数
+   */
+  emit<K extends KeysWithoutUndefined<T>>(eventName: K, data: T[K]): void;
+  emit<K extends KeysWithUndefined<T>>(eventName: K, data?: T[K]): void;
+  emit<K extends keyof T>(eventName: K, data?: T[K]) {
+    if (!this.events.has(eventName)) return;
+    // 遍历订阅对象，执行handler
+    this.scheduler(() => {
+      this.events.get(eventName)?.forEach((options, callback) => {
+        const eventExecutorParams: [
+          EventHandler<T[K]>,
+          EventHandlerOptions | undefined,
+        ] = [callback, options];
+
+        if (options) {
+          const optionKeys = Object.keys(
+            options
+          ) as (keyof EventHandlerOptions)[];
+          optionKeys.forEach((key) => {
+            hasOwnProperty(this.eventOptionExecutor, key) &&
+              this.eventOptionExecutor[key](
+                this.events,
+                eventName,
+                eventExecutorParams
+              );
+          });
+        }
+        // 可能执行时事件可能已经被移除
+        // 利用 eventExecutorParams 是数组的引用类型特征
+        // eventOptionExecutor 处理后 eventHandler 内还存在才运行
+        eventExecutorParams[0] && callback(data as T[K]); // 必须在最后
+      });
+    });
+  }
+}

package/src/utils/fetch-xhr/helpers.ts

@@ -0,0 +1,85 @@
+/**
+ * @author sonion
+ * @description
+ * @param xhr - XMLHttpRequest 实例对象
+ * @param headers 请求头参数
+ */
+export const setRequestHeaders = (
+  xhr: XMLHttpRequest,
+  headers: RequestInit['headers']
+) => {
+  if (headers) {
+    if (headers instanceof Headers) {
+      headers.forEach((value, key) => {
+        xhr.setRequestHeader(key, value);
+      });
+    } else if (Array.isArray(headers)) {
+      headers.forEach((header) => {
+        xhr.setRequestHeader(header[0], header[1]);
+      });
+    } else {
+      Object.keys(headers).forEach((key) => {
+        xhr.setRequestHeader(key, headers[key]);
+      });
+    }
+  }
+};
+
+/**
+ * @author sonion
+ * @description 处理请求体，将 ReadableStream 类型转换为 Blob 类型
+ * @param body - 请求体
+ * @param signal - 信号量
+ */
+export const handleRequestBody = async (
+  body: RequestInit['body'],
+  signal?: AbortSignal | null
+) => {
+  if (!(body instanceof ReadableStream)) {
+    return body;
+  }
+  const chunks: Uint8Array[] = [];
+  const reader = body.getReader();
+  while (true) {
+    signal?.throwIfAborted(); // 信号被终止，就抛出错误
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+  return new Blob(chunks as BlobPart[]);
+};
+
+/** 响应头分隔符 正则 */
+const RegExpForSplitHeaders = /[\r\n]+/;
+
+/**
+ * @author sonion
+ * @description 获取响应头
+ * @param {XMLHttpRequest} xhr XMLHttpRequest对象
+ */
+export const getResponseHeaders = function (xhr: XMLHttpRequest) {
+  const headerStr = xhr.getAllResponseHeaders();
+  const arr = headerStr.trim().split(RegExpForSplitHeaders);
+  const headerLines = arr.map((line) => {
+    const index = line.indexOf(':');
+    if (index <= -1) {
+      return [] as unknown as [string, string];
+    }
+    return [line.slice(0, index), line.slice(index + 1).trim()] satisfies [
+      string,
+      string,
+    ];
+  });
+  return new Headers(headerLines);
+};
+
+/**
+ * @author sonion
+ * @description 自定义超时错误类
+ */
+export class CustomTimeoutError extends DOMException {
+  readonly isTimeout = true;
+  constructor(msg?: string) {
+    super(msg ?? 'signal is aborted without reason', 'AbortError');
+  }
+}

package/src/utils/fetch-xhr/index.ts

@@ -0,0 +1,103 @@
+import {
+  setRequestHeaders,
+  handleRequestBody,
+  getResponseHeaders,
+  CustomTimeoutError,
+} from './helpers';
+
+export { CustomTimeoutError };
+
+// fetch 请求参数中 xhr 支持的参数
+type RequestInitFields =
+  | 'body'
+  | 'method'
+  | 'headers'
+  | 'credentials'
+  | 'signal';
+
+export interface FetchXHRInit extends Pick<RequestInit, RequestInitFields> {
+  /**
+   * @description 超时时间，单位毫秒
+   */
+  timeout?: number;
+  /**
+   * @description 上传进度回调
+   */
+  onUploadProgress?: (loaded: number, total: number, e: ProgressEvent) => void;
+  /**
+   * @description 下载进度回调
+   */
+  onDownloadProgress?: (
+    loaded: number,
+    total: number,
+    e: ProgressEvent
+  ) => void;
+}
+
+/**
+ * @author sonion
+ * @description 基于 XMLHttpRequest 实现的 fetch 函数。
+ * 除增加 timeout、onUploadProgress、onDownloadProgress 外，其他与 fetch 一致。
+ * @param url 请求地址
+ * @param init 请求配置。
+ */
+export const fetchXHR = async (url: string, init?: FetchXHRInit) => {
+  return new Promise<Response>((resolve, reject) => {
+    const {
+      body,
+      method = 'GET',
+      headers,
+      credentials,
+      signal,
+      timeout,
+      onUploadProgress,
+      onDownloadProgress,
+    } = init || {};
+    const xhr = new XMLHttpRequest();
+    const normalizedMethod = method.toUpperCase();
+    xhr.open(normalizedMethod, url, true); // 必须在设置请求头之前
+    // 设置请求头
+    setRequestHeaders(xhr, headers);
+    credentials === 'include' && (xhr.withCredentials = true); // cookie跨域是否携带
+    xhr.responseType = 'blob'; // 固定 blob，传给Response处理
+    typeof timeout === 'number' &&
+      !Number.isNaN(timeout) &&
+      (xhr.timeout = timeout); // 设置超时时间
+
+    onUploadProgress &&
+      (xhr.upload.onprogress = (e) => onUploadProgress(e.loaded, e.total, e));
+
+    onDownloadProgress &&
+      (xhr.onprogress = (e) => onDownloadProgress(e.loaded, e.total, e));
+
+    if (signal) {
+      const handleAbort = () => xhr.abort();
+      signal.addEventListener('abort', handleAbort, { once: true });
+      xhr.onloadend = () => signal?.removeEventListener('abort', handleAbort);
+    }
+
+    xhr.onabort = () =>
+      reject(
+        new DOMException('signal is aborted without reason', 'AbortError')
+      );
+
+    // 兼容 fetch 的超时写法。继承 DOMException name 也是 AbortError。扩展 isTimeout 标识是否超时。
+    xhr.ontimeout = () => reject(new CustomTimeoutError('请求超时'));
+
+    xhr.onerror = () => reject(new TypeError('网络错误'));
+
+    // 200系、400系、500系状态码都认为是成功
+    xhr.onload = () =>
+      resolve(
+        new Response(xhr.response, {
+          status: xhr.status,
+          statusText: xhr.statusText,
+          headers: getResponseHeaders(xhr),
+        })
+      );
+
+    handleRequestBody(body, signal).then((res) =>
+      xhr.send(['GET', 'HEAD'].includes(normalizedMethod) ? null : res)
+    ); // 处理请求体,在发送
+  });
+};

package/src/utils/hash.ts

@@ -0,0 +1,25 @@
+export type SupportedHashType = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+/**
+ * @author sonion
+ * @description 字符串转哈希
+ * @param {string} message - 要转换的字符串
+ * @param {SupportedHashType} algorithm - 哈希算法，默认SHA-1
+ */
+export async function stringToHash(
+  message: string,
+  algorithm: SupportedHashType = 'SHA-1'
+): Promise<string> {
+  try {
+    if (!message) {
+      throw new Error('message is empty');
+    }
+    const encoder = new TextEncoder();
+    const data = encoder.encode(message);
+    const hashBuffer = await window.crypto.subtle.digest(algorithm, data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+  } catch (err) {
+    throw err instanceof Error ? err : new Error('string to hash failed');
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,18 @@
+export * from './thenable';
+export * from './concurrency';
+export * from './debounce';
+export * from './hash';
+export * from './download';
+export * from './deep-copy';
+export * from './raf-interval';
+
+export * from './json-convert';
+export * from './fetch-xhr';
+export * from './class-singleton';
+export * from './event-emitter';
+export * from './micro-queue-scheduler';
+export * from './record-typed-map';
+export * from './retry-async';
+export * from './is-deep-plain-equal';
+
+import './dev';

package/src/utils/is-deep-plain-equal.ts

@@ -0,0 +1,45 @@
+/**
+ * @author sonion
+ * @param value 要判断的值
+ * @description 是否为null或undefined
+ */
+export const isNil = (value: unknown): value is null | undefined =>
+  value === null || value === undefined;
+
+/**
+ * @author sonion
+ * @description 深度比较两个未知类型的值是否相等。支持 Plain Object。
+ * 不支持比较函数、Symbol、Date、RegExp等。
+ * @param a 要比较的第一个值
+ * @param b 要比较的第二个值
+ * @returns 如果两个值相等则返回 true，否则返回 false
+ */
+export const isDeepPlainEqual = (a: unknown, b: unknown): boolean => {
+  if (isNil(a) || isNil(b)) return Object.is(a, b);
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0, length = a.length; i < length; i++) {
+      // 可能有顺序不一致问题
+      if (!isDeepPlainEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  // 不支持比较函数、Symbol、Date、RegExp等
+  if (typeof a === 'object' && typeof b === 'object') {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const key of aKeys) {
+      if (!Object.hasOwnProperty.call(b, key)) return false; // 解决无属性和有属性但值为 undefined 的情况
+      if (
+        !isDeepPlainEqual(a[key as keyof typeof a], b[key as keyof typeof b])
+      ) {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+};