identifier-js 0.0.1 → 0.0.3

package/index.d.ts

@@ -0,0 +1,73 @@
+/** @throws {Error} If the UUID is invalid. */
+export const isUUID: (string: string) => true;
+/** @throws {Error} If the UUID-v4 is invalid. */
+export const isUUIDv4: (string: string) => true;
+
+/** @throws {Error} If the URI is invalid. */
+export const isUri: (uri: string) => true;
+/** @throws {Error} If the URI-reference is invalid. */
+export const isUriReference: (uriReference: string) => true;
+/** @throws {Error} If the absolute-URI is invalid. */
+export const isAbsoluteUri: (uri: string) => true;
+
+/** @throws {Error} If the URI is invalid. */
+export const parseUri: (uri: string) => IdentifierComponents;
+/** @throws {Error} If the URI-reference is invalid. */
+export const parseUriReference: (uriReference: string) => RelativeIdentifierComponents;
+/** @throws {Error} If the absolute-URI is invalid. */
+export const parseAbsoluteUri: (uri: string) => AbsoluteIdentifierComponents;
+
+/** @throws {Error} If the IRI is invalid. */
+export const isIri: (iri: string) => true;
+/** @throws {Error} If the IRI-reference is invalid. */
+export const isIriReference: (iriReference: string) => true;
+/** @throws {Error} If the absolute-IRI is invalid. */
+export const isAbsoluteIri: (iri: string) => true;
+
+/** @throws {Error} If the IRI is invalid. */
+export const parseIri: (iri: string) => IdentifierComponents;
+/** @throws {Error} If the IRI-reference is invalid. */
+export const parseIriReference: (iriReference: string) => RelativeIdentifierComponents;
+/** @throws {Error} If the absolute-IRI is invalid. */
+export const parseAbsoluteIri: (iri: string) => AbsoluteIdentifierComponents;
+
+/** @throws {Error} If the reference is invalid. */
+export const normalizeReference: (reference: string) => string;
+/** @throws {Error} If the base or the reference is invalid. */
+export const resolveReference: (reference: string, base: string, strict?: boolean, returnParts?: boolean) => string;
+/** @throws {Error} If the reference is invalid. */
+export const toAbsoluteReference: (reference: string) => string;
+/** @throws {Error} If the base or the reference is invalid. */
+export const toRelativeReference: (target: string, base: string) => string;
+
+type IdentifierComponents = {
+    scheme: string;
+    authority: string;
+    userinfo?: string;
+    host: string;
+    port?: string;
+    path: string;
+    query?: string;
+    fragment?: string;
+};
+
+type RelativeIdentifierComponents = {
+    scheme?: string;
+    authority?: string;
+    userinfo?: string;
+    host?: string;
+    port?: string;
+    path: string;
+    query?: string;
+    fragment?: string;
+};
+
+type AbsoluteIdentifierComponents = {
+    scheme: string;
+    authority: string;
+    userinfo?: string;
+    host: string;
+    port?: string;
+    path: string;
+    query?: string;
+};

package/index.js

