prevent multiple identical compilations via watch startTime

.editorconfig

@@ -8,6 +8,6 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[.md]
+[*.md]
 insert_final_newline = false
 trim_trailing_whitespace = false

README.md

@@ -64,15 +64,15 @@ _Note: The `publicPath` property is required, whereas all other options are opti
 
 ### headers
 
-Type: `Object`
+Type: `Object`  
 Default: `undefined`
 
 This property allows a user to pass custom HTTP headers on each request. eg.
 `{ "X-Custom-Header": "yes" }`
 
 ### index
 
-Type: `String`
+Type: `String`  
 Default: `undefined`
 
 "index.html",
@@ -82,21 +82,21 @@ Default: `undefined`
 
 ### lazy
 
-Type: `Boolean`
+Type: `Boolean`  
 Default: `undefined`
 
 This option instructs the module to operate in 'lazy' mode, meaning that it won't
 recompile when files change, but rather on each request.
 
 ### logger
 
-Type: `Object`
+Type: `Object`  
 Default: [`webpack-log`](https://github.com/webpack-contrib/webpack-log/blob/master/index.js)
 
 In the rare event that a user would like to provide a custom logging interface,
 this property allows the user to assign one. The module leverages
 [`webpack-log`](https://github.com/webpack-contrib/webpack-log#readme)
-for creating the [`loglevelnext`](https://github.com/shellscape/loglevelnext#readme) 
+for creating the [`loglevelnext`](https://github.com/shellscape/loglevelnext#readme)
 logging management by default. Any custom logger must adhere to the same
 exports for compatibility. Specifically, all custom loggers must have the
 following exported methods at a minimum:
@@ -111,7 +111,7 @@ Please see the documentation for `loglevel` for more information.
 
 ### logLevel
 
-Type: `String`
+Type: `String`  
 Default: `'info'`
 
 This property defines the level of messages that the module will log. Valid levels
@@ -131,15 +131,15 @@ for logging management, and more information can be found on its page.
 
 ### logTime
 
-Type: `Boolean`
+Type: `Boolean`  
 Default: `false`
 
 If `true` the log output of the module will be prefixed by a timestamp in the
 `HH:mm:ss` format.
 
 ### mimeTypes
 
-Type: `Object`
+Type: `Object`  
 Default: `null`
 
 This property allows a user to register custom mime types or extension mappings.
@@ -148,15 +148,15 @@ eg. `{ 'text/html': [ 'phtml' ] }`. Please see the documentation for
 
 ### publicPath
 
-Type: `String`
+Type: `String`  
 _Required_
 
 The public path that the middleware is bound to. _Best Practice: use the same
 `publicPath` defined in your webpack config._
 
 ### reporter
 
-Type: `Object`
+Type: `Object`  
 Default: `undefined`
 
 Allows users to provide a custom reporter to handle logging within the module.
@@ -165,23 +165,39 @@ for an example.
 
 ### serverSideRender
 
-Type: `Boolean`
+Type: `Boolean`  
 Default: `undefined`
 
 Instructs the module to enable or disable the server-side rendering mode. Please
 see [Server-Side Rendering](#server-side-rendering) for more information.
 
 ### stats
-Type: `Object`
+
+Type: `Object`  
 Default: `{ context: process.cwd() }`
 
 Options for formatting statistics displayed during and after compile. For more
 information and property details, please see the
 [webpack documentation](https://webpack.js.org/configuration/stats/#stats).
 
+### watchOffset
+
+Type: `Number`  
+Default: `11000`
+
+Watching (by means of `lazy: false`) will frequently cause multiple compilations
+as the bundle changes during compilation. This is due in part to cross-platform
+differences in file watchers, so that webpack doesn't loose file changes when
+watched files change rapidly. Since that scenario is more an edge case than not,
+this option serves as a means to prevent multiple needless, identical compilations
+by advancing start-time of a watcher by a number of seconds, which keeps generated
+files from triggering the watch cycle.
+
+_To disable this prevention, set this option to a value of `0`._
+
 ### watchOptions
 
-Type: `Object`
+Type: `Object`  
 Default: `{ aggregateTimeout: 200 }`
 
 The module accepts an `Object` containing options for file watching, which is

index.js

@@ -18,6 +18,7 @@ const defaults = {
     colors: true,
     context: process.cwd()
   },
+  watchOffset: 11000,
   watchOptions: {
     aggregateTimeout: 200
   }

lib/context.js

@@ -94,10 +94,27 @@ module.exports = function ctx(compiler, options) {
   }
 
   context.rebuild = rebuild;
-  context.compiler.plugin('done', done);
   context.compiler.plugin('invalid', invalid);
-  context.compiler.plugin('watch-run', invalid);
   context.compiler.plugin('run', invalid);
 
+  context.compiler.plugin('done', (stats) => {
+    // clean up the time offset
+    if (options.watchOffset > 0) {
+      stats.startTime -= options.watchOffset;
+    }
+
+    done(stats);
+  });
+
+  context.compiler.plugin('watch-run', (watcher, callback) => {
+    // apply a fix for compiler.watch, if watchOffset is greater than 0:
+    //   ff0000-ad-tech/wp-plugin-watch-offset
+    // offset start-time
+    if (options.watchOffset > 0) {
+      watcher.startTime += options.watchOffset;
+    }
+    invalid(watcher, callback);
+  });
+
   return context;
 };