Minor fixes on documentation (proposal)

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-#Contributing to Browsersync
+# Contributing to Browsersync
 
 We'd love for you to contribute to Browsersync and help make it even better than it is
 today! Here are the guidelines we'd like you to follow:
@@ -35,8 +35,7 @@ then it's very likely to fall to the bottom of the heap. Help us out by providin
 * Provide a reduced test case. "Browsersync is not working with my app" is far less helpful than "Here's a example project showing the problem".
 An example project might contain a single `index.html` file with some JS/CSS from CDNs & a short description of the issue. If we
  can just pull a repo/gist and see the problem for ourselves, your issue will jump straight to the top of the stack.
-* Screencast or GIF - not always appropriate, but can be very helpful where possible. (non-issue related gifs are always welcome, we'll often
-respond with something from giphy :p)
+* Screencast or GIF - not always appropriate, but can be very helpful where possible. (non-issue related gifs are always welcome, we'll often respond with something from giphy :p)
 
 ## <a name="feature"></a> Want a Feature?
 You can request a new feature by submitting an issue to our [Github Issues](https://github.com/BrowserSync/browser-sync/issues) page.
@@ -49,9 +48,9 @@ Head over to the [Browsersync Website Repo](https://github.com/BrowserSync/brows
 Pull requests should always be branched off the main **Master** branch. (There's no guarantee that what lives on the develop
 branch will ever make it back to master, I do a **lot** of experimentation).
 
-Never commit directly to the master branch, instead create a new branch and submit a PR. This applies to users who have write access also.
+**Never** commit directly to the master branch, instead create a new branch and submit a PR. This applies to users who have write access also.
 
-Note: If your first PR is merged, you'll get write access to all Browsersync repos.
+**Note:** If your first PR is merged, you'll get write access to all Browsersync repos.
 
 ## <a name="rules"></a> Coding Advice
 To ensure consistency throughout the source code, keep these rules in mind as you are working. 
@@ -66,5 +65,4 @@ To ensure consistency throughout the source code, keep these rules in mind as yo
 If *you* have particular experience though, then feel free to rip my code apart and tell me a better way to do something - I'll be extremely grateful (as will the growing number of users!).
 
 ## <a name="thanks"></a> Thank you!
-If you contribute to Browsersync, or any other Open Source project, you're awesome! This project has been vastly improved
- by community input & contributions and we look forward to continuing that trend.
+If you contribute to Browsersync, or any other Open Source project, you're awesome! This project has been vastly improved by community input & contributions and we look forward to continuing that trend.

appveyor.yml

@@ -10,7 +10,6 @@ environment:
   matrix:
     - nodejs_version: '6'
     - nodejs_version: '4'
-    - nodejs_version: '0'
 
 install:
   - ps: Install-Product node $env:nodejs_version

gulpfile.js

@@ -1,21 +1,36 @@
 "use strict";
 
 var gulp = require("gulp");
-var contribs = require("gulp-contribs");
-var conventionalChangelog = require("gulp-conventional-changelog");
+var bs = require("./").create();
+var Rx = require("rx");
+// var contribs = require("gulp-contribs");
+// var conventionalChangelog = require("gulp-conventional-changelog");
+//
+// gulp.task("contribs", function () {
+//     gulp.src("README.md")
+//         .pipe(contribs())
+//         .pipe(gulp.dest(""));
+// });
+//
+// gulp.task("changelog", function () {
+//     return gulp.src("CHANGELOG.md", {
+//         buffer: false
+//     })
+//         .pipe(conventionalChangelog({
+//             preset: "angular"
+//         }))
+//         .pipe(gulp.dest("./"));
+// });
 
-gulp.task("contribs", function () {
-    gulp.src("README.md")
-        .pipe(contribs())
-        .pipe(gulp.dest(""));
-});
+gulp.task("dev", function() {
+
+    bs.init({
+        server: "test/fixtures",
+        open: false,
+        reloadDelay: 1000,
+        reloadDebounce: 1000
+    });
 
-gulp.task("changelog", function () {
-    return gulp.src("CHANGELOG.md", {
-        buffer: false
-    })
-        .pipe(conventionalChangelog({
-            preset: "angular"
-        }))
-        .pipe(gulp.dest("./"));
+    gulp.src("lib/**")
+        .pipe(bs.stream())
 });

index.js

@@ -102,6 +102,10 @@ module.exports.reload  = noop("reload");
  *
  * @method stream
  * @param {Object} [opts] Configuration for the stream method
+ * @param {Object} [opts.match] Resulting files to reload. The path is from the
+ * root of the site (not the root of your project).  You can use '**' to recurse
+ * directories.
+ * @param {Object} [opts.once] Only reload on the first changed file in teh stream.
  * @since 2.6.0
  * @returns {*}
  */

lib/browser-sync.js

@@ -633,48 +633,6 @@ BrowserSync.prototype.resetMiddlewareStack = function () {
     bs.app.stack = middlewares;
 };
 
-/**
- * Handle Browser Reloads
- */
-BrowserSync.prototype.doBrowserReload = function () {
-
-    var bs = this;
-
-    if (bs._browserReload) {
-        return;
-    }
-    bs._browserReload = setTimeout(function () {
-        bs.io.sockets.emit("browser:reload");
-        clearTimeout(bs._browserReload);
-        bs._browserReload = false;
-    }, bs.options.get("reloadDelay"));
-};
-
-/**
- * Handle a queue of reloads
- * @param {Object} data
- */
-BrowserSync.prototype.doFileReload = function (data) {
-
-    var bs = this;
-
-    var willReload = utils.willCauseReload(
-        [data.path],
-        bs.options.get("injectFileTypes").toJS()
-    );
-
-    /**
-     * If the current item will cause the browser
-     * to reload, fire the correct
-     */
-    if (willReload) {
-        bs.io.sockets.emit("browser:reload");
-        return;
-    }
-
-    bs.io.sockets.emit("file:reload", data);
-};
-
 /**
  * @param fn
  */

lib/cli/opts.start.json

@@ -92,6 +92,10 @@
     "type": "number",
     "desc": "Specify a port for the UI to use"
   },
+  "watchEvents": {
+    "type": "array",
+    "desc": "Specify which file events to respond to"
+  },
   "no-notify": {
     "desc": "Disable the notify element in browsers"
   },

lib/default-config.js

@@ -31,6 +31,16 @@ module.exports = {
      */
     files: false,
 
+    /**
+     * Specify which file events to respond to.
+     * Available events: `add`, `change`, `unlink`, `addDir`, `unlinkDir`
+     * @property watchEvents
+     * @type Array
+     * @default ["change"]
+     * @since 2.18.8
+     */
+    watchEvents: ["change"],
+
     /**
      * File watching options that get passed along to [Chokidar](https://github.com/paulmillr/chokidar).
      * Check their docs for available options
@@ -40,11 +50,11 @@ module.exports = {
      * @since 2.6.0
      */
     watchOptions: {
+        ignoreInitial: true
         /*
          persistent: true,
 
          ignored: '*.txt',
-         ignoreInitial: false,
          followSymlinks: true,
          cwd: '.',
 
@@ -130,13 +140,14 @@ module.exports = {
      * @type string
      * @default undefined
      * @since 2.18.0
-     */    
+     */
 
     /**
      * Clicks, Scrolls & Form inputs on any device will be mirrored to all others.
      * @property ghostMode
      * @param {Boolean} [clicks=true]
      * @param {Boolean} [scroll=true]
+     * @param {Boolean} [location=true]
      * @param {Boolean} [forms=true]
      * @param {Boolean} [forms.submit=true]
      * @param {Boolean} [forms.inputs=true]
@@ -146,6 +157,7 @@ module.exports = {
     ghostMode: {
         clicks: true,
         scroll: true,
+        location: true,
         forms: {
             submit: true,
             inputs: true,
@@ -166,10 +178,10 @@ module.exports = {
      * own project based on Browsersync
      * @property logPrefix
      * @type String
-     * @default BS
+     * @default Browsersync
      * @since 1.5.1
      */
-    logPrefix: "BS",
+    logPrefix: "Browsersync",
 
     /**
      * @property logConnections
@@ -245,7 +257,7 @@ module.exports = {
 
     /**
      * Decide which URL to open automatically when Browsersync starts. Defaults to "local" if none set.
-     * Can be true, `local`, `external`, `ui`, `ui-external`, `tunnel` or `false`
+     * Can be `true`, `local`, `external`, `ui`, `ui-external`, `tunnel` or `false`
      * @property open
      * @type Boolean|String
      * @default true
@@ -501,7 +513,7 @@ module.exports = {
         "js":   "script"
     },
 
-    injectFileTypes: ["css", "png", "jpg", "jpeg", "svg", "gif", "webp"],
+    injectFileTypes: ["css", "png", "jpg", "jpeg", "svg", "gif", "webp", "map"],
     excludedFileTypes: [
         "js",
         "css",

lib/file-event-handler.js

@@ -0,0 +1,120 @@
+var utils = require("./utils");
+
+/**
+ * Apply the operators that apply to the 'file:changed' event
+ * @param {Rx.Observable} subject
+ * @param options
+ * @return {Rx.Observable<{type: string, files: Array<any>}>}
+ */
+function fileChanges(subject, options) {
+    var operators = [
+        {
+            option: "reloadThrottle",
+            fnName: "throttle"
+        },
+        {
+            option: "reloadDelay",
+            fnName: "delay"
+        }
+    ];
+
+    var scheduler = options.getIn(["debug", "scheduler"]);
+
+    /**
+     * if the 'reloadDebounce' option was provided, create
+     * a stream buffered/debounced stream of events
+     */
+    var initial = (function() {
+        if (options.get("reloadDebounce") > 0) {
+            return getAggregatedDebouncedStream(subject, options, scheduler);
+        }
+        return subject;
+    })();
+
+    return applyOperators(operators, initial, options, scheduler)
+        .map(function(xs) {
+
+            var items = [].concat(xs);
+            var paths = items.map(function (x) { return x.path });
+
+            if (utils.willCauseReload(paths, options.get("injectFileTypes").toJS())) {
+                return {
+                    type: "reload",
+                    files: items
+                }
+            }
+            return {
+                type: "inject",
+                files: items
+            }
+        });
+}
+module.exports.fileChanges = fileChanges;
+
+/**
+ * Apply the operators that apply to the 'browser:reload' event
+ * @param {Rx.Observable} subject
+ * @param options
+ * @returns {Rx.Observable}
+ */
+function applyReloadOperators (subject, options) {
+    var operators = [
+        {
+            option: "reloadDebounce",
+            fnName: "debounce"
+        },
+        {
+            option: "reloadThrottle",
+            fnName: "throttle"
+        },
+        {
+            option: "reloadDelay",
+            fnName: "delay"
+        }
+    ];
+
+    return applyOperators(operators, subject, options, options.getIn(["debug", "scheduler"]));
+}
+module.exports.applyReloadOperators = applyReloadOperators;
+
+/**
+ * @param items
+ * @param subject
+ * @param options
+ * @param scheduler
+ */
+function applyOperators (items, subject, options, scheduler) {
+    return items.reduce(function(subject, item) {
+        var value = options.get(item.option);
+        if (value > 0) {
+            return subject[item.fnName].call(subject, value, scheduler);
+        }
+        return subject;
+    }, subject);
+}
+
+/**
+ * @param subject
+ * @param options
+ * @param scheduler
+ */
+function getAggregatedDebouncedStream (subject, options, scheduler) {
+    return subject
+        .filter(function(x) { return options.get("watchEvents").indexOf(x.event) > -1 })
+        .buffer(subject.debounce(options.get("reloadDebounce"), scheduler))
+        .map(function(buffered) {
+            return buffered.reduce(function (acc, item) {
+                if (!acc[item.path]) acc[item.path] = item;
+                if (acc[item.path]) acc[item.path] = item;
+                return acc;
+            }, {});
+        })
+        .map(function(group) {
+            return Object
+                .keys(group)
+                .map(function(key) {
+                    return group[key];
+                });
+        })
+        .filter(function (x) { return x.length })
+}

lib/file-utils.js

@@ -21,7 +21,7 @@ var fileUtils = {
          * `add` `unlink` etc etc so we need to check for that and only
          * respond to 'change', for now.
          */
-        if (data.event === "change") {
+        if (bs.options.get("watchEvents").indexOf(data.event) > -1) {
             if (!bs.paused && data.namespace === "core") {
                 bs.events.emit("file:reload", fileUtils.getFileInfo(data, bs.options));
             }
@@ -41,6 +41,7 @@ var fileUtils = {
             ext:           data.ext,
             path:          data.path,
             basename:      data.basename,
+            event:         data.event,
             type:          "inject"
         };