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/internal/url.js

@@ -1594,6 +1594,8 @@ module.exports = {
   toUSVString,
   fileURLToPath,
   pathToFileURL,
+  getPathFromURLPosix,
+  getPathFromURLWin32,
   toPathIfFileURL,
   isURLInstance,
   URL,

lib/path.js

@@ -47,6 +47,21 @@ const {
   validateString,
 } = require('internal/validators');
 
+const {
+  codes: {
+    ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_URL_SCHEME,
+  },
+} = require('internal/errors');
+
+
+let urlModule;
+function lazyURLModule() {
+  // Lazy require to avoid circular dependency
+  urlModule ??= require('internal/url');
+  return urlModule;
+}
+
 const platformIsWin32 = (process.platform === 'win32');
 
 function isPathSeparator(code) {
@@ -1061,6 +1076,19 @@ const win32 = {
     return ret;
   },
 
+  fromURL(fileURLOrPath) {
+    if (typeof fileURLOrPath === 'string') {
+      return fileURLOrPath;
+    }
+    if (!lazyURLModule().isURLInstance(fileURLOrPath)) {
+      throw new ERR_INVALID_ARG_TYPE('fileURLOrPath', ['string', 'URL'], fileURLOrPath);
+    }
+    if (fileURLOrPath.protocol !== 'file:')
+      throw new ERR_INVALID_URL_SCHEME('file');
+
+    return lazyURLModule().getPathFromURLWin32(fileURLOrPath);
+  },
+
   sep: '\\',
   delimiter: ';',
   win32: null,
@@ -1527,12 +1555,26 @@ const posix = {
     return ret;
   },
 
+  fromURL(fileURLOrPath) {
+    if (typeof fileURLOrPath === 'string') {
+      return fileURLOrPath;
+    }
+    if (!lazyURLModule().isURLInstance(fileURLOrPath)) {
+      throw new ERR_INVALID_ARG_TYPE('fileURLOrPath', ['string', 'URL'], fileURLOrPath);
+    }
+    if (fileURLOrPath.protocol !== 'file:')
+      throw new ERR_INVALID_URL_SCHEME('file');
+
+    return lazyURLModule().getPathFromURLPosix(fileURLOrPath);
+  },
+
   sep: '/',
   delimiter: ':',
   win32: null,
   posix: null
 };
 
+
 posix.win32 = win32.win32 = win32;
 posix.posix = win32.posix = posix;
 

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

@@ -0,0 +1,31 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('node:assert');
+const { fromURL, win32 } = 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 an empty string', () => assert
+    .strictEqual(fromURL(''), ''));
+  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'));
+  it('should parse a windows file URI', () => {
+    const fn = common.isWindows ? fromURL : win32.fromURL;
+    assert.strictEqual(fn(new URL('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' }));
+  it('should throw an error if converting invalid types', () => [{}, [], 1, null, undefined,
+                                                                 Promise.resolve(new URL('file:///some/path/')), Symbol(), true, false, 1n, 0, 0n, () => {}]
+    .forEach((item) => assert.throws(() => fromURL(item), { code: 'ERR_INVALID_ARG_TYPE' })));
+});