From fe12cc07b3ef37148bce9765a506e20f21a5bd86 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 1 Feb 2021 15:53:36 -0800
Subject: [PATCH] fs: add fsPromises.watch()

An alternative to `fs.watch()` that returns an `AsyncIterator`

```js
const { watch } = require('fs/promises');

(async () => {

  const ac = new AbortController();
  const { signal } = ac;
  setTimeout(() => ac.abort(), 10000);

  const watcher = watch('file.txt', { signal });

  for await (const { eventType, filename } of watcher) {
    console.log(eventType, filename);
  }

})()
```

Signed-off-by: James M Snell <jasnell@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/37179
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/fs.md                           |  53 ++++++++++-
 lib/internal/fs/promises.js             |   2 +
 lib/internal/fs/watchers.js             | 119 +++++++++++++++++++++++-
 test/parallel/test-bootstrap-modules.js |   3 +
 test/parallel/test-fs-promises-watch.js | 116 +++++++++++++++++++++++
 5 files changed, 286 insertions(+), 7 deletions(-)
 create mode 100644 test/parallel/test-fs-promises-watch.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b37539960f32ac..2143679900651f 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1181,6 +1181,55 @@ The `atime` and `mtime` arguments follow these rules:
 * If the value can not be converted to a number, or is `NaN`, `Infinity` or
   `-Infinity`, an `Error` will be thrown.
 
+### `fsPromises.watch(filename[, options])`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `filename` {string|Buffer|URL}
+* `options` {string|Object}
+  * `persistent` {boolean} Indicates whether the process should continue to run
+    as long as files are being watched. **Default:** `true`.
+  * `recursive` {boolean} Indicates whether all subdirectories should be
+    watched, or only the current directory. This applies when a directory is
+    specified, and only on supported platforms (See [caveats][]). **Default:**
+    `false`.
+  * `encoding` {string} Specifies the character encoding to be used for the
+     filename passed to the listener. **Default:** `'utf8'`.
+  * `signal` {AbortSignal} An {AbortSignal} used to signal when the watcher
+    should stop.
+* Returns: {AsyncIterator} of objects with the properties:
+  * `eventType` {string} The type of change
+  * `filename` {string|Buffer} The name of the file changed.
+
+Returns an async iterator that watches for changes on `filename`, where `filename`
+is either a file or a directory.
+
+```js
+const { watch } = require('fs/promises');
+
+const ac = new AbortController();
+const { signal } = ac;
+setTimeout(() => ac.abort(), 10000);
+
+(async () => {
+  try {
+    const watcher = watch(__filename, { signal });
+    for await (const event of watcher)
+      console.log(event);
+  } catch (err) {
+    if (err.name === 'AbortError')
+      return;
+    throw err;
+  }
+})();
+```
+
+On most platforms, `'rename'` is emitted whenever a filename appears or
+disappears in the directory.
+
+All the [caveats][] for `fs.watch()` also apply to `fsPromises.watch()`.
+
 ### `fsPromises.writeFile(file, data[, options])`
 <!-- YAML
 added: v10.0.0
@@ -3461,7 +3510,7 @@ changes:
     as long as files are being watched. **Default:** `true`.
   * `recursive` {boolean} Indicates whether all subdirectories should be
     watched, or only the current directory. This applies when a directory is
-    specified, and only on supported platforms (See [Caveats][]). **Default:**
+    specified, and only on supported platforms (See [caveats][]). **Default:**
     `false`.
   * `encoding` {string} Specifies the character encoding to be used for the
      filename passed to the listener. **Default:** `'utf8'`.
