JS Domain Parser

JS Domain Parser is a lightweight JavaScript library designed to parse and extract detailed information from URLs. It supports detecting TLDs (Top-Level Domains), handling private and unknown TLDs, and extending the TLD list with custom values.

Features

• Extracts detailed URL components (protocol, domain, hostname, path, etc.).
• Detects TLDs using a comprehensive list of ICANN and private TLDs.
• Supports custom TLDs via configuration.
• Allows toggling support for private and unknown TLDs.
• Supports all protocols (e.g., http, https, ssh, ftp, telnet, etc.).

Installation

1npm install jsdomain-parser

---

or you can include jsdomain-parser directly in your project by adding the following <script> tag to your HTML file:

1<script src="./dist/jsdomain-parser.umd.min.js"></script>

This will expose the jsDomainParser global object in the browser.

Usage

Example 1: Basic Parsing

1import { parse } from "jsdomain-parser";
2
3const url = "https://www.example.com/path?query=test#hash";
4const result = parse(url);
5
6console.log(result);

Output:

1{
2  "tld": {
3    "name": "com",
4    "length": 1,
5    "parts": ["com"]
6  },
7  "url": {
8    "domain": "example.com",
9    "origin": "https://www.example.com",
10    "protocol": "https:",
11    "host": "www.example.com",
12    "hostname": "www.example.com",
13    "port": "",
14    "pathname": "/path",
15    "search": "?query=test",
16    "hash": "#hash",
17    "query": {
18      "query": "test"
19    }
20  }
21}

Example 2: Using Custom Options

1const url = "my.custom.tld";
2
3const result = parse(url, {
4  allowPrivate: true, // Enable private TLDs
5  allowUnknown: false, // Disallow unknown TLDs
6  extendedTlds: ["custom.tld", "tld"], // Add custom TLDs
7});
8
9console.log(result);

Output:

1{
2  "tld": {
3    "name": "custom.tld",
4    "length": 2,
5    "parts": ["custom", "tld"]
6  },
7  "url": {
8    "domain": "my.custom.tld",
9    "origin": "http://my.custom.tld",
10    "protocol": "http:",
11    "host": "my.custom.tld",
12    "hostname": "my.custom.tld",
13    "port": "",
14    "pathname": "/",
15    "search": "",
16    "hash": "",
17    "query": {}
18  }
19}

Example 3: Error Handling

1try {
2  const result = parse("invalid-url");
3  console.log(result);
4} catch (e) {
5  console.error("Error:", e.message);
6}

Output:

Error: Invalid URL: Invalid URL: Error: Could not detect TLD. You can set allowUnknown to true for allowing unknown TLDs.

API Reference

parse(url, options = {})

Parses a URL string and returns an object containing TLD and URL details.

• url: The URL to parse (string).
• options (object): Optional configurations:
  • allowPrivate (boolean): Allow private TLDs (default: true).
  • allowUnknown (boolean): Allow unknown TLDs (default: false).
  • extendedTlds (array): Array of custom TLDs to extend the list.

Returns: An object with the following structure:

• tld: Details of the detected TLD.
  • name: The TLD name.
  • length: The number of parts in the TLD.
  • parts: An array of the TLD parts.
• url: Details of the parsed URL.
  • domain: The domain name.
  • origin: The full URL origin.
  • protocol: The protocol (e.g., http:).
  • host: The host.
  • hostname: The hostname.
  • port: The port (if any).
  • pathname: The path.
  • search: The query string.
  • hash: The hash fragment.
  • query: An object representation of query parameters.