identifier-js 0.0.13 → 0.0.14

package/index.js

@@ -140,10 +140,10 @@ const validate = (string, rule) => {
 function compose(parts = {}) {
     let result = '';
     if (parts.scheme) result += parts.scheme + ':';
-    if (parts.authority) result += '//' + parts.authority;
-    result += parts.path || '';
-    if (parts.query) result += '?' + parts.query;
-    if (parts.fragment) result += '#' + parts.fragment;
+    if (parts.authority !== undefined && parts.authority !== null) result += '//' + parts.authority;
+    result += parts.path ?? '';
+    if (parts.query !== undefined && parts.query !== null) result += '?' + parts.query;
+    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)
@@ -251,21 +251,40 @@ const toRelativeReference = (target, base) => {
     if (T.scheme !== B.scheme || T.authority !== B.authority) return target;
     let result;
     if (B.path === T.path) {
-        result = '';
+        if (T.query === undefined && B.query !== undefined) {
+            // Use an explicit path to prevent the base query from being inherited.
+            if (T.path.startsWith('/')) result = T.path;
+            else if (T.path) {
+                const segment = T.path.slice(T.path.lastIndexOf('/') + 1);
+                result = segment && !segment.includes(':') ? segment : `./${segment}`;
+            } else if (T.authority !== undefined) result = `//${T.authority}`;
+            else return target;
+        } else result = '';
+    } else if (!T.path) {
+        // A network-path reference is required to represent an empty path without inheritance.
+        if (T.authority !== undefined) result = `//${T.authority}`;
+        else return target;
     } else {
         const baseSegments = B.path.split('/');
         const targetSegments = T.path.split('/');
         let position = 0;
+        // Find the common path prefix before constructing the relative traversal.
         while (baseSegments[position] === targetSegments[position] && position < baseSegments.length - 1 && position < targetSegments.length - 1) {
             position++;
         }
         const segments = [];
+        // Backtrack from the base resource to the common path prefix.
         for (let index = position + 1; index < baseSegments.length; index++) segments.push('..');
+        // Append the target path after the common prefix.
         for (let index = position; index < targetSegments.length; index++) segments.push(targetSegments[index]);
         result = segments.join('/');
+        if (!result) result = T.path.startsWith('/') ? T.path : './';
+        else if (/^[^/]*:/.test(result)) result = './' + result;
     }
     if (T.query !== undefined) result += `?${T.query}`;
     if (T.fragment !== undefined) result += `#${T.fragment}`;
+    // Parent traversal would convert a rootless path into an absolute path during resolution.
+    if (T.authority === undefined && !T.path.startsWith('/') && result.startsWith('..')) return target;
     return result;
 };
 // export

package/normalization.md

@@ -0,0 +1,299 @@
+# Identifier normalization research notes
+
+These notes summarize the standards and design choices that should be resolved before implementing `normalizeReference`. They are research material, not the current API contract.
+
+## Central constraint
+
+There is no universal canonical form for every URI or IRI. RFC 3986 defines comparison in levels because a transformation that is safe for one scheme or application can merge distinct identifiers in another.
+
+A normalizer should minimize false negatives without creating false positives:
+
+1. **Simple comparison** — compare characters exactly.
+2. **Syntax-based normalization** — apply transformations licensed by generic URI syntax.
+3. **Scheme-based normalization** — apply additional equivalences defined by a scheme.
+4. **Protocol-based normalization** — use equivalences established by observed protocol behavior.
+
+`normalizeReference` should implement only an explicitly selected level. Protocol-derived normalization does not belong in a deterministic identifier library.
+
+Reference: [RFC 3986 §6](https://www.rfc-editor.org/rfc/rfc3986#section-6).
+
+## Generic syntax-based normalization
+
+The following transformations are suitable candidates for a generic URI profile.
+
+### Scheme and host case
+
+- Lowercase the scheme.
+- Lowercase the host.
+- Do not lowercase userinfo, path, query, or fragment.
+- Preserve Unicode component case unless a scheme or external policy defines equivalence.
+
+Example:
+
+```text
+HTTP://WWW.EXAMPLE.COM/ → http://www.example.com/
+```
+
+Reference: RFC 3986 §6.2.2.1.
+
+### Percent-triplet case
+
+Uppercase hexadecimal letters in every valid percent triplet:
+
+```text
+%3a → %3A
+%2f → %2F
+```
+
+This changes presentation, not the represented octet.
+
+Reference: RFC 3986 §§2.1 and 6.2.2.1.
+
+### Decode percent-encoded unreserved characters
+
+Decode a percent triplet only when it represents an ASCII unreserved character:
+
+```text
+ALPHA / DIGIT / "-" / "." / "_" / "~"
+```
+
+Examples:
+
+```text
+%63 → c
+%7E → ~
+```
+
+Do not generically decode reserved characters. `%2F` and `/`, for example, can have different structural meanings.
+
+Parse components before decoding so an encoded delimiter cannot be mistaken for syntax. Never decode the same data twice.
+
+References: RFC 3986 §§2.2–2.4 and 6.2.2.2.
+
+### Remove dot segments
+
+Apply the RFC 3986 §5.2.4 algorithm to the parsed path:
+
+```text
+/a/b/c/./../../g → /a/g
+```
+
+Only complete `.` and `..` path segments are special. Do not process similar text in a query or fragment:
+
+```text
+g?y/../x
+g#s/../x
+```
+
+References: RFC 3986 §§5.2.4 and 6.2.2.3.
+
+### Preserve component presence
+
+Recomposition must distinguish an absent component from a present but empty component:
+
+```text
+https://example.com/path
+https://example.com/path?
+https://example.com/path#
+```
+
+The same applies to an empty authority. Component delimiters must be emitted based on definedness, not truthiness.
+
+Reference: RFC 3986 §5.3.
+
+## Scheme-based profiles
+
+Scheme-specific transformations should not run unless the scheme profile is selected or automatic scheme handling is part of the documented contract.
+
+### HTTP and HTTPS
+
+RFC 9110 permits these normal forms:
+
+- lowercase scheme and host;
+- remove port `80` from `http`;
+- remove port `443` from `https`;
+- remove an explicitly empty port;
+- use `/` when authority is present and path is empty;
+- decode percent-encoded unreserved characters;
+- preserve all other component case.
+
+Examples:
+
+```text
+HTTP://Example.COM:80 → http://example.com/
+https://example.com:443/a → https://example.com/a
+```
+
+An HTTP request target does not include a fragment, but identifier normalization should not silently discard a fragment unless the selected operation specifically produces a request target.
+
+Userinfo in HTTP and HTTPS targets is deprecated and should be rejected or reported by an HTTP policy rather than silently normalized away.
+
+Reference: [RFC 9110 §§4.2.1–4.2.5](https://www.rfc-editor.org/rfc/rfc9110#section-4.2).
+
+### WS and WSS
+
+Potential scheme-specific rules include:
+
+- default port `80` for `ws`;
+- default port `443` for `wss`;
+- `/` as the resource path when the path is empty;
+- no fragment identifiers;
+- IDN-to-ASCII handling under an explicitly selected hostname policy.
+
+Fragment rejection is validation, not normalization. A normalizer should not repair a WebSocket URI by silently deleting its fragment.
+
+Reference: [RFC 6455 §3](https://www.rfc-editor.org/rfc/rfc6455#section-3).
+
+### File
+
+A generic `file` normalizer is not recommended. Behavior varies by platform and filesystem:
+
+- local empty authority versus `localhost`;
+- POSIX roots;
+- Windows drive-letter case and UNC paths;
+- path case sensitivity;
+- backslash handling;
+- platform-specific Unicode normalization;
+- reserved device names and namespace paths.
+
+Require an explicit platform profile before applying these transformations.
+
+Reference: [RFC 8089](https://www.rfc-editor.org/rfc/rfc8089).
+
+### Other schemes
+
+Apply only generic syntax normalization unless the scheme's authoritative specification defines additional equivalences. Do not infer default ports, path case rules, or authority behavior from a similar scheme.
+
+## IRI and Unicode decisions
+
+RFC 3987 recommends that creators produce IRIs in NFC, but comparison code must not arbitrarily normalize an existing Unicode IRI. Normalizing third-party text can merge identifiers that were intentionally distinct.
+
+Recommended policy:
+
+- do not apply Unicode normalization by default;
+- offer NFC only as an explicit creation or application-policy option;
+- do not offer NFKC as a generic identifier transformation;
+- retain the original IRI when a normalized form is generated only as a comparison key.
+
+### IRI-to-URI mapping is a separate operation
+
+Mapping an IRI to a URI is not merely normalization:
+
+1. encode non-ASCII `ucschar` and `iprivate` characters as UTF-8;
+2. percent-encode each UTF-8 octet as `%HH`;
+3. preserve existing valid percent triplets and URI-allowed characters;
+4. apply an explicit IDNA policy to internationalized hostnames when required.
+
+The reverse operation must decode only valid UTF-8 and must preserve encoded reserved characters. It must not guess legacy encodings.
+
+Reference: [RFC 3987 §§3 and 5](https://www.rfc-editor.org/rfc/rfc3987).
+
+## Transformations excluded by default
+
+A generic normalizer should not:
+
+- decode percent-encoded reserved characters;
+- lowercase userinfo, paths, queries, or fragments;
+- sort, deduplicate, or reinterpret query parameters;
+- remove empty query or fragment delimiters;
+- add or remove trailing slashes without scheme authority;
+- apply Unicode NFC or NFKC automatically;
+- convert an internationalized hostname without a defined IDNA version and policy;
+- remove userinfo rather than reporting it;
+- infer filesystem semantics for `file`;
+- infer equivalence from redirects or successful retrievals;
+- convert a relative reference without a supplied base.
+
+## Suggested API design
+
+Avoid a single aggressive operation. Two viable designs are:
+
+### Explicit profiles
+
+```js
+normalizeReference(reference, {
+    profile: 'generic', // generic | http | https | ws | wss
+    unicodeNormalization: false,
+});
+```
+
+A `file` profile should additionally require a platform policy.
+
+### Separate operations
+
+```js
+normalizeReference(reference);          // generic syntax only
+normalizeHttpReference(reference);      // HTTP/HTTPS scheme rules
+normalizeWebSocketReference(reference); // WS/WSS scheme rules
+iriToUri(reference, options);            // explicit representation mapping
+```
+
+Separate operations are harder to misuse and make compatibility changes more visible. A profile-based API is easier to extend. The final choice should follow the expected consumers.
+
+## Suggested generic processing order
+
+1. Parse and retain whether authority, query, and fragment are absent or empty.
+2. Lowercase scheme and host where generic syntax permits it.
+3. Normalize percent-triplet hexadecimal case.
+4. Decode percent-encoded ASCII unreserved characters component by component.
+5. Remove dot segments from the path.
+6. Apply an explicitly selected scheme profile.
+7. Apply Unicode normalization only when explicitly requested.
+8. Recompose while preserving empty components.
+9. Validate the normalized output under the same identifier and scheme policy.
+10. Optionally verify idempotence:
+
+```js
+normalizeReference(normalizeReference(value)) === normalizeReference(value)
+```
+
+## Acceptance scenarios
+
+A generic profile should include at least these cases:
+
+```text
+HTTP://Example.COM/%7euser       → http://example.com/~user
+http://example.com/a/./b/../c   → http://example.com/a/c
+http://example.com/path?        → http://example.com/path?
+http://example.com/path#        → http://example.com/path#
+http://example.com/%2F          → http://example.com/%2F
+```
+
+An HTTP profile can additionally include:
+
+```text
+http://example.com:80           → http://example.com/
+https://example.com:443/a       → https://example.com/a
+```
+
+Cases that must remain distinct under generic normalization include:
+
+```text
+http://example.com/a            ≠ http://example.com/a/
+http://example.com/path         ≠ http://example.com/path?
+http://example.com/%2F          ≠ http://example.com//
+http://example.com/A            ≠ http://example.com/a
+```
+
+Testing should cover URI and IRI forms, empty components, rootless paths, percent triplets, Unicode supplementary characters, idempotence, and normalization followed by parsing/recomposition.
+
+## Open decisions
+
+Before implementation, decide:
+
+1. Whether `normalizeReference` is generic-only or selects profiles automatically by scheme.
+2. Whether output preserves the input category: URI versus IRI.
+3. Whether relative references are normalized in place or require a base and become absolute.
+4. Whether Unicode NFC is offered, and for which creation contexts.
+5. Whether IDNA conversion belongs here or in a dedicated hostname dependency.
+6. Whether comparison keys and display/transport identifiers use separate APIs.
+7. Whether unsupported scheme profiles throw, fall back to generic rules, or require an explicit option.
+8. Whether current callers can rely on `normalizeReference` remaining an identity function until a major release.
+
+## Authoritative references
+
+- [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
+- [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
+- [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
+- [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
+- [RFC 8089 — The `file` URI Scheme](https://www.rfc-editor.org/rfc/rfc8089)

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "identifier-js",
-  "version": "0.0.13",
-  "description": "A RFC3986 / RFC3987 compliant fast parser/validator/resolver/composer for NodeJS and browser.",
-  "keywords": [
-    "IRI",
-    "URI",
-    "IRI-reference",
-    "URI-reference",
-    "ipv4",
-    "ipv6",
-    "uuid",
-    "parser",
-    "validator",
-    "RFC3986",
-    "RFC3987"
-  ],
-  "homepage": "https://github.com/SorinGFS/identifier-js#readme",
-  "bugs": {
-    "url": "https://github.com/SorinGFS/identifier-js/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/SorinGFS/identifier-js.git"
-  },
-  "license": "MIT",
-  "author": "SorinGFS",
-  "type": "commonjs",
-  "main": "index.js",
-  "scripts": {
-    "update-deps": "npx npm-check-updates -u && npm install",
-    "test": "node tests/vitest-setup && npm test"
-  },
-  "dependencies": {
-    "url-templates": "^1.0.4"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "engineStrict": true
-}
+{
+  "name": "identifier-js",
+  "version": "0.0.14",
+  "description": "A RFC3986 / RFC3987 compliant fast parser/validator/resolver/composer for NodeJS and browser.",
+  "keywords": [
+    "IRI",
+    "URI",
+    "IRI-reference",
+    "URI-reference",
+    "ipv4",
+    "ipv6",
+    "uuid",
+    "parser",
+    "validator",
+    "RFC3986",
+    "RFC3987"
+  ],
+  "homepage": "https://github.com/SorinGFS/identifier-js#readme",
+  "bugs": {
+    "url": "https://github.com/SorinGFS/identifier-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SorinGFS/identifier-js.git"
+  },
+  "license": "MIT",
+  "author": "SorinGFS",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "update-deps": "npx npm-check-updates -u && npm install",
+    "test": "node tests/vitest-setup && npm test"
+  },
+  "dependencies": {
+    "url-templates": "^1.0.5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "engineStrict": true
+}

package/readme.md

@@ -1,110 +1,449 @@
----
-
-title: Identifier JS
-
-description: A RFC3986 / RFC3987 compliant fast parser/validator/resolver/composer for NodeJS and browser.
-
----
-
-## Overview
-
-A fully RFC [3986](https://datatracker.ietf.org/doc/html/rfc3986.html)/[3897](https://datatracker.ietf.org/doc/html/rfc3987.html) compliant URI/IRI parser, validator, resolver and composer, along with other identifier utilities. This library implements the following [IANA registered](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) schemes:
-- `http` defined by [RFC9110, Section 4.2.1](https://datatracker.ietf.org/doc/html/rfc9110#section-4.2.1)
-- `https` defined by [RFC9110, Section 4.2.2](https://datatracker.ietf.org/doc/html/rfc9110#section-4.2.2)
-- `ws` defined by [RFC6455, Section 3](https://datatracker.ietf.org/doc/html/rfc6455#section-3)
-- `wss` defined by [RFC6455, Section 3](https://datatracker.ietf.org/doc/html/rfc6455#section-3)
-- `file` defined by [RFC8089, Section 2](https://datatracker.ietf.org/doc/html/rfc8089#section-2)
-
-Other schemes that are `IANA registered` schemes and compliant with the generic `URI` or `IRI` syntax are also supported. As for the identifiers that are not `IANA registered`, but compliant with the generic `URI` or `IRI` syntax, the preferred schemes are `uri` and respectively `iri`.
-
-## Install
-
-### Requirements
-
-- `regular expression with unicode support`, available in modern browsers and `NodeJS 18+`
-
-```bash title="console"
-npm i identifier-js
-```
-
-## API
-
-Exports are documented below.
-
-### URI (RFC 3986)
-
-#### Validation
-
-Validate a URI:
-- isUri: (value: string) => boolean
-
-Validate a URI reference (absolute or relative):
-- isUriReference: (value: string) => boolean
-
-Validate an absolute URI (must include scheme):
-- isAbsoluteUri: (value: string) => boolean
-
-#### Parsing
-
-Parse a URI into structured components:
-- parseUri: (value: string) => IdentifierComponents
-
-Parse a URI reference into structured components:
-- parseUriReference: (value: string) => RelativeIdentifierComponents
-
-Parse an absolute URI (must include scheme):
-- parseAbsoluteUri: (value: string) => AbsoluteIdentifierComponents
-
-### IRI (RFC 3987)
-
-#### Validation
-
-Validate an IRI:
-- isIri: (value: string) => boolean
-
-Validate an IRI reference (absolute or relative):
-- isIriReference: (value: string) => boolean
-
-Validate an absolute IRI (must include scheme):
-- isAbsoluteIri: (value: string) => boolean
-
-#### Parsing
-
-Parse an IRI into structured components:
-- parseIri: (value: string) => IdentifierComponents
-
-Parse an IRI reference into structured components:
-- parseIriReference: (value: string) => RelativeIdentifierComponents
-
-Parse an absolute IRI (must include scheme):
-- parseAbsoluteIri: (value: string) => AbsoluteIdentifierComponents
-
-### Reference Utilities (URI/IRI)
-
-Normalize a URI or IRI reference:
-- normalizeReference: (reference: string) => string
-
-Resolve a reference against a base identifier:
-- resolveReference: (reference: string, base: string, strict?: boolean, returnParts?: boolean) => string
-
-**Note:** 
-- strict (default: `true`) enables strict resolution behavior.
-- returnParts (default: `false`) returns structured components instead of a string.
-
-Convert a reference into absolute form:
-- toAbsoluteReference: (reference: string) => string
-
-Compute a relative reference from base to target:
-- toRelativeReference: (target: string, base: string) => string
-
-### UUID
-
-Validate a UUID (any version):
-- isUUID: (value: string) => boolean
-
-Validate a UUID version 4:
-- isUUIDv4: (value: string) => boolean
-
-## Testing
-
-- npm test
+---
+
+title: Identifier JS
+
+description: An RFC 3986 and RFC 3987 parser, validator, and reference resolver for Node.js and browser bundles.
+
+---
+
+# Identifier JS
+
+`identifier-js` is a fully RFC [3986](https://www.rfc-editor.org/rfc/rfc3986) and RFC [3987](https://www.rfc-editor.org/rfc/rfc3987) compliant URI/IRI parser, validator, resolver, and composer. It provides:
+
+- URI and IRI validation;
+- parsed identifier components;
+- RFC 3986 reference resolution and dot-segment removal;
+- relative-reference generation with round-trip guarantees for supported forms;
+- UUID and UUIDv4 lexical validation;
+- lazily compiled and cached regular expressions.
+
+The package is synchronous, CommonJS, and supports Node.js 18 or newer. Browser use requires a bundler or runtime that supports CommonJS dependencies and Unicode regular expressions.
+
+## Install
+
+```bash title="console"
+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.
+
+### Validate URI syntax
+
+Validate a complete URI, a URI reference, or an absolute URI without a fragment.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+isUri(value: string): true
+isUriReference(value: string): true
+isAbsoluteUri(value: string): true
+```
+
+```js
+const { isUri, isUriReference, isAbsoluteUri } = require('identifier-js');
+
+console.log(isUri('https://example.com/path?query#fragment')); // true
+console.log(isUriReference('../asset?version=2')); // true
+console.log(isAbsoluteUri('https://example.com/path?query')); // true
+```
+
+An `absolute-URI` is the fragment-free grammar defined by RFC 3986. Use `isUri` when a fragment is allowed.
+
+</details>
+
+### Parse URI components
+
+Parse URI syntax into scheme, authority, userinfo, host, port, path, query, and fragment components.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+parseUri(value: string): IdentifierComponents
+parseUriReference(value: string): RelativeIdentifierComponents
+parseAbsoluteUri(value: string): AbsoluteIdentifierComponents
+```
+
+```js
+const { parseUri } = require('identifier-js');
+
+console.log(parseUri('https://user@example.com:8443/a?b#c'));
+// {
+//   scheme: 'https',
+//   authority: 'user@example.com:8443',
+//   userinfo: 'user',
+//   host: 'example.com',
+//   port: '8443',
+//   path: '/a',
+//   query: 'b',
+//   fragment: 'c'
+// }
+```
+
+Absent optional components are returned as `undefined`. Present but empty query and fragment components are returned as empty strings.
+
+</details>
+
+### Validate IRI syntax
+
+Validate Unicode-capable identifiers using RFC 3987 grammar.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+isIri(value: string): true
+isIriReference(value: string): true
+isAbsoluteIri(value: string): true
+```
+
+```js
+const { isIri, isIriReference } = require('identifier-js');
+
+console.log(isIri('https://例え.テスト/資料?項目=値#概要')); // true
+console.log(isIriReference('../résumé')); // true
+```
+
+IRI support permits RFC 3987 Unicode ranges in applicable components. Complete IDNA processing and conversion to a transport URI are separate responsibilities.
+
+</details>
+
+### Parse IRI components
+
+Parse an IRI while preserving its Unicode component values.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+parseIri(value: string): IdentifierComponents
+parseIriReference(value: string): RelativeIdentifierComponents
+parseAbsoluteIri(value: string): AbsoluteIdentifierComponents
+```
+
+```js
+const { parseIri } = require('identifier-js');
+
+console.log(parseIri('https://usér@例え.テスト:8443/résumé?lang=fr#profil'));
+// {
+//   scheme: 'https',
+//   authority: 'usér@例え.テスト:8443',
+//   userinfo: 'usér',
+//   host: '例え.テスト',
+//   port: '8443',
+//   path: '/résumé',
+//   query: 'lang=fr',
+//   fragment: 'profil'
+// }
+```
+
+</details>
+
+### Resolve a reference
+
+Resolve a URI or IRI reference against an absolute base using RFC 3986 §5.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+resolveReference(
+    reference: string,
+    base: string,
+    strict?: boolean,
+    returnParts?: boolean
+): string | Record<string, string | undefined>
+```
+
+```js
+const { resolveReference } = require('identifier-js');
+
+console.log(resolveReference('../images/logo.svg', 'https://example.com/docs/api/page'));
+// https://example.com/docs/images/logo.svg
+
+console.log(resolveReference('?page=2', 'https://example.com/items?page=1#current'));
+// https://example.com/items?page=2
+```
+
+`strict` defaults to `true`. In strict mode, a reference containing a scheme replaces the base identifier even when both schemes are equal. `returnParts` defaults to `false`; when enabled at runtime, the function returns the resolved component object.
+
+Empty authorities, queries, and fragments are preserved during recomposition.
+
+</details>
+
+### Produce absolute and relative forms
+
+Remove a base fragment or derive a relative reference that resolves back to a target.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+toAbsoluteReference(reference: string): string
+toRelativeReference(target: string, base: string): string
+```
+
+```js
+const { toAbsoluteReference, toRelativeReference } = require('identifier-js');
+
+console.log(toAbsoluteReference('https://example.com/a/../b#section'));
+// https://example.com/b
+
+const target = 'https://example.com/docs/images/logo.svg';
+const base = 'https://example.com/docs/api/page';
+const relative = toRelativeReference(target, base);
+console.log(relative); // ../images/logo.svg
+```
+
+When no safe rootless relative form can round-trip to the target, `toRelativeReference` returns the absolute target. Different schemes or authorities also return the target unchanged.
+
+</details>
+
+### Normalization status
+
+`normalizeReference` is reserved for future normalization policy and currently returns its input unchanged.
+
+<details>
+<summary><strong>Current behavior and research</strong></summary>
+
+```ts
+normalizeReference(reference: string): string
+```
+
+```js
+const { normalizeReference } = require('identifier-js');
+
+console.log(normalizeReference('HTTP://Example.COM/a/../b'));
+// HTTP://Example.COM/a/../b
+```
+
+URI/IRI normalization has multiple standards-defined levels and scheme-specific tradeoffs. See [`normalization.md`](normalization.md) for implementation options, unsafe transformations, suggested profiles, and acceptance scenarios.
+
+</details>
+
+### Validate UUID text
+
+Validate the canonical UUID text shape or the stricter UUIDv4 version and variant fields.
+
+<details>
+<summary><strong>API and examples</strong></summary>
+
+```ts
+isUUID(value: string): true
+isUUIDv4(value: string): true
+```
+
+```js
+const { isUUID, isUUIDv4 } = require('identifier-js');
+
+console.log(isUUID('99c17cbb-656f-564a-940f-1a4568f03487')); // true
+console.log(isUUIDv4('123e4567-e89b-42d3-9456-426614174000')); // true
+```
+
+`isUUID` validates the `8-4-4-4-12` hexadecimal layout without restricting the version or variant fields. `isUUIDv4` requires version `4` and the RFC variant nibble `8`, `9`, `a`, or `b`.
+
+</details>
+
+## Processing model
+
+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.
+2. Recursively expand grammar references through `url-templates`.
+3. Add named capture groups when parsing is requested.
+4. Compile the complete expression with Unicode support.
+5. Cache the expression by operation, grammar rule, and scheme-policy 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.
+
+<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.
+
+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.
+
+</details>
+
+<details>
+<summary><strong>Scheme-specific hostname policy</strong></summary>
+
+The following schemes trigger DNS-style ASCII or Unicode label rules instead of the fully generic `reg-name` grammar:
+
+- `http`
+- `https`
+- `ws`
+- `wss`
+- `file`
+
+Matching is case-insensitive. Other valid schemes use generic RFC 3986/3987 registered-name syntax.
+
+This policy validates label shape and selected Unicode character classes. It is not complete IDNA processing and does not replace normalization, contextual, bidi, registry, or Punycode validation.
+
+</details>
+
+## Real-world use cases
+
+### Follow HTTP redirects and resource locations
+
+HTTP `Location` values are URI references and can be relative to the original target URI.
+
+<details>
+<summary><strong>Example and context</strong></summary>
+
+```js
+const { resolveReference } = require('identifier-js');
+
+const requestUrl = 'https://example.com/account/profile';
+const location = '../login?return=profile';
+console.log(resolveReference(location, requestUrl));
+// https://example.com/login?return=profile
+```
+
+RFC 9110 uses URI references in `Location`, `Content-Location`, and `Referer`. Correct resolution requires component parsing, path merging, query inheritance rules, and dot-segment removal.
+
+</details>
+
+### Keep document trees portable
+
+Relative references let documents and assets move together without rewriting every internal link.
+
+<details>
+<summary><strong>Example and context</strong></summary>
+
+```js
+const { resolveReference, toRelativeReference } = require('identifier-js');
+
+const documentUrl = 'https://example.com/manual/chapters/intro.html';
+const imageUrl = 'https://example.com/manual/images/diagram.svg';
+const relative = toRelativeReference(imageUrl, documentUrl);
+console.log(relative); // ../images/diagram.svg
+console.log(resolveReference(relative, documentUrl)); // original image URL
+```
+
+RFC 3986 identifies portable hypertext document trees as a central use for relative references.
+
+</details>
+
+### Process internationalized identifiers
+
+IRI parsing preserves native-script host, path, query, and fragment text for interfaces and internationalized content.
+
+<details>
+<summary><strong>Example and context</strong></summary>
+
+```js
+const { parseIri } = require('identifier-js');
+
+const parts = parseIri('https://例え.テスト/検索?q=資料#結果');
+console.log(parts.host); // 例え.テスト
+console.log(parts.path); // /検索
+```
+
+RFC 3987 uses IRIs for internationalized identification while requiring mapping to URIs when a protocol accepts only URI syntax. Cache lookup, browser history, XML identifiers, and indexing are cited comparison contexts.
+
+</details>
+
+### Validate and route protocol identifiers
+
+Component parsing supports policy decisions without unsafe string splitting.
+
+<details>
+<summary><strong>Example and context</strong></summary>
+
+```js
+const { parseUri } = require('identifier-js');
+
+const parts = parseUri('wss://example.com:8443/events?channel=updates');
+console.log(parts.scheme); // wss
+console.log(parts.host);   // example.com
+console.log(parts.port);   // 8443
+console.log(parts.path);   // /events
+```
+
+Applications can inspect scheme, authority, path, and query before selecting a connector, enforcing an allowlist, constructing an HTTP request target, or routing to a service. Protocol-specific security and semantic validation remains the application's responsibility.
+
+</details>
+
+### Validate externally supplied UUID text
+
+Lexical UUID checks are useful at API, configuration, and storage boundaries.
+
+<details>
+<summary><strong>Example and context</strong></summary>
+
+```js
+const { isUUIDv4 } = require('identifier-js');
+
+try {
+    isUUIDv4('123e4567-e89b-42d3-9456-426614174000');
+    console.log('valid UUIDv4');
+} catch (error) {
+    console.error(error.message);
+}
+```
+
+RFC 9562 lists database keys, filenames, system identifiers, and transaction identifiers among common UUID uses. UUID validation does not establish authorization, unpredictability, uniqueness, or safe use as a capability token.
+
+</details>
+
+## Intentional behavior and limitations
+
+<details>
+<summary><strong>Validation and parsing boundaries</strong></summary>
+
+- Validators return `true` or throw; they do not return `false`.
+- URI functions reject non-ASCII characters where RFC 3986 permits only URI syntax. Use the IRI functions for RFC 3987 Unicode ranges.
+- `absolute-URI` and `absolute-IRI` exclude fragments by definition. The complete `URI` and `IRI` functions permit fragments.
+- Scheme-specific processing currently specializes hostname syntax; it does not implement every protocol rule for HTTP, WebSocket, or `file` identifiers.
+- Scheme-specific Unicode labels are not complete IDNA validation.
+- Ports are restricted to an empty value or the numeric range 0–65535. Generic RFC 3986 syntax itself permits any sequence of digits.
+- Generic registered names may contain syntax that DNS-style hostnames reject.
+- Parsing separates components before any application-level percent decoding.
+- The library does not perform network, DNS, filesystem, registry, or authorization checks.
+
+</details>
+
+<details>
+<summary><strong>Resolution and conversion boundaries</strong></summary>
+
+- Resolution uses IRI grammar, so Unicode references and bases are accepted.
+- Empty authorities, queries, and fragments remain distinct from absent components.
+- `strict = false` enables RFC 3986 backward-compatible handling when a reference repeats the base scheme.
+- `toAbsoluteReference` requires an identifier containing a scheme and removes its fragment through empty-reference resolution.
+- `toRelativeReference` compares scheme and authority text exactly; it does not normalize them first.
+- `toRelativeReference` may return an absolute target when a rootless relative path cannot preserve identity.
+- `normalizeReference` is intentionally an identity function until a normalization contract is selected.
+
+</details>
+
+<details>
+<summary><strong>UUID boundaries</strong></summary>
+
+- `isUUID` validates canonical hexadecimal layout only; it does not enforce a known version or the RFC variant.
+- `isUUIDv4` validates the version and variant fields but does not assess random-number quality.
+- A syntactically valid UUID is not proof of uniqueness, integrity, authenticity, or authorization.
+
+</details>
+
+## Qualification
+
+The current suite contains 418 active tests covering URI/IRI validation and parsing, scheme-specific hosts, IPv4, IPv6, ports, UUIDs, RFC 3986 resolution examples, empty components, absolute conversion, and relative-reference round trips.
+
+The reference-conversion changes were additionally checked against 2,646 combinations of paths, absent/empty/non-empty queries, and absent/empty/non-empty fragments.
+
+## Authoritative references
+
+- [RFC 3986 — Uniform Resource Identifier: Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986)
+- [RFC 3987 — Internationalized Resource Identifiers](https://www.rfc-editor.org/rfc/rfc3987)
+- [RFC 9110 — HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110)
+- [RFC 6455 — The WebSocket Protocol](https://www.rfc-editor.org/rfc/rfc6455)
+- [RFC 8089 — The `file` URI Scheme](https://www.rfc-editor.org/rfc/rfc8089)
+- [RFC 9562 — Universally Unique IDentifiers](https://www.rfc-editor.org/rfc/rfc9562)
+
+## Disclaimer
+
+Validation establishes conformance with this implementation's syntax and policy. It does not establish that an identifier is registered, reachable, trustworthy, safe to dereference, or appropriate for a particular protocol operation.

package/tests/resolve.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'vitest';
 import id from '../index.js';
 
+// Verify reference resolution behavior beyond the RFC's published examples.
 const resolveTests = [
     ['urn:some:ip:prop', 'urn:some:ip:prop', 'urn:some:ip:prop'],
     ['urn:some:ip:prop', 'urn:some:other:prop', 'urn:some:ip:prop'],
@@ -13,4 +14,24 @@ describe('resolveReference', () => {
             expect(subject).to.equal(expected);
         });
     });
+
+    // Preserve an explicitly empty query while replacing the base query.
+    test('Preserves an empty query component', () => {
+        expect(id.resolveReference('?', 'https://example.com/path?old#fragment')).to.equal('https://example.com/path?');
+    });
+
+    // Preserve an explicitly empty fragment after inheriting the base query.
+    test('Preserves an empty fragment component', () => {
+        expect(id.resolveReference('#', 'https://example.com/path?query#old')).to.equal('https://example.com/path?query#');
+    });
+
+    // Preserve an empty query inherited by an empty reference.
+    test('Preserves an inherited empty query component', () => {
+        expect(id.resolveReference('', 'https://example.com/path?#fragment')).to.equal('https://example.com/path?');
+    });
+
+    // Preserve the delimiter that distinguishes an empty authority from no authority.
+    test('Preserves an empty authority component', () => {
+        expect(id.resolveReference('uri:///target', 'uri:/base')).to.equal('uri:///target');
+    });
 });

package/tests/to-relative.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'vitest';
 import id from '../index.js';
 
+// Verify relative-reference generation and round trips through reference resolution.
 describe('toRelativeReference IRI', () => {
     test.each([
         ['https://examplé.com/var/lib', 'https://examplé.com', '/var/lib'],
@@ -48,3 +49,25 @@ describe('toRelativeReference URI', () => {
         expect(id.resolveReference(relative, base)).to.equal(target); // sanity check
     });
 });
+
+// Verify empty components and path forms that require explicit inheritance control.
+describe('toRelativeReference component presence', () => {
+    // Require every generated reference to have the expected form and resolve back to its target.
+    test.each([
+        ['clears a query on the same absolute path', 'https://example.com/a/item', 'https://example.com/a/item?old', '/a/item'],
+        ['preserves an empty target query', 'https://example.com/a/item?', 'https://example.com/a/item?old', '?'],
+        ['preserves an empty target fragment', 'https://example.com/a/item#', 'https://example.com/a/item', '#'],
+        ['clears a query on an empty path', 'https://example.com', 'https://example.com?old', '//example.com'],
+        ['clears a query on a colon-containing rootless path', 'urn:a:b', 'urn:a:b?old', './a:b'],
+        ['produces an empty path from a non-empty base path', 'https://example.com', 'https://example.com/a', '//example.com'],
+        ['produces a root path from a single-segment base path', 'https://example.com/', 'https://example.com/a', '/'],
+        ['preserves a trailing slash on a rootless directory', 'urn:a/', 'urn:a/b', './'],
+        ['protects a colon-containing first path segment', 'urn:a:b', 'urn:c', './a:b'],
+        ['falls back for an empty rootless target path', 'urn:', 'urn:a', 'urn:'],
+        ['falls back when rootless parent traversal changes path form', 'urn:a', 'urn:a/', 'urn:a'],
+    ])('%s', (description, target, base, expected) => {
+        const relative = id.toRelativeReference(target, base);
+        expect(relative).to.equal(expected);
+        expect(id.resolveReference(relative, base)).to.equal(target);
+    });
+});