0
# tldts - Blazing Fast URL Parsing
1

2
tldts is a JavaScript/TypeScript library to extract hostnames, domains, public suffixes, top-level domains and subdomains from URLs. It provides high-performance URL parsing (0.1 to 1 μs per input) with comprehensive Unicode/IDNA support, IPv4/IPv6 detection, and email parsing capabilities.
3

4
## Package Information
5

6
- **Package Name**: tldts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tldts`
10

11
## Core Imports
12

13
```typescript
14
import { parse, getHostname, getDomain, getPublicSuffix, getSubdomain, getDomainWithoutSuffix } from "tldts";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { parse, getHostname, getDomain } = require("tldts");
21
```
22

23
**Type Imports**: TypeScript types are not re-exported from the main package. If you need type definitions, import them from the core library:
24

25
```typescript
26
import type { IResult, IOptions } from "tldts-core";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { parse, getDomain, getHostname } from "tldts";
33

34
// Parse a complete URL
35
const result = parse("https://www.example.co.uk/path");
36
console.log(result.domain); // "example.co.uk"
37
console.log(result.subdomain); // "www"
38
console.log(result.publicSuffix); // "co.uk"
39

40
// Extract specific components
41
const domain = getDomain("https://api.github.com/users");
42
console.log(domain); // "github.com"
43

44
const hostname = getHostname("https://secure.example.org:8080/admin");
45
console.log(hostname); // "secure.example.org"
46
```
47

48
## Architecture
49

50
tldts is built around several key components:
51

52
- **Core Parser**: High-performance parsing engine with early exit optimization
53
- **Public Suffix List**: Continuously updated trie-based data structure for TLD recognition
54
- **Options System**: Granular configuration for performance tuning and behavior customization
55
- **Type Safety**: Full TypeScript integration with comprehensive interface definitions
56
- **Multi-format Support**: Handles URLs, hostnames, email addresses, and IP addresses
57

58
## Capabilities
59

60
### Complete URL Parsing
61

62
Extracts all URL components in a single operation with comprehensive metadata.
63

64
```typescript { .api }
65
/**
66
 * Parse URL or hostname and extract all components
67
 * @param url - URL or hostname string to parse
68
 * @param options - Optional parsing configuration
69
 * @returns Complete parsing result with all extracted components
70
 */
71
function parse(url: string, options?: Partial<IOptions>): IResult;
72

73
interface IResult {
74
  /** Extracted hostname from the input */
75
  hostname: string | null;
76
  /** Whether hostname is an IP address (IPv4 or IPv6) */
77
  isIp: boolean | null;
78
  /** Subdomain portion (everything before the domain) */
79
  subdomain: string | null;
80
  /** Full domain (domain + public suffix) */
81
  domain: string | null;
82
  /** Public suffix/TLD (e.g., "com", "co.uk") */
83
  publicSuffix: string | null;
84
  /** Domain without the public suffix (second-level domain) */
85
  domainWithoutSuffix: string | null;
86
  /** Whether public suffix comes from ICANN section */
87
  isIcann: boolean | null;
88
  /** Whether public suffix comes from Private section */
89
  isPrivate: boolean | null;
90
}
91
```
92

93
### Hostname Extraction
94

95
Extracts hostname from URLs or validates hostname strings.
96

97
```typescript { .api }
98
/**
99
 * Extract hostname from URL or hostname string
100
 * @param url - URL or hostname string
101
 * @param options - Optional parsing configuration
102
 * @returns Hostname string or null if invalid
103
 */
104
function getHostname(url: string, options?: Partial<IOptions>): string | null;
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import { getHostname } from "tldts";
111

112
getHostname("https://www.example.com/path"); // "www.example.com"
113
getHostname("example.com"); // "example.com"
114
getHostname("https://user:pass@api.example.com:8080/v1"); // "api.example.com"
115
getHostname("mailto:user@example.org"); // "example.org"
116
```
117

118
### Domain Extraction
119

120
Extracts the fully qualified domain (domain + public suffix).
121

122
```typescript { .api }
123
/**
124
 * Extract fully qualified domain from URL or hostname
125
 * @param url - URL or hostname string
126
 * @param options - Optional parsing configuration
127
 * @returns Domain string or null if no valid domain found
128
 */
129
function getDomain(url: string, options?: Partial<IOptions>): string | null;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { getDomain } from "tldts";
136

137
getDomain("https://www.google.com"); // "google.com"
138
getDomain("api.github.com"); // "github.com"
139
getDomain("secure.example.co.uk"); // "example.co.uk"
140
getDomain("localhost"); // null (unless validHosts specified)
141
```
142

143
### Public Suffix Extraction
144

145
Extracts the public suffix (TLD) using the Mozilla Public Suffix List.
146

147
```typescript { .api }
148
/**
149
 * Extract public suffix (TLD) from URL or hostname
150
 * @param url - URL or hostname string
151
 * @param options - Optional parsing configuration
152
 * @returns Public suffix string or null if none found
153
 */
154
function getPublicSuffix(url: string, options?: Partial<IOptions>): string | null;
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { getPublicSuffix } from "tldts";
161

162
getPublicSuffix("example.com"); // "com"
163
getPublicSuffix("example.co.uk"); // "co.uk"
164
getPublicSuffix("s3.amazonaws.com"); // "com"
165
getPublicSuffix("s3.amazonaws.com", { allowPrivateDomains: true }); // "s3.amazonaws.com"
166
```
167

168
### Subdomain Extraction
169

170
Extracts the subdomain portion (everything before the domain).
171

172
```typescript { .api }
173
/**
174
 * Extract subdomain from URL or hostname
175
 * @param url - URL or hostname string
176
 * @param options - Optional parsing configuration
177
 * @returns Subdomain string or null if none exists
178
 */
