zena:url

An immutable, parsed URL. Components are exposed with the same names and string shapes as the web API (protocol includes ':', search includes '?', hash includes '#', all empty when absent).

One piece of a parsed pattern.

prefix and suffix are the literal text bound to the part rather than standing on its own — the / in /users/:id belongs to the id part, so that an optional part takes its separator with it when it is absent. Both are empty when there is none, which is a real answer rather than an absent one, so they live on the base alongside the modifier and the component.

The variants are suffixed Part because Regex alone would collide with zena:regex's, and URLPattern will import both.

Raised for a pattern string that cannot be parsed.

A pattern over the components of a URL.

Construction normalizes: every component is parsed and written back out, so the pattern a URLPattern reports is a canonical spelling of the one it was given rather than the text that came in.

Matching is not implemented yet — this builds and exposes the component patterns only.

One component's pattern, as supplied to the constructor.

Every field is nullable because absent and empty mean different things here: an absent component may be inherited from baseURL, while an empty one is a pattern that matches only the empty string. JavaScript draws that line with undefined, which Zena does not have, so null draws it instead.

The fields are mutable and the constructor takes no arguments, so callers set only what they mean to constrain.

An ordered, mutable list of (name, value) pairs — the application/x-www-form-urlencoded half of the WHATWG URL Standard (https://url.spec.whatwg.org/#interface-urlsearchparams).

Order is significant and duplicate names are allowed, so this is a multimap over a list, not a map. Unlike URL this type is mutable: it is a collection/builder, like GrowableArray or StringBuilder.

Names and values are held DECODED. Percent-encoding and +-for-space happen only at toString, so a value containing & or = round-trips.

Thrown when a URLSearchParams is mutated while an iteration over it is still in progress.

This is a deliberate divergence from the web API, which iterates live: in JS, deleting a pair during a for...of silently SKIPS the following pair (WebIDL's default pair iterator indexes into the current list and re-reads it on every step), and appending during iteration never terminates. Both produce a wrong answer with no signal, so this follows Java's fail-fast collections instead and reports the bug where it happens.

Like Java's, the check is best-effort: it exists to catch mistakes, not to make concurrent mutation safe.

Lives here rather than in zena:error because URLSearchParams is the only collection that currently detects this; it should move if others adopt the same discipline.

The percent-encode sets defined by the URL Standard. Each set includes all of the sets above it (C0 control ⊂ fragment ⊂ ... is not a strict chain — fragment and query diverge — but every set includes the C0 control set).

How many times a part may repeat.

Which URL component a pattern was written for.

True when byte b must be percent-encoded for set. Bytes outside 0x20..0x7E (C0 controls, DEL, and all non-ASCII bytes) are encoded in every set.

Percent-encodes input for the given encode set. spaceAsPlus implements the form-urlencoded serializer's special case (0x20 → '+').

Percent-decodes input (https://url.spec.whatwg.org/#percent-decode). A '%' not followed by two hex digits is passed through unchanged, per spec. plusAsSpace implements the form-urlencoded parser's '+' → 0x20 rule.

Appends b to sb, percent-encoded if set requires it. This is the byte-at-a-time form the URL parser builds components with.

Parses an application/x-www-form-urlencoded string into ordered (name, value) pairs (https://url.spec.whatwg.org/#urlencoded-parsing). A leading '?' is NOT stripped here — callers strip it (the URL API layer does, matching URLSearchParams).

Serializes ordered (name, value) pairs to application/x-www-form-urlencoded (https://url.spec.whatwg.org/#concept-urlencoded-serializer).

Builds a URL from a template, percent-encoding every interpolated value for the component it lands in.

let team = 'a/b team';
url`https://example.com/teams/${team}`;  // .../teams/a%2Fb%20team
url`https://example.com/s?q=${team}`;    // ...?q=a%2Fb%20team

Values are encoded with the component percent-encode set, which covers every delimiter that could end the component early — /, ?, #, &, =, and % itself — so an interpolation cannot add a path segment, start a query, or smuggle in an extra parameter.

Interpolation is only allowed in the path, query, and fragment. A hole in the scheme, credentials, host, or port returns null: those parts are not percent-decoded when parsed — a host goes through IDNA and IP parsing on its raw text — so there is no encoding that would make an untrusted value safe there, and pretending otherwise is worse than refusing. Build those with URL.parse and the with* methods if you need them dynamic.

The template must be an absolute URL; like URL.parse, anything that does not parse comes back as null.

Parses one component's pattern string into its parts.

componentType is carried on every part rather than used during parsing: a prefix tree spanning a whole URL needs to know which component a part came from, and the caller knows it here.

encode is applied to literal text only — fixed values, prefixes and suffixes — and defaults to leaving it alone. URLPattern passes the percent-encoder for the component being parsed, which is why it cannot be done to the pattern string as a whole: that would encode the pattern syntax along with the text.

Encodes one label, per RFC 3492 section 6.3.

The result carries no "xn--" prefix. An all-ASCII label encodes to itself followed by a '-', which is what the RFC specifies even though IDNA never has a reason to encode such a label.

Returns null if the input is not well-formed UTF-8, or if the label is so pathological that the encoder's arithmetic would overflow.

Decodes one label, per RFC 3492 section 6.2.

The input must not carry the "xn--" prefix. Returns null for a label that is not valid Punycode: a bad digit, arithmetic that would overflow, a non-ASCII byte in the literal portion, or a result outside the Unicode scalar range.