3.3.0

[jesselpalmer]

🎯 Key Highlights

AI Debug Mode

• Enhanced debugging experience with structured JSON logging
• MCP-compatible format for AI-assisted debugging workflows
• Performance metrics and memory tracking for optimization
• Production-ready debug wrapper example

Comprehensive Examples Directory

• Six real-world examples covering all major use cases
• From basic validation to advanced TypeScript integration
• Bulk processing strategies and error handling patterns
• Full CommonJS and ESM compatibility examples

📝 What's Changed

Added

AI Debug Mode (debug: true option)

• Structured JSON logging with MCP-compatible format for AI tooling
• Performance timing for each validation phase (format check, MX lookup, disposable check)
• Memory usage tracking including heap, RSS, and external memory
• Detailed error logging with stack traces for debugging
• Production wrapper example showing how to collect and analyze debug data

Examples Directory

• examples/basic-validation.js - Getting started with simple email validation
• examples/typescript-usage.ts - Full TypeScript integration with all types
• examples/bulk-validation.js - Efficient strategies for validating email lists
• examples/error-handling.js - Comprehensive error handling with error codes
• examples/commonjs-usage.cjs - CommonJS compatibility and promise handling
• examples/debug-mode.js - AI Debug Mode usage and production patterns

💻 Quick Example

Debug Mode

import emailValidator from 'node-email-verifier';

// Enable debug mode for detailed logging
const result = await emailValidator('[email protected]', {
  debug: true,
  checkMx: true,
  checkDisposable: true,
  detailed: true,
});

// Debug logs are written to console as structured JSON
// Perfect for AI-assisted debugging and performance analysis

Production Debug Wrapper

import { EmailValidatorDebugger } from './examples/debug-mode.js';

const validator = new EmailValidatorDebugger();
const { result, debug } = await validator.validateWithDebug('[email protected]', {
  checkMx: true,
  checkDisposable: true,
});

console.log(`Validation took ${debug.totalDuration.toFixed(2)}ms`);
console.log(`Memory impact: ${(debug.memoryUsage.delta / 1024).toFixed(2)}KB`);

🚀 Performance Impact

The debug mode has minimal performance overhead when disabled. When enabled:

• Adds ~1-2ms per validation for logging
• Memory tracking uses native Node.js APIs
• All debug code is excluded when debug: false (default)

📦 Installation

npm install [email protected]

🔄 Migration Guide

No breaking changes! Simply update and optionally enable debug mode:

// Existing code continues to work
const isValid = await emailValidator('[email protected]');

// Opt-in to debug mode when needed
const isValid = await emailValidator('[email protected]', { debug: true });

📚 Documentation

• examples/debug-mode.js - Complete guide to using debug mode
• examples/ - Six comprehensive examples for different use cases
• README.md#api - Full API reference

Full Changelog: ## 🎯 Key Highlights

AI Debug Mode

• Enhanced debugging experience with structured JSON logging
• MCP-compatible format for AI-assisted debugging workflows
• Performance metrics and memory tracking for optimization
• Production-ready debug wrapper example

Comprehensive Examples Directory

• Six real-world examples covering all major use cases
• From basic validation to advanced TypeScript integration
• Bulk processing strategies and error handling patterns
• Full CommonJS and ESM compatibility examples

📝 What's Changed

Added

AI Debug Mode (debug: true option)

• Structured JSON logging with MCP-compatible format for AI tooling
• Performance timing for each validation phase (format check, MX lookup, disposable check)
• Memory usage tracking including heap, RSS, and external memory
• Detailed error logging with stack traces for debugging
• Production wrapper example showing how to collect and analyze debug data

Examples Directory

• examples/basic-validation.js - Getting started with simple email validation
• examples/typescript-usage.ts - Full TypeScript integration with all types
• examples/bulk-validation.js - Efficient strategies for validating email lists
• examples/error-handling.js - Comprehensive error handling with error codes
• examples/commonjs-usage.cjs - CommonJS compatibility and promise handling
• examples/debug-mode.js - AI Debug Mode usage and production patterns

💻 Quick Example

Debug Mode

import emailValidator from 'node-email-verifier';

// Enable debug mode for detailed logging
const result = await emailValidator('[email protected]', {
  debug: true,
  checkMx: true,
  checkDisposable: true,
  detailed: true,
});

// Debug logs are written to console as structured JSON
// Perfect for AI-assisted debugging and performance analysis

Production Debug Wrapper

import { EmailValidatorDebugger } from './examples/debug-mode.js';

const validator = new EmailValidatorDebugger();
const { result, debug } = await validator.validateWithDebug('[email protected]', {
  checkMx: true,
  checkDisposable: true,
});

console.log(`Validation took ${debug.totalDuration.toFixed(2)}ms`);
console.log(`Memory impact: ${(debug.memoryUsage.delta / 1024).toFixed(2)}KB`);

🚀 Performance Impact

The debug mode has minimal performance overhead when disabled. When enabled:

• Adds ~1-2ms per validation for logging
• Memory tracking uses native Node.js APIs
• All debug code is excluded when debug: false (default)

📦 Installation

npm install [email protected]

🔄 Migration Guide

No breaking changes! Simply update and optionally enable debug mode:

// Existing code continues to work
const isValid = await emailValidator('[email protected]');

// Opt-in to debug mode when needed
const isValid = await emailValidator('[email protected]', { debug: true });

📚 Documentation

• examples/debug-mode.js - Complete guide to using debug mode
• examples/ - Six comprehensive examples for different use cases
• README.md#api - Full API reference

Full Changelog: 3.2.0...3.3.0