nodeurl

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package nodeurl ports the Node URL host/path handling and fileURLToPath semantics used by PiG.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeURIComponent

func DecodeURIComponent(s string) (string, error)

DecodeURIComponent is JavaScript's decodeURIComponent: every %XX becomes its byte, and a malformed escape or invalid UTF-8 is a URIError.

func DomainToUnicode

func DomainToUnicode(host string) string

DomainToUnicode is Node's url.domainToUnicode for a host FileHost returned: an IP address is unchanged, and a domain's IDNA labels become Unicode.

func FileHost

func FileHost(server string) (string, error)

FileHost is the WHATWG host parser's result for a file URL's host: an IPv6 address in brackets, a dotted IPv4 address, or a lowercase ASCII domain, where localhost is empty. The input is percent-decoded first, as the parser does.

func FileURLToPath

func FileURLToPath(raw string, windows bool) (string, error)

FileURLToPath converts raw as Node's url.fileURLToPath(raw, {windows}) does: raw is parsed as a WHATWG URL, and a Windows host names a UNC server in Unicode. It returns the Error Node throws for a URL that does not parse, is not a file URL, encodes a path separator, has a host on POSIX, or on Windows has neither a host nor a drive letter.

func FormURLEncode

func FormURLEncode(value string) string

FormURLEncode is the application/x-www-form-urlencoded byte serializer that `URLSearchParams.toString()` uses: ASCII alphanumerics and "*-._" stay, a space becomes "+", and every other byte is percent-encoded.

func PathToFileURL

func PathToFileURL(path string, windows bool) string

PathToFileURL is Node 24.19.0's url.pathToFileURL(path, { windows }).href. It resolves path as path.posix or path.win32 does, keeps a trailing separator, and percent-encodes what Node's encodePathChars and the WHATWG path state encode: C0 controls, space, `"#%<>?[\]^` + "`{|}~", DEL and every non-ASCII byte. A Windows UNC path names the URL's host.

func PrepareInput

func PrepareInput(raw string) string

PrepareInput applies the URL parser's C0/space trimming and tab/newline removal.

func RequestURL

func RequestURL(serialized string) (*url.URL, error)

RequestURL represents an already-resolved WHATWG URL without net/url rewriting its serialized spelling. Opaque retains path characters and malformed percent escapes that Go's RawPath cannot represent; Host and Path still identify the request destination.

func ResolveDirectoryPath

func ResolveDirectoryPath(raw, relativePath string) (string, error)

