feat(utils): add requestWithURL and requestWithBaseURL utils

Lightweight request proxying via `Proxy` to override the URL without
cloning the entire `Request` object. Uses a shared proxy handler with
a `WeakMap` for per-proxy URL storage to minimize allocations.

`requestWithBaseURL` strips a base path prefix from the request URL
and is now used internally by `H3.mount()` instead of `new Request()`.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pi0

src/h3.ts

@@ -2,6 +2,7 @@ import { createRouter, addRoute, findRoute } from "rou3";
 import { H3Event } from "./event.ts";
 import { toResponse, kNotFound } from "./response.ts";
 import { callMiddleware, normalizeMiddleware } from "./middleware.ts";
+import { requestWithBaseURL } from "./utils/request.ts";
 
 import type { ServerRequest } from "srvx";
 import type { H3Config, H3CoreConfig, H3Plugin, MatchedRoute, RouterContext } from "./types/h3.ts";
@@ -142,9 +143,7 @@ export const H3 = /* @__PURE__ */ (() => {
       } else {
         const fetchHandler = "fetch" in input ? input.fetch : input;
         this.all(`${base}/**`, function _mountedMiddleware(event) {
-          const url = new URL(event.url);
-          url.pathname = url.pathname.slice(base.length) || "/";
-          return fetchHandler(new Request(url, event.req));
+          return fetchHandler(requestWithBaseURL(event.req, base));
         });
       }
       return this;

src/index.ts

@@ -82,6 +82,8 @@ export { type RouteDefinition, defineRoute } from "./utils/route.ts";
 // Request
 
 export {
+  requestWithURL,
+  requestWithBaseURL,
   toRequest,
   getRequestHost,
   getRequestIP,

src/utils/request.ts

@@ -11,6 +11,36 @@ import type { HTTPMethod } from "../types/h3.ts";
 import type { H3EventContext } from "../types/context.ts";
 import type { ServerRequest } from "srvx";
 
+const _urlOverrides = new WeakMap<Request, string>();
+
+const _proxyHandler: ProxyHandler<Request> = {
+  get(target, prop, receiver) {
+    if (prop === "url") return _urlOverrides.get(receiver);
+    const value = Reflect.get(target, prop);
+    return typeof value === "function" ? value.bind(target) : value;
+  },
+};
+
+/**
+ * Create a lightweight request proxy that overrides only the URL.
+ *
+ * Avoids cloning the original request (no `new Request()` allocation).
+ */
+export function requestWithURL(req: ServerRequest, url: string): ServerRequest {
+  const proxy = new Proxy(req, _proxyHandler);
+  _urlOverrides.set(proxy, url);
+  return proxy;
+}
+
+/**
+ * Create a lightweight request proxy with the base path stripped from the URL pathname.
+ */
+export function requestWithBaseURL(req: ServerRequest, base: string): ServerRequest {
+  const url = new URL(req.url);
+  url.pathname = url.pathname.slice(base.length) || "/";
+  return requestWithURL(req, url.href);
+}
+
 /**
  * Convert input into a web [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request).
  *

test/unit/package.test.ts

@@ -106,6 +106,8 @@ describe("h3 package", () => {
         "readValidatedBody",
         "redirect",
         "removeResponseHeader",
+        "requestWithBaseURL",
+        "requestWithURL",
         "requireBasicAuth",
         "sanitizeStatusCode",
         "sanitizeStatusMessage",

test/unit/request.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { requestWithURL, requestWithBaseURL } from "../../src/utils/request.ts";
+
+describe("requestWithURL", () => {
+  const original = new Request("http://example.com/base/path", {
+    method: "POST",
+    headers: { "x-test": "value" },
+    body: "hello",
+  });
+
+  it("overrides url", () => {
+    const proxied = requestWithURL(original, "http://example.com/path");
+    expect(proxied.url).toBe("http://example.com/path");
+  });
+
+  it("preserves original url on source request", () => {
+    requestWithURL(original, "http://example.com/path");
+    expect(original.url).toBe("http://example.com/base/path");
+  });
+
+  it("preserves method", () => {
+    const proxied = requestWithURL(original, "http://example.com/path");
+    expect(proxied.method).toBe("POST");
+  });
+
+  it("preserves headers", () => {
+    const proxied = requestWithURL(original, "http://example.com/path");
+    expect(proxied.headers.get("x-test")).toBe("value");
+  });
+
+  it("is instanceof Request", () => {
+    const proxied = requestWithURL(original, "http://example.com/path");
+    expect(proxied instanceof Request).toBe(true);
+  });
+
+  it("clone() works and keeps overridden url", () => {
+    const proxied = requestWithURL(original, "http://example.com/path");
+    const cloned = proxied.clone();
+    expect(cloned.url).toBe("http://example.com/base/path");
+    expect(cloned.method).toBe("POST");
+  });
+});
+
+describe("requestWithBaseURL", () => {
+  const original = new Request("http://example.com/base/path?q=1", {
+    method: "POST",
+    headers: { "x-test": "value" },
+    body: "hello",
+  });
+
+  it("strips base from pathname", () => {
+    const proxied = requestWithBaseURL(original, "/base");
+    expect(proxied.url).toBe("http://example.com/path?q=1");
+  });
+
+  it("returns / when pathname equals base", () => {
+    const req = new Request("http://example.com/base");
+    const proxied = requestWithBaseURL(req, "/base");
+    expect(new URL(proxied.url).pathname).toBe("/");
+  });
+
+  it("preserves query string", () => {
+    const proxied = requestWithBaseURL(original, "/base");
+    expect(new URL(proxied.url).search).toBe("?q=1");
+  });
+
+  it("preserves method and headers", () => {
+    const proxied = requestWithBaseURL(original, "/base");
+    expect(proxied.method).toBe("POST");
+    expect(proxied.headers.get("x-test")).toBe("value");
+  });
+
+  it("is instanceof Request", () => {
+    const proxied = requestWithBaseURL(original, "/base");
+    expect(proxied instanceof Request).toBe(true);
+  });
+});