1 | [![npm version][npm-image]][npm-url]
|
2 | [![downloads][downloads-image]][npm-url]
|
3 | [![build status][build-image]][build-url]
|
4 | [![Language grade: JavaScript][lgtm-image]][lgtm-url]
|
5 | [![Install size][packagephobia-image]][packagephobia-url]
|
6 |
|
7 |
|
8 | # Awesome phonenumber parser
|
9 |
|
10 | 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.
|
11 |
|
12 | TypeScript typings are provided within the package.
|
13 |
|
14 | Uses libphonenumber v8.12.31
|
15 |
|
16 | ## Comparison with other libraries
|
17 |
|
18 | 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).
|
19 |
|
20 | 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*.
|
21 |
|
22 | 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.
|
23 |
|
24 | 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.
|
25 |
|
26 | Action | awesome-phonenumber<br/>2.56.0<br/>(lib 8.12.29) | google-libphonenumber<br/>3.2.22<br/>(lib 8.12.27) | libphonenumber-js<br/>1.9.23<br/>(lib -)
|
27 | ------------------------- | ------------------- | --------------------- | ----------------
|
28 | Load library first time | 11.0 ms ✅ | 29.67 ms | 32.87 ms
|
29 | Parse first phone number | 4.3 ms | 4.01 ms | 3.43 ms ✅
|
30 | **⇒ Load + parse first number** | 15.3 ms ✅ | 33.68 ms | 36.3 ms
|
31 | Parse second phone number | 0.78 ms ✅ | 0.97 ms | 0.92 ms
|
32 | Increased memory usage | 5.12 M ✅ | 9.99 M | 5.86 M
|
33 | node_modules size | 296 K ✅ | 600 K | 7.6 M
|
34 | node_modules files | 8 | 7 ✅ | 653
|
35 |
|
36 |
|
37 | ## Basic usage
|
38 | ```js
|
39 | var PhoneNumber = require( 'awesome-phonenumber' );
|
40 |
|
41 | var pn = new PhoneNumber( '0707123456', 'SE' );
|
42 | pn.isValid( ); // -> true
|
43 | pn.isMobile( ); // -> true
|
44 | pn.canBeInternationallyDialled( ); // -> true
|
45 | pn.getNumber( ); // -> '+46707123456'
|
46 | pn.getNumber( 'e164' ); // -> '+46707123456' (default)
|
47 | pn.getNumber( 'international' ); // -> '+46 70 712 34 56'
|
48 | pn.getNumber( 'national' ); // -> '070-712 34 56'
|
49 | pn.getNumber( 'rfc3966' ); // -> 'tel:+46-70-712-34-56'
|
50 | pn.getNumber( 'significant' ); // -> '707123456'
|
51 | pn.getRegionCode( ); // -> 'SE'
|
52 | pn.getCountryCode( ); // -> 46
|
53 |
|
54 | pn.toJSON( ); // -> json blob, so that:
|
55 | JSON.stringify( pn, null, 4 ); // -> This:
|
56 | // {
|
57 | // "canBeInternationallyDialled": true,
|
58 | // "number": {
|
59 | // "input": "0707123456",
|
60 | // "international": "+46 70 712 34 56",
|
61 | // "national": "070-712 34 56",
|
62 | // "e164": "+46707123456",
|
63 | // "rfc3966": "tel:+46-70-712-34-56",
|
64 | // "significant": "707123456"
|
65 | // },
|
66 | // "regionCode": "SE",
|
67 | // "valid": true,
|
68 | // "possible": true,
|
69 | // "type": "mobile",
|
70 | // "possibility": "is-possible"
|
71 | // }
|
72 | ```
|
73 |
|
74 | ### Detect country
|
75 |
|
76 | When constructed with a phone number on `e164` format (i.e. prefixed with a `+`), awesome-phonenumber will auto-detect the country:
|
77 |
|
78 | ```js
|
79 | PhoneNumber( '+46707123456' ).getRegionCode( ); // -> 'SE'
|
80 | ```
|
81 |
|
82 | ## API types
|
83 |
|
84 | The API consists of the `PhoneNumber` class which sometimes uses *enums*. These are:
|
85 |
|
86 | ### <a name="phone-number-types"></a>Phone number types
|
87 | ```js
|
88 | 'fixed-line'
|
89 | 'fixed-line-or-mobile'
|
90 | 'mobile'
|
91 | 'pager'
|
92 | 'personal-number'
|
93 | 'premium-rate'
|
94 | 'shared-cost'
|
95 | 'toll-free'
|
96 | 'uan'
|
97 | 'voip'
|
98 | 'unknown'
|
99 | ```
|
100 |
|
101 | ### Phone number possibilities
|
102 |
|
103 | ```js
|
104 | 'is-possible'
|
105 | 'invalid-country-code'
|
106 | 'too-long'
|
107 | 'too-short'
|
108 | 'unknown'
|
109 | ```
|
110 |
|
111 | ### Phone number formats
|
112 |
|
113 | ```js
|
114 | 'international'
|
115 | 'national'
|
116 | 'e164'
|
117 | 'rfc3966'
|
118 | 'significant'
|
119 | ```
|
120 |
|
121 | ## API functions
|
122 |
|
123 | ### Library
|
124 | ```js
|
125 | var PhoneNumber = require( 'awesome-phonenumber' );
|
126 | ```
|
127 |
|
128 | ### Country codes
|
129 |
|
130 | There are conversion functions between the 2-character ISO 3166-1 region codes (e.g. 'SE' for Sweden) and the corresponding country calling codes.
|
131 |
|
132 | ```js
|
133 | PhoneNumber.getCountryCodeForRegionCode( regionCode ); // -> countryCode
|
134 | PhoneNumber.getRegionCodeForCountryCode( countryCode ); // -> regionCode
|
135 | ```
|
136 |
|
137 | #### Example
|
138 |
|
139 | ```js
|
140 | PhoneNumber.getCountryCodeForRegionCode( 'SE' ); // -> 46
|
141 | PhoneNumber.getRegionCodeForCountryCode( 46 ); // -> 'SE'
|
142 | ```
|
143 |
|
144 | ### Supported calling codes
|
145 |
|
146 | ```js
|
147 | PhoneNumber.getSupportedCallingCodes( ); // -> [ calling codes... ]
|
148 | ```
|
149 |
|
150 | ### Supported region codes
|
151 |
|
152 | ```js
|
153 | PhoneNumber.getSupportedRegionCodes( ); // -> [ region codes... ]
|
154 | ```
|
155 |
|
156 | ### Phone numbers
|
157 |
|
158 | An instance of the `PhoneNumber` class will be created even if `PhoneNumber` is called as a function.
|
159 |
|
160 | ```js
|
161 | var pn = PhoneNumber( number, regionCode );
|
162 | // is the same as
|
163 | var pn = new PhoneNumber( number, regionCode );
|
164 | ```
|
165 |
|
166 | PhoneNumber objects can also be created using the `getExample( regionCode[, type ] )` function, see section [Example phone numbers for country](#example) below.
|
167 |
|
168 | ```js
|
169 | pn.toJSON( ); // -> json blob as seen in "Basic usage" above
|
170 | pn.isValid( ); // -> Boolean
|
171 | pn.isPossible( ); // -> Boolean
|
172 | pn.getType( ); // -> Any of the "Phone number types" defined above
|
173 | pn.isMobile( ); // -> true if type is 'mobile' or 'fixed-line-or-mobile'
|
174 | pn.isFixedLine( ); // -> true if type is 'fixed-line' or 'fixed-line-or-mobile'
|
175 | pn.getNumber( [ format ] ); // -> Formatted number, see "Basic usage" for examples
|
176 |
|
177 | // Returns the number formatted to how to dial it from another region.
|
178 | pn.getNumberFrom( fromRegionCode );
|
179 | ```
|
180 |
|
181 | #### Example
|
182 |
|
183 | ```js
|
184 | // Calling the Swedish number 0707123456 from Japan:
|
185 | PhoneNumber( '0707123456', 'SE' ).getNumberFrom( 'JP' ); // '010 46 70 712 34 56'
|
186 | ```
|
187 |
|
188 | ### <a name="example"></a>Example phone numbers for country
|
189 |
|
190 | 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.
|
191 |
|
192 | ```js
|
193 | PhoneNumber.getExample( regionCode[, phoneNumberType] ); // PhoneNumber object
|
194 | ```
|
195 |
|
196 | The `phoneNumberType` is any of the [types defined above](#phone-number-types).
|
197 |
|
198 | #### Example
|
199 |
|
200 | ```js
|
201 | PhoneNumber.getExample( 'SE' ).getNumber( ); // '+468123456'
|
202 | PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( ); // '+46701234567'
|
203 | PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( 'national' ); // '070 123 45 67'
|
204 | ```
|
205 |
|
206 | ### As-you-type formatting
|
207 |
|
208 | 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:
|
209 |
|
210 | ```js
|
211 | // Add a character to the end of the number
|
212 | ayt.addChar( nextChar );
|
213 |
|
214 | // Get the current formatted number
|
215 | ayt.number( );
|
216 |
|
217 | // Remove the last character
|
218 | ayt.removeChar( );
|
219 |
|
220 | // Replace the whole number with a new number (or an empty number if null)
|
221 | ayt.reset( [ number ] );
|
222 |
|
223 | // Get a PhoneNumber object representing the current number
|
224 | ayt.getPhoneNumber( );
|
225 | ```
|
226 |
|
227 | All the functions above except `getPhoneNumber( )` return the current formatted number (as a String of course, as it may include spaces and other characters).
|
228 |
|
229 | #### Example
|
230 |
|
231 | ```js
|
232 | var ayt = PhoneNumber.getAsYouType( 'SE' );
|
233 | ayt.addChar( '0' ); // -> '0'
|
234 | ayt.addChar( '7' ); // -> '07'
|
235 | ayt.addChar( '0' ); // -> '070'
|
236 | ayt.addChar( '7' ); // -> '070 7'
|
237 | ayt.addChar( '1' ); // -> '070 71'
|
238 | ayt.addChar( '2' ); // -> '070 712'
|
239 | ayt.addChar( '3' ); // -> '070 712 3'
|
240 | ayt.addChar( '4' ); // -> '070 712 34'
|
241 | ayt.addChar( '5' ); // -> '070 712 34 5'
|
242 | ayt.addChar( '6' ); // -> '070 712 34 56'
|
243 | ayt.removeChar( ); // -> '070 712 34 5'
|
244 | ayt.addChar( '7' ); // -> '070 712 34 57'
|
245 | ```
|
246 |
|
247 | [npm-image]: https://img.shields.io/npm/v/awesome-phonenumber.svg
|
248 | [npm-url]: https://npmjs.org/package/awesome-phonenumber
|
249 | [downloads-image]: https://img.shields.io/npm/dm/awesome-phonenumber.svg
|
250 | [build-image]: https://img.shields.io/github/workflow/status/grantila/awesome-phonenumber/Master.svg
|
251 | [build-url]: https://github.com/grantila/awesome-phonenumber/actions?query=workflow%3AMaster
|
252 | [lgtm-image]: https://img.shields.io/lgtm/grade/javascript/g/grantila/awesome-phonenumber.svg?logo=lgtm&logoWidth=18
|
253 | [lgtm-url]: https://lgtm.com/projects/g/grantila/awesome-phonenumber/context:javascript
|
254 | [packagephobia-image]: https://packagephobia.now.sh/badge?p=awesome-phonenumber
|
255 | [packagephobia-url]: https://packagephobia.now.sh/result?p=awesome-phonenumber
|