ResolveDirectoryPath is `const base = new URL(raw); base.pathname = base.pathname.replace(/\/+$/u, "") + "/"; new URL(relativePath, base).toString()` for a path-relative reference: the base path becomes a directory (the pathname setter's encoding and dot-segment rules apply), the base query and fragment are dropped, and a base that is not a valid URL, or whose path is opaque, fails as the constructors do.

func SearchPairs

func SearchPairs(query string) [][2]string

SearchPairs is the list `new URLSearchParams(query)` holds for a query without its leading "?": the decoded name and value of each pair, in order, with repeated names kept.

func SearchParams

func SearchParams(query string) url.Values

SearchParams is `new URLSearchParams(query)` for a query without its leading "?": the application/x-www-form-urlencoded parser. Unlike url.ParseQuery it keeps a pair containing ";" and a malformed percent escape, which it leaves as written, and it decodes each name and value as UTF-8 with replacement.

func SpecialHost

func SpecialHost(server string) (string, error)

SpecialHost parses the host of a WHATWG special URL. Unlike FileHost, localhost remains a hostname.

func SpecialPath

func SpecialPath(pathname string, file bool) string

SpecialPath resolves dot segments in a special URL pathname. File URLs additionally preserve and normalize a leading Windows drive letter.

Types

type Error

type Error struct {
	Code    string
	Message string
}

Error is an error Node's url.fileURLToPath throws, with its code. URIError comes from decodeURIComponent and has no code.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Thrown

func (e *Error) Thrown() string

Thrown is String(e) of the error Node throws: its name, code and message, `TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute`, or `URIError: URI malformed` for the decodeURIComponent failure, which has no code. A program that does not catch it reports this headline.

type HTTPHref

type HTTPHref struct {
	HTTPURL
	// Href is the serialized URL and Origin its origin, as `new URL(raw).href` and `.origin` give them: dot segments
	// resolved, the path, query and fragment percent-encoded, the default port and an empty path normalized.
	Href   string
	Origin string
	// The embedded Pathname is `new URL(raw).pathname`.
	// Username and Password are the percent-encoded userinfo. Query and Fragment are the encoded text after "?" and
	// "#", with HasQuery and HasFragment telling an empty one from an absent one.
	Username, Password string
	Query, Fragment    string
	HasQuery           bool
	HasFragment        bool
}

HTTPHref is an http or https URL with the serialization of `new URL(raw)`.

func ParseHTTPHref

func ParseHTTPHref(raw string) (HTTPHref, error)

ParseHTTPHref is ParseHTTPURL with the serialized URL, origin, pathname, userinfo, query and fragment.

type HTTPURL

type HTTPURL struct {
	Protocol string
	Hostname string
	Port     string
	Pathname string
	Search   string
	Hash     string
}

HTTPURL is the part of a WHATWG http or https URL that Node's `new URL(value)` exposes as protocol, hostname, port, pathname, search and hash. Pathname is Node's: dot segments (including "%2e") and backslashes are resolved and the path percent-encode set is applied. Search and Hash keep the raw query and fragment after the "?" or "#": the parser's percent-encoding is not applied, so they equal Node's values only in being empty or not.

func ParseHTTPURL

func ParseHTTPURL(raw string) (HTTPURL, error)

ParseHTTPURL is `URL.canParse(raw)` and `new URL(raw)` for an http or https URL without a base. It fails for a URL the parser rejects and for any other scheme, which the callers treat alike: they accept only `http:` and `https:`.

func (HTTPURL) Origin

func (u HTTPURL) Origin() string

Origin is the URL's ASCII serialized origin, as Node's `url.origin` gives it for an http or https URL.

type URL

type URL struct {
	Protocol string
	Username string
	Password string
	Hostname string
	// Port is the serialized port: "" when absent or the default of a special scheme.
	Port string
	// Pathname is the serialized path: "/..." for a special URL or any URL with a leading slash, the opaque text after "scheme:" for a URL without
	// an authority or leading slash, and "" for a host with no path.
	Pathname string
	// Hash is "#" and the percent-encoded fragment, or "" when the fragment is absent or empty.
	Hash string
	// Query is the percent-encoded text after "?", as `url.search` gives it without the "?"; `new URLSearchParams(url.search)` and SearchParams(Query) hold the same pairs.
	Query string
	// contains filtered or unexported fields
}

URL is the part of a WHATWG URL that Node's `new URL(value)` exposes as protocol, username, password, hostname, pathname and hash, for any scheme the parser can read without a base.

func ParseURL

func ParseURL(raw string) (URL, error)

ParseURL is `new URL(raw)` without a base, for every scheme. The special schemes other than file (http, https, ws, wss, ftp) go through the WHATWG special parser, file through the file URL parser, and every other scheme is a non-special URL: "//" starts an authority whose host is opaque (not lowercased, forbidden code points rejected, a bracketed IPv6 address allowed), a leading "/" starts a path, and anything else is an opaque path. It fails where Node throws: a missing or invalid scheme, an invalid host, a port that is not digits or is above 65535, or credentials or a port without a host.

func ResolveURL

func ResolveURL(input, base string) (URL, error)

ResolveURL is `new URL(input, base)` for a base with a special scheme other than file (http, https, ws, wss, ftp). An input naming another scheme, or a different special one, is parsed on its own with ParseURL; an input naming the base's scheme without an authority is relative to the base. A relative input resolves as the parser's relative state does: "//" and "\\" start an authority, "/" a path, "?" and "#" replace the query or the fragment, and anything else replaces the base path's last segment.

func (URL) Href

func (u URL) Href() string

Href is `new URL(raw).toString()`.

func (URL) Origin

func (u URL) Origin() string

Origin is `url.origin`: scheme, host and port of a special URL other than file; for a blob URL, the origin of the http or https URL its path holds; and "null" for every other URL, file included, whose origin is opaque.

func (URL) ResolveAbsolutePath

func (u URL) ResolveAbsolutePath(path string) (string, error)

ResolveAbsolutePath is `new URL(path, base).toString()` for a path that starts with a single "/" and is already in its serialized form (no dot segments, nothing the path percent-encode set changes): the scheme, userinfo and host of the base, the path, no query and no fragment. A file base whose first path segment starts with a drive letter ("C:", the two-character test of Node's URL parser) keeps that segment unless the path starts with a drive letter itself. It fails where the constructor throws: a base whose path is opaque (no authority and no leading slash) cannot be a base.

func (URL) ResolveRelativePath

func (u URL) ResolveRelativePath(ref string) (URL, error)

ResolveRelativePath is `new URL(ref, base)` for a relative path reference, one that has no scheme and does not start with "/", "?" or "#": the base's path up to and including its last "/" followed by ref, parsed again as a URL (dot segments, percent-encoding), with the base's query and fragment dropped. A base whose path is opaque cannot be a base. An empty path counts as "/". A file base whose only path segment starts with a letter and ":" keeps that segment, as the parser's path shortening does for a Windows drive letter (Node applies it to any such prefix, not only "a:").

func (URL) String

func (u URL) String() string

String is the href, as `String(url)` and a template literal give it.

func (URL) WithPathname

func (u URL) WithPathname(path string) string

WithPathname is `url.pathname = path; url.toString()`: the href with its path replaced. The path is used as given, as setting it would encode. The setter does nothing to a URL with an opaque path (no authority, and a path that does not start with "/"), so its href is unchanged.

func (URL) WithPort

func (u URL) WithPort(port string) URL

WithPort is `url.port = port` for a port given as decimal digits: the default port of a special scheme is dropped, and a URL without a host, or a file URL, cannot have one.

func (URL) WithQuery

func (u URL) WithQuery(query string) URL

WithQuery is `url.search = "?" + query` for a query already percent-encoded: the URL with that query.

func (URL) WithSearch

func (u URL) WithSearch(query string) string

WithSearch is `url.search = query; url.toString()`: the setter removes the query for "", otherwise drops one leading "?" and then every tab and newline (an empty query then serializes as "?"), applies the query percent-encode set (the special one for http, https, ws, wss, ftp and file), and keeps the path and the fragment.

func (URL) WithSearchParam

func (u URL) WithSearchParam(name, value string) string

WithSearchParam is `url.searchParams.set(name, value); url.toString()`: the existing pairs are parsed in order, the first pair named name takes the value and later ones are removed (or the pair is appended), and the query becomes the form serialization of the list. Setting a pair never leaves an empty query.

func (URL) WithoutCredentials

func (u URL) WithoutCredentials() URL

WithoutCredentials is `url.username = ""; url.password = ""`: the URL without its userinfo. A URL that has none, such as every file URL, is unchanged.

func (URL) WithoutFragment

func (u URL) WithoutFragment() URL

WithoutFragment is `url.hash = ""`: the URL without its fragment, an empty one ("#") included.

func (URL) WithoutHash

func (u URL) WithoutHash() URL

WithoutHash is `url.hash = ""`: the URL without its fragment.

func (URL) WithoutQuery

func (u URL) WithoutQuery() URL

WithoutQuery is `url.search = ""`: the URL without its query, so its href has no "?".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL