identifier-js 0.2.0 → 0.4.0

package/index.d.ts

@@ -31,25 +31,32 @@ 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;
-/** @throws {Error} If the base or the reference is invalid. */
+/** Resolve with generic RFC 3986 semantics; this does not invoke a URN resolution service.
+ * @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;
-/** @throws {Error} If the base or the reference is invalid. */
+/** Derive a generic URI reference without scheme-specific relative-URN semantics.
+ * @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. */
 export type RegNameMapper = (regName: string) => string;
 
-/** Select optional URI output and registered-name mapping for parsed-result normalization. */
+/** Select a target representation after parsed-result normalization. */
+export type NormalizeTransform = 'URI' | 'IRI';
+
+/** Select optional representation transformation and registered-name mapping. */
 export type NormalizeOptions = {
-    toUri?: boolean;
+    transform?: NormalizeTransform;
     mapRegName?: RegNameMapper;
 };
 
-/** Provide lazy RFC normalization and optional IRI-to-URI output on a parsed result. */
+/** Provide lazy RFC normalization and optional URI/IRI transformation on a parsed result. */
 export type NormalizableReference = {
     normalize(options?: NormalizeOptions): string;
 };
@@ -87,6 +94,18 @@ export type AbsoluteIdentifierComponents = {
     query?: string;
 };
 
-export type ParsedIdentifierComponents = IdentifierComponents & NormalizableReference;
-export type ParsedRelativeIdentifierComponents = RelativeIdentifierComponents & NormalizableReference;
-export type ParsedAbsoluteIdentifierComponents = AbsoluteIdentifierComponents & NormalizableReference;
+// 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;
+};
+
+type AbsoluteUrnIdentifierComponents = Omit<UrnIdentifierComponents, 'fragment'>;
+
+export type ParsedIdentifierComponents = (IdentifierComponents | UrnIdentifierComponents) & NormalizableReference;
+export type ParsedRelativeIdentifierComponents = (RelativeIdentifierComponents | UrnIdentifierComponents) & NormalizableReference;
+export type ParsedAbsoluteIdentifierComponents = (AbsoluteIdentifierComponents | AbsoluteUrnIdentifierComponents) & NormalizableReference;

package/index.js

@@ -1,9 +1,9 @@
 'use strict';
-// Parse, validate, normalize, resolve, and convert RFC 3986 URI and RFC 3987 IRI references.
-// a valid URI is always a valid IRI
+// 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])';
+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 commonRules = {
     implemented_schemes,
@@ -79,6 +79,31 @@ 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.
+const urnRules = {
+    scheme: implemented_schemes,
+    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}|/)*',
+    rq_components: '(?:[?][+]{r_component})?(?:[?]={q_component})?',
+    r_component: '{pchar}(?:{pchar}|/|[?](?!=))*',
+    q_component: '{pchar}(?:{pchar}|/|[?])*',
+    f_component: '{fragment}',
+};
+// Reuse the grammar repertoires when selecting URI octets safe for IRI output.
+const uriUnreservedPattern = new RegExp(`^${commonRules.unreserved}$`);
+const iriUcscharPattern = new RegExp(`^${iriRules.ucschar}$`, 'u');
+const iriPrivatePattern = new RegExp(`^${iriRules.iprivate}$`, 'u');
+// Apply the additional RFC 3987 Section 4.1 prose restriction outside the ABNF repertoire.
+const forbiddenIriFormattingPattern = /^[\u200E\u200F\u202A-\u202E]$/u;
 // scheme specific URI reg_name and IRI ireg_name
 const schemeSpecificRules = {
     scheme: implemented_schemes,
@@ -119,11 +144,16 @@ const groupNames = {
     ipath_noscheme: 'path',
     ipath_rootless: 'path',
     ipath_empty: 'path',
+    NID: 'nid',
+    NSS: 'nss',
+    r_component: 'rComponent',
+    q_component: 'qComponent',
 };
-// Select and merge generic, DNS-host, or empty-file-host grammar overrides.
+// Detect schemes for which the package implements grammar beyond generic URI/IRI syntax.
 const isSpecificScheme = (string) => new RegExp('^' + implemented_schemes + ':').test(string);
-const schemeProfile = (string) => (string.slice(0, 8).toLowerCase() === 'file:///' ? 'f' : isSpecificScheme(string) ? 's' : '');
-const rules = (profile) => Object.assign({}, commonRules, uriRules, iriRules, profile === 'f' ? emptyFileHostRules : profile ? schemeSpecificRules : {});
+// 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)
 const parse = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
@@ -321,6 +351,10 @@ function isIPv4Address(host) {
     }
     return true;
 }
