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

npm install whoistld

Usage

Basic Domain Parsing

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'
//   }
// }

Check WHOIS Privacy Support

import { supportsWhoisPrivacy } from 'whoistld';

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

Get TLD Data Directly

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'
// }

List All Available TLDs

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

Using with Zod Validation

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);
}

Disabling Analytics

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:

import { configure } from 'whoistld';

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

You can also check the current configuration:

import { getConfig } from 'whoistld';

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

API Reference

parseDomain(input: string): ParsedDomain

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)

supportsWhoisPrivacy(tld: string): boolean | null

Checks if a TLD supports WHOIS privacy.

Returns:

• true if supported
• false if not supported
• null if TLD is unknown

getTldData(tld: string): TldCharacteristics | null

Gets TLD characteristics for a specific TLD.

Returns: TLD characteristics object or null if unknown

getAllTlds(): string[]

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

isKnownTld(tld: string): boolean

Checks if a TLD exists in the database.

configure(options: WhoistldConfig): void

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

getConfig(): WhoistldConfig

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:

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.