awesome-phonenumber

What is awesome-phonenumber?

The awesome-phonenumber npm package is a comprehensive library for parsing, formatting, and validating phone numbers. It supports a wide range of international phone number formats and provides utilities for handling phone number data effectively.

What are awesome-phonenumber's main functionalities?

Parsing Phone Numbers

This feature allows you to parse a phone number from a string and create a PhoneNumber object. The example demonstrates how to parse a US phone number.

const PhoneNumber = require('awesome-phonenumber');
const pn = new PhoneNumber('[phone]');
console.log(pn.getNumber()); // Outputs: [phone]

Formatting Phone Numbers

This feature allows you to format phone numbers in different formats such as E.164, international, and national. The example shows how to format a US phone number in various formats.

const PhoneNumber = require('awesome-phonenumber');
const pn = new PhoneNumber('[phone]');
console.log(pn.getNumber('e164')); // Outputs: [phone]
console.log(pn.getNumber('international')); // Outputs: [phone]
console.log(pn.getNumber('national')); // Outputs: [phone]

Validating Phone Numbers

This feature allows you to validate whether a phone number is valid or not. The example demonstrates how to check the validity of a US phone number.

const PhoneNumber = require('awesome-phonenumber');
const pn = new PhoneNumber('[phone]');
console.log(pn.isValid()); // Outputs: true

Getting Region Code

This feature allows you to get the region code of a phone number. The example shows how to retrieve the region code for a US phone number.

const PhoneNumber = require('awesome-phonenumber');
const pn = new PhoneNumber('[phone]');
console.log(pn.getRegionCode()); // Outputs: US

Getting Country Code

This feature allows you to get the country code of a phone number. The example demonstrates how to retrieve the country code for a US phone number.

const PhoneNumber = require('awesome-phonenumber');
const pn = new PhoneNumber('[phone]');
console.log(pn.getCountryCode()); // Outputs: 1

Other packages similar to awesome-phonenumber

libphonenumber-js

libphonenumber-js is a simpler and smaller alternative to Google's libphonenumber library. It provides similar functionalities for parsing, formatting, and validating phone numbers. Compared to awesome-phonenumber, libphonenumber-js is more lightweight and may be preferable for projects where bundle size is a concern.

google-libphonenumber

google-libphonenumber is a comprehensive library developed by Google for parsing, formatting, and validating international phone numbers. It is the most feature-rich and widely used library for phone number handling. Compared to awesome-phonenumber, google-libphonenumber offers more extensive support and features but comes with a larger bundle size.

phone

The phone package is a simple library for parsing and formatting phone numbers. It is less feature-rich compared to awesome-phonenumber but provides basic functionalities for handling phone numbers. It is suitable for projects that require minimal phone number processing capabilities.

README

Awesome phonenumber parser

This library is a pre-compiled version of Google's libphonenumber, with a slightly simpler interface. It has a minimal footprint - is by far the smallest libphonenumber-based library available on npmjs, and has no dependencies.

Unlike libphonenumber, it includes a findNumbers( ) function to find phone numbers in text.

TypeScript typings are provided within the package.

Uses libphonenumber v8.13.47

Versions

• v3:
  • Changed API (although with backwards compatible ABI)
  • Added ESM export
• v4:
  • Changed API to be much cleaner
    • No constructor
    • No functions on returned object
    • No errors being thrown
  • Not backwards compatible, although like v3 except:
    • The second argument to parsePhoneNumber is an object
      • E.g. { regionCode: 'SE' } instead of a region code string
    • The return value is like toJSON( ) on v3
• v5:
  • Dropped Node 12 support
• v6:
  • Dropped Node 16 support
• v7:
  • Added findNumbers( ) feature, to find phone numbers in text
  • Added support for short numbers

Comparison with other libraries

Since this library is pre-compiled, it doesn't depend on the closure compiler, and needs not load it on start. This makes the library faster and saves you a lot of space. It also means this library is trivial to use in any webpack project (or using any other means to run in the browser).

Among all the popular phone number using Google's libphonenumber (or mimicing it), only this one, google-libphonenumber and libphonenumber-js have decent README's with examples. This may have changed since first doing these benchmarks.

A library should be quick to load (require()), quick to parse first time and all consecutive times. It shouldn't bloat your node_modules, and it should have a small memory footprint, if possible.

The following is the result of a test program which loads the library, then parses a phone number, and then once again. It's called 100 times for each library and the mean values are shown here. Parsing a phone number first time might be slower because of initially compiling/optimizing regular expressions and whatnot. Parsing a phone number a second time will show the speed of likely all future parsing within that process.

