identifier-js 0.1.4 → 0.3.0

package/index.d.ts

@@ -1,3 +1,4 @@
+// Declare the public validation, parsing, resolution, and normalization API.
 /** @throws {Error} If the UUID is invalid. */
 export const isUUID: (string: string) => true;
 /** @throws {Error} If the UUID-v4 is invalid. */
@@ -11,11 +12,11 @@ export const isUriReference: (uriReference: string) => true;
 export const isAbsoluteUri: (uri: string) => true;
 
 /** @throws {Error} If the URI is invalid. */
-export const parseUri: (uri: string) => IdentifierComponents;
+export const parseUri: (uri: string) => ParsedIdentifierComponents;
 /** @throws {Error} If the URI-reference is invalid. */
-export const parseUriReference: (uriReference: string) => RelativeIdentifierComponents;
+export const parseUriReference: (uriReference: string) => ParsedRelativeIdentifierComponents;
 /** @throws {Error} If the absolute-URI is invalid. */
-export const parseAbsoluteUri: (uri: string) => AbsoluteIdentifierComponents;
+export const parseAbsoluteUri: (uri: string) => ParsedAbsoluteIdentifierComponents;
 
 /** @throws {Error} If the IRI is invalid. */
 export const isIri: (iri: string) => true;
@@ -25,33 +26,50 @@ export const isIriReference: (iriReference: string) => true;
 export const isAbsoluteIri: (iri: string) => true;
 
 /** @throws {Error} If the IRI is invalid. */
-export const parseIri: (iri: string) => IdentifierComponents;
+export const parseIri: (iri: string) => ParsedIdentifierComponents;
 /** @throws {Error} If the IRI-reference is invalid. */
-export const parseIriReference: (iriReference: string) => RelativeIdentifierComponents;
+export const parseIriReference: (iriReference: string) => ParsedRelativeIdentifierComponents;
 /** @throws {Error} If the absolute-IRI is invalid. */
-export const parseAbsoluteIri: (iri: string) => AbsoluteIdentifierComponents;
-
-/** @throws {Error} If the reference is invalid. */
-export const normalizeReference: (reference: string) => string;
+export const parseAbsoluteIri: (iri: string) => ParsedAbsoluteIdentifierComponents;
 /** @throws {Error} If the base or the reference is invalid. */
-export const resolveReference: (reference: string, base: string, strict?: boolean, returnParts?: boolean) => string;
+export function resolveReference(reference: string, base: string, strict?: boolean, returnParts?: false): string;
+export function resolveReference(reference: string, base: string, strict: boolean | undefined, returnParts: true): IdentifierComponents;
+export function resolveReference(reference: string, base: string, strict: boolean | undefined, returnParts: boolean | undefined): string | IdentifierComponents;
 /** @throws {Error} If the reference is invalid. */
 export const toAbsoluteReference: (reference: string) => string;
 /** @throws {Error} If the base or the reference is invalid. */
 export const toRelativeReference: (target: string, base: string) => string;
 
