### Install tldts-icann with npm

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Install the tldts-icann package using npm.

```bash
npm install --save tldts-icann
```

--------------------------------

### Install tldts with npm

Source: https://github.com/remusao/tldts/blob/master/README.md

Install the tldts package using npm. This is the first step to using the library in your project.

```bash
npm install --save tldts
```

--------------------------------

### Install tldts packages

Source: https://context7.com/remusao/tldts/llms.txt

Install the main tldts package or one of its variants for different use cases.

```bash
# Main package (recommended)
npm install tldts
```

```bash
# ICANN-only variant (no isIcann/isPrivate on result)
npm install tldts-icann
```

```bash
# Experimental probabilistic variant (smallest, fastest, rare false positives)
npm install tldts-experimental
```

```bash
# Core primitives (for building custom lookup back-ends)
npm install tldts-core
```

--------------------------------

### psl Library Default Behavior Example

Source: https://github.com/remusao/tldts/blob/master/README.md

Demonstrates the default behavior of the 'psl' library when parsing a URL, showing that the public suffix can be from the private section.

```javascript
const psl = require('psl');

psl.parse('https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv');
// {
//   input: 'spark-public.s3.amazonaws.com',
//   tld: 's3.amazonaws.com',
//   sld: 'spark-public',
//   domain: 'spark-public.s3.amazonaws.com',
//   subdomain: null,
//   listed: true
// }
```

--------------------------------

### Get Domain with tldts vs psl

Source: https://github.com/remusao/tldts/blob/master/README.md

Compares extracting the domain using tldts's `getDomain` function versus psl's `get` function. Using dedicated functions like `getDomain` is more efficient than using the generic `parse` function.

```javascript
tldts.getDomain('spark-public.s3.amazonaws.com', { allowPrivateDomains: true })
```

```javascript
psl.get('spark-public.s3.amazonaws.com')
```

--------------------------------

### tldts-experimental Parse Example

Source: https://context7.com/remusao/tldts/llms.txt

Showcases the tldts-experimental variant, offering a smaller bundle size and faster performance using probabilistic data structures. It has an identical API to tldts but may have rare false positives.

```javascript
import { parse, getPublicSuffix, getDomain, getSubdomain } from 'tldts-experimental';

// Identical API to tldts — just swap the import
parse('https://www.example.co.uk/path');
// {
//   domain: 'example.co.uk',
//   domainWithoutSuffix: 'example',
//   hostname: 'www.example.co.uk',
//   isIcann: true,
//   isIp: false,
//   isPrivate: false,
//   publicSuffix: 'co.uk',
//   subdomain: 'www'
// }

// Batch processing millions of URLs (2-3M+ ops/sec)
const urls = ['https://a.example.com', 'https://b.test.co.uk', 'https://192.168.1.1'];
const results = urls.map(u => getDomain(u));
// ['example.com', 'test.co.uk', null]

getSubdomain('deep.nested.sub.example.com'); // 'deep.nested.sub'
getPublicSuffix('foo.bar.blogspot.com', { allowPrivateDomains: true }); // 'blogspot.com'
```

--------------------------------

### tldts Default Behavior Example

Source: https://github.com/remusao/tldts/blob/master/README.md

Shows the default behavior of tldts when parsing a hostname, where it prioritizes ICANN public suffixes over private ones.

```javascript
const { parse } = require('tldts');

parse('spark-public.s3.amazonaws.com');
// {
//   domain: 'amazonaws.com',
//   domainWithoutSuffix: 'amazonaws',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIcann: true,
//   isIp: false,
//   isPrivate: false,
//   publicSuffix: 'com',
//   subdomain: 'spark-public.s3'
// }
```

--------------------------------

### tldts-icann Parse Example

Source: https://context7.com/remusao/tldts/llms.txt

Demonstrates parsing with the tldts-icann variant, which only uses the ICANN portion of the Public Suffix List. Private domains can still be queried explicitly.

```javascript
import { parse, getDomain, getPublicSuffix } from 'tldts-icann';

parse('http://www.writethedocs.org/conf/eu/2017/');
// {
//   domain: 'writethedocs.org',
//   domainWithoutSuffix: 'writethedocs',
//   hostname: 'www.writethedocs.org',
//   isIp: false,
//   publicSuffix: 'org',
//   subdomain: 'www'
// }

// Private domains can still be queried explicitly
parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true });
// { domain: 'spark-public.s3.amazonaws.com', publicSuffix: 's3.amazonaws.com', ... }

getPublicSuffix('s3.amazonaws.com');          // 'com'  (no Private by default)
getDomain('localhost', { validHosts: ['localhost'] }); // 'localhost'
```

--------------------------------

### Get Public Suffix

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Use `getPublicSuffix` to identify the public suffix of a hostname. An optional `allowPrivateDomains` option can be provided.

