Add maxWait option

index.d.ts

@@ -1,12 +1,23 @@
 declare namespace debounceFn {
 	interface Options {
 		/**
-		Time to wait until the `input` function is called.
+		Time in milliseconds to wait until the `input` function is called.
 
 		@default 0
 		*/
 		readonly wait?: number;
 
+		/**
+		Maximum time in milliseconds to wait between calls to the `input` function.
+		Disabled when 0
+
+		This can be used to limit the number of calls handled in a constant stream.
+		For example, a media player sending updates every few milliseconds but wants to be handled only once a second.
+
+		@default 0
+		*/
+		readonly maxWait?: number;
+
 		/**
 		Trigger the function on the leading edge of the `wait` interval.
 

index.js

@@ -8,6 +8,7 @@ module.exports = (inputFunction, options = {}) => {
 
 	const {
 		wait = 0,
+		maxWait = 0,
 		before = false,
 		after = true
 	} = options;
@@ -17,6 +18,7 @@ module.exports = (inputFunction, options = {}) => {
 	}
 
 	let timeout;
+	let maxTimeout;
 	let result;
 
 	const debouncedFunction = function (...arguments_) {
@@ -25,6 +27,24 @@ module.exports = (inputFunction, options = {}) => {
 		const later = () => {
 			timeout = undefined;
 
+			if (maxTimeout) {
+				clearTimeout(maxTimeout);
+				maxTimeout = undefined;
+			}
+
+			if (after) {
+				result = inputFunction.apply(context, arguments_);
+			}
+		};
+
+		const maxLater = () => {
+			maxTimeout = undefined;
+
+			if (timeout) {
+				clearTimeout(timeout);
+				timeout = undefined;
+			}
+
 			if (after) {
 				result = inputFunction.apply(context, arguments_);
 			}
@@ -34,6 +54,10 @@ module.exports = (inputFunction, options = {}) => {
 		clearTimeout(timeout);
 		timeout = setTimeout(later, wait);
 
+		if (maxWait > 0 && !maxTimeout) {
+			maxTimeout = setTimeout(maxLater, maxWait);
+		}
+
 		if (shouldCallNow) {
 			result = inputFunction.apply(context, arguments_);
 		}
@@ -48,6 +72,11 @@ module.exports = (inputFunction, options = {}) => {
 			clearTimeout(timeout);
 			timeout = undefined;
 		}
+
+		if (maxTimeout) {
+			clearTimeout(maxTimeout);
+			maxTimeout = undefined;
+		}
 	};
 
 	return debouncedFunction;

readme.md

@@ -43,6 +43,16 @@ Default: `0`
 
 Time to wait until the `input` function is called.
 
+##### maxWait
+
+Type: `number`\
+Default: `0` (disabled)
+
+Maximum time in milliseconds to wait between calls to the `input` function.
+
+This can be used to limit the number of calls handled in a constant stream.
+For example, a media player sending updates every few milliseconds but wants to be handled only once a second.
+
 ##### before
 
 Type: `boolean`\

test.js

@@ -142,3 +142,60 @@ test('.cancel() method', async t => {
 	t.is(debounced(3), undefined);
 	t.is(count, 0);
 });
+
+test('before:false after:true `maxWait` option', async t => {
+	let count = 0;
+
+	const debounced = debounceFn(value => {
+		count++;
+		return value;
+	}, {
+		wait: 40,
+		maxWait: 50,
+		after: true,
+		before: false
+	});
+
+	t.is(debounced(1), undefined);
+	await delay(30);
+	t.is(count, 0);
+
+	t.is(debounced(2), undefined);
+	await delay(30);
+	t.is(count, 1);
+
+	t.is(debounced(3), 1);
+
+	await delay(200);
+	t.is(count, 2);
+});
+
+test('before:true after:false `maxWait` option', async t => {
+	let count = 0;
+
+	const debounced = debounceFn(value => {
+		count++;
+		return value;
+	}, {
+		wait: 40,
+		maxWait: 50,
+		after: false,
+		before: true
+	});
+
+	t.is(debounced(1), 1);
+	t.is(count, 1);
+	await delay(30);
+
+	t.is(debounced(2), 1);
+	t.is(count, 1);
+	await delay(30);
+
+	t.is(debounced(3), 3);
+	t.is(count, 2);
+
+	await delay(50);
+
+	t.is(debounced(4), 4);
+	t.is(count, 3);
+});