cizgile 0.2.0 → 0.3.0

package/dist/uri.d.mts

@@ -37,22 +37,19 @@ interface NormalizeUriOptions {
   readonly schemeBased?: boolean;
   /** Redacts credentials, for logs; `"keep"` by default. */
   readonly userinfo?: "keep" | "strip-password" | "strip";
+  /** What to do with a trailing slash on a path longer than `/`; `"keep"` by default. */
+  readonly trailingSlash?: "keep" | "add" | "remove";
+  /** Drop a `?` with nothing after it; `"keep"` by default. */
+  readonly emptyQuery?: "keep" | "remove";
+  /** Drop a `#` with nothing after it; `"keep"` by default. */
+  readonly emptyFragment?: "keep" | "remove";
+  /** Convert a registered-name host to its `xn--` form or back to Unicode; `"keep"` by default. */
+  readonly host?: "keep" | "idna" | "unicode";
+  /** Throw a `TypeError` on a host or port the RFC 3986 grammar rejects instead of passing it through. */
+  readonly strict?: boolean;
 }
 /** 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
@@ -103,9 +100,35 @@ export declare function encodeFragment(fragment: string): string;
 export declare function encodeForm(value: string): string;
 //#endregion
 //#region src/uri/extract.d.ts
+/** A URI found in prose by `findUris`, with its offsets in the text. */
+interface FoundUri {
+  readonly uri: string;
+  readonly start: number;
+  readonly end: number;
+}
+/** Finds the URIs in ordinary text: anything with `scheme://`, a `www.` host, or a `mailto:`, `tel:`, `urn:`, `data:` style scheme, ending at whitespace or a quote and trimmed of trailing punctuation the way `extractUri` does. */
+export declare function findUris(text: string): FoundUri[];
 /** 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/helpers.d.ts
+/** RFC 6454 origin of a URI: lowercase `scheme://host` plus the port unless it is the scheme's default. `undefined` when there is no scheme or no authority. */
+export declare function getOrigin(uri: string): string | undefined;
+/** Whether two URIs share an RFC 6454 origin. Two URIs without an origin never match. */
+export declare function isSameOrigin(a: string, b: string): boolean;
+/** The URI without its fragment. */
+export declare function stripFragment(uri: string): string;
+/** A query parameter as a decoded `[name, value]` pair; a bare name has the value `""`. */
+type QueryPair = readonly [string, string];
+/** Decodes an `application/x-www-form-urlencoded` query (`a=1&b=2`, `+` as space) into pairs in order; a leading `?` is ignored. */
+export declare function parseQuery(query: string): QueryPair[];
+/** Encodes pairs as an `application/x-www-form-urlencoded` query without the leading `?`. */
+export declare function stringifyQuery(pairs: Iterable<QueryPair>): string;
+/** The URI with its query parameters sorted by name, then value, byte-wise on the encoded text; parameters are otherwise left as written. */
+export declare function sortQuery(uri: string): string;
+/** Joins path pieces with single slashes, keeps the first piece's leading slash and the last piece's trailing slash, and resolves `.` and `..` so the result never contains `//` or a dot segment. */
+export declare function joinPaths(...pieces: readonly 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";
@@ -120,6 +143,8 @@ interface ParsedHost {
 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 5952 canonical text of an IPv6 address: lowercase, no leading zeros, the longest zero run as `::`, an embedded IPv4 tail kept. Anything that is not an IPv6 address is returned as is. */
+export declare function normalizeIPv6Address(text: string): string;
 /** 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. */
@@ -173,11 +198,37 @@ interface UriComponents {
   query?: string;
   /** Without the leading `#`. */
   fragment?: string;
+  /** The authority's userinfo; set by `parseUri(input, { authority: true })`, read by `serializeUri` when `authority` is absent. */
+  userinfo?: string;
+  /** The authority's host; set by `parseUri(input, { authority: true })`, read by `serializeUri` when `authority` is absent. */
+  host?: string;
+  /** The authority's port as written; set by `parseUri(input, { authority: true })`, read by `serializeUri` when `authority` is absent. */
+  port?: string;
+  /** The port as a number when it is in range; set by `parseUri(input, { authority: true })`. */
+  portNumber?: number;
 }
-/** 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. */
+/** Options for `parseUri`. */
+interface ParseUriOptions {
+  /** Also split the authority into `userinfo`, `host`, `port` and `portNumber`. */
+  readonly authority?: boolean;
+}
+/** Splits a URI reference into its components with the RFC 3986 Appendix B regular expression; never throws. With `authority: true` the authority is split further. */
+export declare function parseUri(input: string, options?: ParseUriOptions): UriComponents;
+/** Recomposes components per RFC 3986 section 5.3, inserting `/.` or `./` where the grammar requires it. `authority` wins over `host`, `port` and `userinfo`. */
 export declare function serializeUri(components: UriComponents): string;
+/** 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;
 //#endregion
 //#region src/uri/path.d.ts
 /** RFC 3986 section 5.2.4, the two-buffer algorithm as written: resolves `.` and `..` segments. */
@@ -278,4 +329,4 @@ 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 };
+export type { AuthorityComponents, EncodePathOptions, EncodePathSegmentOptions, EncodeSet, EncodeSetName, EquivalenceLevel, EquivalentUrisOptions, FoundUri, HostKind, IriToUriOptions, NormalizePathOptions, NormalizeUriOptions, ParseUriOptions, ParsedHost, PathForm, PercentDecodeOptions, QueryPair, ReferenceClassification, ResolveUriOptions, SameDocumentOptions, UriComponents, ValidateOptions };