identifier-js 0.4.0 → 0.4.1

package/index.d.ts

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

package/index.js

@@ -3,7 +3,7 @@
 // A valid URI is always a valid IRI, subject to every implemented scheme's more specific grammar.
 const { recursiveCompile } = require('url-templates');
 const patterns = new Map();
-const implemented_schemes = '(?:[hH][tT][tT][pP][sS]?|[wW][sS][sS]?|[fF][iI][lL][eE]|[uU][rR][nN])';
+const implemented_schemes = '(?:[hH][tT][tT][pP][sS]?|[wW][sS][sS]?|[fF][iI][lL][eE])';
 // RFC3986/RFC3987 common rules + https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2:~:text=DNS%29%2E-,A,of%20%5BRFC1123%5D%2E
 const commonRules = {
     implemented_schemes,
@@ -81,11 +81,9 @@ const iriRules = {
 };
 // Define RFC 8141 productions and URI/IRI root overrides for the conditional URN profile.
 const urnRules = {
-    scheme: implemented_schemes,
-    URI_reference: '{URI}',
+    scheme: '[uU][rR][nN]',
     URI: '{namestring}',
     absolute_URI: '{assigned_name}(?:{rq_components})?',
-    IRI_reference: '{IRI}',
     IRI: '{URI}',
     absolute_IRI: '{absolute_URI}',
     namestring: '{assigned_name}(?:{rq_components})?(?:#{f_component})?',
@@ -148,7 +146,10 @@ const groupNames = {
     NSS: 'nss',
     r_component: 'rComponent',
     q_component: 'qComponent',
+    f_component: 'fComponent',
 };
+// Keep URN parse results limited to their RFC 8141 component names.
+const genericUrnGroupNames = new Set(['authority', 'userinfo', 'host', 'port', 'path', 'query', 'fragment']);
 // Detect schemes for which the package implements grammar beyond generic URI/IRI syntax.
 const isSpecificScheme = (string) => new RegExp('^' + implemented_schemes + ':').test(string);
 // Select and merge generic, DNS-host, empty-file-host, or URN grammar profiles.
@@ -158,7 +159,11 @@ const rules = (profile) => Object.assign({}, commonRules, uriRules, iriRules, pr
 const parse = (string, rule) => {
     if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
     const profile = schemeProfile(string);
-    const addNames = (key) => (groupNames[key] ? `(?<${groupNames[key]}>${rules(profile)[key]})` : rules(profile)[key]);
+    // Select only the component captures exposed by the active grammar.
+    const addNames = (key) => {
+        const groupName = groupNames[key];
+        return groupName && !(profile === 'u' && genericUrnGroupNames.has(groupName)) ? `(?<${groupName}>${rules(profile)[key]})` : rules(profile)[key];
+    };
     const ruleId = '_' + profile + rule;
     if (!patterns.has(ruleId)) patterns.set(ruleId, new RegExp(`^${recursiveCompile(rules(profile), rule, addNames)}$`, 'u'));
     const match = patterns.get(ruleId).exec(string);
@@ -562,7 +567,7 @@ function normalizeParsedReference(parts, options = {}) {
         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) });
+        return compose({ scheme: parts.scheme.toLowerCase(), path: `${parts.nid.toLowerCase()}:${normalizePercentEncoding(parts.nss, false)}`, query, fragment: parts.fComponent === undefined ? undefined : normalizePercentEncoding(parts.fComponent, false) });
     }
     // Normalize each component independently so encoded delimiters cannot become structure.
     const scheme = parts.scheme === undefined ? undefined : parts.scheme.toLowerCase();

package/normalization.md

@@ -60,7 +60,7 @@ Without a mapper, normalization retains the parser's host classification as an I
 
 ## 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.
+A parsed value under the case-insensitive `urn` scheme takes a separate RFC 8141 normalization path using its captured `scheme`, `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` properties.
 
 | Input component | Output | Source |
 | --- | --- | --- |

package/package.json

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

package/readme.md

@@ -169,12 +169,12 @@ 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.fComponent); // 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'`.
+URN parse results expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent`. They do not expose generic `path`, `query`, or `fragment` aliases. To require a URN after parsing a value accepted as a general URI, check `parsed.scheme.toLowerCase() === 'urn'`.
 
 URNs remain ASCII even through the IRI operations. Callers representing non-ASCII names must first encode them as UTF-8 and then percent-encode the resulting octets; lexical validation does not decode or verify those octet sequences.
 
@@ -212,7 +212,7 @@ console.log(resolveReference('?page=2', 'https://example.com/items?page=1#curren
 
 Empty authorities, queries, and fragments are preserved during recomposition.
 
-This function performs generic RFC 3986 reference resolution only. It does not invoke a URN resolution service or implement scheme-specific URN resolution semantics.
+`resolveReference` does not apply when either input uses the `urn` scheme. URN resolution services are outside this package's scope.
 
 </details>
 
@@ -242,7 +242,7 @@ console.log(relative); // ../images/logo.svg
 
 When no safe rootless relative form can round-trip to the target, `toRelativeReference` returns the absolute target. Different schemes or authorities also return the target unchanged. Complete dot segments in either path also trigger this fallback because RFC resolution removes them. For those inputs, resolving the result produces the same identifier as resolving the target directly; lexical dot-segment spelling is not preserved.
 
-These conversion functions retain their generic URI-reference behavior. They do not construct, resolve, or interpret scheme-specific relative URNs.
+`toAbsoluteReference` and `toRelativeReference` do not apply when an input uses the `urn` scheme. Relative-URN semantics are outside this package's scope.
 
 </details>
 
@@ -465,7 +465,7 @@ RFC 9562 lists database keys, filenames, system identifiers, and transaction ide
 
 - 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.
+- Values with the case-insensitive `urn` scheme follow RFC 8141 namestring syntax and expose `nid`, `nss`, `rComponent`, `qComponent`, and `fComponent` fields through the URI and IRI parsers.
 - URN validation establishes generic lexical syntax only, not namespace registration, namespace-specific syntax, assignment, resolution, or equivalence.
 - Validators return `true` or throw at the first grammar violation.
 - `absolute-URI` and `absolute-IRI` use the fragment-free grammar defined by their RFCs; complete URI and IRI operations accept fragments.
@@ -483,7 +483,7 @@ RFC 9562 lists database keys, filenames, system identifiers, and transaction ide
 - `toAbsoluteReference` removes the fragment from an identifier containing a scheme.
 - `toRelativeReference` generates a reference whose RFC resolution equals the target resolution for supported forms.
 - `normalize()` implements the applicable case, percent-encoding, and path-segment rules from RFC 3986 §§6.2.2.1–6.2.2.3 and RFC 3987 §§5.3.2.1, 5.3.2.3–5.3.2.4, RFC 3987 §§3.1–3.2 URI/IRI representation transformation, RFC 5952 IPv6 text, RFC 9110 HTTP(S) port/path forms, RFC 6455 WS(S) port/resource-name forms, and RFC 8141 scheme/NID/percent-triplet normalization without NSS decoding or path reduction.
-- RFC 3986 reference resolution and relative-reference generation receive no URN-specific semantics; RFC 8141 URN resolution services and URN-equivalence APIs are not implemented.
+- Reference resolution and absolute/relative reference conversion do not apply to `urn` inputs; RFC 8141 URN resolution services and URN-equivalence APIs are not implemented.
 
 </details>