fs: add 'close' event to FSWatcher

PR-URL: #19900
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

Author: aleclarson

doc/api/fs.md

@@ -329,6 +329,13 @@ added: v0.5.8
 
 Emitted when an error occurs while watching the file.
 
+### Event: 'close'
+<!-- YAML
+added: REPLACEME
+-->
+
+Emitted when the watcher stops watching for changes.
+
 ### watcher.close()
 <!-- YAML
 added: v0.5.8

lib/fs.js

@@ -1387,8 +1387,13 @@ FSWatcher.prototype.close = function() {
     return;
   }
   this._handle.close();
+  process.nextTick(emitCloseNT, this);
 };
 
+function emitCloseNT(self) {
+  self.emit('close');
+}
+
 fs.watch = function(filename, options, listener) {
   if (typeof options === 'function') {
     listener = options;

test/parallel/test-fs-watch.js

@@ -54,6 +54,7 @@ for (const testCase of cases) {
     }
     assert.fail(err);
   });
+  watcher.on('close', common.mustCall());
   watcher.on('change', common.mustCall(function(eventType, argFilename) {
     if (interval) {
       clearInterval(interval);