• Stars
    star
    759
  • Rank 59,846 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 11 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

Phone · PRs Welcome FOSSA Status

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:

`(817) 569-8900` or
`817569-8900` or
`1(817) 569-8900` or
`+1(817) 569-8900` or ...

We always want:

+18175698900

Install

npm install phone

// or

yarn add phone

Usage

const {phone} = require('phone');

// or

import {phone} from 'phone';

1. Simple usage

phone('+852 6569-8900');
// { isValid: true, phoneNumber: '+85265698900',  countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }

2. With Country

phone('+1(817) 569-8900', {country: ''}); 
// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1'}

phone('(817) 569-8900', {country: 'USA'});
// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1'}

phone('(817) 569-8900', {country: 'HKG'});
// { isValid: false }
// not a valid HKG mobile phone number

phone('+1(817) 569-8900', {country: 'HKG'});
// { isValid: false }
// not a valid HKG mobile phone number

phone('6123-6123', {country: 'HKG'});
// { isValid: true, phoneNumber: '+85261236123', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }

3. Without country code and no phone prefix

If both country code and country phone prefix are not provided, the phone number will be treated as USA or Canada by default.

phone('(817) 569-8900');
// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1' }

phone('(817) 569-8900', {country: ''});
// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1' }

phone('780-569-8900', {country: null});
// { isValid: true, phoneNumber: '+17805698900', countryIso2: 'CA', countryIso3: 'CAN', countryCode: '+1' }
// 780 is a Canada phone prefix

phone('6123-6123', {country: null});
// { isValid: false }
// as default country is USA / CAN and the phone number does not fit such countries' rules

4. With country code / phone prefix, but no + sign

Even you input a valid phone number with a valid prefix, if there is no plus sign, it will not work as expected:

phone('85291234567');
// or
phone('85291234567', {country: null});

// { isValid: false }

852 is a valid Hong Kong phone prefix, and 91234567 is a valid Hong Kong mobile phone number. However, there is no plus sign provided, the module will assume the phone number is a USA or Canada phone number, hence no result will be found.

If you know you have provided country phone prefix, make sure you also provide a plus sign:

phone('+85291234567');
// or
phone('+85291234567', {country: null});

// { isValid: true, phoneNumber: '+85291234567', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }

or, if you know the country, and only want to reformat the phone number to E.164 format:

phone('91234567',  {country: 'HKG'})
// { isValid: true, phoneNumber: '+85291234567', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }

5. Skipping phone number initial digit checking

If you want to skip phone number initial digit checking, set validateMobilePrefix to false:

phone('+(852) 2356-4902');
// { isValid: false }
// '2' is a Hong Kong landline phone number prefix, not a valid mobile phone number prefix

phone('+(852) 2356-4902', {validateMobilePrefix: true});
// { isValid: false }
// same as above, default value of validateMobilePrefix = true

phone('+(852) 2356-4902', {validateMobilePrefix: false});
// { isValid: true, phoneNumber: '+85223564902', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }
// skipping mobile prefix checking

With validateMobilePrefix set to false, the initial digit checking logic will be disabled completely, even you enter a phone number start with a non-exist digit:

phone('+(852) 0356-4902', {validateMobilePrefix: false});
// { isValid: true, phoneNumber: '+85203564902', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }
// even the phone number start with `0` is not a valid landline phone number

Note that the module does not have the capability to determine if the prefix is a valid landline prefix number.

6. Trunk Code Detection Logic

For some phone numbers, such as this sample UK phone number:

+44 07911 123456

There is a trunk code 0 after the country code +44 so that it is unable to match any correct country.

Hence the module will try to remove 1 digit after the country code,

and try to detect:

+44 7911 123456

and it would become a valid UK phone number now.

phone('+4407911 123456')
// { isValid: true, phoneNumber: '+447911123456', countryIso2: 'GB', countryIso3: 'GBR', countryCode: '+44' }

If you want to disable this behavior, please set strictDetection to true:

phone('+4407911 123456', {strictDetection: true})
// { isValid: false }

API

const {phone} = require('phone');

// or

import {phone} from 'phone';

phone(phoneNumber: string, { country, validateMobilePrefix, strictDetection }?: {
    country?: string;
    validateMobilePrefix?: boolean;
    strictDetection?: boolean;
})

Input

Parameter Type Required Default Description
phoneNumber String Yes - The phone number text you want to process
country String No null Provided country code in iso-3166 alpha 2 or 3 format
validateMobilePrefix Boolean No true Set to false if you want to skip phone number initial digit checking
strictDetection Boolean No false Set to true if you want to disable trunk code detection logic.

Returns

type PhoneResult = PhoneInvalidResult | PhoneValidResult;

interface PhoneValidResult {
	isValid: true;
	phoneNumber: string;
	countryIso2: string;
	countryIso3: string;
	countryCode: string;
}

interface PhoneInvalidResult {
	isValid: false;
	phoneNumber: null;
	countryIso2: null;
	countryIso3: null;
	countryCode: null;
}
Parameter Type Description
isValid Boolean To indicate if the result valid
phoneNumber String or null Normalized phone number in E.164 format
countryIso2 String or null Detected phone number country code in iso-3166 alpha 2 format
countryIso3 String or null Detected phone number country code in iso-3166 alpha 3 format
countryCode String or null Detected phone number country calling code with + sign

