cizgile 0.1.0 → 0.2.0

package/dist/uri.d.mts

@@ -1,156 +1,281 @@
 //#region src/uri/charset.d.ts
+/** The named keep-sets `percentEncode` understands: the RFC 3986 productions and the WHATWG percent-encode sets. */
 type EncodeSetName = "unreserved" | "pchar" | "segment-nz-nc" | "path" | "query" | "fragment" | "userinfo" | "whatwg-c0-control" | "whatwg-fragment" | "whatwg-query" | "whatwg-special-query" | "whatwg-path" | "whatwg-userinfo" | "whatwg-component" | "form";
+/** A named keep-set or a predicate over code points that returns true for characters to leave unencoded. */
 type EncodeSet = EncodeSetName | ((codePoint: number) => boolean);
+/** RFC 3986 `ALPHA`. */
 export declare function isAlpha(cp: number): boolean;
+/** RFC 3986 `DIGIT`. */
 export declare function isDigit(cp: number): boolean;
+/** RFC 3986 `HEXDIG`, either case. */
 export declare function isHexDigit(cp: number): boolean;
+/** Whether `text` is a valid RFC 3986 `scheme`: a letter followed by letters, digits, `+`, `-` or `.`. */
 export declare function isScheme(text: string): boolean;
+/** RFC 3986 section 2.3 `unreserved`: letters, digits, `- . _ ~`. */
 export declare function isUnreserved(cp: number): boolean;
+/** RFC 3986 section 2.2 `gen-delims`: `: / ? # [ ] @`. */
 export declare function isGenDelim(cp: number): boolean;
+/** RFC 3986 section 2.2 `sub-delims`: `! $ & ' ( ) * + , ; =`. */
 export declare function isSubDelim(cp: number): boolean;
+/** RFC 3986 section 2.2 `reserved`: `gen-delims` or `sub-delims`. */
 export declare function isReserved(cp: number): boolean;
+/** RFC 3986 section 3.3 `pchar` less `pct-encoded`: `unreserved`, `sub-delims`, `:` or `@`. */
 export declare function isPchar(cp: number): boolean;
+/** RFC 3986 section 3.3 `segment-nz-nc` character: `pchar` without the colon. */
 export declare function isSegmentNzNc(cp: number): boolean;
+/** A character allowed unencoded in a `query` or `fragment`: `pchar`, `/` or `?`. */
 export declare function isQueryChar(cp: number): boolean;
+/** The predicate behind a named keep-set, or the predicate itself. */
 export declare function resolveEncodeSet(set: EncodeSet): (codePoint: number) => boolean;
 //#endregion
 //#region src/uri/normalize.d.ts
+/** Options for `normalizeUri`. */
 interface NormalizeUriOptions {
+  /** Scheme to default port, merged over `DEFAULT_PORTS`. */
   readonly defaultPorts?: Readonly<Record<string, number>>;
+  /** RFC 3986 section 6.2.3: drop default ports and turn an empty path into `/`; `true` by default. */
   readonly schemeBased?: boolean;
+  /** Redacts credentials, for logs; `"keep"` by default. */
   readonly userinfo?: "keep" | "strip-password" | "strip";
 }
+/** Default ports of the common schemes, used by `normalizeUri` and `equivalentUris`. */
 export declare const DEFAULT_PORTS: Readonly<Record<string, number>>;
+/** The parts of an RFC 3986 `authority`. */
 interface AuthorityComponents {
+  /** Without the trailing `@`. */
   userinfo?: string;
+  /** As written, brackets included for IP literals. */
   host: string;
+  /** Digits only, without the colon; `""` when the colon was present but empty. */
   port?: string;
 }
+/** Splits an authority into userinfo, host and port. */
 export declare function parseAuthority(authority: string): AuthorityComponents;
+/** Recomposes an authority from its parts. */
 export declare function serializeAuthority(components: AuthorityComponents): string;
+/** RFC 3986 section 6.2 syntax-based and scheme-based normalisation: case, percent-encoding, dot segments, default ports, empty path. */
 export declare function normalizeUri(input: string, options?: NormalizeUriOptions): string;
 //#endregion
 //#region src/uri/compare.d.ts
+/** The RFC 3986 section 6.2 comparison ladder: string, syntax-based or scheme-based normalisation. */
 type EquivalenceLevel = "simple" | "syntax" | "scheme";
