fs: add ignore option to fs.watch

[mcollina]

Add an ignore option to fs.watch() to filter filesystem events.

Type: string | RegExp | Function | Array<string | RegExp | Function>

fs.watch(dir, { ignore: '*.log' });
fs.watch(dir, { ignore: /\.tmp$/ });
fs.watch(dir, { ignore: (f) => f.startsWith('.') });
fs.watch(dir, { ignore: ['*.log', /\.tmp$/] });

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (637bda0) to head (7571d97).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61433      +/-   ##
==========================================
+ Coverage   88.51%   89.86%   +1.34%     
==========================================
  Files         704      671      -33     
  Lines      208883   203297    -5586     
  Branches    40334    39098    -1236     
==========================================
- Hits       184890   182684    -2206     
+ Misses      15977    12966    -3011     
+ Partials     8016     7647     -369     

Files with missing lines	Coverage Δ
lib/fs.js	98.19% <100.00%> (+<0.01%)	⬆️
lib/internal/fs/recursive_watch.js	84.91% <100.00%> (+0.54%)	⬆️
lib/internal/fs/watchers.js	87.29% <100.00%> (+2.12%)	⬆️
lib/internal/validators.js	98.25% <100.00%> (+0.09%)	⬆️

... and 95 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/70890/

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[avivkeller]

We have a lazy utility in internal utils

[aduh95]

It looks like there's a consistent failure on macOS

AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

true !== false

    at process.<anonymous> (/Users/runner/work/node/node/node/test/parallel/test-fs-watch-ignore-recursive.js:165:12)
    at process.emit (node:events:520:22) {
  generatedMessage: true,
  code: 'ERR_ASSERTION',
  actual: true,
  expected: false,
  operator: 'strictEqual',
  diff: 'simple'
}

Node.js v26.0.0-pre
Command: out/Release/node /Users/runner/work/node/node/node/test/parallel/test-fs-watch-ignore-recursive.js

[lpinca]

Can't users already do this by ignoring the events they are not interested in? What are the advantages for having this option in core?

[mcollina]

Can't users already do this by ignoring the events they are not interested in? What are the advantages for having this option in core?

Unfortunately that's not identical. Let's imagine there is a big folder full of files (e.g. node_modules). Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

It's not equivalent, and it's needded for any pratical application of watch.

[lpinca]

Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

From a glance, it seems that this PR does not touch the native layer and all the changes are still returned by the OS for later filtering. Am I reading this wrong?

[mcollina]

Watching all those directories and files would create a huge pressure on the OS, because each file watching are data structures kernel-land. There are limits on how many of these a process can create (on some OSes).

From a glance, it seems that this PR does not touch the native layer and all the changes are still returned by the OS for later filtering. Am I reading this wrong?

@lpinca nope, fixed.

[lpinca]

Ok, it makes sense now.

[nodejs-github-bot]

Landed in f700203