+// Identify ASCII octets through the URI grammar's canonical unreserved repertoire.
+function isAsciiUnreservedOctet(octet) {
+    return uriUnreservedPattern.test(String.fromCharCode(octet));
+}
 // Normalize percent triplets while optionally decoding only ASCII unreserved octets.
 function normalizePercentEncoding(value, decodeUnreserved = true) {
     let result = '';
@@ -332,8 +366,7 @@ function normalizePercentEncoding(value, decodeUnreserved = true) {
         }
         const hexadecimal = value.slice(index + 1, index + 3);
         const octet = Number.parseInt(hexadecimal, 16);
-        const unreserved = (octet >= 0x41 && octet <= 0x5A) || (octet >= 0x61 && octet <= 0x7A) || (octet >= 0x30 && octet <= 0x39) || octet === 0x2D || octet === 0x2E || octet === 0x5F || octet === 0x7E;
-        result += decodeUnreserved && unreserved ? String.fromCharCode(octet) : `%${hexadecimal.toUpperCase()}`;
+        result += decodeUnreserved && isAsciiUnreservedOctet(octet) ? String.fromCharCode(octet) : `%${hexadecimal.toUpperCase()}`;
         index += 2;
     }
     return result;
@@ -459,6 +492,52 @@ function encodeIriComponent(component) {
     // Process complete code points so supplementary characters produce one UTF-8 sequence.
     return component.replace(/[^\x00-\x7F]/gu, (character) => encodeURIComponent(character).toUpperCase());
 }
