canxuemianbao / phone

With a given country and phone number, validate and format the MOBILE phone number to E.164 standard. The purpose for this is allow us to send SMS to mobile phone only.

Phone ·

What is phone?

phone is used to normalize mobile phone numbers into E.164 format.

A common problem is that users normally input phone numbers in this way:

`[phone]` or
`817569-8900` or
`1(817) 569-8900` or
`[phone]` or ...

We always want:

[phone]

Install

npm install phone

Usage

const phone = require('phone');

phone('[phone]'); // return ['[phone]', 'HKG']
phone('[phone]', ''); // return ['[phone]', 'USA']
phone('[phone]', 'USA'); // return ['[phone]', 'USA']
phone('[phone]', 'HKG'); // return []
phone('[phone]', 'HKG'); // return [], as it is not a valid HKG mobile phone number
phone('6123-6123', 'HKG'); // return ['[phone]', 'HKG']

If both country code and country phone prefix are not provided, will treat as USA or Canada by default

phone('[phone]'); // return ['[phone], 'USA']
phone('[phone]', ''); // return ['[phone], 'USA']
phone('[phone]', ''); // return ['[phone]', 'USA']
phone('780-569-8900', ''); // return ['[phone], 'CAN'], 780 is a Canada phone prefix
phone('6123-6123', ''); // return [], as default country is USA / CAN and it does not match any result

If you want to validate landline phone numbers, set allowLandline to true:

phone('+(852) 2356-4902', '', true);

API

const phone = require('phone');

phone(phone: String, [country: string, allowLandline: Boolean]): Array

Input

Parameter	Type	Required	Description
phone	String	Yes	The phone number text you want to process
country	String	No	Provided country code in iso-3166 alpha 2 or 3 format
allowLandLine	Boolean	No	Set to true if you want to use the module to validate landlane phone number

Returns

Array

Array index	Type	Description
0	String	Normalized phone number in E.164 format
1	String	Detected phone number country code in iso-3166 alpha 3 format

If the phone number cannot be reformatted due to any reason (e.g. unable to match any country), the result would be an empty array.

The function response is in Array format for some historical reason and expected to be updated to a proper object response in the next major version bump. (Will not change on version 2.x)

Test

npm test

Build

yarn build

Old browsers & browser support

We currently transpile script to work on target environments for which the browser's global usage is >1%, and Node.js 6.10+.

You can check browser usage statistics on the browserlist.

You may need polyfills for some older browsers; for more details, please read the example/README file.

FAQ

1. Does phone do any logical validation?

   Yes. If you provide the 2nd parameter (country), and the phone number does not start with + sign.

   phone will validate phone_number_lengths and mobile_begin_with

2. Why is phone returning null for a valid phone number?

   By default the function will validate a mobile phone number only, to validate a landline phone number, please set 3rd parameter allowLandline to true.

   If you find the result is still incorrect, please submit a ticket to improve our validation rules.

Help

We've tried to make sure that this package works for as many cases as possible, if you notice that we have an incorrect rule for a country or other case, please open an issue to let us know.

For creating new pull requests regarding add or modify phone number formats, please include the reference information such as PDFs, websites, etc. Thank you very much.

License

This project is licensed under the MIT license.