Action	awesome-phonenumber 2.56.0 (lib 8.12.29)	google-libphonenumber 3.2.22 (lib 8.12.27)	libphonenumber-js 1.9.23 (lib -)
Load library first time	11.0 ms ✅	29.67 ms	32.87 ms
Parse first phone number	4.3 ms	4.01 ms	3.43 ms ✅
⇒ Load + parse first number	15.3 ms ✅	33.68 ms	36.3 ms
Parse second phone number	0.78 ms ✅	0.97 ms	0.92 ms
Increased memory usage	5.12 M ✅	9.99 M	5.86 M
node_modules size	296 K ✅	600 K	7.6 M
node_modules files	8	7 ✅	653

Basic usage

import { parsePhoneNumber } from 'awesome-phonenumber'

const pn = parsePhoneNumber( '0707123456', { regionCode: 'SE' } );
// or on e164 format:
const pn = parsePhoneNumber( '[phone]' );

// pn is now the same as:
const pn = {
	valid: true,

	number: {
		input: '0707123456',
		e164: '[phone]',
		international: '[phone]',
		national: '070-712 34 56',
		rfc3966: 'tel:[phone]',
		significant: '707123456',
	},
	possibility: 'is-possible',
	regionCode: 'SE',
	possible: true,
	shortPossible: false,
	shortValid: false,
	canBeInternationallyDialled: true,
	type: 'mobile',
	countryCode: 46,
	typeIsMobile: true,
	typeIsFixedLine: false,
};

The return type is ParsedPhoneNumber which is either a ParsedPhoneNumberValid or a ParsedPhoneNumberInvalid. The valid property identifies whether the parsing was successful or not, hence which type is returned.

The format of a successful parsing is:

interface ParsedPhoneNumberValid {
	valid: true;

	number: {
		input: string;
		international: string;
		national: string;
		e164: string;
		rfc3966: string;
		significant: string;
	};
	possibility: PhoneNumberPossibility; // a string union, see below
	regionCode: string;
	possible: boolean;
	shortPossible: boolean;
	shortValid: boolean;
	canBeInternationallyDialled: boolean;
	type: PhoneNumberTypes; // a string union, see below
	countryCode: number;
	typeIsMobile: boolean;
	typeIsFixedLine: boolean;
}

If the number failed to be parsed, or there was another error, the return type is:

interface ParsedPhoneNumberInvalid {
	valid: false;

	possible: false;
	possibility: 'invalid';
	shortPossible: boolean;
	shortValid: boolean;
	error?: unknown;
};

Note that an incorrect (invalid) phone number can still be a valid short number for the given region.

API

import {
	parsePhoneNumber,
	findNumbers,
	getNumberFrom,
	getExample,
	getCountryCodeForRegionCode,
	getRegionCodeForCountryCode,
	getSupportedCallingCodes,
	getSupportedRegionCodes,
	getAsYouType,
} from 'awesome-phonenumber'

parsePhoneNumber

parsePhoneNumber( phoneNumber, { regionCode: string } ) parses a phone number as described above.

The first argument is the phone number to parse, on either national or international (e164, i.e. prefixed with a +) form. If national form, the second argument is required to contain a regionCode string property, e.g. 'SE' for Sweden, 'CH' for Switzerland, etc.

findNumbers

To find (extract) phone numbers in text, use findNumbers( ):

import { findNumbers } from 'awesome-phonenumber'

const text = 'My number is [phone], otherwise call [phone].';
const numbers = findNumbers( text );

The returned list of numbers is of the type PhoneNumberMatch such as:

interface PhoneNumberMatch
{
	text: string; // The raw string found
	phoneNumber: object; // Same as the result of parsePhoneNumber()
	start: number; // Start offset in the text
	end: number; // End offset in the text
}

A second options argument to findNumbers( text, options ) can be provided on the form:

interface FindNumbersOptions
{
	defaultRegionCode?: string;
	leniency?: FindNumbersLeniency;
	maxTries?: number;
}

where FindNumbersLeniency is an enum of 'valid' or 'possible'. The default is 'valid' meaning that only valid phone numbers are found. If this is set to 'possible' also possible (but invalid) phone numbers are found.

defaultRegionCode can be set (e.g. to 'SE' for Sweden), in which case phone numbers on national form (i.e. without + prefix) will be found, as long as they are from that region.

For really large texts, maxTries will set the maximum number of phone numbers to try to find (not necessary actually find).

