identifier-js 0.4.0 → 0.4.2

package/index.d.ts

@@ -31,17 +31,13 @@ export const parseIri: (iri: string) => ParsedIdentifierComponents;
 export const parseIriReference: (iriReference: string) => ParsedRelativeIdentifierComponents;
 /** @throws {Error} If the absolute-IRI is invalid. */
 export const parseAbsoluteIri: (iri: string) => ParsedAbsoluteIdentifierComponents;
-/** Resolve with generic RFC 3986 semantics; this does not invoke a URN resolution service.
- * @throws {Error} If the base or the reference is invalid.
- */
+/** @throws {Error} If the base or the reference is invalid. */
 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;
-/** Derive a generic URI reference without scheme-specific relative-URN semantics.
- * @throws {Error} If the base or the reference is invalid.
- */
+/** @throws {Error} If the base or the reference is invalid. */
 export const toRelativeReference: (target: string, base: string) => string;
 
 /** Map a parsed non-empty registered-name host to caller-owned text. */
@@ -94,17 +90,16 @@ export type AbsoluteIdentifierComponents = {
     query?: string;
 };
 
-// Describe the scheme-specific captures returned by each complete or fragment-free URN grammar.
 type UrnIdentifierComponents = {
     scheme: string;
     nid: string;
     nss: string;
     rComponent?: string;
     qComponent?: string;
-    fragment?: string;
+    fComponent?: string;
 };
 
-type AbsoluteUrnIdentifierComponents = Omit<UrnIdentifierComponents, 'fragment'>;
+type AbsoluteUrnIdentifierComponents = Omit<UrnIdentifierComponents, 'fComponent'>;
 
 export type ParsedIdentifierComponents = (IdentifierComponents | UrnIdentifierComponents) & NormalizableReference;
 export type ParsedRelativeIdentifierComponents = (RelativeIdentifierComponents | UrnIdentifierComponents) & NormalizableReference;

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]|[uU][rR][nN])';
-// 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,9 +79,9 @@ 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: implemented_schemes,
+    scheme: '[uU][rR][nN]',
     URI_reference: '{URI}',
     URI: '{namestring}',
     absolute_URI: '{assigned_name}(?:{rq_components})?',
@@ -92,21 +92,21 @@ const urnRules = {
     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}))*)',
@@ -115,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,20 +148,23 @@ const groupNames = {
     NSS: 'nss',
     r_component: 'rComponent',
     q_component: 'qComponent',
+    f_component: 'fComponent',
 };
-// 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);
-    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);
+    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.
@@ -173,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;
@@ -192,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 ?? '';
@@ -237,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');
@@ -287,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) => {
@@ -373,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);
     }
@@ -423,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(':');
@@ -435,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}`;
@@ -480,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++) {
@@ -509,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;
@@ -538,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);
@@ -561,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.fragment === undefined ? undefined : normalizePercentEncoding(parts.fragment, 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),
@@ -574,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 `fragment` 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,35 @@ 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');
+
+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 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({
@@ -155,7 +157,7 @@ ACE-to-Unicode and Unicode-to-ACE registered-name conversion remain application
 
 ## 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.0",
+  "version": "0.4.2",
   "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.fragment);   // part
-console.log(parsed.normalize());
-// urn:example:a%2F/../B?+service?x?=key=value#part
-```
-
-URN parse results expose `nid`, `nss`, `rComponent`, and `qComponent`, while the RFC-defined f-component is exposed as `fragment`. They do not expose generic `path` or `query` 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.
@@ -212,7 +173,7 @@ console.log(resolveReference('?page=2', 'https://example.com/items?page=1#curren
 
 Empty authorities, queries, and fragments are preserved during recomposition.
 
-This function performs generic RFC 3986 reference resolution only. It does not invoke a URN resolution service or implement scheme-specific URN resolution semantics.
+`resolveReference` does not apply when either input uses the `urn` scheme. URN resolution services are outside this package's scope.
 
 </details>
 
@@ -242,7 +203,7 @@ 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. 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.
 
-These conversion functions retain their generic URI-reference behavior. They do not construct, resolve, or interpret scheme-specific relative URNs.
+`toAbsoluteReference` and `toRelativeReference` do not apply when an input uses the `urn` scheme. Relative-URN semantics are outside this package's scope.
 
 </details>
 
@@ -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 this hostname policy again.
+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.
+
+```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, r-component, q-component, and fragment 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.
@@ -483,7 +481,7 @@ RFC 9562 lists database keys, filenames, system identifiers, and transaction ide
 - `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, RFC 6455 WS(S) port/resource-name forms, and RFC 8141 scheme/NID/percent-triplet normalization without NSS decoding or path reduction.
-- RFC 3986 reference resolution and relative-reference generation receive no URN-specific semantics; RFC 8141 URN resolution services and URN-equivalence APIs are not implemented.
+- Reference resolution and absolute/relative reference conversion do not apply to `urn` inputs; RFC 8141 URN resolution services and URN-equivalence APIs are not implemented.
 
 </details>
 
@@ -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>