debounce-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atif C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# debounce-ts
+
+A lightweight, type-safe debounce utility for both sync and async functions with support for leading-edge execution, maximum wait enforcement, and error handling.
+
+## Installation
+
+```bash
+npm install debounce-ts
+```
+
+## Basic Usage
+
+```typescript
+import { debounce } from 'debounce-ts';
+
+// Async function example
+const saveData = debounce(
+	async (text: string) => {
+		await fetch('/api/save', {
+			method: 'POST',
+			body: JSON.stringify({ text })
+		});
+	},
+	{ delay: 500 }
+);
+
+// Fire-and-forget — function is invoked 500ms after last call
+input.addEventListener('input', e => saveData(e.target.value));
+
+// Sync function example
+const updateCounter = debounce(
+	(count: number) => {
+		document.getElementById('counter').textContent = count.toString();
+	},
+	{ delay: 300 }
+);
+
+button.addEventListener('click', () => updateCounter(++clicks));
+```
+
+## API
+
+### debounce(fn, options?)
+
+**Parameters:**
+
+- `fn` (Function): Function to debounce (can be sync or async)
+- `options` (object, optional):
+  - `immediate` (boolean, default: `false`) — Fire on leading edge. Also fires trailing if new args arrive during cooldown.
+  - `delay` (number, default: `1000`) — Wait time in ms after last call
+  - `maxWait` (number, optional) — Max time before forced execution
+  - `onError` ((error: unknown) => void, optional) — Error handler for async rejections. Without this, errors surface as unhandled rejections.
+
+**Returns:** `DebouncedFunction` — Debounced function (void return, fire-and-forget)
+
+**Methods on returned function:**
+
+- `.cancel()` — Cancel all pending invocations and clear timers
+- `.flush()` — Immediately execute pending invocation (if any) and clear timers
+
+**Throws:**
+
+- `TypeError` if delay is not a non-negative number
+- `TypeError` if maxWait is not a non-negative number
+- `TypeError` if maxWait < delay
+
+## Comprehensive Example
+
+```typescript
+import { debounce } from 'debounce-ts';
+
+// Real-world: Auto-save user input
+// - Immediate feedback (save on first keystroke)
+// - Debounced API calls (wait 500ms after typing stops)
+// - Maximum 5-second delay (force-save during continuous typing)
+// - Error handling via onError callback
+
+const autoSave = debounce(
+	async (text: string) => {
+		const response = await fetch('/api/save', {
+			method: 'POST',
+			body: JSON.stringify({ text })
+		});
+		if (!response.ok) throw new Error('Save failed');
+	},
+	{
+		immediate: true,
+		delay: 500,
+		maxWait: 5000,
+		onError: error => {
+			console.error('Auto-save failed:', error);
+			showNotification('Failed to save. Will retry...');
+		}
+	}
+);
+
+// Fire-and-forget — errors route to onError callback
+const textInput = document.querySelector('textarea');
+textInput.addEventListener('input', e => {
+	autoSave(e.target.value);
+});
+
+// Force-save any pending data before page unload
+window.addEventListener('beforeunload', () => {
+	autoSave.flush();
+});
+
+// Cancel pending save (e.g., user discards changes)
+function handleDiscard() {
+	autoSave.cancel();
+}
+```
+
+## Error Handling
+
+By default, errors from the debounced function (both sync and async) surface as **unhandled rejections** (Node's standard behavior). To handle errors explicitly:
+
+```typescript
+const save = debounce(
+	async data => {
+		throw new Error('Network error');
+	},
+	{
+		onError: error => {
+			// Handle error here
+			console.error('Save failed:', error);
+		}
+	}
+);
+```
+
+Without `onError`, the error will trigger Node's `unhandledRejection` event, making it visible in logs and crash reporters.
+
+## TypeScript Support
+
+This package is written in TypeScript and exports full type definitions. The `DebouncedFunction` interface is exported for use in your code:
+
+```typescript
+import { debounce, DebouncedFunction } from 'debounce-ts';
+
+const save: DebouncedFunction<[string]> = debounce(
+	async (text: string) => {
+		await api.save(text);
+	},
+	{ delay: 500 }
+);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+export interface DebounceOptions {
+    immediate?: boolean;
+    delay?: number;
+    maxWait?: number;
+    onError?: (error: unknown) => void;
+}
+export interface DebouncedFunction<TArgs extends readonly unknown[]> {
+    (...args: TArgs): void;
+    cancel(): void;
+    flush(): void;
+}
+/**
+ * Creates a debounced version of a function (sync or async) that delays invoking it
+ * until after a specified wait time has elapsed since the last call.
+ *
+ * Supports leading-edge invocation (immediate), max wait enforcement, and
+ * error handling via an onError callback.
+ *
+ * @template TArgs - Function argument types
+ * @template TReturn - Function return type
+ * @param {Function} fn - Function to debounce (can be sync or async)
+ * @param {DebounceOptions} [options] - Configuration options
+ * @param {boolean} [options.immediate=false] - Fire on leading edge. Also fires
+ *   trailing if new args arrive during cooldown.
+ * @param {number} [options.delay=1000] - Delay in ms after last call
+ * @param {number} [options.maxWait] - Max time in ms before forced execution
+ * @param {Function} [options.onError] - Error handler for async rejections.
+ *   Without this, errors surface as unhandled rejections.
+ * @returns {DebouncedFunction} Debounced function (void return) with
+ *   cancel() and flush() methods
+ *
+ * @throws {TypeError} If delay is not a non-negative number
+ * @throws {TypeError} If maxWait is not a non-negative number
+ * @throws {TypeError} If maxWait < delay
+ *
+ * @example
+ * // Async function
+ * const save = debounce(async (data) => {
+ *     await api.save(data);
+ * }, {
+ *     delay: 500,
+ *     maxWait: 5000,
+ *     immediate: true,
+ *     onError: (err) => console.error('Save failed:', err),
+ * });
+ *
+ * // Sync function
+ * const updateUI = debounce((value) => {
+ *     element.textContent = value;
+ * }, { delay: 300 });
+ *
+ * input.addEventListener('input', (e) => save(e.target.value));
+ *
+ * // Cleanup on unmount:
+ * save.cancel();
+ *
+ * // Force save before navigation:
+ * save.flush();
+ */
+export declare const debounce: <TArgs extends readonly unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>, options?: DebounceOptions) => DebouncedFunction<TArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,SAAS,OAAO,EAAE;IAClE,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,SAAS,SAAS,OAAO,EAAE,EAAE,OAAO,EACjE,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAClD,UAAU,eAAe,KACvB,iBAAiB,CAAC,KAAK,CA4HzB,CAAC"}

package/dist/index.js

@@ -0,0 +1,154 @@
+/**
+ * Creates a debounced version of a function (sync or async) that delays invoking it
+ * until after a specified wait time has elapsed since the last call.
+ *
+ * Supports leading-edge invocation (immediate), max wait enforcement, and
+ * error handling via an onError callback.
+ *
+ * @template TArgs - Function argument types
+ * @template TReturn - Function return type
+ * @param {Function} fn - Function to debounce (can be sync or async)
+ * @param {DebounceOptions} [options] - Configuration options
+ * @param {boolean} [options.immediate=false] - Fire on leading edge. Also fires
+ *   trailing if new args arrive during cooldown.
+ * @param {number} [options.delay=1000] - Delay in ms after last call
+ * @param {number} [options.maxWait] - Max time in ms before forced execution
+ * @param {Function} [options.onError] - Error handler for async rejections.
+ *   Without this, errors surface as unhandled rejections.
+ * @returns {DebouncedFunction} Debounced function (void return) with
+ *   cancel() and flush() methods
+ *
+ * @throws {TypeError} If delay is not a non-negative number
+ * @throws {TypeError} If maxWait is not a non-negative number
+ * @throws {TypeError} If maxWait < delay
+ *
+ * @example
+ * // Async function
+ * const save = debounce(async (data) => {
+ *     await api.save(data);
+ * }, {
+ *     delay: 500,
+ *     maxWait: 5000,
+ *     immediate: true,
+ *     onError: (err) => console.error('Save failed:', err),
+ * });
+ *
+ * // Sync function
+ * const updateUI = debounce((value) => {
+ *     element.textContent = value;
+ * }, { delay: 300 });
+ *
+ * input.addEventListener('input', (e) => save(e.target.value));
+ *
+ * // Cleanup on unmount:
+ * save.cancel();
+ *
+ * // Force save before navigation:
+ * save.flush();
+ */
+export const debounce = (fn, options) => {
+    const { immediate = false, delay = 1000, maxWait, onError } = options ?? {};
+    // Input validation
+    if (typeof delay !== 'number' || Number.isNaN(delay) || delay < 0) {
+        throw new TypeError('delay must be a non-negative number');
+    }
+    if (maxWait !== undefined) {
+        if (typeof maxWait !== 'number' || Number.isNaN(maxWait) || maxWait < 0) {
+            throw new TypeError('maxWait must be a non-negative number');
+        }
+        if (maxWait < delay) {
+            throw new TypeError('maxWait must be greater than or equal to delay');
+        }
+    }
+    let timeout = null;
+    let maxTimeout = null;
+    let pendingArgs = null;
+    let firstCallTime = null;
+    const invoke = () => {
+        if (!pendingArgs)
+            return;
+        const args = pendingArgs;
+        pendingArgs = null;
+        // Wrap in try-catch to handle sync errors, then Promise.resolve() for async
+        try {
+            const result = fn(...args);
+            const promise = Promise.resolve(result);
+            if (onError) {
+                promise.catch(onError);
+            }
+            // Without onError, the rejection is unhandled → triggers
+            // Node's unhandledRejection event (standard, visible behavior)
+        }
+        catch (error) {
+            // Handle synchronous errors
+            if (onError) {
+                onError(error);
+            }
+            else {
+                // Re-throw to maintain unhandled rejection behavior
+                Promise.reject(error);
+            }
+        }
+    };
+    const clearTimers = () => {
+        if (timeout) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+        if (maxTimeout) {
+            clearTimeout(maxTimeout);
+            maxTimeout = null;
+        }
+    };
+    const startMaxWaitTimer = () => {
+        if (maxWait === undefined || maxTimeout || firstCallTime === null)
+            return;
+        const elapsed = Date.now() - firstCallTime;
+        const remaining = Math.max(0, maxWait - elapsed);
+        maxTimeout = setTimeout(() => {
+            clearTimers();
+            invoke();
+            firstCallTime = null;
+        }, remaining);
+    };
+    const debounced = ((...args) => {
+        pendingArgs = args;
+        if (firstCallTime === null) {
+            firstCallTime = Date.now();
+        }
+        const shouldInvokeLeading = immediate && timeout === null;
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(() => {
+            timeout = null;
+            // Fire trailing call if:
+            // - Not in immediate mode (standard trailing behavior), OR
+            // - In immediate mode AND new args arrived after the leading call
+            if (!immediate || pendingArgs !== null) {
+                invoke();
+            }
+            if (maxTimeout) {
+                clearTimeout(maxTimeout);
+                maxTimeout = null;
+            }
+            firstCallTime = null;
+        }, delay);
+        if (shouldInvokeLeading) {
+            invoke();
+            // invoke() nulls pendingArgs. Any subsequent call during cooldown
+            // sets pendingArgs to new args, which the trailing timeout detects.
+        }
+        startMaxWaitTimer();
+    });
+    debounced.cancel = () => {
+        clearTimers();
+        pendingArgs = null;
+        firstCallTime = null;
+    };
+    debounced.flush = () => {
+        clearTimers();
+        invoke();
+    };
+    return debounced;
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "debounce-ts",
+	"version": "1.0.0",
+	"description": "Small and fast debounce function",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc",
+		"test": "vitest run",
+		"test:watch": "vitest --watch",
+		"test:coverage": "vitest run --coverage",
+		"prettier:check": "prettier --check .",
+		"prettier:write": "prettier --write .",
+		"elint:check": "eslint .",
+		"elint:fix": "eslint --fix .",
+		"format": "prettier --write . && eslint --fix .",
+		"type-check": "tsc --noEmit",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"debounce",
+		"debouncing",
+		"function",
+		"throttle",
+		"invoke",
+		"limit",
+		"limited",
+		"interval",
+		"rate",
+		"batch",
+		"rate-limit",
+		"async",
+		"sync",
+		"typescript"
+	],
+	"author": "Atif C <atifcdev@gmail.com>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/atif-c/debounce-ts.git"
+	},
+	"bugs": {
+		"url": "https://github.com/atif-c/debounce-ts/issues"
+	},
+	"homepage": "https://github.com/atif-c/debounce-ts#readme",
+	"devDependencies": {
+		"@eslint/js": "^9.18.0",
+		"@vitest/coverage-v8": "^2.1.8",
+		"eslint": "^9.18.0",
+		"prettier": "^3.4.2",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.19.1",
+		"vitest": "^2.1.8"
+	}
+}