FreeScript
rdapper
by jakejarvis · version 2026.11.15 · updated yesterday
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 152 KB
- Code check
- Clean
- Licence
- MIT
- Released
- Nov 2026
🎩 RDAP/WHOIS fetcher, parser, and normalizer for Node
🎩 rdapper
RDAP‑first domain registration lookups with WHOIS fallback. Produces a single, normalized record shape regardless of source.
Quick Start
Normalize arbitrary input (domain or URL) to its registrable domain (eTLD+1):
Convenience helpers to quickly check availability:
API
For quick checks, a minimal CLI is included:
Domains are looked up one at a time, in order, printing each result as JSON; the exit code is
Edge runtimes (e.g., Vercel Edge)
WHOIS requires a raw TCP connection over port 43 via
By default, rdapper fetches IANA's RDAP bootstrap registry from [
For production applications that perform many domain lookups, you can take control of bootstrap data caching by fetching and caching the data yourself, then passing it to rdapper using the
**W
…
RDAP‑first domain registration lookups with WHOIS fallback. Produces a single, normalized record shape regardless of source.
- RDAP‑first lookup via IANA bootstrap with automatic WHOIS fallback when needed
- Smart WHOIS client (TCP 43): authoritative TLD discovery, registrar referral follow, and curated exceptions
- Rich, normalized results: registrar, contacts, nameservers, EPP statuses, key dates, DNSSEC, privacy flag, source metadata
- RDAP enrichment: follows related/entity/registrar links (bounded) to fill in missing details
- TypeScript‑first: shipped types, ESM‑only, zero external HTTP client (uses global
fetch)
IMPORTANT
Edge runtimes (e.g., Vercel Edge, Cloudflare Workers) do not support WHOIS (TCP 43 vianode:net). Use RDAP‑only mode by setting{ rdapOnly: true }.
TIPInstall
Seerdapperin action on Domainstack!
npm install rdapperQuick Start
import { lookup } from "rdapper";
const { ok, record, error } = await lookup("example.com");
if (!ok) throw new Error(error);
console.log(record); // normalized DomainRecordNormalize arbitrary input (domain or URL) to its registrable domain (eTLD+1):
import { toRegistrableDomain } from "rdapper";
toRegistrableDomain("https://sub.example.co.uk/page"); // => "example.co.uk"
toRegistrableDomain("spark-public.s3.amazonaws.com"); // => "amazonaws.com" (ICANN-only default)
toRegistrableDomain("www.google.uk.com"); // => "google.uk.com" (CentralNic sub-registry)
toRegistrableDomain("192.168.0.1"); // => nullConvenience helpers to quickly check availability:
import { isRegistered, isAvailable } from "rdapper";
await isRegistered("example.com"); // => true
await isRegistered("likely-unregistered-thing-320485230458.com"); // => false
await isAvailable("example.com"); // => false
await isAvailable("likely-unregistered-thing-320485230458.com"); // => trueAPI
lookup(domain, options?) => Promise- Tries RDAP first if supported by the domain’s TLD; if unavailable or fails, falls back to WHOIS (unless toggled off).
- Result is
{ ok: boolean, record?: DomainRecord, error?: string }. domainmay be Unicode (münchen.de) and may carry surrounding whitespace or a trailing dot; the lowercase punycode form is what gets queried.domainmust be a registrable name (example.com,example.co.uk), not a subdomain or a bare public suffix:www.example.comfails withinvalid_inputnamingexample.com, since the registry would otherwise answer "not registered". UsetoRegistrableDomainto normalize hostnames and URLs first.toRegistrableDomain(input, options?) => string | null- Normalizes a domain or URL to its registrable domain (eTLD+1), the name
lookup()accepts. A name under a sub-registry keeps its own label (google.uk.com, notuk.com). - Returns the registrable domain string, or
nullfor IPs/invalid input; options are forwarded totldts(e.g.,allowPrivateDomains). getDomainTld(domain, options?) => string | null- The suffix a name is registered under, matching the
tlda lookup reports: the ICANN public suffix (co.uk), or a sub-registry's (uk.comforgoogle.uk.com). isRegistered(domain, options?) => PromiseisAvailable(domain, options?) => Promise- Reject when the lookup fails, with an
RdapperError(exported) whosecode,phase,server, andretryAfterMsmirror the result'serrorCode,errorPhase,errorServer, andretryAfterMs. An abort keeps the name"AbortError". finalizeContact(contact, redactedHint?) => Contact- Cleans a contact: drops placeholder values (recording them in
redactedFields), drops a registry handle (JJ1234-IS) given as the name or organization, setsprivacyService, resolvescountry/countryCode, and setsredacted. Safe to re-run on an already-cleaned contact, e.g. to upgrade contacts stored by an older version. isPrivacyContact(contact) => boolean- True when the contact hides who it is: a privacy service is named, or something was withheld and no name or organization is left.
normalizeEppStatus(status) => string- Maps a status in either spelling to its EPP code (
"client transfer prohibited"→"clientTransferProhibited", RDAP"active"→"ok"), leaving other values as they are. Useful for upgrading statuses stored by an older version.
For quick checks, a minimal CLI is included:
npx rdapper example.com example.org
echo "example.com" | npx rdapperDomains are looked up one at a time, in order, printing each result as JSON; the exit code is
1 when any lookup fails.Edge runtimes (e.g., Vercel Edge)
WHOIS requires a raw TCP connection over port 43 via
node:net, which is not available on edge runtimes. rdapper lazily loads node:net only when the WHOIS path is taken.
- Prefer RDAP only on edge:
import { lookup } from "rdapper";
const res = await lookup("example.com", { rdapOnly: true });
- If
rdapOnlyis omitted and the code path reaches WHOIS on edge, rdapper throws a clear runtime error advising to run in Node or set{ rdapOnly: true }.
By default, rdapper fetches IANA's RDAP bootstrap registry from [
https://data.iana.org/rdap/dns.json](https://data.iana.org/rdap/dns.json) on every RDAP lookup to discover the authoritative RDAP servers for a given TLD. While this ensures you always have up-to-date server mappings, it also adds latency and a network dependency to each lookup.For production applications that perform many domain lookups, you can take control of bootstrap data caching by fetching and caching the data yourself, then passing it to rdapper using the
customBootstrapData option. This eliminates redundant network requests and gives you full control over cache invalidation.**W
…