whoistld

A TypeScript package using Zod for parsing domain names and extracting TLD (Top-Level Domain) characteristics including WHOIS privacy support, registration restrictions, and other properties.

Features

- 🚀 Zero Dependencies (except Zod) - All data is embedded in the package
- 🔒 Type-Safe - Full TypeScript support with Zod schemas
- 🌐 Comprehensive TLD Data - Information about gTLDs, ccTLDs, and sponsored TLDs
- ⚡ Fast - No remote requests, all data is local
- 📦 Lightweight - Minimal package size

Installation

``bash
npm install whoistld
`

Usage

$3

`typescript
import { parseDomain } from 'whoistld';

// Parse a full domain
const result = parseDomain('example.com');
console.log(result);
// {
// input: 'example.com',
// tld: 'com',
// domain: 'example',
// characteristics: {
// tld: 'com',
// whoisPrivacySupport: true,
// registrationRestrictions: 'none',
// dnssecSupport: true,
// idn: true,
// category: 'generic',
// description: 'Commercial - most popular gTLD'
// }
// }

// Parse a subdomain
const subdomainResult = parseDomain('blog.example.com');
console.log(subdomainResult);
// {
// input: 'blog.example.com',
// tld: 'com',
// domain: 'example',
// subdomain: 'blog',
// characteristics: { ... }
// }

// Parse just a TLD
const tldResult = parseDomain('.edu');
console.log(tldResult);
// {
// input: '.edu',
// tld: 'edu',
// characteristics: {
// tld: 'edu',
// whoisPrivacySupport: false,
// registrationRestrictions: 'educational',
// dnssecSupport: true,
// idn: false,
// category: 'sponsored',
// description: 'Educational institutions - restricted to accredited institutions'
// }
// }
`

$3

`typescript
import { supportsWhoisPrivacy } from 'whoistld';

console.log(supportsWhoisPrivacy('com')); // true
console.log(supportsWhoisPrivacy('edu')); // false
console.log(supportsWhoisPrivacy('xyz')); // true
console.log(supportsWhoisPrivacy('unknown')); // null
`

$3

`typescript
import { getTldData } from 'whoistld';

const comData = getTldData('com');
console.log(comData);
// {
// tld: 'com',
// whoisPrivacySupport: true,
// registrationRestrictions: 'none',
// dnssecSupport: true,
// idn: true,
// category: 'generic',
// description: 'Commercial - most popular gTLD'
// }

const govData = getTldData('gov');
console.log(govData);
// {
// tld: 'gov',
// whoisPrivacySupport: false,
// registrationRestrictions: 'governmental',
// dnssecSupport: true,
// idn: false,
// category: 'sponsored',
// description: 'US Government - restricted to US government entities'
// }
`

$3

`typescript
import { getAllTlds, isKnownTld } from 'whoistld';

const allTlds = getAllTlds();
console.log(allTlds);
// ['com', 'net', 'org', 'edu', 'gov', 'mil', ...]

console.log(isKnownTld('com')); // true
console.log(isKnownTld('xyz')); // true
console.log(isKnownTld('invalid')); // false
`

$3

`typescript
import { parseDomain, ParsedDomainSchema } from 'whoistld';

// The result is already validated with Zod
const result = parseDomain('example.com');

// You can also use the schema directly
try {
const validated = ParsedDomainSchema.parse(result);
console.log(validated);
} catch (error) {
console.error('Validation error:', error);
}
`

$3

By default, this package collects anonymous analytics when an unknown TLD is encountered. This helps us identify missing TLDs and improve the package's coverage. No personal data is collected - only the unknown TLD string is sent.

If you prefer to disable this analytics collection, you can do so using the configure function:

`typescript
import { configure } from 'whoistld';

// Disable analytics collection
configure({ disableAnalytics: true });
`

You can also check the current configuration:

`typescript
import { getConfig } from 'whoistld';

const config = getConfig();
console.log(config.disableAnalytics); // false (default) or true if disabled
`

API Reference

$3

Parses a domain name and returns comprehensive information including TLD characteristics.

Parameters:
- input - Domain name (can be full domain, partial, or just TLD)

Returns: ParsedDomain object containing:
- input - Original input string
- tld - Extracted TLD
- domain - Domain name (if present)
- subdomain - Subdomain (if present)
- characteristics - TLD characteristics (or null if TLD is unknown)

$3

Checks if a TLD supports WHOIS privacy.

Returns:
- true if supported
- false if not supported
- null if TLD is unknown

$3

Gets TLD characteristics for a specific TLD.

Returns: TLD characteristics object or null if unknown

$3

Returns an array of all known TLD strings in the database.

$3

Checks if a TLD exists in the database.

$3

Configure the whoistld module.

Parameters:
- options - Configuration object with the following properties:
- disableAnalytics (optional, boolean) - When true, disables analytics collection for missing TLDs. Default: false

$3

Returns the current configuration object.

TLD Characteristics

Each TLD has the following characteristics:

- tld - The TLD string
- whoisPrivacySupport - Whether the TLD supports WHOIS privacy/proxy services
- registrationRestrictions - Type of registration restrictions:
- none - Open to anyone
- governmental - Restricted to government entities
- educational - Restricted to educational institutions
- organizational - Restricted to specific types of organizations
- geographic - Geographic restrictions
- reserved - Reserved/special use
- dnssecSupport - Whether DNSSEC is supported
- idn - Whether Internationalized Domain Names are supported
- category - TLD category:
- generic - Generic TLD
- country-code - Country code TLD
- sponsored - Sponsored TLD with restrictions
- infrastructure - Infrastructure TLD
- test - Test/example TLD
- generic-restricted - Generic restricted TLD
- description - Human-readable description (optional)

Supported TLDs

The package includes data for many popular TLDs including:

- Generic TLDs: com, net, org, info, biz, dev, app, tech, online, store, blog, xyz
- Country Code TLDs: us, uk, de, fr, jp, cn, au, ca, io
- Sponsored/Restricted TLDs: edu, gov, mil, int, museum, coop, aero
- Infrastructure/Test TLDs: arpa, test, localhost, example

TypeScript Types

All types are exported for use in your TypeScript projects:

`typescript
import type {
ParsedDomain,
TldCharacteristics,
RegistrationRestriction,
TldCategory,
WhoistldConfig,
} from 'whoistld';
``

Why This Package?

- Fast: All data is embedded, no API calls or remote requests
- Reliable: No network dependencies means consistent performance
- Type-Safe: Full TypeScript and Zod schema support
- Privacy-Aware: Helps determine if WHOIS privacy is available for a domain
- Comprehensive: Includes data about various TLD characteristics

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.