identifier-js 0.0.2 → 0.0.3

package/index.d.ts

@@ -1,25 +1,43 @@
-export const isUUID: (string: string) => boolean;
-export const isUUIDv4: (string: string) => boolean;
+/** @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;
 
-export const isUri: (uri: string) => boolean;
-export const isUriReference: (uriReference: string) => boolean;
-export const isAbsoluteUri: (uri: string) => boolean;
+/** @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;
 
-export const isIri: (iri: string) => boolean;
-export const isIriReference: (iriReference: string) => boolean;
-export const isAbsoluteIri: (iri: string) => boolean;
+/** @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 = {

package/index.js

@@ -19,8 +19,8 @@ const commonRules = {
     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}',
+    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 = {
@@ -105,15 +105,18 @@ 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 TypeError(`Invalid ${rule.replace('_', '-')}: ${string}`);
+    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'));
-    return patterns.get(rule).test(string);
+    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 = {}) {
@@ -249,8 +252,8 @@ const toRelativeReference = (target, base) => {
 };
 // export
 module.exports = {
-    isUUID: (string) => validate(string, 'uuid'),
-    isUUIDv4: (string) => validate(string, 'uuid_v4'),
+    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'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "identifier-js",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A RFC3986 / RFC3987 compliant fast parser/validator/resolver/composer for NodeJS and browser.",
   "keywords": [
     "IRI",
@@ -35,5 +35,9 @@
   },
   "dependencies": {
     "url-templates": "^1.0.4"
-  }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "engineStrict": true
 }

package/readme.md

@@ -12,6 +12,10 @@ 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
 ```

package/tests/validation.test.js

@@ -15,54 +15,54 @@ describe('isUUID', () => {
     });
 
     test('invalid UUID missing hyphens', () => {
-        expect(id.isUUID('123e4567e89b12d3a456426614174000')).to.equal(false);
+        expect(() => id.isUUID('123e4567e89b12d3a456426614174000')).to.throw(Error, 'Invalid UUID: 123e4567e89b12d3a456426614174000');
     });
 
     test('invalid UUID with extra hyphens', () => {
-        expect(id.isUUID('123e4567-e89b-12d3-a456-426-614174000')).to.equal(false);
+        expect(() => id.isUUID('123e4567-e89b-12d3-a456-426-614174000')).to.throw(Error, 'Invalid UUID: 123e4567-e89b-12d3-a456-426-614174000');
     });
 
     test('invalid UUID with incorrect group lengths', () => {
-        expect(id.isUUID('123e4567-e89b-12d3-a456426614174000')).to.equal(false);
+        expect(() => id.isUUID('123e4567-e89b-12d3-a456426614174000')).to.throw(Error, 'Invalid UUID: 123e4567-e89b-12d3-a456426614174000');
     });
 
     test('invalid UUID with non-hexadecimal characters', () => {
-        expect(id.isUUID('123e4567-e89b-12d3-g456-426614174000')).to.equal(false);
+        expect(() => id.isUUID('123e4567-e89b-12d3-g456-426614174000')).to.throw(Error, 'Invalid UUID: 123e4567-e89b-12d3-g456-426614174000');
     });
 
     test('invalid UUID string that is too short', () => {
-        expect(id.isUUID('123e4567-e89b-12d3-a456-42661417400')).to.equal(false);
+        expect(() => id.isUUID('123e4567-e89b-12d3-a456-42661417400')).to.throw(Error, 'Invalid UUID: 123e4567-e89b-12d3-a456-42661417400');
     });
 
     test('invalid UUID string that is too long', () => {
-        expect(id.isUUID('123e4567-e89b-12d3-a456-4266141740000')).to.equal(false);
+        expect(() => id.isUUID('123e4567-e89b-12d3-a456-4266141740000')).to.throw(Error, 'Invalid UUID: 123e4567-e89b-12d3-a456-4266141740000');
     });
 
-    test('valid uuid with all zeroes except version control chars', () => {
+    test('valid UUID with all zeroes except version control chars', () => {
         expect(id.isUUID('00000000-0000-4000-8000-000000000000')).to.equal(true);
     });
 
-    test('invalid uuid with missing section', () => {
-        expect(id.isUUID('2eb8aa08-aa98-11ea-73b441d16380')).to.equal(false);
+    test('invalid UUID with missing section', () => {
+        expect(() => id.isUUID('2eb8aa08-aa98-11ea-73b441d16380')).to.throw(Error, 'Invalid UUID: 2eb8aa08-aa98-11ea-73b441d16380');
     });
 
-    test('invalid uuid with too many dashes', () => {
-        expect(id.isUUID('2eb8-aa08-aa98-11ea-b4aa73b44-1d16380')).to.equal(false);
+    test('invalid UUID with too many dashes', () => {
+        expect(() => id.isUUID('2eb8-aa08-aa98-11ea-b4aa73b44-1d16380')).to.throw(Error, 'Invalid UUID: 2eb8-aa08-aa98-11ea-b4aa73b44-1d16380');
     });
 
-    test('invalid uuid with dashes in the wrong spot', () => {
-        expect(id.isUUID('2eb8aa08aa9811eab4aa73b441d16380----')).to.equal(false);
+    test('invalid UUID with dashes in the wrong spot', () => {
+        expect(() => id.isUUID('2eb8aa08aa9811eab4aa73b441d16380----')).to.throw(Error, 'Invalid UUID: 2eb8aa08aa9811eab4aa73b441d16380----');
     });
 
-    test('valid uuid v5', () => {
+    test('valid UUID v5', () => {
         expect(id.isUUID('99c17cbb-656f-564a-940f-1a4568f03487')).to.equal(true);
     });
 
-    test('valid uuid hypothetical v6', () => {
+    test('valid UUID hypothetical v6', () => {
         expect(id.isUUID('99c17cbb-656f-664a-940f-1a4568f03487')).to.equal(true);
     });
 
-    test('valid uuid hypothetical v15', () => {
+    test('valid UUID hypothetical v15', () => {
         expect(id.isUUID('99c17cbb-656f-f64a-940f-1a4568f03487')).to.equal(true);
     });
 });
@@ -81,43 +81,43 @@ describe('isUUIDv4', () => {
     });
 
     test('invalid UUID v4 missing hyphens', () => {
-        expect(id.isUUIDv4('123e4567e89b12d3a456426614174000')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567e89b12d3a456426614174000')).to.throw(Error, 'Invalid UUID-v4: 123e4567e89b12d3a456426614174000');
     });
 
     test('invalid UUID v4 with extra hyphens', () => {
-        expect(id.isUUIDv4('123e4567-e89b-12d3-a456-426-614174000')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567-e89b-12d3-a456-426-614174000')).to.throw(Error, 'Invalid UUID-v4: 123e4567-e89b-12d3-a456-426-614174000');
     });
 
     test('invalid UUID v4 with incorrect group lengths', () => {
-        expect(id.isUUIDv4('123e4567-e89b-12d3-a456426614174000')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567-e89b-12d3-a456426614174000')).to.throw(Error, 'Invalid UUID-v4: 123e4567-e89b-12d3-a456426614174000');
     });
 
     test('invalid UUID v4 with non-hexadecimal characters', () => {
-        expect(id.isUUIDv4('123e4567-e89b-12d3-g456-426614174000')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567-e89b-12d3-g456-426614174000')).to.throw(Error, 'Invalid UUID-v4: 123e4567-e89b-12d3-g456-426614174000');
     });
 
     test('invalid UUID v4 string that is too short', () => {
-        expect(id.isUUIDv4('123e4567-e89b-12d3-a456-42661417400')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567-e89b-12d3-a456-42661417400')).to.throw(Error, 'Invalid UUID-v4: 123e4567-e89b-12d3-a456-42661417400');
     });
 
     test('invalid UUID v4 string that is too long', () => {
-        expect(id.isUUIDv4('123e4567-e89b-12d3-a456-4266141740000')).to.equal(false);
+        expect(() => id.isUUIDv4('123e4567-e89b-12d3-a456-4266141740000')).to.throw(Error, 'Invalid UUID-v4: 123e4567-e89b-12d3-a456-4266141740000');
     });
 
-    test('valid uuid v4 with all zeroes except version control chars', () => {
+    test('valid UUID v4 with all zeroes except version control chars', () => {
         expect(id.isUUIDv4('00000000-0000-4000-8000-000000000000')).to.equal(true);
     });
 
-    test('invalid uuid v4 with missing section', () => {
-        expect(id.isUUIDv4('2eb8aa08-aa98-11ea-73b441d16380')).to.equal(false);
+    test('invalid UUID v4 with missing section', () => {
+        expect(() => id.isUUIDv4('2eb8aa08-aa98-11ea-73b441d16380')).to.throw(Error, 'Invalid UUID-v4: 2eb8aa08-aa98-11ea-73b441d16380');
     });
 
-    test('invalid uuid v4 with too many dashes', () => {
-        expect(id.isUUIDv4('2eb8-aa08-aa98-11ea-b4aa73b44-1d16380')).to.equal(false);
+    test('invalid UUID v4 with too many dashes', () => {
+        expect(() => id.isUUIDv4('2eb8-aa08-aa98-11ea-b4aa73b44-1d16380')).to.throw(Error, 'Invalid UUID-v4: 2eb8-aa08-aa98-11ea-b4aa73b44-1d16380');
     });
 
-    test('invalid uuid v4 with dashes in the wrong spot', () => {
-        expect(id.isUUIDv4('2eb8aa08aa9811eab4aa73b441d16380----')).to.equal(false);
+    test('invalid UUID v4 with dashes in the wrong spot', () => {
+        expect(() => id.isUUIDv4('2eb8aa08aa9811eab4aa73b441d16380----')).to.throw(Error, 'Invalid UUID-v4: 2eb8aa08aa9811eab4aa73b441d16380----');
     });
 });
 
@@ -127,7 +127,7 @@ describe('isUri', () => {
     });
 
     test('Scheme is required', () => {
-        expect(id.isUri('//example.com/foo?bar#baz')).to.equal(false);
+        expect(() => id.isUri('//example.com/foo?bar#baz')).to.throw(Error, 'Invalid URI: //example.com/foo?bar#baz');
     });
 
     test('No authority', () => {
@@ -135,7 +135,7 @@ describe('isUri', () => {
     });
 
     test('No authority starting with double slash', () => {
-        expect(id.isUri('uri://12:34:56/foo?bar#baz')).to.equal(false);
+        expect(() => id.isUri('uri://12:34:56/foo?bar#baz')).to.throw(Error, 'Invalid URI: uri://12:34:56/foo?bar#baz');
     });
 
     test('Rootless path', () => {
@@ -143,7 +143,7 @@ describe('isUri', () => {
     });
 
     test('Unicode is not allowed', () => {
-        expect(id.isUri('http://examplé.org/rosé#')).to.equal(false);
+        expect(() => id.isUri('http://examplé.org/rosé#')).to.throw(Error, 'Invalid URI: http://examplé.org/rosé#');
     });
 });
 
@@ -177,7 +177,7 @@ describe('isUriReference', () => {
     });
 
     test('Unicode is not allowed', () => {
-        expect(id.isUriReference('/rosé#')).to.equal(false);
+        expect(() => id.isUriReference('/rosé#')).to.throw(Error, 'Invalid URI-reference: /rosé#');
     });
 });
 
@@ -187,15 +187,15 @@ describe('isAbsoluteUri', () => {
     });
 
     test('Scheme is required', () => {
-        expect(id.isAbsoluteUri('//example.com/foo?bar')).to.equal(false);
+        expect(() => id.isAbsoluteUri('//example.com/foo?bar')).to.throw(Error, 'Invalid absolute-URI: //example.com/foo?bar');
     });
 
     test('Fragment is not allowed', () => {
-        expect(id.isAbsoluteUri('https://example.com/foo?bar#baz')).to.equal(false);
+        expect(() => id.isAbsoluteUri('https://example.com/foo?bar#baz')).to.throw(Error, 'Invalid absolute-URI: https://example.com/foo?bar#baz');
     });
 
     test('Unicode is not allowed', () => {
-        expect(id.isAbsoluteUri('http://examplé.org/rosé')).to.equal(false);
+        expect(() => id.isAbsoluteUri('http://examplé.org/rosé')).to.throw(Error, 'Invalid absolute-URI: http://examplé.org/rosé');
     });
 });
 
@@ -205,7 +205,7 @@ describe('isIri', () => {
     });
 
     test('Scheme is required', () => {
-        expect(id.isIri('//examplé.com/rosé?fóo#bár')).to.equal(false);
+        expect(() => id.isIri('//examplé.com/rosé?fóo#bár')).to.throw(Error, 'Invalid IRI: //examplé.com/rosé?fóo#bár');
     });
 
     test('No authority', () => {
@@ -213,7 +213,7 @@ describe('isIri', () => {
     });
 
     test('No authority starting with double slash', () => {
-        expect(id.isIri('uri://12:23:45/rosé?fóo#bár')).to.equal(false);
+        expect(() => id.isIri('uri://12:23:45/rosé?fóo#bár')).to.throw(Error, 'Invalid IRI: uri://12:23:45/rosé?fóo#bár');
     });
 
     test('Rootless path', () => {
@@ -221,7 +221,7 @@ describe('isIri', () => {
     });
 
     test('Unicode is not allowed in scheme', () => {
-        expect(id.isAbsoluteIri('examplé://examplé.org/rosé')).to.equal(false);
+        expect(() => id.isIri('examplé://examplé.org/rosé')).to.throw(Error, 'Invalid IRI: examplé://examplé.org/rosé');
     });
 });
 
@@ -265,14 +265,14 @@ describe('isAbsoluteIri', () => {
     });
 
     test('Scheme is required', () => {
-        expect(id.isAbsoluteIri('//examplé.org/rosé?fóo')).to.equal(false);
+        expect(() => id.isAbsoluteIri('//examplé.org/rosé?fóo')).to.throw(Error, 'Invalid absolute-IRI: //examplé.org/rosé?fóo');
     });
 
     test('Fragment is not allowed', () => {
-        expect(id.isAbsoluteIri('http://examplé.org/rosé?fóo#bár')).to.equal(false);
+        expect(() => id.isAbsoluteIri('http://examplé.org/rosé?fóo#bár')).to.throw(Error, 'Invalid absolute-IRI: http://examplé.org/rosé?fóo#bár');
     });
 
     test('Unicode is not allowed in scheme', () => {
-        expect(id.isAbsoluteIri('examplé://examplé.org/rosé')).to.equal(false);
+        expect(() => id.isAbsoluteIri('examplé://examplé.org/rosé')).to.throw(Error, 'Invalid absolute-IRI: examplé://examplé.org/rosé');
     });
 });