Function watch

lib/fs.js:3032–3087

* Watches for the changes on `filename`. * @param {string | Buffer | URL} filename * @param {string | { * persistent?: boolean; * recursive?: boolean; * encoding?: string; * signal?: AbortSignal; * throwIfNoEntry?: boolean; * }} [options] * @param {( * eventType?: string, *

(filename, options, listener)

 * @returns {watchers.FSWatcher}
 */
function watch(filename, options, listener) {
  const h = vfsState.handlers;
  if (h !== null) {
    const result = h.watch(filename, options, listener);
    if (result !== undefined) return result;
  }
  if (typeof options === 'function') {
    listener = options;
  }
  options = getOptions(options);

  // Don't make changes directly on options object
  options = copyObject(options);

  if (options.persistent === undefined) options.persistent = true;
  if (options.recursive === undefined) options.recursive = false;
  if (options.throwIfNoEntry === undefined) options.throwIfNoEntry = true;

  let watcher;
  const watchers = require('internal/fs/watchers');
  const path = getValidatedPath(filename);
  // TODO(anonrig): Remove non-native watcher when/if libuv supports recursive.
  // 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 && !isMacOS && !isWindows) {
    const nonNativeWatcher = require('internal/fs/recursive_watch');
    watcher = new nonNativeWatcher.FSWatcher(options);
    watcher[watchers.kFSWatchStart](path);
  } else {
    watcher = new watchers.FSWatcher();
    watcher[watchers.kFSWatchStart](path,
                                    options.persistent,
                                    options.recursive,
                                    options.encoding,
                                    options.ignore,
                                    options.throwIfNoEntry);
  }

  if (listener) {
    watcher.addListener('change', listener);
  }
  if (options.signal) {
    if (options.signal.aborted) {
      process.nextTick(() => watcher.close());
    } else {
      const listener = () => watcher.close();
      kResistStopPropagation ??= require('internal/event_target').kResistStopPropagation;
      options.signal.addEventListener('abort', listener, { __proto__: null, [kResistStopPropagation]: true });
      watcher.once('close', () => {
        options.signal.removeEventListener('abort', listener);
      });
    }
  }

  return watcher;
}