Run debounce callback if browser tab is closed

A common issue with debounced API calls is that when the user closes the
browser tab, the debounced function may not have run yet. This is a
frequent cause of data loss. The debounce implementation now prevents
this issue by running the trailing debounce immediately if the tab is
closed prior to the trailing timeout.

The code detects whether it's running in an environment with access to
`document.addEventListener()`. In runtimes where this function is
unavailable (e.g. Node.js) the new functionality is ignored since would
not be relevant in that context.

Author: h

docs/modules/debounce.html

@@ -866,6 +866,15 @@ <h1>debounce.js</h1>
 parameter. If <code>immediate</code> is passed, the argument function will be
 triggered at the beginning of the sequence instead of at the end.</p>
 
+              <p>A common issue with other debounce libraries is that when the user closes
+the browser tab, the debounced function may not have run yet. This is a
+frequent cause of data loss. This implementation prevents that problem by
+running the debounced function immediately if the tab is closed prior to the
+timeout. (Not applicable to Node.js or other headless runtimes.)</p>
+
+              <p>When making debounced API calls it is recommended to use `fetch()` with the
+`keepalive` parameter. This allows the HTTP request to finish in the
+background after the user closes the browser tab.</p>
             </div>
 
             <div class="content"><div class='highlight'><pre><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">function</span> <span class="hljs-title function_">debounce</span>(<span class="hljs-params">func, wait, immediate</span>) {

docs/underscore-esm.html

@@ -2933,6 +2933,14 @@ <h1>underscore-esm.js</h1>
 function is triggered. The end of a sequence is defined by the <code>wait</code>
 parameter. If <code>immediate</code> is passed, the argument function will be
 triggered at the beginning of the sequence instead of at the end.</p>
+              <p>A common issue with other debounce libraries is that when the user closes
+the browser tab, the debounced function may not have run yet. This is a
+frequent cause of data loss. This implementation prevents that problem by
+running the debounced function immediately if the tab is closed prior to the
+timeout. (Not applicable to Node.js or other headless runtimes.)</p>
+              <p>When making debounced API calls it is recommended to use `fetch()` with the
+`keepalive` parameter. This allows the HTTP request to finish in the
+background after the user closes the browser tab.</p>
 
             </div>
 

modules/debounce.js

@@ -5,18 +5,35 @@ import now from './now.js';
 // function is triggered. The end of a sequence is defined by the `wait`
 // parameter. If `immediate` is passed, the argument function will be
 // triggered at the beginning of the sequence instead of at the end.
+//
+// A common issue with other debounce libraries is that when the user closes
+// the browser tab, the debounced function may not have run yet. This is a
+// frequent cause of data loss. This implementation prevents that problem by
+// running the debounced function immediately if the tab is closed prior to the
+// timeout. (Not applicable to Node.js or other headless runtimes.)
+//
+// When making debounced API calls it is recommended to use `fetch()` with the
+// `keepalive` parameter. This allows the HTTP request to finish in the
+// background after the user closes the browser tab.
 export default function debounce(func, wait, immediate) {
   var timeout, previous, args, result, context;
 
   var later = function() {
     var passed = now() - previous;
-    if (wait > passed) {
-      timeout = setTimeout(later, wait - passed);
-    } else {
+    var pageHidden = global.document && global.document.visibilityState === 'hidden';
+    clearTimeout(timeout);
+    if (wait <= passed || (!immediate && pageHidden)) {
+      if (!immediate && global.document && global.document.removeEventListener) {
+        global.document.removeEventListener(
+          'visibilityChange',
+          later, { capture: true });
+      }
       timeout = null;
       if (!immediate) result = func.apply(context, args);
       // This check is needed because `func` can recursively invoke `debounced`.
       if (!timeout) args = context = null;
+    } else {
+      timeout = setTimeout(later, wait - passed);
     }
   };
 
@@ -26,6 +43,11 @@ export default function debounce(func, wait, immediate) {
     previous = now();
     if (!timeout) {
       timeout = setTimeout(later, wait);
+      if (!immediate && global.document && global.document.addEventListener) {
+        global.document.addEventListener(
+          'visibilityChange',
+          later, { capture: true, passive: true });
+      }
       if (immediate) result = func.apply(context, args);
     }
     return result;

underscore-esm.js

@@ -1134,18 +1134,35 @@ function throttle(func, wait, options) {
 // function is triggered. The end of a sequence is defined by the `wait`
 // parameter. If `immediate` is passed, the argument function will be
 // triggered at the beginning of the sequence instead of at the end.
+//
+// A common issue with other debounce libraries is that when the user closes
+// the browser tab, the debounced function may not have run yet. This is a
+// frequent cause of data loss. This implementation prevents that problem by
+// running the debounced function immediately if the tab is closed prior to the
+// timeout. (Not applicable to Node.js or other headless runtimes.)
+//
+// When making debounced API calls it is recommended to use `fetch()` with the
+// `keepalive` parameter. This allows the HTTP request to finish in the
+// background after the user closes the browser tab.
 function debounce(func, wait, immediate) {
   var timeout, previous, args, result, context;
 
   var later = function() {
     var passed = now() - previous;
-    if (wait > passed) {
-      timeout = setTimeout(later, wait - passed);
-    } else {
+    var pageHidden = global.document && global.document.visibilityState === 'hidden';
+    clearTimeout(timeout);
+    if (wait <= passed || (!immediate && pageHidden)) {
+      if (!immediate && global.document && global.document.removeEventListener) {
+        global.document.removeEventListener(
+          'visibilityChange',
+          later, { capture: true });
+      }
       timeout = null;
       if (!immediate) result = func.apply(context, args);
       // This check is needed because `func` can recursively invoke `debounced`.
       if (!timeout) args = context = null;
+    } else {
+      timeout = setTimeout(later, wait - passed);
     }
   };
 
@@ -1155,6 +1172,11 @@ function debounce(func, wait, immediate) {
     previous = now();
     if (!timeout) {
       timeout = setTimeout(later, wait);
+      if (!immediate && global.document && global.document.addEventListener) {
+        global.document.addEventListener(
+          'visibilityChange',
+          later, { capture: true, passive: true });
+      }
       if (immediate) result = func.apply(context, args);
     }
     return result;