This PR implements the missing promises.watch() and promises.watchFile() methods in memfs, providing full compatibility with Node.js's fs.promises API for file system watching.

Implementation

promises.watch(filename[, options])

Returns an AsyncIterableIterator that yields {eventType, filename} events when files or directories change. Supports all Node.js options:

• persistent - Keep the process running while watching (default: true)
• recursive - Watch subdirectories recursively (default: false)
• encoding - Character encoding for filenames (default: 'utf8')
• signal - AbortSignal for cancellation
• maxQueue - Maximum events to queue (default: 2048)
• overflow - Behavior when queue overflows: 'ignore' or 'throw' (default: 'ignore')

promises.watchFile(filename[, options])

Returns an AsyncIterableIterator that yields {curr, prev} stat objects when file stats change. Options:

• persistent - Keep the process running while watching (default: true)
• interval - Polling interval in milliseconds (default: 5007)

Usage

const { promises } = require('memfs');

// Watch with for-await loop
const watcher = promises.watch('/path/to/file');
for await (const event of watcher) {
  console.log(`${event.eventType}: ${event.filename}`);
  if (someCondition) break;
}

// Watch with AbortSignal
const controller = new AbortController();
const watcher = promises.watch('/path/to/file', { 
  signal: controller.signal 
});

setTimeout(() => controller.abort(), 5000);

try {
  for await (const event of watcher) {
    console.log(event);
  }
} catch (error) {
  console.log('Watching cancelled');
}

// Watch file stats
const statWatcher = promises.watchFile('/path/to/file');
for await (const {curr, prev} of statWatcher) {
  console.log(`Size changed from ${prev.size} to ${curr.size}`);
}

Technical Details

• Built on top of existing FSWatcher and StatWatcher implementations
• Zero breaking changes - all existing callback APIs continue to work
• Proper cleanup and memory management
• Full TypeScript support with correct return types
• Comprehensive test coverage including edge cases
• Queue overflow protection prevents memory leaks

Tests

Added comprehensive tests covering:

• Basic functionality for both watch methods
• AbortSignal cancellation
• Queue overflow handling (ignore/throw strategies)
• For-await loop compatibility
• Iterator protocol compliance
• Integration with existing file system operations

All existing tests continue to pass, ensuring backward compatibility.

Fixes #1120.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.