Function watch

lib/internal/fs/watchers.js:380–485

(filename, options = kEmptyObject)

let kResistStopPropagation;

async function* watch(filename, options = kEmptyObject) {
  const path = toNamespacedPath(getValidatedPath(filename));
  validateObject(options, 'options');

  const {
    persistent = true,
    recursive = false,
    encoding = 'utf8',
    maxQueue = 2048,
    overflow = 'ignore',
    signal,
    ignore,
  } = options;

  validateBoolean(persistent, 'options.persistent');
  validateBoolean(recursive, 'options.recursive');
  validateInteger(maxQueue, 'options.maxQueue');
  validateOneOf(overflow, 'options.overflow', ['ignore', 'error']);
  validateAbortSignal(signal, 'options.signal');
  validateIgnoreOption(ignore, 'options.ignore');

  if (encoding && !isEncoding(encoding)) {
    const reason = 'is invalid encoding';
    throw new ERR_INVALID_ARG_VALUE('encoding', encoding, reason);
  }

  if (signal?.aborted)
    throw new AbortError(undefined, { cause: signal.reason });

  const handle = new FSEvent();
  const ignoreMatcher = createIgnoreMatcher(ignore);
  let { promise, resolve } = PromiseWithResolvers();
  const queue = [];
  const oncancel = () => {
    handle.close();
    resolve();
  };

  try {
    if (signal) {
      kResistStopPropagation ??= require('internal/event_target').kResistStopPropagation;
      signal.addEventListener('abort', oncancel, { __proto__: null, once: true, [kResistStopPropagation]: true });
    }
    handle.onchange = (status, eventType, filename) => {
      if (status < 0) {
        const error = new UVException({
          errno: status,
          syscall: 'watch',
          path: filename,
        });
        error.filename = filename;
        handle.close();
        ArrayPrototypePush(queue, error);
        resolve();
        return;
      }
      // Filter events if ignore matcher is set and filename is available
      if (filename != null && ignoreMatcher?.(filename)) {