From cdc9349b74c8cff45d8f63b43c2b9072f5803e7c Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 19 Oct 2022 16:00:33 -0400
Subject: [PATCH 01/38] fs: add recursive watch to linux

---
 doc/api/fs.md                                 |   4 -
 lib/fs.js                                     |  27 ++-
 lib/internal/fs/linux_watcher.js              | 207 ++++++++++++++++++
 .../parallel/test-fs-watch-recursive-linux.js | 138 ++++++++++++
 test/parallel/test-fs-watch-recursive.js      |   8 +-
 5 files changed, 364 insertions(+), 20 deletions(-)
 create mode 100644 lib/internal/fs/linux_watcher.js
 create mode 100644 test/parallel/test-fs-watch-recursive-linux.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index fa3368da281da4..c7f7b9b16a5eae 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -4377,10 +4377,6 @@ the returned {fs.FSWatcher}.
 The `fs.watch` API is not 100% consistent across platforms, and is
 unavailable in some situations.
 
-The recursive option is only supported on macOS and Windows.
-An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown
-when the option is used on a platform that does not support it.
-
 On Windows, no events will be emitted if the watched directory is moved or
 renamed. An `EPERM` error is reported when the watched directory is deleted.
 
diff --git a/lib/fs.js b/lib/fs.js
index 5e110eef17dd8b..5bd709874c2eaf 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -57,6 +57,7 @@ const {
 
 const pathModule = require('path');
 const { isArrayBufferView } = require('internal/util/types');
+const linuxWatcher = require('internal/fs/linux_watcher');
 
 // We need to get the statValues from the binding at the callsite since
 // it's re-initialized after deserialization.
@@ -68,7 +69,6 @@ const {
   codes: {
     ERR_FS_FILE_TOO_LARGE,
     ERR_INVALID_ARG_VALUE,
-    ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
   },
   AbortError,
   uvErrmapGet,
@@ -161,7 +161,7 @@ let FileReadStream;
 let FileWriteStream;
 
 const isWindows = process.platform === 'win32';
-const isOSX = process.platform === 'darwin';
+const isLinux = process.platform === 'linux';
 
 
 function showTruncateDeprecation() {
@@ -2297,13 +2297,22 @@ function watch(filename, options, listener) {
 
   if (options.persistent === undefined) options.persistent = true;
   if (options.recursive === undefined) options.recursive = false;
-  if (options.recursive && !(isOSX || isWindows))
-    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('watch recursively');
-  const watcher = new watchers.FSWatcher();
-  watcher[watchers.kFSWatchStart](filename,
-                                  options.persistent,
-                                  options.recursive,
-                                  options.encoding);
+
+  let watcher;
+
+  // TODO(anonrig): Remove this when/if libuv supports it.
+  // libuv does not support recursive file watch on Linux due to
+  // the limitations of inotify.
+  if (options.recursive && isLinux) {
+    watcher = new linuxWatcher.FSWatcher(options);
+    watcher[linuxWatcher.kFSWatchStart](filename);
+  } else {
+    watcher = new watchers.FSWatcher();
+    watcher[watchers.kFSWatchStart](filename,
+                                    options.persistent,
+                                    options.recursive,
+                                    options.encoding);
+  }
 
   if (listener) {
     watcher.addListener('change', listener);
diff --git a/lib/internal/fs/linux_watcher.js b/lib/internal/fs/linux_watcher.js
new file mode 100644
index 00000000000000..2ee732b5f9d563
--- /dev/null
+++ b/lib/internal/fs/linux_watcher.js
@@ -0,0 +1,207 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const path = require('path');
+const { SafeMap, Symbol, StringPrototypeStartsWith } = primordials;
+const { validateObject } = require('internal/validators');
+const { kEmptyObject } = require('internal/util');
+const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
+
+const kFSWatchStart = Symbol('kFSWatchStart');
+
+let internalSync;
+let internalPromises;
+
+function lazyLoadFsPromises() {
+  internalPromises ??= require('fs/promises');
+  return internalPromises;
+}
+
+function lazyLoadFsSync() {
+  internalSync ??= require('fs');
+  return internalSync;
+}
+
+async function traverse(dir, files = new SafeMap()) {
+  const { stat, opendir } = lazyLoadFsPromises();
+
+  files.set(dir, await stat(dir));
+
+  try {
+    const directory = await opendir(dir);
+
+    for await (const file of directory) {
+      const f = path.join(dir, file.name);
+
+      try {
+        const stats = await stat(f);
+
+        files.set(f, stats);
+
+        if (stats.isDirectory()) {
+          await traverse(f, files);
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT' || error.code !== 'EPERM') {
+          this.emit('error', error);
+        }
+      }
+
+    }
+  } catch (error) {
+    if (error.code !== 'EACCES') {
+      this.emit('error', error);
+    }
+  }
+
+  return files;
+}
+
+class FSWatcher extends EventEmitter {
+  #options = null;
+  #closed = false;
+  #files = new SafeMap();
+  #rootPath = path.resolve();
+
+  /**
+   * @param {{
+   *   persistent?: boolean;
+   *   recursive?: boolean;
+   *   encoding?: string;
+   *   signal?: AbortSignal;
+   *   }} [options]
+   */
+  constructor(options = kEmptyObject) {
+    super();
+
+    validateObject(options, 'options');
+    this.#options = options;
+  }
+
+  close() {
+    const { unwatchFile } = lazyLoadFsSync();
+    this.#closed = true;
+
+    for (const file of this.#files.keys()) {
+      unwatchFile(file);
+    }
+
+    this.emit('close');
+  }
+
+  #getPath(file) {
+    if (file === this.#rootPath) {
+      return this.#rootPath;
+    }
+
+    return path.relative(this.#rootPath, file);
+  }
+
+  #unwatchFolder(file) {
+    const { unwatchFile } = lazyLoadFsSync();
+
+    for (const filename of this.#files.keys()) {
+      if (StringPrototypeStartsWith(filename, file)) {
+        unwatchFile(filename);
+      }
+    }
+  }
+
+  async #watchFolder(folder) {
+    const { opendir, stat } = lazyLoadFsPromises();
+
+    try {
+      const files = await opendir(folder);
+
+      for await (const file of files) {
+        const f = path.join(folder, file.name);
+
+        if (this.#closed) {
+          break;
+        }
+
+        if (!this.#files.has(f)) {
+          const fileStats = await stat(f);
+
+          this.#files.set(f, fileStats);
+          this.emit('change', 'rename', this.#getPath(f));
+
+          if (fileStats.isDirectory()) {
+            await this.#watchFolder(f);
+          } else {
+            this.#watchFile(f);
+          }
+        }
+      }
+    } catch (error) {
+      this.emit('error', error);
+    }
+  }
+
+  /**
+   * @param {string} file
+   */
+  #watchFile(file) {
+    const { watchFile } = lazyLoadFsSync();
+
+    if (this.#closed) {
+      return;
+    }
+
+    const existingStat = this.#files.get(file);
+
+    watchFile(file, {
+      persistent: this.#options.persistent,
+    }, (statWatcher, previousStatWatcher) => {
+      if (existingStat && !existingStat.isDirectory() &&
+        statWatcher.nlink !== 0 && existingStat.mtime.getTime() === statWatcher.mtime.getTime()) {
+        return;
+      }
+
+      this.#files.set(file, statWatcher);
+
+      if (statWatcher.birthtimeMs === 0 && previousStatWatcher.birthtimeMs !== 0) {
+        // The file is now deleted
+        this.#files.delete(file);
+        this.emit('change', 'rename', this.#getPath(file));
+
+        if (statWatcher.isDirectory()) {
+          this.#unwatchFolder(file);
+        }
+      } else if (statWatcher.isDirectory()) {
+        this.#watchFolder(file);
+        this.emit('change', 'change', this.#getPath(file));
+      } else {
+        this.emit('change', 'change', this.#getPath(file));
+      }
+    });
+  }
+
+  /**
+   * @param {string | Buffer | URL} filename
+   */
+  async [kFSWatchStart](filename) {
+    this.#rootPath = filename;
+    this.#closed = false;
+    this.#files = await traverse(filename);
+
+    for (const f of this.#files.keys()) {
+      this.#watchFile(f);
+    }
+  }
+
+  ref() {
+    // This is kept to have the same API with FSWatcher
+    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('ref');
+  }
+
+  unref() {
+    // This is kept to have the same API with FSWatcher
+    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('unref');
+  }
+}
+
+module.exports = {
+  FSWatcher,
+  kFSWatchStart,
+};
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
new file mode 100644
index 00000000000000..e1b019b04c47a1
--- /dev/null
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -0,0 +1,138 @@
+'use strict';
+
+const common = require('../common');
+const { setTimeout } = require('timers/promises');
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const { randomUUID } = require('crypto');
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+
+const tmpdir = require('../common/tmpdir');
+const testDir = tmpdir.path;
+tmpdir.refresh();
+
+(async () => {
+  {
+    // Add a file to already watching folder
+
+    const testsubdir = fs.mkdtempSync(testDir + path.sep);
+    const file = `${randomUUID()}.txt`;
+    const filePath = path.join(testsubdir, file);
+    const watcher = fs.watch(testsubdir, { recursive: true });
+
+    let watcherClosed = false;
+    watcher.on('change', function(event, filename) {
+      assert.ok(event === 'change' || event === 'rename');
+
+      if (filename === file) {
+        watcher.close();
+        watcherClosed = true;
+      }
+    });
+
+    await setTimeout(100);
+    fs.writeFileSync(filePath, 'world');
+
+    process.on('exit', function() {
+      assert(watcherClosed, 'watcher Object was not closed');
+    });
+  }
+
+  {
+    // Add a folder to already watching folder
+
+    const testsubdir = fs.mkdtempSync(testDir + path.sep);
+    const file = `folder-${randomUUID()}`;
+    const filePath = path.join(testsubdir, file);
+    const watcher = fs.watch(testsubdir, { recursive: true });
+
+    let watcherClosed = false;
+    watcher.on('change', function(event, filename) {
+      assert.ok(event === 'change' || event === 'rename');
+
+      if (filename === file) {
+        watcher.close();
+        watcherClosed = true;
+      }
+    });
+
+    await setTimeout(100);
+    fs.mkdirSync(filePath);
+
+    process.on('exit', function() {
+      assert(watcherClosed, 'watcher Object was not closed');
+    });
+  }
+
+  {
+    // Add a file to newly created folder to already watching folder
+
+    const testsubdir = fs.mkdtempSync(testDir + path.sep);
+    const file = `folder-${randomUUID()}`;
+    const filePath = path.join(testsubdir, file);
+    const watcher = fs.watch(testsubdir, { recursive: true });
+    const childrenFile = `file-${randomUUID()}.txt`;
+    const childrenAbsolutePath = path.join(filePath, childrenFile);
+
+    let watcherClosed = false;
+
+    watcher.on('change', function(event, filename) {
+      assert.ok(event === 'change' || event === 'rename');
+
+      if (filename === path.join(file, childrenFile)) {
+        watcher.close();
+        watcherClosed = true;
+      }
+    });
+
+    await setTimeout(100);
+    fs.mkdirSync(filePath);
+    await setTimeout(100);
+    fs.writeFileSync(childrenAbsolutePath, 'world');
+
+    process.on('exit', function() {
+      assert(watcherClosed, 'watcher Object was not closed');
+    });
+  }
+
+  {
+    // Add a file to subfolder of a watching folder
+
+    const testsubdir = fs.mkdtempSync(testDir + path.sep);
+    const file = `folder-${randomUUID()}`;
+    const filePath = path.join(testsubdir, file);
+    fs.mkdirSync(filePath);
+
+    const subFolder = `subfolder-${randomUUID()}`;
+    const subfolderPath = path.join(filePath, subFolder);
+
+    fs.mkdirSync(subfolderPath);
+
+    const watcher = fs.watch(testsubdir, { recursive: true });
+    const childrenFile = `file-${randomUUID()}.txt`;
+    const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
+    const relativePath = path.join(file, subFolder, childrenFile);
+
+    let watcherClosed = false;
+
+    watcher.on('change', function(event, filename) {
+      assert.ok(event === 'change' || event === 'rename');
+
+      if (filename === relativePath) {
+        watcher.close();
+        watcherClosed = true;
+      }
+    });
+
+    await setTimeout(100);
+    fs.writeFileSync(childrenAbsolutePath, 'world');
+
+    process.on('exit', function() {
+      assert(watcherClosed, 'watcher Object was not closed');
+    });
+  }
+})().then(common.mustCall());
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 70b413814e78f4..a8fc6e59cb836f 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -17,12 +17,6 @@ tmpdir.refresh();
 const testsubdir = fs.mkdtempSync(testDir + path.sep);
 const relativePathOne = path.join(path.basename(testsubdir), filenameOne);
 const filepathOne = path.join(testsubdir, filenameOne);
-
-if (!common.isOSX && !common.isWindows) {
-  assert.throws(() => { fs.watch(testDir, { recursive: true }); },
-                { code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM' });
-  return;
-}
 const watcher = fs.watch(testDir, { recursive: true });
 
 let watcherClosed = false;
@@ -41,7 +35,7 @@ watcher.on('change', function(event, filename) {
 });
 
 let interval;
-if (common.isOSX) {
+if (common.isOSX || common.isLinux) {
   interval = setInterval(function() {
     fs.writeFileSync(filepathOne, 'world');
   }, 10);

From 296646b0d7e1bc44013164a00176a132c3062b29 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Fri, 21 Oct 2022 19:46:13 -0400
Subject: [PATCH 02/38] fs: replace traverse with readdir for performance

---
 lib/internal/fs/linux_watcher.js | 40 +++++++++++---------------------
 1 file changed, 13 insertions(+), 27 deletions(-)

diff --git a/lib/internal/fs/linux_watcher.js b/lib/internal/fs/linux_watcher.js
index 2ee732b5f9d563..1e08dd859135b3 100644
--- a/lib/internal/fs/linux_watcher.js
+++ b/lib/internal/fs/linux_watcher.js
@@ -6,6 +6,7 @@ const { SafeMap, Symbol, StringPrototypeStartsWith } = primordials;
 const { validateObject } = require('internal/validators');
 const { kEmptyObject } = require('internal/util');
 const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
+const { Dirent, UV_DIRENT_DIR } = require('internal/fs/utils');
 
 const kFSWatchStart = Symbol('kFSWatchStart');
 
@@ -22,35 +23,20 @@ function lazyLoadFsSync() {
   return internalSync;
 }
 
-async function traverse(dir, files = new SafeMap()) {
-  const { stat, opendir } = lazyLoadFsPromises();
+function traverse(dir, files = new SafeMap()) {
+  const { readdirSync } = lazyLoadFsSync()
 
-  files.set(dir, await stat(dir));
+  const filenames = readdirSync(dir, { withFileTypes: true });
 
-  try {
-    const directory = await opendir(dir);
+  files.set(dir, new Dirent(dir, UV_DIRENT_DIR));
 
-    for await (const file of directory) {
-      const f = path.join(dir, file.name);
+  for (let file of filenames) {
+    const f = path.join(dir, file.name);
 
-      try {
-        const stats = await stat(f);
+    files.set(f, file);
 
-        files.set(f, stats);
-
-        if (stats.isDirectory()) {
-          await traverse(f, files);
-        }
-      } catch (error) {
-        if (error.code !== 'ENOENT' || error.code !== 'EPERM') {
-          this.emit('error', error);
-        }
-      }
-
-    }
-  } catch (error) {
-    if (error.code !== 'EACCES') {
-      this.emit('error', error);
+    if (file.isDirectory()) {
+      traverse(f, files);
     }
   }
 
@@ -154,7 +140,7 @@ class FSWatcher extends EventEmitter {
       persistent: this.#options.persistent,
     }, (statWatcher, previousStatWatcher) => {
       if (existingStat && !existingStat.isDirectory() &&
-        statWatcher.nlink !== 0 && existingStat.mtime.getTime() === statWatcher.mtime.getTime()) {
+        statWatcher.nlink !== 0 && existingStat.mtime?.getTime() === statWatcher.mtime?.getTime()) {
         return;
       }
 
@@ -180,10 +166,10 @@ class FSWatcher extends EventEmitter {
   /**
    * @param {string | Buffer | URL} filename
    */
-  async [kFSWatchStart](filename) {
+  [kFSWatchStart](filename) {
     this.#rootPath = filename;
     this.#closed = false;
-    this.#files = await traverse(filename);
+    this.#files = traverse(filename);
 
     for (const f of this.#files.keys()) {
       this.#watchFile(f);

From 77cb9a0cb639702862f8dbbed620f2f760af61a9 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 13:02:47 -0400
Subject: [PATCH 03/38] fs: fix linter issues

---
 lib/internal/fs/linux_watcher.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/internal/fs/linux_watcher.js b/lib/internal/fs/linux_watcher.js
index 1e08dd859135b3..9a2b0faa323a0d 100644
--- a/lib/internal/fs/linux_watcher.js
+++ b/lib/internal/fs/linux_watcher.js
@@ -24,13 +24,13 @@ function lazyLoadFsSync() {
 }
 
 function traverse(dir, files = new SafeMap()) {
-  const { readdirSync } = lazyLoadFsSync()
+  const { readdirSync } = lazyLoadFsSync();
 
   const filenames = readdirSync(dir, { withFileTypes: true });
 
   files.set(dir, new Dirent(dir, UV_DIRENT_DIR));
 
-  for (let file of filenames) {
+  for (const file of filenames) {
     const f = path.join(dir, file.name);
 
     files.set(f, file);

From 5b72449fe22075c5c92286cf1733446b5c50a463 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 13:30:23 -0400
Subject: [PATCH 04/38] fs: move linux watcher to internal/fs/watch

---
 doc/api/fs.md                                 |  8 +++
 lib/fs.js                                     |  2 +-
 .../fs/{linux_watcher.js => watch/linux.js}   | 60 +++++++++----------
 3 files changed, 39 insertions(+), 31 deletions(-)
 rename lib/internal/fs/{linux_watcher.js => watch/linux.js} (80%)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index c7f7b9b16a5eae..9c0204cd284e1d 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -6403,6 +6403,10 @@ By default, all {fs.FSWatcher} objects are "ref'ed", making it normally
 unnecessary to call `watcher.ref()` unless `watcher.unref()` had been
 called previously.
 
+`watcher.ref()` is not available on Linux. An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`
+exception will be thrown when the function is used on a platform that
+does not support it.
+
 #### `watcher.unref()`
 
 <!-- YAML
@@ -6419,6 +6423,10 @@ event loop running, the process may exit before the {fs.FSWatcher} object's
 callback is invoked. Calling `watcher.unref()` multiple times will have
 no effect.
 
+`watcher.unref()` is not available on Linux. An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`
+exception will be thrown when the function is used on a platform that
+does not support it.
+
 ### Class: `fs.StatWatcher`
 
 <!-- YAML
diff --git a/lib/fs.js b/lib/fs.js
index 5bd709874c2eaf..7ba8a7738b68f0 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -57,7 +57,7 @@ const {
 
 const pathModule = require('path');
 const { isArrayBufferView } = require('internal/util/types');
-const linuxWatcher = require('internal/fs/linux_watcher');
+const linuxWatcher = require('internal/fs/watch/linux');
 
 // We need to get the statValues from the binding at the callsite since
 // it's re-initialized after deserialization.
diff --git a/lib/internal/fs/linux_watcher.js b/lib/internal/fs/watch/linux.js
similarity index 80%
rename from lib/internal/fs/linux_watcher.js
rename to lib/internal/fs/watch/linux.js
index 9a2b0faa323a0d..e1c9faa6f9473f 100644
--- a/lib/internal/fs/linux_watcher.js
+++ b/lib/internal/fs/watch/linux.js
@@ -3,10 +3,9 @@
 const { EventEmitter } = require('events');
 const path = require('path');
 const { SafeMap, Symbol, StringPrototypeStartsWith } = primordials;
-const { validateObject } = require('internal/validators');
+const { validateObject, validateString } = require('internal/validators');
 const { kEmptyObject } = require('internal/util');
 const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
-const { Dirent, UV_DIRENT_DIR } = require('internal/fs/utils');
 
 const kFSWatchStart = Symbol('kFSWatchStart');
 
@@ -23,20 +22,25 @@ function lazyLoadFsSync() {
   return internalSync;
 }
 
-function traverse(dir, files = new SafeMap()) {
-  const { readdirSync } = lazyLoadFsSync();
+async function traverse(dir, parent = undefined, files = new SafeMap()) {
+  const { readdir, stat } = lazyLoadFsPromises();
 
-  const filenames = readdirSync(dir, { withFileTypes: true });
+  const filenames = await readdir(dir, { withFileTypes: true });
 
-  files.set(dir, new Dirent(dir, UV_DIRENT_DIR));
+  if (parent !== undefined) {
+    files.set(dir, parent);
+  } else {
+    // Optimization: Only call `stat` on the root element.
+    files.set(dir, await stat(dir));
+  }
 
-  for (const file of filenames) {
+  for await (const file of filenames) {
     const f = path.join(dir, file.name);
 
     files.set(f, file);
 
     if (file.isDirectory()) {
-      traverse(f, files);
+      await traverse(f, file, files);
     }
   }
 
@@ -49,14 +53,6 @@ class FSWatcher extends EventEmitter {
   #files = new SafeMap();
   #rootPath = path.resolve();
 
-  /**
-   * @param {{
-   *   persistent?: boolean;
-   *   recursive?: boolean;
-   *   encoding?: string;
-   *   signal?: AbortSignal;
-   *   }} [options]
-   */
   constructor(options = kEmptyObject) {
     super();
 
@@ -75,7 +71,13 @@ class FSWatcher extends EventEmitter {
     this.emit('close');
   }
 
+  /**
+   * @param {string} file
+   * @return {string}
+   */
   #getPath(file) {
+    validateString(file, 'file');
+
     if (file === this.#rootPath) {
       return this.#rootPath;
     }
@@ -84,6 +86,8 @@ class FSWatcher extends EventEmitter {
   }
 
   #unwatchFolder(file) {
+    validateString(file, 'file');
+
     const { unwatchFile } = lazyLoadFsSync();
 
     for (const filename of this.#files.keys()) {
@@ -94,7 +98,9 @@ class FSWatcher extends EventEmitter {
   }
 
   async #watchFolder(folder) {
-    const { opendir, stat } = lazyLoadFsPromises();
+    validateString(folder, 'folder');
+
+    const { opendir } = lazyLoadFsPromises();
 
     try {
       const files = await opendir(folder);
@@ -107,12 +113,10 @@ class FSWatcher extends EventEmitter {
         }
 
         if (!this.#files.has(f)) {
-          const fileStats = await stat(f);
-
-          this.#files.set(f, fileStats);
+          this.#files.set(f, file);
           this.emit('change', 'rename', this.#getPath(f));
 
-          if (fileStats.isDirectory()) {
+          if (file.isDirectory()) {
             await this.#watchFolder(f);
           } else {
             this.#watchFile(f);
@@ -124,10 +128,9 @@ class FSWatcher extends EventEmitter {
     }
   }
 
-  /**
-   * @param {string} file
-   */
   #watchFile(file) {
+    validateString(file, 'file');
+
     const { watchFile } = lazyLoadFsSync();
 
     if (this.#closed) {
@@ -155,21 +158,18 @@ class FSWatcher extends EventEmitter {
           this.#unwatchFolder(file);
         }
       } else if (statWatcher.isDirectory()) {
-        this.#watchFolder(file);
         this.emit('change', 'change', this.#getPath(file));
+        this.#watchFolder(file);
       } else {
         this.emit('change', 'change', this.#getPath(file));
       }
     });
   }
 
-  /**
-   * @param {string | Buffer | URL} filename
-   */
-  [kFSWatchStart](filename) {
+  async [kFSWatchStart](filename) {
     this.#rootPath = filename;
     this.#closed = false;
-    this.#files = traverse(filename);
+    this.#files = await traverse(filename);
 
     for (const f of this.#files.keys()) {
       this.#watchFile(f);

From 87866c33eae11a92e1433ef0c31d4da68b3c2706 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 15:55:15 -0400
Subject: [PATCH 05/38] test: add missing clear interval for linux

---
 test/parallel/test-fs-watch-recursive.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index a8fc6e59cb836f..5cb3ddff9d03a9 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -27,7 +27,7 @@ watcher.on('change', function(event, filename) {
   if (filename !== relativePathOne)
     return;
 
-  if (common.isOSX) {
+  if (common.isOSX || common.isLinux) {
     clearInterval(interval);
   }
   watcher.close();

From 00ab12d6402e00b678b379abe75ddd50bd8d0d92 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 15:58:03 -0400
Subject: [PATCH 06/38] fs: add promise support to linux watcher

---
 lib/internal/fs/promises.js                   | 19 ++++++++-
 lib/internal/fs/watch/linux.js                | 28 +++++++++++--
 .../test-fs-watch-recursive-linux-promise.js  | 40 +++++++++++++++++++
 3 files changed, 82 insertions(+), 5 deletions(-)
 create mode 100644 test/parallel/test-fs-watch-recursive-linux-promise.js

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index f38391ac753e4d..a1dcb93acd774c 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -89,6 +89,7 @@ const {
 const { EventEmitterMixin } = require('internal/event_target');
 const { StringDecoder } = require('string_decoder');
 const { watch } = require('internal/fs/watchers');
+const linuxWatcher = require('internal/fs/watch/linux');
 const { isIterable } = require('internal/streams/utils');
 const assert = require('internal/assert');
 
@@ -120,6 +121,7 @@ const getDirectoryEntriesPromise = promisify(getDirents);
 const validateRmOptionsPromise = promisify(validateRmOptions);
 
 const isWindows = process.platform === 'win32';
+const isLinux = process.platform === 'linux';
 
 let cpPromises;
 function lazyLoadCpPromises() {
@@ -917,6 +919,21 @@ async function readFile(path, options) {
   return handleFdClose(readFileHandle(fd, options), fd.close);
 }
 
+function _watch(filename, options) {
+  options = getOptions(options, { persistent: true, recursive: false, encoding: 'utf8' });
+
+  // TODO(anonrig): Remove this when/if libuv supports it.
+  // libuv does not support recursive file watch on Linux due to
+  // the limitations of inotify.
+  if (options.recursive && isLinux) {
+    const watcher = new linuxWatcher.FSWatcher(options);
+    watcher[linuxWatcher.kFSWatchStart](filename);
+    return watcher;
+  }
+
+  return watch(filename, options);
+}
+
 module.exports = {
   exports: {
     access,
@@ -947,7 +964,7 @@ module.exports = {
     writeFile,
     appendFile,
     readFile,
-    watch,
+    watch: _watch,
     constants,
   },
 
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index e1c9faa6f9473f..55c0e436f5a929 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -1,11 +1,12 @@
 'use strict';
 
+const { SafeMap, Symbol, StringPrototypeStartsWith, SymbolAsyncIterator, Promise } = primordials;
+
+const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
+const { kEmptyObject } = require('internal/util');
+const { validateObject, validateString } = require('internal/validators');
 const { EventEmitter } = require('events');
 const path = require('path');
-const { SafeMap, Symbol, StringPrototypeStartsWith } = primordials;
-const { validateObject, validateString } = require('internal/validators');
-const { kEmptyObject } = require('internal/util');
-const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
 
 const kFSWatchStart = Symbol('kFSWatchStart');
 
@@ -185,6 +186,25 @@ class FSWatcher extends EventEmitter {
     // This is kept to have the same API with FSWatcher
     throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('unref');
   }
+
+  async next() {
+    if (this.#closed) {
+      return { done: true };
+    }
+
+    const result = await new Promise((resolve) => {
+      this.once('change', (eventType, filename) => {
+        resolve({ eventType, filename });
+      });
+    });
+
+    return { done: false, value: result };
+  }
+
+  // eslint-disable-next-line require-yield
+  *[SymbolAsyncIterator]() {
+    return this;
+  }
 }
 
 module.exports = {
diff --git a/test/parallel/test-fs-watch-recursive-linux-promise.js b/test/parallel/test-fs-watch-recursive-linux-promise.js
new file mode 100644
index 00000000000000..6eb43b34c85776
--- /dev/null
+++ b/test/parallel/test-fs-watch-recursive-linux-promise.js
@@ -0,0 +1,40 @@
+'use strict';
+
+const common = require('../common');
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const { randomUUID } = require('crypto');
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs/promises');
+
+const tmpdir = require('../common/tmpdir');
+const testDir = tmpdir.path;
+tmpdir.refresh();
+
+(async () => {
+  {
+    // Add a file to already watching folder
+
+    const testsubdir = await fs.mkdtemp(testDir + path.sep);
+    const file = `${randomUUID()}.txt`;
+    const filePath = path.join(testsubdir, file);
+    const watcher = fs.watch(testsubdir, { recursive: true });
+
+    setTimeout(async () => {
+      await fs.writeFile(filePath, 'world');
+    }, 100);
+
+    for await (const payload of watcher) {
+      const { eventType, filename } = payload;
+
+      assert.ok(eventType === 'change' || eventType === 'rename');
+
+      if (filename === file) {
+        break;
+      }
+    }
+  }
+})().then(common.mustCall());

From cb4b455ac44238c7f0ae4b5b1598e4f62b4da9ec Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 16:37:06 -0400
Subject: [PATCH 07/38] test: simplify start and update tests

---
 lib/internal/fs/watch/linux.js          | 16 ++++++----------
 test/parallel/test-bootstrap-modules.js |  1 +
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 55c0e436f5a929..415e513bbf7408 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -23,25 +23,18 @@ function lazyLoadFsSync() {
   return internalSync;
 }
 
-async function traverse(dir, parent = undefined, files = new SafeMap()) {
-  const { readdir, stat } = lazyLoadFsPromises();
+async function traverse(dir, files = new SafeMap()) {
+  const { readdir } = lazyLoadFsPromises();
 
   const filenames = await readdir(dir, { withFileTypes: true });
 
-  if (parent !== undefined) {
-    files.set(dir, parent);
-  } else {
-    // Optimization: Only call `stat` on the root element.
-    files.set(dir, await stat(dir));
-  }
-
   for await (const file of filenames) {
     const f = path.join(dir, file.name);
 
     files.set(f, file);
 
     if (file.isDirectory()) {
-      await traverse(f, file, files);
+      await traverse(f, files);
     }
   }
 
@@ -168,9 +161,12 @@ class FSWatcher extends EventEmitter {
   }
 
   async [kFSWatchStart](filename) {
+    const { stat } = lazyLoadFsPromises();
+
     this.#rootPath = filename;
     this.#closed = false;
     this.#files = await traverse(filename);
+    this.#files.set(filename, await stat(filename));
 
     for (const f of this.#files.keys()) {
       this.#watchFile(f);
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index 702dadfc5be7df..f5caa95a052947 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -67,6 +67,7 @@ const expectedModules = new Set([
   'NativeModule internal/fs/read_file_context',
   'NativeModule internal/fs/rimraf',
   'NativeModule internal/fs/utils',
+  'NativeModule internal/fs/watch/linux',
   'NativeModule internal/fs/watchers',
   'NativeModule internal/heap_utils',
   'NativeModule internal/histogram',

From 4144949688ccefe3c127bdcdd0fedf7a6d673dc4 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 17:06:23 -0400
Subject: [PATCH 08/38] fs: avoid prototype pollution

---
 lib/internal/fs/watch/linux.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 415e513bbf7408..38fd3c6877f741 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -185,7 +185,7 @@ class FSWatcher extends EventEmitter {
 
   async next() {
     if (this.#closed) {
-      return { done: true };
+      return { __proto__: null, done: true };
     }
 
     const result = await new Promise((resolve) => {
@@ -194,7 +194,7 @@ class FSWatcher extends EventEmitter {
       });
     });
 
-    return { done: false, value: result };
+    return { __proto__: null, done: false, value: result };
   }
 
   // eslint-disable-next-line require-yield

From 9a864102b0b3a81d7d8fcae0823e32f15deab870 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 22 Oct 2022 23:29:54 -0400
Subject: [PATCH 09/38] test: improve fs.watch tests

---
 lib/internal/fs/promises.js                   |  5 +-
 lib/internal/fs/watch/linux.js                | 51 ++++++++++++++++---
 .../test-fs-watch-recursive-linux-promise.js  |  3 ++
 .../parallel/test-fs-watch-recursive-linux.js |  3 ++
 4 files changed, 52 insertions(+), 10 deletions(-)

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index a1dcb93acd774c..acda765f210696 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -919,8 +919,9 @@ async function readFile(path, options) {
   return handleFdClose(readFileHandle(fd, options), fd.close);
 }
 
-function _watch(filename, options) {
-  options = getOptions(options, { persistent: true, recursive: false, encoding: 'utf8' });
+function _watch(filename, options = kEmptyObject) {
+  validateString(filename, 'filename');
+  validateObject(options, 'options');
 
   // TODO(anonrig): Remove this when/if libuv supports it.
   // libuv does not support recursive file watch on Linux due to
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 38fd3c6877f741..a3afe690d10bfd 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -2,9 +2,12 @@
 
 const { SafeMap, Symbol, StringPrototypeStartsWith, SymbolAsyncIterator, Promise } = primordials;
 
-const { ERR_FEATURE_UNAVAILABLE_ON_PLATFORM } = require('internal/errors');
+const {
+  ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
+  codes: { ERR_INVALID_ARG_TYPE, ERR_INVALID_ARG_VALUE },
+} = require('internal/errors');
 const { kEmptyObject } = require('internal/util');
-const { validateObject, validateString } = require('internal/validators');
+const { validateString, validateObject, validateBoolean, validateAbortSignal } = require('internal/validators');
 const { EventEmitter } = require('events');
 const path = require('path');
 
@@ -51,6 +54,25 @@ class FSWatcher extends EventEmitter {
     super();
 
     validateObject(options, 'options');
+
+    if (options.persistent !== undefined) {
+      validateBoolean(options.persistent, 'options.persistent');
+    }
+
+    if (options.recursive !== undefined) {
+      validateBoolean(options.recursive, 'options.recursive');
+    }
+
+    if (options.signal !== undefined) {
+      validateAbortSignal(options.signal, 'options.signal');
+    }
+
+    if (options.encoding !== undefined) {
+      if (typeof options.encoding !== 'string') {
+        throw new ERR_INVALID_ARG_VALUE('encoding', 'options.encoding');
+      }
+    }
+
     this.#options = options;
   }
 
@@ -62,6 +84,7 @@ class FSWatcher extends EventEmitter {
       unwatchFile(file);
     }
 
+    this.#files.clear();
     this.emit('close');
   }
 
@@ -160,16 +183,28 @@ class FSWatcher extends EventEmitter {
     });
   }
 
-  async [kFSWatchStart](filename) {
-    const { stat } = lazyLoadFsPromises();
+  [kFSWatchStart](filename) {
+    validateString(filename, 'filename');
+
+    if (filename.length === 0) {
+      throw new ERR_INVALID_ARG_TYPE('filename');
+    }
+
+    const file = lazyLoadFsSync().statSync(filename);
 
     this.#rootPath = filename;
     this.#closed = false;
-    this.#files = await traverse(filename);
-    this.#files.set(filename, await stat(filename));
+    this.#files.set(filename, file);
 
-    for (const f of this.#files.keys()) {
-      this.#watchFile(f);
+    if (file.isDirectory()) {
+      traverse(filename, this.#files)
+        .then(() => {
+          for (const f of this.#files.keys()) {
+            this.#watchFile(f);
+          }
+        });
+    } else {
+      this.#watchFile(filename);
     }
   }
 
diff --git a/test/parallel/test-fs-watch-recursive-linux-promise.js b/test/parallel/test-fs-watch-recursive-linux-promise.js
index 6eb43b34c85776..294b2333147e30 100644
--- a/test/parallel/test-fs-watch-recursive-linux-promise.js
+++ b/test/parallel/test-fs-watch-recursive-linux-promise.js
@@ -5,6 +5,9 @@ const common = require('../common');
 if (!common.hasCrypto)
   common.skip('missing crypto');
 
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
 const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index e1b019b04c47a1..91511ab8eb796d 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -6,6 +6,9 @@ const { setTimeout } = require('timers/promises');
 if (!common.hasCrypto)
   common.skip('missing crypto');
 
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
 const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');

From 8b36541671fc598df0f8c334d34e8d34d1249aaf Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sun, 23 Oct 2022 15:32:43 -0400
Subject: [PATCH 10/38] test: handle edge cases

---
 lib/fs.js                                |   7 +-
 lib/internal/fs/promises.js              |  19 ++--
 lib/internal/fs/watch/linux.js           | 138 ++++++++++++++---------
 test/parallel/test-fs-watch-enoent.js    |  30 +----
 test/parallel/test-fs-watch-recursive.js |   2 +
 test/parallel/test-fs-watch-ref-unref.js |  33 +++++-
 test/parallel/test-fs-watchfile.js       |   4 +-
 test/sequential/test-fs-watch.js         |  42 -------
 8 files changed, 133 insertions(+), 142 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index 7ba8a7738b68f0..a9cbc5ed59ee40 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -161,8 +161,7 @@ let FileReadStream;
 let FileWriteStream;
 
 const isWindows = process.platform === 'win32';
-const isLinux = process.platform === 'linux';
-
+const isOSX = process.platform === 'darwin';
 
 function showTruncateDeprecation() {
   if (truncateWarn) {
@@ -2303,7 +2302,9 @@ function watch(filename, options, listener) {
   // TODO(anonrig): Remove this when/if libuv supports it.
   // libuv does not support recursive file watch on Linux due to
   // the limitations of inotify.
-  if (options.recursive && isLinux) {
+  if (options.recursive != null && !isOSX && !isWindows) {
+    validateBoolean(options.recursive, 'options.recursive');
+
     watcher = new linuxWatcher.FSWatcher(options);
     watcher[linuxWatcher.kFSWatchStart](filename);
   } else {
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index acda765f210696..1dac9dd06b3aa4 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -121,7 +121,7 @@ const getDirectoryEntriesPromise = promisify(getDirents);
 const validateRmOptionsPromise = promisify(validateRmOptions);
 
 const isWindows = process.platform === 'win32';
-const isLinux = process.platform === 'linux';
+const isOSX = process.platform === 'darwin';
 
 let cpPromises;
 function lazyLoadCpPromises() {
@@ -920,16 +920,17 @@ async function readFile(path, options) {
 }
 
 function _watch(filename, options = kEmptyObject) {
-  validateString(filename, 'filename');
   validateObject(options, 'options');
 
-  // TODO(anonrig): Remove this when/if libuv supports it.
-  // libuv does not support recursive file watch on Linux due to
-  // the limitations of inotify.
-  if (options.recursive && isLinux) {
-    const watcher = new linuxWatcher.FSWatcher(options);
-    watcher[linuxWatcher.kFSWatchStart](filename);
-    return watcher;
+  if (options.recursive != null) {
+    // TODO(anonrig): Remove this when/if libuv supports it.
+    // libuv does not support recursive file watch on Linux due to
+    // the limitations of inotify.
+    if (!isOSX && !isWindows) {
+      const watcher = new linuxWatcher.FSWatcher(options);
+      watcher[linuxWatcher.kFSWatchStart](filename);
+      return watcher;
+    }
   }
 
   return watch(filename, options);
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index a3afe690d10bfd..04541201e295f0 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -1,14 +1,25 @@
 'use strict';
 
-const { SafeMap, Symbol, StringPrototypeStartsWith, SymbolAsyncIterator, Promise } = primordials;
-
+const {
+  SafeMap,
+  StringPrototypeStartsWith,
+  Symbol,
+  SymbolAsyncIterator,
+  ObjectCreate,
+} = primordials;
+
+const { Buffer } = require('buffer');
 const {
   ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
-  codes: { ERR_INVALID_ARG_TYPE, ERR_INVALID_ARG_VALUE },
+  codes: {
+    ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_ARG_VALUE,
+  },
 } = require('internal/errors');
+const { URL } = require('internal/url');
 const { kEmptyObject } = require('internal/util');
-const { validateString, validateObject, validateBoolean, validateAbortSignal } = require('internal/validators');
-const { EventEmitter } = require('events');
+const { validateObject, validateBoolean, validateAbortSignal, validateBuffer } = require('internal/validators');
+const { EventEmitter, once } = require('events');
 const path = require('path');
 
 const kFSWatchStart = Symbol('kFSWatchStart');
@@ -55,19 +66,20 @@ class FSWatcher extends EventEmitter {
 
     validateObject(options, 'options');
 
-    if (options.persistent !== undefined) {
+    if (options.persistent != null) {
       validateBoolean(options.persistent, 'options.persistent');
     }
 
-    if (options.recursive !== undefined) {
+    if (options.recursive != null) {
       validateBoolean(options.recursive, 'options.recursive');
     }
 
-    if (options.signal !== undefined) {
+    if (options.signal != null) {
       validateAbortSignal(options.signal, 'options.signal');
     }
 
-    if (options.encoding !== undefined) {
+    if (options.encoding != null) {
+      // This is required since on macOS and Windows it throws ERR_INVALID_ARG_VALUE
       if (typeof options.encoding !== 'string') {
         throw new ERR_INVALID_ARG_VALUE('encoding', 'options.encoding');
       }
@@ -77,6 +89,10 @@ class FSWatcher extends EventEmitter {
   }
 
   close() {
+    if (this.#closed) {
+      return;
+    }
+
     const { unwatchFile } = lazyLoadFsSync();
     this.#closed = true;
 
@@ -93,7 +109,12 @@ class FSWatcher extends EventEmitter {
    * @return {string}
    */
   #getPath(file) {
-    validateString(file, 'file');
+    const root = this.#files.get(this.#rootPath);
+
+    // When watching files the path is always the root.
+    if (root.isFile()) {
+      return this.#rootPath.slice(this.#rootPath.lastIndexOf('/') + 1);
+    }
 
     if (file === this.#rootPath) {
       return this.#rootPath;
@@ -103,8 +124,6 @@ class FSWatcher extends EventEmitter {
   }
 
   #unwatchFolder(file) {
-    validateString(file, 'file');
-
     const { unwatchFile } = lazyLoadFsSync();
 
     for (const filename of this.#files.keys()) {
@@ -115,8 +134,6 @@ class FSWatcher extends EventEmitter {
   }
 
   async #watchFolder(folder) {
-    validateString(folder, 'folder');
-
     const { opendir } = lazyLoadFsPromises();
 
     try {
@@ -146,8 +163,6 @@ class FSWatcher extends EventEmitter {
   }
 
   #watchFile(file) {
-    validateString(file, 'file');
-
     const { watchFile } = lazyLoadFsSync();
 
     if (this.#closed) {
@@ -174,38 +189,57 @@ class FSWatcher extends EventEmitter {
         if (statWatcher.isDirectory()) {
           this.#unwatchFolder(file);
         }
-      } else if (statWatcher.isDirectory()) {
-        this.emit('change', 'change', this.#getPath(file));
-        this.#watchFolder(file);
       } else {
         this.emit('change', 'change', this.#getPath(file));
+
+        if (statWatcher.isDirectory()) {
+          this.#watchFolder(file);
+        }
       }
     });
   }
 
   [kFSWatchStart](filename) {
-    validateString(filename, 'filename');
-
-    if (filename.length === 0) {
-      throw new ERR_INVALID_ARG_TYPE('filename');
+    if (typeof filename !== 'string' && !(filename instanceof Buffer) && !(filename instanceof URL)) {
+      throw new ERR_INVALID_ARG_TYPE('filename', 'string', filename);
     }
 
-    const file = lazyLoadFsSync().statSync(filename);
+    if (typeof filename === 'string') {
+      if (filename.length === 0) {
+        throw new ERR_INVALID_ARG_TYPE('filename', 'string', filename);
+      }
+    } else if (Buffer.isBuffer(filename)) {
+      validateBuffer(filename, 'filename');
 
-    this.#rootPath = filename;
-    this.#closed = false;
-    this.#files.set(filename, file);
+      if (filename.length === 0) {
+        throw new ERR_INVALID_ARG_TYPE('filename', 'buffer', filename);
+      }
+    }
 
-    if (file.isDirectory()) {
-      traverse(filename, this.#files)
-        .then(() => {
-          for (const f of this.#files.keys()) {
-            this.#watchFile(f);
-          }
-        });
-    } else {
-      this.#watchFile(filename);
+    try {
+      const file = lazyLoadFsSync().statSync(filename);
+
+      this.#rootPath = filename;
+      this.#closed = false;
+      this.#files.set(filename, file);
+
+      if (file.isDirectory()) {
+        traverse(filename, this.#files)
+          .then(() => {
+            for (const f of this.#files.keys()) {
+              this.#watchFile(f);
+            }
+          });
+      } else {
+        this.#watchFile(filename);
+      }
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        error.filename = filename;
+        throw error;
+      }
     }
+
   }
 
   ref() {
@@ -218,23 +252,23 @@ class FSWatcher extends EventEmitter {
     throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('unref');
   }
 
-  async next() {
-    if (this.#closed) {
-      return { __proto__: null, done: true };
-    }
-
-    const result = await new Promise((resolve) => {
-      this.once('change', (eventType, filename) => {
-        resolve({ eventType, filename });
-      });
+  [SymbolAsyncIterator]() {
+    const watcher = this;
+    return ObjectCreate({
+      __proto__: null,
+      async next() {
+        if (watcher.#closed) {
+          return { __proto__: null, done: true };
+        }
+        const { 0: eventType, 1: filename } = await once(watcher, 'change');
+        return {
+          __proto__: null,
+          value: { __proto__: null, eventType, filename },
+          done: false,
+        };
+      },
+      [SymbolAsyncIterator]() { return this; },
     });
-
-    return { __proto__: null, done: false, value: result };
-  }
-
-  // eslint-disable-next-line require-yield
-  *[SymbolAsyncIterator]() {
-    return this;
   }
 }
 
diff --git a/test/parallel/test-fs-watch-enoent.js b/test/parallel/test-fs-watch-enoent.js
index b76fa825e251a7..cb16b7c02f9f78 100644
--- a/test/parallel/test-fs-watch-enoent.js
+++ b/test/parallel/test-fs-watch-enoent.js
@@ -25,11 +25,9 @@ tmpdir.refresh();
   const validateError = (err) => {
     assert.strictEqual(err.path, nonexistentFile);
     assert.strictEqual(err.filename, nonexistentFile);
-    assert.strictEqual(err.syscall, 'watch');
+    assert.ok(err.syscall === 'watch' || err.syscall === 'stat');
     if (err.code === 'ENOENT') {
-      assert.strictEqual(
-        err.message,
-        `ENOENT: no such file or directory, watch '${nonexistentFile}'`);
+      assert.ok(err.message.startsWith('ENOENT: no such file or directory'));
       assert.strictEqual(err.errno, UV_ENOENT);
       assert.strictEqual(err.code, 'ENOENT');
     } else {  // AIX
@@ -47,27 +45,3 @@ tmpdir.refresh();
     validateError
   );
 }
-
-{
-  const file = path.join(tmpdir.path, 'file-to-watch');
-  fs.writeFileSync(file, 'test');
-  const watcher = fs.watch(file, common.mustNotCall());
-
-  const validateError = (err) => {
-    assert.strictEqual(err.path, nonexistentFile);
-    assert.strictEqual(err.filename, nonexistentFile);
-    assert.strictEqual(
-      err.message,
-      `ENOENT: no such file or directory, watch '${nonexistentFile}'`);
-    assert.strictEqual(err.errno, UV_ENOENT);
-    assert.strictEqual(err.code, 'ENOENT');
-    assert.strictEqual(err.syscall, 'watch');
-    fs.unlinkSync(file);
-    return true;
-  };
-
-  watcher.on('error', common.mustCall(validateError));
-
-  // Simulate the invocation from the binding
-  watcher._handle.onchange(UV_ENOENT, 'ENOENT', nonexistentFile);
-}
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 5cb3ddff9d03a9..2f2125959ba15e 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -2,6 +2,8 @@
 
 const common = require('../common');
 
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
 
 const assert = require('assert');
 const path = require('path');
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
index e51ecaf5b2fcc1..389e28fa45efd6 100644
--- a/test/parallel/test-fs-watch-ref-unref.js
+++ b/test/parallel/test-fs-watch-ref-unref.js
@@ -5,16 +5,37 @@ const common = require('../common');
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
+const assert = require('assert');
 const fs = require('fs');
 
+const isWindows = process.platform === 'win32';
+const isOSX = process.platform === 'darwin';
+const isLinux = process.platform === 'linux';
+
 const watcher = fs.watch(__filename, common.mustNotCall());
 
-watcher.unref();
+if (isOSX || isWindows) {
+  watcher.unref();
+
+  setTimeout(
+    common.mustCall(() => {
+      watcher.ref();
+      watcher.unref();
+    }),
+    common.platformTimeout(100)
+  );
+}
 
-setTimeout(
-  common.mustCall(() => {
+if (isLinux) {
+  assert.throws(() => {
     watcher.ref();
+  }, {
+    code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+  });
+
+  assert.throws(() => {
     watcher.unref();
-  }),
-  common.platformTimeout(100)
-);
+  }, {
+    code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+  });
+}
diff --git a/test/parallel/test-fs-watchfile.js b/test/parallel/test-fs-watchfile.js
index 8d1241bae8f1c2..4a94b16f9b63f2 100644
--- a/test/parallel/test-fs-watchfile.js
+++ b/test/parallel/test-fs-watchfile.js
@@ -90,9 +90,9 @@ if (common.isLinux || common.isOSX || common.isWindows) {
   fs.mkdir(dir, common.mustCall(function(err) {
     if (err) assert.fail(err);
 
-    fs.watch(dir, common.mustCall(function(eventType, filename) {
+    const handle = fs.watch(dir, common.mustCall(function(eventType, filename) {
       clearInterval(interval);
-      this._handle.close();
+      handle.close();
       assert.strictEqual(filename, 'foo.txt');
     }));
 
diff --git a/test/sequential/test-fs-watch.js b/test/sequential/test-fs-watch.js
index c5db585f3f4a59..ca71f9b5321fda 100644
--- a/test/sequential/test-fs-watch.js
+++ b/test/sequential/test-fs-watch.js
@@ -120,45 +120,3 @@ function repeat(fn) {
 {
   fs.watch(__filename, { persistent: false }, common.mustNotCall());
 }
-
-// Whitebox test to ensure that wrapped FSEvent is safe
-// https://github.com/joyent/node/issues/6690
-{
-  let oldhandle;
-  assert.throws(
-    () => {
-      const w = fs.watch(__filename, common.mustNotCall());
-      oldhandle = w._handle;
-      w._handle = { close: w._handle.close };
-      w.close();
-    },
-    {
-      name: 'Error',
-      code: 'ERR_INTERNAL_ASSERTION',
-      message: /^handle must be a FSEvent/,
-    }
-  );
-  oldhandle.close(); // clean up
-}
-
-{
-  let oldhandle;
-  assert.throws(
-    () => {
-      const w = fs.watch(__filename, common.mustNotCall());
-      oldhandle = w._handle;
-      const protoSymbols =
-        Object.getOwnPropertySymbols(Object.getPrototypeOf(w));
-      const kFSWatchStart =
-        protoSymbols.find((val) => val.toString() === 'Symbol(kFSWatchStart)');
-      w._handle = {};
-      w[kFSWatchStart]();
-    },
-    {
-      name: 'Error',
-      code: 'ERR_INTERNAL_ASSERTION',
-      message: /^handle must be a FSEvent/,
-    }
-  );
-  oldhandle.close(); // clean up
-}

From 89abb18ad6edcd880fef3ffdabd2afa299fca2d2 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sun, 23 Oct 2022 18:18:06 -0400
Subject: [PATCH 11/38] fs: handle more linux edge cases

---
 lib/fs.js                                |  2 +-
 lib/internal/fs/promises.js              |  4 +-
 lib/internal/fs/watch/linux.js           |  2 +-
 test/parallel/test-fs-watch-ref-unref.js | 50 ++++++++++++++----------
 4 files changed, 34 insertions(+), 24 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index a9cbc5ed59ee40..e6c2b0b1cacfd1 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -2302,7 +2302,7 @@ function watch(filename, options, listener) {
   // TODO(anonrig): Remove this when/if libuv supports it.
   // libuv does not support recursive file watch on Linux due to
   // the limitations of inotify.
-  if (options.recursive != null && !isOSX && !isWindows) {
+  if (options.recursive && !isOSX && !isWindows) {
     validateBoolean(options.recursive, 'options.recursive');
 
     watcher = new linuxWatcher.FSWatcher(options);
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 1dac9dd06b3aa4..17055276dd6cf8 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -923,10 +923,12 @@ function _watch(filename, options = kEmptyObject) {
   validateObject(options, 'options');
 
   if (options.recursive != null) {
+    validateBoolean(options.recursive, 'options.recursive');
+
     // TODO(anonrig): Remove this when/if libuv supports it.
     // libuv does not support recursive file watch on Linux due to
     // the limitations of inotify.
-    if (!isOSX && !isWindows) {
+    if (options.recursive && !isOSX && !isWindows) {
       const watcher = new linuxWatcher.FSWatcher(options);
       watcher[linuxWatcher.kFSWatchStart](filename);
       return watcher;
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 04541201e295f0..0d5cc1bc729a18 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -10,8 +10,8 @@ const {
 
 const { Buffer } = require('buffer');
 const {
-  ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
   codes: {
+    ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
     ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
   },
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
index 389e28fa45efd6..54e166087d0cef 100644
--- a/test/parallel/test-fs-watch-ref-unref.js
+++ b/test/parallel/test-fs-watch-ref-unref.js
@@ -12,30 +12,38 @@ const isWindows = process.platform === 'win32';
 const isOSX = process.platform === 'darwin';
 const isLinux = process.platform === 'linux';
 
-const watcher = fs.watch(__filename, common.mustNotCall());
+{
+  const watcher = fs.watch(__filename, common.mustNotCall());
 
-if (isOSX || isWindows) {
-  watcher.unref();
+  if (isOSX || isWindows) {
+    watcher.unref();
 
-  setTimeout(
-    common.mustCall(() => {
-      watcher.ref();
-      watcher.unref();
-    }),
-    common.platformTimeout(100)
-  );
+    setTimeout(
+      common.mustCall(() => {
+        watcher.ref();
+        watcher.unref();
+      }),
+      common.platformTimeout(100)
+    );
+  }
 }
 
-if (isLinux) {
-  assert.throws(() => {
-    watcher.ref();
-  }, {
-    code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
-  });
+{
+  const watcher = fs.watch(__filename, { recursive: true }, common.mustNotCall());
 
-  assert.throws(() => {
-    watcher.unref();
-  }, {
-    code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
-  });
+  if (isLinux) {
+    assert.throws(() => {
+      watcher.ref();
+    }, {
+      code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+    });
+
+    assert.throws(() => {
+      watcher.unref();
+    }, {
+      code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
+    });
+  }
+
+  watcher.close();
 }

From f15251f7dd646a925654999adde6a7472550bc91 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sun, 23 Oct 2022 18:28:43 -0400
Subject: [PATCH 12/38] fs: update requested changes

---
 doc/api/fs.md                                 |  12 +-
 lib/fs.js                                     |   4 +-
 lib/internal/fs/promises.js                   |   9 +-
 lib/internal/fs/watch/linux.js                | 127 +++++-----
 .../test-fs-watch-recursive-linux-promise.js  |  35 ++-
 .../parallel/test-fs-watch-recursive-linux.js | 235 +++++++++---------
 6 files changed, 215 insertions(+), 207 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 9c0204cd284e1d..e78f4c13ce46aa 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -6403,9 +6403,9 @@ By default, all {fs.FSWatcher} objects are "ref'ed", making it normally
 unnecessary to call `watcher.ref()` unless `watcher.unref()` had been
 called previously.
 
-`watcher.ref()` is not available on Linux. An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`
-exception will be thrown when the function is used on a platform that
-does not support it.
+`watcher.ref()` is only supported on macOS and Windows. An
+`ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown when the
+function is used on a platform that does not support it.
 
 #### `watcher.unref()`
 
@@ -6423,9 +6423,9 @@ event loop running, the process may exit before the {fs.FSWatcher} object's
 callback is invoked. Calling `watcher.unref()` multiple times will have
 no effect.
 
-`watcher.unref()` is not available on Linux. An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`
-exception will be thrown when the function is used on a platform that
-does not support it.
+`watcher.unref()` is only supported on macOS and Windows. An
+`ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown when the
+function is used on a platform that does not support it.
 
 ### Class: `fs.StatWatcher`
 
diff --git a/lib/fs.js b/lib/fs.js
index e6c2b0b1cacfd1..ec2514308652b5 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -2303,10 +2303,8 @@ function watch(filename, options, listener) {
   // libuv does not support recursive file watch on Linux due to
   // the limitations of inotify.
   if (options.recursive && !isOSX && !isWindows) {
-    validateBoolean(options.recursive, 'options.recursive');
-
     watcher = new linuxWatcher.FSWatcher(options);
-    watcher[linuxWatcher.kFSWatchStart](filename);
+    watcher[watchers.kFSWatchStart](filename);
   } else {
     watcher = new watchers.FSWatcher();
     watcher[watchers.kFSWatchStart](filename,
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 17055276dd6cf8..4cd5a48f0ee2cb 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -12,6 +12,7 @@ const {
   PromiseReject,
   SafeArrayIterator,
   SafePromisePrototypeFinally,
+  SymbolAsyncIterator,
   Symbol,
   Uint8Array,
 } = primordials;
@@ -88,7 +89,7 @@ const {
 } = require('internal/util');
 const { EventEmitterMixin } = require('internal/event_target');
 const { StringDecoder } = require('string_decoder');
-const { watch } = require('internal/fs/watchers');
+const { kFSWatchStart, watch } = require('internal/fs/watchers');
 const linuxWatcher = require('internal/fs/watch/linux');
 const { isIterable } = require('internal/streams/utils');
 const assert = require('internal/assert');
@@ -930,8 +931,8 @@ function _watch(filename, options = kEmptyObject) {
     // the limitations of inotify.
     if (options.recursive && !isOSX && !isWindows) {
       const watcher = new linuxWatcher.FSWatcher(options);
-      watcher[linuxWatcher.kFSWatchStart](filename);
-      return watcher;
+      watcher[kFSWatchStart](filename);
+      return watcher[SymbolAsyncIterator]();
     }
   }
 
@@ -968,7 +969,7 @@ module.exports = {
     writeFile,
     appendFile,
     readFile,
-    watch: _watch,
+    watch: !isOSX && !isWindows ? _watch : watch,
     constants,
   },
 
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 0d5cc1bc729a18..6295e06ccfb628 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -1,28 +1,30 @@
 'use strict';
 
 const {
+  SafePromiseAll,
+  PromisePrototypeThen,
   SafeMap,
+  SafeSet,
   StringPrototypeStartsWith,
-  Symbol,
+  StringPrototypeSlice,
+  StringPrototypeLastIndexOf,
   SymbolAsyncIterator,
-  ObjectCreate,
 } = primordials;
 
-const { Buffer } = require('buffer');
+const assert = require('assert');
+const { EventEmitter } = require('events');
 const {
   codes: {
     ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
-    ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
   },
 } = require('internal/errors');
-const { URL } = require('internal/url');
+const { getValidatedPath } = require('internal/fs/utils');
+const { kFSWatchStart } = require('internal/fs/watchers');
 const { kEmptyObject } = require('internal/util');
-const { validateObject, validateBoolean, validateAbortSignal, validateBuffer } = require('internal/validators');
-const { EventEmitter, once } = require('events');
+const { validateBoolean, validateAbortSignal } = require('internal/validators');
 const path = require('path');
-
-const kFSWatchStart = Symbol('kFSWatchStart');
+const { Readable } = require('stream');
 
 let internalSync;
 let internalPromises;
@@ -38,9 +40,10 @@ function lazyLoadFsSync() {
 }
 
 async function traverse(dir, files = new SafeMap()) {
-  const { readdir } = lazyLoadFsPromises();
+  const { opendir } = lazyLoadFsPromises();
 
-  const filenames = await readdir(dir, { withFileTypes: true });
+  const filenames = await opendir(dir);
+  const subdirectories = new SafeSet();
 
   for await (const file of filenames) {
     const f = path.join(dir, file.name);
@@ -48,10 +51,12 @@ async function traverse(dir, files = new SafeMap()) {
     files.set(f, file);
 
     if (file.isDirectory()) {
-      await traverse(f, files);
+      subdirectories.add(traverse(f, files));
     }
   }
 
+  await SafePromiseAll(subdirectories);
+
   return files;
 }
 
@@ -60,32 +65,32 @@ class FSWatcher extends EventEmitter {
   #closed = false;
   #files = new SafeMap();
   #rootPath = path.resolve();
+  #watchingFile = false;
 
   constructor(options = kEmptyObject) {
     super();
 
-    validateObject(options, 'options');
+    assert(typeof options === 'object' && options.recursive === true);
 
-    if (options.persistent != null) {
-      validateBoolean(options.persistent, 'options.persistent');
-    }
+    const { persistent, recursive, signal, encoding } = options;
 
-    if (options.recursive != null) {
-      validateBoolean(options.recursive, 'options.recursive');
+    if (persistent != null) {
+      validateBoolean(persistent, 'options.persistent');
     }
 
-    if (options.signal != null) {
-      validateAbortSignal(options.signal, 'options.signal');
+    if (signal != null) {
+      validateAbortSignal(signal, 'options.signal');
     }
 
-    if (options.encoding != null) {
+    if (encoding != null) {
       // This is required since on macOS and Windows it throws ERR_INVALID_ARG_VALUE
-      if (typeof options.encoding !== 'string') {
-        throw new ERR_INVALID_ARG_VALUE('encoding', 'options.encoding');
+      if (typeof encoding !== 'string') {
+        throw new ERR_INVALID_ARG_VALUE(encoding, 'options.encoding');
       }
     }
 
-    this.#options = options;
+
+    this.#options = { persistent, recursive, signal, encoding };
   }
 
   close() {
@@ -106,20 +111,21 @@ class FSWatcher extends EventEmitter {
 
   /**
    * @param {string} file
-   * @return {string}
+   * @return {string} the full path of `file` if we're watching a directory, or the
+                      filename when watching a file.
    */
   #getPath(file) {
-    const root = this.#files.get(this.#rootPath);
-
-    // When watching files the path is always the root.
-    if (root.isFile()) {
-      return this.#rootPath.slice(this.#rootPath.lastIndexOf('/') + 1);
+    // Always return the filename instead of the full path if watching a file (not a directory)
+    if (this.#watchingFile) {
+      return StringPrototypeSlice(this.#rootPath, StringPrototypeLastIndexOf(this.#rootPath, '/') + 1);
     }
 
+    // When watching directories, and root directory is changed, return the full file path
     if (file === this.#rootPath) {
       return this.#rootPath;
     }
 
+    // Otherwise return relative path for all files & folders
     return path.relative(this.#rootPath, file);
   }
 
@@ -140,12 +146,12 @@ class FSWatcher extends EventEmitter {
       const files = await opendir(folder);
 
       for await (const file of files) {
-        const f = path.join(folder, file.name);
-
         if (this.#closed) {
           break;
         }
 
+        const f = path.join(folder, file.name);
+
         if (!this.#files.has(f)) {
           this.#files.set(f, file);
           this.emit('change', 'rename', this.#getPath(f));
@@ -163,12 +169,11 @@ class FSWatcher extends EventEmitter {
   }
 
   #watchFile(file) {
-    const { watchFile } = lazyLoadFsSync();
-
     if (this.#closed) {
       return;
     }
 
+    const { watchFile } = lazyLoadFsSync();
     const existingStat = this.#files.get(file);
 
     watchFile(file, {
@@ -200,21 +205,7 @@ class FSWatcher extends EventEmitter {
   }
 
   [kFSWatchStart](filename) {
-    if (typeof filename !== 'string' && !(filename instanceof Buffer) && !(filename instanceof URL)) {
-      throw new ERR_INVALID_ARG_TYPE('filename', 'string', filename);
-    }
-
-    if (typeof filename === 'string') {
-      if (filename.length === 0) {
-        throw new ERR_INVALID_ARG_TYPE('filename', 'string', filename);
-      }
-    } else if (Buffer.isBuffer(filename)) {
-      validateBuffer(filename, 'filename');
-
-      if (filename.length === 0) {
-        throw new ERR_INVALID_ARG_TYPE('filename', 'buffer', filename);
-      }
-    }
+    filename = path.resolve(getValidatedPath(filename));
 
     try {
       const file = lazyLoadFsSync().statSync(filename);
@@ -222,14 +213,17 @@ class FSWatcher extends EventEmitter {
       this.#rootPath = filename;
       this.#closed = false;
       this.#files.set(filename, file);
+      this.#watchingFile = file.isFile();
 
       if (file.isDirectory()) {
-        traverse(filename, this.#files)
-          .then(() => {
+        PromisePrototypeThen(
+          traverse(filename, this.#files),
+          () => {
             for (const f of this.#files.keys()) {
               this.#watchFile(f);
             }
-          });
+          },
+        );
       } else {
         this.#watchFile(filename);
       }
@@ -253,22 +247,23 @@ class FSWatcher extends EventEmitter {
   }
 
   [SymbolAsyncIterator]() {
-    const watcher = this;
-    return ObjectCreate({
-      __proto__: null,
-      async next() {
-        if (watcher.#closed) {
-          return { __proto__: null, done: true };
-        }
-        const { 0: eventType, 1: filename } = await once(watcher, 'change');
-        return {
-          __proto__: null,
-          value: { __proto__: null, eventType, filename },
-          done: false,
-        };
+    const self = this;
+    const stream = new Readable({
+      destroy(error, callback) {
+        self.close();
+        callback(error);
       },
-      [SymbolAsyncIterator]() { return this; },
+      read() { },
+      autoDestroy: true,
+      objectMode: true,
+      signal: this.#options.signal,
     });
+
+    this.on('change', (eventType, filename) => {
+      stream.push({ eventType, filename });
+    });
+
+    return stream;
   }
 }
 
diff --git a/test/parallel/test-fs-watch-recursive-linux-promise.js b/test/parallel/test-fs-watch-recursive-linux-promise.js
index 294b2333147e30..0a4e29aaaf8a78 100644
--- a/test/parallel/test-fs-watch-recursive-linux-promise.js
+++ b/test/parallel/test-fs-watch-recursive-linux-promise.js
@@ -12,32 +12,47 @@ const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
 const fs = require('fs/promises');
+const fsSync = require('fs');
 
 const tmpdir = require('../common/tmpdir');
 const testDir = tmpdir.path;
 tmpdir.refresh();
 
-(async () => {
-  {
-    // Add a file to already watching folder
+(async function run() {
+  // Add a file to already watching folder
 
-    const testsubdir = await fs.mkdtemp(testDir + path.sep);
-    const file = `${randomUUID()}.txt`;
-    const filePath = path.join(testsubdir, file);
-    const watcher = fs.watch(testsubdir, { recursive: true });
+  const testsubdir = await fs.mkdtemp(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
 
-    setTimeout(async () => {
-      await fs.writeFile(filePath, 'world');
-    }, 100);
+  let interval;
 
+  process.nextTick(common.mustCall(() => {
+    interval = setInterval(() => {
+      fsSync.writeFileSync(filePath, 'world');
+    }, 500);
+  }));
+
+  try {
     for await (const payload of watcher) {
       const { eventType, filename } = payload;
 
       assert.ok(eventType === 'change' || eventType === 'rename');
 
       if (filename === file) {
+        clearInterval(interval);
+        interval = null;
         break;
       }
     }
+  } catch (error) {
+    if (error.name !== 'AbortError') {
+      assert.fail(error);
+    }
   }
+
+  process.on('exit', function() {
+    assert.ok(interval === null, 'watcher Object was not closed');
+  });
 })().then(common.mustCall());
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index 91511ab8eb796d..80bcb7fc6b79cd 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -19,123 +19,122 @@ const testDir = tmpdir.path;
 tmpdir.refresh();
 
 (async () => {
-  {
-    // Add a file to already watching folder
+  // Add a file to already watching folder
 
-    const testsubdir = fs.mkdtempSync(testDir + path.sep);
-    const file = `${randomUUID()}.txt`;
-    const filePath = path.join(testsubdir, file);
-    const watcher = fs.watch(testsubdir, { recursive: true });
-
-    let watcherClosed = false;
-    watcher.on('change', function(event, filename) {
-      assert.ok(event === 'change' || event === 'rename');
-
-      if (filename === file) {
-        watcher.close();
-        watcherClosed = true;
-      }
-    });
-
-    await setTimeout(100);
-    fs.writeFileSync(filePath, 'world');
-
-    process.on('exit', function() {
-      assert(watcherClosed, 'watcher Object was not closed');
-    });
-  }
-
-  {
-    // Add a folder to already watching folder
-
-    const testsubdir = fs.mkdtempSync(testDir + path.sep);
-    const file = `folder-${randomUUID()}`;
-    const filePath = path.join(testsubdir, file);
-    const watcher = fs.watch(testsubdir, { recursive: true });
-
-    let watcherClosed = false;
-    watcher.on('change', function(event, filename) {
-      assert.ok(event === 'change' || event === 'rename');
-
-      if (filename === file) {
-        watcher.close();
-        watcherClosed = true;
-      }
-    });
-
-    await setTimeout(100);
-    fs.mkdirSync(filePath);
-
-    process.on('exit', function() {
-      assert(watcherClosed, 'watcher Object was not closed');
-    });
-  }
-
-  {
-    // Add a file to newly created folder to already watching folder
-
-    const testsubdir = fs.mkdtempSync(testDir + path.sep);
-    const file = `folder-${randomUUID()}`;
-    const filePath = path.join(testsubdir, file);
-    const watcher = fs.watch(testsubdir, { recursive: true });
-    const childrenFile = `file-${randomUUID()}.txt`;
-    const childrenAbsolutePath = path.join(filePath, childrenFile);
-
-    let watcherClosed = false;
-
-    watcher.on('change', function(event, filename) {
-      assert.ok(event === 'change' || event === 'rename');
-
-      if (filename === path.join(file, childrenFile)) {
-        watcher.close();
-        watcherClosed = true;
-      }
-    });
-
-    await setTimeout(100);
-    fs.mkdirSync(filePath);
-    await setTimeout(100);
-    fs.writeFileSync(childrenAbsolutePath, 'world');
-
-    process.on('exit', function() {
-      assert(watcherClosed, 'watcher Object was not closed');
-    });
-  }
-
-  {
-    // Add a file to subfolder of a watching folder
-
-    const testsubdir = fs.mkdtempSync(testDir + path.sep);
-    const file = `folder-${randomUUID()}`;
-    const filePath = path.join(testsubdir, file);
-    fs.mkdirSync(filePath);
-
-    const subFolder = `subfolder-${randomUUID()}`;
-    const subfolderPath = path.join(filePath, subFolder);
-
-    fs.mkdirSync(subfolderPath);
-
-    const watcher = fs.watch(testsubdir, { recursive: true });
-    const childrenFile = `file-${randomUUID()}.txt`;
-    const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
-    const relativePath = path.join(file, subFolder, childrenFile);
-
-    let watcherClosed = false;
-
-    watcher.on('change', function(event, filename) {
-      assert.ok(event === 'change' || event === 'rename');
-
-      if (filename === relativePath) {
-        watcher.close();
-        watcherClosed = true;
-      }
-    });
-
-    await setTimeout(100);
-    fs.writeFileSync(childrenAbsolutePath, 'world');
-
-    process.on('exit', function() {
-      assert(watcherClosed, 'watcher Object was not closed');
-    });
-  }
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(100);
+  fs.writeFileSync(filePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a folder to already watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(100);
+  fs.mkdirSync(filePath);
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a file to newly created folder to already watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenAbsolutePath = path.join(filePath, childrenFile);
+
+  let watcherClosed = false;
+
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === path.join(file, childrenFile)) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(100);
+  fs.mkdirSync(filePath);
+  await setTimeout(100);
+  fs.writeFileSync(childrenAbsolutePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+
+(async () => {
+  // Add a file to subfolder of a watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  fs.mkdirSync(filePath);
+
+  const subFolder = `subfolder-${randomUUID()}`;
+  const subfolderPath = path.join(filePath, subFolder);
+
+  fs.mkdirSync(subfolderPath);
+
+  const watcher = fs.watch(testsubdir, { recursive: true });
+  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
+  const relativePath = path.join(file, subFolder, childrenFile);
+
+  let watcherClosed = false;
+
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === relativePath) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(100);
+  fs.writeFileSync(childrenAbsolutePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
 })().then(common.mustCall());

From cd240a6059d8ea49bf920d9fb3f2188310d64f1d Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Mon, 24 Oct 2022 17:05:18 -0400
Subject: [PATCH 13/38] fs: fix circular dependency

---
 lib/internal/fs/watch/linux.js | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 6295e06ccfb628..6d72b4ecd428a1 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -11,7 +11,6 @@ const {
   SymbolAsyncIterator,
 } = primordials;
 
-const assert = require('assert');
 const { EventEmitter } = require('events');
 const {
   codes: {
@@ -26,9 +25,15 @@ const { validateBoolean, validateAbortSignal } = require('internal/validators');
 const path = require('path');
 const { Readable } = require('stream');
 
+let internalAssert;
 let internalSync;
 let internalPromises;
 
+function lazyLoadAssert() {
+  // This is required due to circular dependency
+  internalAssert ??= require('assert');
+  return internalAssert;
+}
 function lazyLoadFsPromises() {
   internalPromises ??= require('fs/promises');
   return internalPromises;
@@ -70,7 +75,7 @@ class FSWatcher extends EventEmitter {
   constructor(options = kEmptyObject) {
     super();
 
-    assert(typeof options === 'object' && options.recursive === true);
+    lazyLoadAssert()(typeof options === 'object' && options.recursive === true);
 
     const { persistent, recursive, signal, encoding } = options;
 

From 6311cf5e9b657a35ce23f4921a553a7786bef26c Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Mon, 24 Oct 2022 17:09:45 -0400
Subject: [PATCH 14/38] fs: improve tests

---
 lib/internal/fs/watch/linux.js           |  1 +
 test/parallel/test-fs-watch-ref-unref.js | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 6d72b4ecd428a1..e7093b99444239 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -34,6 +34,7 @@ function lazyLoadAssert() {
   internalAssert ??= require('assert');
   return internalAssert;
 }
+
 function lazyLoadFsPromises() {
   internalPromises ??= require('fs/promises');
   return internalPromises;
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
index 54e166087d0cef..6ec1ad56a0cf61 100644
--- a/test/parallel/test-fs-watch-ref-unref.js
+++ b/test/parallel/test-fs-watch-ref-unref.js
@@ -13,9 +13,9 @@ const isOSX = process.platform === 'darwin';
 const isLinux = process.platform === 'linux';
 
 {
-  const watcher = fs.watch(__filename, common.mustNotCall());
-
   if (isOSX || isWindows) {
+    const watcher = fs.watch(__filename, common.mustNotCall());
+
     watcher.unref();
 
     setTimeout(
@@ -29,9 +29,9 @@ const isLinux = process.platform === 'linux';
 }
 
 {
-  const watcher = fs.watch(__filename, { recursive: true }, common.mustNotCall());
-
   if (isLinux) {
+    const watcher = fs.watch(__filename, { recursive: true }, common.mustNotCall());
+
     assert.throws(() => {
       watcher.ref();
     }, {
@@ -43,7 +43,7 @@ const isLinux = process.platform === 'linux';
     }, {
       code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
     });
-  }
 
-  watcher.close();
+    watcher.close();
+  }
 }

From d8d2a0c6e8d5860c3a2fe2c12da0765eafea3c4a Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Mon, 24 Oct 2022 18:15:01 -0400
Subject: [PATCH 15/38] test: add url as parameter for fs.watch

---
 .../parallel/test-fs-watch-recursive-linux.js | 29 ++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index 80bcb7fc6b79cd..ef9e5048fc6c38 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -13,6 +13,7 @@ const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
 const fs = require('fs');
+const { pathToFileURL } = require('url');
 
 const tmpdir = require('../common/tmpdir');
 const testDir = tmpdir.path;
@@ -101,7 +102,6 @@ tmpdir.refresh();
   });
 })().then(common.mustCall());
 
-
 (async () => {
   // Add a file to subfolder of a watching folder
 
@@ -138,3 +138,30 @@ tmpdir.refresh();
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
+
+(async () => {
+   // Add a file to already watching folder, and use URL as the path
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const url = new URL(pathToFileURL(testsubdir));
+  const watcher = fs.watch(url, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(100);
+  fs.writeFileSync(filePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());

From 632a4bc4864ccbb6cef5b6e1b2aa0b64d8ab67b7 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 25 Oct 2022 10:20:20 -0400
Subject: [PATCH 16/38] test: update lint errors

---
 test/parallel/test-fs-watch-recursive-linux.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index ef9e5048fc6c38..820b8dd19d82eb 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -140,7 +140,7 @@ tmpdir.refresh();
 })().then(common.mustCall());
 
 (async () => {
-   // Add a file to already watching folder, and use URL as the path
+  // Add a file to already watching folder, and use URL as the path
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
   const file = `${randomUUID()}.txt`;

From df610ef2348c0b7c4e4fefa25f0f453d822deaf9 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 25 Oct 2022 10:20:36 -0400
Subject: [PATCH 17/38] test: fix url error

---
 test/parallel/test-fs-watch-recursive-linux.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index 820b8dd19d82eb..fdc52ef53d36af 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -145,7 +145,7 @@ tmpdir.refresh();
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
   const file = `${randomUUID()}.txt`;
   const filePath = path.join(testsubdir, file);
-  const url = new URL(pathToFileURL(testsubdir));
+  const url = pathToFileURL(testsubdir);
   const watcher = fs.watch(url, { recursive: true });
 
   let watcherClosed = false;

From 8243dde24eb77cccd29ba1894a769e62f3c3ca49 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 25 Oct 2022 11:58:46 -0400
Subject: [PATCH 18/38] test: improve test-fs-watch-recursive.js

---
 test/parallel/test-fs-watch-recursive.js | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 2f2125959ba15e..5546ca1f82d749 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -29,21 +29,13 @@ watcher.on('change', function(event, filename) {
   if (filename !== relativePathOne)
     return;
 
-  if (common.isOSX || common.isLinux) {
-    clearInterval(interval);
-  }
   watcher.close();
   watcherClosed = true;
 });
 
-let interval;
-if (common.isOSX || common.isLinux) {
-  interval = setInterval(function() {
-    fs.writeFileSync(filepathOne, 'world');
-  }, 10);
-} else {
+setTimeout(common.mustCall(() => {
   fs.writeFileSync(filepathOne, 'world');
-}
+}), common.platformTimeout(100));
 
 process.on('exit', function() {
   assert(watcherClosed, 'watcher Object was not closed');

From 37a083963ed2d900851e35f2f06ce3151352ca3d Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 25 Oct 2022 11:58:59 -0400
Subject: [PATCH 19/38] fs: use arrays instead of sets

---
 lib/internal/fs/watch/linux.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index e7093b99444239..8c054e45be841c 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -1,10 +1,10 @@
 'use strict';
 
 const {
+  ArrayPrototypePush,
   SafePromiseAll,
   PromisePrototypeThen,
   SafeMap,
-  SafeSet,
   StringPrototypeStartsWith,
   StringPrototypeSlice,
   StringPrototypeLastIndexOf,
@@ -49,7 +49,7 @@ async function traverse(dir, files = new SafeMap()) {
   const { opendir } = lazyLoadFsPromises();
 
   const filenames = await opendir(dir);
-  const subdirectories = new SafeSet();
+  const subdirectories = [];
 
   for await (const file of filenames) {
     const f = path.join(dir, file.name);
@@ -57,7 +57,7 @@ async function traverse(dir, files = new SafeMap()) {
     files.set(f, file);
 
     if (file.isDirectory()) {
-      subdirectories.add(traverse(f, files));
+      ArrayPrototypePush(subdirectories, traverse(f, files));
     }
   }
 

From c7512efab42654108ef0a0ed11c3a04951d42888 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Tue, 25 Oct 2022 15:41:50 -0400
Subject: [PATCH 20/38] fs: remove lazy loading assert

---
 lib/internal/fs/watch/linux.js | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 8c054e45be841c..5843f4953c0e7c 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -12,6 +12,7 @@ const {
 } = primordials;
 
 const { EventEmitter } = require('events');
+const assert = require('internal/assert');
 const {
   codes: {
     ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
@@ -25,16 +26,9 @@ const { validateBoolean, validateAbortSignal } = require('internal/validators');
 const path = require('path');
 const { Readable } = require('stream');
 
-let internalAssert;
 let internalSync;
 let internalPromises;
 
-function lazyLoadAssert() {
-  // This is required due to circular dependency
-  internalAssert ??= require('assert');
-  return internalAssert;
-}
-
 function lazyLoadFsPromises() {
   internalPromises ??= require('fs/promises');
   return internalPromises;
@@ -76,7 +70,7 @@ class FSWatcher extends EventEmitter {
   constructor(options = kEmptyObject) {
     super();
 
-    lazyLoadAssert()(typeof options === 'object' && options.recursive === true);
+    assert(typeof options === 'object' && options.recursive === true);
 
     const { persistent, recursive, signal, encoding } = options;
 

From 6eee87833a673af4b8b120870bba84f6eda63209 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 08:53:14 -0400
Subject: [PATCH 21/38] fs: revert certain changes

---
 test/parallel/test-fs-watch-enoent.js         | 26 +++++++++++
 .../parallel/test-fs-watch-recursive-linux.js | 12 ++---
 test/sequential/test-fs-watch.js              | 46 +++++++++++++++++++
 3 files changed, 78 insertions(+), 6 deletions(-)

diff --git a/test/parallel/test-fs-watch-enoent.js b/test/parallel/test-fs-watch-enoent.js
index cb16b7c02f9f78..0d5bfc97315d0e 100644
--- a/test/parallel/test-fs-watch-enoent.js
+++ b/test/parallel/test-fs-watch-enoent.js
@@ -45,3 +45,29 @@ tmpdir.refresh();
     validateError
   );
 }
+
+{
+  if (common.isOSX || common.isWindows) {
+    const file = path.join(tmpdir.path, 'file-to-watch');
+    fs.writeFileSync(file, 'test');
+    const watcher = fs.watch(file, common.mustNotCall());
+
+    const validateError = (err) => {
+      assert.strictEqual(err.path, nonexistentFile);
+      assert.strictEqual(err.filename, nonexistentFile);
+      assert.strictEqual(
+        err.message,
+        `ENOENT: no such file or directory, watch '${nonexistentFile}'`);
+      assert.strictEqual(err.errno, UV_ENOENT);
+      assert.strictEqual(err.code, 'ENOENT');
+      assert.strictEqual(err.syscall, 'watch');
+      fs.unlinkSync(file);
+      return true;
+    };
+
+    watcher.on('error', common.mustCall(validateError));
+
+    // Simulate the invocation from the binding
+    watcher._handle.onchange(UV_ENOENT, 'ENOENT', nonexistentFile);
+  }
+}
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index fdc52ef53d36af..8298e2fe1b436e 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -37,7 +37,7 @@ tmpdir.refresh();
     }
   });
 
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(filePath, 'world');
 
   process.on('exit', function() {
@@ -63,7 +63,7 @@ tmpdir.refresh();
     }
   });
 
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.mkdirSync(filePath);
 
   process.on('exit', function() {
@@ -92,9 +92,9 @@ tmpdir.refresh();
     }
   });
 
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.mkdirSync(filePath);
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(childrenAbsolutePath, 'world');
 
   process.on('exit', function() {
@@ -131,7 +131,7 @@ tmpdir.refresh();
     }
   });
 
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(childrenAbsolutePath, 'world');
 
   process.on('exit', function() {
@@ -158,7 +158,7 @@ tmpdir.refresh();
     }
   });
 
-  await setTimeout(100);
+  await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(filePath, 'world');
 
   process.on('exit', function() {
diff --git a/test/sequential/test-fs-watch.js b/test/sequential/test-fs-watch.js
index ca71f9b5321fda..d94021072af498 100644
--- a/test/sequential/test-fs-watch.js
+++ b/test/sequential/test-fs-watch.js
@@ -120,3 +120,49 @@ function repeat(fn) {
 {
   fs.watch(__filename, { persistent: false }, common.mustNotCall());
 }
+
+// Whitebox test to ensure that wrapped FSEvent is safe
+// https://github.com/joyent/node/issues/6690
+{
+  if (common.isOSX || common.isWindows) {
+    let oldhandle;
+    assert.throws(
+      () => {
+        const w = fs.watch(__filename, common.mustNotCall());
+        oldhandle = w._handle;
+        w._handle = { close: w._handle.close };
+        w.close();
+      },
+      {
+        name: 'Error',
+        code: 'ERR_INTERNAL_ASSERTION',
+        message: /^handle must be a FSEvent/,
+      }
+    );
+    oldhandle.close(); // clean up
+  }
+}
+
+{
+  if (common.isOSX || common.isWindows) {
+    let oldhandle;
+    assert.throws(
+      () => {
+        const w = fs.watch(__filename, common.mustNotCall());
+        oldhandle = w._handle;
+        const protoSymbols =
+          Object.getOwnPropertySymbols(Object.getPrototypeOf(w));
+        const kFSWatchStart =
+          protoSymbols.find((val) => val.toString() === 'Symbol(kFSWatchStart)');
+        w._handle = {};
+        w[kFSWatchStart]();
+      },
+      {
+        name: 'Error',
+        code: 'ERR_INTERNAL_ASSERTION',
+        message: /^handle must be a FSEvent/,
+      }
+    );
+    oldhandle.close(); // clean up
+  }
+}

From a6906f24564c7b230b0c0ebf9b421b200da843c3 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 09:00:00 -0400
Subject: [PATCH 22/38] fs: add recursive validation to linux watcher

---
 lib/internal/fs/watch/linux.js                 |  7 ++++++-
 test/parallel/test-fs-watch-recursive-linux.js | 13 +++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 5843f4953c0e7c..923a6c48186898 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -70,10 +70,15 @@ class FSWatcher extends EventEmitter {
   constructor(options = kEmptyObject) {
     super();
 
-    assert(typeof options === 'object' && options.recursive === true);
+    assert(typeof options === 'object');
 
     const { persistent, recursive, signal, encoding } = options;
 
+    // TODO(anonrig): Add non-recursive support to linux-watcher for IBMi support.
+    if (recursive != null) {
+      validateBoolean(recursive, 'options.recursive');
+    }
+
     if (persistent != null) {
       validateBoolean(persistent, 'options.persistent');
     }
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
index 8298e2fe1b436e..5dbdabfec88c8e 100644
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ b/test/parallel/test-fs-watch-recursive-linux.js
@@ -165,3 +165,16 @@ tmpdir.refresh();
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
+
+(async () => {
+  // Handle non-boolean values for options.recursive
+
+  if (!common.isWindows && !common.isOSX) {
+    assert.throws(() => {
+      const testsubdir = fs.mkdtempSync(testDir + path.sep);
+      fs.watch(testsubdir, { recursive: '1' });
+    }, {
+      code: 'ERR_INVALID_ARG_TYPE',
+    });
+  }
+})().then(common.mustCall());

From 6061330241f52aa35a7cb698e7a4621b7b27176d Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 11:16:02 -0400
Subject: [PATCH 23/38] test: improve tests

---
 .../test-fs-watch-close-when-destroyed.js     |   7 +
 test/parallel/test-fs-watch-encoding.js       |   3 +
 .../parallel/test-fs-watch-recursive-linux.js | 180 ---------------
 ....js => test-fs-watch-recursive-promise.js} |   7 +
 test/parallel/test-fs-watch-recursive.js      | 217 ++++++++++++++++--
 5 files changed, 212 insertions(+), 202 deletions(-)
 delete mode 100644 test/parallel/test-fs-watch-recursive-linux.js
 rename test/parallel/{test-fs-watch-recursive-linux-promise.js => test-fs-watch-recursive-promise.js} (84%)

diff --git a/test/parallel/test-fs-watch-close-when-destroyed.js b/test/parallel/test-fs-watch-close-when-destroyed.js
index 2dfff953aa9214..d185599ee96a23 100644
--- a/test/parallel/test-fs-watch-close-when-destroyed.js
+++ b/test/parallel/test-fs-watch-close-when-destroyed.js
@@ -5,6 +5,13 @@
 
 const common = require('../common');
 
+// fs-watch on folders have limited capability in AIX.
+// The testcase makes use of folder watching, and causes
+// hang. This behavior is documented. Skip this for AIX.
+
+if (common.isAIX)
+  common.skip('folder watch capability is limited in AIX.');
+
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
diff --git a/test/parallel/test-fs-watch-encoding.js b/test/parallel/test-fs-watch-encoding.js
index 13b4dc340e43cf..0ef0881a6b5142 100644
--- a/test/parallel/test-fs-watch-encoding.js
+++ b/test/parallel/test-fs-watch-encoding.js
@@ -19,6 +19,9 @@ const common = require('../common');
 if (common.isAIX)
   common.skip('folder watch capability is limited in AIX.');
 
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
 const fs = require('fs');
 const path = require('path');
 
diff --git a/test/parallel/test-fs-watch-recursive-linux.js b/test/parallel/test-fs-watch-recursive-linux.js
deleted file mode 100644
index 5dbdabfec88c8e..00000000000000
--- a/test/parallel/test-fs-watch-recursive-linux.js
+++ /dev/null
@@ -1,180 +0,0 @@
-'use strict';
-
-const common = require('../common');
-const { setTimeout } = require('timers/promises');
-
-if (!common.hasCrypto)
-  common.skip('missing crypto');
-
-if (common.isIBMi)
-  common.skip('IBMi does not support `fs.watch()`');
-
-const { randomUUID } = require('crypto');
-const assert = require('assert');
-const path = require('path');
-const fs = require('fs');
-const { pathToFileURL } = require('url');
-
-const tmpdir = require('../common/tmpdir');
-const testDir = tmpdir.path;
-tmpdir.refresh();
-
-(async () => {
-  // Add a file to already watching folder
-
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
-
-  let watcherClosed = false;
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === file) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(filePath, 'world');
-
-  process.on('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
-(async () => {
-  // Add a folder to already watching folder
-
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
-
-  let watcherClosed = false;
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === file) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.mkdirSync(filePath);
-
-  process.on('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
-(async () => {
-  // Add a file to newly created folder to already watching folder
-
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
-  const childrenFile = `file-${randomUUID()}.txt`;
-  const childrenAbsolutePath = path.join(filePath, childrenFile);
-
-  let watcherClosed = false;
-
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === path.join(file, childrenFile)) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.mkdirSync(filePath);
-  await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(childrenAbsolutePath, 'world');
-
-  process.on('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
-(async () => {
-  // Add a file to subfolder of a watching folder
-
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
-  const filePath = path.join(testsubdir, file);
-  fs.mkdirSync(filePath);
-
-  const subFolder = `subfolder-${randomUUID()}`;
-  const subfolderPath = path.join(filePath, subFolder);
-
-  fs.mkdirSync(subfolderPath);
-
-  const watcher = fs.watch(testsubdir, { recursive: true });
-  const childrenFile = `file-${randomUUID()}.txt`;
-  const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
-  const relativePath = path.join(file, subFolder, childrenFile);
-
-  let watcherClosed = false;
-
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === relativePath) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(childrenAbsolutePath, 'world');
-
-  process.on('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
-(async () => {
-  // Add a file to already watching folder, and use URL as the path
-
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
-  const filePath = path.join(testsubdir, file);
-  const url = pathToFileURL(testsubdir);
-  const watcher = fs.watch(url, { recursive: true });
-
-  let watcherClosed = false;
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === file) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(filePath, 'world');
-
-  process.on('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
-(async () => {
-  // Handle non-boolean values for options.recursive
-
-  if (!common.isWindows && !common.isOSX) {
-    assert.throws(() => {
-      const testsubdir = fs.mkdtempSync(testDir + path.sep);
-      fs.watch(testsubdir, { recursive: '1' });
-    }, {
-      code: 'ERR_INVALID_ARG_TYPE',
-    });
-  }
-})().then(common.mustCall());
diff --git a/test/parallel/test-fs-watch-recursive-linux-promise.js b/test/parallel/test-fs-watch-recursive-promise.js
similarity index 84%
rename from test/parallel/test-fs-watch-recursive-linux-promise.js
rename to test/parallel/test-fs-watch-recursive-promise.js
index 0a4e29aaaf8a78..ecfbe92b424cc8 100644
--- a/test/parallel/test-fs-watch-recursive-linux-promise.js
+++ b/test/parallel/test-fs-watch-recursive-promise.js
@@ -8,6 +8,13 @@ if (!common.hasCrypto)
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
+// fs-watch on folders have limited capability in AIX.
+// The testcase makes use of folder watching, and causes
+// hang. This behavior is documented. Skip this for AIX.
+
+if (common.isAIX)
+  common.skip('folder watch capability is limited in AIX.');
+
 const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 5546ca1f82d749..4b404b90a89c76 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -1,42 +1,215 @@
 'use strict';
 
 const common = require('../common');
+const { setTimeout } = require('timers/promises');
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
 
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
+// fs-watch on folders have limited capability in AIX.
+// The testcase makes use of folder watching, and causes
+// hang. This behavior is documented. Skip this for AIX.
+
+if (common.isAIX)
+  common.skip('folder watch capability is limited in AIX.');
+
+const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
 const fs = require('fs');
+const { pathToFileURL } = require('url');
 
 const tmpdir = require('../common/tmpdir');
-
 const testDir = tmpdir.path;
-const filenameOne = 'watch.txt';
-
 tmpdir.refresh();
 
-const testsubdir = fs.mkdtempSync(testDir + path.sep);
-const relativePathOne = path.join(path.basename(testsubdir), filenameOne);
-const filepathOne = path.join(testsubdir, filenameOne);
-const watcher = fs.watch(testDir, { recursive: true });
+{
+  const filenameOne = 'watch.txt';
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const relativePathOne = path.join(path.basename(testsubdir), filenameOne);
+  const filepathOne = path.join(testsubdir, filenameOne);
+  const watcher = fs.watch(testDir, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    // Ignore stale events generated by mkdir and other tests
+    if (filename !== relativePathOne)
+      return;
+
+    watcher.close();
+    watcherClosed = true;
+  });
+
+  setTimeout(common.mustCall(() => {
+    fs.writeFileSync(filepathOne, 'world');
+  }), common.platformTimeout(100));
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+}
+
+(async () => {
+  // Add a file to already watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(filePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a folder to already watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.mkdirSync(filePath);
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a file to newly created folder to already watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenAbsolutePath = path.join(filePath, childrenFile);
+
+  let watcherClosed = false;
+
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === path.join(file, childrenFile)) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.mkdirSync(filePath);
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(childrenAbsolutePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a file to subfolder of a watching folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `folder-${randomUUID()}`;
+  const filePath = path.join(testsubdir, file);
+  fs.mkdirSync(filePath);
+
+  const subFolder = `subfolder-${randomUUID()}`;
+  const subfolderPath = path.join(filePath, subFolder);
+
+  fs.mkdirSync(subfolderPath);
+
+  const watcher = fs.watch(testsubdir, { recursive: true });
+  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
+  const relativePath = path.join(file, subFolder, childrenFile);
+
+  let watcherClosed = false;
+
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === relativePath) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(childrenAbsolutePath, 'world');
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a file to already watching folder, and use URL as the path
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const url = pathToFileURL(testsubdir);
+  const watcher = fs.watch(url, { recursive: true });
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
 
-let watcherClosed = false;
-watcher.on('change', function(event, filename) {
-  assert.ok(event === 'change' || event === 'rename');
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
 
-  // Ignore stale events generated by mkdir and other tests
-  if (filename !== relativePathOne)
-    return;
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(filePath, 'world');
 
-  watcher.close();
-  watcherClosed = true;
-});
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
 
-setTimeout(common.mustCall(() => {
-  fs.writeFileSync(filepathOne, 'world');
-}), common.platformTimeout(100));
+(async () => {
+  // Handle non-boolean values for options.recursive
 
-process.on('exit', function() {
-  assert(watcherClosed, 'watcher Object was not closed');
-});
+  if (!common.isWindows && !common.isOSX) {
+    assert.throws(() => {
+      const testsubdir = fs.mkdtempSync(testDir + path.sep);
+      fs.watch(testsubdir, { recursive: '1' });
+    }, {
+      code: 'ERR_INVALID_ARG_TYPE',
+    });
+  }
+})().then(common.mustCall());

From 9d596e8f386ae098773c03144ae50b6f064b298e Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 11:57:33 -0400
Subject: [PATCH 24/38] fs: do not throw abort errors

---
 lib/internal/fs/watch/linux.js                |  6 +++++-
 .../test-fs-watch-recursive-promise.js        | 20 +++++++------------
 2 files changed, 12 insertions(+), 14 deletions(-)

diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/watch/linux.js
index 923a6c48186898..43c497ecef090c 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/watch/linux.js
@@ -256,7 +256,11 @@ class FSWatcher extends EventEmitter {
     const stream = new Readable({
       destroy(error, callback) {
         self.close();
-        callback(error);
+        if (error.name !== 'AbortError') {
+          callback(error)
+        } else {
+          callback(null);
+        }
       },
       read() { },
       autoDestroy: true,
diff --git a/test/parallel/test-fs-watch-recursive-promise.js b/test/parallel/test-fs-watch-recursive-promise.js
index ecfbe92b424cc8..409dd67f51e1ef 100644
--- a/test/parallel/test-fs-watch-recursive-promise.js
+++ b/test/parallel/test-fs-watch-recursive-promise.js
@@ -41,21 +41,15 @@ tmpdir.refresh();
     }, 500);
   }));
 
-  try {
-    for await (const payload of watcher) {
-      const { eventType, filename } = payload;
+  for await (const payload of watcher) {
+    const { eventType, filename } = payload;
 
-      assert.ok(eventType === 'change' || eventType === 'rename');
+    assert.ok(eventType === 'change' || eventType === 'rename');
 
-      if (filename === file) {
-        clearInterval(interval);
-        interval = null;
-        break;
-      }
-    }
-  } catch (error) {
-    if (error.name !== 'AbortError') {
-      assert.fail(error);
+    if (filename === file) {
+      clearInterval(interval);
+      interval = null;
+      break;
     }
   }
 

From d94f3651391068feaa22468e430ecbce3f06534e Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 11:59:07 -0400
Subject: [PATCH 25/38] fs: rename recursive watch

---
 lib/fs.js                                              | 4 ++--
 lib/internal/fs/promises.js                            | 2 +-
 lib/internal/fs/{watch/linux.js => recursive_watch.js} | 2 +-
 test/parallel/test-bootstrap-modules.js                | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)
 rename lib/internal/fs/{watch/linux.js => recursive_watch.js} (99%)

diff --git a/lib/fs.js b/lib/fs.js
index ec2514308652b5..edccd57378d925 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -57,7 +57,7 @@ const {
 
 const pathModule = require('path');
 const { isArrayBufferView } = require('internal/util/types');
-const linuxWatcher = require('internal/fs/watch/linux');
+const recursiveWatcher = require('internal/fs/recursive_watch');
 
 // We need to get the statValues from the binding at the callsite since
 // it's re-initialized after deserialization.
@@ -2303,7 +2303,7 @@ function watch(filename, options, listener) {
   // libuv does not support recursive file watch on Linux due to
   // the limitations of inotify.
   if (options.recursive && !isOSX && !isWindows) {
-    watcher = new linuxWatcher.FSWatcher(options);
+    watcher = new recursiveWatcher.FSWatcher(options);
     watcher[watchers.kFSWatchStart](filename);
   } else {
     watcher = new watchers.FSWatcher();
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 4cd5a48f0ee2cb..53f8ece5cfe13d 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -90,7 +90,7 @@ const {
 const { EventEmitterMixin } = require('internal/event_target');
 const { StringDecoder } = require('string_decoder');
 const { kFSWatchStart, watch } = require('internal/fs/watchers');
-const linuxWatcher = require('internal/fs/watch/linux');
+const linuxWatcher = require('internal/fs/recursive_watch');
 const { isIterable } = require('internal/streams/utils');
 const assert = require('internal/assert');
 
diff --git a/lib/internal/fs/watch/linux.js b/lib/internal/fs/recursive_watch.js
similarity index 99%
rename from lib/internal/fs/watch/linux.js
rename to lib/internal/fs/recursive_watch.js
index 43c497ecef090c..5fc10194a649a3 100644
--- a/lib/internal/fs/watch/linux.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -257,7 +257,7 @@ class FSWatcher extends EventEmitter {
       destroy(error, callback) {
         self.close();
         if (error.name !== 'AbortError') {
-          callback(error)
+          callback(error);
         } else {
           callback(null);
         }
diff --git a/test/parallel/test-bootstrap-modules.js b/test/parallel/test-bootstrap-modules.js
index f5caa95a052947..c0698fe1a96b5c 100644
--- a/test/parallel/test-bootstrap-modules.js
+++ b/test/parallel/test-bootstrap-modules.js
@@ -65,9 +65,9 @@ const expectedModules = new Set([
   'NativeModule internal/fs/dir',
   'NativeModule internal/fs/promises',
   'NativeModule internal/fs/read_file_context',
+  'NativeModule internal/fs/recursive_watch',
   'NativeModule internal/fs/rimraf',
   'NativeModule internal/fs/utils',
-  'NativeModule internal/fs/watch/linux',
   'NativeModule internal/fs/watchers',
   'NativeModule internal/heap_utils',
   'NativeModule internal/histogram',

From b5161e5f3abfe63e37522626f3bdd6585fb6148a Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 12:34:46 -0400
Subject: [PATCH 26/38] fs: adjust implementation

---
 lib/internal/fs/recursive_watch.js               | 3 +--
 test/parallel/test-fs-watch-recursive-promise.js | 5 +++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index 5fc10194a649a3..626be91f025fb9 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -94,7 +94,6 @@ class FSWatcher extends EventEmitter {
       }
     }
 
-
     this.#options = { persistent, recursive, signal, encoding };
   }
 
@@ -272,7 +271,7 @@ class FSWatcher extends EventEmitter {
       stream.push({ eventType, filename });
     });
 
-    return stream;
+    return stream[SymbolAsyncIterator]();
   }
 }
 
diff --git a/test/parallel/test-fs-watch-recursive-promise.js b/test/parallel/test-fs-watch-recursive-promise.js
index 409dd67f51e1ef..f1a67101c94035 100644
--- a/test/parallel/test-fs-watch-recursive-promise.js
+++ b/test/parallel/test-fs-watch-recursive-promise.js
@@ -47,12 +47,13 @@ tmpdir.refresh();
     assert.ok(eventType === 'change' || eventType === 'rename');
 
     if (filename === file) {
-      clearInterval(interval);
-      interval = null;
       break;
     }
   }
 
+  clearInterval(interval);
+  interval = null;
+
   process.on('exit', function() {
     assert.ok(interval === null, 'watcher Object was not closed');
   });

From 6e4299dec2950a44669e8cd306b9aba89b38ef99 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Wed, 26 Oct 2022 18:35:37 -0400
Subject: [PATCH 27/38] fs: add ref and unref to fs.watch

---
 doc/api/fs.md                      |  8 --------
 lib/internal/fs/recursive_watch.js | 23 +++++++++++++++--------
 2 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index e78f4c13ce46aa..c7f7b9b16a5eae 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -6403,10 +6403,6 @@ By default, all {fs.FSWatcher} objects are "ref'ed", making it normally
 unnecessary to call `watcher.ref()` unless `watcher.unref()` had been
 called previously.
 
-`watcher.ref()` is only supported on macOS and Windows. An
-`ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown when the
-function is used on a platform that does not support it.
-
 #### `watcher.unref()`
 
 <!-- YAML
@@ -6423,10 +6419,6 @@ event loop running, the process may exit before the {fs.FSWatcher} object's
 callback is invoked. Calling `watcher.unref()` multiple times will have
 no effect.
 
-`watcher.unref()` is only supported on macOS and Windows. An
-`ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown when the
-function is used on a platform that does not support it.
-
 ### Class: `fs.StatWatcher`
 
 <!-- YAML
diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index 626be91f025fb9..ede40bffbe54c4 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -15,12 +15,11 @@ const { EventEmitter } = require('events');
 const assert = require('internal/assert');
 const {
   codes: {
-    ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
     ERR_INVALID_ARG_VALUE,
   },
 } = require('internal/errors');
 const { getValidatedPath } = require('internal/fs/utils');
-const { kFSWatchStart } = require('internal/fs/watchers');
+const { kFSWatchStart, StatWatcher } = require('internal/fs/watchers');
 const { kEmptyObject } = require('internal/util');
 const { validateBoolean, validateAbortSignal } = require('internal/validators');
 const path = require('path');
@@ -157,10 +156,10 @@ class FSWatcher extends EventEmitter {
         const f = path.join(folder, file.name);
 
         if (!this.#files.has(f)) {
-          this.#files.set(f, file);
           this.emit('change', 'rename', this.#getPath(f));
 
           if (file.isDirectory()) {
+            this.#files.set(f, file);
             await this.#watchFolder(f);
           } else {
             this.#watchFile(f);
@@ -216,10 +215,11 @@ class FSWatcher extends EventEmitter {
 
       this.#rootPath = filename;
       this.#closed = false;
-      this.#files.set(filename, file);
       this.#watchingFile = file.isFile();
 
       if (file.isDirectory()) {
+        this.#files.set(filename, file);
+
         PromisePrototypeThen(
           traverse(filename, this.#files),
           () => {
@@ -241,13 +241,19 @@ class FSWatcher extends EventEmitter {
   }
 
   ref() {
-    // This is kept to have the same API with FSWatcher
-    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('ref');
+    this.#files.forEach((file) => {
+      if (file instanceof StatWatcher) {
+        file.ref();
+      }
+    });
   }
 
   unref() {
-    // This is kept to have the same API with FSWatcher
-    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('unref');
+    this.#files.forEach((file) => {
+      if (file instanceof StatWatcher) {
+        file.unref();
+      }
+    });
   }
 
   [SymbolAsyncIterator]() {
@@ -255,6 +261,7 @@ class FSWatcher extends EventEmitter {
     const stream = new Readable({
       destroy(error, callback) {
         self.close();
+        // TODO(anonrig): Find the reason of 'break' inside for await Readable stream throwing AbortError.
         if (error.name !== 'AbortError') {
           callback(error);
         } else {

From 2e5d4b325b9d7a5e235b65b79b5aaea27d735c51 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Thu, 27 Oct 2022 09:22:14 -0400
Subject: [PATCH 28/38] fs: update async iterator implementation

---
 lib/internal/fs/recursive_watch.js            | 46 +++++++++----------
 .../test-fs-watch-recursive-promise.js        | 38 +++++++++++++++
 test/parallel/test-fs-watch-ref-unref.js      | 45 ++++--------------
 3 files changed, 69 insertions(+), 60 deletions(-)

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index ede40bffbe54c4..8179a83a8ae55c 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -3,6 +3,7 @@
 const {
   ArrayPrototypePush,
   SafePromiseAll,
+  Promise,
   PromisePrototypeThen,
   SafeMap,
   StringPrototypeStartsWith,
@@ -14,6 +15,7 @@ const {
 const { EventEmitter } = require('events');
 const assert = require('internal/assert');
 const {
+  AbortError,
   codes: {
     ERR_INVALID_ARG_VALUE,
   },
@@ -23,7 +25,6 @@ const { kFSWatchStart, StatWatcher } = require('internal/fs/watchers');
 const { kEmptyObject } = require('internal/util');
 const { validateBoolean, validateAbortSignal } = require('internal/validators');
 const path = require('path');
-const { Readable } = require('stream');
 
 let internalSync;
 let internalPromises;
@@ -257,28 +258,27 @@ class FSWatcher extends EventEmitter {
   }
 
   [SymbolAsyncIterator]() {
-    const self = this;
-    const stream = new Readable({
-      destroy(error, callback) {
-        self.close();
-        // TODO(anonrig): Find the reason of 'break' inside for await Readable stream throwing AbortError.
-        if (error.name !== 'AbortError') {
-          callback(error);
-        } else {
-          callback(null);
-        }
-      },
-      read() { },
-      autoDestroy: true,
-      objectMode: true,
-      signal: this.#options.signal,
-    });
-
-    this.on('change', (eventType, filename) => {
-      stream.push({ eventType, filename });
-    });
-
-    return stream[SymbolAsyncIterator]();
+    const { signal } = this.#options;
+    const promiseExecutor = signal == null ?
+      (resolve) => {
+        this.once('change', (eventType, filename) => {
+          resolve({ __proto__: null, value: { eventType, filename } });
+        });
+      } : (resolve, reject) => {
+        const onAbort = () => reject(new AbortError(undefined, { cause: signal.reason }));
+        if (signal.aborted) return onAbort();
+        signal.addEventListener('abort', onAbort, { __proto__: null, once: true });
+        this.once('change', (eventType, filename) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve({ __proto__: null, value: { eventType, filename } });
+        });
+      };
+    return {
+      next: () => (this.#closed ?
+        { __proto__: null, done: true } :
+        new Promise(promiseExecutor)),
+      [SymbolAsyncIterator]() { return this; },
+    };
   }
 }
 
diff --git a/test/parallel/test-fs-watch-recursive-promise.js b/test/parallel/test-fs-watch-recursive-promise.js
index f1a67101c94035..77674cdf06f2b3 100644
--- a/test/parallel/test-fs-watch-recursive-promise.js
+++ b/test/parallel/test-fs-watch-recursive-promise.js
@@ -35,6 +35,10 @@ tmpdir.refresh();
 
   let interval;
 
+  process.on('exit', function() {
+    assert.ok(interval === null, 'watcher Object was not closed');
+  });
+
   process.nextTick(common.mustCall(() => {
     interval = setInterval(() => {
       fsSync.writeFileSync(filePath, 'world');
@@ -53,8 +57,42 @@ tmpdir.refresh();
 
   clearInterval(interval);
   interval = null;
+})().then(common.mustCall());
 
+(async function() {
+  // Test that aborted AbortSignal are reported.
+  const testsubdir = await fs.mkdtemp(testDir + path.sep);
+  const error = new Error();
+  const watcher = fs.watch(testsubdir, { recursive: true, signal: AbortSignal.abort(error) });
+  await assert.rejects(async () => {
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of watcher);
+  }, { code: 'ABORT_ERR', cause: error });
+})().then(common.mustCall());
+
+(async function() {
+  // Test that with AbortController.
+  const testsubdir = await fs.mkdtemp(testDir + path.sep);
+  const file = `${randomUUID()}.txt`;
+  const filePath = path.join(testsubdir, file);
+  const error = new Error();
+  const ac = new AbortController();
+  const watcher = fs.watch(testsubdir, { recursive: true, signal: ac.signal });
+  let interval;
   process.on('exit', function() {
     assert.ok(interval === null, 'watcher Object was not closed');
   });
+  process.nextTick(common.mustCall(() => {
+    interval = setInterval(() => {
+      fsSync.writeFileSync(filePath, 'world');
+    }, 50);
+    ac.abort(error);
+  }));
+  await assert.rejects(async () => {
+    for await (const { eventType } of watcher) {
+      assert.ok(eventType === 'change' || eventType === 'rename');
+    }
+  }, { code: 'ABORT_ERR', cause: error });
+  clearInterval(interval);
+  interval = null;
 })().then(common.mustCall());
diff --git a/test/parallel/test-fs-watch-ref-unref.js b/test/parallel/test-fs-watch-ref-unref.js
index 6ec1ad56a0cf61..e51ecaf5b2fcc1 100644
--- a/test/parallel/test-fs-watch-ref-unref.js
+++ b/test/parallel/test-fs-watch-ref-unref.js
@@ -5,45 +5,16 @@ const common = require('../common');
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
-const assert = require('assert');
 const fs = require('fs');
 
-const isWindows = process.platform === 'win32';
-const isOSX = process.platform === 'darwin';
-const isLinux = process.platform === 'linux';
+const watcher = fs.watch(__filename, common.mustNotCall());
 
-{
-  if (isOSX || isWindows) {
-    const watcher = fs.watch(__filename, common.mustNotCall());
+watcher.unref();
 
+setTimeout(
+  common.mustCall(() => {
+    watcher.ref();
     watcher.unref();
-
-    setTimeout(
-      common.mustCall(() => {
-        watcher.ref();
-        watcher.unref();
-      }),
-      common.platformTimeout(100)
-    );
-  }
-}
-
-{
-  if (isLinux) {
-    const watcher = fs.watch(__filename, { recursive: true }, common.mustNotCall());
-
-    assert.throws(() => {
-      watcher.ref();
-    }, {
-      code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
-    });
-
-    assert.throws(() => {
-      watcher.unref();
-    }, {
-      code: 'ERR_FEATURE_UNAVAILABLE_ON_PLATFORM',
-    });
-
-    watcher.close();
-  }
-}
+  }),
+  common.platformTimeout(100)
+);

From cd3199b2a982db81d049d9da9e0bb1b9e2618122 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Fri, 28 Oct 2022 08:48:44 -0400
Subject: [PATCH 29/38] fs: improve watcher

---
 lib/internal/fs/recursive_watch.js            |  4 +-
 .../test-fs-watch-recursive-promise.js        |  8 +---
 test/parallel/test-fs-watch-recursive.js      | 39 ++++++++-----------
 3 files changed, 21 insertions(+), 30 deletions(-)

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index 8179a83a8ae55c..32654af3c0c109 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -2,7 +2,7 @@
 
 const {
   ArrayPrototypePush,
-  SafePromiseAll,
+  SafePromiseAllReturnVoid,
   Promise,
   PromisePrototypeThen,
   SafeMap,
@@ -55,7 +55,7 @@ async function traverse(dir, files = new SafeMap()) {
     }
   }
 
-  await SafePromiseAll(subdirectories);
+  await SafePromiseAllReturnVoid(subdirectories);
 
   return files;
 }
diff --git a/test/parallel/test-fs-watch-recursive-promise.js b/test/parallel/test-fs-watch-recursive-promise.js
index 77674cdf06f2b3..cb00a35db27417 100644
--- a/test/parallel/test-fs-watch-recursive-promise.js
+++ b/test/parallel/test-fs-watch-recursive-promise.js
@@ -2,9 +2,6 @@
 
 const common = require('../common');
 
-if (!common.hasCrypto)
-  common.skip('missing crypto');
-
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
@@ -15,7 +12,6 @@ if (common.isIBMi)
 if (common.isAIX)
   common.skip('folder watch capability is limited in AIX.');
 
-const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
 const fs = require('fs/promises');
@@ -29,7 +25,7 @@ tmpdir.refresh();
   // Add a file to already watching folder
 
   const testsubdir = await fs.mkdtemp(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
+  const file = '1.txt';
   const filePath = path.join(testsubdir, file);
   const watcher = fs.watch(testsubdir, { recursive: true });
 
@@ -73,7 +69,7 @@ tmpdir.refresh();
 (async function() {
   // Test that with AbortController.
   const testsubdir = await fs.mkdtemp(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
+  const file = '2.txt';
   const filePath = path.join(testsubdir, file);
   const error = new Error();
   const ac = new AbortController();
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 4b404b90a89c76..20375a59e18695 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -3,9 +3,6 @@
 const common = require('../common');
 const { setTimeout } = require('timers/promises');
 
-if (!common.hasCrypto)
-  common.skip('missing crypto');
-
 if (common.isIBMi)
   common.skip('IBMi does not support `fs.watch()`');
 
@@ -16,7 +13,6 @@ if (common.isIBMi)
 if (common.isAIX)
   common.skip('folder watch capability is limited in AIX.');
 
-const { randomUUID } = require('crypto');
 const assert = require('assert');
 const path = require('path');
 const fs = require('fs');
@@ -26,7 +22,7 @@ const tmpdir = require('../common/tmpdir');
 const testDir = tmpdir.path;
 tmpdir.refresh();
 
-{
+(async () => {
   const filenameOne = 'watch.txt';
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
   const relativePathOne = path.join(path.basename(testsubdir), filenameOne);
@@ -45,20 +41,19 @@ tmpdir.refresh();
     watcherClosed = true;
   });
 
-  setTimeout(common.mustCall(() => {
-    fs.writeFileSync(filepathOne, 'world');
-  }), common.platformTimeout(100));
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(filepathOne, 'world');
 
-  process.on('exit', function() {
+  process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
   });
-}
+})().then(common.mustCall());
 
 (async () => {
   // Add a file to already watching folder
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
+  const file = 'file-1.txt';
   const filePath = path.join(testsubdir, file);
   const watcher = fs.watch(testsubdir, { recursive: true });
 
@@ -75,7 +70,7 @@ tmpdir.refresh();
   await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(filePath, 'world');
 
-  process.on('exit', function() {
+  process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
@@ -84,7 +79,7 @@ tmpdir.refresh();
   // Add a folder to already watching folder
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
+  const file = 'folder-2';
   const filePath = path.join(testsubdir, file);
   const watcher = fs.watch(testsubdir, { recursive: true });
 
@@ -101,7 +96,7 @@ tmpdir.refresh();
   await setTimeout(common.platformTimeout(100));
   fs.mkdirSync(filePath);
 
-  process.on('exit', function() {
+  process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
@@ -110,10 +105,10 @@ tmpdir.refresh();
   // Add a file to newly created folder to already watching folder
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
+  const file = 'folder-3';
   const filePath = path.join(testsubdir, file);
   const watcher = fs.watch(testsubdir, { recursive: true });
-  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenFile = 'file-4.txt';
   const childrenAbsolutePath = path.join(filePath, childrenFile);
 
   let watcherClosed = false;
@@ -132,7 +127,7 @@ tmpdir.refresh();
   await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(childrenAbsolutePath, 'world');
 
-  process.on('exit', function() {
+  process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
@@ -141,17 +136,17 @@ tmpdir.refresh();
   // Add a file to subfolder of a watching folder
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `folder-${randomUUID()}`;
+  const file = 'folder-5';
   const filePath = path.join(testsubdir, file);
   fs.mkdirSync(filePath);
 
-  const subFolder = `subfolder-${randomUUID()}`;
+  const subFolder = 'subfolder-6';
   const subfolderPath = path.join(filePath, subFolder);
 
   fs.mkdirSync(subfolderPath);
 
   const watcher = fs.watch(testsubdir, { recursive: true });
-  const childrenFile = `file-${randomUUID()}.txt`;
+  const childrenFile = 'file-7.txt';
   const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
   const relativePath = path.join(file, subFolder, childrenFile);
 
@@ -169,7 +164,7 @@ tmpdir.refresh();
   await setTimeout(common.platformTimeout(100));
   fs.writeFileSync(childrenAbsolutePath, 'world');
 
-  process.on('exit', function() {
+  process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
   });
 })().then(common.mustCall());
@@ -178,7 +173,7 @@ tmpdir.refresh();
   // Add a file to already watching folder, and use URL as the path
 
   const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = `${randomUUID()}.txt`;
+  const file = 'file-8.txt';
   const filePath = path.join(testsubdir, file);
   const url = pathToFileURL(testsubdir);
   const watcher = fs.watch(url, { recursive: true });

From d69a56573c1346be840250d8dc591c49aa784dad Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 18:14:01 -0400
Subject: [PATCH 30/38] fs: rename linux watcher

---
 lib/internal/fs/promises.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 53f8ece5cfe13d..3f4f659b3dad15 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -90,7 +90,7 @@ const {
 const { EventEmitterMixin } = require('internal/event_target');
 const { StringDecoder } = require('string_decoder');
 const { kFSWatchStart, watch } = require('internal/fs/watchers');
-const linuxWatcher = require('internal/fs/recursive_watch');
+const nonNativeWatcher = require('internal/fs/recursive_watch');
 const { isIterable } = require('internal/streams/utils');
 const assert = require('internal/assert');
 
@@ -930,7 +930,7 @@ function _watch(filename, options = kEmptyObject) {
     // libuv does not support recursive file watch on Linux due to
     // the limitations of inotify.
     if (options.recursive && !isOSX && !isWindows) {
-      const watcher = new linuxWatcher.FSWatcher(options);
+      const watcher = new nonNativeWatcher.FSWatcher(options);
       watcher[kFSWatchStart](filename);
       return watcher[SymbolAsyncIterator]();
     }

From 28ee387008da7a203e49e2a789ab870c5b420cd4 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 18:33:27 -0400
Subject: [PATCH 31/38] fs: add support for symlinks

---
 lib/internal/fs/recursive_watch.js            | 26 +++---
 .../test-fs-watch-recursive-symlink.js        | 88 +++++++++++++++++++
 test/parallel/test-fs-watch-recursive.js      | 10 +--
 3 files changed, 106 insertions(+), 18 deletions(-)
 create mode 100644 test/parallel/test-fs-watch-recursive-symlink.js

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index 32654af3c0c109..d67bb84c278418 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -50,7 +50,9 @@ async function traverse(dir, files = new SafeMap()) {
 
     files.set(f, file);
 
-    if (file.isDirectory()) {
+    if (file.isSymbolicLink()) {
+      // Do not follow symbolic links
+    } else if (file.isDirectory()) {
       ArrayPrototypePush(subdirectories, traverse(f, files));
     }
   }
@@ -74,7 +76,7 @@ class FSWatcher extends EventEmitter {
 
     const { persistent, recursive, signal, encoding } = options;
 
-    // TODO(anonrig): Add non-recursive support to linux-watcher for IBMi support.
+    // TODO(anonrig): Add non-recursive support to non-native-watcher for IBMi & AIX support.
     if (recursive != null) {
       validateBoolean(recursive, 'options.recursive');
     }
@@ -133,7 +135,7 @@ class FSWatcher extends EventEmitter {
     return path.relative(this.#rootPath, file);
   }
 
-  #unwatchFolder(file) {
+  #unwatchFiles(file) {
     const { unwatchFile } = lazyLoadFsSync();
 
     for (const filename of this.#files.keys()) {
@@ -159,11 +161,14 @@ class FSWatcher extends EventEmitter {
         if (!this.#files.has(f)) {
           this.emit('change', 'rename', this.#getPath(f));
 
-          if (file.isDirectory()) {
-            this.#files.set(f, file);
-            await this.#watchFolder(f);
-          } else {
+          if (file.isFile()) {
             this.#watchFile(f);
+          } else {
+            this.#files.set(f, file);
+
+            if (file.isDirectory() && !file.isSymbolicLink()) {
+              await this.#watchFolder(f);
+            }
           }
         }
       }
@@ -194,14 +199,11 @@ class FSWatcher extends EventEmitter {
         // The file is now deleted
         this.#files.delete(file);
         this.emit('change', 'rename', this.#getPath(file));
-
-        if (statWatcher.isDirectory()) {
-          this.#unwatchFolder(file);
-        }
+        this.#unwatchFiles(file);
       } else {
         this.emit('change', 'change', this.#getPath(file));
 
-        if (statWatcher.isDirectory()) {
+        if (statWatcher.isDirectory() && !statWatcher.isSymbolicLink()) {
           this.#watchFolder(file);
         }
       }
diff --git a/test/parallel/test-fs-watch-recursive-symlink.js b/test/parallel/test-fs-watch-recursive-symlink.js
new file mode 100644
index 00000000000000..b606806c25c66a
--- /dev/null
+++ b/test/parallel/test-fs-watch-recursive-symlink.js
@@ -0,0 +1,88 @@
+'use strict';
+
+const common = require('../common');
+const { setTimeout } = require('timers/promises');
+
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
+// fs-watch on folders have limited capability in AIX.
+// The testcase makes use of folder watching, and causes
+// hang. This behavior is documented. Skip this for AIX.
+
+if (common.isAIX)
+  common.skip('folder watch capability is limited in AIX.');
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+
+const tmpdir = require('../common/tmpdir');
+const testDir = tmpdir.path;
+tmpdir.refresh();
+
+(async () => {
+  // Add a recursive symlink to the parent folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = 'file-1.txt';
+  const filePath = path.join(testsubdir, file);
+  const watcher = fs.watch(testsubdir, { recursive: true });
+
+  const symlinkFile = path.join(testsubdir, 'symlink-folder');
+  fs.symlinkSync(testsubdir, symlinkFile);
+
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+
+    if (filename === file) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(filePath, 'world');
+
+  process.once('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
+
+(async () => {
+  // Add a recursive symlink outside the parent folder
+
+  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const file = 'file-1.txt';
+  const filePath = path.join(testsubdir, file);
+
+  const trackFolder = path.join(testsubdir, 'tracking-folder');
+  const acceptableFile = 'acceptable-1.txt';
+  const acceptableFilePath = path.join(trackFolder, acceptableFile);
+  fs.mkdirSync(trackFolder);
+
+  const symlinkFile = path.join(trackFolder, 'symlink-folder');
+  fs.symlinkSync(testsubdir, symlinkFile);
+
+  const watcher = fs.watch(trackFolder, { recursive: true });
+  let watcherClosed = false;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(filename === 'symlink-folder' || filename === trackFolder || filename === acceptableFile);
+
+    if (filename === acceptableFile) {
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(filePath, 'world');
+  await setTimeout(common.platformTimeout(100));
+  fs.writeFileSync(acceptableFilePath, 'acceptable');
+
+  process.once('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+  });
+})().then(common.mustCall());
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 20375a59e18695..ea912f266c6413 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -33,12 +33,10 @@ tmpdir.refresh();
   watcher.on('change', function(event, filename) {
     assert.ok(event === 'change' || event === 'rename');
 
-    // Ignore stale events generated by mkdir and other tests
-    if (filename !== relativePathOne)
-      return;
-
-    watcher.close();
-    watcherClosed = true;
+    if (filename === relativePathOne) {
+      watcher.close();
+      watcherClosed = true;
+    }
   });
 
   await setTimeout(common.platformTimeout(100));

From 8e4e3ddf8955b45806fa39c9fd9dcd873aafc943 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 19:09:47 -0400
Subject: [PATCH 32/38] test: remove redundant test

---
 test/parallel/test-fs-watch-recursive.js | 25 ------------------------
 1 file changed, 25 deletions(-)

diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index ea912f266c6413..9aca7bffd590ec 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -22,31 +22,6 @@ const tmpdir = require('../common/tmpdir');
 const testDir = tmpdir.path;
 tmpdir.refresh();
 
-(async () => {
-  const filenameOne = 'watch.txt';
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const relativePathOne = path.join(path.basename(testsubdir), filenameOne);
-  const filepathOne = path.join(testsubdir, filenameOne);
-  const watcher = fs.watch(testDir, { recursive: true });
-
-  let watcherClosed = false;
-  watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-
-    if (filename === relativePathOne) {
-      watcher.close();
-      watcherClosed = true;
-    }
-  });
-
-  await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(filepathOne, 'world');
-
-  process.once('exit', function() {
-    assert(watcherClosed, 'watcher Object was not closed');
-  });
-})().then(common.mustCall());
-
 (async () => {
   // Add a file to already watching folder
 

From e6019be6615e8df3c5860e0aba6b4f8bc8130d3e Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 19:11:08 -0400
Subject: [PATCH 33/38] fs: rename to nonNativeWatcher

---
 lib/fs.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index edccd57378d925..41a90aaca1b28b 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -57,7 +57,7 @@ const {
 
 const pathModule = require('path');
 const { isArrayBufferView } = require('internal/util/types');
-const recursiveWatcher = require('internal/fs/recursive_watch');
+const nonNativeWatcher = require('internal/fs/recursive_watch');
 
 // We need to get the statValues from the binding at the callsite since
 // it's re-initialized after deserialization.
@@ -2303,7 +2303,7 @@ function watch(filename, options, listener) {
   // libuv does not support recursive file watch on Linux due to
   // the limitations of inotify.
   if (options.recursive && !isOSX && !isWindows) {
-    watcher = new recursiveWatcher.FSWatcher(options);
+    watcher = new nonNativeWatcher.FSWatcher(options);
     watcher[watchers.kFSWatchStart](filename);
   } else {
     watcher = new watchers.FSWatcher();

From 1e903a2d72bb332295683f7e09233576148da6d6 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 20:39:51 -0400
Subject: [PATCH 34/38] fs: update comments

---
 lib/fs.js                   | 2 +-
 lib/internal/fs/promises.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index 41a90aaca1b28b..a96067c2a1a2bb 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -2300,7 +2300,7 @@ function watch(filename, options, listener) {
   let watcher;
 
   // TODO(anonrig): Remove this when/if libuv supports it.
-  // libuv does not support recursive file watch on Linux due to
+  // libuv does not support recursive file watch on all platforms, e.g. Linux due to
   // the limitations of inotify.
   if (options.recursive && !isOSX && !isWindows) {
     watcher = new nonNativeWatcher.FSWatcher(options);
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 3f4f659b3dad15..d0bb034d4ef419 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -927,7 +927,7 @@ function _watch(filename, options = kEmptyObject) {
     validateBoolean(options.recursive, 'options.recursive');
 
     // TODO(anonrig): Remove this when/if libuv supports it.
-    // libuv does not support recursive file watch on Linux due to
+    // libuv does not support recursive file watch on all platforms, e.g. Linux due to
     // the limitations of inotify.
     if (options.recursive && !isOSX && !isWindows) {
       const watcher = new nonNativeWatcher.FSWatcher(options);

From b8b87f653f93969c4f0119d8ceb9def4f03b9b43 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sat, 29 Oct 2022 20:41:31 -0400
Subject: [PATCH 35/38] test: update symlink error message

---
 test/parallel/test-fs-watch-recursive-symlink.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/parallel/test-fs-watch-recursive-symlink.js b/test/parallel/test-fs-watch-recursive-symlink.js
index b606806c25c66a..4f279b402ed2f1 100644
--- a/test/parallel/test-fs-watch-recursive-symlink.js
+++ b/test/parallel/test-fs-watch-recursive-symlink.js
@@ -69,7 +69,7 @@ tmpdir.refresh();
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
     assert.ok(event === 'change' || event === 'rename');
-    assert.ok(filename === 'symlink-folder' || filename === trackFolder || filename === acceptableFile);
+    assert.ok(filename === 'symlink-folder' || filename === trackFolder || filename === acceptableFile, `Received filename ${filename}`);
 
     if (filename === acceptableFile) {
       watcher.close();

From ab4f1d2e042ff4196b3ef647cfc560066f698466 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sun, 30 Oct 2022 18:57:23 -0400
Subject: [PATCH 36/38] fs: update implementation

---
 lib/internal/fs/promises.js | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index d0bb034d4ef419..67781a12101015 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -12,7 +12,6 @@ const {
   PromiseReject,
   SafeArrayIterator,
   SafePromisePrototypeFinally,
-  SymbolAsyncIterator,
   Symbol,
   Uint8Array,
 } = primordials;
@@ -920,7 +919,7 @@ async function readFile(path, options) {
   return handleFdClose(readFileHandle(fd, options), fd.close);
 }
 
-function _watch(filename, options = kEmptyObject) {
+async function* _watch(filename, options = kEmptyObject) {
   validateObject(options, 'options');
 
   if (options.recursive != null) {
@@ -931,12 +930,13 @@ function _watch(filename, options = kEmptyObject) {
     // the limitations of inotify.
     if (options.recursive && !isOSX && !isWindows) {
       const watcher = new nonNativeWatcher.FSWatcher(options);
-      watcher[kFSWatchStart](filename);
-      return watcher[SymbolAsyncIterator]();
+      await watcher[kFSWatchStart](filename);
+      yield* watcher;
+      return;
     }
   }
 
-  return watch(filename, options);
+  yield* watch(filename, options);
 }
 
 module.exports = {

From c11bb628a293a5cb322939261e59707cc75e649d Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Sun, 30 Oct 2022 21:34:39 -0400
Subject: [PATCH 37/38] test: make fs.watch errors more strict

---
 lib/internal/fs/recursive_watch.js            |  65 +++++-----
 .../test-fs-watch-recursive-symlink.js        |  60 +++++----
 test/parallel/test-fs-watch-recursive.js      | 118 ++++++++++++------
 3 files changed, 145 insertions(+), 98 deletions(-)

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
index d67bb84c278418..197c4f1a461724 100644
--- a/lib/internal/fs/recursive_watch.js
+++ b/lib/internal/fs/recursive_watch.js
@@ -6,9 +6,8 @@ const {
   Promise,
   PromisePrototypeThen,
   SafeMap,
+  SafeSet,
   StringPrototypeStartsWith,
-  StringPrototypeSlice,
-  StringPrototypeLastIndexOf,
   SymbolAsyncIterator,
 } = primordials;
 
@@ -39,7 +38,7 @@ function lazyLoadFsSync() {
   return internalSync;
 }
 
-async function traverse(dir, files = new SafeMap()) {
+async function traverse(dir, files = new SafeMap(), symbolicLinks = new SafeSet()) {
   const { opendir } = lazyLoadFsPromises();
 
   const filenames = await opendir(dir);
@@ -50,8 +49,9 @@ async function traverse(dir, files = new SafeMap()) {
 
     files.set(f, file);
 
+    // Do not follow symbolic links
     if (file.isSymbolicLink()) {
-      // Do not follow symbolic links
+      symbolicLinks.add(f);
     } else if (file.isDirectory()) {
       ArrayPrototypePush(subdirectories, traverse(f, files));
     }
@@ -66,6 +66,7 @@ class FSWatcher extends EventEmitter {
   #options = null;
   #closed = false;
   #files = new SafeMap();
+  #symbolicFiles = new SafeSet();
   #rootPath = path.resolve();
   #watchingFile = false;
 
@@ -112,32 +113,15 @@ class FSWatcher extends EventEmitter {
     }
 
     this.#files.clear();
+    this.#symbolicFiles.clear();
     this.emit('close');
   }
 
-  /**
-   * @param {string} file
-   * @return {string} the full path of `file` if we're watching a directory, or the
-                      filename when watching a file.
-   */
-  #getPath(file) {
-    // Always return the filename instead of the full path if watching a file (not a directory)
-    if (this.#watchingFile) {
-      return StringPrototypeSlice(this.#rootPath, StringPrototypeLastIndexOf(this.#rootPath, '/') + 1);
-    }
-
-    // When watching directories, and root directory is changed, return the full file path
-    if (file === this.#rootPath) {
-      return this.#rootPath;
-    }
-
-    // Otherwise return relative path for all files & folders
-    return path.relative(this.#rootPath, file);
-  }
-
   #unwatchFiles(file) {
     const { unwatchFile } = lazyLoadFsSync();
 
+    this.#symbolicFiles.delete(file);
+
     for (const filename of this.#files.keys()) {
       if (StringPrototypeStartsWith(filename, file)) {
         unwatchFile(filename);
@@ -159,7 +143,11 @@ class FSWatcher extends EventEmitter {
         const f = path.join(folder, file.name);
 
         if (!this.#files.has(f)) {
-          this.emit('change', 'rename', this.#getPath(f));
+          this.emit('change', 'rename', path.relative(this.#rootPath, f));
+
+          if (file.isSymbolicLink()) {
+            this.#symbolicFiles.add(f);
+          }
 
           if (file.isFile()) {
             this.#watchFile(f);
@@ -187,25 +175,28 @@ class FSWatcher extends EventEmitter {
 
     watchFile(file, {
       persistent: this.#options.persistent,
-    }, (statWatcher, previousStatWatcher) => {
+    }, (currentStats, previousStats) => {
       if (existingStat && !existingStat.isDirectory() &&
-        statWatcher.nlink !== 0 && existingStat.mtime?.getTime() === statWatcher.mtime?.getTime()) {
+        currentStats.nlink !== 0 && existingStat.mtimeMs === currentStats.mtimeMs) {
         return;
       }
 
-      this.#files.set(file, statWatcher);
+      this.#files.set(file, currentStats);
 
-      if (statWatcher.birthtimeMs === 0 && previousStatWatcher.birthtimeMs !== 0) {
+      if (currentStats.birthtimeMs === 0 && previousStats.birthtimeMs !== 0) {
         // The file is now deleted
         this.#files.delete(file);
-        this.emit('change', 'rename', this.#getPath(file));
+        this.emit('change', 'rename', path.relative(this.#rootPath, file));
         this.#unwatchFiles(file);
-      } else {
-        this.emit('change', 'change', this.#getPath(file));
-
-        if (statWatcher.isDirectory() && !statWatcher.isSymbolicLink()) {
-          this.#watchFolder(file);
-        }
+      } else if (file === this.#rootPath && this.#watchingFile) {
+        // This case will only be triggered when watching a file with fs.watch
+        this.emit('change', 'change', path.basename(file));
+      } else if (this.#symbolicFiles.has(file)) {
+        // Stats from watchFile does not return correct value for currentStats.isSymbolicLink()
+        // Since it is only valid when using fs.lstat(). Therefore, check the existing symbolic files.
+        this.emit('change', 'rename', path.relative(this.#rootPath, file));
+      } else if (currentStats.isDirectory()) {
+        this.#watchFolder(file);
       }
     });
   }
@@ -224,7 +215,7 @@ class FSWatcher extends EventEmitter {
         this.#files.set(filename, file);
 
         PromisePrototypeThen(
-          traverse(filename, this.#files),
+          traverse(filename, this.#files, this.#symbolicFiles),
           () => {
             for (const f of this.#files.keys()) {
               this.#watchFile(f);
diff --git a/test/parallel/test-fs-watch-recursive-symlink.js b/test/parallel/test-fs-watch-recursive-symlink.js
index 4f279b402ed2f1..602ec58eab0d7a 100644
--- a/test/parallel/test-fs-watch-recursive-symlink.js
+++ b/test/parallel/test-fs-watch-recursive-symlink.js
@@ -24,19 +24,25 @@ tmpdir.refresh();
 (async () => {
   // Add a recursive symlink to the parent folder
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'file-1.txt';
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
+  const testDirectory = fs.mkdtempSync(testDir + path.sep);
 
-  const symlinkFile = path.join(testsubdir, 'symlink-folder');
-  fs.symlinkSync(testsubdir, symlinkFile);
+  // Do not use `testDirectory` as base. It will hang the tests.
+  const rootDirectory = path.join(testDirectory, 'test-1');
+  fs.mkdirSync(rootDirectory);
 
+  const filePath = path.join(rootDirectory, 'file.txt');
+
+  const symlinkFolder = path.join(rootDirectory, 'symlink-folder');
+  fs.symlinkSync(rootDirectory, symlinkFolder);
+
+
+  const watcher = fs.watch(rootDirectory, { recursive: true });
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename', `Received ${event}`);
+    assert.ok(filename === path.basename(symlinkFolder) || filename === path.basename(filePath), `Received ${filename}`);
 
-    if (filename === file) {
+    if (filename === path.basename(filePath)) {
       watcher.close();
       watcherClosed = true;
     }
@@ -51,36 +57,42 @@ tmpdir.refresh();
 })().then(common.mustCall());
 
 (async () => {
-  // Add a recursive symlink outside the parent folder
+  // This test checks how a symlink to outside the tracking folder can trigger change
+  // tmp/sub-directory/tracking-folder/symlink-folder -> tmp/sub-directory
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'file-1.txt';
-  const filePath = path.join(testsubdir, file);
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
 
-  const trackFolder = path.join(testsubdir, 'tracking-folder');
-  const acceptableFile = 'acceptable-1.txt';
-  const acceptableFilePath = path.join(trackFolder, acceptableFile);
-  fs.mkdirSync(trackFolder);
+  const subDirectory = path.join(rootDirectory, 'sub-directory');
+  fs.mkdirSync(subDirectory);
 
-  const symlinkFile = path.join(trackFolder, 'symlink-folder');
-  fs.symlinkSync(testsubdir, symlinkFile);
+  const trackingSubDirectory = path.join(subDirectory, 'tracking-folder');
+  fs.mkdirSync(trackingSubDirectory);
 
-  const watcher = fs.watch(trackFolder, { recursive: true });
+  const symlinkFolder = path.join(trackingSubDirectory, 'symlink-folder');
+  fs.symlinkSync(subDirectory, symlinkFolder);
+
+  const forbiddenFile = path.join(subDirectory, 'forbidden.txt');
+  const acceptableFile = path.join(trackingSubDirectory, 'acceptable.txt');
+
+  const watcher = fs.watch(trackingSubDirectory, { recursive: true });
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
-    assert.ok(filename === 'symlink-folder' || filename === trackFolder || filename === acceptableFile, `Received filename ${filename}`);
+    // macOS will only change the following events:
+    // { event: 'rename', filename: 'symlink-folder' }
+    // { event: 'rename', filename: 'acceptable.txt' }
+    assert.ok(event === 'rename', `Received ${event}`);
+    assert.ok(filename === path.basename(symlinkFolder) || filename === path.basename(acceptableFile), `Received ${filename}`);
 
-    if (filename === acceptableFile) {
+    if (filename === path.basename(acceptableFile)) {
       watcher.close();
       watcherClosed = true;
     }
   });
 
   await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(filePath, 'world');
+  fs.writeFileSync(forbiddenFile, 'world');
   await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(acceptableFilePath, 'acceptable');
+  fs.writeFileSync(acceptableFile, 'acceptable');
 
   process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
diff --git a/test/parallel/test-fs-watch-recursive.js b/test/parallel/test-fs-watch-recursive.js
index 9aca7bffd590ec..a4c22bfbd2ce11 100644
--- a/test/parallel/test-fs-watch-recursive.js
+++ b/test/parallel/test-fs-watch-recursive.js
@@ -25,23 +25,25 @@ tmpdir.refresh();
 (async () => {
   // Add a file to already watching folder
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'file-1.txt';
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-1');
+  fs.mkdirSync(testDirectory);
 
+  const testFile = path.join(testDirectory, 'file-1.txt');
+
+  const watcher = fs.watch(testDirectory, { recursive: true });
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename');
 
-    if (filename === file) {
+    if (filename === path.basename(testFile)) {
       watcher.close();
       watcherClosed = true;
     }
   });
 
   await setTimeout(common.platformTimeout(100));
-  fs.writeFileSync(filePath, 'world');
+  fs.writeFileSync(testFile, 'world');
 
   process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
@@ -51,23 +53,25 @@ tmpdir.refresh();
 (async () => {
   // Add a folder to already watching folder
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'folder-2';
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-2');
+  fs.mkdirSync(testDirectory);
 
+  const testFile = path.join(testDirectory, 'folder-2');
+
+  const watcher = fs.watch(testDirectory, { recursive: true });
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename');
 
-    if (filename === file) {
+    if (filename === path.basename(testFile)) {
       watcher.close();
       watcherClosed = true;
     }
   });
 
   await setTimeout(common.platformTimeout(100));
-  fs.mkdirSync(filePath);
+  fs.mkdirSync(testFile);
 
   process.once('exit', function() {
     assert(watcherClosed, 'watcher Object was not closed');
@@ -77,19 +81,23 @@ tmpdir.refresh();
 (async () => {
   // Add a file to newly created folder to already watching folder
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'folder-3';
-  const filePath = path.join(testsubdir, file);
-  const watcher = fs.watch(testsubdir, { recursive: true });
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-3');
+  fs.mkdirSync(testDirectory);
+
+  const filePath = path.join(testDirectory, 'folder-3');
+
   const childrenFile = 'file-4.txt';
   const childrenAbsolutePath = path.join(filePath, childrenFile);
+  const childrenRelativePath = path.join(path.basename(filePath), childrenFile);
 
+  const watcher = fs.watch(testDirectory, { recursive: true });
   let watcherClosed = false;
-
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename');
+    assert.ok(filename === path.basename(filePath) || filename === childrenRelativePath);
 
-    if (filename === path.join(file, childrenFile)) {
+    if (filename === childrenRelativePath) {
       watcher.close();
       watcherClosed = true;
     }
@@ -108,25 +116,25 @@ tmpdir.refresh();
 (async () => {
   // Add a file to subfolder of a watching folder
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-4');
+  fs.mkdirSync(testDirectory);
+
   const file = 'folder-5';
-  const filePath = path.join(testsubdir, file);
+  const filePath = path.join(testDirectory, file);
   fs.mkdirSync(filePath);
 
-  const subFolder = 'subfolder-6';
-  const subfolderPath = path.join(filePath, subFolder);
-
+  const subfolderPath = path.join(filePath, 'subfolder-6');
   fs.mkdirSync(subfolderPath);
 
-  const watcher = fs.watch(testsubdir, { recursive: true });
   const childrenFile = 'file-7.txt';
   const childrenAbsolutePath = path.join(subfolderPath, childrenFile);
-  const relativePath = path.join(file, subFolder, childrenFile);
+  const relativePath = path.join(file, path.basename(subfolderPath), childrenFile);
 
+  const watcher = fs.watch(testDirectory, { recursive: true });
   let watcherClosed = false;
-
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename');
 
     if (filename === relativePath) {
       watcher.close();
@@ -145,17 +153,19 @@ tmpdir.refresh();
 (async () => {
   // Add a file to already watching folder, and use URL as the path
 
-  const testsubdir = fs.mkdtempSync(testDir + path.sep);
-  const file = 'file-8.txt';
-  const filePath = path.join(testsubdir, file);
-  const url = pathToFileURL(testsubdir);
-  const watcher = fs.watch(url, { recursive: true });
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-5');
+  fs.mkdirSync(testDirectory);
+
+  const filePath = path.join(testDirectory, 'file-8.txt');
+  const url = pathToFileURL(testDirectory);
 
+  const watcher = fs.watch(url, { recursive: true });
   let watcherClosed = false;
   watcher.on('change', function(event, filename) {
-    assert.ok(event === 'change' || event === 'rename');
+    assert.ok(event === 'rename');
 
-    if (filename === file) {
+    if (filename === path.basename(filePath)) {
       watcher.close();
       watcherClosed = true;
     }
@@ -169,6 +179,40 @@ tmpdir.refresh();
   });
 })().then(common.mustCall());
 
+(async () => {
+  // Watch a file (not a folder) using fs.watch
+
+  const rootDirectory = fs.mkdtempSync(testDir + path.sep);
+  const testDirectory = path.join(rootDirectory, 'test-6');
+  fs.mkdirSync(testDirectory);
+
+  const filePath = path.join(testDirectory, 'only-file.txt');
+  fs.writeFileSync(filePath, 'hello');
+
+  const watcher = fs.watch(filePath, { recursive: true });
+  let watcherClosed = false;
+  let interval;
+  watcher.on('change', function(event, filename) {
+    assert.ok(event === 'change');
+
+    if (filename === path.basename(filePath)) {
+      clearInterval(interval);
+      interval = null;
+      watcher.close();
+      watcherClosed = true;
+    }
+  });
+
+  interval = setInterval(() => {
+    fs.writeFileSync(filePath, 'world');
+  }, common.platformTimeout(10));
+
+  process.on('exit', function() {
+    assert(watcherClosed, 'watcher Object was not closed');
+    assert.ok(interval === null, 'interval should have been null');
+  });
+})().then(common.mustCall());
+
 (async () => {
   // Handle non-boolean values for options.recursive
 

From bddb83f15381339dfe7c4d96cc21c81302cef7e9 Mon Sep 17 00:00:00 2001
From: Yagiz Nizipli <yagiz@nizipli.com>
Date: Mon, 31 Oct 2022 10:43:45 -0400
Subject: [PATCH 38/38] fs: add documentation

---
 doc/api/fs.md               | 3 +++
 lib/fs.js                   | 4 ++--
 lib/internal/fs/promises.js | 4 ++--
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index c7f7b9b16a5eae..b0d7eaeac2fbe0 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -4320,6 +4320,9 @@ The `atime` and `mtime` arguments follow these rules:
 <!-- YAML
 added: v0.5.10
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/45098
+    description: Added recursive support for Linux, AIX and IBMi.
   - version:
       - v15.9.0
       - v14.17.0
diff --git a/lib/fs.js b/lib/fs.js
index a96067c2a1a2bb..4ffc55c8abbd70 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -2300,8 +2300,8 @@ function watch(filename, options, listener) {
   let watcher;
 
   // TODO(anonrig): Remove this when/if libuv supports it.
-  // libuv does not support recursive file watch on all platforms, e.g. Linux due to
-  // the limitations of inotify.
+  // As of November 2022, libuv does not support recursive file watch on all platforms,
+  // e.g. Linux due to the limitations of inotify.
   if (options.recursive && !isOSX && !isWindows) {
     watcher = new nonNativeWatcher.FSWatcher(options);
     watcher[watchers.kFSWatchStart](filename);
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 67781a12101015..9f5adb62113215 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -926,8 +926,8 @@ async function* _watch(filename, options = kEmptyObject) {
     validateBoolean(options.recursive, 'options.recursive');
 
     // TODO(anonrig): Remove this when/if libuv supports it.
-    // libuv does not support recursive file watch on all platforms, e.g. Linux due to
-    // the limitations of inotify.
+    // As of November 2022, libuv does not support recursive file watch on all platforms,
+    // e.g. Linux due to the limitations of inotify.
     if (options.recursive && !isOSX && !isWindows) {
       const watcher = new nonNativeWatcher.FSWatcher(options);
       await watcher[kFSWatchStart](filename);