node:url

The node:url module in Azion Runtime: URL parsing and formatting, examples for request URLs, query parameters, validation, and routing, and the supported APIs.

Last updated

View as Markdown Agent setup

The node:url module provides the Node.js utilities for resolving, parsing, and formatting URLs. With it, a function reads the parts of a URL in a structured way, changes them, and builds URLs for routing and API requests. Azion Runtime provides the module through its Node.js compatibility. A function can use it to parse the incoming request URL, read its query parameters, and build URLs when it proxies or redirects traffic. In Azion Runtime, url.URL is the same object as the global URL, and the legacy functions url.parse(), url.format(), and url.resolve() work in a deployed function.

Examples

Each example is a complete function that imports url from node:url. The response below each example is the one a deployed function returns.

URL parsing and formatting

This function creates a URL with the global URL class, builds a URL string from an object with url.format(), and parses that string with url.parse():

JavaScript
01/**
02 * An example of using Node.js URL API in an Azion Function.
03 * Support:
04 * - Partially supported (Extended by library `url`)
05 * @module runtime-apis/nodejs/url/main
06 * @example
07 * // Build and run with the Azion CLI:
08 * azion build
09 * azion dev
10 */
11import url from "node:url";
12/**
13 * An example of using the Node.js URL API in an Azion Function.
14 * @param {*} event
15 * @returns {Promise<Response>}
16 */
17const main = async (event) => {
18 /**
19 * URL globalThis object
20 * https://developer.mozilla.org/en-US/docs/Web/API/URL
21 * if use URL in the browser, don't need to import
22 */
23 const newUrl = new URL("https://example.com/some/path?format=json&page=1");
24 console.log("newURL", newUrl);
25
26 const urlFormated = url.format({
27 protocol: "https",
28 hostname: "example.com",
29 pathname: "/some/path",
30 query: {
31 page: 1,
32 format: "json",
33 },
34 });
35
36 console.log(url.parse(urlFormated));
37
38 return new Response("Done!", { status: 200 });
39};
40
41export default main;

The function responds with Done!. It logs the URL, the deprecation warning that url.parse() prints, and the parsed object:

Text
01newURL "https://example.com/some/path?format=json&page=1"
02[DeprecationWarning] [unenv] [node:url] DEP0169: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.
03{"auth":null,"hash":null,"host":"example.com","hostname":"example.com","href":"https://example.com/some/path?page=1&format=json","path":"/some/path?page=1&format=json","pathname":"/some/path","protocol":"https:","search":"?page=1&format=json","slashes":true,"port":null,"query":"page=1&format=json"}

Request URL parsing

This function reads the components of the request URL, collects its query parameters, and splits its path into segments:

JavaScript
01// url module imported for legacy API demonstration
02// new URL() and URLSearchParams are available globally
03import url from "node:url";
04
05const main = async (event) => {
06 const request = event.request;
07 const requestUrl = new URL(request.url);
08
09 // Extract URL components
10 const urlInfo = {
11 href: requestUrl.href,
12 origin: requestUrl.origin,
13 protocol: requestUrl.protocol,
14 hostname: requestUrl.hostname,
15 port: requestUrl.port,
16 pathname: requestUrl.pathname,
17 search: requestUrl.search,
18 hash: requestUrl.hash
19 };
20
21 // Parse query parameters
22 const searchParams = requestUrl.searchParams;
23 const queryParams = {};
24 for (const [key, value] of searchParams) {
25 queryParams[key] = value;
26 }
27
28 // ⚠️ url.parse() is deprecated since Node.js v11.0.0
29 // Prefer the WHATWG URL API (new URL()) shown above
30 const parsedUrl = url.parse(request.url, true);
31 console.log("Parsed URL:", parsedUrl);
32
33 // Get path segments
34 const segments = requestUrl.pathname.split("/").filter(Boolean);
35
36 return new Response(JSON.stringify({
37 urlInfo,
38 queryParams,
39 segments,
40 parsedQuery: parsedUrl.query
41 }), {
42 headers: { "Content-Type": "application/json" }
43 });
44};
45
46export default main;