+/** Options for `equivalentUris`. */
 interface EquivalentUrisOptions {
+  /** How much normalisation to apply before comparing; `"scheme"` by default. */
   readonly level?: EquivalenceLevel;
+  /** Resolves both references against this base first. */
   readonly base?: string;
+  /** Compares without the fragments. */
   readonly ignoreFragment?: boolean;
+  /** Scheme to default port, merged over `DEFAULT_PORTS`. */
   readonly defaultPorts?: NormalizeUriOptions["defaultPorts"];
 }
+/** Whether two URIs identify the same resource under the chosen normalisation level. IRIs are never mapped to URIs (RFC 3987 section 5.3.1). */
 export declare function equivalentUris(a: string, b: string, options?: EquivalentUrisOptions): boolean;
+/** Options for `isSameDocumentReference`. */
 interface SameDocumentOptions {
+  /** Normalises both sides before comparing. */
   readonly normalize?: boolean;
 }
+/** RFC 3986 section 4.4: whether `reference` resolved against `base` differs from it only in the fragment. */
 export declare function isSameDocumentReference(base: string, reference: string, options?: SameDocumentOptions): boolean;
 //#endregion
 //#region src/uri/encode.d.ts
+/** Options for `encodePathSegment`. */
 interface EncodePathSegmentOptions {
+  /** Also encodes `:`, for the first segment of a relative reference (`segment-nz-nc`). */
   readonly noColon?: boolean;
 }
+/** Encodes one path segment so that `/`, `?` and `#` inside it cannot be mistaken for delimiters. */
 export declare function encodePathSegment(segment: string, options?: EncodePathSegmentOptions): string;
+/** Options for `encodePath`. */
 interface EncodePathOptions {
+  /** Encodes the colon in the first segment so the path cannot be read as a scheme. */
   readonly relative?: boolean;
 }
+/** Encodes each segment of `path`, keeping the `/` separators. */
 export declare function encodePath(path: string, options?: EncodePathOptions): string;
+/** Encodes `query` with the RFC 3986 `query` set, keeping `/`, `?`, `=` and `&`. */
 export declare function encodeQuery(query: string): string;
+/** Encodes `fragment` with the RFC 3986 `fragment` set. */
 export declare function encodeFragment(fragment: string): string;
+/** `application/x-www-form-urlencoded` encoding of one value: spaces become `+`, `*-._` and alphanumerics stay. */
 export declare function encodeForm(value: string): string;
 //#endregion
 //#region src/uri/extract.d.ts
+/** RFC 3986 Appendix C: recovers a URI from text that wraps it in `<>`, quotes or brackets, prefixes it with `URL:`, breaks it across lines or ends it with punctuation. Markdown links and `href`/`src` attributes yield their URL. */
 export declare function extractUri(text: string): string;
 //#endregion
 //#region src/uri/host.d.ts
+/** The three RFC 3986 section 3.2.2 host forms. */
 type HostKind = "ip-literal" | "ipv4" | "reg-name";
+/** The result of `parseHost`. */
 interface ParsedHost {
+  /** Which host production matched. */
   readonly kind: HostKind;
+  /** The address without brackets, or the registered name as written. */
   readonly value: string;
 }
+/** RFC 3986 `IPv4address`: four decimal octets, no leading zeros; `0x7f.0.0.1` is a registered name, not an address. */
 export declare function isIPv4Address(text: string): boolean;
+/** RFC 3986 `IPv6address`, all nine ABNF alternatives including the embedded IPv4 form. */
 export declare function isIPv6Address(text: string): boolean;
+/** RFC 3986 `IPvFuture`: `v` + hex + `.` + unreserved or sub-delims. */
 export declare function isIPvFuture(text: string): boolean;
+/** RFC 3986 `IP-literal`: an IPv6 address or IPvFuture in square brackets. */
 export declare function isIPLiteral(text: string): boolean;
+/** RFC 3986 `reg-name`: unreserved, percent-encoded and sub-delims characters, possibly empty. */
 export declare function isRegName(text: string): boolean;
+/** Classifies `text` as an IP literal, IPv4 address or registered name, or returns `undefined`. */
 export declare function parseHost(text: string): ParsedHost | undefined;
+/** Whether `text` is a valid RFC 3986 `host`. */
 export declare function isHost(text: string): boolean;
 //#endregion
 //#region src/uri/iri.d.ts
