fix(files): implement a more robust (correct) debounce, along with throttle & delay - re: #982 #1121

Author: shakyShane

lib/browser-sync.js

@@ -648,39 +648,21 @@ BrowserSync.prototype.doFileReload = function (data) {
 
     var bs = this;
 
-    bs._reloadQueue = bs._reloadQueue || [];
-    bs._reloadQueue.push(data);
-
-    if (bs._reloadTimer) {
-        return;
-    }
-
     var willReload = utils.willCauseReload(
-        bs._reloadQueue.map(function (item) { return item.path; }),
+        [data.path],
         bs.options.get("injectFileTypes").toJS()
     );
 
-    bs._reloadTimer = setTimeout(function () {
-
-        if (willReload) {
-            if (!bs._reloadDebounced) {
-                bs._reloadDebounced = setTimeout(function () {
-                    bs._reloadDebounced = false;
-                }, bs.options.get("reloadDebounce"));
-                bs.io.sockets.emit("browser:reload");
-            }
-        } else {
-            bs._reloadQueue.forEach(function (item) {
-                bs.io.sockets.emit("file:reload", item);
-            });
-        }
-
-        clearTimeout(bs._reloadTimer);
-
-        bs._reloadTimer = undefined;
-        bs._reloadQueue = [];
+    /**
+     * If the current item will cause the browser
+     * to reload, fire the correct 
+     */
+    if (willReload) {
+        bs.io.sockets.emit("browser:reload");
+        return;
+    }
 
-    }, bs.options.get("reloadDelay"));
+    bs.io.sockets.emit("file:reload", data);
 };
 
 /**

lib/default-config.js

@@ -326,15 +326,25 @@ module.exports = {
     reloadDelay: 0,
 
     /**
-     * Restrict the frequency in which browser:reload events
-     * can be emitted to connected clients
+     * Wait for a specified window of event-silence before
+     * sending any reload events.
      * @property reloadDebounce
      * @type Number
      * @default 0
      * @since 2.6.0
      */
     reloadDebounce: 0,
 
