✨ [util] 新增func_throttle

Author: Gaubee

deno.lock

@@ -1,6 +1,6 @@
 {
   "name": "@gaubee/util",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "exports": {
     "./abort": "./src/abort.ts",
     "./bigint": "./src/bigint.ts",
@@ -23,6 +23,7 @@
     "./pure_event": "./src/pure_event.ts",
     "./readable_stream": "./src/readable_stream.ts",
     "./string": "./src/string.ts",
+    "./throttle": "./src/throttle.ts",
     ".": "./src/index.ts"
   },
   "publish": {

util/deno.json

@@ -47,7 +47,7 @@ Deno.test("should clear the timer with `cancel` method", async () => {
     const debounced = func_debounce(fn, 100);
 
     debounced();
-    debounced.clear();
+    debounced.cancel();
 
     await delay(200);
 

util/src/debounce.test.ts

@@ -5,7 +5,7 @@ import { type Timmer, timmers } from "./promise.ts";
 export namespace func_debounce {
     export type DebouncedFunction<F extends Func> = Func.SetReturn<F, Promise<Func.Return<F>>> & {
         readonly isPending: boolean;
-        clear(): void;
+        cancel(): void;
         source: F;
         flush(): void;
     };
@@ -64,7 +64,7 @@ export const func_debounce = <T extends Func>(
         get isPending() {
             return clear != null;
         },
-        clear() {
+        cancel() {
             clear?.();
         },
         source: fn,

util/src/debounce.ts

@@ -174,37 +174,80 @@ export const extendsGetter = <T extends object>(
 };
 
 export interface FuncCatch {
-    <E = unknown, F extends Func = Func>(fn: F, errorParser?: (err: unknown) => E): FuncCatchWrapper<E, F>;
+    <E = unknown, F extends Func = Func>(fn: F, errorParser?: (err: unknown) => E): FuncCatch.Wrapper<E, F>;
+    wrapSuccess: <R>(resule: R) => FuncCatch.SuccessReturn<R>;
+    wrapError: <E>(err: E, errorParser?: (err: unknown) => E) => FuncCatch.ErrorReturn<E>;
 }
-export type FuncCatchWrapper<E, F extends Func> =
-    & Func<
-        ThisParameterType<F>,
-        Parameters<F>,
-        FuncCatchReturn<E, ReturnType<F>>
-    >
-    & {
-        catchType<E>(errorParser?: (err: unknown) => E): FuncCatchWrapper<E, F>;
+export namespace FuncCatch {
+    export type Wrapper<E, F extends Func> =
+        & Func<
+            ThisParameterType<F>,
+            Parameters<F>,
+            Return<E, ReturnType<F>>
+        >
+        & {
+            catchType<E>(errorParser?: (err: unknown) => E): Wrapper<E, F>;
+        };
+    export type SuccessReturn<R> = readonly [undefined, R] & {
+        readonly success: true;
+        readonly result: R;
+        readonly error: void;
+    };
+    export type ErrorReturn<E> = readonly [E, undefined] & {
+        readonly success: false;
+        readonly result: void;
+        readonly error: E;
     };
-export type FuncCatchReturn<E, R> = R extends PromiseLike<infer R> ? PromiseLike<[E, undefined] | [undefined, R]>
-    : [E, undefined] | [undefined, R];
+    export type Return<E, R> = [R] extends [never] ? ErrorReturn<E>
+        : R extends PromiseLike<infer T> ? PromiseLike<SuccessReturn<T> | ErrorReturn<E>>
+        : SuccessReturn<R> | ErrorReturn<E>;
+}
+
+const wrapSuccess = <R>(result: R): FuncCatch.SuccessReturn<R> => {
+    return Object.defineProperties(
+        [undefined, result] as const,
+        {
+            success: { value: true, writable: false, enumerable: false, configurable: true },
+            result: { value: result, writable: false, enumerable: false, configurable: true },
+            error: { value: undefined, writable: false, enumerable: false, configurable: true },
+        } as const,
+    ) as FuncCatch.SuccessReturn<R>;
+};
+const wrapError = <E>(err: E, errorParser?: (err: unknown) => E): FuncCatch.ErrorReturn<E> => {
+    const error = errorParser ? errorParser(err) : err as E;
+    return Object.defineProperties(
+        [error, undefined] as const,
+        {
+            success: { value: false, writable: false, enumerable: false, configurable: true },
+            result: { value: undefined, writable: false, enumerable: false, configurable: true },
+            error: { value: error, writable: false, enumerable: false, configurable: true },
+        } as const,
+    ) as FuncCatch.ErrorReturn<E>;
+};
 /** 包裹一个函数，并对其进行错误捕捉并返回 */
-export const func_catch: FuncCatch = <E = unknown, F extends Func = Func>(fn: F, errorParser?: (err: unknown) => E) => {
-    return Object.assign(function (this: ThisParameterType<F>) {
-        try {
-            const res: ReturnType<F> = fn.apply(this, arguments as any);
-            if (isPromiseLike(res)) {
-                return res.then(
-                    (value: unknown) => [undefined, value],
-                    (err: unknown) => [errorParser ? errorParser(err) : err as E, undefined],
-                );
+export const func_catch: FuncCatch = Object.assign(
+    <E = unknown, F extends Func = Func>(fn: F, errorParser?: (err: unknown) => E) => {
+        return Object.assign(function (this: ThisParameterType<F>) {
+            try {
+                const res: ReturnType<F> = fn.apply(this, arguments as any);
+                if (isPromiseLike(res)) {
+                    return res.then(
+                        (value: unknown) => wrapSuccess(value),
+                        (err: unknown) => wrapError(err, errorParser),
+                    );
+                }
+                return wrapSuccess(res);
+            } catch (err) {
+                return wrapError(err, errorParser);
             }
-            return [undefined, res];
-        } catch (err) {
-            return [errorParser ? errorParser(err) : err as E, undefined];
-        }
-    }, {
-        catchType<E>(errorParser?: (err: unknown) => E) {
-            return func_catch(fn, errorParser);
-        },
-    }) as FuncCatchWrapper<E, F>;
-};
+        }, {
+            catchType<E>(errorParser?: (err: unknown) => E) {
+                return func_catch(fn, errorParser);
+            },
+        });
+    },
+    {
+        wrapSuccess,
+        wrapError,
+    },
+);

util/src/func.ts

@@ -21,3 +21,4 @@ export * from "./promise.ts";
 export * from "./pure_event.ts";
 export * from "./readable_stream.ts";
 export * from "./string.ts";
+export * from "./throttle.ts";

util/src/index.ts

@@ -0,0 +1,81 @@
+import { func_throttle } from "./throttle.ts";
+import assert from "node:assert";
+import { delay } from "./promise.ts";
+
+Deno.test("should throttle function calls", async () => {
+    let callCount = 0;
+    const fn = () => callCount++;
+
+    // 测试 leading: false 的情况
+    const throttled = func_throttle(fn, 100);
+
+    throttled(); // 不会立即执行
+    assert.equal(callCount, 0);
+
+    await delay(150);
+    assert.equal(callCount, 1); // 延迟后执行
+});
+Deno.test("should support `before` option", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+    const throttled = func_throttle(fn, 100, { before: true });
+
+    throttled(); // 立即执行（假设默认配置）
+    assert.equal(callCount, 1); // 第一次立即调用
+
+    throttled();
+    throttled();
+
+    assert.equal(callCount, 1);
+
+    await delay(150); // 超过节流时间
+    assert.equal(callCount, 2); // 新时间窗口的第一次调用
+});
+
+Deno.test("should cancel pending execution", async () => {
+    let callCount = 0;
+    const fn = () => callCount++;
+    const throttled = func_throttle(fn, 100);
+
+    throttled(); // 立即执行
+    throttled.cancel();
+
+    await delay(150);
+    assert.equal(callCount, 0); // 取消后不应再执行
+});
+
+Deno.test("should flush pending execution", async () => {
+    let callCount = 0;
+    const fn = () => callCount++;
+    const throttled = func_throttle(fn, 100, { before: false });
+
+    throttled();
+    throttled.flush(); // 立即执行
+
+    assert.equal(callCount, 1);
+    await delay(150);
+    assert.equal(callCount, 1); // 不应重复执行
+});
+
+Deno.test("should return promise with result", async () => {
+    const fn = () => "result";
+    const throttled = func_throttle(fn, 100);
+
+    const result = await throttled();
+    assert.equal(result, "result");
+});
+
+Deno.test("should track pending status", async () => {
+    const fn = () => {};
+    const throttled = func_throttle(fn, 100, { before: false });
+
+    assert(!throttled.isPending);
+
+    throttled();
+    assert(throttled.isPending); // 有等待中的执行
+
+    await delay(150);
+    assert(!throttled.isPending);
+});

util/src/throttle.test.ts

@@ -0,0 +1,85 @@
+import { type Func, func_catch } from "./func.ts";
+import { obj_assign_props } from "./object.ts";
+import { type Timmer, timmers } from "./promise.ts";
+export namespace func_throttle {
+    export type ThrottledFunction<F extends Func> = Func.SetReturn<F, Promise<Func.Return<F>>> & {
+        readonly isPending: boolean;
+        clear(): void;
+        source: F;
+        flush(): void;
+    };
+}
+
+export const func_throttle = <T extends Func>(
+    fn: T,
+    wait: number | Timmer = 0,
+    options: { waitPromise?: boolean; before?: boolean } = {},
+) => {
+    const timmer = timmers.from(wait);
+    let clear: Timmer.Clear | undefined;
+
+    type R = Func.Return<T>;
+    let jobs: PromiseWithResolvers<R>[] = [];
+
+    let target: Func | undefined;
+
+    return obj_assign_props(function throttled(this: Func.This<T>, ...args: Func.Args<T>) { // eslint-disable-line func-names
+        const job = Promise.withResolvers<R>();
+        if (clear == null) {
+            clear = timmer(
+                target = async () => {
+                    target = undefined;
+                    if (!options.waitPromise) {
+                        clear = undefined;
+                    }
+
+                    const res = await func_catch(() => fn.apply(this, args) as Func.Return<T>)();
+
+                    if (options.waitPromise) {
+                        clear = undefined;
+                    }
+                    if (res.success) {
+                        for (const job of jobs) {
+                            job.resolve(res.result);
+                        }
+                    } else {
+                        for (const job of jobs) {
+                            job.reject(res.error);
+                        }
+                    }
+                    jobs = [];
+                },
+            );
+            if (options.before) {
+                (async () => {
+                    const res = await func_catch(() => fn.apply(this, args) as Func.Return<T>)();
+                    if (res.success) {
+                        job.resolve(res.result);
+                    } else {
+                        job.reject(res.error);
+                    }
+                })();
+            } else {
+                jobs.push(job);
+            }
+        } else {
+            jobs.push(job);
+        }
+
+        return job.promise;
+    }, {
+        get isPending() {
+            return clear != null;
+        },
+        cancel() {
+            clear?.();
+            clear = undefined;
+        },
+        source: fn,
+        flush() {
+            clear?.();
+            clear = undefined;
+            target?.();
+        },
+    });
+};