✨ [util] 新增func_debounce，新增timmers

Author: Gaubee

deno.lock

@@ -1,38 +1,32 @@
 {
-    "name": "@gaubee/util",
-    "version": "0.21.1",
-    "exports": {
-        "./abort": "./src/abort.ts",
-        "./bigint": "./src/bigint.ts",
-        "./collections": "./src/collections.ts",
-        "./date": "./src/date.ts",
-        "./decorators-legacy": "./src/decorators-legacy.ts",
-        "./decorators": "./src/decorators.ts",
-        "./disposable": "./src/disposable.ts",
-        "./encoding": "./src/encoding.ts",
-        "./event_target": "./src/event_target.ts",
-        "./func": "./src/func.ts",
-        "./generator": "./src/generator.ts",
-        "./lrc": "./src/lrc.ts",
-        "./map": "./src/map.ts",
-        "./math": "./src/math.ts",
-        "./number": "./src/number.ts",
-        "./object": "./src/object.ts",
-        "./promise": "./src/promise.ts",
-        "./pure_event": "./src/pure_event.ts",
-        "./readable_stream": "./src/readable_stream.ts",
-        "./string": "./src/string.ts",
-        ".": "./src/index.ts"
-    },
-    "publish": {
-        "include": [
-            "LICENSE",
-            "README.md",
-            "src/**/*.ts"
-        ],
-        "exclude": [
-            "src/**/*.bench.ts",
-            "src/**/*.test.ts"
-        ]
-    }
-}
+  "name": "@gaubee/util",
+  "version": "0.22.0",
+  "exports": {
+    "./abort": "./src/abort.ts",
+    "./bigint": "./src/bigint.ts",
+    "./collections": "./src/collections.ts",
+    "./date": "./src/date.ts",
+    "./debounce": "./src/debounce.ts",
+    "./decorators-legacy": "./src/decorators-legacy.ts",
+    "./decorators": "./src/decorators.ts",
+    "./disposable": "./src/disposable.ts",
+    "./encoding": "./src/encoding.ts",
+    "./event_target": "./src/event_target.ts",
+    "./func": "./src/func.ts",
+    "./generator": "./src/generator.ts",
+    "./lrc": "./src/lrc.ts",
+    "./map": "./src/map.ts",
+    "./math": "./src/math.ts",
+    "./number": "./src/number.ts",
+    "./object": "./src/object.ts",
+    "./promise": "./src/promise.ts",
+    "./pure_event": "./src/pure_event.ts",
+    "./readable_stream": "./src/readable_stream.ts",
+    "./string": "./src/string.ts",
+    ".": "./src/index.ts"
+  },
+  "publish": {
+    "include": ["LICENSE", "README.md", "src/**/*.ts"],
+    "exclude": ["src/**/*.bench.ts", "src/**/*.test.ts"]
+  }
+}

util/deno.json

@@ -0,0 +1,102 @@
+import { func_debounce } from "./debounce.ts";
+import assert from "node:assert";
+import { delay } from "./promise.ts";
+
+Deno.test("should debounce function calls", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+
+    const debounced = func_debounce(fn, 100);
+
+    debounced();
+    debounced();
+    debounced();
+
+    assert.equal(callCount, 0);
+
+    await delay(200);
+
+    assert.equal(callCount, 1);
+});
+
+Deno.test("should call the function immediately if `before` option is true", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+
+    const debounced = func_debounce(fn, 100, { before: true });
+
+    debounced();
+
+    assert.equal(callCount, 1);
+
+    await delay(200);
+
+    assert.equal(callCount, 1);
+});
+
+Deno.test("should clear the timer with `cancel` method", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+
+    const debounced = func_debounce(fn, 100);
+
+    debounced();
+    debounced.clear();
+
+    await delay(200);
+
+    assert.equal(callCount, 0);
+});
+
+Deno.test("should flush the timer with `flush` method", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+
+    const debounced = func_debounce(fn, 100);
+
+    debounced();
+    debounced.flush();
+
+    assert.equal(callCount, 1);
+
+    await delay(200);
+
+    assert.equal(callCount, 1);
+});
+
+Deno.test("should return a promise that resolves with the function result", async () => {
+    const fn = () => "result";
+
+    const debounced = func_debounce(fn, 100);
+
+    const result = await debounced();
+
+    assert.equal(result, "result");
+});
+
+Deno.test("should have `isPending` property", async () => {
+    let callCount = 0;
+    const fn = () => {
+        callCount++;
+    };
+
+    const debounced = func_debounce(fn, 100);
+
+    assert(!debounced.isPending);
+
+    debounced();
+
+    assert(debounced.isPending);
+
+    await delay(200);
+
+    assert(!debounced.isPending);
+});