+/** RFC 3987 `ucschar`: the non-ASCII code points an IRI may contain unencoded. */
 export declare function isUcschar(cp: number): boolean;
+/** RFC 3987 `iprivate`: private-use code points, allowed only in the query. */
 export declare function isIprivate(cp: number): boolean;
+/** Whether `cp` is a bidirectional formatting character (RFC 3987 section 4.1 forbids them). */
 export declare function isBidiControl(cp: number): boolean;
+/** Whether `input` contains any bidirectional formatting character. */
 export declare function hasBidiControls(input: string): boolean;
+/** RFC 3987 `iunreserved`: `unreserved` or `ucschar`. */
 export declare function isIunreserved(cp: number): boolean;
+/** RFC 3987 `ipchar` less `pct-encoded`. */
 export declare function isIpchar(cp: number): boolean;
+/** Options for `iriToUri`. */
 interface IriToUriOptions {
+  /** What to do with bidirectional formatting characters: throw, or strip them; by default they are percent-encoded like any other character. */
   readonly bidi?: "throw" | "strip";
+  /** Normalises to NFC first; off by default because RFC 3987 section 3.1 says not to alter characters. */
   readonly nfc?: boolean;
+  /** Rejects characters no IRI may contain instead of encoding them. */
   readonly strict?: boolean;
+  /** How to convert a non-ASCII host: percent-encode it (default) or apply `domainToAscii`. */
   readonly host?: "percent" | "punycode";
 }
+/** RFC 3987 section 3.1: percent-encodes the non-ASCII characters of an IRI, component by component, without altering them. */
 export declare function iriToUri(iri: string, options?: IriToUriOptions): string;
+/** RFC 3987 section 3.2: decodes the percent-encoded sequences a URI may show as characters, and only those, per component. */
 export declare function uriToIri(uri: string): string;
 //#endregion
 //#region src/uri/parse.d.ts
+/** The five RFC 3986 components. An absent component is `undefined`; an empty one is `""`, and the two serialise differently. */
 interface UriComponents {
+  /** Without the trailing colon. */
   scheme?: string;
+  /** Without the leading `//`; split it with `parseAuthority`. */
   authority?: string;
+  /** Always present, possibly empty. */
   path: string;
+  /** Without the leading `?`. */
   query?: string;
+  /** Without the leading `#`. */
   fragment?: string;
 }
+/** Splits a URI reference into its components with the RFC 3986 Appendix B regular expression; never throws. */
 export declare function parseUri(input: string): UriComponents;
+/** Recomposes components per RFC 3986 section 5.3, inserting `/.` or `./` where the grammar requires it. */
 export declare function serializeUri(components: UriComponents): string;
 //#endregion
 //#region src/uri/path.d.ts
+/** RFC 3986 section 5.2.4, the two-buffer algorithm as written: resolves `.` and `..` segments. */
 export declare function removeDotSegments(path: string): string;
+/** Options for `normalizePath`. */
 interface NormalizePathOptions {
+  /** What to do with a trailing slash; `"keep"` by default. */
   readonly trailingSlash?: "keep" | "add" | "remove";
 }
+/** Removes dot segments and normalises percent-encoding in a path, relative paths included. */
 export declare function normalizePath(path: string, options?: NormalizePathOptions): string;
 //#endregion
 //#region src/uri/percent.d.ts
+/** Percent-encodes `input` as UTF-8 with uppercase hex, leaving the characters `keep` names untouched; `"form"` also turns spaces into `+`. */
 export declare function percentEncode(input: string, keep?: EncodeSet): string;
+/** Options for `percentDecode`. */
 interface PercentDecodeOptions {
+  /** Decodes `+` as a space, as `application/x-www-form-urlencoded` does. */
   readonly plusAsSpace?: boolean;
 }
+/** Decodes every `%XX` sequence as UTF-8; malformed bytes become U+FFFD and lone `%` is kept. */
 export declare function percentDecode(input: string, options?: PercentDecodeOptions): string;
+/** RFC 3986 section 6.2.2.2: decodes percent-encoded `unreserved` characters and uppercases the hex of the rest. */
 export declare function normalizePercentEncoding(input: string): string;
 //#endregion
 //#region src/uri/punycode.d.ts
+/** RFC 3492 Punycode encoding of one label, without the `xn--` prefix. */
 export declare function punycodeEncode(input: string): string;