For a GET request to https://example.com/blog/post-1, the function responds with the URL components, an empty query, and the two path segments:

{"urlInfo":{"href":"https://example.com/blog/post-1","origin":"https://example.com","protocol":"https:","hostname":"example.com","port":"","pathname":"/blog/post-1","search":"","hash":""},"queryParams":{},"segments":["blog","post-1"],"parsedQuery":{}}

Dynamic URL construction

This function builds an API URL with query parameters, a redirect URL with url.format(), and a URL from its parts. It also resolves a relative path twice, with url.resolve() and with the URL constructor:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 // Build API URL with query parameters
05 const apiUrl = new URL("https://api.example.com/v1/users");
06 apiUrl.searchParams.set("page", "1");
07 apiUrl.searchParams.set("limit", "10");
08 apiUrl.searchParams.set("sort", "name");
09 apiUrl.searchParams.set("active", "true");
10
11 console.log("API URL:", apiUrl.toString());
12
13 // Build redirect URL
14 const redirectUrl = url.format({
15 protocol: "https",
16 hostname: "app.example.com",
17 pathname: "/dashboard",
18 query: {
19 ref: "login",
20 session: "abc123"
21 }
22 });
23
24 // Resolve relative URL
25 // ⚠️ url.resolve() is deprecated since Node.js v11.0.0
26 // Prefer: new URL(relativePath, baseUrl).href
27 const baseUrl = "https://example.com/docs/";
28 const relativePath = "../api/reference";
29 const resolvedUrl = url.resolve(baseUrl, relativePath);
30 console.log("Resolved URL (deprecated):", resolvedUrl);
31
32 // Modern alternative using URL constructor
33 const modernResolvedUrl = new URL(relativePath, baseUrl).href;
34 console.log("Resolved URL (modern):", modernResolvedUrl);
35
36 // Build URL from parts
37 const parts = {
38 protocol: "https:",
39 hostname: "cdn.example.com",
40 port: "443",
41 pathname: "/assets/images/logo.png"
42 };
43 const fullUrl = url.format(parts);
44
45 return new Response(JSON.stringify({
46 apiUrl: apiUrl.toString(),
47 redirectUrl,
48 resolvedUrl,
49 builtUrl: fullUrl
50 }), {
51 headers: { "Content-Type": "application/json" }
52 });
53};
54
55export default main;

The function responds with the four URLs. Both ways of resolving the relative path log https://example.com/api/reference, and the URL built from parts keeps the port 443:

{"apiUrl":"https://api.example.com/v1/users?page=1&limit=10&sort=name&active=true","redirectUrl":"https://app.example.com/dashboard?ref=login&session=abc123","resolvedUrl":"https://example.com/api/reference","builtUrl":"https://cdn.example.com:443/assets/images/logo.png"}

Query parameter handling

This function reads, checks, changes, and sorts the query parameters of the request, then builds a second query string from an object:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const requestUrl = new URL(event.request.url);
05 const params = requestUrl.searchParams;
06
07 // Read parameters
08 const page = params.get("page") || "1";
09 const limit = params.get("limit") || "10";
10 const sort = params.get("sort");
11
12 console.log("Page:", page, "Limit:", limit, "Sort:", sort);
13
14 // Check if parameter exists
15 const hasFilter = params.has("filter");
16 console.log("Has filter:", hasFilter);
17
18 // Get all values for a parameter (multi-value)
19 const tags = params.getAll("tag");
20 console.log("Tags:", tags);
21
22 // Modify parameters
23 params.set("page", "2");
24 params.set("timestamp", Date.now().toString());
25 params.delete("debug");
26
27 // Iterate over parameters
28 const allParams = [];
29 for (const [key, value] of params) {
30 allParams.push({ key, value });
31 }
32
33 // Sort parameters alphabetically
34 params.sort();
35
36 // Convert to string
37 const queryString = params.toString();
38
39 // Create new URLSearchParams from object
40 const newParams = new URLSearchParams({
41 format: "json",
42 version: "2",
43 pretty: "true"
44 });
45
46 return new Response(JSON.stringify({
47 originalParams: { page, limit, sort },
48 hasFilter,
49 tags,
50 modifiedParams: allParams,
51 queryString,
52 newParamsString: newParams.toString()
53 }), {
54 headers: { "Content-Type": "application/json" }
55 });
56};
57
58export default main;