Test

yarn test

Interactive Web Example

yarn start:example

or

yarn dev

And then visit http://localhost:8080

Build

yarn build

FAQ

  1. Does phone do any logical validation?

    Yes. If you provide country, and the phone number does not start with + sign,

    the module will validate phone_number_lengths and mobile_begin_with

  2. Why is phone returning an invalid result for a valid phone number?

    By default, the function will validate a mobile phone number only, to validate a landline phone number, please set validateMobilePrefix to false.

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

  3. Why is phone returning an object with isValid = false instead of returning a null directly?

    It reserves the flexibility to extend the response interface for invalid result in future.

Migrate from v2

The interface of v3 has been changed for better usability, maintainability and flexibility, this shows all the changes from v2:

Function Interface

Version Interface
v2 phone(phoneNumber, country, allowLandline)
v3 phone(phoneNumber,{country: String, validateMobilePrefix: Boolean, strictDetection: Boolean})

Function Response

Version Result Interface
v2 - [phoneNumber, country]
v3 Valid {isValid: true, phoneNumber: string, countryIso2: string, countryIso3: string, countryCode: string}
v3 Invalid {isValid: false, phoneNumber: null, countryIso2: null, countryIso3: null, countryCode: null}

allowLandline vs validateMobilePrefix

allowLandline in v2 is essentially equals to validateMobilePrefix in v3, however, the value is opposite.

Because allowLandline = true in v2 means "Skip the mobile phone number prefix validation", and there is NO capability to verify if the input phone number is a valid landline phone number.

To avoid the misleading information, the parameter name has been changed to validateMobilePrefix, and the input value is opposite, while validateMobilePrefix = false means "Skip the mobile phone number prefix validation".

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.

The library supports mobile phone number format only. We are unable to provide landline phone number support as we do not have landline phone number format data, hence we do not accept PRs for landline phone numbers.

License

This project is licensed under the MIT license.

FOSSA Status

More Repositories

1

email-verifier

✅ A Go library for email verification without sending any emails.
Go
928
star
2

SaaS

List of SaaS that we are using
123
star
3

aftership-sdk-php

The PHP SDK of AfterShip API
PHP
64
star
4

aftership-sdk-nodejs

The node.js SDK of AfterShip API
JavaScript
61
star
5

aftership-sdk-python

The python SDK of AfterShip API
Python
48
star
6

clickhouse-sql-parser

ClickHouse SQL Parser writing in Go
Go
43
star
7

challenge

Different challenges, try them all if you like!
40
star
8

eslint-config-aftership

The coding guideline for AfterShip's node.js projects
JavaScript
38
star
9

aftership-sdk-ruby

The ruby gem SDK of AfterShip API
Ruby
32
star
10

aftership-apps-woocommerce

Add tracking number and carrier name, insert Track Button to order history page, and auto import tracking numbers from WooCommerce.
PHP
20
star
11

company-intro

We like to show case our engineering culture, from hiring to PR marketing.
JavaScript
19
star
12

deprecated-koa-newrelic

Koa middleware to allow Newrelic monitor Koa applications like Express
JavaScript
18
star
13

swagger-ajv

Old name: koa-swagger-ajv
JavaScript
16
star
14

aftership-sdk-net

The .NET SDK of AfterShip API
C#
13
star
15

aftership-sdk-java

The Java SDK of AfterShip API
Java
13
star
16

deprecated-apps-spree

Spree Extension for AfterShip
Ruby
13
star
17

bsw

JavaScript
11
star
18

aftership-sdk-go

Golang SDK for Aftership API
Go
10
star
19

rate-limiter

Redis rate limiter for Node.js
JavaScript
10
star
20

apps-opencart

PHP
10
star
21

aftership-sdk-android

The Android SDK of AfterShip API
Java
7
star
22

bigquery-streamer

JavaScript
7
star
23

demo-k8s-nodejs

JavaScript
6
star
24

deprecated-demo-cloudflare-workers

5
star
25

aftership-apps-prestashop

Auto import tracking numbers and order info from PrestaShop store every 3 hours.
PHP
4
star
26

deprecated-newrelic.aftershipdemo.com

This is demo site for NewRelic APM testing event on 2019-02-23
JavaScript
4
star
27

deprecated-demo-beanstalkd

Demo Beanstalkd
JavaScript
3
star
28

deprecated-demo-newrelic

JavaScript
2
star
29

deprecated-spot-cluster

JavaScript
2
star
30

deprecated-demo_streamer2bigquery

The demo streaming data from redis to bigquery
JavaScript
2
star
31

demo-bdd-test-workshop

A workshop for bdd test coding by Nodejs
JavaScript
1
star
32

node-tmfy

JavaScript
1
star
33

ga.aftershipdemo.com

This is demo site for GA AB Testing event on 2018-01-19
HTML
1
star
34

techblog.aftership.com

HTML
1
star