path: add fromURL

doc/api/path.md

@@ -267,6 +267,38 @@ path.format({
 // Returns: 'C:\\path\\dir\\file.txt'
 ```
 
+## `path.fromURL(pathOrUrl)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `pathOrUrl` {string|URL}.
+* Returns: {string}
+
+converts a [`URL`][] instance to a path string,
+returns `pathOrUrl` if it is already a string.
+
+A [`TypeError`][] is thrown if `pathOrUrl` is a
+[`URL`][] with a schema other than `file://`.
+
+```js
+path.fromURL(new URL('file:///Users/node/dev'));
+// Returns: '/Users/node/dev'
+
+path.fromURL('file:///Users/node/dev');
+// Returns: 'file:///Users/node/dev'
+
+path.fromURL(new URL('file:///c:/foo.txt'));
+// Returns On Windows: 'c:/foo.txt'
+
+path.fromURL('index/path');
+// Returns: 'index/path'
+
+path.fromURL(new URL('http://example.com'));
+// Throws 'TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file'
+```
+
 ## `path.isAbsolute(path)`
 
 <!-- YAML
@@ -604,6 +636,7 @@ The API is accessible via `require('node:path').win32` or `require('node:path/wi
 
 [MSDN-Rel-Path]: https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file#fully-qualified-vs-relative-paths
 [`TypeError`]: errors.md#class-typeerror
+[`URL`]: url.md#the-whatwg-url-api
 [`path.parse()`]: #pathparsepath
 [`path.posix`]: #pathposix
 [`path.sep`]: #pathsep

lib/path.js

@@ -1533,6 +1533,15 @@ const posix = {
   posix: null
 };
 
+let toPathIfFileURL;
+function fromURL(fileURLOrPath) {
+  // Lazy require to avoid circular dependency
+  toPathIfFileURL = toPathIfFileURL ?? require('internal/url').toPathIfFileURL;
+  return toPathIfFileURL(fileURLOrPath);
+}
+
+posix.fromURL = win32.fromURL = fromURL;
+
 posix.win32 = win32.win32 = win32;
 posix.posix = win32.posix = posix;
 

test/parallel/test-path-from-url.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('node:assert');
+const { fromURL } = require('node:path');
+const { describe, it } = require('node:test');
+
+
+describe('path.fromURL', { concurrency: true }, () => {
+  it('should passthrough path string', () => assert
+    .strictEqual(fromURL('/Users/node/dev'), '/Users/node/dev'));
+  it('should passthrough a URL string with file schema', () => assert
+    .strictEqual(fromURL('file:///Users/node/dev'), 'file:///Users/node/dev'));
+  it('should parse a URL instance with file schema', () => assert
+    .strictEqual(fromURL(new URL('file:///Users/node/dev')), '/Users/node/dev'));
+  it('should parse a URL instance with file schema', () => assert
+    .strictEqual(fromURL(new URL('file:///path/to/file')), '/path/to/file'));
+  it('should remove the host from a URL instance', () => assert
+    .strictEqual(fromURL(new URL('file://localhost/etc/fstab')), '/etc/fstab'));
+  if (common.isWindows) {
+    it('should parse a windows file URI', () => assert
+      .strictEqual(fromURL('file:///c:/foo.txt'), 'c:/foo.txt'));
+  }
+  it('should throw an error if the URL is not a file URL', () => assert
+    .throws(() => fromURL(new URL('http://localhost/etc/fstab')), { code: 'ERR_INVALID_URL_SCHEME' }));
+});