getNumberFrom

import { parsePhoneNumber, getNumberFrom } from 'awesome-phonenumber'

const pn = parsePhoneNumber( '0707654321', { regionCode: 'SE' } );
if ( pn.valid ) {
	const fromJp = getNumberFrom( pn, 'JP' );
	// fromJp is the number to call from Japan:
	fromJp.number === "010 46 70 765 43 21";
}

The return value from getNumberFrom is a PhoneNumberFrom which is either a PhoneNumberFromValid or a PhoneNumberFromInvalid.

The PhoneNumberFromValid is defined as:

interface PhoneNumberFromValid
{
	valid: true;
	number: string;
}

The PhoneNumberFromInvalid is defined as:

interface PhoneNumberFromInvalid
{
	valid: false;
	error?: unknown;
}

getExample

Sometimes you want to display a formatted example phone number for a certain country (and maybe also a certain type of phone number). The getExample function is used for this.

import { getExample } from 'awesome-phonenumber'

getExample( regionCode[, phoneNumberType] ); // Parsed phone number

The phoneNumberType is any of the types defined above.

Example

import { getExample } from 'awesome-phonenumber'

// Get an example Swedish phone number
const example = getExample( 'SE' ); // A ParsedPhoneNumberValid
const exampleMobile = getExample( 'SE', 'mobile' ); // A ParsedPhoneNumberValid

example.number.e164;           // e.g. '[phone]'
exampleMobile.number.e164;     // e.g. '[phone]'
exampleMobile.number.national; // e.g. '070 123 45 67'

Country codes

There are conversion functions between the 2-character ISO 3166-1 region codes (e.g. 'SE' for Sweden) and the corresponding country calling codes.

import {
	getCountryCodeForRegionCode,
	getRegionCodeForCountryCode,
	getSupportedCallingCodes,
	getSupportedRegionCodes,
} from 'awesome-phonenumber'

getCountryCodeForRegionCode( regionCode );  // -> countryCode
getRegionCodeForCountryCode( countryCode ); // -> regionCode

Example

getCountryCodeForRegionCode( 'SE' ); // -> 46
getRegionCodeForCountryCode( 46 );   // -> 'SE'

Supported calling codes

getSupportedCallingCodes( ); // -> [ calling codes... ]

Supported region codes

getSupportedRegionCodes( ); // -> [ region codes... ]

API types

The API consists of the PhoneNumber class which sometimes uses enums. These are:

Phone number types

type PhoneNumberTypes =
	| 'fixed-line'
	| 'fixed-line-or-mobile'
	| 'mobile'
	| 'pager'
	| 'personal-number'
	| 'premium-rate'
	| 'shared-cost'
	| 'toll-free'
	| 'uan'
	| 'voip'
	| 'unknown'

Phone number possibilities

type PhoneNumberPossibility =
	| 'is-possible'
	| 'invalid-country-code'
	| 'too-long'
	| 'too-short'
	| 'unknown'

Phone number formats

'international'
'national'
'e164'
'rfc3966'
'significant'

As-you-type formatting

You can create an AsYouType class with getAsYouType() to format a phone number as it is being typed.

import { getAsYouType } from 'awesome-phonenumber'

const ayt = getAsYouType( 'SE' );

The returned class instance has the following methods

// Add a character to the end of the number
ayt.addChar( nextChar: string );

// Get the current formatted number
ayt.number( );

// Remove the last character
ayt.removeChar( );

// Replace the whole number with a new number (or an empty number if undefined)
ayt.reset( number?: string );

// Get a ParsedPhoneNumber object representing the current number
ayt.getPhoneNumber( );

All the functions above except getPhoneNumber( ) return the current formatted number as a string.

Example

import { getAsYouType } from 'awesome-phonenumber'

const ayt = getAsYouType( 'SE' );
ayt.addChar( '0' ); // -> '0'
ayt.addChar( '7' ); // -> '07'
ayt.addChar( '0' ); // -> '070'
ayt.addChar( '7' ); // -> '070 7'
ayt.addChar( '1' ); // -> '070 71'
ayt.addChar( '2' ); // -> '070 712'
ayt.addChar( '3' ); // -> '070 712 3'
ayt.addChar( '4' ); // -> '070 712 34'
ayt.addChar( '5' ); // -> '070 712 34 5'
ayt.addChar( '6' ); // -> '070 712 34 56'
ayt.removeChar( );  // -> '070 712 34 5'
ayt.addChar( '7' ); // -> '070 712 34 57'