URL Module

The std/url module provides utilities for parsing, building, encoding, and validating URLs.

Import

import { url } from "std/url";

Parsing

url.parse(rawUrl: string): any

Parses a URL string into a map with components: scheme, host, hostname, port, path, query, fragment, and raw.

const parts = url.parse("https://example.com:8080/api?q=hello#top");
println(parts["scheme"]);   // "https"
println(parts["host"]);     // "example.com:8080"
println(parts["hostname"]); // "example.com"
println(parts["port"]);     // "8080"
println(parts["path"]);     // "/api"
println(parts["query"]);    // "q=hello"
println(parts["fragment"]); // "top"

url.format(components: any): string

Builds a URL string from a map of components.

const u = url.format({
    "scheme": "https",
    "host": "example.com",
    "path": "/api/v1",
    "query": "page=1"
});
println(u); // "https://example.com/api/v1?page=1"

Query Strings

url.queryParse(queryString: string): any

Parses a query string into a map of key-value pairs.

const params = url.queryParse("name=chuks&version=1.0&lang=en");
println(params["name"]);    // "chuks"
println(params["version"]); // "1.0"

url.queryFormat(params: any): string

Builds a query string from a map.

const qs = url.queryFormat({"page": "2", "limit": "10"});
println(qs); // "limit=10&page=2"

Encoding

url.encode(str: string): string

URL-encodes a string (percent-encoding for special characters).

println(url.encode("hello world&foo=bar"));
// "hello+world%26foo%3Dbar"

url.decode(str: string): string

Decodes a URL-encoded string.

println(url.decode("hello+world%26foo%3Dbar"));
// "hello world&foo=bar"

Validation & Joining

url.isValid(rawUrl: string): bool

Returns true if the string is a valid URL with a scheme and host.

println(url.isValid("https://example.com")); // true
println(url.isValid("not a url"));           // false

url.join(base: string, path: string): string

Resolves a path against a base URL.

println(url.join("https://example.com/base/", "/api/v1"));
// "https://example.com/api/v1"

println(url.join("https://example.com/base/", "sub/page"));
// "https://example.com/base/sub/page"

Full Example

import { url } from "std/url";

// Parse a URL
const parsed = url.parse("https://api.example.com/v2/users?page=1&limit=20");
println("Host: " + parsed["host"]);
println("Path: " + parsed["path"]);

// Build query string
const qs = url.queryFormat({"search": "chuks lang", "sort": "stars"});
const fullUrl = url.join("https://api.example.com", "/repos?" + qs);
println(fullUrl);

// Encode user input for safe URLs
const userInput = "hello world & special=chars";
const safe = url.encode(userInput);
println("Encoded: " + safe);