@mikkelscheike/email-provider-links 2.8.2 → 3.0.0

package/README.md

@@ -8,20 +8,21 @@ A robust TypeScript library providing direct links to **93 email providers** (18
 
 **[Live Demo](https://demo.mikkelscheike.com)** - Test the library with any email address and see it in action!
 
-## ✨ New in Version 2.7.0
-
-- 🚀 **Modern TypeScript**: Updated to latest TypeScript 2025 standards with strict type checking
-- 🌍 **Enhanced International Support**: Improved IDN validation and Punycode handling
-- 📧 **Advanced Email Validation**: Comprehensive validation with detailed error reporting
-- 🔄 **Batch Processing**: Efficiently process multiple emails with deduplication
-- 🛡️ **Improved Security**: Enhanced cryptographic integrity verification
-- ⚡ **Better Performance**: Optimized concurrent DNS with smart caching
-- 🎯 **Developer Experience**: Enhanced error messages and debugging information
-- 📊 **Development Mode**: Memory usage tracking when NODE_ENV=development
+## ✨ New in Version 3.0.0
+
+- 🚀 **Performance Optimizations**: Further improved DNS resolution and caching
+- 🎯 **Enhanced Precision**: Adjusted performance thresholds based on real-world metrics
+- 🛡️ **Security Updates**: Removed legacy detection methods and updated security hashes
+- 📝 **TypeScript Improvements**: Resolved TypeScript errors and enhanced type safety
+- 📚 **Documentation**: Consolidated and improved documentation for better clarity
+- ⚡ **Infrastructure**: Optimized build process and development workflow
+- 🧪 **Testing**: Expanded test coverage to 445 comprehensive tests
+- 🔄 **Provider Updates**: Added support for 23 new email providers
+- 🔍 **Advanced Alias Detection**: Refined provider-specific email alias handling for dots, plus addressing, and case sensitivity
 
 ## ✨ Core Features
 
-- 🚀 **Fast & Lightweight**: Zero dependencies, ultra-low memory (~0.08MB initial, ~0.03MB per 1000 ops)
+- 🚀 **Fast & Lightweight**: Zero dependencies, ultra-low memory (0.10MB initial, 0.00004MB per 1000 ops), small footprint (~39.5KB compressed)
 - 📧 **93 Email Providers**: Gmail, Outlook, Yahoo, ProtonMail, iCloud, and many more
 - 🌐 **207 Domains Supported**: Comprehensive international coverage
 - 🌍 **Full IDN Support**: International domain names with RFC compliance and Punycode
@@ -36,7 +37,7 @@ A robust TypeScript library providing direct links to **93 email providers** (18
 - 🔄 **Email Alias Detection**: Normalize Gmail dots, plus addressing, and provider-specific aliases
 - 🛡️ **Fraud Prevention**: Detect duplicate accounts through email alias manipulation
 - 📦 **Batch Processing**: Efficiently process multiple emails with deduplication
-- 🧪 **Thoroughly Tested**: 424 tests with 93.16% code coverage
+- 🧪 **Thoroughly Tested**: 445 tests with 94.65% code coverage
 
 ## Installation
 
@@ -236,8 +237,6 @@ console.log(domain); // 'example.com'
 
 ## Performance and Detection System
 
-For detailed performance metrics and information about the detection system, refer to [Performance and Detection System](docs/PERFORMANCE.md).
-
 ### Development Mode Features
 
 When `NODE_ENV` is set to 'development', the library provides additional insights:
@@ -247,15 +246,6 @@ When `NODE_ENV` is set to 'development', the library provides additional insight
 // 🚀 Current memory usage: 0.08 MB
 ```
 
-### Memory Management
-
-The library implements careful memory management:
-- Initial load: ~0.08MB heap usage
-- Batch operations: ~0.03MB per 1000 operations
-- Maximum load: < 25MB even under heavy concurrent operations
-- Automatic garbage collection hints
-- Memory usage logging in development mode
-
 ### Performance Benchmarks
 
 Extensively optimized for both speed and memory efficiency:
@@ -267,10 +257,10 @@ Extensively optimized for both speed and memory efficiency:
 - Batch processing: 1000 operations in ~1.1ms
 - Email validation: <1ms for complex IDN domains
 
-**Memory Usage**:
-- Initial footprint: ~0.08MB
-- Per operation: ~0.03MB per 1000 lookups
-- Peak usage: <25MB under heavy load
+**Memory Management**:
+- Initial load: ~0.10MB heap usage
+- Batch operations: ~0.00004MB per 1000 operations
+- Maximum load: < 25MB under heavy concurrent operations
 - Cache efficiency: >99% hit rate
 - Garbage collection: Automatic optimization
 
@@ -282,15 +272,21 @@ Extensively optimized for both speed and memory efficiency:
 
 To run benchmarks:
 ```bash
-npm run benchmark # Basic benchmarks
-node --expose-gc benchmark/memory.ts # Detailed memory analysis
+# Memory usage benchmark
+npm run benchmark:memory
+
+# DNS performance benchmark
+npm run benchmark:dns
+
+# Both scripts are available in the scripts/ directory
+# and can be modified for custom performance testing
 ```
 
 ## Contributing
 
 We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on adding new email providers.
 
-**Quality Assurance**: This project maintains high standards with 424 comprehensive tests achieving 93.16% code coverage (96.46% function coverage).
+**Quality Assurance**: This project maintains high standards with 445 comprehensive tests achieving 94.65% code coverage (95.95% function coverage).
 **Security Note**: All new providers undergo security validation and must pass our allowlist verification.
 
 ## Security

package/dist/alias-detection.d.ts

@@ -3,6 +3,43 @@
  *
  * Clean, focused implementation with only essential functions.
  * Detects and normalizes email aliases across different providers.
+ *
+ * Alias Configuration Behavior:
+ * ---------------------------
+ * The module handles email aliases based on provider-specific configurations.
+ * Each provider can specify how to handle three types of email variations:
+ *
+ * 1. Case sensitivity ("case")
+ * 2. Plus addressing ("plus")
+ * 3. Dots in username ("dots")
+ *
+ * Important: For each of these properties, modifications are only applied if
+ * explicitly configured in the provider's settings:
+ *
+ * - If a property is defined (e.g., "case": {"ignore": true, "strip": true}),
+ *   the specified behavior is applied
+ *
+ * - If a property is missing from the provider's alias configuration,
+ *   the original value is preserved without modification
+ *
+ * Example:
+ * ```json
+ * {
+ *   "alias": {
+ *     "dots": { "ignore": false, "strip": false },
+ *     "plus": { "ignore": true, "strip": true }
+ *     // case is not defined, so case will be preserved
+ *   }
+ * }
+ * ```
+ *
+ * In this example:
+ * - Dots will be preserved (configured to not ignore/strip)
+ * - Plus addressing will be stripped (configured to ignore/strip)
+ * - Case will be preserved (not configured)
+ *
+ * Note: The domain part of email addresses is always converted to lowercase
+ * as per RFC 5321 standard, regardless of provider configuration.
  */
 export interface AliasDetectionResult {
     /** The normalized/canonical email address */
@@ -21,8 +58,26 @@ export interface AliasDetectionResult {
 /**
  * Detects and analyzes email aliases
  *
+ * This function processes email addresses according to provider-specific rules.
+ * Case is always lowercased in the canonical form for consistency and safety.
+ * It only applies additional modifications (plus, dots) that are explicitly
+ * defined in the provider's configuration.
+ *
  * @param email - Email address to analyze
  * @returns Detailed analysis of the email alias
+ *
+ * @example
+ * Provider with no case handling defined:
+ * ```typescript
+ * detectEmailAlias('User.Name@example.com')
+ * // Preserves case: User.Name@example.com
+ * ```
+ *
+ * Provider with case handling defined:
+ * ```typescript
+ * detectEmailAlias('User.Name@gmail.com')
+ * // Converts to lowercase: user.name@gmail.com
+ * ```
  */
 export declare function detectEmailAlias(email: string): AliasDetectionResult;
 /**

package/dist/alias-detection.js

@@ -4,6 +4,43 @@
  *
  * Clean, focused implementation with only essential functions.
  * Detects and normalizes email aliases across different providers.
+ *
+ * Alias Configuration Behavior:
+ * ---------------------------
+ * The module handles email aliases based on provider-specific configurations.
+ * Each provider can specify how to handle three types of email variations:
+ *
+ * 1. Case sensitivity ("case")
+ * 2. Plus addressing ("plus")
+ * 3. Dots in username ("dots")
+ *
+ * Important: For each of these properties, modifications are only applied if
+ * explicitly configured in the provider's settings:
+ *
+ * - If a property is defined (e.g., "case": {"ignore": true, "strip": true}),
+ *   the specified behavior is applied
+ *
+ * - If a property is missing from the provider's alias configuration,
+ *   the original value is preserved without modification
+ *
+ * Example:
+ * ```json
+ * {
+ *   "alias": {
+ *     "dots": { "ignore": false, "strip": false },
+ *     "plus": { "ignore": true, "strip": true }
+ *     // case is not defined, so case will be preserved
+ *   }
+ * }
+ * ```
+ *
+ * In this example:
+ * - Dots will be preserved (configured to not ignore/strip)
+ * - Plus addressing will be stripped (configured to ignore/strip)
+ * - Case will be preserved (not configured)
+ *
+ * Note: The domain part of email addresses is always converted to lowercase
+ * as per RFC 5321 standard, regardless of provider configuration.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectEmailAlias = detectEmailAlias;
@@ -20,24 +57,44 @@ function isValidEmail(email) {
 /**
  * Detects and analyzes email aliases
  *
+ * This function processes email addresses according to provider-specific rules.
+ * Case is always lowercased in the canonical form for consistency and safety.
+ * It only applies additional modifications (plus, dots) that are explicitly
+ * defined in the provider's configuration.
+ *
  * @param email - Email address to analyze
  * @returns Detailed analysis of the email alias
+ *
+ * @example
+ * Provider with no case handling defined:
+ * ```typescript
+ * detectEmailAlias('User.Name@example.com')
+ * // Preserves case: User.Name@example.com
+ * ```
+ *
+ * Provider with case handling defined:
+ * ```typescript
+ * detectEmailAlias('User.Name@gmail.com')
+ * // Converts to lowercase: user.name@gmail.com
+ * ```
  */
 function detectEmailAlias(email) {
     if (!isValidEmail(email)) {
         throw new Error('Invalid email format');
     }
     const originalEmail = email.trim();
+    // Split normally, lowering case both for username and domain by default
     const emailParts = originalEmail.toLowerCase().split('@');
     const username = emailParts[0];
-    const domain = emailParts[1];
+    const domain = emailParts[1]; // domain is always case-insensitive per RFC 5321
     if (!username || !domain) {
         throw new Error('Invalid email format - missing username or domain');
     }
     const { domainMap } = (0, loader_1.loadProviders)();
     const provider = domainMap.get(domain);
     const result = {
-        canonical: originalEmail.toLowerCase(),
+        // Only lowercase domain part by default
+        canonical: `${username}@${domain}`,
         original: originalEmail,
         isAlias: false,
         aliasType: 'none'
@@ -50,13 +107,15 @@ function detectEmailAlias(email) {
     let isAlias = false;
     let aliasType = 'none';
     let aliasPart;
-    // Handle case sensitivity (all modern providers are case-insensitive)
+    // Canonical form is always lowercased to ensure consistent and
+    // reliable email handling across different providers.
     if (provider.alias?.case?.ignore) {
         if (provider.alias.case?.strip) {
             normalizedUsername = normalizedUsername.toLowerCase();
         }
     }
-    // Handle plus addressing (common for Gmail, Outlook, Yahoo, etc.)
+    // Handle plus addressing if defined in provider settings
+    // If plus handling is not defined, preserve plus addressing
     if (provider.alias?.plus?.ignore) {
         const plusIndex = username.indexOf('+');
         if (plusIndex !== -1) {
@@ -68,7 +127,8 @@ function detectEmailAlias(email) {
             }
         }
     }
-    // Handle dots (primarily for Gmail)
+    // Handle dots if defined in provider settings
+    // If dots handling is not defined, preserve dots
     if (provider.alias?.dots?.ignore) {
         const hasDots = username.includes('.');
         if (hasDots) {

package/dist/hash-verifier.js

@@ -27,9 +27,9 @@ const path_1 = require("path");
  */
 const KNOWN_GOOD_HASHES = {
     // SHA-256 hash of the legitimate emailproviders.json
-    'emailproviders.json': '288a17c8e186f9c16dca4c9d752ab8a55b9b1e240b991b490cb41c928b4366a6',
+    'emailproviders.json': '65c136a13cbcd31507241b7ddc8850f81b98196d2e57fcd9ce6060825a010cef',
     // You can add hashes for other critical files
-    'package.json': 'a1a44dfdda78bb08ac5d2cb489d9bf577b57006a9f9df7d2e7b9251060c4cf4c'
+    'package.json': '75ed1f7fb74a7be7002700358232660b0c2aa1da82499466d83b049687e74de9',
 };
 /**
  * Calculates SHA-256 hash of a file or string content

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikkelscheike/email-provider-links",
-  "version": "2.8.2",
-  "description": "TypeScript library for email provider detection with 93 providers (207 domains), concurrent DNS resolution, optimized performance, 91.75% test coverage, and enterprise security for login and password reset flows",
+  "version": "3.0.0",
+  "description": "TypeScript library for email provider detection with 93 providers (207 domains), concurrent DNS resolution, optimized performance, 94.65% test coverage, and enterprise security for login and password reset flows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -26,7 +26,8 @@
     "release:major": "tsx scripts/prepare-release.ts",
     "release:minor": "tsx scripts/prepare-release.ts",
     "release:patch": "tsx scripts/prepare-release.ts",
-    "benchmark": "tsx --expose-gc benchmark/memory.ts"
+    "benchmark:memory": "tsx --expose-gc scripts/benchmark-memory.ts",
+    "benchmark:dns": "tsx scripts/benchmark-concurrent-dns.ts"
   },
   "keywords": [
     "email",

package/providers/emailproviders.json

@@ -349,7 +349,7 @@
       "loginUrl": "https://www.hushmail.com/signin/"
     },
     {
-"id": "icloud",
+      "id": "icloud",
       "domains": [
         "icloud.com",
         "me.com",
@@ -484,7 +484,7 @@
       "loginUrl": "https://www.mail.bg"
     },
     {
-"id": "com",
+      "id": "com",
       "domains": [
         "mail.com"
       ],
@@ -937,7 +937,7 @@
       "loginUrl": "https://app.titan.email"
     },
     {
-"id": "tutano",
+      "id": "tutano",
       "domains": [
         "tutanota.com",
         "tutanota.de",
@@ -1058,7 +1058,7 @@
       }
     },
     {
-"id": "yandex",
+      "id": "yandex",
       "domains": [
         "yandex.ru",
         "yandex.com"
@@ -1106,7 +1106,7 @@
       }
     },
     {
-"id": "zohoeu",
+      "id": "zohoeu",
       "domains": [
         "zoho.eu"
       ],