179
function getSubdomain(url: string, options?: Partial<IOptions>): string | null;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { getSubdomain } from "tldts";
186

187
getSubdomain("www.example.com"); // "www"
188
getSubdomain("api.v2.example.com"); // "api.v2"
189
getSubdomain("example.com"); // ""
190
getSubdomain("secure.shop.example.co.uk"); // "secure.shop"
191
```
192

193
### Domain Without Suffix Extraction
194

195
Extracts the domain without its public suffix (second-level domain).
196

197
```typescript { .api }
198
/**
199
 * Extract domain without public suffix (second-level domain)
200
 * @param url - URL or hostname string
201
 * @param options - Optional parsing configuration
202
 * @returns Domain without suffix or null if no valid domain
203
 */
204
function getDomainWithoutSuffix(url: string, options?: Partial<IOptions>): string | null;
205
```
206

207
**Usage Examples:**
208

209
```typescript
210
import { getDomainWithoutSuffix } from "tldts";
211

212
getDomainWithoutSuffix("example.com"); // "example"
213
getDomainWithoutSuffix("www.github.com"); // "github"
214
getDomainWithoutSuffix("secure.example.co.uk"); // "example"
215
```
216

217
## Configuration Options
218

219
```typescript { .api }
220
interface IOptions {
221
  /** Use suffixes from ICANN section (default: true) */
222
  allowIcannDomains: boolean;
223
  /** Use suffixes from Private section (default: false) */
224
  allowPrivateDomains: boolean;
225
  /** Perform IP address detection (default: true) */
226
  detectIp: boolean;
227
  /** Extract hostname from URLs (default: true) */
228
  extractHostname: boolean;
229
  /** Handle mixed URLs and hostnames (default: true) */
230
  mixedInputs: boolean;
231
  /** Additional valid hosts for localhost-style domains (default: null) */
232
  validHosts: string[] | null;
233
  /** Validate hostnames after extraction (default: true) */
234
  validateHostname: boolean;
235
}
236
```
237

238
**Configuration Examples:**
239

240
```typescript
241
import { parse, getDomain } from "tldts";
242

243
// Enable private domains (like s3.amazonaws.com)
244
const result = parse("https://bucket.s3.amazonaws.com/file", {
245
  allowPrivateDomains: true
246
});
247
console.log(result.publicSuffix); // "s3.amazonaws.com"
248

249
// Handle localhost and custom domains
250
const domain = getDomain("api.localhost", {
251
  validHosts: ["localhost"]
252
});
253
console.log(domain); // "localhost"
254

255
// Performance optimization for hostname-only inputs
256
const hostname = parse("example.com", {
257
  extractHostname: false,
258
  mixedInputs: false
259
});
260
```
261

262
## Special Input Handling
263

264
### IPv4 and IPv6 Addresses
265

266
```typescript
267
import { parse } from "tldts";
268

269
// IPv4 address
270
const ipv4Result = parse("https://192.168.1.1/admin");
271
console.log(ipv4Result.isIp); // true
272
console.log(ipv4Result.hostname); // "192.168.1.1"
273
console.log(ipv4Result.domain); // null
274

275
// IPv6 address
276
const ipv6Result = parse("https://[2001:db8::1]/api");
277
console.log(ipv6Result.isIp); // true
278
console.log(ipv6Result.hostname); // "2001:db8::1"
279
```
280

281
### Email Addresses
282

283
```typescript
284
import { parse } from "tldts";
285

286
const emailResult = parse("user@example.co.uk");
287
console.log(emailResult.hostname); // "example.co.uk"
288
console.log(emailResult.domain); // "example.co.uk"
289
console.log(emailResult.publicSuffix); // "co.uk"
290
```
291

292
### Edge Cases and Error Handling
293

294
```typescript
295
import { parse, getDomain } from "tldts";
296

297
// Invalid inputs return null values
298
console.log(getDomain("")); // null
299
console.log(getDomain("not-a-url")); // null
300

301
// Unknown TLDs are handled gracefully
302
const unknownTld = parse("example.unknown");
303
console.log(unknownTld.publicSuffix); // "unknown"
304
console.log(unknownTld.isIcann); // false
305

306
// Malformed URLs
307
const malformed = parse("ht!tp://bad-url");
308
console.log(malformed.hostname); // null
309
```
310

311
## Command Line Interface
312

313
The package includes a CLI tool for parsing URLs from the command line:
314

315
```bash
316
# Parse single URL
317
npx tldts "https://www.example.co.uk/path"
318

319
# Parse from stdin
320
echo "https://api.github.com" | npx tldts
321

322
# Output format (JSON)
323
{
324
  "domain": "example.co.uk",
325
  "domainWithoutSuffix": "example",
326
  "hostname": "www.example.co.uk",
327
  "isIcann": true,
328
  "isIp": false,
329
  "isPrivate": false,
330
  "publicSuffix": "co.uk",
331
  "subdomain": "www"
332
}
333
```
334

335
## Performance Characteristics
336

337
- **Speed**: 0.1 to 1 microsecond per input
338
- **Memory**: Optimized trie data structures with small footprint
339
- **Scalability**: Handles millions of URLs per second
340
- **Bundle Size**: Multiple optimized formats (UMD, ESM, CommonJS)
341
- **Early Exit**: Internal optimization to avoid unnecessary computation
342

343
For maximum performance with known input types, use specialized options:
344

345
```typescript
346
// For hostname-only inputs (fastest)
347
const options = {
348
  extractHostname: false,
349
  mixedInputs: false,
350
  validateHostname: false
351
};
352

353
// For domain extraction only (faster than full parse)
354
const domain = getDomain(input, options);
355
```