```javascript
const { getPublicSuffix } = require('tldts');

getPublicSuffix('google.com'); // returns `com`
getPublicSuffix('fr.google.com'); // returns `com`
getPublicSuffix('google.co.uk'); // returns `co.uk`
getPublicSuffix('s3.amazonaws.com'); // returns `com`
getPublicSuffix('s3.amazonaws.com', { allowPrivateDomains: true }); // returns `s3.amazonaws.com`
getPublicSuffix('tld.is.unknown'); // returns `unknown`
```

--------------------------------

### Get Domain with Private Domains Allowed

Source: https://github.com/remusao/tldts/blob/master/README.md

Use getDomain with allowPrivateDomains: true to include private domains in the result. This is useful for internal hostnames.

```javascript
console.log(getDomain(url, { allowPrivateDomains: true })); // spark-public.s3.amazonaws.com
```

--------------------------------

### Get Subdomain

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Employ `getSubdomain` to extract the subdomain part of a given hostname. It returns an empty string if no subdomain is present.

```javascript
const { getSubdomain } = require('tldts');

getSubdomain('google.com'); // returns ``
getSubdomain('fr.google.com'); // returns `fr`
getSubdomain('google.co.uk'); // returns ``
getSubdomain('foo.google.co.uk'); // returns `foo`
getSubdomain('moar.foo.google.co.uk'); // returns `moar.foo`
getSubdomain('t.co'); // returns ``
getSubdomain('fr.t.co'); // returns `fr`
getSubdomain(
  'https://user:password@secure.example.co.uk:443/some/path?and&query#hash',
); // returns `secure`
```

--------------------------------

### Get Subdomain from URL or Hostname

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Extracts the complete subdomain from a given string. Returns an empty string if no subdomain is present.

```javascript
const { getSubdomain } = require('tldts-icann');

getSubdomain('google.com'); // returns ``
getSubdomain('fr.google.com'); // returns `fr`
getSubdomain('google.co.uk'); // returns ``
getSubdomain('foo.google.co.uk'); // returns `foo`
getSubdomain('moar.foo.google.co.uk'); // returns `moar.foo`
getSubdomain('t.co'); // returns ``
getSubdomain('fr.t.co'); // returns `fr`
getSubdomain(
  'https://user:password@secure.example.co.uk:443/some/path?and&query#hash'
); // returns `secure`
```

--------------------------------

### Parse full URL or hostname with tldts

Source: https://context7.com/remusao/tldts/llms.txt

Use the `parse` function to get all components of a URL or hostname. It handles schemes, ports, paths, queries, and fragments automatically. Enable `allowPrivateDomains` option to include private suffixes.

```javascript
import { parse } from 'tldts';

// Plain hostname
parse('www.writethedocs.org');
// {
//   domain: 'writethedocs.org',
//   domainWithoutSuffix: 'writethedocs',
//   hostname: 'www.writethedocs.org',
//   isIcann: true,
//   isIp: false,
//   isPrivate: false,
//   publicSuffix: 'org',
//   subdomain: 'www'
// }
```

```javascript
// Full URL (scheme, port, path, query, hash all stripped automatically)
parse('https://user:pass@secure.example.co.uk:8080/some/path?q=1#anchor');
// {
//   domain: 'example.co.uk',
//   domainWithoutSuffix: 'example',
//   hostname: 'secure.example.co.uk',
//   isIcann: true,
//   isIp: false,
//   isPrivate: false,
//   publicSuffix: 'co.uk',
//   subdomain: 'secure'
// }
```

```javascript
// Private suffix (e.g. S3 subdomain) — default ignores Private section
parse('spark-public.s3.amazonaws.com');
// { domain: 'amazonaws.com', publicSuffix: 'com', isPrivate: false, ... }
```

```javascript
// Enable Private section of the Public Suffix List
parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true });
// {
//   domain: 'spark-public.s3.amazonaws.com',
//   domainWithoutSuffix: 'spark-public',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIcann: false,
//   isIp: false,
//   isPrivate: true,
//   publicSuffix: 's3.amazonaws.com',
//   subdomain: ''
// }
```

```javascript
// IPv4 address
parse('https://192.168.0.1/admin');
// { hostname: '192.168.0.1', isIp: true, domain: null, publicSuffix: null, subdomain: null, ... }
```

```javascript
// IPv6 address
parse('https://[::1]:3000/api');
// { hostname: '::1', isIp: true, domain: null, publicSuffix: null, subdomain: null, ... }
```

```javascript
// Email address
parse('user@emailprovider.co.uk');
// { domain: 'emailprovider.co.uk', publicSuffix: 'co.uk', subdomain: '', hostname: 'emailprovider.co.uk', ... }
```

```javascript
// Unknown / unregistered TLD — still parses, isIcann: false
parse('gopher://domain.unknown/');
// { domain: 'domain.unknown', publicSuffix: 'unknown', isIcann: false, isPrivate: false, ... }
```

--------------------------------

### Get Subdomain with Private Domains Allowed

Source: https://github.com/remusao/tldts/blob/master/README.md

Use getSubdomain with allowPrivateDomains: true to extract the subdomain. Returns an empty string if no subdomain is found.

```javascript
console.log(getSubdomain(url, { allowPrivateDomains: true })); // ''
```

--------------------------------

