parse-domain 3.0.3 → 5.0.0

package/LICENSE

@@ -1,24 +1,21 @@
-This is free and unencumbered software released into the public domain.
+MIT License
 
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
+Copyright (c) 2021 Peerigon GmbH
 
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-For more information, please refer to <http://unlicense.org>
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,36 +7,32 @@
 [![Monthly downloads on NPM](https://img.shields.io/npm/dm/parse-domain?style=for-the-badge)](https://www.npmjs.com/package/parse-domain)<br>
 [![NPM Bundle size minified](https://img.shields.io/bundlephobia/min/parse-domain?style=for-the-badge)](https://bundlephobia.com/result?p=parse-domain)
 [![NPM Bundle size minified and gzipped](https://img.shields.io/bundlephobia/minzip/parse-domain?style=for-the-badge)](https://bundlephobia.com/result?p=parse-domain)<br>
-[![Dependencies status](https://img.shields.io/david/peerigon/parse-domain?style=for-the-badge)](https://david-dm.org/peerigon/parse-domain)
-[![Known Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/parse-domain?style=for-the-badge)](https://snyk.io/test/github/peerigon/parse-domain)<br>
-![Written in TypeScript](https://img.shields.io/npm/types/parse-domain?style=for-the-badge)
-[![Coverage Status](https://img.shields.io/coveralls/github/peerigon/parse-domain?style=for-the-badge)](https://coveralls.io/github/peerigon/parse-domain?branch=master)
-[![License](https://img.shields.io/npm/l/parse-domain?style=for-the-badge)](https://unlicense.org/)
+[![License](https://img.shields.io/npm/l/parse-domain?style=for-the-badge)](./LICENSE)
 
 Since domain name registrars organize their namespaces in different ways, it's not straight-forward to split a hostname into subdomains, the domain and top-level domains. In order to do that **parse-domain** uses a [large list of known top-level domains](https://publicsuffix.org/list/public_suffix_list.dat) from [publicsuffix.org](https://publicsuffix.org/):
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain(
-	// This should be a string with basic latin characters only.
-	// More information below.
-	"www.some.example.co.uk",
+  // This should be a string with basic latin letters only.
+  // More information below.
+  "www.some.example.co.uk"
 );
 
 // Check if the domain is listed in the public suffix list
 if (parseResult.type === ParseResultType.Listed) {
-	const {subDomains, domain, topLevelDomains} = parseResult;
+  const { subDomains, domain, topLevelDomains } = parseResult;
 
-	console.log(subDomains); // ["www", "some"]
-	console.log(domain); // "example"
-	console.log(topLevelDomains); // ["co", "uk"]
+  console.log(subDomains); // ["www", "some"]
+  console.log(domain); // "example"
+  console.log(topLevelDomains); // ["co", "uk"]
 } else {
-	// Read more about other parseResult types below...
+  // Read more about other parseResult types below...
 }
 ```
 
-This package has been designed for modern Node and browser environments, supporting both CommonJS and ECMAScript modules. It assumes an ES2015 environment with [`Symbol()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) and [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL) globally available. You need to transpile it down to ES5 (e.g. by using [Babel](https://babeljs.io/)) if you need to support older environments.
+This package has been designed for modern Node and browser environments, supporting both CommonJS and ECMAScript modules. It assumes an ES2015 environment with [`Symbol()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL) and [`TextDecoder()](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) globally available. You need to transpile it down to ES5 (e.g. by using [Babel](https://babeljs.io/)) if you need to support older environments.
 
 The list of top-level domains is stored in a [trie](https://en.wikipedia.org/wiki/Trie) data structure and serialization format to ensure the fastest lookup and the smallest possible library size. The library is side-effect free (this is important for proper [tree-shaking](https://webpack.js.org/guides/tree-shaking/)).
 
@@ -67,10 +63,10 @@ npm install parse-domain
 There is the utility function [`fromUrl`](#api-js-fromUrl) which tries to extract the hostname from a (partial) URL and puny-encodes it:
 
 ```javascript
-import {parseDomain, fromUrl} from "parse-domain";
+import { parseDomain, fromUrl } from "parse-domain";
 
-const {subDomains, domain, topLevelDomains} = parseDomain(
-	fromUrl("https://www.münchen.de?query"),
+const { subDomains, domain, topLevelDomains } = parseDomain(
+  fromUrl("https://www.münchen.de?query")
 );
 
 console.log(subDomains); // ["www"]
@@ -78,7 +74,7 @@ console.log(domain); // "xn--mnchen-3ya"
 console.log(topLevelDomains); // ["de"]
 
 // You can use the 'punycode' NPM package to decode the domain again
-import {toUnicode} from "punycode";
+import { toUnicode } from "punycode";
 
 console.log(toUnicode(domain)); // "münchen"
 ```
@@ -100,10 +96,10 @@ When parsing a hostname there are 5 possible results:
 
 ### 👉 Invalid domains
 
-The given input is first validated against [RFC 1034](https://tools.ietf.org/html/rfc1034). If the validation fails, `parseResult.type` will be `ParseResultType.Invalid`:
+The given input is first validated against [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696#section-2) (the domain labels are limited to basic latin letters, numbers and hyphens). If the validation fails, `parseResult.type` will be `ParseResultType.Invalid`:
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain("münchen.de");
 
@@ -112,12 +108,26 @@ console.log(parseResult.type === ParseResultType.Invalid); // true
 
 Check out the [API](#api-ts-ValidationError) if you need more information about the validation error.
 
+If you don't want the characters to be validated (e.g. because you need to allow underscores in hostnames), there's also a more relaxed validation mode (according to [RFC 2181](https://www.rfc-editor.org/rfc/rfc2181#section-11)).
+
+```javascript
+import { parseDomain, ParseResultType, Validation } from "parse-domain";
+
+const parseResult = parseDomain("_jabber._tcp.gmail.com", {
+  validation: Validation.Lax,
+});
+
+console.log(parseResult.type === ParseResultType.Listed); // true
+```
+
+See also [#134](https://github.com/peerigon/parse-domain/issues/134) for the discussion.
+
 ### 👉 IP addresses
 
 If the given input is an IP address, `parseResult.type` will be `ParseResultType.Ip`:
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain("192.168.2.1");
 
@@ -140,7 +150,7 @@ There are 5 top-level domains that are not listed in the public suffix list but
 In these cases, `parseResult.type` will be `ParseResultType.Reserved`:
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain("pecorino.local");
 
@@ -153,7 +163,7 @@ console.log(parseResult.labels); // ["pecorino", "local"]
 If the given hostname is valid, but not listed in the downloaded public suffix list, `parseResult.type` will be `ParseResultType.NotListed`:
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain("this.is.not-listed");
 
@@ -179,7 +189,7 @@ Some examples for public suffixes:
 If the hostname is listed in the public suffix list, the `parseResult.type` will be `ParseResultType.Listed`:
 
 ```javascript
-import {parseDomain, ParseResultType} from "parse-domain";
+import { parseDomain, ParseResultType } from "parse-domain";
 
 const parseResult = parseDomain("example.co.uk");
 
@@ -190,7 +200,7 @@ console.log(parseResult.labels); // ["example", "co", "uk"]
 Now `parseResult` will also provide a `subDomains`, `domain` and `topLevelDomains` property:
 
 ```javascript
-const {subDomains, domain, topLevelDomains} = parseResult;
+const { subDomains, domain, topLevelDomains } = parseResult;
 
 console.log(subDomains); // []
 console.log(domain); // "example"
@@ -203,21 +213,21 @@ We recommend switching over the `parseResult.type`:
 
 ```javascript
 switch (parseResult.type) {
-	case ParseResultType.Listed: {
-		const {hostname, topLevelDomains} = parseResult;
-
-		console.log(`${hostname} belongs to ${topLevelDomains.join(".")}`);
-		break;
-	}
-	case ParseResultType.Reserved:
-	case ParseResultType.NotListed: {
-		const {hostname} = parseResult;
-
-		console.log(`${hostname} is a reserved or unknown domain`);
-		break;
-	}
-	default:
-		throw new Error(`${hostname} is an ip address or invalid domain`);
+  case ParseResultType.Listed: {
+    const { hostname, topLevelDomains } = parseResult;
+
+    console.log(`${hostname} belongs to ${topLevelDomains.join(".")}`);
+    break;
+  }
+  case ParseResultType.Reserved:
+  case ParseResultType.NotListed: {
+    const { hostname } = parseResult;
+
+    console.log(`${hostname} is a reserved or unknown domain`);
+    break;
+  }
+  default:
+    throw new Error(`${hostname} is an ip address or invalid domain`);
 }
 ```
 
@@ -226,8 +236,8 @@ switch (parseResult.type) {
 What's surprising to a lot of people is that the definition of public suffix means that regular user domains can become effective top-level domains:
 
 ```javascript
-const {subDomains, domain, topLevelDomains} = parseDomain(
-	"parse-domain.github.io",
+const { subDomains, domain, topLevelDomains } = parseDomain(
+  "parse-domain.github.io"
 );
 
 console.log(subDomains); // []
@@ -241,7 +251,7 @@ If you want to deviate from the browser's understanding of a top-level domain an
 
 ```javascript
 const parseResult = parseDomain("parse-domain.github.io");
-const {subDomains, domain, topLevelDomains} = parseResult.icann;
+const { subDomains, domain, topLevelDomains } = parseResult.icann;
 
 console.log(subDomains); // ["parse-domain"]
 console.log(domain); // "github"
@@ -251,7 +261,7 @@ console.log(topLevelDomains); // ["io"]
 ### ⚠️ `domain` can also be `undefined`
 
 ```javascript
-const {subDomains, domain, topLevelDomains} = parseDomain("co.uk");
+const { subDomains, domain, topLevelDomains } = parseDomain("co.uk");
 
 console.log(subDomains); // []
 console.log(domain); // undefined
@@ -263,7 +273,7 @@ console.log(topLevelDomains); // ["co", "uk"]
 The empty string `""` represents the [DNS root](https://en.wikipedia.org/wiki/DNS_root_zone) and is considered to be valid. `parseResult.type` will be `ParseResultType.Reserved` in that case:
 
 ```javascript
-const {type, subDomains, domain, topLevelDomains} = parseDomain("");
+const { type, subDomains, domain, topLevelDomains } = parseDomain("");
 
 console.log(type === ParseResultType.Reserved); // true
 console.log(subDomains); // []
@@ -277,17 +287,27 @@ console.log(topLevelDomains); // []
 🧬 = TypeScript export
 
 <h3 id="api-js-parseDomain">
-🧩 <code>export parseDomain(hostname: string | typeof <a href="#api-js-NO_HOSTNAME">NO_HOSTNAME</a>): <a href="#api-ts-ParseResult">ParseResult</a></code>
+🧩 <code>export parseDomain(hostname: string | typeof <a href="#api-js-NO_HOSTNAME">NO_HOSTNAME</a>, options?: <a href="#api-ts-ParseDomainOptions">ParseDomainOptions</a>): <a href="#api-ts-ParseResult">ParseResult</a></code>
 </h3>
 
-Takes a hostname (e.g. `"www.example.com"`) and returns a [`ParseResult`](#api-ts-ParseResult). The hostname must only contain basic latin characters, digits, hyphens and dots. International hostnames must be puny-encoded. Does not throw an error, even with invalid input.
+Takes a hostname (e.g. `"www.example.com"`) and returns a [`ParseResult`](#api-ts-ParseResult). The hostname must only contain basic latin letters, digits, hyphens and dots. International hostnames must be puny-encoded. Does not throw an error, even with invalid input.
 
 ```javascript
-import {parseDomain} from "parse-domain";
+import { parseDomain } from "parse-domain";
 
 const parseResult = parseDomain("www.example.com");
 ```
 
+Use `Validation.Lax` if you want to allow all characters:
+
+```javascript
+import { parseDomain, Validation } from "parse-domain";
+
+const parseResult = parseDomain("_jabber._tcp.gmail.com", {
+  validation: Validation.Lax,
+});
+```
+
 <h3 id="api-js-fromUrl">
 🧩 <code>export fromUrl(input: string): string | typeof <a href="#api-js-NO_HOSTNAME">NO_HOSTNAME</a></code>
 </h3>
@@ -300,6 +320,54 @@ Takes a URL-like string and tries to extract the hostname. Requires the global [
 
 `NO_HOSTNAME` is a symbol that is returned by [`fromUrl`](#api-js-fromUrl) when it was not able to extract a hostname from the given string. When passed to [`parseDomain`](#api-js-parseDomain), it will always yield a [`ParseResultInvalid`](#api-ts-ParseResultInvalid).
 
+<h3 id="api-ts-ParseDomainOptions">
+🧬 <code>export type ParseDomainOptions</code>
+</h3>
+
+```ts
+export type ParseDomainOptions = {
+  /**
+   * If no validation is specified, Validation.Strict will be used.
+   **/
+  validation?: Validation;
+};
+```
+
+<h3 id="api-js-Validation">
+🧩 <code>export Validation</code>
+</h3>
+
+An object that holds all possible [Validation](#api-ts-Validation) `validation` values:
+
+```javascript
+export const Validation = {
+  /**
+   * Allows any octets as labels
+   * but still restricts the length of labels and the overall domain.
+   *
+   * @see https://www.rfc-editor.org/rfc/rfc2181#section-11
+   **/
+  Lax: "LAX",
+
+  /**
+   * Only allows ASCII letters, digits and hyphens (aka LDH),
+   * forbids hyphens at the beginning or end of a label
+   * and requires top-level domain names not to be all-numeric.
+   *
+   * This is the default if no validation is configured.
+   *
+   * @see https://datatracker.ietf.org/doc/html/rfc3696#section-2
+   */
+  Strict: "STRICT",
+};
+```
+
+<h3 id="api-ts-Validation">
+🧬 <code>export Validation</code>
+</h3>
+
+This type represents all possible `validation` values.
+
 <h3 id="api-ts-ParseResult">
 🧬 <code>export ParseResult</code>
 </h3>
@@ -318,11 +386,11 @@ An object that holds all possible [ParseResult](#api-ts-ParseResult) `type` valu
 
 ```javascript
 const ParseResultType = {
-	Invalid: "INVALID",
-	Ip: "IP",
-	Reserved: "RESERVED",
-	NotListed: "NOT_LISTED",
-	Listed: "LISTED",
+  Invalid: "INVALID",
+  Ip: "IP",
+  Reserved: "RESERVED",
+  NotListed: "NOT_LISTED",
+  Listed: "LISTED",
 };
 ```
 
@@ -390,11 +458,12 @@ An object that holds all possible [ValidationError](#api-ts-ValidationError) `ty
 
 ```javascript
 const ValidationErrorType = {
-	NoHostname: "NO_HOSTNAME",
-	DomainMaxLength: "DOMAIN_MAX_LENGTH",
-	LabelMinLength: "LABEL_MIN_LENGTH",
-	LabelMaxLength: "LABEL_MAX_LENGTH",
-	LabelInvalidCharacter: "LABEL_INVALID_CHARACTER",
+  NoHostname: "NO_HOSTNAME",
+  DomainMaxLength: "DOMAIN_MAX_LENGTH",
+  LabelMinLength: "LABEL_MIN_LENGTH",
+  LabelMaxLength: "LABEL_MAX_LENGTH",
+  LabelInvalidCharacter: "LABEL_INVALID_CHARACTER",
+  LastLabelInvalid: "LAST_LABEL_INVALID",
 };
 ```
 
@@ -525,7 +594,7 @@ type ParseResultListed = {
 
 ## License
 
-Unlicense
+MIT
 
 ## Sponsors
 

package/bin/update.js

@@ -2,24 +2,24 @@
 
 "use strict";
 
-const {EOL} = require("os");
+const { EOL } = require("os");
 
 (async () => {
-	process.argv.push(
-		"--",
-		"../../serialized-tries",
-		"../../../build-esm/serialized-tries",
-	);
+  process.argv.push(
+    "--",
+    "../../serialized-tries",
+    "../../../build-esm/serialized-tries"
+  );
 
-	await require("../build-cjs/src/scripts/update-tries.js").done;
+  await require("../build-cjs/src/scripts/update-tries.js").done;
 
-	process.stderr.write("Running smoke test... ");
+  process.stderr.write("Running smoke test... ");
 
-	require("../build-cjs/src/smoke-test.js").runSmokeTest();
+  require("../build-cjs/src/smoke-test.js").runSmokeTest();
 
-	process.stdout.write("ok" + EOL);
+  process.stdout.write("ok" + EOL);
 })().catch((error) => {
-	console.error(`parse-domain update failed: ${error}`);
-	// eslint-disable-next-line no-process-exit
-	process.exit(1);
+  console.error(`parse-domain update failed: ${error}`);
+  // eslint-disable-next-line no-process-exit, node/no-process-exit
+  process.exit(1);
 });