identifier-js 0.2.0 → 0.3.0

package/index.d.ts

@@ -43,13 +43,16 @@ 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;
 };

package/index.js

@@ -79,6 +79,12 @@ const iriRules = {
     iprivate: '[\\uE000-\\uF8FF\\u{F0000}-\\u{FFFFD}\\u{100000}-\\u{10FFFD}]',
     ucschar: '[\\xA0-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFEF\\u{10000}-\\u{1FFFD}\\u{20000}-\\u{2FFFD}\\u{30000}-\\u{3FFFD}\\u{40000}-\\u{4FFFD}\\u{50000}-\\u{5FFFD}\\u{60000}-\\u{6FFFD}\\u{70000}-\\u{7FFFD}\\u{80000}-\\u{8FFFD}\\u{90000}-\\u{9FFFD}\\u{A0000}-\\u{AFFFD}\\u{B0000}-\\u{BFFFD}\\u{C0000}-\\u{CFFFD}\\u{D0000}-\\u{DFFFD}\\u{E1000}-\\u{EFFFD}]',
 };
+// Reuse the grammar repertoires when selecting URI octets safe for IRI output.
+const uriUnreservedPattern = new RegExp(`^${commonRules.unreserved}$`);
+const iriUcscharPattern = new RegExp(`^${iriRules.ucschar}$`, 'u');
+const iriPrivatePattern = new RegExp(`^${iriRules.iprivate}$`, 'u');
+// Apply the additional RFC 3987 Section 4.1 prose restriction outside the ABNF repertoire.
+const forbiddenIriFormattingPattern = /^[\u200E\u200F\u202A-\u202E]$/u;
 // scheme specific URI reg_name and IRI ireg_name
 const schemeSpecificRules = {
     scheme: implemented_schemes,
@@ -321,6 +327,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 +342,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 +468,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,8 +530,8 @@ 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 each component independently so encoded delimiters cannot become structure.
     const scheme = parts.scheme === undefined ? undefined : parts.scheme.toLowerCase();
@@ -496,12 +551,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, and WSS scheme rules, and optional RFC 3987 URI/IRI representation transformation. The method returns a string and leaves the parsed components unchanged.
 
 ## API
 
 ```ts
 type RegNameMapper = (regName: string) => string
 
+type NormalizeTransform = 'URI' | 'IRI'
+
 type NormalizeOptions = {
-    toUri?: boolean
+    transform?: NormalizeTransform
     mapRegName?: RegNameMapper
 }
 
@@ -51,7 +53,8 @@ parsed.path;
 | Path segments | Apply the RFC dot-segment algorithm where the parsed reference can be normalized independently. Preserve unresolved rootless-relative path semantics. | [RFC 3986 §§5.2.4 and 6.2.2.3](https://www.rfc-editor.org/rfc/rfc3986#section-5.2.4), [RFC 3987 §5.3.2.4](https://www.rfc-editor.org/rfc/rfc3987#section-5.3.2.4) |
 | Component recomposition | Emit authority, query, and fragment delimiters from component presence, including present-empty components. | [RFC 3986 §5.3](https://www.rfc-editor.org/rfc/rfc3986#section-5.3) |
 | IPv6 text | Suppress leading zeroes, compress the longest zero run with first-run tie breaking, and use lowercase hexadecimal. Known embedded-IPv4 forms use mixed notation. | [RFC 5952 §§4–5](https://www.rfc-editor.org/rfc/rfc5952#section-4) |
-| IRI-to-URI output | With `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.
 
@@ -91,7 +94,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 +111,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "identifier-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A fast URI/IRI parser, validator, normalizer, resolver, and composer based on RFC 3986 and RFC 3987.",
   "keywords": [
     "IRI",

package/readme.md

@@ -213,8 +213,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
 }
 
@@ -239,7 +241,7 @@ Normalization implements RFC 3986 and RFC 3987 syntax normalization for scheme a
 
 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.
 
@@ -433,7 +435,7 @@ 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, and RFC 6455 WS(S) port/resource-name forms.
 
 </details>
 
@@ -473,7 +475,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,137 tests covering URI/IRI validation, parsing, generic normalization, bidirectional URI/IRI representation transformation, scheme-specific hosts, IPv4, IPv6, IPvFuture, ports, UUIDs, RFC 3986 resolution examples, empty components, absolute conversion, and relative-reference round trips, including 2,646 generated combinations of target/base paths, query-presence states, and target-fragment states across equivalent URI and IRI families.
 
 <details>
 <summary><strong>Test details</strong></summary>