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

npm install zim-phone-utils

Quick Start

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.

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.

phoneUtils.formatLocal('+263772123456');  // '0772123456'
phoneUtils.formatLocal('263772123456');   // '0772123456'
phoneUtils.formatLocal('0772123456');     // '0772123456'

formatInternational(number)

Formats a phone number to international format.

phoneUtils.formatInternational('0772123456');    // '+263772123456'
phoneUtils.formatInternational('263772123456');  // '+263772123456'
phoneUtils.formatInternational('+263772123456'); // '+263772123456'

formatBoth(number)

Returns both local and international formats.

const result = phoneUtils.formatBoth('0772123456');
// {
//   local: '0772123456',
//   international: '+263772123456'
// }

Detection Functions

detectCarrier(number)

Detects the mobile carrier for mobile numbers.

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.

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.

phoneUtils.getNumberType('0772123456'); // 'mobile'
phoneUtils.getNumberType('0242123456'); // 'landline'
phoneUtils.getNumberType('invalid');    // 'invalid'

isMobile(number)

Checks if a number is a mobile number.

phoneUtils.isMobile('0772123456'); // true
phoneUtils.isMobile('0242123456'); // false

isLandline(number)

Checks if a number is a landline number.

phoneUtils.isLandline('0242123456'); // true
phoneUtils.isLandline('0772123456'); // false

Comprehensive Information

getPhoneInfo(number)

Returns comprehensive information about a phone number.

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.

const prefixes = phoneUtils.getCarrierPrefixes();
// {
//   econet: ['077', '078'],
//   netone: ['071'],
//   telecel: ['073']
// }

getAreaCodes()

Returns all supported landline area codes.

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

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

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

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:

npm test

Run tests with coverage:

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