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:
- v6:
- 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' } );
const pn = parsePhoneNumber( '+46707123456' );
const pn = {
valid: true,
number: {
input: '0707123456',
e164: '+46707123456',
international: '+46 70 712 34 56',
national: '070-712 34 56',
rfc3966: 'tel:+46-70-712-34-56',
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;
regionCode: string;
possible: boolean;
shortPossible: boolean;
shortValid: boolean;
canBeInternationallyDialled: boolean;
type: PhoneNumberTypes;
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 +46 707 123 456, otherwise call +33777777777.';
const numbers = findNumbers( text );
The returned list of numbers is of the type PhoneNumberMatch
such as:
interface PhoneNumberMatch
{
text: string;
phoneNumber: object;
start: number;
end: number;
}
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.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] );
The phoneNumberType
is any of the types defined above.
Example
import { getExample } from 'awesome-phonenumber'
const example = getExample( 'SE' );
const exampleMobile = getExample( 'SE', 'mobile' );
example.number.e164;
exampleMobile.number.e164;
exampleMobile.number.national;
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 );
getRegionCodeForCountryCode( countryCode );
Example
getCountryCodeForRegionCode( 'SE' );
getRegionCodeForCountryCode( 46 );
Supported calling codes
getSupportedCallingCodes( );
Supported region codes
getSupportedRegionCodes( );
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
ayt.addChar( nextChar: string );
ayt.number( );
ayt.removeChar( );
ayt.reset( number?: string );
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' );
ayt.addChar( '7' );
ayt.addChar( '0' );
ayt.addChar( '7' );
ayt.addChar( '1' );
ayt.addChar( '2' );
ayt.addChar( '3' );
ayt.addChar( '4' );
ayt.addChar( '5' );
ayt.addChar( '6' );
ayt.removeChar( );
ayt.addChar( '7' );