### Get Public Suffix with Private Domains Allowed

Source: https://github.com/remusao/tldts/blob/master/README.md

Use getPublicSuffix with allowPrivateDomains: true to retrieve the public suffix, even for domains that might be considered private.

```javascript
console.log(getPublicSuffix(url, { allowPrivateDomains: true })); // s3.amazonaws.com
```

--------------------------------

### Get Fully Qualified Domain Name

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Use `getDomain` to extract the fully qualified domain from various URL or hostname formats. It handles subdomains and complex TLDs.

```javascript
const { getDomain } = require('tldts');

getDomain('google.com'); // returns `google.com`
getDomain('fr.google.com'); // returns `google.com`
getDomain('fr.google.google'); // returns `google.google`
getDomain('foo.google.co.uk'); // returns `google.co.uk`
getDomain('t.co'); // returns `t.co`
getDomain('fr.t.co'); // returns `t.co`
getDomain('https://user:password@example.co.uk:8080/some/path?and&query#hash'); // returns `example.co.uk`
```

--------------------------------

### Custom Suffix Lookup with tldts-core

Source: https://context7.com/remusao/tldts/llms.txt

Implement a custom suffix lookup function using `tldts-core`. This example demonstrates how to integrate custom logic for recognizing '.internal' as a valid suffix and provides a fallback mechanism. The `myLookup` function must populate the `out` object in place.

```typescript
import {
  parseImpl,
  FLAG,
  getEmptyResult,
  IOptions,
  IResult,
  IPublicSuffix,
  ISuffixLookupOptions,
  fastPathLookup,
} from 'tldts-core';

// Custom suffix lookup function — must populate `out` in place
function myLookup(
  hostname: string,
  options: ISuffixLookupOptions,
  out: IPublicSuffix,
): void {
  // Try the built-in fast path first (.com, .org, .net, .edu, .gov, .de)
  if (fastPathLookup(hostname, options, out)) return;

  // Custom logic: treat '.internal' as a valid ICANN-like suffix
  if (hostname.endsWith('.internal')) {
    out.isIcann = true;
    out.isPrivate = false;
    out.publicSuffix = 'internal';
    return;
  }

  // Fallback: extract last label as publicSuffix
  const dot = hostname.lastIndexOf('.');
  out.publicSuffix = dot !== -1 ? hostname.slice(dot + 1) : null;
  out.isIcann = false;
  out.isPrivate = false;
}

// Wire into parseImpl
function customParse(url: string, options: Partial<IOptions> = {}): IResult {
  return parseImpl(url, FLAG.ALL, myLookup, options, getEmptyResult());
}

customParse('api.service.internal');
// { hostname: 'api.service.internal', domain: 'service.internal',
//   publicSuffix: 'internal', subdomain: 'api', domainWithoutSuffix: 'service',
//   isIp: false, isIcann: true, isPrivate: false }

customParse('192.168.1.10');
// { hostname: '192.168.1.10', isIp: true, domain: null, ... }
```

--------------------------------

### Get Domain Without Suffix with Private Domains Allowed

Source: https://github.com/remusao/tldts/blob/master/README.md

Use getDomainWithoutSuffix with allowPrivateDomains: true to get the domain part excluding the public suffix, useful for identifying the main domain name.

```javascript
console.log(getDomainWithoutSuffix(url, { allowPrivateDomains: true })); // spark-public
```

--------------------------------

### Handle Custom Hostnames with Options

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Configure `tldts` methods to recognize custom hostnames like 'localhost' by providing a `validHosts` array in the options.

```javascript
const tldts = require('tldts');

tldts.getDomain('localhost'); // returns null
tldts.getSubdomain('vhost.localhost'); // returns null

tldts.getDomain('localhost', { validHosts: ['localhost'] }); // returns 'localhost'
tldts.getSubdomain('vhost.localhost', { validHosts: ['localhost'] }); // returns 'vhost'
```

--------------------------------

### Get Hostname from Subdomain

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Retrieves the hostname from a string containing a subdomain. This function efficiently extracts the full hostname.

```javascript
getHostname('fr.google.com'); // returns `fr.google.com`
getHostname('fr.google.google'); // returns `fr.google.google`
getHostname('foo.google.co.uk'); // returns `foo.google.co.uk`
getHostname('t.co'); // returns `t.co`
getHostname('fr.t.co'); // returns `fr.t.co`
```

--------------------------------

### Troubleshooting: Localhost and Custom Hostnames

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Guidance on how to handle 'localhost' and other custom hostnames, which are not standard TLDs, by using the `validHosts` option.

```APIDOC
## Retrieving subdomain of `localhost` and custom hostnames

### Description
`tldts` methods `getDomain` and `getSubdomain` are designed to work only with known and valid TLDs. To work with custom hosts like 'localhost', you can pass the `validHosts` option.

### Method
`getDomain`, `getSubdomain` with `validHosts` option

### Parameters
#### Path Parameters
- **url | hostname** (string) - Required - The URL or hostname string to parse.
- **options** (object) - Optional - Configuration options. Include `validHosts` array.
  - **validHosts** (array) - Required - An array of strings representing valid hosts.

### Request Example
```javascript
const tldts = require('tldts-icann');