For a request without a query string, the function responds with the default values, the changed parameters, and both query strings. The timestamp value comes from Date.now():

{"originalParams":{"page":"1","limit":"10","sort":null},"hasFilter":false,"tags":[],"modifiedParams":[{"key":"page","value":"2"},{"key":"timestamp","value":"1767268800000"}],"queryString":"page=2&timestamp=1767268800000","newParamsString":"format=json&version=2&pretty=true"}

URL validation and normalization

This function checks a list of URLs with the URL constructor, then normalizes each valid URL: it lowercases the hostname and removes a default port:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const request = event.request;
05 // Note: In a real application, you might receive URLs from the request body
06 // const { urls: customUrls } = await request.json().catch(() => ({}));
07
08 // URLs to validate
09 const testUrls = [
10 "https://example.com/path",
11 "http://localhost:3000/api?query=test",
12 "HTTPS://EXAMPLE.COM/UPPERCASE",
13 "https://example.com:443/standard-port",
14 "https://user:pass@example.com/auth",
15 "not-a-url",
16 "ftp://files.example.com"
17 ];
18
19 const results = testUrls.map(testUrl => {
20 try {
21 const parsed = new URL(testUrl);
22 return {
23 original: testUrl,
24 valid: true,
25 normalized: parsed.href,
26 protocol: parsed.protocol,
27 hostname: parsed.hostname,
28 isHttps: parsed.protocol === "https:"
29 };
30 } catch (error) {
31 return {
32 original: testUrl,
33 valid: false,
34 error: error.message
35 };
36 }
37 });
38
39 // Normalize a URL (lowercase hostname, default port removal)
40 const normalizeUrl = (urlString) => {
41 try {
42 const parsed = new URL(urlString);
43 parsed.hostname = parsed.hostname.toLowerCase();
44
45 // Remove default ports
46 if (parsed.protocol === "https:" && parsed.port === "443") {
47 parsed.port = "";
48 }
49 if (parsed.protocol === "http:" && parsed.port === "80") {
50 parsed.port = "";
51 }
52
53 return parsed.href;
54 } catch {
55 return null;
56 }
57 };
58
59 const normalizedUrls = testUrls.map(normalizeUrl);
60
61 return new Response(JSON.stringify({
62 validationResults: results,
63 normalizedUrls
64 }), {
65 headers: { "Content-Type": "application/json" }
66 });
67};
68
69export default main;

The function responds with the result for each URL and the normalized list. The URL constructor rejects not-a-url with the message Invalid URL: 'not-a-url', and the normalized list holds null in its place:

