@whitesev/utils 2.11.11 → 2.11.12

package/src/Utils.ts

@@ -102,19 +102,25 @@ class Utils {
   }
   /**
    * ajax劫持库，支持xhr和fetch劫持。
-   * + 来源：https://bbs.tampermonkey.net.cn/thread-3284-1-1.html
-   * + 作者：cxxjackie
-   * + 版本：1.4.8
-   * + 旧版本：1.2.4
-   * + 文档：https://scriptcat.org/zh-CN/script-show-page/637/
-   * @param useOldVersion 是否使用旧版本，默认false
+   * + 来源: https://bbs.tampermonkey.net.cn/thread-3284-1-1.html
+   * + 作者: cxxjackie
+   * + 实现方式: Proxy
+   * + 版本: `1.4.8`
+   * + 文档: https://scriptcat.org/zh-CN/script-show-page/637/
    */
-  ajaxHooker = (useOldVersion: boolean = false): UtilsAjaxHookResult => {
-    if (useOldVersion) {
-      return AjaxHooker1_2_4();
-    } else {
-      return ajaxHooker();
-    }
+  ajaxHooker = (): UtilsAjaxHookResult => {
+    return ajaxHooker();
+  };
+  /**
+   * ajax劫持库，支持xhr和fetch劫持。
+   * + 来源: https://bbs.tampermonkey.net.cn/thread-3284-1-1.html
+   * + 作者: cxxjackie
+   * + 实现方式: Object.defineProperty
+   * + 版本: `1.2.4`
+   * + 文档: https://scriptcat.org/zh-CN/script-show-page/637/
+   */
+  oldAjaxHooker = (): UtilsAjaxHookResult => {
+    return AjaxHooker1_2_4();
   };
   /**
    * 根据坐标点击canvas元素的内部位置
@@ -2207,26 +2213,14 @@ class Utils {
        */
       config?: MutationObserverInit;
       /**
-       * 是否主动触发一次
+       * （可选）是否主动触发一次
        */
       immediate?: boolean;
       /**
-       * 触发的回调函数
+       * （可选）是否仅触发一次
+       * @default false
        */
-      callback: MutationCallback;
-    }
-  ): MutationObserver;
-  mutationObserver(
-    target: HTMLElement | Node | NodeList | Document,
-    observer_config: {
-      /**
-       * observer的配置
-       */
-      config?: MutationObserverInit;
-      /**
-       * 是否主动触发一次
-       */
-      immediate?: boolean;
+      once?: boolean;
       /**
        * 触发的回调函数
        */
@@ -2275,6 +2269,7 @@ class Utils {
         characterDataOldValue: void 0 as any as boolean,
       },
       immediate: false,
+      once: false,
     };
     observer_config = that.assign(default_obverser_config, observer_config);
     const windowMutationObserver =
@@ -2282,13 +2277,20 @@ class Utils {
       (this.windowApi.window as any).webkitMutationObserver ||
       (this.windowApi.window as any).MozMutationObserver;
     // 观察者对象
+    const handler = (mutations: MutationRecord[], observer: MutationObserver) => {
+      if (observer_config.once) {
+        // 仅触发一次
+        observer.disconnect();
+      }
+      if (typeof observer_config.callback === "function") {
+        observer_config.callback(mutations, observer);
+      }
+    };
     const mutationObserver = new windowMutationObserver(function (
       mutations: MutationRecord[],
       observer: MutationObserver
     ) {
-      if (typeof observer_config.callback === "function") {
-        observer_config.callback(mutations, observer);
-      }
+      handler(mutations, observer);
     });
 
     if (Array.isArray(target) || target instanceof NodeList) {
@@ -2297,7 +2299,7 @@ class Utils {
         mutationObserver.observe(item, observer_config.config);
       });
     } else if (that.isJQuery(target)) {
-      /* 传入的参数是jQuery对象 */
+      // 传入的参数是jQuery对象
       (target as any).each((_: any, item: any) => {
         mutationObserver.observe(item, observer_config.config);
       });
@@ -2305,16 +2307,14 @@ class Utils {
       mutationObserver.observe(target, observer_config.config);
     }
     if (observer_config.immediate) {
-      /* 主动触发一次 */
-      if (typeof observer_config.callback === "function") {
-        observer_config.callback([], mutationObserver);
-      }
+      // 主动触发一次
+      handler([], mutationObserver);
     }
     return mutationObserver;
   }
   /**
    * 使用观察器观察元素出现在视图内，出现的话触发回调
-   * @param target 目标元素
+   * @param $el 目标元素
    * @param callback 触发的回调
    * @param options 观察器配置
    * @example
@@ -2323,36 +2323,54 @@ class Utils {
    * }))
    */
   mutationVisible(
-    target: Element | Element[],
+    $el: Element | Element[],
     callback: (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void,
-    options?: IntersectionObserverInit
+    options?: IntersectionObserverInit & {
+      /** （可选）是否主动触发一次，默认false */
+      immediate?: boolean;
+      /** （可选）是否仅触发一次，默认false */
+      once?: boolean;
+    }
   ) {
     if (typeof IntersectionObserver === "undefined") {
       throw new TypeError("IntersectionObserver is not defined");
     }
-    if (target == null) {
+    if ($el == null) {
       throw new TypeError("mutatuinVisible target is null");
     }
+    options = options || {};
     let defaultOptions: IntersectionObserverInit = {
       root: null,
       rootMargin: "0px 0px 0px 0px",
       threshold: [0.01, 0.99],
     };
-    defaultOptions = this.assign(defaultOptions, options || {});
+    defaultOptions = this.assign(defaultOptions, options);
+    const handler = (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => {
+      if (options.once) {
+        // 仅触发一次
+        observer.disconnect();
+      }
+      if (typeof callback === "function") {
+        callback(entries, observer);
+      }
+    };
     const intersectionObserver = new IntersectionObserver((entries, observer) => {
       if (entries[0].isIntersecting) {
-        if (typeof callback === "function") {
-          callback(entries, observer);
-        }
+        handler(entries, observer);
       }
     }, defaultOptions);
-    if (Array.isArray(target)) {
-      target.forEach((item) => {
-        intersectionObserver.observe(item);
+    if (Array.isArray($el)) {
+      $el.forEach(($elItem) => {
+        intersectionObserver.observe($elItem);
       });
     } else {
-      intersectionObserver.observe(target);
+      intersectionObserver.observe($el);
+    }
+    if (options.immediate) {
+      // 立即触发
+      handler([], intersectionObserver);
     }
+    return intersectionObserver;
   }
   /**
    * 去除全局window下的Utils，返回控制权
@@ -3438,12 +3456,26 @@ class Utils {
   }
   /**
    * 将UrlSearchParams格式的字符串转为对象
+   * @param searhParamsStr 字符串或对象
+   * @example
+   * Utils.searchParamStrToObj("xxx=xx&xx2=xx2")
+   * @example
+   * Utils.searchParamStrToObj(new URLSearchParams({
+   *   test1: 1,
+   *   test2: 2
+   * }))
    */
-  searchParamStrToObj<T>(searhParamsStr?: string | null | undefined): T {
-    if (typeof searhParamsStr !== "string") {
-      return {} as any as T;
-    }
-    return Object.fromEntries(new URLSearchParams(searhParamsStr) as any) as T;
+  searchParamStrToObj<T = any>(searhParamsStr?: string | null | undefined | URLSearchParams): T {
+    const params = {};
+    if (searhParamsStr == null) {
+      return params as T;
+    }
+    const urlSearchParams =
+      searhParamsStr instanceof URLSearchParams ? searhParamsStr : new URLSearchParams(searhParamsStr);
+    urlSearchParams.forEach((value, key) => {
+      Reflect.set(params, key, value);
+    });
+    return params as T;
   }
   /**
    * 提供一个封装了 try-catch 的函数，可以执行传入的函数并捕获其可能抛出的错误，并通过传入的错误处理函数进行处理。

package/src/ajaxHooker/ajaxHooker.js

@@ -132,8 +132,12 @@ export const ajaxHooker = function () {
       );
     }
     waitForRequestKeys() {
+      /**
+       * @type {Set<typeof hookInst>}
+       */
+      const winHookInsts = win.__ajaxHooker.hookInsts;
       if (!this.request.async) {
-        win.__ajaxHooker.hookInsts.forEach(({ hookFns, filters }) => {
+        winHookInsts.forEach(({ hookFns, filters }) => {
           if (this.shouldFilter(filters)) return;
           hookFns.forEach((fn) => {
             if (getType(fn) === "[object Function]")
@@ -147,10 +151,10 @@ export const ajaxHooker = function () {
       }
       const promises = [];
       const ignoreKeys = new Set(["type", "async", "response"]);
-      win.__ajaxHooker.hookInsts.forEach(({ hookFns, filters }) => {
+      winHookInsts.forEach(({ hookFns, filters }) => {
         if (this.shouldFilter(filters)) return;
         promises.push(
-          Promise.all(hookFns.map((fn) => catchError(fn, this.request))).then(
+          Promise.all(hookFns.map((fn,index) => catchError(fn, this.request, index))).then(
             () => {
               const requestKeys = [];
               for (const key in this.request)
@@ -594,10 +598,54 @@ export const ajaxHooker = function () {
       });
     });
   }
+
+  /**
+   * 
+   * @type {import("./../types/ajaxHooker.d.ts").UtilsAjaxHookResult["removeHook"]} 
+   */
+  const removeHook = (fn, onlyRemove = false) => {
+    let flag = false;
+    for (let index = hookInst.hookFns.length-1; index >=0; index--) {
+      const __fn__ = hookInst.hookFns[index];
+      if(fn === __fn__){
+        hookInst.hookFns.splice(index, 1);
+        flag = true;
+        if(onlyRemove){
+          break;
+        }
+      }
+    }
+    return flag;
+  }
+
+  /**
+   * 
+   * @type {import("./../types/ajaxHooker.d.ts").UtilsAjaxHookResult["removeFilter"]} 
+   */
+  const removeFilter = ()=>{
+    if(Array.isArray(hookInst.filters)){
+      hookInst.filters.length = 0;
+    }else{
+      hookInst.filters = [];
+    }
+  }
+
   return {
-    hook: (fn) => hookInst.hookFns.push(fn),
+    hook: (fn) => {
+      hookInst.hookFns.push(fn);
+      return {
+        remove: () => {
+          return removeHook(fn, true);
+        }
+      }
+    },
     filter: (arr) => {
-      if (Array.isArray(arr)) hookInst.filters = arr;
+      if (Array.isArray(arr)) {
+        hookInst.filters = arr;
+      }
+      return {
+        remove: removeFilter
+      }
     },
     protect: () => {
       readonly(win, "XMLHttpRequest", winAh.fakeXHR);
@@ -613,5 +661,7 @@ export const ajaxHooker = function () {
         delete win.__ajaxHooker;
       }
     },
+    removeHook: removeHook,
+    removeFilter: removeFilter
   };
 };

package/src/ajaxHooker/ajaxHooker1.2.4.js

@@ -431,19 +431,63 @@ export const AjaxHooker1_2_4 = function () {
     Object.keys(realXhr).forEach((key) => (fakeXhr[key] = realXhr[key]));
     fakeXhr.prototype = realXhr.prototype;
     win.fetch = fakeFetch;
-    return {
-      hook: (fn) => hookFns.push(fn),
-      filter: (arr) => {
-        filter = Array.isArray(arr) && arr.map(toFilterObj);
-      },
-      protect: () => {
-        readonly(win, "XMLHttpRequest", fakeXhr);
-        readonly(win, "fetch", fakeFetch);
-      },
-      unhook: () => {
-        writable(win, "XMLHttpRequest", realXhr);
-        writable(win, "fetch", realFetch);
-      },
-    };
+
+  /**
+   * 
+   * @type {import("./../types/ajaxHooker.d.ts").UtilsAjaxHookResult["removeHook"]} 
+   */
+    const removeHook = (fn, onlyRemove = false) => {
+    let flag = false;
+    for (let index = hookFns.length-1; index >=0; index--) {
+      const __fn__ = hookFns[index];
+      if(fn === __fn__){
+        hookFns.splice(index, 1);
+        flag = true;
+        if(onlyRemove){
+          break;
+        }
+      }
+    }
+    return flag;
+  }
+
+  /**
+   * 
+   * @type {import("./../types/ajaxHooker.d.ts").UtilsAjaxHookResult["removeFilter"]} 
+   */
+  const removeFilter = ()=>{
+    if(Array.isArray(filter)){
+      filter.length = 0;
+    }else{
+      filter = void 0;
+    }
+  }
+
+  return {
+    hook: (fn) => {
+      hookFns.push(fn);
+      return {
+        remove: () => {
+          return removeHook(fn, true);
+        }
+      }
+    },
+    filter: (arr) => {
+      filter = Array.isArray(arr) && arr.map(toFilterObj);
+      return {
+        remove: removeFilter
+      }
+    },
+    protect: () => {
+      readonly(win, "XMLHttpRequest", fakeXhr);
+      readonly(win, "fetch", fakeFetch);
+    },
+    unhook: () => {
+      writable(win, "XMLHttpRequest", realXhr);
+      writable(win, "fetch", realFetch);
+    },
+    removeHook: removeHook,
+    removeFilter: removeFilter
+  };
   })();
 };

package/src/types/Httpx.d.ts

@@ -1052,30 +1052,30 @@ export declare interface HttpxRequestOption {
    */
   data?: string | FormData | object;
   /**
-   * 是否自动对data进行处理
+   * 是否自动对`data`进行处理
    *
    * ## 处理以下请求类型
-   * + `GET` 自动进行`URLSearchParams`转换
-   * + `HEAD` 自动进行`URLSearchParams`转换
-   * + `POST` 处理`Content-Type`不为空的情况
+   * + 当请求类型为`GET`，自动进行`URLSearchParams`转换
+   * + 当请求类型为`HEAD`，自动进行`URLSearchParams`转换
+   * + 当请求类型为`POST`，根据下面的`Content-Type`类型来处理（`Content-Type`不为空才会处理）
    *
-   * ### `application/json`
+   * ### `POST` => `Content-Type` => `application/json`
    *
-   * + `string`: 不做处理
-   * + `FormData`: 转为`JSON`并进行`JSON.stringify`处理
-   * + `object`: 进行`JSON.stringify`处理
+   * + `data: string`: ignore
+   * + `data: object`: 进行`JSON.stringify`处理
+   * + `data: FormData`: 转为`JSON`并进行`JSON.stringify`处理
    *
-   * ### `application/x-www-form-urlencoded`
+   * ### `POST` => `Content-Type` => `application/x-www-form-urlencoded`
    *
-   * + `string`: 不做处理
-   * + `FormData`: 转为`URLSearchParams`，再转为`string`
-   * + `object`: 转为`URLSearchParams`，再转为`string`
+   * + `data: string`: ignore
+   * + `data: object`: 转为`URLSearchParams`，再转为`string`
+   * + `data: FormData`: 转为`URLSearchParams`，再转为`string`
    *
-   * ### `multipart/form-data`（上传文件专用）
+   * ### `POST` => `Content-Type` => `multipart/form-data`（上传文件专用）
    *
-   * + `string`: 不做处理
-   * + `FormData`: 移除`Content-Type`
-   * + `object`: 不做处理
+   * + `data: string`: ignore
+   * + `data: object`: ignore
+   * + `data: FormData`: 移除`Content-Type`
    * @default true
    */
   processData?: boolean;

package/src/types/ajaxHooker.d.ts

@@ -89,67 +89,103 @@ export declare interface UtilsAjaxHookFilterOptions {
 /** Utils.ajaxHooker */
 export declare interface UtilsAjaxHookResult {
   /**
-     * 劫持xhr和fetch
-     * 
-     * 提示：如果多次调用.hook方法，将会多次处理同一个请求
-     * @example
-        ajaxHooker.hook(request => {
-            if (request.url === 'https://www.example.com/') {
-                request.response = res => {
-                    console.log(res);
-                    res.responseText += 'test';
-                };
-            }
-        });
-      * @example
-        // 异步特性无法作用于同步请求，但同步修改仍然有效
-        // 你可以将以上所有可修改属性赋值为Promise，原请求将被阻塞直至Promise完成（若发生reject，数据将不会被修改）
-        // 此特性可用于异步劫持。以下是一个异步修改响应数据的例子
-        ajaxHooker.hook(request => {
-            request.response = res => {
-                const responseText = res.responseText; // 注意保存原数据
-                res.responseText = new Promise(resolve => {
-                    setTimeout(() => {
-                        resolve(responseText + 'test');
-                    }, 3000);
-                });
-            };
-        });
-
-        // 也可以传入async回调函数以实现异步
-        ajaxHooker.hook(async request => {
-            request.data = await modifyData(request.data);
-            request.response = async res => {
-                res.responseText = await modifyResponse(res.responseText);
-            };
-        });
-     */
+   * 劫持xhr和fetch
+   *
+   * 提示：如果多次调用.hook方法，将会多次处理同一个请求
+   * @example
+   *   ajaxHooker.hook(request => {
+   *       if (request.url === 'https://www.example.com/') {
+   *           request.response = res => {
+   *               console.log(res);
+   *               res.responseText += 'test';
+   *           };
+   *       }
+   *   });
+   * * @example
+   *   // 异步特性无法作用于同步请求，但同步修改仍然有效
+   *   // 你可以将以上所有可修改属性赋值为Promise，原请求将被阻塞直至Promise完成（若发生reject，数据将不会被修改）
+   *   // 此特性可用于异步劫持。以下是一个异步修改响应数据的例子
+   *   ajaxHooker.hook(request => {
+   *       request.response = res => {
+   *           const responseText = res.responseText; // 注意保存原数据
+   *           res.responseText = new Promise(resolve => {
+   *               setTimeout(() => {
+   *                   resolve(responseText + 'test');
+   *               }, 3000);
+   *           });
+   *       };
+   *   });
+   *   // 也可以传入async回调函数以实现异步
+   *   ajaxHooker.hook(async request => {
+   *       request.data = await modifyData(request.data);
+   *       request.response = async res => {
+   *           res.responseText = await modifyResponse(res.responseText);
+   *       };
+   *   });
+   */
   hook(
-    callback: (request: UtilsAjaxHookRequestOptions) => void | undefined | null | Promise<void | undefined | null>
-  ): void;
-  /**
-     * 过滤
-     * @example
-        // 应于hook方法之前执行，此方法若尽早执行，有助于提升性能。
-        // 为hook方法设置过滤规则，只有符合规则的请求才会触发hook。过滤规则是一个对象数组，参考下例
-        ajaxHooker.filter([
-            {type: 'xhr', url: 'www.example.com', method: 'GET', async: true},
-            {url: /^http/},
-        ]);
+    callback: (
+      /**
+       * hook请求的配置
+       */
+      request: UtilsAjaxHookRequestOptions,
+      /**
+       * 当前的`callback`的索引下标
+       */
+      index: number
+    ) => void | undefined | null | Promise<void | undefined | null>
+  ): {
+    /**
+     * 该函数是额外添加的，原版仅返回空值
      */
-  filter(filterOptions: UtilsAjaxHookFilterOptions[]): void;
+    remove: () => boolean;
+  };
   /**
-     * 阻止xhr和fetch被改写
-     * @example
-        // 如果库劫持失败，可能是其他代码对xhr/fetch进行了二次劫持，protect方法会尝试阻止xhr和fetch被改写。应于document-start阶段尽早执行，部分网页下可能引发错误，谨慎使用。
-        ajaxHooker.protect();
+   * 过滤
+   *
+   * 注意：重复调用`.filter`设置规则会覆盖之前设置的规则
+   * @example
+   *   // 应于hook方法之前执行，此方法若尽早执行，有助于提升性能。
+   *   // 为hook方法设置过滤规则，只有符合规则的请求才会触发hook。过滤规则是一个对象数组，参考下例
+   *   ajaxHooker.filter([
+   *       {type: 'xhr', url: 'www.example.com', method: 'GET', async: true},
+   *       {url: /^http/},
+   *   ]);
+   */
+  filter(filterOptions: UtilsAjaxHookFilterOptions[]): {
+    /**
+     * 该函数是额外添加的，原版仅返回空值
      */
+    remove: () => void;
+  };
+  /**
+   * 阻止xhr和fetch被改写
+   * @example
+   *  // 如果库劫持失败，可能是其他代码对xhr/fetch进行了二次劫持，protect方法会尝试阻止xhr和fetch被改写。应于document-start阶段尽早执行，部分网页下可能引发错误，谨慎使用。
+   *   ajaxHooker.protect();
+   */
   protect(): void;
   /**
-     * 取消劫持
-     * @example
-        // 将xhr和fetch恢复至劫持前的状态，调用此方法后，hook方法不再生效。
-        ajaxHooker.unhook();
-     */
+   * 取消劫持
+   * @example
+   *   // 将xhr和fetch恢复至劫持前的状态，调用此方法后，hook方法不再生效。
+   *   ajaxHooker.unhook();
+   */
   unhook(): void;
+  /**
+   * 移除通过`.hook`添加的函数
+   *
+   * @description 此函数为额外添加的增强函数
+   * @param fn `.hook`添加的函数
+   * @param onlyRemove （可选）是否仅移除一个（如果命中的话），默认false
+   */
+  removeHook(
+    fn: (request: UtilsAjaxHookRequestOptions) => void | undefined | null | Promise<void | undefined | null>,
+    onlyRemove: boolean
+  ): boolean;
+  /**
+   * 重置通过`.filter`设置的规则
+   * @description 此函数为额外添加的增强函数
+   */
+  removeFilter(): void;
 }