The behavior of tldts can be customized using an options argument for all
the functions exposed as part of the public API. This is useful to both change
the behavior of the library as well as fine-tune the performance depending on
your inputs.
{ // Use suffixes from ICANN section (default: true) allowIcannDomains: boolean; // Use suffixes from Private section (default: false) allowPrivateDomains: boolean; // Extract and validate hostname (default: true) // When set to `false`, inputs will be considered valid hostnames. extractHostname: boolean; // Validate hostnames after parsing (default: true) // If a hostname is not valid, not further processing is performed. When set // to `false`, inputs to the library will be considered valid and parsing will // proceed regardless. validateHostname: boolean; // Perform IP address detection (default: true). detectIp: boolean; // Detect IANA special-use domains (RFC 6761 et al.) and expose the result as // `isSpecialUse` (default: false). Off by default so the common path does no // extra work; the field stays `null` unless this is enabled. detectSpecialUse: boolean; // Assume that both URLs and hostnames can be given as input (default: true) // If set to `false` we assume only URLs will be given as input, which // speed-ups processing. mixedInputs: boolean; // Hostnames to treat as registrable domains, e.g. ['localhost'] (default: null) validHosts: string[] | null; // Extra public suffix rules, in PSL syntax, per section (default: null) // See "Adding public suffixes" below. extraSuffixes: { icann?: readonly string[]; private?: readonly string[] } | null;}
The parse method returns handy properties about a URL or a hostname.
Set { detectSpecialUse: true } to flag reserved special-use names such as localhost, *.test, *.local, *.onion, and home.arpa via the isSpecialUse result field. isIcann/isPrivate don't identify these: most aren't in the Public Suffix List, and the few that are (e.g. onion, home.arpa) appear there as ordinary ICANN suffixes. The field is null unless the option is enabled, so the default path does no extra work:
Returns the full domain — the subdomain together with the registrable domain (as
returned by getDomain(...)), i.e. the whole hostname including any subdomain —
or null when the input has no registrable domain (IP address, single label,
bare public suffix, …). The result is the normalized hostname (lower-cased,
trailing dot stripped); it is not a DNS-absolute name (no trailing root dot) and
no IDNA/punycode conversion is performed.
The Public Suffix List only accepts entries from domain owners. To use suffixes
it does not list, pass extraSuffixes in PSL syntax (foo.com, *.foo.com,
!a.foo.com), per section:
tldts made the opinionated choice of shipping with a list of suffixes directly
in its bundle. There is currently no mechanism to update the lists yourself, but
we make sure that the version shipped is always up-to-date.
If you keep tldts updated, the lists should be up-to-date as well!
Performance
tldts is the fastest JavaScript library available for parsing hostnames. It is able to parse millions of inputs per second (typically 2-3M depending on your hardware and inputs). It also offers granular options to fine-tune the behavior and performance of the library depending on the kind of inputs you are dealing with (e.g.: if you know you only manipulate valid hostnames you can disable the hostname extraction step with { extractHostname: false }).