{"validationResults":[{"original":"https://example.com/path","valid":true,"normalized":"https://example.com/path","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"http://localhost:3000/api?query=test","valid":true,"normalized":"http://localhost:3000/api?query=test","protocol":"http:","hostname":"localhost","isHttps":false},{"original":"HTTPS://EXAMPLE.COM/UPPERCASE","valid":true,"normalized":"https://example.com/UPPERCASE","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"https://example.com:443/standard-port","valid":true,"normalized":"https://example.com/standard-port","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"https://user:pass@example.com/auth","valid":true,"normalized":"https://user:pass@example.com/auth","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"not-a-url","valid":false,"error":"Invalid URL: 'not-a-url'"},{"original":"ftp://files.example.com","valid":true,"normalized":"ftp://files.example.com/","protocol":"ftp:","hostname":"files.example.com","isHttps":false}],"normalizedUrls":["https://example.com/path","http://localhost:3000/api?query=test","https://example.com/UPPERCASE","https://example.com/standard-port","https://user:pass@example.com/auth",null,"ftp://files.example.com/"]}

URL routing and path matching

This function matches the request path against a route table, including a route with an :id parameter, and checks whether the route accepts the request method. It answers 404 when no route matches, and 405 when a route matches but its methods do not include the request method:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const requestUrl = new URL(event.request.url);
05 const pathname = requestUrl.pathname;
06
07 // Define routes
08 const routes = {
09 "/": { handler: "home", methods: ["GET"] },
10 "/api/users": { handler: "users", methods: ["GET", "POST"] },
11 "/api/users/:id": { handler: "userDetail", methods: ["GET", "PUT", "DELETE"] },
12 "/api/products": { handler: "products", methods: ["GET"] },
13 "/health": { handler: "health", methods: ["GET"] }
14 };
15
16 // Match route
17 const matchRoute = (path) => {
18 // Exact match
19 if (routes[path]) {
20 return { ...routes[path], params: {} };
21 }
22
23 // Pattern match for :id style routes
24 for (const [pattern, config] of Object.entries(routes)) {
25 if (pattern.includes(":")) {
26 const regex = new RegExp("^" + pattern.replace(/:\w+/g, "([^/]+)") + "$");
27 const match = path.match(regex);
28 if (match) {
29 const paramNames = pattern.match(/:\w+/g) || [];
30 const params = {};
31 paramNames.forEach((name, i) => {
32 params[name.slice(1)] = match[i + 1];
33 });
34 return { ...config, params };
35 }
36 }
37 }
38
39 return null;
40 };
41
42 const matchedRoute = matchRoute(pathname);
43 const method = event.request.method;
44
45 // Check if method is allowed
46 const methodAllowed = matchedRoute?.methods?.includes(method);
47
48 // Build response
49 const response = {
50 pathname,
51 method,
52 matched: matchedRoute ? {
53 handler: matchedRoute.handler,
54 params: matchedRoute.params,
55 methodAllowed
56 } : null,
57 query: Object.fromEntries(requestUrl.searchParams)
58 };
59
60 return new Response(JSON.stringify(response, null, 2), {
61 status: matchedRoute && methodAllowed ? 200 : matchedRoute ? 405 : 404,
62 headers: { "Content-Type": "application/json" }
63 });
64};
65
66export default main;

For a GET request to https://example.com/blog/post-1, a path the route table does not list, the function takes its no-match branch and responds with status 404 and this body:

JSON
01{
02 "pathname": "/blog/post-1",
03 "method": "GET",
04 "matched": null,
05 "query": {}
06}

Supported APIs

The table lists the status of each node:url API in Azion Runtime:

APIStatus
URL (global)🟢 Supported
URLSearchParams🟢 Supported
url.URL🟢 Supported
url.URLSearchParams🟢 Supported
url.format()🟢 Supported
url.parse()🟡 Supported (deprecated, use new URL())
url.resolve()🟡 Supported (deprecated, use new URL(relative, base))
url.domainToASCII()🟡 Partially supported
url.domainToUnicode()🟡 Partially supported
url.fileURLToPath()🟡 Partially supported
url.pathToFileURL()🟡 Partially supported
url.urlToHttpOptions()🟡 Partially supported

APIs marked 🟡 Partially supported have limited functionality compared to the full Node.js implementation. In a deployed function, url.fileURLToPath("file:///tmp/x.txt") returns /tmp/x.txt, url.pathToFileURL("/tmp/x.txt") returns file:///tmp/x.txt, and url.domainToASCII("español.com") returns xn--espaol-zwa.com.

A function that calls url.parse() can log this deprecation warning, as the first example shows:

[DeprecationWarning] [unenv] [node:url] DEP0169: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.

Node.js deprecates url.parse(), url.resolve(), and url.format() from v11.0.0. Use the WHATWG URL and URLSearchParams APIs instead: in Azion Runtime, both are globals that need no import.

Node.js APIs

Every Node.js module Azion Runtime resolves, and the status of url among them.

Use Node.js APIs through polyfills

How the build resolves node:url and the other Node.js imports for Azion Runtime.

Node.js url documentation

The Node.js reference for each node:url API the table lists.

MDN URL API documentation

The Web reference for the global URL class that every example uses.