+/**
+ * RFC 3492 Punycode decoding of one label, without the `xn--` prefix.
+ * @throws {RangeError} on malformed input.
+ */
 export declare function punycodeDecode(input: string): string;
+/**
+ * Converts a domain to its A-label form: maps and lowercases each label the way UTS #46 does, punycodes the non-ASCII ones, and validates lengths, hyphens and existing `xn--` labels. IP literals pass through.
+ * @throws {RangeError} when a label or the domain is not valid.
+ */
 export declare function domainToAscii(host: string): string;
+/**
+ * Converts the `xn--` labels of a domain back to Unicode and lowercases the rest.
+ * @throws {RangeError} when an `xn--` label does not decode to a valid U-label.
+ */
 export declare function domainToUnicode(host: string): string;
 //#endregion
 //#region src/uri/relativize.d.ts
+/** The shortest relative reference that resolves against `base` to `target`; the target itself when they share nothing. */
 export declare function relativize(base: string, target: string): string;
 //#endregion
 //#region src/uri/resolve.d.ts
+/** Options for `resolveUri`. */
 interface ResolveUriOptions {
+  /** Strict parsing (RFC 3986 section 5.2.2): `http:g` against an `http:` base stays `http:g`; `true` by default. */
   readonly strict?: boolean;
+  /** Accepts a base without a scheme instead of throwing. */
   readonly allowRelativeBase?: boolean;
 }
+/** RFC 3986 section 5.2.3: merges a relative path reference with the base path. */
 export declare function mergePaths(base: UriComponents, referencePath: string): string;
+/**
+ * RFC 3986 section 5.2 reference resolution; every section 5.4 example passes.
+ * @throws {TypeError} when `base` is not an absolute URI, unless `allowRelativeBase` is set.
+ */
 export declare function resolveUri(base: string, reference: string, options?: ResolveUriOptions): string;
 //#endregion
 //#region src/uri/validate.d.ts
+/** The RFC 3986 section 3.3 path productions. */
 type PathForm = "empty" | "absolute" | "abempty" | "rootless" | "noscheme";
+/** The result of `classifyReference`. */
 interface ReferenceClassification {
+  /** Whether the reference carries a scheme. */
   readonly kind: "uri" | "relative";
+  /** Whether it is an `absolute-URI`: a scheme and no fragment. */
   readonly absolute: boolean;
+  /** Which path production matched. */
   readonly path: PathForm;
+  /** The parsed components. */
   readonly components: UriComponents;
 }
+/** Options for `classifyReference`. */
 interface ValidateOptions {
+  /** Validates against the RFC 3987 IRI grammar instead of the URI grammar. */
   readonly iri?: boolean;
 }
+/** Which RFC 3986 path production `path` matches. */
 export declare function pathForm(path: string, components?: UriComponents): PathForm;
+/** Validates `input` against the RFC 3986 (or 3987) grammar and reports its kind, or returns `undefined` when it does not parse. */
 export declare function classifyReference(input: string, options?: ValidateOptions): ReferenceClassification | undefined;
+/** Whether `input` is a valid RFC 3986 `URI-reference`. */
 export declare function isUriReference(input: string): boolean;
+/** Whether `input` is a valid RFC 3986 `URI`: it has a scheme. */
 export declare function isUri(input: string): boolean;
+/** Whether `input` is a valid RFC 3986 `absolute-URI`: a scheme and no fragment. */
 export declare function isAbsoluteUri(input: string): boolean;
+/** Whether `input` is a valid RFC 3986 `relative-ref`: no scheme. */
 export declare function isRelativeReference(input: string): boolean;
+/** Whether `input` is a valid RFC 3987 `IRI-reference`. */
 export declare function isIriReference(input: string): boolean;
+/** Whether `input` is a valid RFC 3987 `IRI`. */
 export declare function isIri(input: string): boolean;
 //#endregion
 export type { AuthorityComponents, EncodePathOptions, EncodePathSegmentOptions, EncodeSet, EncodeSetName, EquivalenceLevel, EquivalentUrisOptions, HostKind, IriToUriOptions, NormalizePathOptions, NormalizeUriOptions, ParsedHost, PathForm, PercentDecodeOptions, ReferenceClassification, ResolveUriOptions, SameDocumentOptions, UriComponents, ValidateOptions };