Introduce 'fs.watch' and 'fs.Watcher'

[jwerle]

This PR introduces the fs.watch() and fs.Watcher APIs. It is implemented to give as much parity as possible with node's implementation.

Examples

EventEmitter:

import process from 'socket:process'
import fs from 'socket:fs'

// watch resources directory
const watcher  = fs.watch(process.cwd())

watcher.on('change', (eventType, filename) => {
  console.log(eventType) // 'change' or 'rename'
  console.log(filename) // file name relative to `process.cwd()`
})

AsyncIterator (with filename encoding):

import process from 'socket:process'
import fs from 'socket:fs/promises'

// output `filename` as `Buffer` instance
const events = fs.watch(process.cwd(), { encoding: 'buffer' })

for await (const event of events) {
  console.log(event) // { eventType: 'change' | 'rename' , filename: <Buffer ...> }
}

AbortSignal

import process from 'socket:process'
import fs from 'socket:fs/promises'

const controller = new AbortController()
// output `filename` as `Buffer` instance
const events = fs.watch(process.cwd(), { signal: controller.signal })

// watch files for 5000 ms
setTimeout(() => controller.abort(), 5000)

for await (const event of events) {
  console.log(event) // { eventType: 'change' | 'rename' , filename: 'index.js' }
}

Closes #595

[bcomnes]

Random TS question:

If you don't set this to null in the instance value field, and you guarantee set them in the constructor, typescript will let you type it as never null and just the value its typed as. Or maybe this is a strict null check option, I'm not sure. Typescript is a million variants of itself depending on how you configure it.

What about not setting this to null initially, or if there is a reason, why do we set this to null here?

[jwerle]

just by habit
@chicoxyzzy what do you think we should set it to here?

[bcomnes]

Not setting null here (unless I'm mistaken), and also setting in the constructor narrows the fields slightly to be a single type instead of also possibly null.

[bcomnes]

Nice