+// Decode the maximal RFC 3987 URI octet repertoire allowed by one IRI component.
+function decodeUriComponentToIri(component, allowPrivate = false) {
+    let result = '';
+    // Inspect each normalized percent triplet as either ASCII or the lead of one strict UTF-8 scalar.
+    for (let index = 0; index < component.length; index++) {
+        if (component[index] !== '%' || !/^[0-9A-F]{2}$/.test(component.slice(index + 1, index + 3))) {
+            result += component[index];
+            continue;
+        }
+        const hexadecimal = component.slice(index + 1, index + 3);
+        const octet = Number.parseInt(hexadecimal, 16);
+        if (octet <= 0x7F) {
+            result += isAsciiUnreservedOctet(octet) ? String.fromCharCode(octet) : `%${hexadecimal}`;
+            index += 2;
+            continue;
+        }
+        const sequenceLength = octet >= 0xC2 && octet <= 0xDF ? 2 : octet >= 0xE0 && octet <= 0xEF ? 3 : octet >= 0xF0 && octet <= 0xF4 ? 4 : 0;
+        let encoded = '';
+        // Collect exactly one candidate scalar without consuming malformed trailing input.
+        for (let sequenceIndex = 0; sequenceIndex < sequenceLength; sequenceIndex++) {
+            const position = index + sequenceIndex * 3;
+            if (component[position] !== '%' || !/^[0-9A-F]{2}$/.test(component.slice(position + 1, position + 3))) {
+                encoded = '';
+                break;
+            }
+            encoded += component.slice(position, position + 3);
+        }
+        let character;
+        if (encoded) {
+            try {
+                character = decodeURIComponent(encoded);
+            } catch {
+                character = undefined;
+            }
+        }
+        const allowed = character !== undefined && !forbiddenIriFormattingPattern.test(character) && (iriUcscharPattern.test(character) || (allowPrivate && iriPrivatePattern.test(character)));
+        if (allowed) {
+            result += character;
+            index += encoded.length - 1;
+        } else {
+            result += `%${hexadecimal}`;
+            index += 2;
+        }
+    }
+    return result;
+}
 // Rebuild authority from normalized values while preserving other empty component delimiters.
 function normalizeAuthority(parts, scheme, mapRegName) {
     if (parts.authority === undefined) return undefined;
@@ -475,9 +554,16 @@ function normalizeAuthority(parts, scheme, mapRegName) {
 function normalizeParsedReference(parts, options = {}) {
     // Validate the optional API settings before they select normalization behavior.
     if (options === null || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Invalid normalization argument type: must be an options object.');
-    const { toUri = false, mapRegName } = options;
-    if (typeof toUri !== 'boolean') throw new TypeError('Invalid toUri option type: must be a boolean.');
+    const { transform, mapRegName } = options;
+    if (transform !== undefined && transform !== 'URI' && transform !== 'IRI') throw new TypeError('Invalid transform option: must be "URI" or "IRI".');
     if (mapRegName !== undefined && typeof mapRegName !== 'function') throw new TypeError('Invalid registered-name mapper type: must be a function.');
+    // Normalize captured URN fields without applying generic path or representation processing.
+    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) });
+    }
     // Normalize each component independently so encoded delimiters cannot become structure.
     const scheme = parts.scheme === undefined ? undefined : parts.scheme.toLowerCase();
     const normalized = {
@@ -496,12 +582,20 @@ function normalizeParsedReference(parts, options = {}) {
         // Preserve a no-authority path when reduction would reparse it as an authority.
         if (normalized.authority !== undefined || !reducedPath.startsWith('//')) normalized.path = reducedPath;
     }
-    if (!toUri) return compose(normalized);
-    // 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);
+    // Select an explicit target representation only after syntax and scheme normalization is complete.
+    if (transform === 'URI') {
+        // Map every non-ASCII authority, path, query, and fragment scalar under RFC 3987 URI output.
+        if (normalized.authority !== undefined) normalized.authority = encodeIriComponent(normalized.authority);
+        normalized.path = encodeIriComponent(normalized.path);
+        if (normalized.query !== undefined) normalized.query = encodeIriComponent(normalized.query);
+        if (normalized.fragment !== undefined) normalized.fragment = encodeIriComponent(normalized.fragment);
+    } else if (transform === 'IRI') {
+        // Decode valid UTF-8 percent sequences only where the destination component permits their scalar.
+        if (normalized.authority !== undefined) normalized.authority = decodeUriComponentToIri(normalized.authority);
+        normalized.path = decodeUriComponentToIri(normalized.path);
+        if (normalized.query !== undefined) normalized.query = decodeUriComponentToIri(normalized.query, true);
+        if (normalized.fragment !== undefined) normalized.fragment = decodeUriComponentToIri(normalized.fragment);
+    }
     return compose(normalized);
 }
 // export

package/normalization.md

@@ -1,14 +1,16 @@
 # URI and IRI normalization
 
