doc: add WHATWG file URLs in fs module

Update fs module documentation adding WHATWG file URLS support for
relevant fs functions/classes.

PR-URL: https://github.com/nodejs/node/pull/12670
Fixes: https://github.com/nodejs/node/issues/12341
Ref: https://github.com/nodejs/node/pull/10739
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

doc/api/fs.md

@@ -94,6 +94,95 @@ Error: EISDIR: illegal operation on a directory, read
     <stack trace.>
 ```
 
+## WHATWG URL object support
+<!-- YAML
+added: v7.6.0
+-->
+
+> Stability: 1 - Experimental
+
+For most `fs` module functions, the `path` or `filename` argument may be passed
+as a WHATWG [`URL`][] object. Only [`URL`][] objects using the `file:` protocol
+are supported.
+
+```js
+const fs = require('fs');
+const { URL } = require('url');
+const fileUrl = new URL('file:///tmp/hello');
+
+fs.readFileSync(fileUrl);
+```
+
+*Note*: `file:` URLs are always absolute paths.
+
+Using WHATWG [`URL`][] objects might introduce platform-specific behaviors.
+
+On Windows, `file:` URLs with a hostname convert to UNC paths, while `file:`
+URLs with drive letters convert to local absolute paths. `file:` URLs without a
+hostname nor a drive letter will result in a throw :
+
+```js
+// On Windows :
+
+// - WHATWG file URLs with hostname convert to UNC path
+// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
+fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
+
+// - WHATWG file URLs with drive letters convert to absolute path
+// file:///C:/tmp/hello => C:\tmp\hello
+fs.readFileSync(new URL('file:///C:/tmp/hello'));
+
+// - WHATWG file URLs without hostname must have a drive letters
+fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
+fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
+// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute
+```
+
+*Note*: `file:` URLs with drive letters must use `:` as a separator just after
+the drive letter. Using another separator will result in a throw.
+
+On all other platforms, `file:` URLs with a hostname are unsupported and will
+result in a throw:
+
+```js
+// On other platforms:
+
+// - WHATWG file URLs with hostname are unsupported
+// file://hostname/p/a/t/h/file => throw!
+fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
+// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute
+
+// - WHATWG file URLs convert to absolute path
+// file:///tmp/hello => /tmp/hello
+fs.readFileSync(new URL('file:///tmp/hello'));
+```
+
+A `file:` URL having encoded slash characters will result in a throw on all
+platforms:
+
+```js
+// On Windows
+fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
+fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
+/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
+\ or / characters */
+
+// On POSIX
+fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
+fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
+/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
+/ characters */
+```
+On Windows, `file:` URLs having encoded backslash will result in a throw:
+
+```js
+// On Windows
+fs.readFileSync(new URL('file:///C:/path/%5C'));
+fs.readFileSync(new URL('file:///C:/path/%5c'));
+/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
+\ or / characters */
+```
+
 ## Buffer API
 <!-- YAML
 added: v6.0.0
@@ -319,9 +408,14 @@ argument to `fs.createWriteStream()`. If `path` is passed as a string, then
 ## fs.access(path[, mode], callback)
 <!-- YAML
 added: v0.11.15
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 * `callback` {Function}
 
@@ -440,9 +534,14 @@ process.
 ## fs.accessSync(path[, mode])
 <!-- YAML
 added: v0.11.15
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 
 Synchronous version of [`fs.access()`][]. This throws if any accessibility
@@ -520,13 +619,17 @@ The synchronous version of [`fs.appendFile()`][]. Returns `undefined`.
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 * `callback` {Function}
 
@@ -536,9 +639,14 @@ to the completion callback.
 ## fs.chmodSync(path, mode)
 <!-- YAML
 added: v0.6.7
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 
 Synchronous chmod(2). Returns `undefined`.
@@ -547,13 +655,17 @@ Synchronous chmod(2). Returns `undefined`.
 <!-- YAML
 added: v0.1.97
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `uid` {integer}
 * `gid` {integer}
 * `callback` {Function}
@@ -564,9 +676,14 @@ to the completion callback.
 ## fs.chownSync(path, uid, gid)
 <!-- YAML
 added: v0.1.97
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `uid` {integer}
 * `gid` {integer}
 
@@ -607,6 +724,10 @@ operations. The specific constants currently defined are described in
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7831
     description: The passed `options` object will never be modified.
@@ -615,7 +736,7 @@ changes:
     description: The passed `options` object can be a string now.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `flags` {string}
   * `encoding` {string}
@@ -675,6 +796,10 @@ If `options` is a string, then it specifies the encoding.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7831
     description: The passed `options` object will never be modified.
@@ -686,7 +811,7 @@ changes:
     description: The passed `options` object can be a string now.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `flags` {string}
   * `defaultEncoding` {string}
@@ -731,12 +856,17 @@ If `options` is a string, then it specifies the encoding.
 ## fs.exists(path, callback)
 <!-- YAML
 added: v0.0.2
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
 deprecated: v1.0.0
 -->
 
 > Stability: 0 - Deprecated: Use [`fs.stat()`][] or [`fs.access()`][] instead.
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `callback` {Function}
 
 Test whether or not the given path exists by checking with the file system.
@@ -836,9 +966,14 @@ process.
 ## fs.existsSync(path)
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 
 Synchronous version of [`fs.exists()`][].
 Returns `true` if the file exists, `false` otherwise.
@@ -1148,14 +1283,19 @@ Synchronous lchown(2). Returns `undefined`.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `existingPath` and `newPath` parameters can be WHATWG
+                 `URL` objects using `file:` protocol. Support is currently
+                 still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `existingPath` {string|Buffer}
+* `existingPath` {string|Buffer|URL}
-* `newPath` {string|Buffer}
+* `newPath` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous link(2). No arguments other than a possible exception are given to
@@ -1164,10 +1304,16 @@ the completion callback.
 ## fs.linkSync(existingPath, newPath)
 <!-- YAML
 added: v0.1.31
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `existingPath` and `newPath` parameters can be WHATWG
+                 `URL` objects using `file:` protocol. Support is currently
+                 still *experimental*.
 -->
 
-* `existingPath` {string|Buffer}
+* `existingPath` {string|Buffer|URL}
-* `newPath` {string|Buffer}
+* `newPath` {string|Buffer|URL}
 
 Synchronous link(2). Returns `undefined`.
 
@@ -1175,13 +1321,17 @@ Synchronous link(2). Returns `undefined`.
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
@@ -1192,9 +1342,14 @@ not the file that it refers to.
 ## fs.lstatSync(path)
 <!-- YAML
 added: v0.1.30
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 
 Synchronous lstat(2). Returns an instance of [`fs.Stats`][].
 
@@ -1202,13 +1357,17 @@ Synchronous lstat(2). Returns an instance of [`fs.Stats`][].
 <!-- YAML
 added: v0.1.8
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 * `callback` {Function}
 
@@ -1218,9 +1377,14 @@ to the completion callback. `mode` defaults to `0o777`.
 ## fs.mkdirSync(path[, mode])
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `mode` {integer}
 
 Synchronous mkdir(2). Returns `undefined`.
@@ -1313,9 +1477,14 @@ object with an `encoding` property specifying the character encoding to use.
 ## fs.open(path, flags[, mode], callback)
 <!-- YAML
 added: v0.0.2
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `flags` {string|number}
 * `mode` {integer}
 * `callback` {Function}
@@ -1397,9 +1566,14 @@ fs.open('<directory>', 'a+', (err, fd) => {
 ## fs.openSync(path, flags[, mode])
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `flags` {string|number}
 * `mode` {integer}
 
@@ -1442,6 +1616,10 @@ The callback is given the three arguments, `(err, bytesRead, buffer)`.
 <!-- YAML
 added: v0.1.8
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
@@ -1451,7 +1629,7 @@ changes:
     description: The `options` parameter was added.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 * `callback` {Function}
@@ -1468,9 +1646,14 @@ the filenames returned will be passed as `Buffer` objects.
 ## fs.readdirSync(path[, options])
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 
@@ -1482,10 +1665,14 @@ object with an `encoding` property specifying the character encoding to use for
 the filenames passed to the callback. If the `encoding` is set to `'buffer'`,
 the filenames returned will be passed as `Buffer` objects.
 
-## fs.readFile(file[, options], callback)
+## fs.readFile(path[, options], callback)
 <!-- YAML
 added: v0.1.29
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
@@ -1499,7 +1686,7 @@ changes:
     description: The `file` parameter can be a file descriptor now.
 -->
 
-* `file` {string|Buffer|integer} filename or file descriptor
+* `path` {string|Buffer|URL|integer} filename or file descriptor
 * `options` {Object|string}
   * `encoding` {string|null} default = `null`
   * `flag` {string} default = `'r'`
@@ -1527,19 +1714,23 @@ fs.readFile('/etc/passwd', 'utf8', callback);
 
 Any specified file descriptor has to support reading.
 
-_Note: If a file descriptor is specified as the `file`, it will not be closed
+_Note: If a file descriptor is specified as the `path`, it will not be closed
 automatically._
 
-## fs.readFileSync(file[, options])
+## fs.readFileSync(path[, options])
 <!-- YAML
 added: v0.1.8
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v5.0.0
     pr-url: https://github.com/nodejs/node/pull/3163
     description: The `file` parameter can be a file descriptor now.
 -->
 
-* `file` {string|Buffer|integer} filename or file descriptor
+* `path` {string|Buffer|URL|integer} filename or file descriptor
 * `options` {Object|string}
   * `encoding` {string|null} default = `null`
   * `flag` {string} default = `'r'`
@@ -1553,13 +1744,17 @@ string. Otherwise it returns a buffer.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 * `callback` {Function}
@@ -1575,9 +1770,14 @@ the link path returned will be passed as a `Buffer` object.
 ## fs.readlinkSync(path[, options])
 <!-- YAML
 added: v0.1.31
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 
@@ -1609,6 +1809,10 @@ Synchronous version of [`fs.read()`][]. Returns the number of `bytesRead`.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
@@ -1622,7 +1826,7 @@ changes:
     description: The `cache` parameter was removed.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 * `callback` {Function}
@@ -1641,6 +1845,10 @@ the path returned will be passed as a `Buffer` object.
 <!-- YAML
 added: v0.1.31
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v6.4.0
     pr-url: https://github.com/nodejs/node/pull/7899
     description: Calling `realpathSync` now works again for various edge cases
@@ -1650,7 +1858,7 @@ changes:
     description: The `cache` parameter was removed.
 -->
 
-* `path` {string|Buffer};
+* `path` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} default = `'utf8'`
 
@@ -1667,14 +1875,19 @@ will be passed as a `Buffer` object.
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `oldPath` and `newPath` parameters can be WHATWG `URL`
+                 objects using `file:` protocol. Support is currently still
+                 *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `oldPath` {string|Buffer}
+* `oldPath` {string|Buffer|URL}
-* `newPath` {string|Buffer}
+* `newPath` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous rename(2). No arguments other than a possible exception are given
@@ -1683,10 +1896,16 @@ to the completion callback.
 ## fs.renameSync(oldPath, newPath)
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `oldPath` and `newPath` parameters can be WHATWG `URL`
+                 objects using `file:` protocol. Support is currently still
+                 *experimental*.
 -->
 
-* `oldPath` {string|Buffer}
+* `oldPath` {string|Buffer|URL}
-* `newPath` {string|Buffer}
+* `newPath` {string|Buffer|URL}
 
 Synchronous rename(2). Returns `undefined`.
 
@@ -1694,13 +1913,17 @@ Synchronous rename(2). Returns `undefined`.
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameters can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous rmdir(2). No arguments other than a possible exception are given
@@ -1709,9 +1932,14 @@ to the completion callback.
 ## fs.rmdirSync(path)
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameters can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 
 Synchronous rmdir(2). Returns `undefined`.
 
@@ -1719,13 +1947,17 @@ Synchronous rmdir(2). Returns `undefined`.
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
@@ -1744,19 +1976,30 @@ is recommended.
 ## fs.statSync(path)
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 
 Synchronous stat(2). Returns an instance of [`fs.Stats`][].
 
 ## fs.symlink(target, path[, type], callback)
 <!-- YAML
 added: v0.1.31
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `target` and `path` parameters can be WHATWG `URL` objects
+                 using `file:` protocol. Support is currently still
+                 *experimental*.
 -->
 
-* `target` {string|Buffer}
+* `target` {string|Buffer|URL}
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `type` {string}
 * `callback` {Function}
 
@@ -1778,10 +2021,16 @@ It creates a symbolic link named "new-port" that points to "foo".
 ## fs.symlinkSync(target, path[, type])
 <!-- YAML
 added: v0.1.31
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `target` and `path` parameters can be WHATWG `URL` objects
+                 using `file:` protocol. Support is currently still
+                 *experimental*.
 -->
 
-* `target` {string|Buffer}
+* `target` {string|Buffer|URL}
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `type` {string}
 
 Synchronous symlink(2). Returns `undefined`.
@@ -1819,13 +2068,17 @@ passed as the first argument. In this case, `fs.ftruncateSync()` is called.
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
                  it will emit a deprecation warning.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `callback` {Function}
 
 Asynchronous unlink(2). No arguments other than a possible exception are given
@@ -1834,9 +2087,14 @@ to the completion callback.
 ## fs.unlinkSync(path)
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 
 Synchronous unlink(2). Returns `undefined`.
 
@@ -1863,6 +2121,10 @@ when possible._
 <!-- YAML
 added: v0.4.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7897
     description: The `callback` parameter is no longer optional. Not passing
@@ -1873,7 +2135,7 @@ changes:
                  time specifiers.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `atime` {integer}
 * `mtime` {integer}
 * `callback` {Function}
@@ -1893,13 +2155,17 @@ follow these rules:
 <!-- YAML
 added: v0.4.2
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `path` parameter can be a WHATWG `URL` object using `file:`
+                 protocol. Support is currently still *experimental*.
   - version: v4.1.0
     pr-url: https://github.com/nodejs/node/pull/2387
     description: Numeric strings, `NaN` and `Infinity` are now allowed
                  time specifiers.
 -->
 
-* `path` {string|Buffer}
+* `path` {string|Buffer|URL}
 * `atime` {integer}
 * `mtime` {integer}
 
@@ -1909,12 +2175,16 @@ Synchronous version of [`fs.utimes()`][]. Returns `undefined`.
 <!-- YAML
 added: v0.5.10
 changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `filename` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7831
     description: The passed `options` object will never be modified.
 -->
 
-* `filename` {string|Buffer}
+* `filename` {string|Buffer|URL}
 * `options` {string|Object}
   * `persistent` {boolean} Indicates whether the process should continue to run
     as long as files are being watched. default = `true`
@@ -2015,9 +2285,14 @@ fs.watch('somedir', (eventType, filename) => {
 ## fs.watchFile(filename[, options], listener)
 <!-- YAML
 added: v0.1.31
+changes:
+  - version: v7.6.0
+    pr-url: https://github.com/nodejs/node/pull/10739
+    description: The `filename` parameter can be a WHATWG `URL` object using
+                 `file:` protocol. Support is currently still *experimental*.
 -->
 
-* `filename` {string|Buffer}
+* `filename` {string|Buffer|URL}
 * `options` {Object}
   * `persistent` {boolean}
   * `interval` {integer}
@@ -2513,3 +2788,4 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [Common System Errors]: errors.html#errors_common_system_errors
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
+[`URL`]: url.html#url_the_whatwg_url_api