@eryx/uri Module

RFC 3986 URI parsing and validation utilities.

This module provides parsing helpers for:

The parser is split into two stages:

  1. Structural splitting into URI components
  2. Optional RFC 3986 validation

Query string parsing is provided as a convenience helper, but query contents are otherwise treated as opaque URI data.

The implementation aims to be RFC 3986 compliant for generic URI syntax, though IPv6 validation is intentionally permissive for now.

Summary

Functions

uri.parseQueryString(raw: string, plusIsSpace: boolean?) → Query
uri.parseReference(raw: string, validate: boolean?) → URI
uri.parseUri(raw: string, validate: boolean?) → URIWithScheme
uri.parseUrl(raw: string) → URL

API Reference

Functions

uri.parseQueryString

Parses an application/x-www-form-urlencoded style query string.

Repeated keys are collected into arrays.

Keys without values produce empty strings.

Examples:

uri.parseQueryString("a=1&a=2")
-- { a = { "1", "2" } }

uri.parseQueryString("flag")
-- { flag = "" }
uri.parseQueryString(raw: string, plusIsSpace: boolean?) → Query

Parameters

raw: string

Raw query string without leading ?

plusIsSpace: boolean?

Whether + should decode to space

Returns

Query

Parsed query structure

uri.parseReference

Parses a generic RFC 3986 URI reference.

Supports both:

  • Absolute URIs
  • Relative references

Examples:

  • https://example.com
  • /path
  • ../relative
  • ?query
  • #fragment

Validation is optional and validates generic RFC 3986 syntax.

uri.parseReference(raw: string, validate: boolean?) → URI

Parameters

raw: string

URI reference to parse

validate: boolean?

Whether RFC validation should be performed

Returns

URI

Parsed URI reference

uri.parseUri

Parses an absolute URI.

Unlike parseReference, this requires a scheme.

Examples:

uri.parseUri(raw: string, validate: boolean?) → URIWithScheme

Parameters

raw: string

URI to parse

validate: boolean?

Whether RFC validation should be performed

Returns

URIWithScheme

Parsed URI

uri.parseUrl

Parses a network-style URL.

URLs must contain:

  • A scheme
  • An authority
  • A non-empty host

Query strings are automatically parsed into queryValues.

Empty paths are normalised to /.

Examples:

  • https://example.com
  • https://example.com/path?a=1
uri.parseUrl(raw: string) → URL

Parameters

raw: string

URL to parse

Returns

URL

Parsed URL

Types

Authority

Authority component of a URI.

Corresponds to: [ userinfo "@" ] host [ ":" port ]

Examples:

type Authority = { userInfo: string?, host: string, portRaw: string?, port: number? }
userInfo: string?

Optional user information before @.

Example: user:password

host: string

Host component.

May contain:

  • Registered names
  • IPv4 addresses
  • Bracketed IP literals

Examples:

  • example.com
  • 127.0.0.1
  • [::1]
portRaw: string?

Raw port string after :.

Preserves formatting exactly as written.

Examples:

  • "80"
  • "00080"
  • ""
port: number?

Parsed numeric port when representable as a Lua number.

Will be nil for:

  • Missing ports
  • Empty ports
  • Extremely large port values

Query

Parsed query string values.

Keys map to either:

  • A single string value
  • An array of repeated values

Query items without keys are stored numerically.

Example: a=1&a=2&flag&hello=world

Produces:

{
	a = { "1", "2" },
	flag = "",
	hello = "world",
}
type Query = { [string | number]: string | { string? } }

URI

Parsed RFC 3986 URI reference.

Represents either:

  • An absolute URI
  • A relative reference

Examples:

  • https://example.com
  • /path/to/file
  • ../relative
  • ?query
  • #fragment
type URI = { scheme: string?, authority: Authority?, path: string, query: string?, fragment: string? }
scheme: string?

URI scheme.

Examples:

  • https
  • mailto
  • urn
authority: Authority?

Parsed authority component.

path: string

URI path component.

May be:

  • Empty
  • Absolute
  • Relative
  • Rootless
query: string?

Raw query string after ?.

Does not include the leading ?.

fragment: string?

Fragment after #.

Does not include the leading #.

URIWithScheme

Parsed absolute URI.

Unlike URI, this always contains a scheme.

Examples:

type URIWithScheme = URI & { scheme: string }
Implements: URI
scheme: string

URL

Parsed network-style URL.

URLs are a restricted subset of URI intended for locating network resources.

Unlike generic URIs, URLs always contain:

  • A scheme
  • An authority
  • A non-empty host

Query strings are automatically parsed into queryValues.

Examples:

  • https://example.com
  • https://example.com/path?a=1
type URL = URIWithScheme & { authority: Authority, path: string, queryValues: Query? }
Implements: URIWithScheme
authority: Authority
path: string
queryValues: Query?

Parsed query string values using application/x-www-form-urlencoded conventions.

+ is interpreted as space during parsing.