identifier-js 0.4.1 → 0.4.3

package/index.js

@@ -1,13 +1,13 @@
 'use strict';
-// Parse, validate, normalize, resolve, and convert RFC 3986 URI, RFC 3987 IRI, and RFC 8141 URN references.
+// Validate UUIDs and parse, validate, normalize, resolve, and convert RFC 3986 URI, RFC 3987 IRI, and RFC 8141 URN references.
 // A valid URI is always a valid IRI, subject to every implemented scheme's more specific grammar.
 const { recursiveCompile } = require('url-templates');
-const patterns = new Map();
-const implemented_schemes = '(?:[hH][tT][tT][pP][sS]?|[wW][sS][sS]?|[fF][iI][lL][eE])';
-// RFC3986/RFC3987 common rules + https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2:~:text=DNS%29%2E-,A,of%20%5BRFC1123%5D%2E
+const patternCache = new Map();
+const dnsHostSchemesPattern = '(?:[hH][tT][tT][pP][sS]?|[wW][sS][sS]?|[fF][iI][lL][eE])';
+// Define shared RFC 3986/3987 productions and helper productions used by UUID and scheme-specific grammars.
 const commonRules = {
-    implemented_schemes,
-    scheme: '(?!{implemented_schemes}:)[a-zA-Z][a-zA-Z0-9+.-]*',
+    dnsHostSchemesPattern,
+    scheme: '(?!{dnsHostSchemesPattern}:)[a-zA-Z][a-zA-Z0-9+.-]*',
     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})?::)',
@@ -26,7 +26,7 @@ const commonRules = {
     UUID: '{hex_digit}{8}-{hex_digit}{4}-{hex_digit}{4}-{hex_digit}{4}-{hex_digit}{12}',
     UUID_v4: '{hex_digit}{8}-{hex_digit}{4}-4{hex_digit}{3}-[89abAB]{hex_digit}{3}-{hex_digit}{12}',
 };
-// RFC3986 rules
+// Define RFC 3986 URI productions.
 const uriRules = {
     URI_reference: '(?:{URI}|{relative_ref})',
     URI: '{absolute_URI}(?:#{fragment})?',
@@ -51,7 +51,7 @@ const uriRules = {
     fragment: '(?:{pchar}|\/|\\?)*',
     pchar: '(?:{unreserved}|{pct_encoded}|{sub_delims}|:|@)',
 };
-// RFC3987 rules
+// Define RFC 3987 IRI productions.
 const iriRules = {
     IRI_reference: '(?:{IRI}|{irelative_ref})',
     IRI: '{absolute_IRI}(?:#{ifragment})?',
@@ -79,32 +79,34 @@ 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}]',
 };
-// Define RFC 8141 productions and URI/IRI root overrides for the conditional URN profile.
+// Define a closed RFC 8141 profile whose root overrides and direct fragment expression expose only URN captures.
 const urnRules = {
     scheme: '[uU][rR][nN]',
+    URI_reference: '{URI}',
     URI: '{namestring}',
     absolute_URI: '{assigned_name}(?:{rq_components})?',
+    IRI_reference: '{IRI}',
     IRI: '{URI}',
     absolute_IRI: '{absolute_URI}',
     namestring: '{assigned_name}(?:{rq_components})?(?:#{f_component})?',
     assigned_name: '{scheme}:{NID}:{NSS}',
     NID: '{alpha_digit}{ldh}{0,30}{alpha_digit}',
     ldh: '(?:{alpha_digit}|-)',
-    NSS: '{pchar}(?:{pchar}|/)*',
+    NSS: '{pchar}(?:{pchar}|\/)*',
     rq_components: '(?:[?][+]{r_component})?(?:[?]={q_component})?',
-    r_component: '{pchar}(?:{pchar}|/|[?](?!=))*',
-    q_component: '{pchar}(?:{pchar}|/|[?])*',
-    f_component: '{fragment}',
+    r_component: '{pchar}(?:{pchar}|\/|[?](?!=))*',
+    q_component: '{pchar}(?:{pchar}|\/|[?])*',
+    f_component: uriRules.fragment,
 };
-// Reuse the grammar repertoires when selecting URI octets safe for IRI output.
+// Compile character-repertoire checks used during URI/IRI percent-encoding normalization.
 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,
