@visulima/disposable-email-domains 1.0.0-alpha.1

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 (7) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/LICENSE.md +27 -0
  3. package/README.md +197 -0
  4. package/dist/domains.json +1 -0
  5. package/dist/index.d.ts +14 -0
  6. package/dist/index.js +103 -0
  7. package/package.json +57 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,18 @@
1
+ ## @visulima/disposable-email-domains 1.0.0-alpha.1 (2025-12-02)
2
+
3
+ ### Features
4
+
5
+ * implement disposable email domains synchronization workflow and update README ([47713a2](https://github.com/visulima/visulima/commit/47713a2ecf5c746187b6b65352a189e0552ff703))
6
+ * initialize disposable email domains package with configuration and utilities ([ef671a1](https://github.com/visulima/visulima/commit/ef671a14492abae5bbf7324f36b49d24f3f5cf58))
7
+ * update disposable email domains package and enhance synchronization ([dd81823](https://github.com/visulima/visulima/commit/dd818230a2435568317fdb02728a96ec580962a3))
8
+
9
+ ### Miscellaneous Chores
10
+
11
+ * update @visulima/packem version to 2.0.0-alpha.40 across multiple packages ([e5be373](https://github.com/visulima/visulima/commit/e5be373fef8f8dda20c1dee7a1ac30d9b7a7712e))
12
+
13
+ ### Code Refactoring
14
+
15
+ * enhance domain extraction and update README performance metrics ([e391bd0](https://github.com/visulima/visulima/commit/e391bd0ac31ed601066007799bbcf3a38f4e3028))
16
+ * enhance role account prefixes and update README ([b4f3a1f](https://github.com/visulima/visulima/commit/b4f3a1fdf43985f503aecf23b999e3443b52a403))
17
+ * simplify disposable email tests and remove unused functions ([c331ec5](https://github.com/visulima/visulima/commit/c331ec5d93df2b8b564733f2104c373a62fb87ee))
18
+ * update disposable email domains synchronization workflow and README ([c3b3291](https://github.com/visulima/visulima/commit/c3b3291c76a6e4bfa47788341cdf72c34a8987e0))
package/LICENSE.md ADDED
@@ -0,0 +1,27 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 visulima
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ <!-- DEPENDENCIES -->
24
+ <!-- /DEPENDENCIES -->
25
+
26
+ <!-- TYPE_DEPENDENCIES -->
27
+ <!-- /TYPE_DEPENDENCIES -->
package/README.md ADDED
@@ -0,0 +1,197 @@
1
+ <div align="center">
2
+ <h3>visulima disposable-email-domains</h3>
3
+ <p>
4
+ A regularly updated list of disposable and temporary email domains.
5
+ </p>
6
+ </div>
7
+
8
+ <br />
9
+
10
+ <div align="center">
11
+
12
+ [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
13
+
14
+ </div>
15
+
16
+ ---
17
+
18
+ <div align="center">
19
+ <p>
20
+ <sup>
21
+ Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
22
+ </sup>
23
+ </p>
24
+ </div>
25
+
26
+ ---
27
+
28
+ ## Install
29
+
30
+ ```sh
31
+ npm install @visulima/disposable-email-domains
32
+ ```
33
+
34
+ ```sh
35
+ yarn add @visulima/disposable-email-domains
36
+ ```
37
+
38
+ ```sh
39
+ pnpm add @visulima/disposable-email-domains
40
+ ```
41
+
42
+ ## Contributing Sources
43
+
44
+ <!-- START_PLACEHOLDER_CONTRIBUTING -->
45
+
46
+ | Repository | Domains | Success | Performance |
47
+ |------------|---------|---------|-------------|
48
+ | kslr/disposable-email-domains | 112,596 | ✅ | 1.12s (1.7 MB) |
49
+ | FGRibreau/mailchecker | 55,864 | ✅ | 0.61s (838.4 KB) |
50
+ | wesbos/burner-email-providers | 27,284 | ✅ | 0.46s (388.1 KB) |
51
+ | groundcat/disposable-email-domain-list | 27,120 | ✅ | 0.28s (401.7 KB) |
52
+ | disposable/disposable-email-domains | 26,685 | ✅ | 0.53s (375.3 KB) |
53
+ | sublime-security/static-files | 10,523 | ✅ | 0.17s (144.0 KB) |
54
+ | 7c/fakefilter | 8,982 | ✅ | 0.04s (128.9 KB) |
55
+ | disposable-email-domains/disposable-email-domains | 4,932 | ✅ | 0.23s (62.3 KB) |
56
+ | willwhite/freemail | 4,462 | ✅ | 0.02s (61.8 KB) |
57
+ | eser/sanitizer-svc | 3,855 | ✅ | 0.12s (48.9 KB) |
58
+ | unkn0w/disposable-email-domain-list | 3,617 | ✅ | 0.10s (45.8 KB) |
59
+ | MattKetmo/EmailChecker | 2,515 | ✅ | 0.06s (32.4 KB) |
60
+ | GeroldSetz/emailondeck.com-domains | 1,121 | ✅ | 0.07s (15.4 KB) |
61
+ | jespernissen/disposable-maildomain-list | 1,024 | ✅ | 0.01s (13.2 KB) |
62
+ | TheDahoom/disposable-email | 18 | ✅ | 0.06s (234 B) |
63
+
64
+ <!-- END_PLACEHOLDER_CONTRIBUTING -->
65
+ <!-- START_PLACEHOLDER_LAST_UPDATED -->
66
+
67
+ _Last updated: 2025-12-02T08:21:38.381Z_
68
+
69
+ <!-- END_PLACEHOLDER_LAST_UPDATED -->
70
+
71
+ ## Usage
72
+
73
+ ### Basic Usage
74
+
75
+ ```typescript
76
+ import { isDisposableEmail, areDisposableEmails } from "@visulima/disposable-email-domains";
77
+
78
+ // Check if an email is disposable
79
+ if (isDisposableEmail("user@mailinator.com")) {
80
+ console.log("Disposable email detected!");
81
+ }
82
+
83
+ // Check multiple emails at once
84
+ const emails = ["user@mailinator.com", "test@guerrillamail.com", "valid@example.com"];
85
+ const results = areDisposableEmails(emails);
86
+
87
+ results.forEach((isDisposable, email) => {
88
+ console.log(`${email}: ${isDisposable ? "disposable" : "valid"}`);
89
+ });
90
+ ```
91
+
92
+ ### Whitelist Protection
93
+
94
+ 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.
95
+
96
+ ```typescript
97
+ import { isDisposableEmail } from "@visulima/disposable-email-domains";
98
+
99
+ // Common email providers are automatically whitelisted
100
+ isDisposableEmail("user@gmail.com"); // false - whitelisted
101
+ isDisposableEmail("user@yahoo.com"); // false - whitelisted
102
+ isDisposableEmail("user@outlook.com"); // false - whitelisted
103
+
104
+ // Disposable emails are still detected
105
+ isDisposableEmail("user@mailinator.com"); // true - disposable
106
+ ```
107
+
108
+ ### Custom Domains
109
+
110
+ You can provide custom disposable domains to check against:
111
+
112
+ ```typescript
113
+ import { isDisposableEmail, areDisposableEmails } from "@visulima/disposable-email-domains";
114
+
115
+ const customDomains = new Set(["custom-disposable.com", "temp-mail.org"]);
116
+
117
+ // Check with custom domains
118
+ if (isDisposableEmail("user@custom-disposable.com", customDomains)) {
119
+ console.log("Custom disposable email detected!");
120
+ }
121
+
122
+ // Batch check with custom domains
123
+ const emails = ["user@custom-disposable.com", "user@example.com"];
124
+ const results = areDisposableEmails(emails, customDomains);
125
+
126
+ results.forEach((isDisposable, email) => {
127
+ console.log(`${email}: ${isDisposable ? "disposable" : "valid"}`);
128
+ });
129
+ ```
130
+
131
+ ## API Reference
132
+
133
+ ### Functions
134
+
135
+ #### `isDisposableEmail(email, customDomains?)`
136
+
137
+ 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.
138
+
139
+ - **Parameters:**
140
+ - `email` (string): The email address to check
141
+ - `customDomains?` (Set<string>): Optional set of additional disposable domains to check
142
+ - **Returns:** `boolean` - True if the email is from a disposable domain
143
+ - **Features:**
144
+ - Case-insensitive matching
145
+ - Supports wildcard matching (e.g., `subdomain.33mail.com` matches `33mail.com`)
146
+ - Automatically whitelists common email providers
147
+
148
+ #### `areDisposableEmails(emails, customDomains?)`
149
+
150
+ Checks multiple email addresses at once. Returns a Map for efficient lookups.
151
+
152
+ - **Parameters:**
153
+ - `emails` (string[]): Array of email addresses to check
154
+ - `customDomains?` (Set<string>): Optional set of additional disposable domains to check
155
+ - **Returns:** `Map<string, boolean>` - Map of email to boolean indicating if it's disposable
156
+ - **Features:**
157
+ - Batch processing for better performance
158
+ - Same whitelist protection as `isDisposableEmail`
159
+
160
+ ### How It Works
161
+
162
+ 1. **Domain List**: The package maintains a regularly updated list of disposable email domains from multiple trusted sources (see Contributing Sources above).
163
+
164
+ 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.
165
+
166
+ 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.
167
+
168
+ 4. **Custom Domains**: You can provide additional disposable domains to check against, useful for domain-specific blocklists.
169
+
170
+ ## Related
171
+
172
+ ## Supported Node.js Versions
173
+
174
+ Libraries in this ecosystem make the best effort to track [Node.js’ release schedule](https://github.com/nodejs/release#release-schedule).
175
+ Here’s [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
176
+
177
+ ## Contributing
178
+
179
+ If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.
180
+
181
+ > **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
182
+
183
+ ## Credits
184
+
185
+ - [Daniel Bannert](https://github.com/prisis)
186
+ - [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
187
+
188
+ ## License
189
+
190
+ The visulima disposable-email-domains is open-sourced software licensed under the [MIT][license-url]
191
+
192
+ [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
193
+ [typescript-url]: https://www.typescriptlang.org/ "TypeScript"
194
+ [license-image]: https://img.shields.io/npm/l/@visulima/disposable-email-domains?color=blueviolet&style=for-the-badge
195
+ [license-url]: LICENSE.md "license"
196
+ [npm-image]: https://img.shields.io/npm/v/@visulima/disposable-email-domains/latest.svg?style=for-the-badge&logo=npm
197
+ [npm-url]: https://www.npmjs.com/package/@visulima/disposable-email-domains/v/latest "npm"