+    /**
+     * Emit only the first event during sequential time windows
+     * of a specified duration.
+     * @property reloadThrottle
+     * @type Number
+     * @default 0
+     * @since 2.13.0
+     */
+    reloadThrottle: 0,
+
     /**
      * User provided plugins
      * @property plugins

lib/file-watcher.js

@@ -1,6 +1,8 @@
 "use strict";
 
 var _ = require("../lodash.custom");
+var utils = require("./utils");
+var Rx = require("rx/dist/rx.all.js");
 
 /**
  * Plugin interface
@@ -10,6 +12,17 @@ module.exports.plugin = function (bs) {
 
     var options = bs.options;
     var emitter = bs.emitter;
+    var subject = new Rx.Subject();
+    var sub$    = getObservable(subject, bs.options);
+
+    var subscription = sub$.subscribe(function (value) {
+        emitter.emit("file:changed", value);
+    });
+
+    bs.registerCleanupTask(function () {
+        subscription.dispose();
+        subject.dispose();
+    });
 
     var defaultWatchOptions = options.get("watchOptions").toJS();
 
@@ -21,7 +34,7 @@ module.exports.plugin = function (bs) {
          * @param path
          */
         var fn = function (event, path) {
-            emitter.emit("file:changed", {
+            subject.onNext({
                 event: event,
                 path: path,
                 namespace: namespace
@@ -82,3 +95,38 @@ function watch (patterns, opts, cb) {
 }
 
 module.exports.watch = watch;
+
+/**
+ * Apply debounce, throttle or delay operators
+ * to the default stream of events
+ * @param subject
+ * @param options
+ * @returns {*|Observable.<T>}
+ */
+function getObservable(subject, options) {
+
+    var globalItems = [
+        {
+            option: "reloadDebounce",
+            fnName: "debounce"
+        },
+        {
+            option: "reloadThrottle",
+            fnName: "throttle"
+        },
+        {
+            option: "reloadDelay",
+            fnName: "delay"
+        }
+    ];
+
+    var scheduler = options.getIn(["debug", "scheduler"]);
+
+    return globalItems.reduce(function(subject, item) {
+        var value = options.get(item.option);
+        if (value > 0) {
+            return subject[item.fnName].call(subject, value, scheduler);
+        }
+        return subject;
+    }, subject);
+}

package.json

@@ -50,6 +50,7 @@
     "portscanner": "^1.0.0",
     "qs": "6.2.0",
     "resp-modifier": "6.0.1",
+    "rx": "4.1.0",
     "serve-index": "1.7.3",
     "serve-static": "1.10.2",
     "socket.io": "1.4.6",

test/specs/e2e/files/e2e.file.watching.js

@@ -4,105 +4,65 @@ var browserSync = require("../../../../");
 
 var path = require("path");
 var assert = require("chai").assert;
-
 var outpath = path.join(__dirname, "../../fixtures");
 
-describe("file-watching", function () {
-
-    describe("E2E Adding namespaced watchers", function () {
-
-        var instance, file;
-
-        before(function (done) {
+describe("file-watching (2)", function () {
 
-            browserSync.reset();
+    it("Watches files with no namespace", function (done) {
+        browserSync.reset();
 
-            file = path.join(outpath, "watch-func.txt");
-
-            var config = {
-                files:    file,
-                logLevel: "silent"
-            };
-
-            instance = browserSync(config, done).instance;
-        });
+        var file = path.join(outpath, "watch-func.txt");
 
-        after(function () {
-            instance.cleanup();
-        });
+        var config = {
+            files:    file,
+            logLevel: "silent"
+        };
 
-        it("Watches files with no namespace", function (done) {
+        browserSync(config, function (err, bs) {
 
-            assert.ok(instance.watchers.core.watchers);
-            assert.equal(instance.watchers.core.watchers.length, 1);
+            assert.ok(bs.watchers.core.watchers);
+            assert.equal(bs.watchers.core.watchers.length, 1);
+            bs.cleanup();
             done();
         });
     });
 
-    describe("E2E Adding namespaced watchers", function () {
-
-        var instance, file;
-
-        before(function (done) {
-
-            browserSync.reset();
+    it("Watches files when multi given", function (done) {
+        browserSync.reset();
 
-            file = path.join(outpath, "watch-func.txt");
-
-            var config = {
-                files:    "*.html",
-                logLevel: "silent"
-            };
-
-            instance = browserSync(config, done).instance;
-        });
+        var config = {
+            files:    "*.html",
+            logLevel: "silent"
+        };
 
-        after(function () {
-            instance.cleanup();
-        });
-
-        it("Watches files when multi given", function (done) {
-
-            assert.ok(instance.watchers.core.watchers);
-            assert.ok(instance.watchers.core.watchers[0]);
+        browserSync(config, function (err, bs) {
+            assert.ok(bs.watchers.core.watchers);
+            assert.ok(bs.watchers.core.watchers[0]);
+            bs.cleanup();
             done();
         });
     });
 
-    describe("E2E Adding namespaced watchers", function () {
-
-        var instance, file;
-
-        before(function (done) {
-
-            browserSync.reset();
-
-            file = path.join(outpath, "watch-func.txt");
+    it("Watches files when multi given + objs", function (done) {
+        browserSync.reset();
 
-            var config = {
-                files:    [
-                    "*.html",
-                    {
-                        match: "*.css",
-                        fn: function (event, file) {
-                            console.log(file);
-                        }
+        var config = {
+            files:    [
+                "*.html",
+                {
+                    match: "*.css",
+                    fn: function (event, file) {
+                        console.log(file);
                     }
-                ],
-                logLevel: "silent"
-            };
-
-            instance = browserSync(config, done).instance;
-        });
-
-        after(function () {
-            instance.cleanup();
-        });
-
-        it("Watches files when multi given + objs", function (done) {
-
-            assert.ok(instance.watchers.core.watchers);
-            assert.equal(instance.watchers.core.watchers.length, 2);
+                }
+            ],
+            logLevel: "silent"
+        };
+
+        browserSync(config, function (err, bs) {
+            assert.ok(bs.watchers.core.watchers);
+            assert.equal(bs.watchers.core.watchers.length, 2);
+            bs.cleanup();
             done();
         });
     });