-Parsed URI and IRI results expose `normalize()` for syntax-based normalization, the implemented HTTP, HTTPS, WS, and WSS scheme rules, and optional RFC 3987 IRI-to-URI output. The method returns a string and leaves the parsed components unchanged.
+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.
 
 ## API
 
 ```ts
 type RegNameMapper = (regName: string) => string
 
+type NormalizeTransform = 'URI' | 'IRI'
+
 type NormalizeOptions = {
-    toUri?: boolean
+    transform?: NormalizeTransform
     mapRegName?: RegNameMapper
 }
 
@@ -47,14 +49,39 @@ parsed.path;
 | Behavior | Implementation | Source |
 | --- | --- | --- |
 | Case normalization | Lowercase the scheme and an ASCII-only host. Uppercase hexadecimal letters in percent triplets. | [RFC 3986 §6.2.2.1](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.1), [RFC 3987 §5.3.2.1](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.1) |
-| Percent-encoded unreserved characters | Decode percent triplets representing ASCII letters, digits, `-`, `.`, `_`, or `~`. Retain percent encoding for reserved octets. | [RFC 3986 §§2.2–2.4 and 6.2.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-6.2.2.2), [RFC 3987 §5.3.2.3](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.3) |
-| Path segments | Apply the RFC dot-segment algorithm where the parsed reference can be normalized independently. Preserve unresolved rootless-relative path semantics. | [RFC 3986 §§5.2.4 and 6.2.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-5.2.4), [RFC 3987 §5.3.2.4](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.4) |
+| 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) |
 | 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 `toUri: true`, 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) |
+| IRI-to-URI output | With `transform: 'URI'`, encode non-ASCII authority, path, query, and fragment characters as uppercase UTF-8 percent triplets. | [RFC 3987 §3.1](https://www.rfc-editor.org/rfc/rfc3987#section-3.1) |
+| URI-to-IRI output | With `transform: 'IRI'`, decode percent-encoded ASCII unreserved characters and strictly legal UTF-8 sequences permitted in each destination component. Retain reserved, malformed, disallowed, and non-UTF-8 octets. | [RFC 3987 §3.2](https://www.rfc-editor.org/rfc/rfc3987#section-3.2) |
 
 Without a mapper, normalization retains the parser's host classification as an IP literal, IPv4 address, or registered name. IPvFuture literals use generic host case normalization. Existing non-ASCII IRI host text is retained unless the registered-name mapper supplies another value.
 
+## URNs
+
+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
 
 For `http` and `https`, normalization applies the generic rules and these scheme rules:
@@ -91,7 +118,7 @@ wss://example.com:00443/chat         → wss://example.com/chat
 ws://example.com?channel=updates     → ws://example.com/?channel=updates
 ```
 
-## Registered-name mapping and URI output
+## 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.
 
@@ -108,18 +135,27 @@ mapped;
 
 The example deliberately produces text that is not a valid URI or IRI; validating or selecting mapper output belongs to the application.
 
-With `toUri: true`, existing percent triplets remain encoded, and 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.
+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 } = require('identifier-js');
+const { parseIri, parseUri } = require('identifier-js');
 
-parseIri('x:/café?q=資料#résultat').normalize({ toUri: true });
+parseIri('x:/café?q=資料#résultat').normalize({ transform: 'URI' });
 // x:/caf%C3%A9?q=%E8%B3%87%E6%96%99#r%C3%A9sultat
+
+parseUri('x:/caf%C3%A9?q=%E8%B3%87%E6%96%99#r%C3%A9sultat').normalize({ transform: 'IRI' });
+// x:/café?q=資料#résultat
 ```
 
+With `transform: 'IRI'`, conversion uses UTF-8 exclusively and decodes as many eligible percent-encoded characters as possible. Encoded reserved characters, `%25`, malformed or incomplete UTF-8, legacy character encodings, Unicode outside the RFC 3987 component repertoire, and forbidden bidirectional formatting characters remain percent encoded. Private-use characters are decoded only in the query component. The hexadecimal letters of retained triplets are uppercase.
+
+The IRI transformation decodes percent-encoded ASCII unreserved characters even when this changes a registered name into IPv4-looking text. Without an explicit transformation, normalization preserves that registered-name host classification.
+
+ACE-to-Unicode and Unicode-to-ACE registered-name conversion remain application policy. `mapRegName` runs before the selected representation transformation, so applications can provide the appropriate mapping in either direction.
+
 ## Verification
 
-The normalization suite covers URI and IRI parser results, component presence, percent triplets, dot segments, host kinds, RFC 5952 output, HTTP and WebSocket scheme rules, registered-name mapping, IRI-to-URI output, component non-mutation, and idempotence.
+The normalization suite covers URI and IRI parser results, component presence, percent triplets, dot segments, host kinds, RFC 5952 output, HTTP and WebSocket scheme rules, registered-name mapping, both RFC representation transformations, malformed UTF-8 retention, component-specific Unicode repertoires, component non-mutation, round trips, and idempotence.
 
 ```sh
 npm test
