Package Exports

nodispose
nodispose/package.json

Readme

Nodispose

A fast and reliable disposable email address detector for Node.js applications. Protect your application from temporary and disposable email addresses with comprehensive domain detection and flexible configuration options.

✨ Features

🚀 Fast & Efficient - Optimized performance with intelligent caching
🔒 Reliable Detection - Comprehensive database of disposable email domains
📦 Zero Dependencies - Lightweight with no external runtime dependencies
🔧 TypeScript Support - Full TypeScript definitions included
🌐 Dual Module Support - Works with both CommonJS and ES modules
⚡ Race Condition Safe - Handles concurrent requests gracefully
🛡️ Error Handling - Robust error handling with custom error types
🎯 Flexible API - Multiple detection methods for different use cases

📦 Installation

npm install nodispose

yarn add nodispose

pnpm add nodispose

🚀 Quick Start

Basic Usage

const disposableEmailDetector = require('nodispose');

async function checkEmail() {
  // Detailed result with context
  const result = await disposableEmailDetector('test@10minutemail.com');
  console.log(result);
  // Output: { isDisposable: true, domain: '10minutemail.com' }

  // Simple boolean check
  const { isDisposableEmail } = require('nodispose');
  const isDisposable = await isDisposableEmail('user@gmail.com');
  console.log(isDisposable); // false
}

checkEmail();

ES Modules

import disposableEmailDetector, { isDisposableEmail } from 'nodispose';

const result = await disposableEmailDetector('temp@tempmail.org');
console.log(result.isDisposable); // true

const isDisposable = await isDisposableEmail('user@example.com');
console.log(isDisposable); // false (assuming example.com is not disposable)

TypeScript

import disposableEmailDetector, { 
  DetectionResult, 
  isDisposableEmail,
  InvalidEmailError 
} from 'nodispose';

async function validateEmail(email: string): Promise<DetectionResult> {
  try {
    const result = await disposableEmailDetector(email);
    return result;
  } catch (error) {
    if (error instanceof InvalidEmailError) {
      console.error('Invalid email format:', error.message);
    }
    throw error;
  }
}

📚 API Reference

`disposableEmailDetector(email: string): Promise<DetectionResult>`

Main detection function that returns detailed information about the email domain.

Parameters:

email (string): The email address to check

Returns: Promise<DetectionResult>

interface DetectionResult {
  isDisposable: boolean;  // Whether the domain is disposable
  domain: string;         // The extracted domain
  error?: string;         // Error message if detection failed
}

Example:

const result = await disposableEmailDetector('user@tempmail.org');
console.log(result);
// { isDisposable: true, domain: 'tempmail.org' }

`isDisposableEmail(email: string): Promise<boolean>`

Simplified function that returns only a boolean result.

Parameters:

email (string): The email address to check

Returns: Promise<boolean>

Example:

const isDisposable = await isDisposableEmail('test@10minutemail.com');
console.log(isDisposable); // true

Utility Functions

`clearCache(): void`

Clears the internal domain cache. Useful for testing or forcing a refresh of domain data.

import { clearCache } from 'nodispose';

clearCache(); // Forces reload of domain data on next detection

`getCachedDomains(): string[] | undefined`

Returns a copy of the currently cached domains for debugging purposes.

import { getCachedDomains } from 'nodispose';

const domains = getCachedDomains();
console.log(domains?.length); // Number of cached domains

🔧 Configuration

The library uses a local JSON file containing disposable email domains. The domains are loaded automatically and cached for optimal performance.

Domain Data Location

The library looks for domain data in the following location:

data/domains.json (relative to the package installation)

Custom Domain Lists

You can extend or modify the domain detection by updating the domains.json file in the package's data directory. The file should contain a JSON array of domain strings:

[
  "10minutemail.com",
  "tempmail.org",
  "guerrillamail.com",
  "mailinator.com"
]

🛠️ Error Handling

The library provides custom error types for better error handling:

`InvalidEmailError`

Thrown when an email address has an invalid format.

import { InvalidEmailError } from 'nodispose';

try {
  await disposableEmailDetector('invalid-email');
} catch (error) {
  if (error instanceof InvalidEmailError) {
    console.error('Invalid email format:', error.message);
  }
}

Error Scenarios