console.log(tldts.getDomain('localhost')); // returns null
console.log(tldts.getSubdomain('vhost.localhost')); // returns null

console.log(tldts.getDomain('localhost', { validHosts: ['localhost'] })); // returns 'localhost'
console.log(tldts.getSubdomain('vhost.localhost', { validHosts: ['localhost'] })); // returns 'vhost'
```

### Response
#### Success Response (string | null)
- Returns the extracted domain or subdomain, or null if not applicable or not configured.

#### Response Example
```json
"localhost"
```
```

--------------------------------

### Handling Custom Hosts like 'localhost'

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Demonstrates how to use the 'validHosts' option to correctly parse custom hostnames like 'localhost' which are not standard TLDs.

```javascript
const tldts = require('tldts-icann');

tldts.getDomain('localhost'); // returns null
tldts.getSubdomain('vhost.localhost'); // returns null

tldts.getDomain('localhost', { validHosts: ['localhost'] }); // returns 'localhost'
tldts.getSubdomain('vhost.localhost', { validHosts: ['localhost'] }); // returns 'vhost'
```

--------------------------------

### Get Hostname from Simple Domain

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Retrieves the hostname from a simple domain string. This function is optimized for extracting only the hostname.

```javascript
const { getHostname } = require('tldts');

getHostname('google.com'); // returns `google.com`
```

--------------------------------

### tldts CLI Usage

Source: https://context7.com/remusao/tldts/llms.txt

Demonstrates how to use the tldts command-line interface for parsing single URLs or processing line-delimited URLs from standard input.

```bash
# Single URL
npx tldts 'http://www.writethedocs.org/conf/eu/2017/'
# {
#   "domain": "writethedocs.org",

```

--------------------------------

### Parse URL with tldts vs psl

Source: https://github.com/remusao/tldts/blob/master/README.md

Demonstrates parsing a URL using tldts, which directly accepts URLs, compared to psl, which requires extracting the hostname first. tldts simplifies URL parsing by handling hostnames internally.

```javascript
tldts.parse('https://spark-public.s3.amazonaws.com/data', { allowPrivateDomains: true })
```

```javascript
psl.parse(new URL('https://spark-public.s3.amazonaws.com/data').hostname)
```

--------------------------------

### tldts getDomain function with options

Source: https://context7.com/remusao/tldts/llms.txt

Demonstrates how to use the `getDomain` function from the `tldts` library with custom `validHosts` option.

```APIDOC
## `getDomain(input, options?)`

### Description
Extracts the domain name from a given input string, optionally using custom valid hosts.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options (`Partial<IOptions>`)
- **validHosts** (string[] | null) - Optional - Extra TLD-like strings treated as valid suffixes, e.g. ['localhost'] (default: null)

### Request Example
```javascript
import { getDomain } from 'tldts';

getDomain('service.cluster.local', { validHosts: ['cluster.local'] });
```

### Response
#### Success Response (string | null)
Returns the extracted domain name or null if it cannot be determined.

#### Response Example
```json
"service.cluster.local"
```
```

--------------------------------

### Get Public Suffix from Hostname

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Returns the public suffix for a given hostname. This is useful for identifying the top-level domain and its preceding parts.

```javascript
const { getPublicSuffix } = require('tldts-icann');

getPublicSuffix('google.com'); // returns `com`
getPublicSuffix('fr.google.com'); // returns `com`
getPublicSuffix('google.co.uk'); // returns `co.uk`
getPublicSuffix('s3.amazonaws.com'); // returns `com`
getPublicSuffix('tld.is.unknown'); // returns `unknown`
```

--------------------------------

### Get Domain Without Public Suffix

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Returns the domain part of a hostname, excluding the public suffix. This isolates the registrable domain.

```javascript
const { getDomainWithoutSuffix } = require('tldts-icann');

getDomainWithoutSuffix('google.com'); // returns `google`
getDomainWithoutSuffix('fr.google.com'); // returns `google`
getDomainWithoutSuffix('fr.google.google'); // returns `google`
getDomainWithoutSuffix('foo.google.co.uk'); // returns `google`
getDomainWithoutSuffix('t.co'); // returns `t`
getDomainWithoutSuffix('fr.t.co'); // returns `t`
getDomainWithoutSuffix(
  'https://user:password@example.co.uk:8080/some/path?and&query#hash'
); // returns `example`
```

--------------------------------

### tldts CLI usage

Source: https://context7.com/remusao/tldts/llms.txt

Shows how to use the `tldts` command-line interface for parsing single URLs or batch processing from standard input.