@@ -129,6 +165,7 @@ npm test
 
 - [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
 - [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
+- [RFC 8141 — Uniform Resource Names](https://www.rfc-editor.org/rfc/rfc8141)
 - [RFC 5952 — A Recommendation for IPv6 Address Text Representation](https://www.rfc-editor.org/rfc/rfc5952)
 - [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
 - [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "identifier-js",
-  "version": "0.2.0",
-  "description": "A fast URI/IRI parser, validator, normalizer, resolver, and composer based on RFC 3986 and RFC 3987.",
+  "version": "0.4.0",
+  "description": "A fast RFC 3986/3987 URI/IRI parser, validator, normalizer, resolver, and composer with RFC 8141 URN syntax support.",
   "keywords": [
     "IRI",
     "URI",
     "IRI-reference",
     "URI-reference",
+    "URN",
     "ipv4",
     "ipv6",
     "uuid",
     "parser",
     "validator",
     "RFC3986",
-    "RFC3987"
+    "RFC3987",
+    "RFC8141"
   ],
   "homepage": "https://github.com/SorinGFS/identifier-js#readme",
   "bugs": {

package/readme.md

@@ -2,17 +2,17 @@
 
 title: Identifier JS
 
-description: An RFC 3986 and RFC 3987 parser, validator, normalizer, and reference resolver for Node.js and browser bundles.
+description: RFC 3986/3987 URI and IRI tools with scheme-specific RFC 8141 URN syntax 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). 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 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:
 
-- URI and IRI validation;
-- parsed identifier components;
-- conservative syntax normalization, recognized-scheme port/path forms, and a registered-name extension point;
+- 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;
 - RFC 3986 reference resolution and dot-segment removal;
 - relative-reference generation with resolution round-trip guarantees for supported forms;
 - UUID and UUIDv4 lexical validation;
@@ -143,6 +143,45 @@ 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.
@@ -173,6 +212,8 @@ 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.
+
 </details>
 
 ### Produce absolute and relative forms
@@ -201,6 +242,8 @@ 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.
+
 </details>
 
 ### Normalize parsed URI and IRI references
@@ -213,8 +256,10 @@ Every URI and IRI parse result provides an optional, non-enumerable `normalize()
 ```ts
 type RegNameMapper = (regName: string) => string
 
+type NormalizeTransform = 'URI' | 'IRI'
+
 type NormalizeOptions = {
-    toUri?: boolean
+    transform?: NormalizeTransform
     mapRegName?: RegNameMapper
 }
 
@@ -237,9 +282,11 @@ The method is available from `parseUri`, `parseUriReference`, `parseAbsoluteUri`
 
 Normalization implements RFC 3986 and RFC 3987 syntax normalization for scheme and host case, percent triplets, ASCII unreserved characters, path dot segments, and component recomposition. IPv6 literals use RFC 5952 text. HTTP(S) default ports and empty paths follow RFC 9110; WS(S) defaults and resource-name paths follow RFC 6455.
 
+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.
 
-With `toUri: true`, non-ASCII userinfo, mapper output, path, query, and fragment text becomes uppercase UTF-8 percent triplets under RFC 3987 §3.1. A mapper can supply an ASCII hostname when its consuming scheme requires one; this package does not enforce that requirement or validate the complete normalized result.
+With `transform: 'URI'`, non-ASCII userinfo, mapper output, path, query, and fragment text becomes uppercase UTF-8 percent triplets under RFC 3987 §3.1. With `transform: 'IRI'`, eligible percent-encoded ASCII unreserved characters and strictly legal UTF-8 sequences become IRI characters under RFC 3987 §3.2; reserved, malformed, disallowed, and non-UTF-8 octets remain encoded. Private-use characters are decoded only in queries, and forbidden bidirectional formatting characters remain encoded. A mapper can supply the desired Unicode or ASCII hostname representation; this package does not enforce that policy or validate the complete normalized result.
 
 See [`normalization.md`](normalization.md) for the exact RFC section mapping and examples.
 
@@ -272,11 +319,11 @@ console.log(isUUIDv4('123e4567-e89b-42d3-9456-426614174000')); // true
 
 The parser builds its validation logic from declarative RFC grammar fragments:
 
-1. Select generic URI/IRI rules or the package's scheme-specific hostname policy.
+1. Select the applicable generic or scheme-specific URI/IRI syntax.
 2. Recursively expand grammar references through `url-templates`.
-3. Add named capture groups when parsing is requested.
+3. Add named captures for the components exposed by the selected syntax.
 4. Compile the complete expression with Unicode support.
-5. Cache the expression by operation, grammar rule, and scheme-policy class.
+5. Cache expressions by operation, grammar rule, and scheme class.
 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.
 
@@ -300,7 +347,7 @@ 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. 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; 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.
 
 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.
 
@@ -416,8 +463,10 @@ 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; recognized schemes select the documented hostname profile.
-- Generic IRI syntax follows the RFC 3987 Unicode extensions to URI grammar; recognized schemes select the documented hostname profile.
+- 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.
+- 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.
 - Port syntax follows RFC 3986 `port = *DIGIT`, including empty and leading-zero values.
@@ -433,7 +482,8 @@ RFC 9562 lists database keys, filenames, system identifiers, and transaction ide
 - `strict = false` implements RFC 3986 §5.2.2 backward-compatible same-scheme handling.
 - `toAbsoluteReference` removes the fragment from an identifier containing a scheme.
 - `toRelativeReference` generates a reference whose RFC resolution equals the target resolution for supported forms.
-- `normalize()` implements the applicable case, percent-encoding, and path-segment rules from RFC 3986 §§6.2.2.1–6.2.2.3 and RFC 3987 §§5.3.2.1, 5.3.2.3–5.3.2.4, RFC 3987 §3.1 IRI-to-URI output, RFC 5952 IPv6 text, RFC 9110 HTTP(S) port/path forms, and RFC 6455 WS(S) port/resource-name 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.
 
 </details>
 
@@ -473,7 +523,7 @@ Run `gh workspace-data load` again to refresh materialized data after public-dat
 
 ### Tests
 
-The active suite contains 3,130 tests covering URI/IRI validation, parsing, generic normalization, 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, scheme-specific hosts, IPv4, IPv6, IPvFuture, ports, UUIDs, RFC 3986 resolution examples, empty components, absolute conversion, and relative-reference round trips, including 2,646 generated combinations of target/base paths, query-presence states, and target-fragment states across equivalent URI and IRI families.
 
 <details>
 <summary><strong>Test details</strong></summary>
@@ -493,7 +543,7 @@ The suite uses the `node:test` module built into Node.js and requires no separat
 
 ### Benchmarks
 
-The materialized benchmark suite provides portable, version-aware measurements for every exported function plus isolated package loading, reporting initial-call behavior, warmed latency statistics, integer throughput, workload counts, representative inputs, and environment metadata.
+The 26-scenario materialized benchmark suite provides portable, version-aware measurements for every exported function, isolated package loading, and RFC 8141 URN validation, parsing, and normalization. It reports initial-call behavior, warmed latency statistics, integer throughput, workload counts, representative inputs, and environment metadata.
 
 <details>
 <summary><strong>Benchmark details</strong></summary>
@@ -524,6 +574,7 @@ The generic coordinator delegates version-layer selection and ordered concern di
 
 - [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
 - [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
+- [RFC 8141 — Uniform Resource Names](https://www.rfc-editor.org/rfc/rfc8141)
 - [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
 - [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
 - [RFC 8089 — The `file` URI Scheme](https://www.rfc-editor.org/rfc/rfc8089)