@vnejs/helpers.debounce 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type DebounceFn = (...args: never[]) => unknown;
+export type DebounceOptions<T extends DebounceFn> = {
+    fn: T;
+    wait?: number;
+    maxWait?: number;
+    leading?: boolean;
+    trailing?: boolean;
+};
+export declare const debounce: <T extends DebounceFn>({ fn, wait, maxWait, leading, trailing, }: DebounceOptions<T>) => ((...args: Parameters<T>) => void);

package/dist/index.js

@@ -0,0 +1,59 @@
+export const debounce = ({ fn, wait = 0, maxWait, leading = false, trailing = true, }) => {
+    let waitTimer;
+    let maxTimer;
+    let lastArgs;
+    let isPending = false;
+    const clearTimers = () => {
+        if (waitTimer !== undefined)
+            clearTimeout(waitTimer);
+        if (maxTimer !== undefined)
+            clearTimeout(maxTimer);
+        waitTimer = undefined;
+        maxTimer = undefined;
+    };
+    const invoke = () => {
+        const args = lastArgs;
+        lastArgs = undefined;
+        isPending = false;
+        clearTimers();
+        if (args)
+            fn(...args);
+    };
+    return (...args) => {
+        const isLeadingCall = leading && !isPending;
+        lastArgs = args;
+        isPending = true;
+        if (isLeadingCall) {
+            fn(...args);
+            lastArgs = undefined;
+        }
+        if (waitTimer !== undefined)
+            clearTimeout(waitTimer);
+        waitTimer = setTimeout(() => {
+            waitTimer = undefined;
+            if (trailing && lastArgs)
+                invoke();
+            else {
+                isPending = false;
+                lastArgs = undefined;
+                if (maxTimer !== undefined)
+                    clearTimeout(maxTimer);
+                maxTimer = undefined;
+            }
+        }, wait);
+        if (maxWait !== undefined && maxTimer === undefined) {
+            maxTimer = setTimeout(() => {
+                maxTimer = undefined;
+                if (trailing && lastArgs)
+                    invoke();
+                else {
+                    isPending = false;
+                    lastArgs = undefined;
+                    if (waitTimer !== undefined)
+                        clearTimeout(waitTimer);
+                    waitTimer = undefined;
+                }
+            }, maxWait);
+        }
+    };
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@vnejs/helpers.debounce",
+  "version": "0.2.1",
+  "description": "",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "npx @vnejs/monorepo test",
+    "build": "npx @vnejs/monorepo package",
+    "publish:major:plugin": "npm run publish:major",
+    "publish:minor:plugin": "npm run publish:minor",
+    "publish:patch:plugin": "npm run publish:patch",
+    "publish:major": "npx @vnejs/monorepo publish major --access public",
+    "publish:minor": "npx @vnejs/monorepo publish minor --access public",
+    "publish:patch": "npx @vnejs/monorepo publish patch --access public"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@vnejs/configs.ts-common": "~0.2.0",
+    "@vnejs/configs.vitest": "~0.2.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+export type DebounceFn = (...args: never[]) => unknown;
+
+export type DebounceOptions<T extends DebounceFn> = {
+  fn: T;
+  wait?: number;
+  maxWait?: number;
+  leading?: boolean;
+  trailing?: boolean;
+};
+
+export const debounce = <T extends DebounceFn>({
+  fn,
+  wait = 0,
+  maxWait,
+  leading = false,
+  trailing = true,
+}: DebounceOptions<T>): ((...args: Parameters<T>) => void) => {
+  let waitTimer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined;
+  let lastArgs: Parameters<T> | undefined;
+  let isPending = false;
+
+  const clearTimers = () => {
+    if (waitTimer !== undefined) clearTimeout(waitTimer);
+    if (maxTimer !== undefined) clearTimeout(maxTimer);
+    waitTimer = undefined;
+    maxTimer = undefined;
+  };
+
+  const invoke = () => {
+    const args = lastArgs;
+    lastArgs = undefined;
+    isPending = false;
+    clearTimers();
+    if (args) fn(...args);
+  };
+
+  return (...args: Parameters<T>) => {
+    const isLeadingCall = leading && !isPending;
+
+    lastArgs = args;
+    isPending = true;
+
+    if (isLeadingCall) {
+      fn(...args);
+      lastArgs = undefined;
+    }
+
+    if (waitTimer !== undefined) clearTimeout(waitTimer);
+    waitTimer = setTimeout(() => {
+      waitTimer = undefined;
+      if (trailing && lastArgs) invoke();
+      else {
+        isPending = false;
+        lastArgs = undefined;
+        if (maxTimer !== undefined) clearTimeout(maxTimer);
+        maxTimer = undefined;
+      }
+    }, wait);
+
+    if (maxWait !== undefined && maxTimer === undefined) {
+      maxTimer = setTimeout(() => {
+        maxTimer = undefined;
+        if (trailing && lastArgs) invoke();
+        else {
+          isPending = false;
+          lastArgs = undefined;
+          if (waitTimer !== undefined) clearTimeout(waitTimer);
+          waitTimer = undefined;
+        }
+      }, maxWait);
+    }
+  };
+};

package/src/tests/debounce.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { debounce } from "../index.js";
+
+describe("debounce", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("trailing call fires after wait", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const debounced = debounce({ fn, wait: 100 });
+
+    debounced();
+    debounced();
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("leading call fires immediately", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const debounced = debounce({ fn, wait: 100, leading: true, trailing: false });
+
+    debounced();
+    expect(fn).toHaveBeenCalledOnce();
+
+    debounced();
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("leading and trailing fire for a burst", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const debounced = debounce({ fn, wait: 100, leading: true, trailing: true });
+
+    debounced();
+    debounced();
+    expect(fn).toHaveBeenCalledOnce();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("maxWait flushes before wait silence", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const debounced = debounce({ fn, wait: 100, maxWait: 150 });
+
+    debounced();
+    vi.advanceTimersByTime(90);
+    debounced();
+    vi.advanceTimersByTime(90);
+    expect(fn).toHaveBeenCalledOnce();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "@vnejs/configs.ts-common/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules",
+    "src/tests"
+  ]
+}