```APIDOC
## CLI — Command-line interface

### Description
The `tldts` CLI can be invoked using `npx tldts`. It accepts a single URL as an argument or reads line-delimited URLs from STDIN for batch processing.

### Usage

#### Single URL
```bash
npx tldts 'http://www.writethedocs.org/conf/eu/2017/'
```

#### Batch Processing (from STDIN)
```bash
cat urls.txt | npx tldts
```

### Output Format
JSON

### Example Output (Single URL)
```json
{
  "domain": "writethedocs.org",
  "domainWithoutSuffix": "writethedocs",
  "hostname": "www.writethedocs.org",
  "isIp": false,
  "publicSuffix": "org",
  "subdomain": "www"
}
```
```

--------------------------------

### Batch URL parsing with CLI

Source: https://github.com/remusao/tldts/blob/master/README.md

Process multiple URLs from standard input using the command-line interface. Each URL will be parsed and its components displayed.

```js
$ echo "http://www.writethedocs.org/\nhttps://example.com" | npx tldts
{
  "domain": "writethedocs.org",
  "domainWithoutSuffix": "writethedocs",
  "hostname": "www.writethedocs.org",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "org",
  "subdomain": "www"
}
{
  "domain": "example.com",
  "domainWithoutSuffix": "example",
  "hostname": "example.com",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "com",
  "subdomain": ""
}
```

--------------------------------

### Parse URL with CommonJS and options

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Parse a URL using the tldts-icann library with CommonJS, demonstrating different options and inputs.

```javascript
const tldts = require('tldts-icann');

tldts.parse('https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv');
// { domain: 'amazonaws.com',
//   domainWithoutSuffix: 'amazonaws',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIp: false,
//   publicSuffix: 'com',
//   subdomain: 'spark-public.s3' }

tldts.parse(
  'https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv',
  { allowPrivateDomains: true },
);
// { domain: 'spark-public.s3.amazonaws.com',
//   domainWithoutSuffix: 'spark-public',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIp: false,
//   publicSuffix: 's3.amazonaws.com',
//   subdomain: '' }

tldts.parse('gopher://domain.unknown/');
// { domain: 'domain.unknown',
//   domainWithoutSuffix: 'domain',
//   hostname: 'domain.unknown',
//   isIp: false,
//   publicSuffix: 'unknown',
//   subdomain: '' }

tldts.parse('https://192.168.0.0'); // IPv4
// { domain: null,
//   domainWithoutSuffix: null,
//   hostname: '192.168.0.0',
//   isIp: true,
//   publicSuffix: null,
//   subdomain: null }

tldts.parse('https://[::1]'); // IPv6
// { domain: null,
//   domainWithoutSuffix: null,
//   hostname: '::1',
//   isIp: true,
//   publicSuffix: null,
//   subdomain: null }

tldts.parse('tldts@emailprovider.co.uk'); // email
// { domain: 'emailprovider.co.uk',
//   domainWithoutSuffix: 'emailprovider',
//   hostname: 'emailprovider.co.uk',
//   isIp: false,
//   publicSuffix: 'co.uk',
//   subdomain: '' }
```

--------------------------------

### tldts parse function with options

Source: https://context7.com/remusao/tldts/llms.txt

Demonstrates how to use the `parse` function from the `tldts` library with various options to customize domain parsing behavior.

```APIDOC
## `parse(input, options?)`

### Description
Parses a given input string (URL or hostname) and returns detailed information about the domain.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options (`Partial<IOptions>`)
- **allowIcannDomains** (boolean) - Optional - Use suffixes from the ICANN section (default: true)
- **allowPrivateDomains** (boolean) - Optional - Use suffixes from the Private section (default: false)
- **extractHostname** (boolean) - Optional - Parse the hostname from the input; set false if input is already a hostname (default: true)
- **validateHostname** (boolean) - Optional - Reject malformed hostnames before lookup (default: true)
- **detectIp** (boolean) - Optional - Detect and short-circuit on IP addresses (default: true)
- **mixedInputs** (boolean) - Optional - Accept both raw hostnames and full URLs (default: true)
- **validHosts** (string[] | null) - Optional - Extra TLD-like strings treated as valid suffixes, e.g. ['localhost'] (default: null)

### Request Example
```javascript
import { parse } from 'tldts';

// Example with custom options
const options = {
  allowIcannDomains: true,
  allowPrivateDomains: false,
  extractHostname: true,
  validateHostname: true,
  detectIp: true,
  mixedInputs: true,
  validHosts: null
};

parse('api.example.com', options);
```

### Response
#### Success Response (IResult)
- **hostname** (string | null) - Extracted hostname (lowercased)
- **isIp** (boolean | null) - true if hostname is an IPv4 or IPv6 address
- **subdomain** (string | null) - Full subdomain (left of registered domain)
- **domain** (string | null) - Registered domain (publicSuffix + one label)
- **publicSuffix** (string | null) - Effective TLD per Public Suffix List
- **domainWithoutSuffix** (string | null) - Registered domain label without suffix
- **isIcann** (boolean | null) - publicSuffix found in ICANN section
- **isPrivate** (boolean | null) - publicSuffix found in Private section

#### Response Example
```json
{
  "hostname": "api.example.com",
  "isIp": false,
  "subdomain": null,
  "domain": "example.com",
  "publicSuffix": "com",
  "domainWithoutSuffix": "example",
  "isIcann": true,
  "isPrivate": false
}
```
```

