debounce-throttle-utility 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# Debounce & Throttle Utility [(Git)](https://github.com/paradoxial-composition/debounce-throttle-utility)
+
+A lightweight utility for debouncing and throttling functions, optimized for performance. Ideal for handling events like scrolling, resizing, or input changes in web apps.
+
+## Installation
+
+```bash
+npm install debounce-throttle-utility
+```
+
+## Usage
+
+### Debounce
+
+```javascript
+    const { debounce } = require('debounce-throttle-utility');
+
+    const debouncedFunction = debounce(() => {
+        console.log('Debounced!');
+    }, 300);
+
+    debouncedFunction(); // Will execute after 300ms of no calls
+```
+
+### Throttle
+
+```javascript
+    const { throttle } = require('debounce-throttle-utility');
+
+    const throttledFunction = throttle(() => {
+        console.log('Throttled!');
+    }, 500);
+
+    throttledFunction(); // Will execute only once every 500ms
+```
+
+## Key Features
+
+### Simple API for Debounce and Throttle
+
+- The utility offers straightforward methods for applying debounce and throttle logic to any function.
+
+- Example:
+
+```javascript
+    const debouncedFunction = debounce(myFunction, 300);
+    const throttledFunction = throttle(myFunction, 100);
+```
+
+### Customizable Delay and Options
+
+- Developers can specify the delay time (in milliseconds) for both debounce and throttle.
+- For debounce, additional options include leading and trailing flags to determine whether the function should execute at the start, end, or both ends of the delay period.
+- Example:
+  
+```javascript
+const leadingDebounce = debounce(myFunction, 300, { leading: true });
+const trailingDebounce = debounce(myFunction, 300, { trailing: true });
+```
+
+### Zero Dependencies
+
+The utility is self-contained and does not rely on external libraries, making it lightweight and easy to integrate into any project.
+
+## Contributing
+
+Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+MIT.

package/index.js

@@ -0,0 +1,52 @@
+// index.js
+
+/**
+ * Debounce function
+ * @param {Function} func - The function to debounce
+ * @param {number} wait - Delay in milliseconds
+ * @param {Object} options - Optional configuration
+ * @returns {Function} - Debounced function
+ */
+function debounce(func, wait, options = {}) {
+    let timeout;
+    const { leading = false, trailing = true } = options;
+
+    return function(...args) {
+        const context = this;
+        clearTimeout(timeout);
+
+        if (leading && !timeout) {
+            func.apply(context, args);
+        }
+
+        timeout = setTimeout(() => {
+            if (trailing) {
+                func.apply(context, args);
+            }
+        }, wait);
+    };
+}
+
+/**
+ * Throttle function
+ * @param {Function} func - The function to throttle
+ * @param {number} limit - Interval in milliseconds
+ * @returns {Function} - Throttled function
+ */
+function throttle(func, limit) {
+    let inThrottle;
+
+    return function(...args) {
+        const context = this;
+        if (!inThrottle) {
+            func.apply(context, args);
+            inThrottle = true;
+            setTimeout(() => (inThrottle = false), limit);
+        }
+    };
+}
+
+module.exports = {
+    debounce,
+    throttle,
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "debounce-throttle-utility",
+  "version": "1.0.0",
+  "description": "A lightweight utility for debouncing and throttling functions, optimized for performance.",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paradoxial-composition/debounce-throttle-utility.git"
+  },
+  "keywords": ["debounce", "throttle", "utility", "performance", "scroll", "input", "resize"],
+  "author": "elbani.othman@gmail.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/paradoxial-composition/debounce-throttle-utility/issues"
+  },
+  "homepage": "https://github.com/paradoxial-composition/debounce-throttle-utility#readme",
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/test.spec.js

@@ -0,0 +1,47 @@
+// test.js
+
+const { debounce, throttle } = require('./index');
+
+describe('Debounce', () => {
+    it('should delay execution', async () => {
+        let count = 0;
+        const debounced = debounce(() => {
+            count++;
+        }, 100);
+
+        debounced();
+        debounced();
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        expect(count).toBe(1); // Should execute only once
+    });
+});
+
+describe('Throttle', () => {
+    it('should limit execution', async () => {
+        let count = 0;
+        const throttled = throttle(() => {
+            count++;
+        }, 100);
+
+        throttled();
+        throttled();
+
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        expect(count).toBe(1); // Should execute only once within 100ms
+    });
+
+    it('should be executed only twice in a 500ms interval ', async () => {
+        let count = 0;
+        const throttled = throttle(() => {
+            count++;
+        }, 100);
+
+        throttled();
+        throttled();
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        throttled();
+
+        expect(count).toBe(2);
+    });
+});