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.
TypeScript typings are provided within the package.
Uses libphonenumber v8.12.47
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
var PhoneNumber = require( 'awesome-phonenumber' );
var pn = new PhoneNumber( '0707123456', 'SE' );
pn.isValid( );
pn.isMobile( );
pn.canBeInternationallyDialled( );
pn.getNumber( );
pn.getNumber( 'e164' );
pn.getNumber( 'international' );
pn.getNumber( 'national' );
pn.getNumber( 'rfc3966' );
pn.getNumber( 'significant' );
pn.getRegionCode( );
pn.getCountryCode( );
pn.toJSON( );
JSON.stringify( pn, null, 4 );
Detect country
When constructed with a phone number on e164
format (i.e. prefixed with a +
), awesome-phonenumber will auto-detect the country:
PhoneNumber( '+46707123456' ).getRegionCode( );
API types
The API consists of the PhoneNumber
class which sometimes uses enums. These are:
Phone number types
'fixed-line'
'fixed-line-or-mobile'
'mobile'
'pager'
'personal-number'
'premium-rate'
'shared-cost'
'toll-free'
'uan'
'voip'
'unknown'
Phone number possibilities
'is-possible'
'invalid-country-code'
'too-long'
'too-short'
'unknown'
Phone number formats
'international'
'national'
'e164'
'rfc3966'
'significant'
API functions
Library
var PhoneNumber = require( 'awesome-phonenumber' );
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.
PhoneNumber.getCountryCodeForRegionCode( regionCode );
PhoneNumber.getRegionCodeForCountryCode( countryCode );
Example
PhoneNumber.getCountryCodeForRegionCode( 'SE' );
PhoneNumber.getRegionCodeForCountryCode( 46 );
Supported calling codes
PhoneNumber.getSupportedCallingCodes( );
Supported region codes
PhoneNumber.getSupportedRegionCodes( );
Phone numbers
An instance of the PhoneNumber
class will be created even if PhoneNumber
is called as a function.
var pn = PhoneNumber( number, regionCode );
var pn = new PhoneNumber( number, regionCode );
PhoneNumber objects can also be created using the getExample( regionCode[, type ] )
function, see section Example phone numbers for country below.
pn.toJSON( );
pn.isValid( );
pn.isPossible( );
pn.getType( );
pn.isMobile( );
pn.isFixedLine( );
pn.getNumber( [ format ] );
pn.getNumberFrom( fromRegionCode );
Example
PhoneNumber( '0707123456', 'SE' ).getNumberFrom( 'JP' );
Example phone numbers for country
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.
PhoneNumber.getExample( regionCode[, phoneNumberType] );
The phoneNumberType
is any of the types defined above.
Example
PhoneNumber.getExample( 'SE' ).getNumber( );
PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( );
PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( 'national' );
As-you-type formatting
You can use an AsYouType
class to format a phone number as it is being typed. An instance of this class is retrieved by var ayt = PhoneNumber.getAsYouType( regionCode )
, and has the following methods:
ayt.addChar( nextChar );
ayt.number( );
ayt.removeChar( );
ayt.reset( [ number ] );
ayt.getPhoneNumber( );
All the functions above except getPhoneNumber( )
return the current formatted number (as a String of course, as it may include spaces and other characters).
Example
var ayt = PhoneNumber.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' );