velt/net/url

API reference

A WHATWG-style URL and URLSearchParams, plus JS's URI encoding functions (encodeURIComponent and the others): globals, as in Node; velt/net/url exports them too. For a walkthrough, read the guide.

import { decodeURI, UrlError } from "velt/net/url";

Exports

decodeURIJS decodeURI: like decodeURIComponent, but escapes of ;/?:@&=+$,# stay escaped.decodeURIComponentJS decodeURIComponent; throws URIError("URI malformed") on a bad escape or invalid UTF-8.encodeURIJS encodeURI: like encodeURIComponent, but keeps ;,/?:@&=+$#.encodeURIComponentJS encodeURIComponent: escapes everything except alphanumerics and -_.!~*'(); throws URIError("URI malformed") on a lone surrogate, as JS.UrlErrorThrown for invalid URLs (Invalid URL: <input>, Invalid base URL: <base>): a TypeError, as in JS.URLSearchParamsAn ordered list of name/value pairs in application/x-www-form-urlencoded form (JS URLSearchParams).URLA parsed absolute URL (JS URL).

function

decodeURI

#std/net/url/uri.vlt:37

Re-exported from velt/net/url/uri

function decodeURI(s: string): string

JS decodeURI: like decodeURIComponent, but escapes of ;/?:@&=+$,# stay escaped.

function

decodeURIComponent

#std/net/url/uri.vlt:28

Re-exported from velt/net/url/uri

function decodeURIComponent(s: string): string

JS decodeURIComponent; throws URIError("URI malformed") on a bad escape or invalid UTF-8.

function

encodeURI

#std/net/url/uri.vlt:19

Re-exported from velt/net/url/uri

function encodeURI(s: string): string

JS encodeURI: like encodeURIComponent, but keeps ;,/?:@&=+$#.

function

encodeURIComponent

#std/net/url/uri.vlt:10

Re-exported from velt/net/url/uri

function encodeURIComponent(s: string): string

JS encodeURIComponent: escapes everything except alphanumerics and -_.!~*'(); throws URIError("URI malformed") on a lone surrogate, as JS.

class

UrlError

#std/net/url/errors.vlt:7

Re-exported from velt/net/url/errors

class UrlError extends TypeError

Thrown for invalid URLs (Invalid URL: <input>, Invalid base URL: <base>): a TypeError, as in JS. The URI functions throw the prelude's URIError (URI malformed).

class

URLSearchParams

#std/net/url/search_params.vlt:10

Re-exported from velt/net/url/search_params

An ordered list of name/value pairs in application/x-www-form-urlencoded form (JS URLSearchParams). Names may repeat; order is kept.

Parameter ofURL.searchParamsReturned byURL.searchParamsUsed byvelt/net/httpBodyInit

constructor(init: string = "")

Parses a query string (a leading ? is skipped; + means space; bad escapes stay literal).

get size(): usize

Number of pairs.

get(name: string): string | null

The first value for name, or null.

getAll(name: string): string[]

Every value for name, in order.

has(name: string, value: string | null = null): bool

Whether a pair named name (with value value, if given) exists.

append(name: string, value: string)

Adds a pair at the end.

set(name: string, value: string)

Sets the first pair named name to value and removes the others (appends if none).

delete(name: string, value: string | null = null)

Removes every pair named name (with value value, if given).

sort()

Stable sort by name, in UTF-16 code-unit order as in JS.

keys(): string[]

The names, in order (repeats included).

values(): string[]

The values, in order.

entries(): [string, string][]

[name, value] pairs, in order.

toString(): string

a=1&b=x+y (form encoding: space as +, everything but *-._ and alphanumerics escaped).

class

URL

#std/net/url/url.vlt:16

Re-exported from velt/net/url/url

A parsed absolute URL (JS URL).

Parameter ofvelt/net/httpfetchRequest.constructor

constructor(input: string, base: string | null = null)

Parses input, resolved against base when it is relative; throws UrlError.

static parse(input: string, base: string | null = null): URL | null

Like the constructor, but null instead of throwing (JS URL.parse).

static canParse(input: string, base: string | null = null): bool

Whether new URL(input, base) would succeed.

get href(): string

The whole URL; assigning reparses it (throws UrlError if invalid).

set href(v: string)No doc comment yet

get protocol(): string

The scheme with its colon, e.g. https:.

set protocol(value: string)

Switches between schemes of the same kind (special or not), like JS.

get username(): string

Percent-encoded user name ("" if none).

set username(v: string)No doc comment yet

get password(): string

Percent-encoded password ("" if none).

set password(v: string)No doc comment yet

get host(): string

hostname:port, or just the hostname when the port is absent or the scheme's default.

set host(v: string)

Takes the host (and a port after :) up to the first /, ? or #; ignored when the host is invalid, or empty where the URL needs one (a special scheme, credentials or a port). An empty port keeps the current one.

get hostname(): string

The host without the port (lowercased for special schemes; IPv6 keeps its brackets).

set hostname(v: string)

Like host, but a value with a port (h:8) is ignored.

get port(): string

The port as written ("" when absent or the scheme's default, e.g. 443 for https).

set port(value: string)

Takes the leading digits of value ("" clears the port); ignored when out of range or when the URL cannot have a port (no host, or file:).

get pathname(): string

The path, e.g. /a/b (percent-encoded; for mailto:x it is x).

set pathname(v: string)No doc comment yet

get search(): string

? + the query, or "" when the query is absent or empty.

set search(v: string)No doc comment yet

get hash(): string

# + the fragment, or "" when it is absent or empty.

set hash(v: string)No doc comment yet

get origin(): string

scheme://host[:port] for http(s), ws(s) and ftp; "null" for other schemes (JS).

get searchParams(): URLSearchParams

A copy of the parsed query (see the header for how to write it back).

set searchParams(p: URLSearchParams)

Replaces the query with p serialized (no query if p is empty).

toString(): string

Same as href.

toJSON(): string

Same as href (JS toJSON).