@visulima/disposable-email-domains 1.0.0-alpha.16 → 1.0.0-alpha.18

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## @visulima/disposable-email-domains [1.0.0-alpha.18](https://github.com/visulima/visulima/compare/@visulima/disposable-email-domains@1.0.0-alpha.17...@visulima/disposable-email-domains@1.0.0-alpha.18) (2026-06-30)
+
+### Bug Fixes
+
+* **disposable-email-domains:** emit `export =` for /domains types ([b80fd58](https://github.com/visulima/visulima/commit/b80fd587995e376f9cb6d872e387b5fc2d96e6d1))
+
+### Styles
+
+* cs fixes ([2a960bb](https://github.com/visulima/visulima/commit/2a960bb1772c9dc70080e2d75d3a0d827034e294))
+
+### Miscellaneous Chores
+
+* add fallow code-intelligence across all packages ([a3b4821](https://github.com/visulima/visulima/commit/a3b48215002e86fed20f2973038b5d4a0aa1ce04))
+
+### Continuous Integration
+
+* **fallow:** make fallow:health advisory (--report-only) ([d57148e](https://github.com/visulima/visulima/commit/d57148ea0e3556b4c24d8d336b9fa14987f5dc7d))
+* **lint:** raise eslint job timeout and cache slow per-package eslint runs ([#717](https://github.com/visulima/visulima/issues/717)) ([c93878d](https://github.com/visulima/visulima/commit/c93878dbfa1888cc834704448ae6eefd3098597e)), closes [#713](https://github.com/visulima/visulima/issues/713)
+
+## @visulima/disposable-email-domains [1.0.0-alpha.17](https://github.com/visulima/visulima/compare/@visulima/disposable-email-domains@1.0.0-alpha.16...@visulima/disposable-email-domains@1.0.0-alpha.17) (2026-06-13)
+
+### Features
+
+* **disposable-email-domains:** add edge support, allowlist, bare-domain api to disposable check ([a3d1d95](https://github.com/visulima/visulima/commit/a3d1d9551cf857d0c11d245e7126cde73a302fd7))
+
+### Documentation
+
+* **disposable-email-domains:** refresh benchmark timings in README ([5ea04f7](https://github.com/visulima/visulima/commit/5ea04f75479bffe2bceee8d0e9f72285734dcbbf))
+* regenerate package tables ([287ded9](https://github.com/visulima/visulima/commit/287ded982f6d4bcbc3401020732302ebde170933))
+
+### Build System
+
+* **deps:** update disposable-email-domains dependencies ([77c2d3b](https://github.com/visulima/visulima/commit/77c2d3b862ab792a574c95de25effaf58d739c72))
+
+
+### Dependencies
+
+* **@visulima/tabular:** upgraded to 4.0.0-alpha.14
+
 ## @visulima/disposable-email-domains [1.0.0-alpha.16](https://github.com/visulima/visulima/compare/@visulima/disposable-email-domains@1.0.0-alpha.15...@visulima/disposable-email-domains@1.0.0-alpha.16) (2026-06-04)
 
 ### Bug Fixes

package/README.md

@@ -54,27 +54,27 @@ pnpm add @visulima/disposable-email-domains
 
 | Repository | Domains | Success | Performance |
 |------------|---------|---------|-------------|
-| kslr/disposable-email-domains | 120,210 | ✅ | 1.03s (1.8 MB) |
-| disposable/disposable-email-domains | 72,543 | ✅ | 0.59s (1.1 MB) |
-| FGRibreau/mailchecker | 56,048 | ✅ | 0.60s (840.7 KB) |
-| wesbos/burner-email-providers | 27,283 | ✅ | 0.07s (388.1 KB) |
-| groundcat/disposable-email-domain-list | 23,767 | ✅ | 0.12s (332.9 KB) |
-| sublime-security/static-files | 10,523 | ✅ | 0.37s (144.0 KB) |
-| 7c/fakefilter | 9,792 | ✅ | 0.07s (135.9 KB) |
-| disposable-email-domains/disposable-email-domains | 5,739 | ✅ | 0.12s (73.0 KB) |
-| willwhite/freemail | 4,462 | ✅ | 0.13s (61.8 KB) |
-| eser/sanitizer-svc | 3,855 | ✅ | 0.12s (48.9 KB) |
-| unkn0w/disposable-email-domain-list | 3,617 | ✅ | 0.20s (45.8 KB) |
-| MattKetmo/EmailChecker | 2,515 | ✅ | 0.20s (32.4 KB) |
-| GeroldSetz/emailondeck.com-domains | 1,121 | ✅ | 0.09s (15.4 KB) |
-| castle/disposable-email-domains | 1,000 | ✅ | 0.33s (12.9 KB) |
-| jespernissen/disposable-maildomain-list | 994 | ✅ | 0.06s (12.8 KB) |
-| TheDahoom/disposable-email | 18 | ✅ | 0.11s (234 B) |
+| kslr/disposable-email-domains | 123,343 | ✅ | 1.18s (1.8 MB) |
+| disposable/disposable-email-domains | 74,328 | ✅ | 0.50s (1.1 MB) |
+| FGRibreau/mailchecker | 56,360 | ✅ | 0.45s (846.7 KB) |
+| wesbos/burner-email-providers | 27,279 | ✅ | 0.45s (388.1 KB) |
+| groundcat/disposable-email-domain-list | 17,012 | ✅ | 0.55s (240.3 KB) |
+| sublime-security/static-files | 10,522 | ✅ | 0.17s (144.0 KB) |
+| 7c/fakefilter | 10,151 | ✅ | 0.32s (140.8 KB) |
+| disposable-email-domains/disposable-email-domains | 7,860 | ✅ | 0.21s (109.1 KB) |
+| willwhite/freemail | 4,462 | ✅ | 0.21s (61.8 KB) |
+| eser/sanitizer-svc | 3,855 | ✅ | 0.23s (48.9 KB) |
+| unkn0w/disposable-email-domain-list | 3,618 | ✅ | 0.08s (45.8 KB) |
+| MattKetmo/EmailChecker | 2,515 | ✅ | 0.14s (32.4 KB) |
+| GeroldSetz/emailondeck.com-domains | 1,121 | ✅ | 0.22s (15.4 KB) |
+| castle/disposable-email-domains | 1,000 | ✅ | 0.12s (13.4 KB) |
+| jespernissen/disposable-maildomain-list | 993 | ✅ | 0.10s (12.8 KB) |
+| TheDahoom/disposable-email | 18 | ✅ | 0.22s (234 B) |
 
 <!-- END_PLACEHOLDER_CONTRIBUTING -->
 <!-- START_PLACEHOLDER_LAST_UPDATED -->
 
-_Last updated: 2026-06-04_
+_Last updated: 2026-06-30_
 
 <!-- END_PLACEHOLDER_LAST_UPDATED -->
 
@@ -99,86 +99,172 @@ results.forEach((isDisposable, email) => {
 });
 ```
 
-### Whitelist Protection
+### Provider whitelist (baked into the list)
 
-This package automatically whitelists common email providers (like Gmail, Yahoo, Outlook, etc.) from the [email-providers](https://github.com/derhuerst/email-providers) package. This ensures that legitimate email providers are never incorrectly flagged as disposable, even if they appear in the disposable domains list.
+Common email providers (Gmail, Yahoo, Outlook, etc.) from the [email-providers](https://github.com/derhuerst/email-providers) package are filtered **at list-generation time** — they are removed from the published `domains.json` before it ships, so they can never be flagged as disposable. This is _not_ a runtime allowlist: there is no provider-whitelist parameter at call time. If you need a runtime escape hatch for a specific domain, use the `allowDomains` option below.
 
 ```typescript
 import { isDisposableEmail } from "@visulima/disposable-email-domains";
 
-// Common email providers are automatically whitelisted
-isDisposableEmail("user@gmail.com"); // false - whitelisted
-isDisposableEmail("user@yahoo.com"); // false - whitelisted
-isDisposableEmail("user@outlook.com"); // false - whitelisted
+// Common providers are absent from the list, so they are never flagged
+isDisposableEmail("user@gmail.com"); // false
+isDisposableEmail("user@yahoo.com"); // false
+isDisposableEmail("user@outlook.com"); // false
 
 // Disposable emails are still detected
 isDisposableEmail("user@mailinator.com"); // true - disposable
 ```
 
-### Custom Domains
+### Custom domains
 
-You can provide custom disposable domains to check against:
+You can provide custom disposable domains to check on top of the built-in list. Custom domains use the same wildcard/subdomain semantics as the built-in list (a custom `custom-disposable.com` also matches `sub.custom-disposable.com`):
 
 ```typescript
 import { isDisposableEmail, areDisposableEmails } from "@visulima/disposable-email-domains";
 
 const customDomains = new Set(["custom-disposable.com", "temp-mail.org"]);
 
-// Check with custom domains
+// Legacy form: pass a Set directly
 if (isDisposableEmail("user@custom-disposable.com", customDomains)) {
     console.log("Custom disposable email detected!");
 }
 
+// Options-object form (equivalent)
+isDisposableEmail("user@custom-disposable.com", { customDomains });
+
 // Batch check with custom domains
-const emails = ["user@custom-disposable.com", "user@example.com"];
-const results = areDisposableEmails(emails, customDomains);
+const results = areDisposableEmails(["user@custom-disposable.com", "user@example.com"], customDomains);
+```
 
-results.forEach((isDisposable, email) => {
-    console.log(`${email}: ${isDisposable ? "disposable" : "valid"}`);
-});
+### Runtime allowlist (`allowDomains`)
+
+If a legitimate customer domain wrongly ends up in the list, allowlist it at runtime without forking. The allowlist is checked **before** the disposable list and wins over both the built-in list and `customDomains`. It also honours subdomain matching:
+
+```typescript
+import { isDisposableEmail } from "@visulima/disposable-email-domains";
+
+const allowDomains = new Set(["legit-customer.com"]);
+
+isDisposableEmail("user@legit-customer.com", { allowDomains }); // false, even if it's in the list
+isDisposableEmail("user@mail.legit-customer.com", { allowDomains }); // false (subdomain)
+```
+
+### Bare-domain checks
+
+If you already have a domain (e.g. from an MX lookup or a parsed signup form), use `isDisposableDomain` / `extractDomain` directly instead of fabricating an `x@domain` address:
+
+```typescript
+import { isDisposableDomain, extractDomain } from "@visulima/disposable-email-domains";
+
+isDisposableDomain("mailinator.com"); // true
+extractDomain("User@Example.COM"); // "example.com"
+```
+
+### Edge / browser / bundled runtimes
+
+By default the package reads `dist/domains.json` from disk via `node:fs`. That does not work in Cloudflare Workers, Next.js middleware/edge, Deno, or bundles that relocate `index.js` away from the data file. For those environments, import the list statically and inject it once at startup with `setDomains`:
+
+```typescript
+import { setDomains, isDisposableEmail } from "@visulima/disposable-email-domains";
+import domains from "@visulima/disposable-email-domains/domains" with { type: "json" };
+
+setDomains(domains);
+
+isDisposableEmail("user@mailinator.com"); // true — no filesystem access
+```
+
+On Node you can also call `await preload()` once at startup to move the synchronous read+parse of the multi-megabyte list off the request hot path, and `isListLoaded()` to detect the degraded fail-open state (e.g. a missing/corrupt data file):
+
+```typescript
+import { preload, isListLoaded } from "@visulima/disposable-email-domains";
+
+await preload();
+
+if (!isListLoaded()) {
+    // The built-in list failed to load — disposable detection is disabled.
+}
+```
+
+### Raw domain list (`./domains`)
+
+The raw, sorted array of disposable domains is exported from the `./domains` subpath. In Node ESM you must use a JSON import attribute:
+
+```typescript
+import domains from "@visulima/disposable-email-domains/domains" with { type: "json" };
+
+console.log(domains.length); // number of disposable domains
 ```
 
 ## API Reference
 
 ### Functions
 
-#### `isDisposableEmail(email, customDomains?)`
+All check functions accept either a `Set<string>` of additional disposable domains (legacy) or an options object:
+
+```typescript
+interface DisposableEmailOptions {
+    /** Domains that should never be treated as disposable (wins over everything, supports subdomains). */
+    allowDomains?: Set<string>;
+    /** Extra disposable domains to check on top of the built-in list (supports subdomains). */
+    customDomains?: Set<string>;
+}
+```
 
-Checks if an email address is from a disposable email service. Common email providers (Gmail, Yahoo, Outlook, etc.) are automatically whitelisted and will never be flagged as disposable.
+#### `isDisposableEmail(email, options?)`
+
+Checks if an email address is from a disposable email service.
 
 - **Parameters:**
     - `email` (string): The email address to check
-    - `customDomains?` (Set<string>): Optional set of additional disposable domains to check
-- **Returns:** `boolean` - True if the email is from a disposable domain
+    - `options?` (`Set<string>` | `DisposableEmailOptions`): A set of additional disposable domains, or an options object
+- **Returns:** `boolean` — True if the email is from a disposable domain
 - **Features:**
     - Case-insensitive matching
-    - Supports wildcard matching (e.g., `subdomain.33mail.com` matches `33mail.com`)
-    - Automatically whitelists common email providers
+    - Wildcard/subdomain matching (e.g., `subdomain.33mail.com` matches `33mail.com`) for built-in, custom, and allowlisted domains
 
-#### `areDisposableEmails(emails, customDomains?)`
+#### `areDisposableEmails(emails, options?)`
 
 Checks multiple email addresses at once. Returns a Map for efficient lookups.
 
 - **Parameters:**
     - `emails` (string[]): Array of email addresses to check
-    - `customDomains?` (Set<string>): Optional set of additional disposable domains to check
-- **Returns:** `Map<string, boolean>` - Map of email to boolean indicating if it's disposable
-- **Features:**
-    - Batch processing for better performance
-    - Same whitelist protection as `isDisposableEmail`
+    - `options?` (`Set<string>` | `DisposableEmailOptions`): A set of additional disposable domains, or an options object
+- **Returns:** `Map<string, boolean>` — Map of email to boolean indicating if it's disposable
+
+#### `isDisposableDomain(domain, options?)`
+
+Like `isDisposableEmail` but accepts a bare domain rather than a full email address.
+
+#### `extractDomain(email)`
+
+Returns the normalized (lowercased, trimmed) domain of an email address, or `undefined` if the address is invalid.
+
+#### `setDomains(domains)`
+
+Injects the disposable-domain list explicitly, bypassing the Node filesystem loader. Use in edge/browser/bundled runtimes (see [Edge / browser / bundled runtimes](#edge--browser--bundled-runtimes)).
+
+#### `preload()`
+
+Eagerly loads the built-in list (Node) so the first check does not stall the event loop. Returns a `Promise<void>`.
+
+#### `isListLoaded()`
+
+Returns `true` once the built-in list is loaded; `false` if it has not been accessed yet or failed to load (missing/corrupt data file). Useful to detect the degraded fail-open state.
 
 ### How It Works
 
 1. **Domain List**: The package maintains a regularly updated list of disposable email domains from multiple trusted sources (see Contributing Sources above).
 
-2. **Whitelist Protection**: Common email providers from the [email-providers](https://github.com/derhuerst/email-providers) package are automatically whitelisted. This ensures legitimate providers like Gmail, Yahoo, and Outlook are never incorrectly flagged as disposable.
+2. **Provider whitelist**: Common email providers from the [email-providers](https://github.com/derhuerst/email-providers) package are filtered out **when the list is generated**, so they are simply absent from the published list. There is no runtime provider-whitelist mechanism; use `allowDomains` for per-call exceptions.
 
 3. **Wildcard Matching**: The package supports wildcard matching by checking parent domains. For example, `subdomain.33mail.com` will match `33mail.com` if it's in the disposable list.
 
-4. **Custom Domains**: You can provide additional disposable domains to check against, useful for domain-specific blocklists.
+4. **Custom & allow domains**: You can supply additional disposable domains (`customDomains`) or a runtime allowlist (`allowDomains`), both with subdomain matching.
 
 ## Related
 
+- [@visulima/email](https://github.com/visulima/visulima/tree/main/packages/email/email) — multi-provider email library that re-exports this check at `@visulima/email/validation/disposable-email-domains`.
+
 ## Supported Node.js Versions
 
 Libraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).

package/dist/domains.d.ts

@@ -0,0 +1,2 @@
+declare const domains: string[];
+export = domains;