@@ -0,0 +1,273 @@
+'use strict';
+// a valid URI is always a valid IRI
+const { recursiveCompile } = require('url-templates');
+const patterns = new Map();
+// RFC3986/RFC3987 common rules
+const commonRules = {
+    scheme: '[a-zA-Z][a-zA-Z0-9+.-]*',
+    port: '[0-9]*',
+    IP_literal: '\\[(?:{IPv6address}|{IPvFuture})\\]',
+    IPv6address: '(?:(?:{h16}:){6}{ls32}|::(?:{h16}:){5}{ls32}|(?:(?:{h16})?)::(?:{h16}:){4}{ls32}|(?:(?:{h16}:)?{h16})?::(?:{h16}:){3}{ls32}|(?:(?:{h16}:){0,2}{h16})?::(?:{h16}:){2}{ls32}|(?:(?:{h16}:){0,3}{h16})?::(?:{h16}:){1}{ls32}|(?:(?:{h16}:){0,4}{h16})?::{ls32}|(?:(?:{h16}:){0,5}{h16})?::{h16}|(?:(?:{h16}:){0,6}{h16})?::)',
+    ls32: '(?:{h16}:{h16}|{IPv4address})',
+    h16: '{hexdig}{1,4}',
+    IPv4address: '(?:{dec_octet}\\.){3}{dec_octet}',
+    dec_octet: '(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)',
+    IPvFuture: 'v{hexdig}+\\.(?:{unreserved}|{sub_delims}|:)+',
+    unreserved: '[a-zA-Z0-9_.~-]',
+    reserved: '(?:{gen_delims}|{sub_delims})',
+    pct_encoded: '%{hexdig}{2}',
+    gen_delims: '[:/?#[\\]@]',
+    sub_delims: "[!&'()*+,;=$]",
+    hexdig: '[0-9A-Fa-f]',
+    UUID: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}',
+    UUID_v4: '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}',
+};
+// RFC3986 rules
+const uriRules = {
+    URI_reference: '(?:{URI}|{relative_ref})',
+    URI: '{absolute_URI}(?:#{fragment})?',
+    absolute_URI: '{scheme}:{hier_part}(?:\\?{query})?',
+    relative_ref: '{relative_part}(?:\\?{query})?(?:#{fragment})?',
+    hier_part: '(?:\/\/{authority}{path_abempty}|{path_absolute}|{path_rootless}|{path_empty})',
+    relative_part: '(?:\/\/{authority}{path_abempty}|{path_absolute}|{path_noscheme}|{path_empty})',
+    authority: '(?:{userinfo}@)?{host}(?::{port})?',
+    host: '(?:{IP_literal}|{IPv4address}|{reg_name})',
+    userinfo: '(?:{unreserved}|{pct_encoded}|{sub_delims}|:)*',
+    reg_name: '(?:{unreserved}|{pct_encoded}|{sub_delims})*',
+    path: '(?:{path_abempty}|{path_absolute}|{path_noscheme}|{path_rootless}|{path_empty})',
+    path_abempty: '(?:\/{segment})*',
+    path_absolute: '\/(?:{segment_nz}(?:\/{segment})*)?',
+    path_noscheme: '{segment_nz_nc}(?:\/{segment})*',
+    path_rootless: '{segment_nz}(?:\/{segment})*',
+    path_empty: '',
+    segment: '{pchar}*',
+    segment_nz: '{pchar}+',
+    segment_nz_nc: '(?:{unreserved}|{pct_encoded}|{sub_delims}|@)+',
+    query: '(?:{pchar}|\/|\\?)*',
+    fragment: '(?:{pchar}|\/|\\?)*',
+    pchar: '(?:{unreserved}|{pct_encoded}|{sub_delims}|:|@)',
+};
+// RFC3987 rules
+const iriRules = {
+    IRI_reference: '(?:{IRI}|{irelative_ref})',
+    IRI: '{absolute_IRI}(?:#{ifragment})?',
+    absolute_IRI: '{scheme}:{ihier_part}(?:\\?{iquery})?',
+    irelative_ref: '(?:{irelative_part}(?:\\?{iquery})?(?:#{ifragment})?)',
+    ihier_part: '(?:\/\/{iauthority}{ipath_abempty}|{ipath_absolute}|{ipath_rootless}|{ipath_empty})',
+    irelative_part: '(?:\/\/{iauthority}{ipath_abempty}|{ipath_absolute}|{ipath_noscheme}|{ipath_empty})',
+    iauthority: '(?:{iuserinfo}@)?{ihost}(?::{port})?',
+    iuserinfo: '(?:{iunreserved}|{pct_encoded}|{sub_delims}|:)*',
+    ihost: '(?:{IP_literal}|{IPv4address}|{ireg_name})',
+    ireg_name: '(?:{iunreserved}|{pct_encoded}|{sub_delims})*',
+    ipath: '(?:{ipath_abempty}|{ipath_absolute}|{ipath_noscheme}|{ipath_rootless}|{ipath_empty})',
+    ipath_empty: '',
+    ipath_rootless: '{isegment_nz}(?:\/{isegment})*',
+    ipath_noscheme: '{isegment_nz_nc}(?:\/{isegment})*',
+    ipath_absolute: '\/(?:{isegment_nz}(?:\/{isegment})*)?',
+    ipath_abempty: '(?:\/{isegment})*',
+    isegment_nz_nc: '(?:{iunreserved}|{pct_encoded}|{sub_delims}|@)+',
+    isegment_nz: '{ipchar}+',
+    isegment: '{ipchar}*',
+    iquery: '(?:{ipchar}|{iprivate}|\/|\\?)*',
+    ifragment: '(?:{ipchar}|\/|\\?)*',
+    ipchar: '(?:{iunreserved}|{pct_encoded}|{sub_delims}|:|@)',
+    iunreserved: '(?:[a-zA-Z0-9._~-]|{ucschar})',
+    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}]',
+};
+// pattern RFC group names
+const groupNames = {
+    scheme: 'scheme',
+    port: 'port',
+    authority: 'authority',
+    host: 'host',
+    userinfo: 'userinfo',
+    query: 'query',
+    fragment: 'fragment',
+    iauthority: 'authority',
+    ihost: 'host',
+    iuserinfo: 'userinfo',
+    iquery: 'query',
+    ifragment: 'fragment',
+    path_abempty: 'path',
+    path_absolute: 'path',
+    path_noscheme: 'path',
+    path_rootless: 'path',
+    path_empty: 'path',
+    ipath_abempty: 'path',
+    ipath_absolute: 'path',
+    ipath_noscheme: 'path',
+    ipath_rootless: 'path',
+    ipath_empty: 'path',
+};
+// all rules into one map
+const rules = Object.assign({}, commonRules, uriRules, iriRules);
+const addNames = (key) => (groupNames[key] ? `(?<${groupNames[key]}>${rules[key]})` : rules[key]);
+// 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.`);
+    if (!patterns.has('_' + rule)) patterns.set('_' + rule, new RegExp(`^${recursiveCompile(rules, rule, addNames)}$`, 'u'));
+    const match = patterns.get('_' + rule).exec(string);
+    if (match) return match.groups;
+    throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
+};
+// validate (faster, it uses regex.test and does not include named capture groups)
+const validate = (string, rule) => {
+    if (typeof string !== 'string') throw new TypeError(`Invalid ${rule.replace('_', '-')} type: must be a string.`);
+    if (!patterns.has(rule)) patterns.set(rule, new RegExp(`^${recursiveCompile(rules, rule)}$`, 'u'));
+    if (patterns.get(rule).test(string)) return true;
+    throw new SyntaxError(`Invalid ${rule.replace('_', '-')}: ${string}`);
+};
+// compose as per RFC 3986 Section 5.3 (component recomposition)
+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;
+    return result;
+}
+// remove dot segments algorithm per RFC 3986 Section 5.2.4 (loop and replace)
+function removeDotSegments(path) {
+    const output = [];
+    let input = path;
+    while (input.length > 0) {
+        if (input.startsWith('../')) input = input.slice(3);
+        else if (input.startsWith('./')) input = input.slice(2);
+        else if (input.startsWith('/./')) input = input.replace('/./', '/');
+        else if (input === '/.') input = '/';
+        else if (input.startsWith('/../')) {
+            input = input.replace('/../', '/');
+            if (output.length) output.pop();
+        } else if (input === '/..') {
+            input = '/';
+            if (output.length) output.pop();
+        } else if (input === '.' || input === '..') {
+            input = '';
+        } else {
+            // move first segment from input to output
+            let seg = '';
+            if (input[0] === '/') {
+                // keep leading '/'
+                const idx = input.indexOf('/', 1);
+                if (idx === -1) {
+                    seg = input;
+                    input = '';
+                } else {
+                    seg = input.slice(0, idx);
+                    input = input.slice(idx);
+                }
+            } else {
+                const idx = input.indexOf('/');
+                if (idx === -1) {
+                    seg = input;
+                    input = '';
+                } else {
+                    seg = input.slice(0, idx);
+                    input = input.slice(idx);
+                }
+            }
+            output.push(seg);
+        }
+    }
+    return output.join('');
+}
+// resolve as per RFC https://datatracker.ietf.org/doc/html/rfc3986#section-5.2
+function resolveReference(reference, base, strict = true, parts = false) {
+    let B;
+    if (typeof base === 'string') {
+        B = parse(base, 'IRI');
+    } else {
+        B = Object.assign({}, base);
+    }
+    if (!B.scheme) throw new Error('Expected an URI/IRI (with scheme) as base.');
+
+    let R;
+    if (typeof reference === 'string') {
+        R = parse(reference, 'IRI_reference');
+    } else {
+        R = Object.assign({}, reference);
+    }
+
+    let T;
+    if (R.scheme && (strict || R.scheme !== B.scheme)) {
+        T = R;
+    } else {
+        T = {};
+        T.scheme = B.scheme;
+        if (R.authority !== undefined && R.authority !== null) {
+            T.authority = R.authority;
+            T.path = R.path;
+            T.query = R.query;
+        } else {
+            T.authority = B.authority;
+            if (R.path && R.path.length > 0) {
+                if (R.path.startsWith('/')) {
+                    T.path = R.path;
+                } else if (B.authority !== undefined && B.authority !== null && (!B.path || B.path.length === 0)) {
+                    T.path = '/' + R.path;
+                } else {
+                    // merge base path and ref path
+                    const idx = B.path ? B.path.lastIndexOf('/') : -1;
+                    const prefix = idx !== -1 ? B.path.slice(0, idx + 1) : '';
+                    T.path = prefix + R.path;
+                }
+                T.query = R.query;
+            } else {
+                T.path = B.path;
+                if (R.query !== undefined && R.query !== null) T.query = R.query;
+                else T.query = B.query;
+            }
+        }
+        T.fragment = R.fragment;
+    }
+    T.path = removeDotSegments(T.path || '');
+    if (parts) return T;
+    return compose(T);
+}
+// reverse logic for resolve
+const toRelativeReference = (target, base) => {
+    const B = parse(base, 'absolute_IRI');
+    const T = parse(target, 'IRI');
+    if (T.scheme !== B.scheme || T.authority !== B.authority) return target;
+    let result;
+    if (B.path === T.path) {
+        result = '';
+    } else {
+        const baseSegments = B.path.split('/');
+        const targetSegments = T.path.split('/');
+        let position = 0;
+        while (baseSegments[position] === targetSegments[position] && position < baseSegments.length - 1 && position < targetSegments.length - 1) {
+            position++;
+        }
+        const segments = [];
+        for (let index = position + 1; index < baseSegments.length; index++) segments.push('..');
+        for (let index = position; index < targetSegments.length; index++) segments.push(targetSegments[index]);
+        result = segments.join('/');
+    }
+    if (T.query !== undefined) result += `?${T.query}`;
+    if (T.fragment !== undefined) result += `#${T.fragment}`;
+    return result;
+};
+// export
+module.exports = {
+    isUUID: (string) => validate(string, 'UUID'),
+    isUUIDv4: (string) => validate(string, 'UUID_v4'),
+    isUri: (string) => validate(string, 'URI'),
+    isUriReference: (string) => validate(string, 'URI_reference'),
+    isAbsoluteUri: (string) => validate(string, 'absolute_URI'),
+    parseUri: (string) => parse(string, 'URI'),
+    parseUriReference: (string) => parse(string, 'URI_reference'),
+    parseAbsoluteUri: (string) => parse(string, 'absolute_URI'),
+    isIri: (string) => validate(string, 'IRI'),
+    isIriReference: (string) => validate(string, 'IRI_reference'),
+    isAbsoluteIri: (string) => validate(string, 'absolute_IRI'),
+    parseIri: (string) => parse(string, 'IRI'),
+    parseIriReference: (string) => parse(string, 'IRI_reference'),
+    parseAbsoluteIri: (string) => parse(string, 'absolute_IRI'),
+    resolveReference, // not yet decided if the return should be normalized or not, and in what extent
+    normalizeReference: (string) => string, // not done yet
+    toAbsoluteReference: (string) => resolveReference('', string),
+    toRelativeReference,
+};

package/package.json

@@ -1,35 +1,43 @@
-{
-  "name": "identifier-js",
-  "version": "0.0.1",
-  "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",
-    "RFC",
-    "3987",
-    "RFC",
-    "3986"
-  ],
-  "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": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+{
+  "name": "identifier-js",
+  "version": "0.0.3",
+  "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",
+    "RFC",
+    "3987",
+    "RFC",
+    "3986"
+  ],
+  "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
+}

package/readme.md

@@ -12,6 +12,92 @@ A fully RFC [3986](https://datatracker.ietf.org/doc/html/rfc3986.html)/[3897](ht
 
 ## 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 enables strict resolution behavior.
+- returnParts 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