--------------------------------

### Parse URL with CLI

Source: https://github.com/remusao/tldts/blob/master/README.md

Use the npx command to parse a URL directly from the command line and view its extracted components.

```js
$ npx tldts 'http://www.writethedocs.org/conf/eu/2017/'
{
  "domain": "writethedocs.org",
  "domainWithoutSuffix": "writethedocs",
  "hostname": "www.writethedocs.org",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "org",
  "subdomain": "www"
}
```

--------------------------------

### Get Domain Without Public Suffix

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Utilize `getDomainWithoutSuffix` to retrieve the domain part, excluding the public suffix. This is useful for identifying the core domain name.

```javascript
const { getDomainWithoutSuffix } = require('tldts');

getDomainWithoutSuffix('google.com'); // returns `google`
getDomainWithoutSuffix('fr.google.com'); // returns `google`
getDomainWithoutSuffix('fr.google.google'); // returns `google`
getDomainWithoutSuffix('foo.google.co.uk'); // returns `google`
getDomainWithoutSuffix('t.co'); // returns `t`
getDomainWithoutSuffix('fr.t.co'); // returns `t`
getDomainWithoutSuffix(
  'https://user:password@example.co.uk:8080/some/path?and&query#hash',
); // returns `example`
```

--------------------------------

### tldts Accepts Hostnames and URLs

Source: https://github.com/remusao/tldts/blob/master/README.md

Demonstrates that tldts's parse function can accept both raw hostnames and full URLs as input, simplifying the parsing process.

```javascript
const { parse } = require('tldts');

// Both are fine!
parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true });
parse('https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv', {
  allowPrivateDomains: true,
});
```

--------------------------------

### Get Hostname from Full URL

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Extracts the hostname from a complete URL, including credentials, port, path, query, and hash. This demonstrates the function's robustness.

```javascript
getHostname(
  'https://user:password@example.co.uk:8080/some/path?and&query#hash',
); // returns `example.co.uk`
```

--------------------------------

### parse(url | hostname, options?)

Source: https://context7.com/remusao/tldts/llms.txt

Parses a full URL or hostname, returning an IResult object with all parsed components. It handles schemes, ports, paths, queries, and fragments automatically. This function is flexible but slightly slower than single-purpose helpers.

```APIDOC
## parse(url | hostname, options?)

### Description
Returns a complete `IResult` object with all parsed components of the input. Accepts both raw URLs (including scheme, port, path, query, fragment) and plain hostnames. This is the most flexible function but slightly slower than single-purpose helpers because it computes all fields.

### Method
```javascript
import { parse } from 'tldts';

parse(url | hostname, options?)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
- **options** (IOptions) - Optional - An object for fine-grained control over parsing behavior, such as `allowPrivateDomains`.

#### Request Body
None

### Request Example
```javascript
// Plain hostname
parse('www.writethedocs.org');

// Full URL
parse('https://user:pass@secure.example.co.uk:8080/some/path?q=1#anchor');

// With options to allow private domains
parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true });

// IPv4 address
parse('https://192.168.0.1/admin');

// IPv6 address
parse('https://[::1]:3000/api');

// Email address
parse('user@emailprovider.co.uk');
```

### Response
#### Success Response (IResult)
- **domain** (string | null) - The domain name.
- **domainWithoutSuffix** (string | null) - The domain name without the public suffix.
- **hostname** (string | null) - The extracted hostname.
- **isIcann** (boolean) - Whether the domain is an ICANN recognized domain.
- **isIp** (boolean) - Whether the input is an IP address.
- **isPrivate** (boolean) - Whether the domain is a private suffix.
- **publicSuffix** (string | null) - The public suffix of the domain.
- **subdomain** (string | null) - The subdomain part of the hostname.

#### Response Example
```json
{
  "domain": "writethedocs.org",
  "domainWithoutSuffix": "writethedocs",
  "hostname": "www.writethedocs.org",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "org",
  "subdomain": "www"
}
```
```

--------------------------------

### Extract Subdomain with getSubdomain

Source: https://context7.com/remusao/tldts/llms.txt

Use `getSubdomain` to extract the full subdomain component (everything to the left of the registered domain). It returns `null` for IPs or when no valid domain is found. Use `validHosts` to handle custom hostnames.

```javascript
import { getSubdomain } from 'tldts';

getSubdomain('google.com');                          // ''
getSubdomain('fr.google.com');                       // 'fr'
getSubdomain('moar.foo.google.co.uk');               // 'moar.foo'
getSubdomain('t.co');                                // ''
getSubdomain('fr.t.co');                             // 'fr'
getSubdomain('https://user:pw@secure.example.co.uk:443/path?q#h'); // 'secure'

// Custom host — null without validHosts
getSubdomain('vhost.localhost');                              // null
getSubdomain('vhost.localhost', { validHosts: ['localhost'] }); // 'vhost'
```

--------------------------------

### Get Hostname from URL or Hostname String

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Extracts the hostname from a given URL or hostname string. Handles complex URLs with credentials, ports, paths, queries, and fragments.

```javascript
const { getHostname } = require('tldts-icann');

