@yarigai/iana-tlds 1.0.102 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +44 -11
  2. package/package.json +12 -6
package/README.md CHANGED
@@ -1,13 +1,46 @@
1
1
  # @yarigai/iana-tlds
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@yarigai/iana-tlds.svg)](https://www.npmjs.com/package/@yarigai/iana-tlds)
4
- [![License: MIT](https://img.shields.io/npm/l/@yarigai/iana-tlds.svg)](LICENSE)
5
4
  [![CI](https://github.com/yarigai/iana-tlds/actions/workflows/ci.yml/badge.svg)](https://github.com/yarigai/iana-tlds/actions/workflows/ci.yml)
6
- [![IANA sync](https://img.shields.io/badge/IANA_sync-daily-blue.svg)](https://data.iana.org/TLD/tlds-alpha-by-domain.txt)
5
+ [![Bundle size](https://deno.bundlejs.com/badge?q=@yarigai/iana-tlds)](https://bundlejs.com/?q=@yarigai/iana-tlds)
6
+ [![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
7
+ [![TLD list updated](https://img.shields.io/github/last-commit/yarigai/iana-tlds/main?path=src%2Fdata%2Ftlds.ts&label=TLD%20list%20updated)](https://github.com/yarigai/iana-tlds/commits/main/src/data/tlds.ts)
8
+ [![License: MIT](https://img.shields.io/npm/l/@yarigai/iana-tlds.svg)](LICENSE)
9
+
10
+ Validate email and domain TLDs against the official IANA list, checked daily. Zero dependencies, fully typed, ESM + CJS.
11
+
12
+ ## Why
13
+
14
+ Most email and domain validators decide what a TLD is with a regex or a list someone copied years ago. Both fail in production. A pattern like `\.[a-z]{2,6}$` rejects real TLDs such as `.photography` or the internationalized `.xn--p1ai` (Russian `.рф`), and happily accepts typos like `.con` or `.comm`. Hardcoded lists go stale: IANA added `.web` in 2026, and it retires TLDs too (`.goo` is gone). This package checks the TLD against IANA's [root zone list](https://data.iana.org/TLD/tlds-alpha-by-domain.txt), bundled at build time, with no network call at runtime.
15
+
16
+ ```ts
17
+ import { isValidEmail } from "@yarigai/iana-tlds";
18
+
19
+ isValidEmail("ana@studio.photography"); // true
20
+ isValidEmail("ana@example.xn--p1ai"); // true
21
+ isValidEmail("ana@example.con"); // false, unknown_tld
22
+ ```
23
+
24
+ ### How it compares
25
+
26
+ Results from running each package's latest npm release on 2026-09-28.
27
+
28
+ | | `@yarigai/iana-tlds` | [`tlds`][tlds] | [`validator`][validator] `isEmail` | [`email-validator`][email-validator] | [`is-valid-domain`][is-valid-domain] |
29
+ | ---------------------- | -------------------- | ------------------- | ---------------------------------- | ------------------------------------ | ------------------------------------ |
30
+ | Rejects `.con` | yes | yes | no | no | no |
31
+ | Accepts `.photography` | yes | yes | yes | yes | yes |
32
+ | Accepts `.xn--p1ai` | yes | Unicode only (`рф`) | yes | no | yes |
33
+ | Includes `.web` | yes | no | n/a (no TLD list) | n/a (no TLD list) | n/a (no TLD list) |
34
+ | Last npm release | on IANA list change | 2025-10-22 | 2026-04-02 | 2018-05-27 | 2022-02-22 |
35
+ | Runtime dependencies | 0 | 0 | 0 | 0 | 1 (`punycode`) |
36
+ | TypeScript types | bundled | bundled | via `@types/validator` | bundled | bundled |
7
37
 
8
- Always up-to-date IANA TLD list for domain validation in production systems.
38
+ `tlds` exports the list only, with no validation function. `validator` and `email-validator` check syntax well and can be combined with this package, which only answers "is this TLD real?". IDN TLDs are matched in Punycode form (`xn--p1ai`), so convert Unicode domains with `domainToASCII` from `node:url` first.
9
39
 
10
- Data is sourced directly from the [IANA root zone database](https://data.iana.org/TLD/tlds-alpha-by-domain.txt) and bundled at publish time. Zero runtime dependencies — all validation calls are synchronous.
40
+ [tlds]: https://www.npmjs.com/package/tlds
41
+ [validator]: https://www.npmjs.com/package/validator
42
+ [email-validator]: https://www.npmjs.com/package/email-validator
43
+ [is-valid-domain]: https://www.npmjs.com/package/is-valid-domain
11
44
 
12
45
  ## Installation
13
46
 
@@ -26,7 +59,7 @@ pnpm add @yarigai/iana-tlds
26
59
  ```ts
27
60
  import { validateEmail, isValidEmail } from "@yarigai/iana-tlds";
28
61
 
29
- // Detailed result — discriminate on `valid`
62
+ // Detailed result - discriminate on `valid`
30
63
  const result = validateEmail(email);
31
64
  if (result.valid) {
32
65
  console.log(result.tld); // e.g. "com", "mx", "org"
@@ -36,9 +69,9 @@ if (result.valid) {
36
69
  }
37
70
 
38
71
  // Boolean shorthand
39
- isValidEmail(email); // true — TLD is IANA-registered
40
- isValidEmail(unknownTldEmail); // false — TLD not in IANA list
41
- isValidEmail("not-an-email"); // false — invalid format
72
+ isValidEmail(email); // true - TLD is IANA-registered
73
+ isValidEmail(unknownTldEmail); // false - TLD not in IANA list
74
+ isValidEmail("not-an-email"); // false - invalid format
42
75
  ```
43
76
 
44
77
  ### Work with the raw TLD list
@@ -64,7 +97,7 @@ import { tldsList, lastUpdated, validateEmail, isValidEmail } from "@yarigai/ian
64
97
  ### `validateEmail(email: string): EmailValidation`
65
98
 
66
99
  Validates whether an email address has a valid IANA-registered TLD. Only the
67
- TLD portion of the domain is checked — local-part syntax and DNS resolution
100
+ TLD portion of the domain is checked - local-part syntax and DNS resolution
68
101
  are outside the scope of this function.
69
102
 
70
103
  Returns an `EmailValidation` discriminated union:
@@ -137,8 +170,8 @@ Please open an issue first for non-trivial changes.
137
170
 
138
171
  ## License
139
172
 
140
- MIT — see [LICENSE](LICENSE).
173
+ MIT - see [LICENSE](LICENSE).
141
174
 
142
175
  ---
143
176
 
144
- Maintained by [Yarigai](https://yarigai.mx) — Enterprise Technology Architecture & Strategic IT Consulting.
177
+ Maintained by [Yarigai](https://yarigai.mx) - Enterprise Technology Architecture & Strategic IT Consulting.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@yarigai/iana-tlds",
3
- "version": "1.0.102",
4
- "description": "Always up-to-date list of valid Top-Level Domains (TLDs) sourced directly from IANA",
3
+ "version": "1.1.0",
4
+ "description": "Validate email and domain TLDs against the official IANA list, checked daily. Zero dependencies, TypeScript types, ESM + CJS.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
7
7
  "module": "./dist/index.js",
@@ -26,12 +26,18 @@
26
26
  "node": ">=18"
27
27
  },
28
28
  "keywords": [
29
- "iana",
29
+ "email",
30
+ "email-validation",
31
+ "domain",
32
+ "domain-validation",
30
33
  "tld",
31
34
  "tlds",
32
- "domains",
35
+ "iana",
36
+ "validator",
33
37
  "validation",
34
- "email"
38
+ "typescript",
39
+ "idn",
40
+ "punycode"
35
41
  ],
36
42
  "author": {
37
43
  "name": "Yarigai",
@@ -45,7 +51,7 @@
45
51
  "license": "MIT",
46
52
  "repository": {
47
53
  "type": "git",
48
- "url": "https://github.com/yarigai/iana-tlds.git"
54
+ "url": "git+https://github.com/yarigai/iana-tlds.git"
49
55
  },
50
56
  "bugs": {
51
57
  "url": "https://github.com/yarigai/iana-tlds/issues"