url: expose pathToFileURL and fileURLToPath

doc/api/url.md

@@ -921,6 +921,51 @@ console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
 // Prints 'https://你好你好/?abc'
 ```
 
+## File URL Utility Functions
+
+When working with `file:///` URLs in Node.js (eg when working with ES modules
+which are keyed in the registry by File URL), the utility functions
+`urlToFilePath` and `fileUrlToPath` are provided to convert to and from file
+paths.
+
+The edge cases handled by these functions include percent-encoding and decoding
+as well as cross-platform support.
+
+For example, instead of writing:
+
+```js
+// BAD:
+// - fails in Windows
+// - doesn't handle loading paths using extended non-latin characters
+fs.promises.readFile(fileUrl.pathname);
+```
+
+write:
+
+```js
+// GOOD:
+// - works in Windows
+// - handles emoji file paths
+const { fileUrlToPath } = require('url');
+fs.promises.readFile(fileUrlToPath(fileUrl));
+```
+
+### pathToFileUrl(path)
+
+* `path` {string} The absolute path to convert to a File URL.
+* Returns: {URL} The file URL object.
+
+This function ensures the correct encodings of URL control characters in file paths
+when converting into File URLs.
+
+### fileUrlToPath(url)
+
+* `url` {URL} | {string} The file URL string or URL object to convert to a path.
+* Returns: {URL} The fully-resolved platform-specific Node.js file path.
+
+This function ensures the correct decodings of percent-encoded characters as well
+as ensuring a cross-platform valid absolute path string.
+
 ## Legacy URL API
 
 ### Legacy `urlObject`