zim-phone-utils
Version:
A JavaScript utility library for validating, formatting, and detecting carriers for Zimbabwean phone numbers (mobile and landline)
351 lines (271 loc) • 8.26 kB
Markdown
# zim-phone-utils
A comprehensive JavaScript utility library for validating, formatting, and detecting carriers for Zimbabwean phone numbers (mobile and landline).
## Features
✅ **Mobile Number Support**
- Econet: 077, 078
- NetOne: 071
- Telecel: 073
✅ **Landline Number Support**
- Harare: 024
- Bulawayo: 029
- Gweru: 054
- Mutare: 020
- Masvingo: 039
- Kwekwe: 055
- Chinhoyi: 067
- Marondera: 065
- Bindura: 066
✅ **Multiple Format Support**
- Local: 0772123456, 0242123456
- International: +263772123456, +263242123456
- Without +: 263772123456, 263242123456
✅ **MVC Architecture**
- Clean separation of concerns
- Easy to maintain and extend
- Well-documented code
## Installation
```bash
npm install zim-phone-utils
```
## Quick Start
```javascript
const phoneUtils = require('zim-phone-utils');
// Validate a phone number
phoneUtils.isValid('0772123456'); // true
phoneUtils.isValid('0242123456'); // true
phoneUtils.isValid('invalid'); // false
// Format numbers
phoneUtils.formatLocal('+263772123456'); // '0772123456'
phoneUtils.formatInternational('0772123456'); // '+263772123456'
// Detect carrier (mobile only)
phoneUtils.detectCarrier('0772123456'); // 'Econet'
phoneUtils.detectCarrier('0712123456'); // 'NetOne'
phoneUtils.detectCarrier('0732123456'); // 'Telecel'
// Detect area (landline only)
phoneUtils.detectArea('0242123456'); // 'Harare'
phoneUtils.detectArea('0292123456'); // 'Bulawayo'
```
## API Reference
### Core Functions
#### `isValid(number)`
Validates if a phone number is a valid Zimbabwean number.
```javascript
phoneUtils.isValid('0772123456'); // true
phoneUtils.isValid('+263772123456'); // true
phoneUtils.isValid('0242123456'); // true
phoneUtils.isValid('invalid'); // false
```
#### `formatLocal(number)`
Formats a phone number to local Zimbabwean format.
```javascript
phoneUtils.formatLocal('+263772123456'); // '0772123456'
phoneUtils.formatLocal('263772123456'); // '0772123456'
phoneUtils.formatLocal('0772123456'); // '0772123456'
```
#### `formatInternational(number)`
Formats a phone number to international format.
```javascript
phoneUtils.formatInternational('0772123456'); // '+263772123456'
phoneUtils.formatInternational('263772123456'); // '+263772123456'
phoneUtils.formatInternational('+263772123456'); // '+263772123456'
```
#### `formatBoth(number)`
Returns both local and international formats.
```javascript
const result = phoneUtils.formatBoth('0772123456');
// {
// local: '0772123456',
// international: '+263772123456'
// }
```
### Detection Functions
#### `detectCarrier(number)`
Detects the mobile carrier for mobile numbers.
```javascript
phoneUtils.detectCarrier('0772123456'); // 'Econet'
phoneUtils.detectCarrier('0782123456'); // 'Econet'
phoneUtils.detectCarrier('0712123456'); // 'NetOne'
phoneUtils.detectCarrier('0732123456'); // 'Telecel'
phoneUtils.detectCarrier('0242123456'); // null (landline)
```
#### `detectArea(number)`
Detects the city/area for landline numbers.
```javascript
phoneUtils.detectArea('0242123456'); // 'Harare'
phoneUtils.detectArea('0292123456'); // 'Bulawayo'
phoneUtils.detectArea('0542123456'); // 'Gweru'
phoneUtils.detectArea('0772123456'); // null (mobile)
```
### Type Detection
#### `getNumberType(number)`
Returns the type of phone number.
```javascript
phoneUtils.getNumberType('0772123456'); // 'mobile'
phoneUtils.getNumberType('0242123456'); // 'landline'
phoneUtils.getNumberType('invalid'); // 'invalid'
```
#### `isMobile(number)`
Checks if a number is a mobile number.
```javascript
phoneUtils.isMobile('0772123456'); // true
phoneUtils.isMobile('0242123456'); // false
```
#### `isLandline(number)`
Checks if a number is a landline number.
```javascript
phoneUtils.isLandline('0242123456'); // true
phoneUtils.isLandline('0772123456'); // false
```
### Comprehensive Information
#### `getPhoneInfo(number)`
Returns comprehensive information about a phone number.
```javascript
const info = phoneUtils.getPhoneInfo('0772123456');
// {
// isValid: true,
// type: 'mobile',
// local: '0772123456',
// international: '+263772123456',
// carrier: 'Econet',
// area: null
// }
const landlineInfo = phoneUtils.getPhoneInfo('0242123456');
// {
// isValid: true,
// type: 'landline',
// local: '0242123456',
// international: '+263242123456',
// carrier: null,
// area: 'Harare'
// }
```
### Utility Functions
#### `getCarrierPrefixes()`
Returns all supported mobile carrier prefixes.
```javascript
const prefixes = phoneUtils.getCarrierPrefixes();
// {
// econet: ['077', '078'],
// netone: ['071'],
// telecel: ['073']
// }
```
#### `getAreaCodes()`
Returns all supported landline area codes.
```javascript
const areaCodes = phoneUtils.getAreaCodes();
// {
// harare: '024',
// bulawayo: '029',
// gweru: '054',
// mutare: '020',
// masvingo: '039',
// kwekwe: '055',
// chinhoyi: '067',
// marondera: '065',
// bindura: '066'
// }
```
## Usage Examples
### Form Validation
```javascript
const phoneUtils = require('zim-phone-utils');
function validatePhoneForm(phoneNumber) {
if (!phoneUtils.isValid(phoneNumber)) {
return { valid: false, error: 'Invalid phone number' };
}
const info = phoneUtils.getPhoneInfo(phoneNumber);
return {
valid: true,
formatted: info.local,
type: info.type,
carrier: info.carrier,
area: info.area
};
}
// Usage
const result = validatePhoneForm('077 212 3456');
console.log(result);
// {
// valid: true,
// formatted: '0772123456',
// type: 'mobile',
// carrier: 'Econet',
// area: null
// }
```
### Database Normalization
```javascript
const phoneUtils = require('zim-phone-utils');
function normalizePhoneForDatabase(phoneNumber) {
if (!phoneUtils.isValid(phoneNumber)) {
throw new Error('Invalid phone number');
}
return {
local: phoneUtils.formatLocal(phoneNumber),
international: phoneUtils.formatInternational(phoneNumber),
carrier: phoneUtils.detectCarrier(phoneNumber),
area: phoneUtils.detectArea(phoneNumber),
type: phoneUtils.getNumberType(phoneNumber)
};
}
```
### Contact List Processing
```javascript
const phoneUtils = require('zim-phone-utils');
function processContactList(contacts) {
return contacts.map(contact => {
const phoneInfo = phoneUtils.getPhoneInfo(contact.phone);
return {
...contact,
phone: phoneInfo.local,
phoneInternational: phoneInfo.international,
carrier: phoneInfo.carrier,
area: phoneInfo.area,
isValid: phoneInfo.isValid
};
}).filter(contact => contact.isValid);
}
```
## Supported Formats
### Mobile Numbers
- **Local**: `0772123456`, `0782123456`, `0712123456`, `0732123456`
- **International with +**: `+263772123456`, `+263782123456`, `+263712123456`, `+263732123456`
- **International without +**: `263772123456`, `263782123456`, `263712123456`, `263732123456`
### Landline Numbers
- **Local**: `0242123456`, `0292123456`, `0542123456`, etc.
- **International with +**: `+263242123456`, `+263292123456`, `+263542123456`, etc.
- **International without +**: `263242123456`, `263292123456`, `263542123456`, etc.
### Input Sanitization
The library automatically handles:
- Spaces: `077 212 3456`
- Dashes: `077-212-3456`
- Parentheses: `(077) 212-3456`
- Dots: `077.212.3456`
## Testing
Run the test suite:
```bash
npm test
```
Run tests with coverage:
```bash
npm run test:coverage
```
## Architecture
This library follows the MVC (Model-View-Controller) pattern:
- **Model** (`src/models/phoneModel.js`): Contains all business logic for phone number validation, formatting, and carrier detection
- **Controller** (`src/controllers/phoneController.js`): Handles input sanitization and provides clean public methods
- **View**: Not applicable in this context, but logging and result formatting are separated
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
For issues and questions, please open an issue on GitHub.
---
**Made with ❤️ for Zimbabwe @kudahndhlovu**