-type IdentifierComponents = {
+/** Map a parsed non-empty registered-name host to caller-owned text. */
+export type RegNameMapper = (regName: string) => string;
+
+/** Select a target representation after parsed-result normalization. */
+export type NormalizeTransform = 'URI' | 'IRI';
+
+/** Select optional representation transformation and registered-name mapping. */
+export type NormalizeOptions = {
+    transform?: NormalizeTransform;
+    mapRegName?: RegNameMapper;
+};
+
+/** Provide lazy RFC normalization and optional URI/IRI transformation on a parsed result. */
+export type NormalizableReference = {
+    normalize(options?: NormalizeOptions): string;
+};
+
+// Describe component presence for complete, relative, and fragment-free absolute identifiers.
+export type IdentifierComponents = {
     scheme: string;
-    authority: string;
+    authority?: string;
     userinfo?: string;
-    host: string;
+    host?: string;
     port?: string;
     path: string;
     query?: string;
     fragment?: string;
 };
 
-type RelativeIdentifierComponents = {
+export type RelativeIdentifierComponents = {
     scheme?: string;
     authority?: string;
     userinfo?: string;
@@ -62,12 +80,16 @@ type RelativeIdentifierComponents = {
     fragment?: string;
 };
 
-type AbsoluteIdentifierComponents = {
+export type AbsoluteIdentifierComponents = {
     scheme: string;
-    authority: string;
+    authority?: string;
     userinfo?: string;
-    host: string;
+    host?: string;
     port?: string;
     path: string;
     query?: string;
 };
+
+export type ParsedIdentifierComponents = IdentifierComponents & NormalizableReference;
+export type ParsedRelativeIdentifierComponents = RelativeIdentifierComponents & NormalizableReference;
+export type ParsedAbsoluteIdentifierComponents = AbsoluteIdentifierComponents & NormalizableReference;

package/index.js

@@ -1,4 +1,5 @@
 'use strict';
+// Parse, validate, normalize, resolve, and convert RFC 3986 URI and RFC 3987 IRI references.
 // a valid URI is always a valid IRI
 const { recursiveCompile } = require('url-templates');
 const patterns = new Map();
@@ -7,14 +8,14 @@ const implemented_schemes = '(?:[hH][tT][tT][pP][sS]?|[wW][sS][sS]?|[fF][iI][lL]
 const commonRules = {
     implemented_schemes,
     scheme: '(?!{implemented_schemes}:)[a-zA-Z][a-zA-Z0-9+.-]*',
-    port: '(?:0|[1-9]\\d{0,3}|[1-5]\\d{4}|6[0-4]\\d{3}|65[0-4]\\d{2}|655[0-2]\\d|6553[0-5])?',
+    port: '\\d*',
     IP_literal: '\\[(?:{IPv6address}|{IPvFuture})\\]',
     IPv6address: '(?:(?:{h16}:){6}{ls32}|::(?:{h16}:){5}{ls32}|(?:(?:{h16})?)::(?:{h16}:){4}{ls32}|(?:(?:{h16}:)?{h16})?::(?:{h16}:){3}{ls32}|(?:(?:{h16}:){0,2}{h16})?::(?:{h16}:){2}{ls32}|(?:(?:{h16}:){0,3}{h16})?::(?:{h16}:){1}{ls32}|(?:(?:{h16}:){0,4}{h16})?::{ls32}|(?:(?:{h16}:){0,5}{h16})?::{h16}|(?:(?:{h16}:){0,6}{h16})?::)',
     ls32: '(?:{h16}:{h16}|{IPv4address})',
     h16: '{hex_digit}{1,4}',
     IPv4address: '(?:{dec_octet}\\.){3}{dec_octet}',
     dec_octet: '(?:\\d|[1-9]\\d|1\\d{2}|2[0-4]\\d|25[0-5])',
-    IPvFuture: 'v{hex_digit}+\\.(?:{unreserved}|{sub_delims}|:)+',
+    IPvFuture: '[vV]{hex_digit}+\\.(?:{unreserved}|{sub_delims}|:)+',
     unreserved: '[a-zA-Z0-9_.~-]',
     reserved: '(?:{gen_delims}|{sub_delims})',
     pct_encoded: '%{hex_digit}{2}',
@@ -78,6 +79,12 @@ const iriRules = {
     iprivate: '[\\uE000-\\uF8FF\\u{F0000}-\\u{FFFFD}\\u{100000}-\\u{10FFFD}]',
     ucschar: '[\\xA0-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFEF\\u{10000}-\\u{1FFFD}\\u{20000}-\\u{2FFFD}\\u{30000}-\\u{3FFFD}\\u{40000}-\\u{4FFFD}\\u{50000}-\\u{5FFFD}\\u{60000}-\\u{6FFFD}\\u{70000}-\\u{7FFFD}\\u{80000}-\\u{8FFFD}\\u{90000}-\\u{9FFFD}\\u{A0000}-\\u{AFFFD}\\u{B0000}-\\u{BFFFD}\\u{C0000}-\\u{CFFFD}\\u{D0000}-\\u{DFFFD}\\u{E1000}-\\u{EFFFD}]',
 };
+// Reuse the grammar repertoires when selecting URI octets safe for IRI output.
+const uriUnreservedPattern = new RegExp(`^${commonRules.unreserved}$`);
+const iriUcscharPattern = new RegExp(`^${iriRules.ucschar}$`, 'u');
+const iriPrivatePattern = new RegExp(`^${iriRules.iprivate}$`, 'u');
+// Apply the additional RFC 3987 Section 4.1 prose restriction outside the ABNF repertoire.
+const forbiddenIriFormattingPattern = /^[\u200E\u200F\u202A-\u202E]$/u;
 // scheme specific URI reg_name and IRI ireg_name
 const schemeSpecificRules = {
     scheme: implemented_schemes,
@@ -88,6 +95,12 @@ const schemeSpecificRules = {
     u_separator: '[\\x2E\\uFF0E\\u3002\\uFF61]',
     u_char: '[\\p{L}\\p{N}\\p{Mn}\\p{Mc}\\u200C\\u200D\\u00B7\\u0375\\u30FB\\u05F3\\u05F4]',
 };
+// Recognize RFC 8089's empty file authority without weakening other scheme host policies.
+const emptyFileHostRules = Object.assign({}, schemeSpecificRules, {
+    scheme: '[fF][iI][lL][eE]',
+    reg_name: '',
+    ireg_name: '',
+});
 // pattern RFC group names
 const groupNames = {
     scheme: 'scheme',
@@ -113,26 +126,35 @@ const groupNames = {
     ipath_rootless: 'path',
     ipath_empty: 'path',
 };
-// all rules into one map
+// Select and merge generic, DNS-host, or empty-file-host grammar overrides.
 const isSpecificScheme = (string) => new RegExp('^' + implemented_schemes + ':').test(string);
-const rules = (specific) => (specific ? Object.assign({}, commonRules, uriRules, iriRules, schemeSpecificRules) : Object.assign({}, commonRules, uriRules, iriRules));
+const schemeProfile = (string) => (string.slice(0, 8).toLowerCase() === 'file:///' ? 'f' : isSpecificScheme(string) ? 's' : '');
+const rules = (profile) => Object.assign({}, commonRules, uriRules, iriRules, profile === 'f' ? emptyFileHostRules : profile ? schemeSpecificRules : {});
 // parse (slower, it uses regex.exec and includes named capture groups)
 const parse = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
-    const specific = isSpecificScheme(string) ? 's' : '';
-    const addNames = (key) => (groupNames[key] ? `(?<${groupNames[key]}>${rules(specific)[key]})` : rules(specific)[key]);
-    const ruleId = '_' + specific + rule;
-    if (!patterns.has(ruleId)) patterns.set(ruleId, new RegExp(`^${recursiveCompile(rules(specific), rule, addNames)}$`, 'u'));
+    const profile = schemeProfile(string);
+    const addNames = (key) => (groupNames[key] ? `(?<${groupNames[key]}>${rules(profile)[key]})` : rules(profile)[key]);
+    const ruleId = '_' + profile + rule;
+    if (!patterns.has(ruleId)) patterns.set(ruleId, new RegExp(`^${recursiveCompile(rules(profile), rule, addNames)}$`, 'u'));
     const match = patterns.get(ruleId).exec(string);
-    if (match) return match.groups;
+    if (match) {
+        Object.defineProperty(match.groups, 'normalize', {
+            // Normalize this parsed result only when its optional method is called.
+            value: function normalize(options) {
+                return normalizeParsedReference(this, options);
+            },
+        });
+        return match.groups;
+    }
     throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
 };
 // validate (faster, it uses regex.test and does not include named capture groups)
 const validate = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
-    const specific = isSpecificScheme(string) ? 's' : '';
-    const ruleId = specific + rule;
-    if (!patterns.has(ruleId)) patterns.set(ruleId, new RegExp(`^${recursiveCompile(rules(specific), rule)}$`, 'u'));
+    const profile = schemeProfile(string);
+    const ruleId = profile + rule;
+    if (!patterns.has(ruleId)) patterns.set(ruleId, new RegExp(`^${recursiveCompile(rules(profile), rule)}$`, 'u'));
     if (patterns.get(ruleId).test(string)) return true;
     throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
 };
@@ -149,7 +171,7 @@ function compose(parts = {}) {
 // remove dot segments algorithm per RFC 3986 Section 5.2.4 (loop and replace)
 function removeDotSegments(path) {
     const output = [];
-    let input = path;
+    let input = path ?? '';
     while (input.length > 0) {
         if (input.startsWith('../')) input = input.slice(3);
         else if (input.startsWith('./')) input = input.slice(2);
@@ -209,27 +231,28 @@ function resolveReference(reference, base, strict = true, parts = false) {
     }
 
     let T;
-    if (R.scheme && (strict || R.scheme !== B.scheme)) {
+    if (R.scheme && (strict || R.scheme.toLowerCase() !== B.scheme.toLowerCase())) {
         T = R;
+        T.path = removeDotSegments(R.path);
     } else {
         T = {};
         T.scheme = B.scheme;
         if (R.authority !== undefined && R.authority !== null) {
             T.authority = R.authority;
-            T.path = R.path;
+            T.path = removeDotSegments(R.path);
             T.query = R.query;
         } else {
             T.authority = B.authority;
             if (R.path && R.path.length > 0) {
                 if (R.path.startsWith('/')) {
-                    T.path = R.path;
+                    T.path = removeDotSegments(R.path);
                 } else if (B.authority !== undefined && B.authority !== null && (!B.path || B.path.length === 0)) {
-                    T.path = '/' + R.path;
+                    T.path = removeDotSegments('/' + R.path);
                 } else {
-                    // merge base path and ref path
+                    // Merge the base directory and reference path before removing complete dot segments.
                     const idx = B.path ? B.path.lastIndexOf('/') : -1;
                     const prefix = idx !== -1 ? B.path.slice(0, idx + 1) : '';
-                    T.path = prefix + R.path;
+                    T.path = removeDotSegments(prefix + R.path);
                 }
                 T.query = R.query;
             } else {
@@ -240,14 +263,21 @@ function resolveReference(reference, base, strict = true, parts = false) {
         }
         T.fragment = R.fragment;
     }
-    T.path = removeDotSegments(T.path || '');
     if (parts) return T;
     return compose(T);
 }
-// reverse logic for resolve
+// Convert a complete IRI to fragment-free form without changing its other components.
+function toAbsoluteReference(string) {
+    const result = parse(string, 'IRI');
+    result.fragment = undefined;
+    return compose(result);
+}
+// Generate a relative reference when resolution is stable, otherwise retain the absolute target.
 const toRelativeReference = (target, base) => {
     const B = parse(base, 'absolute_IRI');
     const T = parse(target, 'IRI');
+    // Use the absolute target when dot-segment processing makes lexical relative round trips unstable.
+    if (/(?:^|\/)\.{1,2}(?=\/|$)/.test(T.path) || /(?:^|\/)\.{1,2}(?=\/|$)/.test(B.path)) return target;
     if (T.scheme !== B.scheme || T.authority !== B.authority) return target;
     let result;
     if (B.path === T.path) {
@@ -287,6 +317,256 @@ const toRelativeReference = (target, base) => {
     if (T.authority === undefined && !T.path.startsWith('/') && result.startsWith('..')) return target;
     return result;
 };
+// Identify RFC 3986 IPv4 literals without misclassifying numeric registered names.
+function isIPv4Address(host) {
+    const octets = host.split('.');
+    if (octets.length !== 4) return false;
+    // Require the parser's decimal-octet spelling and numeric range for every address part.
+    for (const octet of octets) {
+        if (!/^(?:0|[1-9]\d{0,2})$/.test(octet) || Number(octet) > 255) return false;
+    }
+    return true;
+}
+// Identify ASCII octets through the URI grammar's canonical unreserved repertoire.
+function isAsciiUnreservedOctet(octet) {
+    return uriUnreservedPattern.test(String.fromCharCode(octet));
+}
+// Normalize percent triplets while optionally decoding only ASCII unreserved octets.
+function normalizePercentEncoding(value, decodeUnreserved = true) {
+    let result = '';
+    // Preserve literal Unicode while processing each already-validated percent triplet atomically.
+    for (let index = 0; index < value.length; index++) {
+        if (value[index] !== '%' || !/^[0-9A-Fa-f]{2}$/.test(value.slice(index + 1, index + 3))) {
+            result += value[index];
+            continue;
+        }
+        const hexadecimal = value.slice(index + 1, index + 3);
+        const octet = Number.parseInt(hexadecimal, 16);
+        result += decodeUnreserved && isAsciiUnreservedOctet(octet) ? String.fromCharCode(octet) : `%${hexadecimal.toUpperCase()}`;
+        index += 2;
+    }
+    return result;
+}
+// Expand any accepted IPv6 spelling into eight numeric 16-bit fields.
+function parseIPv6Words(address) {
+    let expanded = address;
+    // Convert a dotted-decimal tail to the same two-field representation used by every later step.
+    const lastColon = expanded.lastIndexOf(':');
+    const lastSegment = expanded.slice(lastColon + 1);
+    if (lastSegment.includes('.')) {
+        const octets = lastSegment.split('.');
+        const high = Number(octets[0]) * 0x100 + Number(octets[1]);
+        const low = Number(octets[2]) * 0x100 + Number(octets[3]);
+        expanded = `${expanded.slice(0, lastColon + 1)}${high.toString(16)}:${low.toString(16)}`;
+    }
+
+    const compression = expanded.indexOf('::');
+    const leftText = compression === -1 ? expanded : expanded.slice(0, compression);
+    const rightText = compression === -1 ? '' : expanded.slice(compression + 2);
+    const left = leftText ? leftText.split(':') : [];
+    const right = rightText ? rightText.split(':') : [];
+    const words = [];
+    // Retain every explicit field before the compressed zero run.
+    for (const field of left) words.push(Number.parseInt(field, 16));
+    // Expand the single compression marker to the required number of zero fields.
+    if (compression !== -1) {
+        // Fill the omitted field count determined from both explicit sides.
+        for (let index = left.length + right.length; index < 8; index++) words.push(0);
+    }
+    // Retain every explicit field after the compressed zero run.
+    for (const field of right) words.push(Number.parseInt(field, 16));
+    return words;
+}
+// Serialize IPv6 fields with maximal first-run zero compression and lowercase digits.
+function serializeIPv6Words(words) {
+    let bestStart = -1;
+    let bestLength = 0;
+    // Select the first longest run containing at least two zero fields.
+    for (let start = 0; start < words.length;) {
+        if (words[start] !== 0) {
+            start++;
+            continue;
+        }
+        let end = start;
+        // Measure this complete zero run before comparing it with the retained candidate.
+        while (end < words.length && words[end] === 0) end++;
+        if (end - start > bestLength) {
+            bestStart = start;
+            bestLength = end - start;
+        }
+        start = end;
+    }
+    if (bestLength < 2) bestStart = -1;
+
+    const fields = [];
+    // Suppress every leading zero by converting each field through its numeric value.
+    for (const word of words) fields.push(word.toString(16));
+    if (bestStart === -1) return fields.join(':');
+    const before = fields.slice(0, bestStart).join(':');
+    const after = fields.slice(bestStart + bestLength).join(':');
+    return `${before}::${after}`;
+}
+// Canonicalize an IPv6 address under RFC 5952, including known embedded-IPv4 prefixes.
+function normalizeIPv6Address(address) {
+    const words = parseIPv6Words(address);
+    // Detect standardized prefixes that identify an embedded IPv4 address from address bits alone.
+    const low32 = words[6] * 0x10000 + words[7];
+    const compatible = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0 && low32 > 1;
+    const mapped = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0xFFFF;
+    const translated = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0xFFFF && words[5] === 0;
+    const nat64 = words[0] === 0x64 && words[1] === 0xFF9B && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0;
+    if (compatible || mapped || translated || nat64) {
+        const prefix = serializeIPv6Words(words.slice(0, 6));
+        const ipv4 = `${words[6] >>> 8}.${words[6] & 0xFF}.${words[7] >>> 8}.${words[7] & 0xFF}`;
+        return prefix.endsWith(':') ? prefix + ipv4 : `${prefix}:${ipv4}`;
+    }
+    return serializeIPv6Words(words);
+}
+// Lowercase an ASCII host without changing uppercase hexadecimal in retained percent triplets.
+function lowercaseAsciiHost(host) {
+    let result = '';
+    // Treat each retained percent triplet as an indivisible token during host case folding.
+    for (let index = 0; index < host.length; index++) {
+        if (host[index] === '%' && /^[0-9A-F]{2}$/.test(host.slice(index + 1, index + 3))) {
+            result += host.slice(index, index + 3);
+            index += 2;
+        } else result += host[index].toLowerCase();
+    }
+    return result;
+}
+// Normalize a parsed host according to its IP-literal, IPv4, or registered-name kind.
+function normalizeHost(host, mapRegName) {
+    if (!host) return host;
+    // Keep IP hosts outside application registered-name policy.
+    if (host.startsWith('[')) {
+        const address = host.slice(1, -1);
+        return address[0].toLowerCase() === 'v' ? `[${address.toLowerCase()}]` : `[${normalizeIPv6Address(address)}]`;
+    }
+    if (isIPv4Address(host)) return host;
+
+    let result = host;
+    // Delegate registered-name representation to the mapper before built-in text normalization.
+    if (mapRegName) {
+        result = mapRegName(host);
+        if (typeof result !== 'string') throw new TypeError('Invalid registered-name mapper result: must be a string.');
+    }
+    // Preserve the parsed host kind only when no mapper has assumed registered-name ownership.
+    const encodedResult = result;
+    result = normalizePercentEncoding(result);
+    if (!mapRegName && isIPv4Address(result)) result = normalizePercentEncoding(encodedResult, false);
+    return /[^\x00-\x7F]/u.test(result) ? result : lowercaseAsciiHost(result);
+}
+// Remove an empty or default-valued HTTP or WebSocket port.
+function normalizePort(scheme, port) {
+    if (port === undefined) return undefined;
+    const defaultPort = scheme === 'http' || scheme === 'ws' ? '80' : scheme === 'https' || scheme === 'wss' ? '443' : undefined;
+    if (defaultPort !== undefined && (port === '' || port.replace(/^0+(?=\d)/, '') === defaultPort)) return undefined;
+    return port;
+}
+// Encode each non-ASCII Unicode scalar as uppercase UTF-8 percent triplets.
+function encodeIriComponent(component) {
+    // Process complete code points so supplementary characters produce one UTF-8 sequence.
+    return component.replace(/[^\x00-\x7F]/gu, (character) => encodeURIComponent(character).toUpperCase());
+}
+// Decode the maximal RFC 3987 URI octet repertoire allowed by one IRI component.
+function decodeUriComponentToIri(component, allowPrivate = false) {
+    let result = '';
+    // Inspect each normalized percent triplet as either ASCII or the lead of one strict UTF-8 scalar.
+    for (let index = 0; index < component.length; index++) {
+        if (component[index] !== '%' || !/^[0-9A-F]{2}$/.test(component.slice(index + 1, index + 3))) {
+            result += component[index];
+            continue;
+        }
+        const hexadecimal = component.slice(index + 1, index + 3);
+        const octet = Number.parseInt(hexadecimal, 16);
+        if (octet <= 0x7F) {
+            result += isAsciiUnreservedOctet(octet) ? String.fromCharCode(octet) : `%${hexadecimal}`;
+            index += 2;
+            continue;
+        }
+        const sequenceLength = octet >= 0xC2 && octet <= 0xDF ? 2 : octet >= 0xE0 && octet <= 0xEF ? 3 : octet >= 0xF0 && octet <= 0xF4 ? 4 : 0;
+        let encoded = '';
+        // Collect exactly one candidate scalar without consuming malformed trailing input.
+        for (let sequenceIndex = 0; sequenceIndex < sequenceLength; sequenceIndex++) {
+            const position = index + sequenceIndex * 3;
+            if (component[position] !== '%' || !/^[0-9A-F]{2}$/.test(component.slice(position + 1, position + 3))) {
+                encoded = '';
+                break;
+            }
+            encoded += component.slice(position, position + 3);
+        }
+        let character;
+        if (encoded) {
+            try {
+                character = decodeURIComponent(encoded);
+            } catch {
+                character = undefined;
+            }
+        }
+        const allowed = character !== undefined && !forbiddenIriFormattingPattern.test(character) && (iriUcscharPattern.test(character) || (allowPrivate && iriPrivatePattern.test(character)));
+        if (allowed) {
+            result += character;
+            index += encoded.length - 1;
+        } else {
+            result += `%${hexadecimal}`;
+            index += 2;
+        }
+    }
+    return result;
+}
+// Rebuild authority from normalized values while preserving other empty component delimiters.
+function normalizeAuthority(parts, scheme, mapRegName) {
+    if (parts.authority === undefined) return undefined;
+    const userinfo = parts.userinfo === undefined ? undefined : normalizePercentEncoding(parts.userinfo);
+    const host = normalizeHost(parts.host, mapRegName);
+    const port = normalizePort(scheme, parts.port);
+    let authority = '';
+    if (userinfo !== undefined) authority += `${userinfo}@`;
+    authority += host;
+    if (port !== undefined) authority += `:${port}`;
+    return authority;
+}
+// Derive a normalized string from parsed URI/IRI components without modifying them.
+function normalizeParsedReference(parts, options = {}) {
+    // Validate the optional API settings before they select normalization behavior.
+    if (options === null || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Invalid normalization argument type: must be an options object.');
+    const { transform, mapRegName } = options;
+    if (transform !== undefined && transform !== 'URI' && transform !== 'IRI') throw new TypeError('Invalid transform option: must be "URI" or "IRI".');
+    if (mapRegName !== undefined && typeof mapRegName !== 'function') throw new TypeError('Invalid registered-name mapper type: must be a function.');
+    // Normalize each component independently so encoded delimiters cannot become structure.
+    const scheme = parts.scheme === undefined ? undefined : parts.scheme.toLowerCase();
+    const normalized = {
+        scheme,
+        authority: normalizeAuthority(parts, scheme, mapRegName),
+        path: normalizePercentEncoding(parts.path),
+        query: parts.query === undefined ? undefined : normalizePercentEncoding(parts.query),
+        fragment: parts.fragment === undefined ? undefined : normalizePercentEncoding(parts.fragment),
+    };
+    // Use the slash form defined for an empty HTTP or WebSocket authority path.
+    if (normalized.authority !== undefined && normalized.path === '' && (scheme === 'http' || scheme === 'https' || scheme === 'ws' || scheme === 'wss')) normalized.path = '/';
+    // Limit dot-segment removal to paths whose standalone interpretation remains stable.
+    const rootlessRelativePath = normalized.scheme === undefined && normalized.authority === undefined && normalized.path.length > 0 && !normalized.path.startsWith('/');
+    if (!rootlessRelativePath) {
+        const reducedPath = removeDotSegments(normalized.path);
+        // Preserve a no-authority path when reduction would reparse it as an authority.
+        if (normalized.authority !== undefined || !reducedPath.startsWith('//')) normalized.path = reducedPath;
+    }
+    // Select an explicit target representation only after syntax and scheme normalization is complete.
+    if (transform === 'URI') {
+        // Map every non-ASCII authority, path, query, and fragment scalar under RFC 3987 URI output.
+        if (normalized.authority !== undefined) normalized.authority = encodeIriComponent(normalized.authority);
+        normalized.path = encodeIriComponent(normalized.path);
+        if (normalized.query !== undefined) normalized.query = encodeIriComponent(normalized.query);
+        if (normalized.fragment !== undefined) normalized.fragment = encodeIriComponent(normalized.fragment);
+    } else if (transform === 'IRI') {
+        // Decode valid UTF-8 percent sequences only where the destination component permits their scalar.
+        if (normalized.authority !== undefined) normalized.authority = decodeUriComponentToIri(normalized.authority);
+        normalized.path = decodeUriComponentToIri(normalized.path);
+        if (normalized.query !== undefined) normalized.query = decodeUriComponentToIri(normalized.query, true);
+        if (normalized.fragment !== undefined) normalized.fragment = decodeUriComponentToIri(normalized.fragment);
+    }
+    return compose(normalized);
+}
 // export
 module.exports = {
     isUUID: (string) => validate(string, 'UUID'),
@@ -305,6 +585,5 @@ module.exports = {
     parseAbsoluteIri: (string) => parse(string, 'absolute_IRI'),
     resolveReference,
     toRelativeReference,
-    toAbsoluteReference: (string) => resolveReference('', string),
-    normalizeReference: (string) => string, // not done yet
+    toAbsoluteReference
 };

package/normalization.md

@@ -1,299 +1,146 @@
-# Identifier normalization research notes
-
-These notes summarize the standards and design choices that should be resolved before implementing `normalizeReference`. They are research material, not the current API contract.
-
-## Central constraint
-
-There is no universal canonical form for every URI or IRI. RFC 3986 defines comparison in levels because a transformation that is safe for one scheme or application can merge distinct identifiers in another.
-
-A normalizer should minimize false negatives without creating false positives:
-
-1. **Simple comparison** — compare characters exactly.
-2. **Syntax-based normalization** — apply transformations licensed by generic URI syntax.
-3. **Scheme-based normalization** — apply additional equivalences defined by a scheme.
-4. **Protocol-based normalization** — use equivalences established by observed protocol behavior.
-
-`normalizeReference` should implement only an explicitly selected level. Protocol-derived normalization does not belong in a deterministic identifier library.
-
-Reference: [RFC 3986 §6](https://www.rfc-editor.org/rfc/rfc3986#section-6).
-
-## Generic syntax-based normalization
-
-The following transformations are suitable candidates for a generic URI profile.
-
-### Scheme and host case
-
-- Lowercase the scheme.
-- Lowercase the host.
-- Do not lowercase userinfo, path, query, or fragment.
-- Preserve Unicode component case unless a scheme or external policy defines equivalence.
-
-Example:
-
-```text
-HTTP://WWW.EXAMPLE.COM/ → http://www.example.com/
-```
-
-Reference: RFC 3986 §6.2.2.1.
-
-### Percent-triplet case
-
-Uppercase hexadecimal letters in every valid percent triplet:
-
-```text
-%3a → %3A
-%2f → %2F
-```
-
-This changes presentation, not the represented octet.
-
-Reference: RFC 3986 §§2.1 and 6.2.2.1.
-
-### Decode percent-encoded unreserved characters
-
-Decode a percent triplet only when it represents an ASCII unreserved character:
-
-```text
-ALPHA / DIGIT / "-" / "." / "_" / "~"
-```
-
-Examples:
-
-```text
-%63 → c
-%7E → ~
-```
-
-Do not generically decode reserved characters. `%2F` and `/`, for example, can have different structural meanings.
-
-Parse components before decoding so an encoded delimiter cannot be mistaken for syntax. Never decode the same data twice.
-
-References: RFC 3986 §§2.2–2.4 and 6.2.2.2.
-
-### Remove dot segments
-
-Apply the RFC 3986 §5.2.4 algorithm to the parsed path:
-
-```text
-/a/b/c/./../../g → /a/g
-```
-
-Only complete `.` and `..` path segments are special. Do not process similar text in a query or fragment:
-
-```text
-g?y/../x
-g#s/../x
-```
-
-References: RFC 3986 §§5.2.4 and 6.2.2.3.
-
-### Preserve component presence
-
-Recomposition must distinguish an absent component from a present but empty component:
-
-```text
-https://example.com/path
-https://example.com/path?
-https://example.com/path#
-```
-
-The same applies to an empty authority. Component delimiters must be emitted based on definedness, not truthiness.
-
-Reference: RFC 3986 §5.3.
-
-## Scheme-based profiles
-
-Scheme-specific transformations should not run unless the scheme profile is selected or automatic scheme handling is part of the documented contract.
-
-### HTTP and HTTPS
-
-RFC 9110 permits these normal forms:
-
-- lowercase scheme and host;
-- remove port `80` from `http`;
-- remove port `443` from `https`;
-- remove an explicitly empty port;
-- use `/` when authority is present and path is empty;
-- decode percent-encoded unreserved characters;
-- preserve all other component case.
-
-Examples:
-
-```text
-HTTP://Example.COM:80 → http://example.com/
-https://example.com:443/a → https://example.com/a
-```
-
-An HTTP request target does not include a fragment, but identifier normalization should not silently discard a fragment unless the selected operation specifically produces a request target.
-
-Userinfo in HTTP and HTTPS targets is deprecated and should be rejected or reported by an HTTP policy rather than silently normalized away.
-
-Reference: [RFC 9110 §§4.2.1–4.2.5](https://www.rfc-editor.org/rfc/rfc9110#section-4.2).
-
-### WS and WSS
-
-Potential scheme-specific rules include:
-
-- default port `80` for `ws`;
-- default port `443` for `wss`;
-- `/` as the resource path when the path is empty;
-- no fragment identifiers;
-- IDN-to-ASCII handling under an explicitly selected hostname policy.
-
-Fragment rejection is validation, not normalization. A normalizer should not repair a WebSocket URI by silently deleting its fragment.
-
-Reference: [RFC 6455 §3](https://www.rfc-editor.org/rfc/rfc6455#section-3).
-
-### File
-
-A generic `file` normalizer is not recommended. Behavior varies by platform and filesystem:
-
-- local empty authority versus `localhost`;
-- POSIX roots;
-- Windows drive-letter case and UNC paths;
-- path case sensitivity;
-- backslash handling;
-- platform-specific Unicode normalization;
-- reserved device names and namespace paths.
-
-Require an explicit platform profile before applying these transformations.
-
-Reference: [RFC 8089](https://www.rfc-editor.org/rfc/rfc8089).
-
-### Other schemes
-
-Apply only generic syntax normalization unless the scheme's authoritative specification defines additional equivalences. Do not infer default ports, path case rules, or authority behavior from a similar scheme.
-
-## IRI and Unicode decisions
-
-RFC 3987 recommends that creators produce IRIs in NFC, but comparison code must not arbitrarily normalize an existing Unicode IRI. Normalizing third-party text can merge identifiers that were intentionally distinct.
-
-Recommended policy:
-
-- do not apply Unicode normalization by default;
-- offer NFC only as an explicit creation or application-policy option;
-- do not offer NFKC as a generic identifier transformation;
-- retain the original IRI when a normalized form is generated only as a comparison key.
-
-### IRI-to-URI mapping is a separate operation
-
-Mapping an IRI to a URI is not merely normalization:
-
-1. encode non-ASCII `ucschar` and `iprivate` characters as UTF-8;
-2. percent-encode each UTF-8 octet as `%HH`;
-3. preserve existing valid percent triplets and URI-allowed characters;
-4. apply an explicit IDNA policy to internationalized hostnames when required.
-
-The reverse operation must decode only valid UTF-8 and must preserve encoded reserved characters. It must not guess legacy encodings.
-
-Reference: [RFC 3987 §§3 and 5](https://www.rfc-editor.org/rfc/rfc3987).
-
-## Transformations excluded by default
-
-A generic normalizer should not:
-
-- decode percent-encoded reserved characters;
-- lowercase userinfo, paths, queries, or fragments;
-- sort, deduplicate, or reinterpret query parameters;
-- remove empty query or fragment delimiters;
-- add or remove trailing slashes without scheme authority;
-- apply Unicode NFC or NFKC automatically;
-- convert an internationalized hostname without a defined IDNA version and policy;
-- remove userinfo rather than reporting it;
-- infer filesystem semantics for `file`;
-- infer equivalence from redirects or successful retrievals;
-- convert a relative reference without a supplied base.
-
-## Suggested API design
-
-Avoid a single aggressive operation. Two viable designs are:
-
-### Explicit profiles
-
-```js
-normalizeReference(reference, {
-    profile: 'generic', // generic | http | https | ws | wss
-    unicodeNormalization: false,
-});
-```
-
-A `file` profile should additionally require a platform policy.
-
-### Separate operations
-
-```js
-normalizeReference(reference);          // generic syntax only
-normalizeHttpReference(reference);      // HTTP/HTTPS scheme rules
-normalizeWebSocketReference(reference); // WS/WSS scheme rules
-iriToUri(reference, options);            // explicit representation mapping
-```
-
-Separate operations are harder to misuse and make compatibility changes more visible. A profile-based API is easier to extend. The final choice should follow the expected consumers.
-
-## Suggested generic processing order
-
-1. Parse and retain whether authority, query, and fragment are absent or empty.
-2. Lowercase scheme and host where generic syntax permits it.
-3. Normalize percent-triplet hexadecimal case.
-4. Decode percent-encoded ASCII unreserved characters component by component.
-5. Remove dot segments from the path.
-6. Apply an explicitly selected scheme profile.
-7. Apply Unicode normalization only when explicitly requested.
-8. Recompose while preserving empty components.
-9. Validate the normalized output under the same identifier and scheme policy.
-10. Optionally verify idempotence:
-
-```js
-normalizeReference(normalizeReference(value)) === normalizeReference(value)
-```
-
-## Acceptance scenarios
-
-A generic profile should include at least these cases:
-
-```text
-HTTP://Example.COM/%7euser       → http://example.com/~user
-http://example.com/a/./b/../c   → http://example.com/a/c
-http://example.com/path?        → http://example.com/path?
-http://example.com/path#        → http://example.com/path#
-http://example.com/%2F          → http://example.com/%2F
-```
-
-An HTTP profile can additionally include:
-
-```text
-http://example.com:80           → http://example.com/
-https://example.com:443/a       → https://example.com/a
-```
-
-Cases that must remain distinct under generic normalization include:
-
-```text
-http://example.com/a            ≠ http://example.com/a/
-http://example.com/path         ≠ http://example.com/path?
-http://example.com/%2F          ≠ http://example.com//
-http://example.com/A            ≠ http://example.com/a
-```
-
-Testing should cover URI and IRI forms, empty components, rootless paths, percent triplets, Unicode supplementary characters, idempotence, and normalization followed by parsing/recomposition.
-
-## Open decisions
-
-Before implementation, decide:
-
-1. Whether `normalizeReference` is generic-only or selects profiles automatically by scheme.
-2. Whether output preserves the input category: URI versus IRI.
-3. Whether relative references are normalized in place or require a base and become absolute.
-4. Whether Unicode NFC is offered, and for which creation contexts.
-5. Whether IDNA conversion belongs here or in a dedicated hostname dependency.
-6. Whether comparison keys and display/transport identifiers use separate APIs.
-7. Whether unsupported scheme profiles throw, fall back to generic rules, or require an explicit option.
-8. Whether current callers can rely on `normalizeReference` remaining an identity function until a major release.
-
-## Authoritative references
-
-- [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
-- [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
-- [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
-- [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
-- [RFC 8089 — The `file` URI Scheme](https://www.rfc-editor.org/rfc/rfc8089)
+# URI and IRI normalization
+
+Parsed URI and IRI results expose `normalize()` for syntax-based normalization, the implemented HTTP, HTTPS, WS, and WSS scheme rules, and optional RFC 3987 URI/IRI representation transformation. The method returns a string and leaves the parsed components unchanged.
+
+## API
+
+```ts
+type RegNameMapper = (regName: string) => string
+
+type NormalizeTransform = 'URI' | 'IRI'
+
+type NormalizeOptions = {
+    transform?: NormalizeTransform
+    mapRegName?: RegNameMapper
+}
+
+interface NormalizableReference {
+    normalize(options?: NormalizeOptions): string
+}
+```
+
+The method is available on results from:
+
+- `parseUri`
+- `parseUriReference`
+- `parseAbsoluteUri`
+- `parseIri`
+- `parseIriReference`
+- `parseAbsoluteIri`
+
+It is non-enumerable and reads the result object's current component properties when called.
+
+```js
+const { parseIriReference } = require('identifier-js');
+
+const parsed = parseIriReference(
+    'HTTP://Example.COM/%7e/a/../b?x=%2f#%41',
+);
+
+parsed.normalize();
+// http://example.com/~/b?x=%2F#A
+
+parsed.path;
+// /%7e/a/../b
+```
+
+## RFC syntax normalization
+
+| Behavior | Implementation | Source |
+| --- | --- | --- |
+| Case normalization | Lowercase the scheme and an ASCII-only host. Uppercase hexadecimal letters in percent triplets. | [RFC 3986 §6.2.2.1](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1), [RFC 3987 §5.3.2.1](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.1) |
+| Percent-encoded unreserved characters | Decode percent triplets representing ASCII letters, digits, `-`, `.`, `_`, or `~`. Retain percent encoding for reserved octets. | [RFC 3986 §§2.2–2.4 and 6.2.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.2), [RFC 3987 §5.3.2.3](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.3) |
+| Path segments | Apply the RFC dot-segment algorithm where the parsed reference can be normalized independently. Preserve unresolved rootless-relative path semantics. | [RFC 3986 §§5.2.4 and 6.2.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-5.2.4), [RFC 3987 §5.3.2.4](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.4) |
+| Component recomposition | Emit authority, query, and fragment delimiters from component presence, including present-empty components. | [RFC 3986 §5.3](https://www.rfc-editor.org/rfc/rfc3986#section-5.3) |
+| IPv6 text | Suppress leading zeroes, compress the longest zero run with first-run tie breaking, and use lowercase hexadecimal. Known embedded-IPv4 forms use mixed notation. | [RFC 5952 §§4–5](https://www.rfc-editor.org/rfc/rfc5952#section-4) |
+| IRI-to-URI output | With `transform: 'URI'`, encode non-ASCII authority, path, query, and fragment characters as uppercase UTF-8 percent triplets. | [RFC 3987 §3.1](https://www.rfc-editor.org/rfc/rfc3987#section-3.1) |
+| URI-to-IRI output | With `transform: 'IRI'`, decode percent-encoded ASCII unreserved characters and strictly legal UTF-8 sequences permitted in each destination component. Retain reserved, malformed, disallowed, and non-UTF-8 octets. | [RFC 3987 §3.2](https://www.rfc-editor.org/rfc/rfc3987#section-3.2) |
+
+Without a mapper, normalization retains the parser's host classification as an IP literal, IPv4 address, or registered name. IPvFuture literals use generic host case normalization. Existing non-ASCII IRI host text is retained unless the registered-name mapper supplies another value.
+
+## HTTP and HTTPS
+
+For `http` and `https`, normalization applies the generic rules and these scheme rules:
+
+| Input component | Output | Source |
+| --- | --- | --- |
+| Empty port | Omit the port delimiter. | [RFC 3986 §3.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.3) |
+| `http` port numerically equal to `80` | Omit the port. | [RFC 9110 §4.2.3](https://www.rfc-editor.org/rfc/rfc9110#section-4.2.3) |
+| `https` port numerically equal to `443` | Omit the port. | [RFC 9110 §4.2.3](https://www.rfc-editor.org/rfc/rfc9110#section-4.2.3) |
+| Empty authority path | Use `/`. | [RFC 9110 §4.2.3](https://www.rfc-editor.org/rfc/rfc9110#section-4.2.3) |
+
+Decimal port comparison includes leading-zero spellings.
+
+```text
+HTTP://Example.COM:80                → http://example.com/
+https://example.com:00443/a          → https://example.com/a
+http://example.com:/a                → http://example.com/a
+```
+
+## WS and WSS
+
+For `ws` and `wss`, normalization applies the generic rules and these scheme rules:
+
+| Input component | Output | Source |
+| --- | --- | --- |
+| Empty port | Omit the port delimiter. | [RFC 3986 §3.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.3) |
+| `ws` port numerically equal to `80` | Omit the port. | [RFC 3986 §6.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.3), [RFC 6455 §3](https://www.rfc-editor.org/rfc/rfc6455#section-3) |
+| `wss` port numerically equal to `443` | Omit the port. | [RFC 3986 §6.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.3), [RFC 6455 §3](https://www.rfc-editor.org/rfc/rfc6455#section-3) |
+| Empty authority path | Use `/` as the resource-name path. | [RFC 6455 §3](https://www.rfc-editor.org/rfc/rfc6455#section-3) |
+
+```text
+WS://Example.COM:80                  → ws://example.com/
+wss://example.com:00443/chat         → wss://example.com/chat
+ws://example.com?channel=updates     → ws://example.com/?channel=updates
+```
+
+## Registered-name mapping and representation transformation
+
+For a non-empty registered-name host, `options.mapRegName` is called once with the current host spelling before built-in normalization. IP literals, IPv4 addresses, absent hosts, and empty hosts bypass the mapper.
+
+The mapper owns the returned text and all registered-name validation, representation, and host-kind policy. This package enforces only the declared string return type. It does not check whether mapper output is non-empty, remains a registered name, introduces component delimiters, resembles an IP address, or satisfies a scheme-specific hostname grammar. The returned string then receives percent-triplet and ASCII host-case normalization. Mapper exceptions propagate unchanged.
+
+```js
+const mapped = parseIriReference('x://example').normalize({
+    mapRegName: () => 'Application Defined',
+});
+
+mapped;
+// x://application defined
+```
+
+The example deliberately produces text that is not a valid URI or IRI; validating or selecting mapper output belongs to the application.
+
+With `transform: 'URI'`, retained reserved and non-ASCII percent triplets remain encoded, and literal non-ASCII userinfo, mapper output, path, query, and fragment text becomes uppercase UTF-8 percent triplets. A mapper can supply an ASCII hostname when its consuming scheme requires one; this package does not validate mapper output against that scheme.
+
+```js
+const { parseIri, parseUri } = require('identifier-js');
+
+parseIri('x:/café?q=資料#résultat').normalize({ transform: 'URI' });
+// x:/caf%C3%A9?q=%E8%B3%87%E6%96%99#r%C3%A9sultat
+
+parseUri('x:/caf%C3%A9?q=%E8%B3%87%E6%96%99#r%C3%A9sultat').normalize({ transform: 'IRI' });
+// x:/café?q=資料#résultat
+```
+
+With `transform: 'IRI'`, conversion uses UTF-8 exclusively and decodes as many eligible percent-encoded characters as possible. Encoded reserved characters, `%25`, malformed or incomplete UTF-8, legacy character encodings, Unicode outside the RFC 3987 component repertoire, and forbidden bidirectional formatting characters remain percent encoded. Private-use characters are decoded only in the query component. The hexadecimal letters of retained triplets are uppercase.
+
+The IRI transformation decodes percent-encoded ASCII unreserved characters even when this changes a registered name into IPv4-looking text. Without an explicit transformation, normalization preserves that registered-name host classification.
+
+ACE-to-Unicode and Unicode-to-ACE registered-name conversion remain application policy. `mapRegName` runs before the selected representation transformation, so applications can provide the appropriate mapping in either direction.
+
+## Verification
+
+The normalization suite covers URI and IRI parser results, component presence, percent triplets, dot segments, host kinds, RFC 5952 output, HTTP and WebSocket scheme rules, registered-name mapping, both RFC representation transformations, malformed UTF-8 retention, component-specific Unicode repertoires, component non-mutation, round trips, and idempotence.
+
+```sh
+npm test
+```
+
+## References
+
+- [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
+- [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
+- [RFC 5952 — A Recommendation for IPv6 Address Text Representation](https://www.rfc-editor.org/rfc/rfc5952)
+- [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
+- [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "identifier-js",
-  "version": "0.1.4",
-  "description": "A RFC3986 / RFC3987 compliant fast parser/validator/resolver/composer for NodeJS and browser.",
+  "version": "0.3.0",
+  "description": "A fast URI/IRI parser, validator, normalizer, resolver, and composer based on RFC 3986 and RFC 3987.",
   "keywords": [
     "IRI",
     "URI",

package/readme.md

@@ -2,18 +2,19 @@
 
 title: Identifier JS
 
-description: An RFC 3986 and RFC 3987 parser, validator, and reference resolver for Node.js and browser bundles.
+description: An RFC 3986 and RFC 3987 parser, validator, normalizer, and reference resolver for Node.js and browser bundles.
 
 ---
 
 # Identifier JS
 
-`identifier-js` is a fully RFC [3986](https://www.rfc-editor.org/rfc/rfc3986) and RFC [3987](https://www.rfc-editor.org/rfc/rfc3987) compliant URI/IRI parser, validator, resolver, and composer. It provides:
+`identifier-js` is a URI/IRI parser, validator, normalizer, resolver, and composer based on RFC [3986](https://www.rfc-editor.org/rfc/rfc3986) and RFC [3987](https://www.rfc-editor.org/rfc/rfc3987). Its recognized HTTP, WebSocket, and `file` schemes retain the documented hostname-policy restrictions below. It provides:
 
 - URI and IRI validation;
 - parsed identifier components;
+- conservative syntax normalization, recognized-scheme port/path forms, and a registered-name extension point;
 - RFC 3986 reference resolution and dot-segment removal;
-- relative-reference generation with round-trip guarantees for supported forms;
+- relative-reference generation with resolution round-trip guarantees for supported forms;
 - UUID and UUIDv4 lexical validation;
 - lazily compiled and cached regular expressions.
 
@@ -62,9 +63,9 @@ Parse URI syntax into scheme, authority, userinfo, host, port, path, query, and
 <summary><strong>API and examples</strong></summary>
 
 ```ts
-parseUri(value: string): IdentifierComponents
-parseUriReference(value: string): RelativeIdentifierComponents
-parseAbsoluteUri(value: string): AbsoluteIdentifierComponents
+parseUri(value: string): ParsedIdentifierComponents
+parseUriReference(value: string): ParsedRelativeIdentifierComponents
+parseAbsoluteUri(value: string): ParsedAbsoluteIdentifierComponents
 ```
 
 ```js
@@ -107,7 +108,7 @@ console.log(isIri('https://例え.テスト/資料?項目=値#概要')); // true
 console.log(isIriReference('../résumé')); // true
 ```
 
-IRI support permits RFC 3987 Unicode ranges in applicable components. Complete IDNA processing and conversion to a transport URI are separate responsibilities.
+IRI support permits the RFC 3987 Unicode ranges in applicable components and preserves their parsed Unicode spelling.
 
 </details>
 
@@ -119,9 +120,9 @@ Parse an IRI while preserving its Unicode component values.
 <summary><strong>API and examples</strong></summary>
 
 ```ts
-parseIri(value: string): IdentifierComponents
-parseIriReference(value: string): RelativeIdentifierComponents
-parseAbsoluteIri(value: string): AbsoluteIdentifierComponents
+parseIri(value: string): ParsedIdentifierComponents
+parseIriReference(value: string): ParsedRelativeIdentifierComponents
+parseAbsoluteIri(value: string): ParsedAbsoluteIdentifierComponents
 ```
 
 ```js
@@ -190,7 +191,7 @@ toRelativeReference(target: string, base: string): string
 const { toAbsoluteReference, toRelativeReference } = require('identifier-js');
 
 console.log(toAbsoluteReference('https://example.com/a/../b#section'));
-// https://example.com/b
+// https://example.com/a/../b
 
 const target = 'https://example.com/docs/images/logo.svg';
 const base = 'https://example.com/docs/api/page';
@@ -198,29 +199,51 @@ const relative = toRelativeReference(target, base);
 console.log(relative); // ../images/logo.svg
 ```
 
-When no safe rootless relative form can round-trip to the target, `toRelativeReference` returns the absolute target. Different schemes or authorities also return the target unchanged.
+When no safe rootless relative form can round-trip to the target, `toRelativeReference` returns the absolute target. Different schemes or authorities also return the target unchanged. Complete dot segments in either path also trigger this fallback because RFC resolution removes them. For those inputs, resolving the result produces the same identifier as resolving the target directly; lexical dot-segment spelling is not preserved.
 
 </details>
 
-### Normalization status
+### Normalize parsed URI and IRI references
 
-`normalizeReference` is reserved for future normalization policy and currently returns its input unchanged.
+Every URI and IRI parse result provides an optional, non-enumerable `normalize()` method. Parsing remains usable by itself; normalization runs only when the method is called and returns a string without modifying the parsed components.
 
 <details>
-<summary><strong>Current behavior and research</strong></summary>
+<summary><strong>API, behavior, and examples</strong></summary>
 
 ```ts
-normalizeReference(reference: string): string
+type RegNameMapper = (regName: string) => string
+
+type NormalizeTransform = 'URI' | 'IRI'
+
+type NormalizeOptions = {
+    transform?: NormalizeTransform
+    mapRegName?: RegNameMapper
+}
+
+interface NormalizableReference {
+    normalize(options?: NormalizeOptions): string
+}
 ```
 
 ```js
-const { normalizeReference } = require('identifier-js');
+const { parseIriReference } = require('identifier-js');
 
-console.log(normalizeReference('HTTP://Example.COM/a/../b'));
-// HTTP://Example.COM/a/../b
+const parsed = parseIriReference('HTTP://Example.COM/%7e/a/../b?x=%2f#%41');
+console.log(parsed.host); // Example.COM
+console.log(parsed.normalize());
+// http://example.com/~/b?x=%2F#A
+console.log(parsed.path); // /%7e/a/../b
 ```
 
-URI/IRI normalization has multiple standards-defined levels and scheme-specific tradeoffs. See [`normalization.md`](normalization.md) for implementation options, unsafe transformations, suggested profiles, and acceptance scenarios.
+The method is available from `parseUri`, `parseUriReference`, `parseAbsoluteUri`, `parseIri`, `parseIriReference`, and `parseAbsoluteIri`.
+
+Normalization implements RFC 3986 and RFC 3987 syntax normalization for scheme and host case, percent triplets, ASCII unreserved characters, path dot segments, and component recomposition. IPv6 literals use RFC 5952 text. HTTP(S) default ports and empty paths follow RFC 9110; WS(S) defaults and resource-name paths follow RFC 6455.
+
+For a non-empty registered-name host, `mapRegName` receives the current host spelling before built-in normalization. The mapper exclusively owns validation, representation, and host-kind policy for its returned string. Apart from enforcing the declared string return type, this package does not check whether mapper output is non-empty, remains a registered name, introduces delimiters, resembles an IP address, or satisfies a scheme-specific hostname grammar.
+
+With `transform: 'URI'`, non-ASCII userinfo, mapper output, path, query, and fragment text becomes uppercase UTF-8 percent triplets under RFC 3987 §3.1. With `transform: 'IRI'`, eligible percent-encoded ASCII unreserved characters and strictly legal UTF-8 sequences become IRI characters under RFC 3987 §3.2; reserved, malformed, disallowed, and non-UTF-8 octets remain encoded. Private-use characters are decoded only in queries, and forbidden bidirectional formatting characters remain encoded. A mapper can supply the desired Unicode or ASCII hostname representation; this package does not enforce that policy or validate the complete normalized result.
+
+See [`normalization.md`](normalization.md) for the exact RFC section mapping and examples.
 
 </details>
 
@@ -243,7 +266,7 @@ console.log(isUUID('99c17cbb-656f-564a-940f-1a4568f03487')); // true
 console.log(isUUIDv4('123e4567-e89b-42d3-9456-426614174000')); // true
 ```
 
-`isUUID` validates the `8-4-4-4-12` hexadecimal layout without restricting the version or variant fields. `isUUIDv4` requires version `4` and the RFC variant nibble `8`, `9`, `a`, or `b`.
+`isUUID` validates the `8-4-4-4-12` hexadecimal layout. `isUUIDv4` additionally requires version `4` and the RFC variant nibble `8`, `9`, `a`, or `b`.
 
 </details>
 
@@ -279,9 +302,9 @@ The following schemes trigger DNS-style ASCII or Unicode label rules instead of
 - `wss`
 - `file`
 
-Matching is case-insensitive. Other valid schemes use generic RFC 3986/3987 registered-name syntax.
+Matching is case-insensitive. Other valid schemes use generic RFC 3986/3987 registered-name syntax. RFC 8089's empty `file` authority is accepted when followed by an absolute path, as in `file:///path`; empty hosts remain rejected for HTTP and WebSocket schemes.
 
-This policy validates label shape and selected Unicode character classes. It is not complete IDNA processing and does not replace normalization, contextual, bidi, registry, or Punycode validation.
+Parsing validates DNS-style label shape and the selected RFC 3987 Unicode character classes. A registered-name mapper runs later during optional normalization, and its returned string is not submitted to this hostname policy again.
 
 </details>
 
@@ -349,7 +372,7 @@ RFC 3987 uses IRIs for internationalized identification while requiring mapping
 
 ### Validate and route protocol identifiers
 
-Component parsing supports policy decisions without unsafe string splitting.
+Component parsing provides scheme, authority, host, port, path, and query fields for policy decisions.
 
 <details>
 <summary><strong>Example and context</strong></summary>
@@ -364,7 +387,7 @@ console.log(parts.port);   // 8443
 console.log(parts.path);   // /events
 ```
 
-Applications can inspect scheme, authority, path, and query before selecting a connector, enforcing an allowlist, constructing an HTTP request target, or routing to a service. Protocol-specific security and semantic validation remains the application's responsibility.
+Applications can inspect scheme, authority, path, and query before selecting a connector, enforcing an allowlist, constructing an HTTP request target, or routing to a service.
 
 </details>
 
@@ -386,46 +409,41 @@ try {
 }
 ```
 
-RFC 9562 lists database keys, filenames, system identifiers, and transaction identifiers among common UUID uses. UUID validation does not establish authorization, unpredictability, uniqueness, or safe use as a capability token.
+RFC 9562 lists database keys, filenames, system identifiers, and transaction identifiers among common UUID uses.
 
 </details>
 
-## Intentional behavior and limitations
+## Standards behavior
 
 <details>
-<summary><strong>Validation and parsing boundaries</strong></summary>
-
-- Validators return `true` or throw; they do not return `false`.
-- URI functions reject non-ASCII characters where RFC 3986 permits only URI syntax. Use the IRI functions for RFC 3987 Unicode ranges.
-- `absolute-URI` and `absolute-IRI` exclude fragments by definition. The complete `URI` and `IRI` functions permit fragments.
-- Scheme-specific processing currently specializes hostname syntax; it does not implement every protocol rule for HTTP, WebSocket, or `file` identifiers.
-- Scheme-specific Unicode labels are not complete IDNA validation.
-- Ports are restricted to an empty value or the numeric range 0–65535. Generic RFC 3986 syntax itself permits any sequence of digits.
-- Generic registered names may contain syntax that DNS-style hostnames reject.
-- Parsing separates components before any application-level percent decoding.
-- The library does not perform network, DNS, filesystem, registry, or authorization checks.
+<summary><strong>Validation and parsing</strong></summary>
+
+- Generic URI syntax follows RFC 3986 character and component grammar; recognized schemes select the documented hostname profile.
+- Generic IRI syntax follows the RFC 3987 Unicode extensions to URI grammar; recognized schemes select the documented hostname profile.
+- Validators return `true` or throw at the first grammar violation.
+- `absolute-URI` and `absolute-IRI` use the fragment-free grammar defined by their RFCs; complete URI and IRI operations accept fragments.
+- Port syntax follows RFC 3986 `port = *DIGIT`, including empty and leading-zero values.
+- Parsing records absent optional components as `undefined` and present-empty components as empty strings.
 
 </details>
 
 <details>
-<summary><strong>Resolution and conversion boundaries</strong></summary>
+<summary><strong>Resolution, conversion, and normalization</strong></summary>
 
-- Resolution uses IRI grammar, so Unicode references and bases are accepted.
-- Empty authorities, queries, and fragments remain distinct from absent components.
-- `strict = false` enables RFC 3986 backward-compatible handling when a reference repeats the base scheme.
-- `toAbsoluteReference` requires an identifier containing a scheme and removes its fragment through empty-reference resolution.
-- `toRelativeReference` compares scheme and authority text exactly; it does not normalize them first.
-- `toRelativeReference` may return an absolute target when a rootless relative path cannot preserve identity.
-- `normalizeReference` is intentionally an identity function until a normalization contract is selected.
+- `resolveReference` implements RFC 3986 §5 component inheritance, path merging, dot-segment removal, and recomposition for URI and IRI text.
+- An empty reference path inherits the base path unchanged.
+- `strict = false` implements RFC 3986 §5.2.2 backward-compatible same-scheme handling.
+- `toAbsoluteReference` removes the fragment from an identifier containing a scheme.
+- `toRelativeReference` generates a reference whose RFC resolution equals the target resolution for supported forms.
+- `normalize()` implements the applicable case, percent-encoding, and path-segment rules from RFC 3986 §§6.2.2.1–6.2.2.3 and RFC 3987 §§5.3.2.1, 5.3.2.3–5.3.2.4, RFC 3987 §§3.1–3.2 URI/IRI representation transformation, RFC 5952 IPv6 text, RFC 9110 HTTP(S) port/path forms, and RFC 6455 WS(S) port/resource-name forms.
 
 </details>
 
 <details>
-<summary><strong>UUID boundaries</strong></summary>
+<summary><strong>UUID validation</strong></summary>
 
-- `isUUID` validates canonical hexadecimal layout only; it does not enforce a known version or the RFC variant.
-- `isUUIDv4` validates the version and variant fields but does not assess random-number quality.
-- A syntactically valid UUID is not proof of uniqueness, integrity, authenticity, or authorization.
+- `isUUID` validates the RFC 9562 hexadecimal `8-4-4-4-12` text layout.
+- `isUUIDv4` additionally validates version `4` and the RFC variant bits.
 
 </details>
 
@@ -457,7 +475,7 @@ Run `gh workspace-data load` again to refresh materialized data after public-dat
 
 ### Tests
 
-The active suite contains 3,064 tests covering URI/IRI validation and parsing, scheme-specific hosts, IPv4, IPv6, ports, UUIDs, RFC 3986 resolution examples, empty components, absolute conversion, and relative-reference round trips, including 2,646 generated combinations of target/base paths, query-presence states, and target-fragment states across equivalent URI and IRI families.
+The active suite contains 3,137 tests covering URI/IRI validation, parsing, generic normalization, bidirectional URI/IRI representation transformation, scheme-specific hosts, IPv4, IPv6, IPvFuture, ports, UUIDs, RFC 3986 resolution examples, empty components, absolute conversion, and relative-reference round trips, including 2,646 generated combinations of target/base paths, query-presence states, and target-fragment states across equivalent URI and IRI families.
 
 <details>
 <summary><strong>Test details</strong></summary>
@@ -500,7 +518,7 @@ Direct invocation also supports an explicit iteration count; `npm run benchmark`
 node ./#/public/benchmarks --iterations 250000
 ```
 
-The generic coordinator delegates version-layer selection and ordered concern discovery to the `gh-workspace-data v0.5.0` runtime. The materialized `#/public/benchmarks/README.md` documents concern registration, version eligibility, workload controls, measurement semantics, output fields, and guidance for interpreting results from noisy CI runners. Benchmark values are observations rather than correctness assertions.
+The generic coordinator delegates version-layer selection and ordered concern discovery to the `gh-workspace-data v0.5.0` runtime. The materialized `#/public/benchmarks/README.md` documents concern registration, version eligibility, workload controls, measurement semantics, output fields, and guidance for interpreting results from noisy CI runners.
 
 </details>
 
@@ -512,7 +530,3 @@ The generic coordinator delegates version-layer selection and ordered concern di
 - [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
 - [RFC 8089 — The `file` URI Scheme](https://www.rfc-editor.org/rfc/rfc8089)
 - [RFC 9562 — Universally Unique IDentifiers](https://www.rfc-editor.org/rfc/rfc9562)
-
-## Disclaimer
-
-Validation establishes conformance with this implementation's syntax and policy. It does not establish that an identifier is registered, reachable, trustworthy, safe to dereference, or appropriate for a particular protocol operation.