feat(fs): introduce 'fs.watch' and 'fs.Watcher'

api/fs/dir.js

@@ -60,12 +60,30 @@ export class Dir {
     this.withFileTypes = options?.withFileTypes !== false
   }
 
+  /**
+   * `true` if closed, otherwise `false`.
+   * @ignore
+   * @type {boolean}
+   */
+  get closed () {
+    return Boolean(this.handle?.closed)
+  }
+
+  /**
+   * `true` if closeing, otherwise `false`.
+   * @ignore
+   * @type {boolean}
+   */
+  get closing () {
+    return Boolean(this.handle?.closig)
+  }
+
   /**
    * Closes container and underlying handle.
    * @param {object|function} options
    * @param {function=} callback
    */
-  async close (options, callback) {
+  async close (options = null, callback) {
     if (typeof options === 'function') {
       callback = options
       options = {}

api/fs/handle.js

@@ -85,7 +85,7 @@ export class FileHandle extends EventEmitter {
    * @param {string} path
    * @param {number} [mode = 0o666]
    * @param {object=} [options]
-   * @return {boolean}
+   * @return {Promise<boolean>}
    */
   static async access (path, mode, options) {
     if (mode !== null && typeof mode === 'object') {
@@ -112,7 +112,7 @@ export class FileHandle extends EventEmitter {
    * @see {@link https://nodejs.org/dist/latest-v20.x/docs/api/fs.html#fspromisesopenpath-flags-mode}
    * @param {string | Buffer | URL} path
    * @param {string=} [flags = 'r']
-   * @param {string=} [mode = 0o666]
+   * @param {string|number=} [mode = 0o666]
    * @param {object=} [options]
    */
   static async open (path, flags, mode, options) {
@@ -137,7 +137,7 @@ export class FileHandle extends EventEmitter {
 
   /**
    * `FileHandle` class constructor
-   * @private
+   * @ignore
    * @param {object} options
    */
   constructor (options) {
@@ -207,7 +207,7 @@ export class FileHandle extends EventEmitter {
       args: [this.id, options],
       async handle (id) {
         if (fds.has(id)) {
-          console.warn('Closing FileHandle on garbage collection')
+          console.warn('Closing fs.FileHandle on garbage collection')
           await ipc.send('fs.close', { id }, options)
           fds.release(id, false)
         }
@@ -420,9 +420,9 @@ export class FileHandle extends EventEmitter {
    * Reads `length` bytes starting from `position` into `buffer` at
    * `offset`.
    * @param {Buffer|object} buffer
-   * @param {number} offset
-   * @param {number} length
-   * @param {number} position
+   * @param {number=} [offset]
+   * @param {number=} [length]
+   * @param {number=} [position]
    * @param {object=} [options]
    */
   async read (buffer, offset, length, position, options) {
@@ -914,7 +914,7 @@ export class DirectoryHandle extends EventEmitter {
       args: [this.id, options],
       async handle (id) {
         if (fds.has(id)) {
-          console.warn('Closing DirectoryHandle on garbage collection')
+          console.warn('Closing fs.DirectoryHandle on garbage collection')
           await ipc.send('fs.closedir', { id }, options)
           fds.release(id, false)
         }

api/fs/index.js

@@ -33,6 +33,7 @@ import { DirectoryHandle, FileHandle } from './handle.js'
 import { ReadStream, WriteStream } from './stream.js'
 import * as constants from './constants.js'
 import * as promises from './promises.js'
+import { Watcher } from './watcher.js'
 import { Stats } from './stats.js'
 import fds from './fds.js'
 
@@ -47,7 +48,7 @@ function defaultCallback (err) {
   if (err) throw err
 }
 
-async function visit (path, options, callback) {
+async function visit (path, options = null, callback) {
   if (typeof options === 'function') {
     callback = options
     options = {}
@@ -133,7 +134,11 @@ export function chmod (path, mode, callback) {
 }
 
 /**
- * @ignore
+ * Changes ownership of file or directory at `path` with `uid` and `gid`.
+ * @param {string} path
+ * @param {number} uid
+ * @param {number} gid
+ * @param {function} callback
  */
 export function chown (path, uid, gid, callback) {
   if (typeof path !== 'string') {
@@ -230,7 +235,9 @@ export function createReadStream (path, options) {
   if (options?.fd) {
     handle = FileHandle.from(options.fd)
   } else {
+    // @ts-ignore
     handle = new FileHandle({ flags: 'r', path, ...options })
+    // @ts-ignore
     handle.open(options).catch((err) => stream.emit('error', err))
   }
 
@@ -239,6 +246,7 @@ export function createReadStream (path, options) {
       try {
         await handle.close(options)
       } catch (err) {
+        // @ts-ignore
         stream.emit('error', err)
       }
     }
@@ -271,6 +279,7 @@ export function createWriteStream (path, options) {
     handle = FileHandle.from(options.fd)
   } else {
     handle = new FileHandle({ flags: 'w', path, ...options })
+    // @ts-ignore
     handle.open(options).catch((err) => stream.emit('error', err))
   }
 
@@ -279,6 +288,7 @@ export function createWriteStream (path, options) {
       try {
         await handle.close(options)
       } catch (err) {
+        // @ts-ignore
         stream.emit('error', err)
       }
     }
@@ -321,7 +331,11 @@ export function fstat (fd, options, callback) {
 }
 
 /**
- * @ignore
+ * Chages ownership of link at `path` with `uid` and `gid.
+ * @param {string} path
+ * @param {number} uid
+ * @param {number} gid
+ * @param {function} callback
  */
 export function lchown (path, uid, gid, callback) {
   if (typeof path !== 'string') {
@@ -346,7 +360,10 @@ export function lchown (path, uid, gid, callback) {
 }
 
 /**
- * @ignore
+ * Creates a link to `dest` from `dest`.
+ * @param {string} src
+ * @param {string} dest
+ * @param {function}
  */
 export function link (src, dest, callback) {
   if (typeof src !== 'string') {
@@ -607,7 +624,9 @@ export function readFile (path, options = {}, callback) {
 }
 
 /**
- * @ignore
+ * Reads link at `path`
+ * @param {string} path
+ * @param {function(err, string)} callback
  */
 export function readlink (path, callback) {
   if (typeof path !== 'string') {
@@ -624,7 +643,9 @@ export function readlink (path, callback) {
 }
 
 /**
- * @ignore
+ * Computes real path for `path`
+ * @param {string} path
+ * @param {function(err, string)} callback
  */
 export function realpath (path, callback) {
   if (typeof path !== 'string') {
@@ -641,7 +662,10 @@ export function realpath (path, callback) {
 }
 
 /**
- * @ignore
+ * Renames file or directory at `src` to `dest`.
+ * @param {string} src
+ * @param {string} dest
+ * @param {function} callback
  */
 export function rename (src, dest, callback) {
   if (typeof src !== 'string') {
@@ -662,7 +686,9 @@ export function rename (src, dest, callback) {
 }
 
 /**
- * @ignore
+ * Removes directory at `path`.
+ * @param {string} path
+ * @param {function} callback
  */
 export function rmdir (path, callback) {
   if (typeof path !== 'string') {
@@ -697,7 +723,7 @@ export function stat (path, options, callback) {
     throw new TypeError('callback must be a function.')
   }
 
-  visit(path, async (err, handle) => {
+  visit(path, {}, async (err, handle) => {
     let stats = null
 
     if (err) {
@@ -717,7 +743,9 @@ export function stat (path, options, callback) {
 }
 
 /**
- * @ignore
+ * Creates a symlink of `src` at `dest`.
+ * @param {string} src
+ * @param {string} dest
  */
 export function symlink (src, dest, type = null, callback) {
   let flags = 0
@@ -756,7 +784,9 @@ export function symlink (src, dest, type = null, callback) {
 }
 
 /**
- * @ignore
+ * Unlinks (removes) file at `path`.
+ * @param {string} path
+ * @param {function} callback
  */
 export function unlink (path, callback) {
   if (typeof path !== 'string') {
@@ -820,6 +850,23 @@ export function writeFile (path, data, options, callback) {
   })
 }
 
+/**
+ * Watch for changes at `path` calling `callback`
+ * @param {string}
+ * @param {function|object=} [options]
+ * @param {?function} [callback]
+ * @return {Watcher}
+ */
+export function watch (path, options, callback = null) {
+  if (typeof options === 'function') {
+    callback = options
+  }
+
+  const watcher = new Watcher(path, options)
+  watcher.on('change', callback)
+  return watcher
+}
+
 // re-exports
 export {
   constants,
@@ -831,6 +878,7 @@ export {
   promises,
   ReadStream,
   Stats,
+  Watcher,
   WriteStream
 }