+// Restrict registered names for selected hierarchical schemes to DNS-style labels.
+const dnsHostRules = {
+    scheme: dnsHostSchemesPattern,
     reg_name: '(?:(?=.{1,255}(?:[:/?#]|$))(?:{a_label})(?:\\.{a_label})*)',
     a_label: '(?:{alpha_digit})(?:(?:{alpha_digit}|-){0,61}(?:{alpha_digit}))?',
     ireg_name: '(?:(?=.{1,255}(?:[:/?#]|$))(?:{u_label})(?:{u_separator}(?:{u_label}))*)',
@@ -113,13 +115,13 @@ const schemeSpecificRules = {
     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, {
+const emptyFileHostRules = Object.assign({}, dnsHostRules, {
     scheme: '[fF][iI][lL][eE]',
     reg_name: '',
     ireg_name: '',
 });
-// pattern RFC group names
-const groupNames = {
+// Map grammar productions to the public named captures returned by parsers.
+const captureGroupNames = {
     scheme: 'scheme',
     port: 'port',
     authority: 'authority',
@@ -148,25 +150,21 @@ const groupNames = {
     q_component: 'qComponent',
     f_component: 'fComponent',
 };
-// Keep URN parse results limited to their RFC 8141 component names.
-const genericUrnGroupNames = new Set(['authority', 'userinfo', 'host', 'port', 'path', 'query', 'fragment']);
-// Detect schemes for which the package implements grammar beyond generic URI/IRI syntax.
-const isSpecificScheme = (string) => new RegExp('^' + implemented_schemes + ':').test(string);
-// Select and merge generic, DNS-host, empty-file-host, or URN grammar profiles.
-const schemeProfile = (string) => (string.slice(0, 4).toLowerCase() === 'urn:' ? 'u' : string.slice(0, 8).toLowerCase() === 'file:///' ? 'f' : isSpecificScheme(string) ? 's' : '');
-const rules = (profile) => Object.assign({}, commonRules, uriRules, iriRules, profile === 'u' ? urnRules : profile === 'f' ? emptyFileHostRules : profile ? schemeSpecificRules : {});
-// parse (slower, it uses regex.exec and includes named capture groups)
+// Detect schemes whose registered names use the DNS-host grammar.
+const usesDnsHostRules = (string) => new RegExp('^' + dnsHostSchemesPattern + ':').test(string);
+// Grammar profiles: '' is generic, 's' uses DNS-host rules, 'f' permits an empty file host, and 'u' is URN.
+const grammarProfile = (string) => (string.slice(0, 4).toLowerCase() === 'urn:' ? 'u' : string.slice(0, 8).toLowerCase() === 'file:///' ? 'f' : usesDnsHostRules(string) ? 's' : '');
+// Select and merge the rules for the active grammar profile.
+const grammarRules = (profile) => Object.assign({}, commonRules, uriRules, iriRules, profile === 'u' ? urnRules : profile === 'f' ? emptyFileHostRules : profile ? dnsHostRules : {});
+// Compile and execute a grammar with named component captures.
 const parse = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
-    const profile = schemeProfile(string);
-    // Select only the component captures exposed by the active grammar.
-    const addNames = (key) => {
-        const groupName = groupNames[key];
-        return groupName && !(profile === 'u' && genericUrnGroupNames.has(groupName)) ? `(?<${groupName}>${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);
+    const profile = grammarProfile(string);
+    // Wrap each public component production in its associated named capture.
+    const addNamedCapture = (key) => (captureGroupNames[key] ? `(?<${captureGroupNames[key]}>${grammarRules(profile)[key]})` : grammarRules(profile)[key]);
+    const cacheKey = '_' + profile + rule;
+    if (!patternCache.has(cacheKey)) patternCache.set(cacheKey, new RegExp(`^${recursiveCompile(grammarRules(profile), rule, addNamedCapture)}$`, 'u'));
+    const match = patternCache.get(cacheKey).exec(string);
     if (match) {
         Object.defineProperty(match.groups, 'normalize', {
             // Normalize this parsed result only when its optional method is called.
@@ -178,17 +176,17 @@ const parse = (string, rule) => {
     }
     throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
 };
-// validate (faster, it uses regex.test and does not include named capture groups)
+// Compile and test a capture-free grammar for validation.
 const validate = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
-    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;
+    const profile = grammarProfile(string);
+    const cacheKey = profile + rule;
+    if (!patternCache.has(cacheKey)) patternCache.set(cacheKey, new RegExp(`^${recursiveCompile(grammarRules(profile), rule)}$`, 'u'));
+    if (patternCache.get(cacheKey).test(string)) return true;
     throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
 };
-// compose as per RFC 3986 Section 5.3 (component recomposition)
-function compose(parts = {}) {
+// Serialize scheme, authority, path, query, and fragment slots using RFC 3986 delimiters.
+function composeReference(parts = {}) {
     let result = '';
     if (parts.scheme) result += parts.scheme + ':';
     if (parts.authority !== undefined && parts.authority !== null) result += '//' + parts.authority;
@@ -197,7 +195,8 @@ function compose(parts = {}) {
     if (parts.fragment !== undefined && parts.fragment !== null) result += '#' + parts.fragment;
     return result;
 }
-// remove dot segments algorithm per RFC 3986 Section 5.2.4 (loop and replace)
+// Local abbreviations: idx is an index and seg is a path segment.
+// Remove complete dot segments using the RFC 3986 Section 5.2.4 algorithm.
 function removeDotSegments(path) {
     const output = [];
     let input = path ?? '';
@@ -242,8 +241,9 @@ function removeDotSegments(path) {
     }
     return output.join('');
 }
-// resolve as per RFC https://datatracker.ietf.org/doc/html/rfc3986#section-5.2
-function resolveReference(reference, base, strict = true, parts = false) {
+// RFC 3986 resolution notation: B is the base, R is the reference, and T is the target.
+// Resolve a reference according to RFC 3986 Section 5.2.
+function resolveReference(reference, base, strict = true, returnParts = false) {
     let B;
     if (typeof base === 'string') {
         B = parse(base, 'IRI');
@@ -292,14 +292,14 @@ function resolveReference(reference, base, strict = true, parts = false) {
         }
         T.fragment = R.fragment;
     }
-    if (parts) return T;
-    return compose(T);
+    if (returnParts) return T;
+    return composeReference(T);
 }
 // 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);
+    return composeReference(result);
 }
 // Generate a relative reference when resolution is stable, otherwise retain the absolute target.
 const toRelativeReference = (target, base) => {
@@ -378,27 +378,27 @@ function normalizePercentEncoding(value, decodeUnreserved = true) {
 }
 // Expand any accepted IPv6 spelling into eight numeric 16-bit fields.
 function parseIPv6Words(address) {
-    let expanded = address;
+    let addressText = 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);
+    const lastColon = addressText.lastIndexOf(':');
+    const lastSegment = addressText.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 highWord = Number(octets[0]) * 0x100 + Number(octets[1]);
+        const lowWord = Number(octets[2]) * 0x100 + Number(octets[3]);
+        addressText = `${addressText.slice(0, lastColon + 1)}${highWord.toString(16)}:${lowWord.toString(16)}`;
     }
 
-    const compression = expanded.indexOf('::');
-    const leftText = compression === -1 ? expanded : expanded.slice(0, compression);
-    const rightText = compression === -1 ? '' : expanded.slice(compression + 2);
+    const compressionIndex = addressText.indexOf('::');
+    const leftText = compressionIndex === -1 ? addressText : addressText.slice(0, compressionIndex);
+    const rightText = compressionIndex === -1 ? '' : addressText.slice(compressionIndex + 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) {
+    if (compressionIndex !== -1) {
         // Fill the omitted field count determined from both explicit sides.
         for (let index = left.length + right.length; index < 8; index++) words.push(0);
     }
@@ -428,7 +428,7 @@ function serializeIPv6Words(words) {
     if (bestLength < 2) bestStart = -1;
 
     const fields = [];
-    // Suppress every leading zero by converting each field through its numeric value.
+    // Render each field without leading hexadecimal zeroes.
     for (const word of words) fields.push(word.toString(16));
     if (bestStart === -1) return fields.join(':');
     const before = fields.slice(0, bestStart).join(':');
@@ -440,11 +440,11 @@ 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 isCompatible = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0 && low32 > 1;
+    const isMapped = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0xFFFF;
+    const isTranslated = words[0] === 0 && words[1] === 0 && words[2] === 0 && words[3] === 0 && words[4] === 0xFFFF && words[5] === 0;
+    const isWellKnownNat64 = words[0] === 0x64 && words[1] === 0xFF9B && words[2] === 0 && words[3] === 0 && words[4] === 0 && words[5] === 0;
+    if (isCompatible || isMapped || isTranslated || isWellKnownNat64) {
         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}`;
@@ -485,20 +485,20 @@ function normalizeHost(host, mapRegName) {
     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.
+// Omit an empty or default port only for HTTP and WebSocket schemes.
 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) {
+// Encode each non-ASCII Unicode scalar as uppercase UTF-8 percent triplets for URI output.
+function encodeNonAsciiForUri(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) {
+// Decode the maximal RFC 3987 character repertoire allowed by one IRI component.
+function decodeUriTextToIri(component, allowPrivateUse = 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++) {
@@ -514,28 +514,28 @@ function decodeUriComponentToIri(component, allowPrivate = false) {
             continue;
         }
         const sequenceLength = octet >= 0xC2 && octet <= 0xDF ? 2 : octet >= 0xE0 && octet <= 0xEF ? 3 : octet >= 0xF0 && octet <= 0xF4 ? 4 : 0;
-        let encoded = '';
+        let encodedSequence = '';
         // 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 = '';
+                encodedSequence = '';
                 break;
             }
-            encoded += component.slice(position, position + 3);
+            encodedSequence += component.slice(position, position + 3);
         }
         let character;
-        if (encoded) {
+        if (encodedSequence) {
             try {
-                character = decodeURIComponent(encoded);
+                character = decodeURIComponent(encodedSequence);
             } catch {
                 character = undefined;
             }
         }
-        const allowed = character !== undefined && !forbiddenIriFormattingPattern.test(character) && (iriUcscharPattern.test(character) || (allowPrivate && iriPrivatePattern.test(character)));
-        if (allowed) {
+        const isAllowedIriCharacter = character !== undefined && !forbiddenIriFormattingPattern.test(character) && (iriUcscharPattern.test(character) || (allowPrivateUse && iriPrivatePattern.test(character)));
+        if (isAllowedIriCharacter) {
             result += character;
-            index += encoded.length - 1;
+            index += encodedSequence.length - 1;
         } else {
             result += `%${hexadecimal}`;
             index += 2;
@@ -543,7 +543,7 @@ function decodeUriComponentToIri(component, allowPrivate = false) {
     }
     return result;
 }
-// Rebuild authority from normalized values while preserving other empty component delimiters.
+// Rebuild authority from normalized userinfo, host, and port while preserving their presence.
 function normalizeAuthority(parts, scheme, mapRegName) {
     if (parts.authority === undefined) return undefined;
     const userinfo = parts.userinfo === undefined ? undefined : normalizePercentEncoding(parts.userinfo);
@@ -566,12 +566,12 @@ function normalizeParsedReference(parts, options = {}) {
     if (parts.nid !== undefined) {
         const rComponent = parts.rComponent === undefined ? undefined : normalizePercentEncoding(parts.rComponent, false);
         const qComponent = parts.qComponent === undefined ? undefined : normalizePercentEncoding(parts.qComponent, false);
-        const query = rComponent !== undefined ? `+${rComponent}${qComponent === undefined ? '' : `?=${qComponent}`}` : qComponent === undefined ? undefined : `=${qComponent}`;
-        return compose({ scheme: parts.scheme.toLowerCase(), path: `${parts.nid.toLowerCase()}:${normalizePercentEncoding(parts.nss, false)}`, query, fragment: parts.fComponent === undefined ? undefined : normalizePercentEncoding(parts.fComponent, false) });
+        const rqComponentText = rComponent !== undefined ? `+${rComponent}${qComponent === undefined ? '' : `?=${qComponent}`}` : qComponent === undefined ? undefined : `=${qComponent}`;
+        return composeReference({ scheme: parts.scheme.toLowerCase(), path: `${parts.nid.toLowerCase()}:${normalizePercentEncoding(parts.nss, false)}`, query: rqComponentText, fragment: parts.fComponent === undefined ? undefined : normalizePercentEncoding(parts.fComponent, false) });
     }
     // Normalize each component independently so encoded delimiters cannot become structure.
     const scheme = parts.scheme === undefined ? undefined : parts.scheme.toLowerCase();
-    const normalized = {
+    const normalizedParts = {
         scheme,
         authority: normalizeAuthority(parts, scheme, mapRegName),
         path: normalizePercentEncoding(parts.path),
@@ -579,31 +579,31 @@ function normalizeParsedReference(parts, options = {}) {
         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 = '/';
+    if (normalizedParts.authority !== undefined && normalizedParts.path === '' && (scheme === 'http' || scheme === 'https' || scheme === 'ws' || scheme === 'wss')) normalizedParts.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('/');
+    const rootlessRelativePath = normalizedParts.scheme === undefined && normalizedParts.authority === undefined && normalizedParts.path.length > 0 && !normalizedParts.path.startsWith('/');
     if (!rootlessRelativePath) {
-        const reducedPath = removeDotSegments(normalized.path);
+        const reducedPath = removeDotSegments(normalizedParts.path);
         // Preserve a no-authority path when reduction would reparse it as an authority.
-        if (normalized.authority !== undefined || !reducedPath.startsWith('//')) normalized.path = reducedPath;
+        if (normalizedParts.authority !== undefined || !reducedPath.startsWith('//')) normalizedParts.path = reducedPath;
     }
-    // Select an explicit target representation only after syntax and scheme normalization is complete.
+    // Select an explicit target representation only after component 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);
+        // Percent-encode every non-ASCII authority, path, query, and fragment scalar for URI output.
+        if (normalizedParts.authority !== undefined) normalizedParts.authority = encodeNonAsciiForUri(normalizedParts.authority);
+        normalizedParts.path = encodeNonAsciiForUri(normalizedParts.path);
+        if (normalizedParts.query !== undefined) normalizedParts.query = encodeNonAsciiForUri(normalizedParts.query);
+        if (normalizedParts.fragment !== undefined) normalizedParts.fragment = encodeNonAsciiForUri(normalizedParts.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);
+        if (normalizedParts.authority !== undefined) normalizedParts.authority = decodeUriTextToIri(normalizedParts.authority);
+        normalizedParts.path = decodeUriTextToIri(normalizedParts.path);
+        if (normalizedParts.query !== undefined) normalizedParts.query = decodeUriTextToIri(normalizedParts.query, true);
+        if (normalizedParts.fragment !== undefined) normalizedParts.fragment = decodeUriTextToIri(normalizedParts.fragment);
     }
-    return compose(normalized);
+    return composeReference(normalizedParts);
 }
-// export
+// Expose the public validation, parsing, resolution, and conversion API.
 module.exports = {
     isUUID: (string) => validate(string, 'UUID'),
     isUUIDv4: (string) => validate(string, 'UUID_v4'),

package/normalization.md

@@ -1,6 +1,6 @@
 # URI and IRI normalization
 
-Parsed URI and IRI results expose `normalize()` for syntax-based normalization, the implemented HTTP, HTTPS, WS, WSS, and URN scheme rules, and optional RFC 3987 URI/IRI representation transformation. The method returns a string and leaves the parsed components unchanged.
+Parsed URI and IRI results expose `normalize()` for generic syntax normalization, scheme-specific HTTP and WebSocket forms, the separate RFC 8141 URN normalization path, and optional RFC 3987 URI/IRI representation transformation. The method returns a string and leaves the parsed components unchanged.
 
 ## API
 
@@ -44,13 +44,13 @@ parsed.path;
 // /%7e/a/../b
 ```
 
-## RFC syntax normalization
+## Generic URI and IRI 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 | For generic URI/IRI components, decode percent triplets representing ASCII letters, digits, `-`, `.`, `_`, or `~`. Retain percent encoding for reserved octets. URNs use the non-decoding rules below. | [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 a generic parsed reference can be normalized independently. Preserve unresolved rootless-relative path semantics and every URN NSS segment. | [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), [RFC 8141 §§2.2 and 3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.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 a parsed generic 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) |
@@ -58,31 +58,9 @@ parsed.path;
 
 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.
 
-## URNs
+## Scheme-specific normalization
 
-A parsed value under the case-insensitive `urn` scheme takes a separate RFC 8141 normalization path using its captured `scheme`, `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` properties.
-
-| Input component | Output | Source |
-| --- | --- | --- |
-| Scheme | Convert `urn` to lowercase. | [RFC 8141 §3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
-| NID | Convert ASCII letters to lowercase. | [RFC 8141 §§2.1 and 3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
-| NSS | Uppercase hexadecimal letters in percent triplets without decoding any octet. Preserve literal case, slash structure, and dot segments. | [RFC 8141 §§2.2 and 3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
-| r-, q-, and f-components | Retain the components and their delimiters, uppercasing hexadecimal letters in percent triplets without decoding. | [RFC 8141 §2.3](https://www.rfc-editor.org/rfc/rfc8141#section-2.3), [RFC 3986 §6.2.2.1](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1) |
-
-```js
-const { parseUri } = require('identifier-js');
-
-parseUri('URN:EXAMPLE:a%62/./b/../C?+r%2f?=q%2f#f%2f').normalize();
-// urn:example:a%62/./b/../C?+r%2F?=q%2F#f%2F
-```
-
-RFC 8141 URNs remain ASCII, including when parsed through an IRI operation. Consequently, `transform: 'URI'` and `transform: 'IRI'` produce the same URN representation, and `mapRegName` is not called because a URN has no authority or registered-name host.
-
-For a parsed URN, the current scheme-specific fields are the normalization input. The NSS and optional-component values stay opaque except for percent-triplet letter case. The method leaves every property unchanged.
-
-Normalization is not a URN-equivalence API. RFC 8141 equivalence compares the normalized assigned-name and ignores r-, q-, and f-components; namespace definitions can add further equivalence rules. This method instead retains those optional components in its returned string. The package does not implement generic or namespace-specific URN-equivalence comparison.
-
-## HTTP and HTTPS
+### HTTP and HTTPS
 
 For `http` and `https`, normalization applies the generic rules and these scheme rules:
 
@@ -101,7 +79,7 @@ https://example.com:00443/a          → https://example.com/a
 http://example.com:/a                → http://example.com/a
 ```
 
-## WS and WSS
+### WS and WSS
 
 For `ws` and `wss`, normalization applies the generic rules and these scheme rules:
 
@@ -118,11 +96,47 @@ wss://example.com:00443/chat         → wss://example.com/chat
 ws://example.com?channel=updates     → ws://example.com/?channel=updates
 ```
 
+### URNs
+
+A parsed value under the case-insensitive `urn` scheme takes the separate RFC 8141 normalization path using its captured `scheme`, `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` properties.
+
+| Input component | Output | Source |
+| --- | --- | --- |
+| Scheme | Convert `urn` to lowercase. | [RFC 8141 §3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
+| NID | Convert ASCII letters to lowercase. | [RFC 8141 §§2.1 and 3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
+| NSS | Uppercase hexadecimal letters in percent triplets without decoding any octet. Preserve literal case, slash structure, and dot segments. | [RFC 8141 §§2.2 and 3.1](https://www.rfc-editor.org/rfc/rfc8141#section-3.1) |
+| r-, q-, and f-components | Retain the components and their delimiters, uppercasing hexadecimal letters in percent triplets without decoding. | [RFC 8141 §2.3](https://www.rfc-editor.org/rfc/rfc8141#section-2.3), [RFC 3986 §6.2.2.1](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1) |
+
+```js
+const { parseUri } = require('identifier-js');
+
+const input = 'URN:EXAMPLE:a%62/./b/../C?+r%2f?=q%2f#f%2f';
+const output = parseUri(input).normalize();
+
+output;
+// urn:example:a%62/./b/../C?+r%2F?=q%2F#f%2F
+```
+
+This example demonstrates each URN normalization rule:
+
+- `URN` becomes `urn` because the scheme is case-insensitive and normalized to lowercase.
+- `EXAMPLE` becomes `example` because ASCII letters in the NID are normalized to lowercase.
+- `%62` remains encoded in the NSS rather than becoming `b`; URN normalization does not decode percent-encoded NSS octets.
+- `/./b/../C` remains unchanged because the NSS is opaque to generic path processing: dot segments are not removed, and literal NSS case is preserved.
+- The r-, q-, and f-components and their `?+`, `?=`, and `#` delimiters are retained.
+- `%2f` becomes `%2F` in each optional component because retained percent triplets use uppercase hexadecimal letters without decoding the represented `/`.
+
+RFC 8141 URNs remain ASCII, including when parsed through an IRI operation. Consequently, `transform: 'URI'` and `transform: 'IRI'` produce the same URN representation, and `mapRegName` is not called because a URN has no authority or registered-name host.
+
+For a parsed URN, the current URN-specific fields are the normalization input. The NSS and optional-component values stay opaque except for percent-triplet letter case. The method leaves every property unchanged.
+
+Normalization is not a URN-equivalence API. RFC 8141 equivalence compares the normalized assigned name and ignores r-, q-, and f-components; namespace definitions can add further equivalence rules. This method instead retains those optional components in its returned string. The package does not implement generic or namespace-specific URN-equivalence comparison.
+
 ## 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.
+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 the DNS-host grammar. The returned string then receives percent-triplet and ASCII host-case normalization. Mapper exceptions propagate unchanged.
 
 ```js
 const mapped = parseIriReference('x://example').normalize({
@@ -135,27 +149,61 @@ mapped;
 
 The example deliberately produces text that is not a valid URI or IRI; validating or selecting mapper output belongs to the application.
 
+### IRI-to-URI transformation
+
 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');
+const { parseIri } = 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
+const input = 'x://usér@exämple/latin-é/emoji-😀?native=資料&private=\uE000&reserved=/&encoded=%c3%a9#résultat';
+const output = parseIri(input).normalize({ transform: 'URI' });
 
-parseUri('x:/caf%C3%A9?q=%E8%B3%87%E6%96%99#r%C3%A9sultat').normalize({ transform: 'IRI' });
-// x:/café?q=資料#résultat
+output;
+// x://us%C3%A9r@ex%C3%A4mple/latin-%C3%A9/emoji-%F0%9F%98%80?native=%E8%B3%87%E6%96%99&private=%EE%80%80&reserved=/&encoded=%C3%A9#r%C3%A9sultat
 ```
 
+This example demonstrates each relevant output rule:
+
+- `usér`, `exämple`, `latin-é`, and `résultat` become UTF-8 percent triplets in userinfo, host, path, and fragment text.
+- `😀` is processed as one Unicode scalar and becomes its four UTF-8 octets `%F0%9F%98%80`.
+- `資料` becomes `%E8%B3%87%E6%96%99` in the query.
+- The query's private-use character `\uE000` becomes `%EE%80%80`.
+- The literal reserved `/` remains literal because it is already valid URI query syntax.
+- The existing encoded sequence `%c3%a9` remains encoded while its hexadecimal letters become uppercase as `%C3%A9`.
+
+### URI-to-IRI transformation
+
 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.
 
+```js
+const { parseUri } = require('identifier-js');
+
+const input = 'x:/ok-%C3%A9/reserved-%2F/percent-%25/malformed-%C3%28/incomplete-%E2%82/latin1-%E9/outside-%EF%B7%90/bidi-%E2%80%8E';
+const output = parseUri(input).normalize({ transform: 'IRI' });
+
+output;
+// x:/ok-é/reserved-%2F/percent-%25/malformed-%C3%28/incomplete-%E2%82/latin1-%E9/outside-%EF%B7%90/bidi-%E2%80%8E
+```
+
+This example shows why transformation is not equivalent to applying `decodeURIComponent()` to every triplet:
+
+- `%C3%A9` becomes `é` because it is valid UTF-8 for a character permitted in an IRI path.
+- `%2F` remains encoded because `/` is reserved and decoding it could change path structure.
+- `%25` remains encoded because decoding it would introduce a literal percent sign.
+- `%C3%28` remains encoded because it is malformed UTF-8.
+- `%E2%82` remains encoded because it is an incomplete UTF-8 sequence.
+- `%E9` remains encoded because a Latin-1 or Windows-1252 byte is not valid UTF-8 by itself.
+- `%EF%B7%90` remains encoded because it represents U+FDD0, which is outside the RFC 3987 character repertoire.
+- `%E2%80%8E` remains encoded because it represents U+200E, a forbidden bidirectional formatting character.
+
 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.
+The normalization suite covers generic URI and IRI parser results, RFC 8141 URNs, 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "identifier-js",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A fast RFC 3986/3987 URI/IRI parser, validator, normalizer, resolver, and composer with RFC 8141 URN syntax support.",
   "keywords": [
     "IRI",

package/readme.md

@@ -2,17 +2,17 @@
 
 title: Identifier JS
 
-description: RFC 3986/3987 URI and IRI tools with scheme-specific RFC 8141 URN syntax and normalization support.
+description: RFC 3986/3987 URI and IRI tools with RFC 8141 URN grammar and normalization support.
 
 ---
 
 # Identifier JS
 
-`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), with scheme-specific RFC [8141](https://www.rfc-editor.org/rfc/rfc8141) URN support. Its recognized HTTP, WebSocket, and `file` schemes retain the documented hostname-policy restrictions below. It provides:
+`identifier-js` is a URI/IRI parser, validator, normalizer, resolver, and reference converter based on RFC [3986](https://www.rfc-editor.org/rfc/rfc3986) and RFC [3987](https://www.rfc-editor.org/rfc/rfc3987), with an RFC [8141](https://www.rfc-editor.org/rfc/rfc8141) URN grammar profile. HTTP, WebSocket, and `file` identifiers use the documented DNS-host grammar where applicable. It provides:
 
 - URI and IRI validation, including RFC 8141 URN namestring syntax;
-- parsed generic URI/IRI components and scheme-specific URN components;
-- conservative syntax normalization, recognized-scheme forms, and a registered-name extension point;
+- parsed generic URI/IRI components and URN-specific components;
+- conservative syntax normalization, scheme-specific forms, and a registered-name extension point;
 - RFC 3986 reference resolution and dot-segment removal;
 - relative-reference generation with resolution round-trip guarantees for supported forms;
 - UUID and UUIDv4 lexical validation;
@@ -28,7 +28,7 @@ npm install identifier-js
 
 ## API
 
-Every validator returns `true` or throws at the first detected violation. Parsing and reference operations also throw when their input does not satisfy the required grammar.
+Every validator returns `true` for valid input and otherwise throws. Parsing and reference operations also throw when their input does not satisfy the required grammar.
 
 ### Validate URI syntax
 
@@ -143,45 +143,6 @@ console.log(parseIri('https://usér@例え.テスト:8443/résumé?lang=fr#profi
 
 </details>
 
-### Validate and parse RFC 8141 URNs
-
-URNs use the existing URI and IRI operations because a URN is a URI under the `urn` scheme. Values with a case-insensitive `urn:` prefix are validated against RFC 8141 namestring syntax; no separate `isUrn` or `parseUrn` API is exported.
-
-```text
-urn:NID:NSS[?+r-component][?=q-component][#f-component]
-```
-
-The NID contains 2–32 ASCII characters, starts and ends with a letter or digit, and permits letters, digits, or hyphens internally. The NSS begins with an RFC 3986 `pchar` and then permits `pchar` or `/`. The ordered r- and q-components also begin with `pchar` and then permit `pchar`, `/`, or `?`, while an f-component can be empty. The first `?=` sequence after an r-component starts the q-component, and any other question mark outside an optional component is rejected.
-
-<details>
-<summary><strong>API behavior and examples</strong></summary>
-
-```js
-const { isUri, isIri, parseUri } = require('identifier-js');
-
-const value = 'URN:Example:a%2f/../B?+service?x?=key=value#part';
-console.log(isUri(value)); // true
-console.log(isIri(value)); // true
-
-const parsed = parseUri(value);
-console.log(parsed.scheme);     // URN
-console.log(parsed.nid);        // Example
-console.log(parsed.nss);        // a%2f/../B
-console.log(parsed.rComponent); // service?x
-console.log(parsed.qComponent); // key=value
-console.log(parsed.fComponent); // part
-console.log(parsed.normalize());
-// urn:example:a%2F/../B?+service?x?=key=value#part
-```
-
-URN parse results expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent`. They do not expose generic `path`, `query`, or `fragment` aliases. To require a URN after parsing a value accepted as a general URI, check `parsed.scheme.toLowerCase() === 'urn'`.
-
-URNs remain ASCII even through the IRI operations. Callers representing non-ASCII names must first encode them as UTF-8 and then percent-encode the resulting octets; lexical validation does not decode or verify those octet sequences.
-
-Validation is deliberately lexical and namespace-independent. Success does not prove that an NID is registered or otherwise legitimate, that an NSS obeys a namespace's additional syntax and canonicalization rules, or that the name was legitimately assigned.
-
-</details>
-
 ### Resolve a reference
 
 Resolve a URI or IRI reference against an absolute base using RFC 3986 §5.
@@ -251,7 +212,7 @@ When no safe rootless relative form can round-trip to the target, `toRelativeRef
 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>API, behavior, and examples</strong></summary>
+<summary><strong>API and examples</strong></summary>
 
 ```ts
 type RegNameMapper = (regName: string) => string
@@ -284,7 +245,7 @@ Normalization implements RFC 3986 and RFC 3987 syntax normalization for scheme a
 
 URN normalization lowercases the scheme and NID, uppercases percent-triplet hexadecimal letters without decoding, and preserves NSS case, slashes, and dot segments. The r-, q-, and f-components are retained, so normalized-string equality is not the RFC 8141 URN-equivalence procedure. Namespace-specific equivalence and URN resolution are outside this package's scope. URI/IRI transformation and registered-name mapping options do not alter authority-free, ASCII-only URNs.
 
-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.
+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 the DNS-host 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.
 
@@ -319,27 +280,27 @@ console.log(isUUIDv4('123e4567-e89b-42d3-9456-426614174000')); // true
 
 The parser builds its validation logic from declarative RFC grammar fragments:
 
-1. Select the applicable generic or scheme-specific URI/IRI syntax.
-2. Recursively expand grammar references through `url-templates`.
-3. Add named captures for the components exposed by the selected syntax.
+1. Select the generic, DNS-host, empty-file-host, or URN grammar profile.
+2. Merge and recursively expand grammar references through `url-templates`.
+3. Add named captures for the public components exposed by parsing.
 4. Compile the complete expression with Unicode support.
-5. Cache expressions by operation, grammar rule, and scheme class.
+5. Cache expressions by operation, grammar rule, and grammar profile.
 6. Validate with `RegExp.test()` or parse with `RegExp.exec()`.
-7. Resolve references by component inheritance, path merging, dot-segment removal, and definedness-preserving recomposition.
+7. Resolve references by component inheritance, path merging, dot-segment removal, and component recomposition.
 
 <details>
 <summary><strong>Lazy compilation and cache behavior</strong></summary>
 
-Parsing and validation use separate cached expressions because parsing requires named groups and validation does not. Generic and scheme-specific identifiers also use separate entries.
+Parsing and validation use separate cached expressions because parsing requires named groups and validation does not. Each grammar profile also uses separate entries.
 
-The first call for an operation/rule/policy combination includes recursive grammar expansion and regular-expression compilation. Later calls reuse the cached expression and are considerably faster. No regular expressions are generated during package import.
+The first call for an operation, grammar rule, and grammar profile includes recursive grammar expansion and regular-expression compilation. Later calls reuse the cached expression and are considerably faster. No regular expressions are generated during package import.
 
 </details>
 
 <details>
-<summary><strong>Scheme-specific hostname policy</strong></summary>
+<summary><strong>DNS-host grammar profile</strong></summary>
 
-The following schemes trigger DNS-style ASCII or Unicode label rules instead of the fully generic `reg-name` grammar:
+The following schemes trigger DNS-style ASCII or Unicode label rules instead of the generic `reg-name` grammar:
 
 - `http`
 - `https`
@@ -347,9 +308,46 @@ 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; URNs instead follow RFC 8141 namestring 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.
+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.
+
+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 the DNS-host grammar again.
+
+</details>
+
+<details>
+<summary><strong>URN grammar profile</strong></summary>
+
+URNs use the existing URI and IRI operations because a URN is a URI under the `urn` scheme. Values with a case-insensitive `urn:` prefix select the closed RFC 8141 grammar profile; no separate `isUrn` or `parseUrn` API is exported.
+
+```text
+urn:NID:NSS[?+r-component][?=q-component][#f-component]
+```
+
+The NID contains 2–32 ASCII characters, starts and ends with a letter or digit, and permits letters, digits, or hyphens internally. The NSS begins with an RFC 3986 `pchar` and then permits `pchar` or `/`. The ordered r- and q-components also begin with `pchar` and then permit `pchar`, `/`, or `?`, while an f-component can be empty. The first `?=` sequence after an r-component starts the q-component, and any other question mark outside an optional component is rejected.
 
-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.
+```js
+const { isUri, isIri, parseUri } = require('identifier-js');
+
+const value = 'URN:Example:a%2f/../B?+service?x?=key=value#part';
+console.log(isUri(value)); // true
+console.log(isIri(value)); // true
+
+const parsed = parseUri(value);
+console.log(parsed.scheme);     // URN
+console.log(parsed.nid);        // Example
+console.log(parsed.nss);        // a%2f/../B
+console.log(parsed.rComponent); // service?x
+console.log(parsed.qComponent); // key=value
+console.log(parsed.fComponent); // part
+console.log(parsed.normalize());
+// urn:example:a%2F/../B?+service?x?=key=value#part
+```
+
+URN parse results expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent`. They do not expose generic `authority`, `userinfo`, `host`, `port`, `path`, `query`, or `fragment` fields. To require a URN after parsing a value accepted as a general URI, check `parsed.scheme.toLowerCase() === 'urn'`.
+
+URNs remain ASCII even through the IRI operations. Callers representing non-ASCII names must first encode them as UTF-8 and then percent-encode the resulting octets; lexical validation does not decode or verify those octet sequences.
+
+Validation is deliberately lexical and namespace-independent. Success does not prove that an NID is registered or otherwise legitimate, that an NSS obeys a namespace's additional syntax and canonicalization rules, or that the name was legitimately assigned.
 
 </details>
 
@@ -463,9 +461,9 @@ RFC 9562 lists database keys, filenames, system identifiers, and transaction ide
 <details>
 <summary><strong>Validation and parsing</strong></summary>
 
-- Generic URI syntax follows RFC 3986 character and component grammar; HTTP, WebSocket, and `file` schemes apply the documented hostname restrictions.
-- Generic IRI syntax follows the RFC 3987 Unicode extensions to URI grammar; HTTP, WebSocket, and `file` schemes apply the documented hostname restrictions.
-- Values with the case-insensitive `urn` scheme follow RFC 8141 namestring syntax and expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` fields through the URI and IRI parsers.
+- The generic URI grammar profile follows RFC 3986 character and component syntax; HTTP, WebSocket, and `file` schemes select the documented DNS-host rules.
+- The generic IRI grammar profile follows the RFC 3987 Unicode extensions to URI syntax; HTTP, WebSocket, and `file` schemes select the documented DNS-host rules.
+- Values with the case-insensitive `urn` scheme select the closed RFC 8141 grammar profile and expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` fields through the URI and IRI parsers.
 - URN validation establishes generic lexical syntax only, not namespace registration, namespace-specific syntax, assignment, resolution, or equivalence.
 - 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.
@@ -523,7 +521,7 @@ Run `gh workspace-data load` again to refresh materialized data after public-dat
 
 ### Tests
 
-The active suite contains 3,157 tests covering URI/IRI validation and parsing, RFC 8141 URN syntax and normalization, 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.
+The active suite contains 3,157 tests covering URI/IRI validation and parsing, RFC 8141 URN syntax and normalization, generic normalization, bidirectional URI/IRI representation transformation, DNS-host grammar, 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>