url: add fileURLToPathBuffer API

[jasnell]

The existing fileURLToPath() does not handle the case where the input URL contains percent-encoded characters that are not valid UTF-8 sequences. This can lead to issues, for instance, when the URL is constructed using file names in non-Unicode encodings (like Shift-JIS). This commit introduces a new API, fileURLToPathBuffer(), which returns a Buffer representing the path, allowing for accurate conversion of file URLs to paths without attempting to decode the percent-encoded bytes into characters.

This is part of the fix for #58634 but there's more to do.

[nodejs-github-bot]

Review requested:

• @nodejs/startup
• @nodejs/url

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/67426/

[codecov]

Codecov Report

Attention: Patch coverage is 48.76033% with 62 lines in your changes missing coverage. Please review.

Project coverage is 90.12%. Comparing base (5e1537c) to head (e362a1e).
Report is 16 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/url.js	47.45%	62 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #58700 +/- ##
==========================================
- Coverage 90.16% 90.12% -0.04% 
==========================================
Files 637 637 Lines 188098 188122 +24 Branches 36905 36898 -7 ==========================================
- Hits 169601 169548 -53 - Misses 11231 11319 +88 + Partials 7266 7255 -11 

Files with missing lines	Coverage Δ
lib/internal/data_url.js	100.00% <100.00%> (+8.23%)	⬆️
lib/url.js	100.00% <100.00%> (ø)
lib/internal/url.js	94.38% <47.45%> (-3.48%)	⬇️

... and 47 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/67427/ 💛

[mcollina]

lgtm

what could we do with this buffer? How could a user manipulate this?

[jasnell]

what could we do with this buffer?

It can be passed directly to node:fs APIs. More importantly tho, it's to help fix the issue discussed in #58634 by making it possible to normalize the arguments passed into the filter callback.

[Ethan-Arrowood]

I wont block on my one change recommendation, but please consider it in regards to consistency with path.win32 and path.posix pattern.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/58700
✔ Done loading data for nodejs/node/pull/58700
----------------------------------- PR info ------------------------------------
Title url: add fileURLToPathBuffer API (#58700)
Author James M Snell <jasnell@gmail.com> (@jasnell)
Branch jasnell:jasnell/add-fileurltopathbuffer -> nodejs:main
Labels fs, url, semver-minor, whatwg-url, author ready, needs-ci
Commits 1
- url: add fileURLToPathBuffer API
Committers 1
- James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/58700
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/58700
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: LiviaMedeiros <livia@cirno.name>
--------------------------------------------------------------------------------
ℹ This PR was created on Thu, 12 Jun 2025 20:49:22 GMT
✔ Approvals: 3
✔ - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/58700#pullrequestreview-2927770869
✔ - Ethan Arrowood (@Ethan-Arrowood): https://github.com/nodejs/node/pull/58700#pullrequestreview-2928406839
✔ - LiviaMedeiros (@LiviaMedeiros): https://github.com/nodejs/node/pull/58700#pullrequestreview-2928714008
✘ Last GitHub CI failed
ℹ Last Full PR CI on 2025-06-14T19:33:13Z: https://ci.nodejs.org/job/node-test-pull-request/67444/
- Querying data for job/node-test-pull-request/67444/
✔ Last Jenkins CI successful
--------------------------------------------------------------------------------
✔ Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/15656016109

[jasnell]

Landed in 3f6ad56