PublicSuffixList

A JavaScript domain name parser for the validation of domain names and top level domains, making use of the Public Suffix List used internally by modern web browsers.

Installation

The publicsuffixlist module can be installed via npm:

npm install publicsuffixlist -S

A current copy of Mozilla's Public Suffix List will be downloaded automatically.

Updating the list

In order to obtin a fresh copy of the current list, run npm run update in the installation folder, usually node_modules/publicsuffixlist (relative to the project directory).

Running the unit tests

Please download and install the Mocha test framework globally (you might need to have superuser rights):

npm install mocha -g

Then run the following command:

mocha

Usage

var PublicSuffixList = require('publicsuffixlist');

// Create a new PublicSuffixList instance
var psl = new PublicSuffixList(options);

psl.initialize(function (err) { // initialize psl asynchronously or
  // Use the methods described below
});

psl.initializeSync(); // initialize psl synchronously
// Use the methods described below

Options

filename {string}

Supplies a filename as source for the data file. This will be Mozilla's "effective_tld_names.dat" by default.

buffer {object}

Supplies a buffer as source for the data file.

lines {string[]}

Supplies an array of strings as source for the data file.

Initialization

.initialize(callback)

Loads all rules from the specified source.

.initializeSync()

Loads all rules synchronously from the specified source.

In order to use this module, it must be initialized synchronously or asynchronously with a ruleset. By default, the ruleset is loaded from disk.

Methods

.lookup(domainString)

lookup() returns an object providing the distinct results for the queried string or null in case of an invalid query.

var result = psl.lookup('www.domain.com');

/* result === { domain: 'domain',
              tld: 'com',
              subdomain: 'www' } */

.domain(domainString)

Get the assignable domain from the fully qualified domain name.

var result = psl.domain('www.domain.com');

/* result === 'domain.com' */

.validateTLD (tld)

Validates the provided top level domain. Returns true or false.

var validTLD = psl.validateTLD('de'); // true
var invalidTLD = psl.validateTLD('ed'); // false

.validate (domainString)

Returns true when the provided domain is valid, otherwise false.

var validDomain = psl.validate('domain.de'); // true
var invalidDomain = psl.validate('domain.yz'); // false

Manual installation

For development purposes, you can also clone this repository. Then, you'll need to install all dependencies via npm install.

When installing in production (npm install --only=production), additional dependencies required for running unit tests won't be installed.

After a manual installation, it is necessary to run the download_list.js script in the root folder in order to download a current version of the list.

Tests

Tests are included in the test/ directory. In order to run these, you will need to install the Mocha testing framework and execute the following command:

mocha
# - or -
gulp mocha

Further reading

• publicsuffix.org
• Mozilla Wiki: Public Suffix List

Credits

• Kristof Csillag disabled certificate validation while installing due to an temporary issue with publicsuffix.org's SSL certificate
• Kirill Dmitrenko added loading Mozilla's public suffix list by default (if nothing else was declared)
• Morton Swimmer forked this library, added a .domain() method and updated the URL of the list
• Simone Carletti
• domainname-parser.googlecode.com

License

MIT License.