getHostname('google.com'); // returns `google.com`
getHostname('fr.google.com'); // returns `fr.google.com`
getHostname('fr.google.google'); // returns `fr.google.google`
getHostname('foo.google.co.uk'); // returns `foo.google.co.uk`
getHostname('t.co'); // returns `t.co`
getHostname('fr.t.co'); // returns `fr.t.co`
getHostname(
  'https://user:password@example.co.uk:8080/some/path?and&query#hash'
); // returns `example.co.uk`
```

--------------------------------

### tldts Dedicated Domain Extraction Methods

Source: https://github.com/remusao/tldts/blob/master/README.md

Shows how to use tldts's specialized functions like `getHostname`, `getDomain`, `getPublicSuffix`, `getSubdomain`, and `getDomainWithoutSuffix` for more efficient extraction of domain parts compared to using the generic `parse` function.

```javascript
const {
  getHostname,
  getDomain,
  getPublicSuffix,
  getSubdomain,
  getDomainWithoutSuffix,
} = require('tldts');

const url = 'https://spark-public.s3.amazonaws.com';

console.log(getHostname(url)); // spark-public.s3.amazonaws.com
```

--------------------------------

### Get Fully Qualified Domain from URL or Hostname

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Extracts the fully qualified domain name from a given string. This is useful for identifying the main domain, ignoring subdomains.

```javascript
const { getDomain } = require('tldts-icann');

getDomain('google.com'); // returns `google.com`
getDomain('fr.google.com'); // returns `google.com`
getDomain('fr.google.google'); // returns `google.google`
getDomain('foo.google.co.uk'); // returns `google.co.uk`
getDomain('t.co'); // returns `t.co`
getDomain('fr.t.co'); // returns `t.co`
getDomain('https://user:password@example.co.uk:8080/some/path?and&query#hash'); // returns `example.co.uk`
```

--------------------------------

### Parse Hostname with tldts vs psl

Source: https://github.com/remusao/tldts/blob/master/README.md

Compares parsing a hostname using tldts with private domain support enabled versus psl's default behavior. Ensure `{ allowPrivateDomains: true }` is used with tldts for equivalent private suffix handling.

```javascript
tldts.parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true })
```

```javascript
psl.parse('spark-public.s3.amazonaws.com')
```

--------------------------------

### Batch URL Processing with tldts

Source: https://context7.com/remusao/tldts/llms.txt

Process multiple URLs by piping them as line-delimited input to `npx tldts`. Each URL is processed individually, and the output is a stream of JSON objects, one per line.

```bash
echo -e "https://example.com
https://sub.test.co.uk" | npx tldts
```

--------------------------------

### ES6 module import for tldts

Source: https://github.com/remusao/tldts/blob/master/README.md

Demonstrates how to import the parse function using ES6 module syntax, suitable for modern JavaScript environments.

```js
import { parse } from 'tldts';
```

--------------------------------

### Get Public Suffix with tldts vs psl

Source: https://github.com/remusao/tldts/blob/master/README.md

Illustrates how to retrieve the public suffix using tldts's `getPublicSuffix` function, comparing it to accessing the `tld` property after parsing with psl. Note the difference in how private suffixes are handled.

```javascript
tldts.getPublicSuffix('spark-public.s3.amazonaws.com', { allowPrivateDomains: true })
```

```javascript
psl.parse('spark-public.s3.amazonaws.com').tld
```

--------------------------------

### tldts Behavior with Private Domains Enabled

Source: https://github.com/remusao/tldts/blob/master/README.md

Illustrates how to enable private domain parsing in tldts using the `{ allowPrivateDomains: true }` option, which then includes private suffixes.

```javascript
const { parse } = require('tldts');

parse('spark-public.s3.amazonaws.com', { allowPrivateDomains: true });
// {
//   domain: 'spark-public.s3.amazonaws.com',
//   domainWithoutSuffix: 'spark-public',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIcann: false,
//   isIp: false,
//   isPrivate: true,
//   publicSuffix: 's3.amazonaws.com',
//   subdomain: ''
// }
```

--------------------------------

### getSubdomain(url | hostname, options?)

Source: https://context7.com/remusao/tldts/llms.txt

Extracts the full subdomain component (everything to the left of the registered domain). Returns null for IPs or when no valid domain can be found.

```APIDOC
## `getSubdomain(url | hostname, options?)` — Extract subdomain

Returns the full subdomain component (everything to the left of the registered domain). Returns `null` for IPs or when no valid domain can be found.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { getSubdomain } from 'tldts';

getSubdomain('google.com');                          // ''
getSubdomain('fr.google.com');                       // 'fr'
getSubdomain('moar.foo.google.co.uk');               // 'moar.foo'
getSubdomain('t.co');                                // ''
getSubdomain('fr.t.co');                             // 'fr'
getSubdomain('https://user:pw@secure.example.co.uk:443/path?q#h'); // 'secure'