@@ -6534,7 +6583,6 @@ A call to `fs.ftruncate()` or `filehandle.truncate()` can be used to reset
 the file contents.
 
 [#25741]: https://github.com/nodejs/node/issues/25741
-[Caveats]: #fs_caveats
 [Common System Errors]: errors.md#errors_common_system_errors
 [File access constants]: #fs_file_access_constants
 [MDN-Date]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
@@ -6544,6 +6592,7 @@ the file contents.
 [Naming Files, Paths, and Namespaces]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file
 [Readable Stream]: stream.md#stream_class_stream_readable
 [Writable Stream]: stream.md#stream_class_stream_writable
+[caveats]: #fs_caveats
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [`Buffer.byteLength`]: buffer.md#buffer_static_method_buffer_bytelength_string_encoding
 [`FSEvents`]: https://developer.apple.com/documentation/coreservices/file_system_events
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 39418446bd9c15..42ede0b9dc4e16 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -72,6 +72,7 @@ const {
 } = require('internal/validators');
 const pathModule = require('path');
 const { promisify } = require('internal/util');
+const { watch } = require('internal/fs/watchers');
 
 const kHandle = Symbol('kHandle');
 const kFd = Symbol('kFd');
@@ -713,6 +714,7 @@ module.exports = {
     writeFile,
     appendFile,
     readFile,
+    watch,
   },
 
   FileHandle
diff --git a/lib/internal/fs/watchers.js b/lib/internal/fs/watchers.js
index 01db66c551c9d3..40d35d815f7886 100644
--- a/lib/internal/fs/watchers.js
+++ b/lib/internal/fs/watchers.js
@@ -3,27 +3,52 @@
 const {
   ObjectDefineProperty,
   ObjectSetPrototypeOf,
+  Promise,
   Symbol,
 } = primordials;
 
-const errors = require('internal/errors');
+const {
+  AbortError,
+  uvException,
+  codes: {
+    ERR_INVALID_ARG_VALUE,
+  },
+} = require('internal/errors');
+
 const {
   kFsStatsFieldsNumber,
   StatWatcher: _StatWatcher
 } = internalBinding('fs');
+
 const { FSEvent } = internalBinding('fs_event_wrap');
 const { UV_ENOSPC } = internalBinding('uv');
 const { EventEmitter } = require('events');
+
 const {
   getStatsFromBinding,
   getValidatedPath
 } = require('internal/fs/utils');
+
 const {
   defaultTriggerAsyncIdScope,
   symbols: { owner_symbol }
 } = require('internal/async_hooks');
+
 const { toNamespacedPath } = require('path');
-const { validateUint32 } = require('internal/validators');
+
+const {
+  validateAbortSignal,
+  validateBoolean,
+  validateObject,
+  validateUint32,
+} = require('internal/validators');
+
+const {
+  Buffer: {
+    isEncoding,
+  },
+} = require('buffer');
+
 const assert = require('internal/assert');
 
 const kOldStatus = Symbol('kOldStatus');
@@ -90,7 +115,7 @@ StatWatcher.prototype[kFSStatWatcherStart] = function(filename,
   validateUint32(interval, 'interval');
   const err = this._handle.start(toNamespacedPath(filename), interval);
   if (err) {
-    const error = errors.uvException({
+    const error = uvException({
       errno: err,
       syscall: 'watch',
       path: filename
@@ -175,7 +200,7 @@ function FSWatcher() {
         this._handle.close();
         this._handle = null;  // Make the handle garbage collectable.
       }
-      const error = errors.uvException({
+      const error = uvException({
         errno: status,
         syscall: 'watch',
         path: filename
@@ -215,7 +240,7 @@ FSWatcher.prototype[kFSWatchStart] = function(filename,
                                  recursive,
                                  encoding);
   if (err) {
-    const error = errors.uvException({
+    const error = uvException({
       errno: err,
       syscall: 'watch',
       path: filename,
@@ -269,10 +294,94 @@ ObjectDefineProperty(FSEvent.prototype, 'owner', {
   set(v) { return this[owner_symbol] = v; }
 });
 
+async function* watch(filename, options = {}) {
+  const path = toNamespacedPath(getValidatedPath(filename));
+  validateObject(options, 'options');
+
+  const {
+    persistent = true,
+    recursive = false,
+    encoding = 'utf8',
+    signal,
+  } = options;
+
+  validateBoolean(persistent, 'options.persistent');
+  validateBoolean(recursive, 'options.recursive');
+  validateAbortSignal(signal, 'options.signal');
+
+  if (encoding && !isEncoding(encoding)) {
+    const reason = 'is invalid encoding';
+    throw new ERR_INVALID_ARG_VALUE(encoding, 'encoding', reason);
+  }
+
+  if (signal?.aborted)
+    throw new AbortError();
+
+  const handle = new FSEvent();
+  let res;
+  let rej;
+  const oncancel = () => {
+    handle.close();
+    rej(new AbortError());
+  };
+
+  try {
+    signal?.addEventListener('abort', oncancel, { once: true });
+
+    let promise = new Promise((resolve, reject) => {
+      res = resolve;
+      rej = reject;
+    });
+
+    handle.onchange = (status, eventType, filename) => {
+      if (status < 0) {
+        const error = uvException({
+          errno: status,
+          syscall: 'watch',
+          path: filename
+        });
+        error.filename = filename;
+        handle.close();
+        rej(error);
+        return;
+      }
+
+      res({ eventType, filename });
+    };
+
+    const err = handle.start(path, persistent, recursive, encoding);
+    if (err) {
+      const error = uvException({
+        errno: err,
+        syscall: 'watch',
+        path: filename,
+        message: err === UV_ENOSPC ?
+          'System limit for number of file watchers reached' : ''
+      });
+      error.filename = filename;
+      handle.close();
+      throw error;
+    }
+
+    while (!signal?.aborted) {
+      yield await promise;
+      promise = new Promise((resolve, reject) => {
+        res = resolve;
+        rej = reject;
+      });
+    }
+    throw new AbortError();
+  } finally {
+    handle.close();
+    signal?.removeEventListener('abort', oncancel);
+  }
+}
+
 module.exports = {
   FSWatcher,
   StatWatcher,
   kFSWatchStart,
   kFSStatWatcherStart,
   kFSStatWatcherAddOrCleanRef,
+  watch,
 };
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index e38c583511b58e..0544f8eec4b54e 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -17,6 +17,7 @@ const expectedModules = new Set([
   'Internal Binding credentials',
   'Internal Binding fs',
   'Internal Binding fs_dir',
+  'Internal Binding fs_event_wrap',
   'Internal Binding messaging',
   'Internal Binding module_wrap',
   'Internal Binding native_module',
@@ -31,6 +32,7 @@ const expectedModules = new Set([
   'Internal Binding types',
   'Internal Binding url',
   'Internal Binding util',
+  'Internal Binding uv',
   'NativeModule async_hooks',
   'NativeModule buffer',
   'NativeModule events',
@@ -49,6 +51,7 @@ const expectedModules = new Set([
   'NativeModule internal/fs/utils',
   'NativeModule internal/fs/promises',
   'NativeModule internal/fs/rimraf',
+  'NativeModule internal/fs/watchers',
   'NativeModule internal/idna',
   'NativeModule internal/linkedlist',
   'NativeModule internal/modules/run_main',
diff --git a/test/parallel/test-fs-promises-watch.js b/test/parallel/test-fs-promises-watch.js
new file mode 100644
index 00000000000000..d7a303aced9b2e
--- /dev/null
+++ b/test/parallel/test-fs-promises-watch.js
@@ -0,0 +1,116 @@
+// Flags: --experimental-abortcontroller
+'use strict';
+const common = require('../common');
+
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
+const { watch } = require('fs/promises');
+const fs = require('fs');
+const assert = require('assert');
+const { join } = require('path');
+const tmpdir = require('../common/tmpdir');
+
+class WatchTestCase {
+  constructor(shouldInclude, dirName, fileName, field) {
+    this.dirName = dirName;
+    this.fileName = fileName;
+    this.field = field;
+    this.shouldSkip = !shouldInclude;
+  }
+  get dirPath() { return join(tmpdir.path, this.dirName); }
+  get filePath() { return join(this.dirPath, this.fileName); }
+}
+
+const kCases = [
+  // Watch on a directory should callback with a filename on supported systems
+  new WatchTestCase(
+    common.isLinux || common.isOSX || common.isWindows || common.isAIX,
+    'watch1',
+    'foo',
+    'filePath'
+  ),
+  // Watch on a file should callback with a filename on supported systems
+  new WatchTestCase(
+    common.isLinux || common.isOSX || common.isWindows,
+    'watch2',
+    'bar',
+    'dirPath'
+  )
+];
+
+tmpdir.refresh();
+
+for (const testCase of kCases) {
+  if (testCase.shouldSkip) continue;
+  fs.mkdirSync(testCase.dirPath);
+  // Long content so it's actually flushed.
+  const content1 = Date.now() + testCase.fileName.toLowerCase().repeat(1e4);
+  fs.writeFileSync(testCase.filePath, content1);
+
+  async function test() {
+    const watcher = watch(testCase[testCase.field]);
+    for await (const { eventType, filename } of watcher) {
+      assert.strictEqual(['rename', 'change'].includes(eventType), true);
+      assert.strictEqual(filename, testCase.fileName);
+      break;
+    }
+
+    // Waiting on it again is a non-op
+    // eslint-disable-next-line no-unused-vars
+    for await (const p of watcher) {
+      assert.fail('should not run');
+    }
+  }
+
+  // Long content so it's actually flushed. toUpperCase so there's real change.
+  const content2 = Date.now() + testCase.fileName.toUpperCase().repeat(1e4);
+  setImmediate(() => {
+    fs.writeFileSync(testCase.filePath, '');
+    fs.writeFileSync(testCase.filePath, content2);
+  });
+
+  test().then(common.mustCall());
+}
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch(1)) {} },
+  { code: 'ERR_INVALID_ARG_TYPE' });
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch(__filename, 1)) {} },
+  { code: 'ERR_INVALID_ARG_TYPE' });
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch('', { persistent: 1 })) {} },
+  { code: 'ERR_INVALID_ARG_TYPE' });
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch('', { recursive: 1 })) {} },
+  { code: 'ERR_INVALID_ARG_TYPE' });
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch('', { encoding: 1 })) {} },
+  { code: 'ERR_INVALID_ARG_VALUE' });
+
+assert.rejects(
+  // eslint-disable-next-line no-unused-vars
+  async () => { for await (const _ of watch('', { signal: 1 })) {} },
+  { code: 'ERR_INVALID_ARG_TYPE' });
+
+(async () => {
+  const ac = new AbortController();
+  const { signal } = ac;
+  setImmediate(() => ac.abort());
+  try {
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of watch(__filename, { signal })) {}
+  } catch (err) {
+    assert.strictEqual(err.name, 'AbortError');
+  }
+})().then(common.mustCall());