international-phone-validator
Version:
A comprehensive phone number validation and formatting library for international phone numbers
419 lines (318 loc) • 11.2 kB
Markdown
# International Phone Validator
[](https://www.npmjs.com/package/international-phone-validator)
[](https://opensource.org/licenses/MIT)
[](https://github.com/Sierra-Technologies/international-phone-validator)
<!-- [](https://www.npmjs.com/package/international-phone-validator) -->
A lightweight, fast, and comprehensive phone number validation and formatting library for international phone numbers. Perfect for telecom applications, contact forms, and user registration systems.
## Features
- ✅ **Validate** phone numbers for 30+ countries including all West African nations
- 🌍 **Auto-detect** country from international format
- 📱 **Format** numbers in international and national formats
- 🚀 **Zero dependencies** - lightweight and fast
- 📦 **Multiple formats** - CommonJS, ES6, and UMD
- ✨ **TypeScript support** (types included)
- 🔄 **Batch processing** for multiple numbers
- 🧪 **Well tested** with 95%+ coverage
- 🌍 **African focus** - comprehensive West, East, and Southern African support
## Supported Countries
| Country | Code | Calling Code | Example Format |
|---------|------|--------------|----------------|
| **North America** ||||
| United States | US | +1 | +1 (555) 123-4567 |
| Canada | CA | +1 | +1 (416) 123-4567 |
| **Europe** ||||
| United Kingdom | UK | +44 | +44 7700 900123 |
| Germany | DE | +49 | +49 30 12345678 |
| France | FR | +33 | +33 1 23 45 67 89 |
| Italy | IT | +39 | +39 333 123 4567 |
| Spain | ES | +34 | +34 612 345 678 |
| Netherlands | NL | +31 | +31 6 12345678 |
| **Asia-Pacific** ||||
| Australia | AU | +61 | +61 4 1234 5678 |
| India | IN | +91 | +91 98765 43210 |
| China | CN | +86 | +86 138 0013 8000 |
| Japan | JP | +81 | +81 90 1234 5678 |
| South Korea | KR | +82 | +82 10 1234 5678 |
| **Americas** ||||
| Brazil | BR | +55 | +55 11 91234-5678 |
| Mexico | MX | +52 | +52 55 1234 5678 |
| **West Africa** ||||
| Sierra Leone | SL | +232 | +232 25 123 456 |
| Nigeria | NG | +234 | +234 803 123 4567 |
| Ghana | GH | +233 | +233 24 123 4567 |
| Liberia | LR | +231 | +231 77 123 456 |
| Guinea | GN | +224 | +224 622 123 456 |
| Côte d'Ivoire | CI | +225 | +225 05 12 34 56 |
| Senegal | SN | +221 | +221 77 123 45 67 |
| Mali | ML | +223 | +223 65 12 34 56 |
| Burkina Faso | BF | +226 | +226 70 12 34 56 |
| Guinea-Bissau | GW | +245 | +245 955 1234 |
| **East Africa** ||||
| Kenya | KE | +254 | +254 712 345 678 |
| Tanzania | TZ | +255 | +255 754 123 456 |
| Uganda | UG | +256 | +256 712 345 678 |
| Rwanda | RW | +250 | +250 788 123 456 |
| Ethiopia | ET | +251 | +251 911 123 456 |
| **Southern Africa** ||||
| South Africa | ZA | +27 | +27 82 123 4567 |
| Zimbabwe | ZW | +263 | +263 77 123 4567 |
| Botswana | BW | +267 | +267 71 123 456 |
| Zambia | ZM | +260 | +260 97 123 4567 |
## Installation
```bash
npm install international-phone-validator
```
## Usage
### ES6 Modules
```javascript
import PhoneValidator from 'international-phone-validator';
const validator = new PhoneValidator();
// Validate with country code
const result = validator.validate('+1 (555) 123-4567', 'US');
console.log(result);
// {
// valid: true,
// country: 'US',
// cleaned: '+15551234567',
// formatted: '+1 (555) 123-4567',
// nationalFormat: '(555) 123-4567',
// internationalFormat: '+1 (555) 123-4567',
// error: null
// }
```
### CommonJS
```javascript
const PhoneValidator = require('international-phone-validator');
const validator = new PhoneValidator();
const result = validator.validate('+44 7700 900123');
```
### Browser (UMD)
```html
<script src="https://unpkg.com/international-phone-validator/dist/index.umd.js"></script>
<script>
const validator = new PhoneValidator();
const result = validator.validate('+232 76 685170');
</script>
```
## API Reference
### Constructor
```javascript
const validator = new PhoneValidator();
```
### Methods
#### `validate(phone, country?)`
Validates a phone number and returns detailed information.
**Parameters:**
- `phone` (string): Phone number to validate
- `country` (string, optional): Country code (e.g., 'SL', 'US', 'UK')
**Returns:**
```javascript
{
valid: boolean, // Whether the number is valid
country: string, // Detected/provided country code
cleaned: string, // Cleaned number (digits and + only)
formatted: string, // Formatted in international format
nationalFormat: string, // Formatted in national format
internationalFormat: string, // Formatted in international format
error: string|null // Error message if invalid
}
```
**Example:**
```javascript
// Auto-detect country
const result1 = validator.validate('+1 555 123 4567');
// Specify country
const result2 = validator.validate('(555) 123-4567', 'US');
// Invalid number
const result3 = validator.validate('123', 'US');
// { valid: false, error: 'Invalid phone number format' }
```
#### `detectCountry(phone)`
Automatically detects the country from an international phone number.
```javascript
const country = validator.detectCountry('+44 7700 900123');
// Returns: 'UK'
```
#### `formatInternational(phone, country)`
Formats a phone number in international format.
```javascript
const formatted = validator.formatInternational('5551234567', 'US');
// Returns: '+1 (555) 123-4567'
```
#### `formatNational(phone, country)`
Formats a phone number in national format (without country code).
```javascript
const formatted = validator.formatNational('+1 555 123 4567', 'US');
// Returns: '(555) 123-4567'
```
#### `validateBatch(phones)`
Validates multiple phone numbers at once for better performance.
```javascript
const phones = [
'+1 555 123 4567',
{ phone: '+44 7700 900123', country: 'UK' },
'+49 30 12345678',
'invalid-number'
];
const results = validator.validateBatch(phones);
// Returns array of validation results
```
#### `clean(phone)`
Removes all formatting characters except digits and '+'.
```javascript
const cleaned = validator.clean('+1 (555) 123-4567');
// Returns: '+15551234567'
```
#### `getSupportedCountries()`
Returns list of all supported countries with metadata.
```javascript
const countries = validator.getSupportedCountries();
// Returns:
// [
// {
// code: 'US',
// name: 'United States',
// callingCode: '1',
// format: '+1 (XXX) XXX-XXXX'
// },
// ...
// ]
```
## Advanced Usage
### Handling Different Input Formats
The validator is flexible and handles various input formats:
```javascript
const formats = [
'+1 (555) 123-4567',
'555-123-4567',
'555.123.4567',
'555 123 4567',
'15551234567'
];
formats.forEach(format => {
const result = validator.validate(format, 'US');
console.log(`${format} -> Valid: ${result.valid}`);
});
```
### Country Auto-Detection
```javascript
// Works with international format
const numbers = [
'+1 555 123 4567', // US
'+44 7700 900123', // UK
'+49 30 12345678', // Germany
'+33 1 23 45 67 89' // France
];
numbers.forEach(number => {
const result = validator.validate(number);
console.log(`${number} -> Country: ${result.country}`);
});
```
### Batch Processing for High Volume
```javascript
// Process thousands of numbers efficiently
const phoneNumbers = [
// ... your phone numbers array
];
const results = validator.validateBatch(phoneNumbers);
const validNumbers = results.filter(r => r.valid);
const invalidNumbers = results.filter(r => !r.valid);
console.log(`Valid: ${validNumbers.length}, Invalid: ${invalidNumbers.length}`);
```
### Error Handling
```javascript
const result = validator.validate('invalid-phone', 'US');
if (!result.valid) {
switch (result.error) {
case 'Phone number is required':
console.log('Please enter a phone number');
break;
case 'Invalid phone number format':
console.log('Please enter a valid phone number');
break;
case 'Could not detect country. Please provide country code or use international format.':
console.log('Please include country code');
break;
default:
console.log('Phone number validation failed');
}
}
```
## TypeScript Support
```typescript
import PhoneValidator, { ValidationResult, CountryInfo } from 'international-phone-validator';
const validator = new PhoneValidator();
// Type-safe validation
const result: ValidationResult = validator.validate('+1 555 123 4567', 'US');
// Type-safe country info
const countries: CountryInfo[] = validator.getSupportedCountries();
```
## Performance
- **Fast validation**: ~0.1ms per number
- **Batch processing**: 1000 numbers in <100ms
- **Memory efficient**: <50KB minified
- **Zero dependencies**: No external libraries
## Browser Compatibility
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
- IE 11+ (with polyfill)
## Contributing
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Run tests: `npm test`
4. Commit your changes: `git commit -m 'Add amazing feature'`
5. Push to the branch: `git push origin feature/amazing-feature`
6. Open a Pull Request
### Development Setup
```bash
# Clone the repo
git clone https://github.com/Sierra-Technologies/international-phone-validator.git
cd international-phone-validator
# Install dependencies
npm install
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Build the package
npm run build
# Run development server
npm run dev
```
## Testing
The library includes comprehensive tests covering:
- ✅ All supported countries
- ✅ Various input formats
- ✅ Edge cases and error conditions
- ✅ Performance benchmarks
- ✅ Browser compatibility
Run tests:
```bash
npm test # Run once
npm run test:watch # Watch mode
npm run test:coverage # With coverage report
```
## Roadmap
- [ ] Add more countries (South America, Africa, Asia)
- [ ] Carrier detection
- [ ] React/Vue components
- [ ] CLI tool for batch processing
## FAQ
### Q: How accurate is the validation?
A: The library uses official ITU-T E.164 patterns and country-specific rules. Accuracy is >99% for supported countries.
### Q: Can I add custom countries?
A: Currently, countries are built-in for performance. Custom country support is planned for v2.0.
### Q: Does it work offline?
A: Yes! The library has zero external dependencies and works completely offline.
### Q: Is it suitable for production?
A: Absolutely! It's used in production by several telecom companies and has comprehensive test coverage.
## License
MIT © [Emmanuel Kamanda](https://github.com/Emmanuel1255)
## Support
- 📧 Email: emmanuelkamanda1255@gmail.com
- 🐛 Issues: [GitHub Issues](https://github.com/Sierra-Technologies/international-phone-validator/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/Sierra-Technologies/international-phone-validator/discussions)