neotld

A modern ESM fork of tld.js for working with domain names, subdomains and well-known TLDs.

It answers with accuracy to questions like what is mail.google.com's domain?, what is a.b.ide.kyoto.jp's subdomain? and is https://big.data's TLD a well-known one?.

Because it relies on Mozilla's public suffix list, now is a good time to say thank you Mozilla!

Install

1# Regular install
2npm install neotld
3pnpm add neotld
4
5# You can update the list of well-known TLD during the install
6pnpm add neotld --neotld-update-rules

The latter is useful if you significantly rely on an up-to-date list of TLDs. You can list the recent changes (changes Atom Feed) to get a better idea of what is going on in the Public Suffix world.

Using It

1import { parse, tldExists } from 'neotld';
2
3// Checking only if TLD exists in URL or hostname
4console.log(tldExists('google.com')); // true
5console.log(tldExists('example.invalid')); // false
6
7// Retrieving hostname related information of a given URL
8parse('http://www.writethedocs.org/conf/eu/2017/');

API

parse()

Returns detailed information about a URL or hostname:

1import { parse } from 'neotld';
2
3parse('https://spark-public.s3.amazonaws.com/data/file.csv');
4// { 
5//   hostname: 'spark-public.s3.amazonaws.com',
6//   isValid: true,
7//   isIp: false,
8//   tldExists: true,
9//   publicSuffix: 's3.amazonaws.com',
10//   domain: 'spark-public.s3.amazonaws.com',
11//   subdomain: ''
12// }
13
14parse('gopher://domain.unknown/');
15// { hostname: 'domain.unknown',
16//   isValid: true,
17//   isIp: false,
18//   tldExists: false,
19//   publicSuffix: 'unknown',
20//   domain: 'domain.unknown',
21//   subdomain: ''
22// }
23
24parse('https://192.168.0.0')
25// { hostname: '192.168.0.0',
26//   isValid: true,
27//   isIp: true,
28//   tldExists: false,
29//   publicSuffix: null,
30//   domain: null,
31//   subdomain: null
32// }

Property Name	Type
hostname	String
isValid	Boolean	Is the hostname valid according to the RFC?
tldExists	Boolean	Is the TLD well-known or not?
publicSuffix	String
domain	String
subdomain	String

Single purpose methods

These methods are shorthands if you want to retrieve only a single value.

tldExists()

Checks if the TLD is well-known for a given hostname — parseable with [URL.parse][].

1import { tldExists } from 'neotld';
2
3tldExists('google.com');      // returns `true`
4tldExists('google.local');    // returns `false` (not an explicit registered TLD)
5tldExists('com');             // returns `true`
6tldExists('uk');              // returns `true`
7tldExists('co.uk');           // returns `true` (because `uk` is a valid TLD)
8tldExists('amazon.fancy.uk'); // returns `true` (still because `uk` is a valid TLD)
9tldExists('amazon.co.uk');    // returns `true` (still because `uk` is a valid TLD)
10tldExists('https://user:password@example.co.uk:8080/some/path?and&query#hash'); // returns `true`

getDomain()

Returns the fully qualified domain from a given string — parseable with [URL.parse][].

1import { getDomain } from 'neotld';
2
3getDomain('google.com');        // returns `google.com`
4getDomain('fr.google.com');     // returns `google.com`
5getDomain('fr.google.google');  // returns `google.google`
6getDomain('foo.google.co.uk');  // returns `google.co.uk`
7getDomain('t.co');              // returns `t.co`
8getDomain('fr.t.co');           // returns `t.co`
9getDomain('https://user:password@example.co.uk:8080/some/path?and&query#hash'); // returns `example.co.uk`

getSubdomain()

Returns the complete subdomain for a given string — parseable with require('url').parse.

1import { getSubdomain } from 'neotld';
2
3getSubdomain('google.com');             // returns ``
4getSubdomain('fr.google.com');          // returns `fr`
5getSubdomain('google.co.uk');           // returns ``
6getSubdomain('foo.google.co.uk');       // returns `foo`
7getSubdomain('moar.foo.google.co.uk');  // returns `moar.foo`
8getSubdomain('t.co');                   // returns ``
9getSubdomain('fr.t.co');                // returns `fr`
10getSubdomain('https://user:password@secure.example.co.uk:443/some/path?and&query#hash'); // returns `secure`

getPublicSuffix()

Returns the public suffix for a given string — parseable with [URL.parse][].

1import { getPublicSuffix } from 'neotld';
2
3getPublicSuffix('google.com');       // returns `com`
4getPublicSuffix('fr.google.com');    // returns `com`
5getPublicSuffix('google.co.uk');     // returns `co.uk`
6getPublicSuffix('s3.amazonaws.com'); // returns `s3.amazonaws.com`
7getPublicSuffix('tld.is.unknown');   // returns `unknown`

isValidHostname()

Checks if the given string is a valid hostname according to RFC 1035. It does not check if the TLD is well-known.

1import { isValidHostname } from 'neotld';
2
3isValidHostname('google.com');      // returns `true`
4isValidHostname('.google.com');     // returns `false`
5isValidHostname('my.fake.domain');  // returns `true`
6isValidHostname('localhost');       // returns `false`
7isValidHostname('https://user:password@example.co.uk:8080/some/path?and&query#hash'); // returns `false`
8isValidHostname('192.168.0.0')      // returns `true`

Troubleshooting

Retrieving subdomain of localhost and custom hostnames

tld.js methods getDomain and getSubdomain are designed to work only with known and valid TLDs. This way, you can trust what a domain is.

localhost is a valid hostname but not a TLD. Although you can instanciate your own flavour of tld.js with additional valid hosts:

1import neotld from 'neotld';
2
3neotld.getDomain('localhost');           // returns null
4neotld.getSubdomain('vhost.localhost');  // returns null
5
6const myNeotld = neotld.fromUserSettings({
7  validHosts: ['localhost']
8});
9
10customTld.getDomain('localhost');           // 'localhost'
11customTld.getSubdomain('vhost.localhost');  // 'vhost'

Updating TLD Rules

Many libraries offer a list of TLDs. But, are they up-to-date? And how to update them?

tld.js bundles a list of known TLDs but this list can become outdated. This is especially true if the package have not been updated on npm for a while.

Hopefully for you, even if I'm flying over the world, if I've lost my Internet connection or even if you do manage your own list, you can update it by yourself, painlessly.

How? By passing the --neotld-update-rules to your npm install command:

1# anytime you reinstall your project
2npm install --neotld-update-rules
3
4# or if you add the dependency to your project
5npm install --save neotld --neotld-update-rules

Open an issue to request an update of the bundled TLDs.

Contributing

Provide a pull request (with tested code) to include your work in this main project. Issues may be awaiting for help so feel free to give a hand, with code or ideas.

Performances

neotld is fast, but keep in mind that it might vary depending on your own use-case. Because the library tried to be smart, the speed can be drastically different depending on the input (it will be faster if you provide an already cleaned hostname, compared to a random URL).

On an Intel i7-6600U (2,60-3,40 GHz):

For already cleaned hostnames

Methods	ops/sec
isValidHostname	~8,700,000
extractHostname	~8,100,000
tldExists	~2,000,000
getPublicSuffix	~1,130,000
getDomain	~1,000,000
getSubdomain	~1,000,000
parse	~850,000

For random URLs

Methods	ops/sec
isValidHostname	~25,400,000
extractHostname	~400,000
tldExists	~310,000
getPublicSuffix	~240,000
getDomain	~240,000
getSubdomain	~240,000
parse	~230,000

You can measure the performance of tld.js on your hardware by running the following command:

1npm run benchmark

Notice: if this is not fast enough for your use-case, keep in mind that you can provide your own extractHostname function (which is the bottleneck in this benchmark) to tld.js.

License

MIT License.