node:url: accept URL-like objects in fileURLToPath

[robobun]

Reproduction

const { fileURLToPath } = require("node:url");

fileURLToPath({ href: "file:///tmp", protocol: "file:", hostname: "", pathname: "/tmp" });
// node: "/tmp"
// bun:  TypeError [ERR_INVALID_ARG_TYPE]: The "url" argument must be of type string

fileURLToPath({ href: "file:///tmp", protocol: "file:" });
// node: TypeError [ERR_INVALID_FILE_URL_HOST]
// bun:  TypeError [ERR_INVALID_ARG_TYPE]

Node's fileURLToPath accepts any object that duck-types as a WHATWG URL via isURL (truthy href and protocol, no legacy url.parse() auth/path fields) and reads protocol/hostname/pathname off it directly. Bun's node:url.fileURLToPath is the native Bun.fileURLToPath, which only accepts a real URL instance or a string.

This surfaces through any API that routes a path-or-URL through toPathIfFileURL (e.g. child_process cwd, fs.glob cwd): those already duck-typed the argument but then passed the plain object to Bun.fileURLToPath, which rejected it.

Fix

Add a fileURLToPath wrapper in internal/url alongside Node's isURL and toPathIfFileURL. Strings and real URL instances go to the native Bun.fileURLToPath unchanged; URL-like objects go through Node's getPathFromURLPosix / getPathFromURLWin32 logic (ported verbatim: hostname check, encoded-separator check, decodeURIComponent, drive-letter / UNC handling) so the observable behaviour, including which property is read when, matches Node exactly.

node:url now exports this wrapper instead of the native function. The duplicated toPathIfFileURL helpers in child_process and internal/fs/glob are replaced with the shared one from internal/url. The domainToASCII/domainToUnicode native binding moves to internal/url so the Win32 UNC path can use it; node:url re-exports them unchanged.

Bun.fileURLToPath itself is untouched: it still only accepts URL | string.

Verification

bun bd test test/js/node/url/url-fileurltopath.test.js passes (new URL-like object block covers POSIX/Windows/UNC paths, encoded-separator and host errors, legacy-Url rejection). Every case was diffed against Node v26.3.0 and matches byte-for-byte on result and error code/message. test/js/node/url/url-domain-ascii-unicode.test.js and test/js/bun/util/fileUrl.test.js pass unchanged.

Related: #33373 rewrites the native functionFileURLToPath for percent-decoding and options.windows; this change is orthogonal and layered in JS, so strings and URL instances continue to route through whichever native implementation is current.

---

no test proof · iteration 1 · Platform-specific test(s) that do not run on this machine. Deferring to CI, which covers all platforms: test/js/node/url/url-fileurltopath.test.js

[robobun]

Reproduced on main; the new URL-like object test in test/js/node/url/url-fileurltopath.test.js fails there with ERR_INVALID_ARG_TYPE and passes with this change.

CI: the diff is green on every lane that ran. Build #73151 and the re-roll #73170 both hit the same darwin-14-aarch64-test-bun agent expiring without picking up the job; every other failure is a known flake that passed on retry (webview animation timing, napi finalizer LSAN, HTTP/3 stream reset, install output ordering, RSS-threshold leak checks). None touch node:url, child_process, or fs/glob. Ready for a maintainer.

[coderabbitai]

Walkthrough

Changes

The shared internal URL module now handles URL-like object detection, file URL conversion, and domain conversion bindings. Node URL APIs, glob, and child process reuse these helpers, with new intrinsic declarations and URL-like object coverage.

Changes

URL and File URL conversion

Layer / File(s)	Summary
Shared URL and file URL helpers src/js/internal/url.ts, src/js/builtins.d.ts	Adds URL-like object detection, POSIX and Windows file URL conversion, path conversion, domain conversion bindings, and related error declarations.
Node API and path consumer wiring src/js/node/url.ts, src/js/internal/fs/glob.ts, src/js/node/child_process.ts	Routes Node URL exports and path consumers through the shared internal URL helpers.
URL-like file path validation test/js/node/url/url-fileurltopath.test.js	Tests URL-like object conversion, platform-specific behavior, decoding, UNC paths, and invalid inputs.

Suggested reviewers: alii, jarred-sumner

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly states the main change: fileURLToPath now accepts URL-like objects.
Description check	✅ Passed	The description explains the behavior change and includes verification details, covering the template's intent.

---

_{Comment @coderabbitai help to get the list of available commands.}

[robobun]

^{Updated 11:33 PM PT - Jul 14th, 2026}

✅ @robobun, your commit a895bc3362154b89ae21736a51692093fc9411fc passed in Build #73170! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 34202

That installs a local version of the PR into your bun-34202 executable, so you can run:

bun-34202 --bun

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/js/internal/url.ts`:
- Line 13: Update both native error calls in src/js/internal/url.ts: at line 13,
pass process.platform directly to $ERR_INVALID_FILE_URL_HOST instead of a
preformatted message; at line 61, pass the intrinsic "file" argument directly to
$ERR_INVALID_URL_SCHEME. Preserve the surrounding validation behavior and let
each binding generate its own error text.

In `@test/js/node/url/url-fileurltopath.test.js`:
- Around line 227-229: Update the invalid-input tests around url.fileURLToPath
to use describe.each() with the existing values [null, undefined, 1, true, {},
[], () => {}], creating an independently reported case for each rejected input
while preserving the ERR_INVALID_ARG_TYPE assertion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 52209779-2fa8-4c30-ac61-f68358df2b68

📥 Commits

Reviewing files that changed from the base of the PR and between 88403d9 and a895bc3.

📒 Files selected for processing (6)

• src/js/builtins.d.ts
• src/js/internal/fs/glob.ts
• src/js/internal/url.ts
• src/js/node/child_process.ts
• src/js/node/url.ts
• test/js/node/url/url-fileurltopath.test.js

[robobun]

Closing as part of a cleanup of stale pull requests. This PR has had no new commits since 2026-07-15 and it conflicts with main. This is not a judgment on the fix itself. If the problem still reproduces on a current build, reopen this PR after a rebase or open a new one against main.