parse-domain

Splits a URL into sub-domain, domain and the top-level domain.

Since domains are handled differently across different countries and organizations, splitting a URL into sub-domain, domain and top-level-domain parts is not a simple regexp. parse-domain uses a large list of known top-level domains from publicsuffix.org to recognize different parts of the domain.

Installation

1npm install --save parse-domain

Usage

1// long subdomains can be handled
2expect(parseDomain("some.subdomain.example.co.uk")).to.eql({
3    subdomain: "some.subdomain",
4    domain: "example",
5    tld: "co.uk"
6});
7
8// protocols, usernames, passwords, ports, paths, queries and hashes are disregarded
9expect(parseDomain("https://user:password@example.co.uk:8080/some/path?and&query#hash")).to.eql({
10    subdomain: "",
11    domain: "example",
12    tld: "co.uk"
13});
14
15// unknown top-level domains are ignored
16expect(parseDomain("unknown.tld.kk")).to.equal(null);
17
18// invalid urls are also ignored
19expect(parseDomain("invalid url")).to.equal(null);
20expect(parseDomain({})).to.equal(null);

Introducing custom tlds

1// custom top-level domains can optionally be specified
2expect(parseDomain("mymachine.local",{ customTlds: ["local"] })).to.eql({
3    subdomain: "",
4    domain: "mymachine",
5    tld: "local"
6});
7
8// custom regexps can optionally be specified (instead of customTlds)
9expect(parseDomain("localhost",{ customTlds:/localhost|\.local/ })).to.eql({
10    subdomain: "",
11    domain: "",
12    tld: "localhost"
13});

It can sometimes be helpful to apply the customTlds argument using a helper function

1function parseLocalDomains(url) {
2    return parseDomain(url, {
3        customTlds: /localhost|\.local/
4    });
5}
6
7expect(parseLocalDomains("localhost")).to.eql({
8    subdomain: "",
9    domain: "",
10    tld: "localhost"
11});
12expect(parseLocalDomains("mymachine.local")).to.eql({
13    subdomain: "",
14    domain: "mymachine",
15    tld: "local"
16});

API

parseDomain(url: string, options: ParseOptions): ParsedDomain|null

Returns null if url has an unknown tld or if it's not a valid url.

ParseOptions

1{
2    // A list of custom tlds that are first matched against the url.
3    // Useful if you also need to split internal URLs like localhost.
4    customTlds: RegExp|Array<string>,
5    
6    // There are lot of private domains that act like top-level domains,
7    // like blogspot.com, googleapis.com or s3.amazonaws.com.
8    // By default, these domains would be split into:
9    // { subdomain: ..., domain: "blogspot", tld: "com" }
10    // When this flag is set to true, the domain will be split into
11    // { subdomain: ..., domain: ..., tld: "blogspot.com" }
12    // See also https://github.com/peerigon/parse-domain/issues/4
13    privateTlds: boolean - default: false
14}

ParsedDomain

1{
2    tld: string,
3    domain: string,
4    subdomain: string
5}

License

Unlicense

Sponsors