FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

fs: add ignore option to fs.watch · nodejs/node@ffbf579 · GitHub

/ node Public

Commit ffbf579

Browse files
mcollina
authored and
juanarbol
committed
fs: add ignore option to fs.watch
Add an `ignore` option to `fs.watch()` to filter filesystem events. Supports string globs, RegExp, functions, or arrays of these. PR-URL: #61433 Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Moshe Atlow <moshe@atlow.co.il> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
1 parent b68524e commit ffbf579

8 files changed

Lines changed: 831 additions & 6 deletions

File tree

‎doc/api/fs.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1801,6 +1801,10 @@ added:
18011801
* `overflow` {string} Either `'ignore'` or `'throw'` when there are more events to be
18021802
queued than `maxQueue` allows. `'ignore'` means overflow events are dropped and a
18031803
warning is emitted, while `'throw'` means to throw an exception. **Default:** `'ignore'`.
1804+
* `ignore` {string|RegExp|Function|Array} Pattern(s) to ignore. Strings are
1805+
glob patterns (using [`minimatch`][]), RegExp patterns are tested against
1806+
the filename, and functions receive the filename and return `true` to
1807+
ignore. **Default:** `undefined`.
18041808
* Returns: {AsyncIterator} of objects with the properties:
18051809
* `eventType` {string} The type of change
18061810
* `filename` {string|Buffer|null} The name of the file changed.
@@ -4761,6 +4765,10 @@ changes:
47614765
* `encoding` {string} Specifies the character encoding to be used for the
47624766
filename passed to the listener. **Default:** `'utf8'`.
47634767
* `signal` {AbortSignal} allows closing the watcher with an AbortSignal.
4768+
* `ignore` {string|RegExp|Function|Array} Pattern(s) to ignore. Strings are
4769+
glob patterns (using [`minimatch`][]), RegExp patterns are tested against
4770+
the filename, and functions receive the filename and return `true` to
4771+
ignore. **Default:** `undefined`.
47644772
* `listener` {Function|undefined} **Default:** `undefined`
47654773
* `eventType` {string}
47664774
* `filename` {string|Buffer|null}
@@ -8516,6 +8524,7 @@ the file contents.
85168524
[`fsPromises.utimes()`]: #fspromisesutimespath-atime-mtime
85178525
[`inotify(7)`]: https://man7.org/linux/man-pages/man7/inotify.7.html
85188526
[`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
8527+
[`minimatch`]: https://github.com/isaacs/minimatch
85198528
[`util.promisify()`]: util.md#utilpromisifyoriginal
85208529
[bigints]: https://tc39.github.io/proposal-bigint
85218530
[caveats]: #caveats

‎lib/fs.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2554,7 +2554,8 @@ function watch(filename, options, listener) {
25542554
watcher[watchers.kFSWatchStart](path,
25552555
options.persistent,
25562556
options.recursive,
2557-
options.encoding);
2557+
options.encoding,
2558+
options.ignore);
25582559
}
25592560

25602561
if (listener) {

‎lib/internal/fs/recursive_watch.js‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ const {
1717
},
1818
} = require('internal/errors');
1919
const { getValidatedPath } = require('internal/fs/utils');
20-
const { kFSWatchStart, StatWatcher } = require('internal/fs/watchers');
20+
const { createIgnoreMatcher, kFSWatchStart, StatWatcher } = require('internal/fs/watchers');
2121
const { kEmptyObject } = require('internal/util');
22-
const { validateBoolean, validateAbortSignal } = require('internal/validators');
22+
const { validateBoolean, validateAbortSignal, validateIgnoreOption } = require('internal/validators');
2323
const {
2424
basename: pathBasename,
2525
join: pathJoin,
@@ -44,13 +44,14 @@ class FSWatcher extends EventEmitter {
4444
#symbolicFiles = new SafeSet();
4545
#rootPath = pathResolve();
4646
#watchingFile = false;
47+
#ignoreMatcher = null;
4748

4849
constructor(options = kEmptyObject) {
4950
super();
5051

5152
assert(typeof options === 'object');
5253

53-
const { persistent, recursive, signal, encoding } = options;
54+
const { persistent, recursive, signal, encoding, ignore } = options;
5455

5556
// TODO(anonrig): Add non-recursive support to non-native-watcher for IBMi & AIX support.
5657
if (recursive != null) {
@@ -72,6 +73,9 @@ class FSWatcher extends EventEmitter {
7273
}
7374
}
7475

76+
validateIgnoreOption(ignore, 'options.ignore');
77+
this.#ignoreMatcher = createIgnoreMatcher(ignore);
78+
7579
this.#options = { persistent, recursive, signal, encoding };
7680
}
7781

@@ -118,9 +122,15 @@ class FSWatcher extends EventEmitter {
118122
}
119123

120124
const f = pathJoin(folder, file.name);
125+
const relativePath = pathRelative(this.#rootPath, f);
126+
127+
// Skip watching ignored paths entirely to avoid kernel resource pressure
128+
if (this.#ignoreMatcher?.(relativePath)) {
129+
continue;
130+
}
121131

122132
if (!this.#files.has(f)) {
123-
this.emit('change', 'rename', pathRelative(this.#rootPath, f));
133+
this.emit('change', 'rename', relativePath);
124134

125135
if (file.isSymbolicLink()) {
126136
this.#symbolicFiles.add(f);

‎lib/internal/fs/watchers.js‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
'use strict';
22

33
const {
4+
ArrayIsArray,
45
ArrayPrototypePush,
56
ArrayPrototypeShift,
67
Error,
78
FunctionPrototypeCall,
89
ObjectDefineProperty,
910
ObjectSetPrototypeOf,
1011
PromiseWithResolvers,
12+
RegExpPrototypeExec,
1113
Symbol,
1214
} = primordials;
1315

@@ -22,6 +24,9 @@ const {
2224

2325
const {
2426
kEmptyObject,
27+
getLazy,
28+
isWindows,
29+
isMacOS,
2530
} = require('internal/util');
2631

2732
const {
@@ -48,6 +53,7 @@ const { toNamespacedPath } = require('path');
4853
const {
4954
validateAbortSignal,
5055
validateBoolean,
56+
validateIgnoreOption,
5157
validateObject,
5258
validateUint32,
5359
validateInteger,
@@ -60,6 +66,8 @@ const {
6066
},
6167
} = require('buffer');
6268

69+
const { isRegExp } = require('internal/util/types');
70+
6371
const assert = require('internal/assert');
6472

6573
const kOldStatus = Symbol('kOldStatus');
@@ -71,6 +79,50 @@ const KFSStatWatcherRefCount = Symbol('KFSStatWatcherRefCount');
7179
const KFSStatWatcherMaxRefCount = Symbol('KFSStatWatcherMaxRefCount');
7280
const kFSStatWatcherAddOrCleanRef = Symbol('kFSStatWatcherAddOrCleanRef');
7381

82+
const lazyMinimatch = getLazy(() => require('internal/deps/minimatch/index'));
83+
84+
/**
85+
* Creates an ignore matcher function from the ignore option.
86+
* @param {string | RegExp | Function | Array} ignore - The ignore patterns
87+
* @returns {Function | null} A function that returns true if filename should be ignored
88+
*/
89+
function createIgnoreMatcher(ignore) {
90+
if (ignore == null) return null;
91+
const matchers = ArrayIsArray(ignore) ? ignore : [ignore];
92+
const compiled = [];
93+
94+
for (let i = 0; i < matchers.length; i++) {
95+
const matcher = matchers[i];
96+
if (typeof matcher === 'string') {
97+
const mm = new (lazyMinimatch().Minimatch)(matcher, {
98+
__proto__: null,
99+
nocase: isWindows || isMacOS,
100+
windowsPathsNoEscape: true,
101+
nonegate: true,
102+
nocomment: true,
103+
optimizationLevel: 2,
104+
platform: process.platform,
105+
// matchBase allows patterns without slashes to match the basename
106+
// e.g., '*.log' matches 'subdir/file.log'
107+
matchBase: true,
108+
});
109+
ArrayPrototypePush(compiled, (filename) => mm.match(filename));
110+
} else if (isRegExp(matcher)) {
111+
ArrayPrototypePush(compiled, (filename) => RegExpPrototypeExec(matcher, filename) !== null);
112+
} else {
113+
// Function
114+
ArrayPrototypePush(compiled, matcher);
115+
}
116+
}
117+
118+
return (filename) => {
119+
for (let i = 0; i < compiled.length; i++) {
120+
if (compiled[i](filename)) return true;
121+
}
122+
return false;
123+
};
124+
}
125+
74126
function emitStop(self) {
75127
self.emit('stop');
76128
}
@@ -199,6 +251,7 @@ function FSWatcher() {
199251

200252
this._handle = new FSEvent();
201253
this._handle[owner_symbol] = this;
254+
this._ignoreMatcher = null;
202255

203256
this._handle.onchange = (status, eventType, filename) => {
204257
// TODO(joyeecheung): we may check self._handle.initialized here
@@ -219,6 +272,10 @@ function FSWatcher() {
219272
error.filename = filename;
220273
this.emit('error', error);
221274
} else {
275+
// Filter events if ignore matcher is set and filename is available
276+
if (filename != null && this._ignoreMatcher?.(filename)) {
277+
return;
278+
}
222279
this.emit('change', eventType, filename);
223280
}
224281
};
@@ -235,7 +292,8 @@ ObjectSetPrototypeOf(FSWatcher, EventEmitter);
235292
FSWatcher.prototype[kFSWatchStart] = function(filename,
236293
persistent,
237294
recursive,
238-
encoding) {
295+
encoding,
296+
ignore) {
239297
if (this._handle === null) { // closed
240298
return;
241299
}
@@ -246,6 +304,10 @@ FSWatcher.prototype[kFSWatchStart] = function(filename,
246304

247305
filename = getValidatedPath(filename, 'filename');
248306

307+
// Validate and create the ignore matcher
308+
validateIgnoreOption(ignore, 'options.ignore');
309+
this._ignoreMatcher = createIgnoreMatcher(ignore);
310+
249311
const err = this._handle.start(toNamespacedPath(filename),
250312
persistent,
251313
recursive,
@@ -319,13 +381,15 @@ async function* watch(filename, options = kEmptyObject) {
319381
maxQueue = 2048,
320382
overflow = 'ignore',
321383
signal,
384+
ignore,
322385
} = options;
323386

324387
validateBoolean(persistent, 'options.persistent');
325388
validateBoolean(recursive, 'options.recursive');
326389
validateInteger(maxQueue, 'options.maxQueue');
327390
validateOneOf(overflow, 'options.overflow', ['ignore', 'error']);
328391
validateAbortSignal(signal, 'options.signal');
392+
validateIgnoreOption(ignore, 'options.ignore');
329393

330394
if (encoding && !isEncoding(encoding)) {
331395
const reason = 'is invalid encoding';
@@ -336,6 +400,7 @@ async function* watch(filename, options = kEmptyObject) {
336400
throw new AbortError(undefined, { cause: signal.reason });
337401

338402
const handle = new FSEvent();
403+
const ignoreMatcher = createIgnoreMatcher(ignore);
339404
let { promise, resolve } = PromiseWithResolvers();
340405
const queue = [];
341406
const oncancel = () => {
@@ -361,6 +426,10 @@ async function* watch(filename, options = kEmptyObject) {
361426
resolve();
362427
return;
363428
}
429+
// Filter events if ignore matcher is set and filename is available
430+
if (filename != null && ignoreMatcher?.(filename)) {
431+
return;
432+
}
364433
if (queue.length < maxQueue) {
365434
ArrayPrototypePush(queue, { __proto__: null, eventType, filename });
366435
resolve();
@@ -409,6 +478,7 @@ async function* watch(filename, options = kEmptyObject) {
409478
}
410479

411480
module.exports = {
481+
createIgnoreMatcher,
412482
FSWatcher,
413483
StatWatcher,
414484
kFSWatchStart,

‎lib/internal/validators.js‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ const { normalizeEncoding } = require('internal/util');
3636
const {
3737
isAsyncFunction,
3838
isArrayBufferView,
39+
isRegExp,
3940
} = require('internal/util/types');
4041
const { signals } = internalBinding('constants').os;
4142

@@ -584,6 +585,38 @@ const validateLinkHeaderValue = hideStackFrames((hints) => {
584585
);
585586
});
586587

588+
/**
589+
* Validates a single ignore option element (string, RegExp, or Function).
590+
* @param {*} value
591+
* @param {string} name
592+
*/
593+
const validateIgnoreOptionElement = hideStackFrames((value, name) => {
594+
if (typeof value === 'string') {
595+
if (value.length === 0)
596+
throw new ERR_INVALID_ARG_VALUE(name, value, 'must be a non-empty string');
597+
return;
598+
}
599+
if (isRegExp(value)) return;
600+
if (typeof value === 'function') return;
601+
throw new ERR_INVALID_ARG_TYPE(name, ['string', 'RegExp', 'Function'], value);
602+
});
603+
604+
/**
605+
* Validates the ignore option for fs.watch.
606+
* @param {*} value
607+
* @param {string} name
608+
*/
609+
const validateIgnoreOption = hideStackFrames((value, name) => {
610+
if (value == null) return;
611+
if (ArrayIsArray(value)) {
612+
for (let i = 0; i < value.length; i++) {
613+
validateIgnoreOptionElement(value[i], `${name}[${i}]`);
614+
}
615+
return;
616+
}
617+
validateIgnoreOptionElement(value, name);
618+
});
619+
587620
// 1. Returns false for undefined and NaN
588621
// 2. Returns true for finite numbers
589622
// 3. Throws ERR_INVALID_ARG_TYPE for non-numbers
@@ -637,6 +670,7 @@ module.exports = {
637670
validateDictionary,
638671
validateEncoding,
639672
validateFunction,
673+
validateIgnoreOption,
640674
validateInt32,
641675
validateInteger,
642676
validateNumber,

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL