Add .trigger() (#41)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: olafurw

index.d.ts

@@ -3,9 +3,13 @@ type AnyFunction = (...arguments_: readonly any[]) => unknown;
 /**
 Creates a debounced function that delays execution until `wait` milliseconds have passed since its last invocation.
 
-Set the `immediate` option to `true` to invoke the function immediately at the start of the `wait` interval, preventing issues such as double-clicks on a button.
+Set the `immediate` option to `true` to execute the function immediately at the start of the `wait` interval, preventing issues such as double-clicks on a button.
 
-The returned function has a `.clear()` method to cancel scheduled executions, and a `.flush()` method for immediate execution and resetting the timer for future calls.
+The returned function has the following methods:
+
+- `.clear()` cancels any scheduled executions.
+- `.flush()` if an execution is scheduled then it will be immediately executed and the timer will be cleared.
+- `.trigger()` executes the function immediately and clears the timer if it was previously set.
 */
 declare function debounce<F extends AnyFunction>(
 	function_: F,
@@ -18,6 +22,7 @@ declare namespace debounce {
 		(...arguments_: Parameters<F>): ReturnType<F> | undefined;
 		clear(): void;
 		flush(): void;
+		trigger(): void;
 	};
 }
 

index.js

@@ -16,6 +16,15 @@ function debounce(function_, wait = 100, options = {}) {
 	let timestamp;
 	let result;
 
+	function run() {
+		const callContext = storedContext;
+		const callArguments = storedArguments;
+		storedContext = undefined;
+		storedArguments = undefined;
+		result = function_.apply(callContext, callArguments);
+		return result;
+	}
+
 	function later() {
 		const last = Date.now() - timestamp;
 
@@ -25,11 +34,7 @@ function debounce(function_, wait = 100, options = {}) {
 			timeoutId = undefined;
 
 			if (!immediate) {
-				const callContext = storedContext;
-				const callArguments = storedArguments;
-				storedContext = undefined;
-				storedArguments = undefined;
-				result = function_.apply(callContext, callArguments);
+				result = run();
 			}
 		}
 	}
@@ -50,11 +55,7 @@ function debounce(function_, wait = 100, options = {}) {
 		}
 
 		if (callNow) {
-			const callContext = storedContext;
-			const callArguments = storedArguments;
-			storedContext = undefined;
-			storedArguments = undefined;
-			result = function_.apply(callContext, callArguments);
+			result = run();
 		}
 
 		return result;
@@ -74,14 +75,13 @@ function debounce(function_, wait = 100, options = {}) {
 			return;
 		}
 
-		const callContext = storedContext;
-		const callArguments = storedArguments;
-		storedContext = undefined;
-		storedArguments = undefined;
-		result = function_.apply(callContext, callArguments);
+		debounced.trigger();
+	};
 
-		clearTimeout(timeoutId);
-		timeoutId = undefined;
+	debounced.trigger = () => {
+		result = run();
+
+		debounced.clear();
 	};
 
 	return debounced;

readme.md

@@ -29,21 +29,31 @@ To later clear the timer and cancel currently scheduled executions:
 window.onresize.clear();
 ```
 
-To execute any pending invocations and reset the timer:
+To execute immediately only if you have scheduled invocations and reset the timer:
 
 ```js
 window.onresize.flush();
 ```
 
+To execute immediately and reset the timer if it was previously set:
+
+```js
+window.onresize.trigger();
+```
+
 ## API
 
 ### debounce(fn, wait, options?)
 
 Creates a debounced function that delays execution until `wait` milliseconds have passed since its last invocation.
 
-Set the `immediate` option to `true` to invoke the function immediately at the start of the `wait` interval, preventing issues such as double-clicks on a button.
+Set the `immediate` option to `true` to execute the function immediately at the start of the `wait` interval, preventing issues such as double-clicks on a button.
+
+The returned function has the following methods:
 
-The returned function has a `.clear()` method to cancel scheduled executions, and a `.flush()` method for immediate execution and resetting the timer for future calls.
+- `.clear()` cancels any scheduled executions.
+- `.flush()` if an execution is scheduled then it will be immediately executed and the timer will be cleared.
+- `.trigger()` executes the function immediately and clears the timer if it was previously set.
 
 ## Related
 

test.js

@@ -397,3 +397,38 @@ test('calling flush method without any scheduled execution', async () => {
 
 	assert.strictEqual(callback.callCount, 0, 'Callback should not be executed if flush is called without any scheduled execution');
 });
+
+test('calling the trigger function should run it immediately', async () => {
+	const clock = sinon.useFakeTimers();
+	const callback = sinon.spy();
+	const fn = debounce(callback, 100);
+
+	fn();
+	fn.trigger();
+
+	assert.strictEqual(callback.callCount, 1, 'Callback should be called once when using trigger method');
+
+	clock.tick(100);
+
+	assert.strictEqual(callback.callCount, 1, 'Callback should stay at one call after timeout');
+
+	clock.restore();
+});
+
+test('calling the trigger should not affect future function calls', async () => {
+	const clock = sinon.useFakeTimers();
+	const callback = sinon.spy();
+	const fn = debounce(callback, 100);
+
+	fn();
+	fn.trigger();
+	fn();
+
+	assert.strictEqual(callback.callCount, 1, 'Callback should be called once when using trigger method');
+
+	clock.tick(100);
+
+	assert.strictEqual(callback.callCount, 2, 'Callback should total two calls after timeout');
+
+	clock.restore();
+});