Suggestion: add support for an async iterator of file change events

[dead-claudia]

The idea is pretty simple: make all file watchers async iterators yielding {event, path, stats} objects.

You could do more with this as well, like allowing automatic coalescing of events like dropping add + remove pairs that occur between a next call, but that's entirely optional - just blindly buffering everything is fine for me.

[paulmillr]

A simple wrapper that yields those shouldnt be too hard.

Tge question is: why would it be useful?

[dead-claudia]

I've got code that uses a lot of promises, and it'd be a bit easier to fit into that world than callbacks.

Also, it makes fault tolerance almost trivial.

while (true) {
  try {
    for await (const {event, path} of watch(dir, {...})) {
        handleEvent(event, path)
    }
    break
  } catch (e) {
    console.error(e)
  }
}

The equivalent of the above with callbacks is pretty clumsy:

function initWatcher() {
  const watcher = watch(dir, {...})
  watcher.on("raw", (event, path) => {
    handleEvent(event, path)
  })
  watcher.on("error", (e) => {
    console.error(e)
    initWatcher()
  })
}
initWatcher()

Add a signal parameter to watch options to stop the watcher and end the iterator, and you could create a signal wrapping SIGTERM and SIGINT and have it automatically stop on that in case you have cleanup you need to do. This is much easier and cleaner to accomplish with an async iterable main loop since it's just a matter of adding code after the loop ends.

// With an async iterator
while (true) {
  try {
    for await (const {event, path} of watch(dir, {signal: terminationSignal, ...})) {
        handleEvent(event, path)
    }
    break
  } catch (e) {
    console.error(e)
  }
}

await doCleanup()

// With callbacks, assuming a `close` event is also added
function initWatcher() {
  const watcher = watch(dir, {signal: terminationSignal, ...})
  watcher.on("close", () => {
    doCleanup()
  })
  watcher.on("raw", (event, path) => {
    handleEvent(event, path)
  })
  watcher.on("error", (e) => {
    console.error(e)
    initWatcher()
  })
}
initWatcher()

// Current API
function initWatcher() {
  const watcher = watch(dir, {...})
  const onAbort = async () => {
    await watcher.close()
    await doCleanup()
  }
  terminationSignal.addEventListener("abort", onAbort, {once: true})
  watcher.on("raw", (event, path) => {
    handleEvent(event, path)
  })
  watcher.on("error", (e) => {
    terminationSignal.removeEventListener("abort", onAbort)
    console.error(e)
    initWatcher()
  })
}
initWatcher()

I think you can see what I mean when I say it gets pretty clumsy to manage with callbacks. And that doCleanup isn't normally one function call, but several calls, so you can pretty easily imagine how out of hand it could get.

Worth noting Node already supports it natively with its fs.promises.watch API, too.