# phone-number-formatter-corrector

> This library provides a simple and efficient way to format and correct phone numbers, ensuring they adhere to international standards. It is designed to be easy to use, with a focus on accuracy and reliability.

Latest version **1.0.14** (published 2023-11-03) · ISC license · 0 weekly downloads

## Install

```sh
npm install phone-number-formatter-corrector
pnpm add phone-number-formatter-corrector
yarn add phone-number-formatter-corrector
bun add phone-number-formatter-corrector
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.14 |
| Published | 2023-11-03 |
| First published | 2023-10-31 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 54.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Jessica Nono |
| Maintainers | jessicanono |
| Keywords | phone, formatter |

## Links

- npm: https://www.npmjs.com/package/phone-number-formatter-corrector
- Repository: https://github.com/jessicaNono/correcttel
- Homepage: https://github.com/jessicaNono/correcttel#readme
- Issues: https://github.com/jessicaNono/correcttel/issues
- npm.io page: https://npm.io/package/phone-number-formatter-corrector

## Dependencies (2)

- [node-cache](https://npm.io/package/node-cache.md) ^5.1.2
- [google-libphonenumber](https://npm.io/package/google-libphonenumber.md) ^3.2.33

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.14 (latest) — 2023-11-03
- 1.0.13 — 2023-11-03
- 1.0.12 — 2023-11-03
- 1.0.11 — 2023-11-03
- 1.0.10 — 2023-11-02
- 1.0.9 — 2023-11-02
- 1.0.8 — 2023-11-02
- 1.0.7 — 2023-11-02
- 1.0.6 — 2023-11-02
- 1.0.5 — 2023-11-02
- 1.0.4 — 2023-11-01
- 1.0.3 — 2023-10-31
- 1.0.2 — 2023-10-31
- 1.0.1 — 2023-10-31
- 1.0.0 — 2023-10-31

## README

# Phone Number Formatter and Corrector

A JavaScript library to automatically format and correct phone numbers for international dialing, with a focus on accuracy and ease of use.

## Features
- **Automatic Formatting**: Converts phone numbers into the E.164 standard format, making them ready for international calls.
- **Country Code Correction**: Adds the correct country code if missing or incorrect.
- **Mobile Operator Detection**: Identifies the mobile operator based on the phone number’s prefix.
- **Phone Number Length Validation**: Validates the length of a phone number to ensure it is correct for the specified country.
- **Phone Number Information Retrieval**: Retrieves comprehensive information about a phone number, including formatting, country code, operator, and length validation.
- **Caching**: Utilizes caching to store previously formatted and corrected phone numbers for quicker access in future requests.
- **Error Handling**: Provides clear error messages for invalid or incorrectly formatted phone numbers.

## Installation
Install the package using npm:

```sh
npm install phone-number-formatter-corrector
```

## Usage

```javascript
const { formatPhoneNumber, getMobileOperator, getPhoneNumberInfo, isNumberValidForRegion } = require('./index');

const phoneNumber = '17645685126';
const code = 'DE';
//TODO: we might move this list to a test-config file and import 
// if it becomes to long.
// To add more validation, please add an object which has a countryCode key and provide
// the list of good and bad numbers. If tests is failing for you, please create an issue 
// in github and we will track it.
const testPhoneNumberList = [
    {
        'countryCode': 'CM',
        'numbers': ['6960923457683', '696092445', '696092545', '677123456'],
        'badNumbers': ['6960923450', '6960924450', '6960925450', '6771234560']
    }
]
const formattedNumber = formatPhoneNumber(phoneNumber, code);

const operator = getMobileOperator(phoneNumber, code);

const phoneNumberInfo = getPhoneNumberInfo(phoneNumber, code);

console.log(`Original Number: ${phoneNumber}`);
console.log(`Formatted Number: ${formattedNumber}`);
console.log(`Mobile Operator: ${operator}`);
console.log(`Phone Number Info: ${JSON.stringify(phoneNumberInfo)}`);
console.assert(phoneNumberInfo.formattedNumber == formattedNumber);
console.assert(phoneNumberInfo.countryCode == code);
console.assert(phoneNumberInfo.operator == operator);



testPhoneNumberList.forEach(function (obj) {
    obj.numbers.forEach(e => console.assert(isNumberValidForRegion(e, obj.countryCode), `${e}(${obj.countryCode}) is expected to be correct, but failed.`));
});

testPhoneNumberList.forEach(function (obj) {
    obj.badNumbers.forEach(e => console.assert(!isNumberValidForRegion(e, obj.countryCode), `${e}(${obj.countryCode}) is expected to fail.`));
});

// here our tests have passed. We just dummy log the phone number info to operators
// this just shows the importance of the isValid attribut on the phone number info object.
testPhoneNumberList.forEach(function (obj) {
    obj.numbers.forEach(e => console.log(`${JSON.stringify(getPhoneNumberInfo(e, obj.countryCode))}`));
});

// We see here that we could process a number, but this number is not valid.
console.log("");
testPhoneNumberList.forEach(function (obj) {
    obj.badNumbers.forEach(e => console.log(`${JSON.stringify(getPhoneNumberInfo(e, obj.countryCode))}`));
});
```

### API

#### `formatPhoneNumber(number, countryCode)`
- `number` (String): The phone number to be formatted.
- `countryCode` (String): The country code to be used if the phone number is not in international format.

#### `getMobileOperator(number, countryCode)`
- `number` (String): The phone number for which the mobile operator will be determined.
- `countryCode` (String): The country code for the provided phone number.

#### `getPhoneNumberInfo(number, countryCode)`
- `number` (String): The phone number to retrieve information for.
- `countryCode` (String): The country code for the provided phone number.
- Returns an object with the phone number information, including the formatted number, country code, mobile operator, and length validation.

#### `isPhoneNumberLengthCorrect(number, countryCode)`
- `number` (String): The phone number to validate the length for.
- `countryCode` (String): The country code for the provided phone number.
- Returns an object with the validation result code and message. A result code of `0` indicates the length is correct, `-1` indicates incorrect length, and `-2` indicates no fixed length was found for the country.

## Technologies Used
- **google-libphonenumber**: For parsing, formatting, and validating international phone numbers.
- **node-cache**: For caching previously formatted and corrected phone numbers.

## Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request.

## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
```

---
_Source: https://npm.io/package/phone-number-formatter-corrector · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._