The library handles various error scenarios gracefully:

Invalid email format: Returns error in result object
Missing domain data: Throws appropriate error
File system errors: Propagates with context
JSON parsing errors: Provides clear error messages

📋 Examples

Basic Email Validation

const disposableEmailDetector = require('nodispose');

async function validateUserEmail(email) {
  const result = await disposableEmailDetector(email);
  
  if (result.error) {
    return { valid: false, reason: result.error };
  }
  
  if (result.isDisposable) {
    return { valid: false, reason: 'Disposable email addresses are not allowed' };
  }
  
  return { valid: true, domain: result.domain };
}

// Usage
validateUserEmail('user@10minutemail.com')
  .then(result => console.log(result));
// { valid: false, reason: 'Disposable email addresses are not allowed' }

Batch Processing

const { isDisposableEmail } = require('nodispose');

async function filterDisposableEmails(emails) {
  const results = await Promise.all(
    emails.map(async (email) => ({
      email,
      isDisposable: await isDisposableEmail(email)
    }))
  );
  
  return {
    legitimate: results.filter(r => !r.isDisposable).map(r => r.email),
    disposable: results.filter(r => r.isDisposable).map(r => r.email)
  };
}

// Usage
const emails = [
  'user@gmail.com',
  'test@10minutemail.com',
  'admin@company.com',
  'temp@tempmail.org'
];

filterDisposableEmails(emails)
  .then(result => console.log(result));

Express.js Middleware

const disposableEmailDetector = require('nodispose');

function validateEmailMiddleware(req, res, next) {
  const { email } = req.body;
  
  if (!email) {
    return res.status(400).json({ error: 'Email is required' });
  }
  
  disposableEmailDetector(email)
    .then(result => {
      if (result.error) {
        return res.status(400).json({ error: result.error });
      }
      
      if (result.isDisposable) {
        return res.status(400).json({ 
          error: 'Disposable email addresses are not allowed' 
        });
      }
      
      req.validatedEmail = {
        email: email,
        domain: result.domain
      };
      next();
    })
    .catch(error => {
      res.status(500).json({ error: 'Email validation failed' });
    });
}

// Usage in Express route
app.post('/register', validateEmailMiddleware, (req, res) => {
  // Email is validated and available in req.validatedEmail
  res.json({ message: 'Email is valid', email: req.validatedEmail });
});

Form Validation

const { isDisposableEmail } = require('nodispose');

class EmailValidator {
  static async validate(email) {
    const errors = [];
    
    // Basic format validation
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(email)) {
      errors.push('Invalid email format');
      return { valid: false, errors };
    }
    
    // Disposable email check
    try {
      const isDisposable = await isDisposableEmail(email);
      if (isDisposable) {
        errors.push('Disposable email addresses are not allowed');
      }
    } catch (error) {
      errors.push('Unable to validate email domain');
    }
    
    return {
      valid: errors.length === 0,
      errors
    };
  }
}

// Usage
EmailValidator.validate('user@tempmail.org')
  .then(result => {
    if (!result.valid) {
      console.log('Validation errors:', result.errors);
    }
  });

🧪 Testing

The library includes comprehensive tests. To run them:

npm test

For coverage report:

npm run test:coverage

For watch mode during development:

npm run test:watch

🏗️ Development

Building from Source

# Clone the repository
git clone https://github.com/aoamusat/nodispose.git
cd nodispose

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Project Structure

nodispose/
├── src/
│   └── index.ts          # Main source file
├── dist/                 # Built files (generated)
├── data/
│   └── domains.json      # Disposable domain list
├── examples/             # Usage examples
├── __tests__/            # Test files
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build - Build all formats (CommonJS, ES modules, TypeScript declarations)
npm run dev - Run in development mode
npm test - Run tests
npm run lint - Run ESLint
npm run format - Format code with Prettier

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Adding New Domains

To add new disposable email domains:

Update data/domains.json with the new domains
Ensure domains are in lowercase
Add tests for the new domains
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Thanks to all contributors who help maintain the disposable domain list
Inspired by the need for better email validation in modern web applications
Built with TypeScript and modern Node.js best practices

📞 Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Issues
📧 Email: hello@a4m.dev

🔗 Links

Made with ❤️ by Akeem Amusat