// Custom host — null without validHosts
getSubdomain('vhost.localhost');                              // null
getSubdomain('vhost.localhost', { validHosts: ['localhost'] }); // 'vhost'
```

### Response
#### Success Response (200)
- **subdomain** (string | null) - The subdomain string or null.

#### Response Example
```json
{
  "subdomain": "fr"
}
```
```

--------------------------------

### parse(url | hostname, options)

Source: https://github.com/remusao/tldts/blob/master/packages/tldts-icann/README.md

Parses a URL or hostname to extract detailed information including domain, public suffix, subdomain, and IP address status. It can be customized with various options.

```APIDOC
## parse(url | hostname, options)

### Description
Parses a URL or hostname to extract detailed information including domain, public suffix, subdomain, and IP address status. It can be customized with various options.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options
- `extractHostname` (boolean): Extract and validate hostname. Default: `true`.
- `validateHostname` (boolean): Validate hostnames after parsing. Default: `true`.
- `detectIp` (boolean): Perform IP address detection. Default: `true`.
- `mixedInputs` (boolean): Assume that both URLs and hostnames can be given as input. Default: `true`.
- `validHosts` (string[] | null): Specifies extra valid suffixes. Default: `null`.

### Request Example
```javascript
const { parse } = require('tldts-icann');

parse('http://www.writethedocs.org/conf/eu/2017/');
// { domain: 'writethedocs.org',
//   domainWithoutSuffix: 'writethedocs',
//   hostname: 'www.writethedocs.org',
//   isIp: false,
//   publicSuffix: 'org',
//   subdomain: 'www' }

parse('https://192.168.0.0'); // IPv4
// { domain: null,
//   domainWithoutSuffix: null,
//   hostname: '192.168.0.0',
//   isIp: true,
//   publicSuffix: null,
//   subdomain: null }
```

### Response
#### Success Response (200)
- `hostname` (string): Hostname of the input extracted automatically.
- `domain` (string): Domain (tld + sld).
- `domainWithoutSuffix` (string): Domain without public suffix.
- `subdomain` (string): Sub domain (what comes after `domain`).
- `publicSuffix` (string): Public Suffix (tld) of `hostname`.
- `isIP` (boolean): Is `hostname` an IP address?

#### Response Example
```json
{
  "domain": "writethedocs.org",
  "domainWithoutSuffix": "writethedocs",
  "hostname": "www.writethedocs.org",
  "isIp": false,
  "publicSuffix": "org",
  "subdomain": "www"
}
```
```

--------------------------------

### tldts.parse(url | hostname, options)

Source: https://github.com/remusao/tldts/blob/master/packages/tldts/README.md

Parses a URL or hostname and returns an object with detailed properties about it. Options can be provided to customize the parsing behavior.

```APIDOC
## tldts.parse(url | hostname, options)

### Description
Parses a URL or hostname and returns an object containing properties such as domain, hostname, public suffix, and subdomain. It can also identify if the input is an IP address or belongs to ICANN or private domain lists.

### Parameters
- `url | hostname` (string): The URL or hostname string to parse.
- `options` (object, optional): An object to customize parsing behavior. Available options include:
  - `allowIcannDomains` (boolean): Use suffixes from ICANN section (default: true).
  - `allowPrivateDomains` (boolean): Use suffixes from Private section (default: false).
  - `extractHostname` (boolean): Extract and validate hostname (default: true).
  - `validateHostname` (boolean): Validate hostnames after parsing (default: true).
  - `detectIp` (boolean): Perform IP address detection (default: true).
  - `mixedInputs` (boolean): Assume that both URLs and hostnames can be given as input (default: true).
  - `validHosts` (string[] | null): Specifies extra valid suffixes (default: null).

### Response
An object with the following properties:
- `hostname` (string): The hostname of the input extracted automatically.
- `domain` (string): Domain (tld + sld).
- `domainWithoutSuffix` (string): Domain without public suffix.
- `subdomain` (string): Sub domain (what comes after `domain`).
- `publicSuffix` (string): Public Suffix (tld) of `hostname`.
- `isIcann` (boolean): Does TLD come from ICANN part of the list.
- `isPrivate` (boolean): Does TLD come from Private part of the list.
- `isIp` (boolean): Is `hostname` an IP address?

### Request Example
```javascript
const tldts = require('tldts');

tldts.parse('https://spark-public.s3.amazonaws.com/dataanalysis/loansData.csv');
// { domain: 'amazonaws.com',
//   domainWithoutSuffix: 'amazonaws',
//   hostname: 'spark-public.s3.amazonaws.com',
//   isIcann: true,
//   isIp: false,
//   isPrivate: false,
//   publicSuffix: 'com',
//   subdomain: 'spark-public.s3' }
```

### Response Example
```json
{
  "domain": "amazonaws.com",
  "domainWithoutSuffix": "amazonaws",
  "hostname": "spark-public.s3.amazonaws.com",
  "isIcann": true,
  "isIp": false,
  "isPrivate": false,
  "publicSuffix": "com",
  "subdomain": "spark-public.s3"
}
```
```