util/src/debounce.test.ts

@@ -0,0 +1,78 @@
+import type { Func } from "./func.ts";
+import { obj_assign_props } from "./object.ts";
+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;
+        source: F;
+        flush(): void;
+    };
+}
+
+export const func_debounce = <T extends Func>(
+    fn: T,
+    wait: number | Timmer = 0,
+    options: {
+        /**
+         * Call the `fn` on the [leading edge of the timeout](https://css-tricks.com/debouncing-throttling-explained-examples/#article-header-id-1). Meaning immediately, instead of waiting for `wait` milliseconds.
+         */
+        before?: boolean;
+    } = {},
+): func_debounce.DebouncedFunction<T> => {
+    if (!Number.isFinite(wait)) {
+        throw new TypeError("Expected `wait` to be a finite number");
+    }
+    const timmer = timmers.from(wait);
+
+    let leadingValue: R;
+    let clear: Timmer.Clear | undefined;
+    type R = Func.Return<T>;
+    let jobList: PromiseWithResolvers<R>[] = [];
+
+    let trigger: Func | undefined;
+    return obj_assign_props(function (this: Func.This<T>, ...args: Func.Args<T>) {
+        const job = Promise.withResolvers<R>();
+        const shouldCallNow = options.before && null == clear;
+
+        if (shouldCallNow) {
+            leadingValue = fn.apply(this, args);
+            job.resolve(leadingValue);
+        } else {
+            jobList.push(job);
+        }
+
+        clear?.();
+        clear = timmer(
+            trigger = () => {
+                clear = undefined;
+                trigger = undefined;
+
+                const result = options.before ? leadingValue : fn.apply(this, args);
+
+                for (const job of jobList) {
+                    job.resolve(result);
+                }
+
+                jobList = [];
+            },
+        );
+
+        return job.promise;
+    }, {
+        get isPending() {
+            return clear != null;
+        },
+        clear() {
+            clear?.();
+        },
+        source: fn,
+        flush() {
+            if (clear != null) {
+                clear();
+                trigger?.();
+            }
+        },
+    });
+};

util/src/debounce.ts

@@ -31,18 +31,23 @@ export type Func<This = any, Arguments extends readonly unknown[] = any[], Retur
             this: This,
             ...args: Arguments
         ) => Return;
-type FunReturn<F> = F extends Func ? ReturnType<F> : undefined;
+export namespace Func {
+    export type Return<F> = F extends Func ? ReturnType<F> : never;
+    export type Args<F> = F extends Func ? Parameters<F> : never;
+    export type This<F> = F extends Func<infer T> ? T : never;
+    export type SetReturn<T, R> = Func<This<T>, Args<T>, R>;
+}
 type KeyFun<F extends Func> = Func<ThisParameterType<F>, Parameters<F>>;
 export type FuncRemember<
     F extends Func,
     K extends (KeyFun<F> | void) = void,
 > = F & {
     readonly source: F;
-    readonly key: FunReturn<K> | undefined;
+    readonly key: Func.Return<K> | undefined;
     readonly runned: boolean;
-    readonly returnValue: ReturnType<F> | undefined;
+    readonly returnValue: Func.Return<F> | undefined;
     reset(): void;
-    rerun(...args: Parameters<F>): ReturnType<F>;
+    rerun(...args: Parameters<F>): Func.Return<F>;
 };
 /**
  * 让一个函数的返回结果是缓存的
@@ -54,8 +59,8 @@ export const func_remember = <
     K extends Func<ThisParameterType<F>, Parameters<F>> | void | void,
 >(func: F, key?: K): FuncRemember<F, K> => {
     let result: {
-        key: FunReturn<K>;
-        res: ReturnType<F>;
+        key: Func.Return<K>;
+        res: Func.Return<F>;
     } | undefined;
 
     const once_fn = function (
@@ -91,7 +96,7 @@ export const func_remember = <
         },
         rerun(...args: Parameters<F>) {
             once_fn_mix.reset();
-            return once_fn_mix(...args) as ReturnType<F>;
+            return once_fn_mix(...args) as Func.Return<F>;
         },
     });
     Object.defineProperties(once_fn_mix, {

util/src/func.ts

@@ -3,6 +3,7 @@ export * from "./generator.ts";
 export * from "./bigint.ts";
 export * from "./collections.ts";
 export * from "./date.ts";
+export * from "./debounce.ts";
 export * from "./decorators-legacy.ts";
 export * from "./decorators.ts";
 export * from "./disposable.ts";