Skip to content

Commit

Permalink
feat(api): changed API, no more class constructors
Browse files Browse the repository at this point in the history 
Move to a purely functional API

BREAKING CHANGE: API change
  • Loading branch information
@grantila
grantila committed May 8, 2022
1 parent baa78a0 commit 09e0aeb
Show file tree
Hide file tree
Showing 4 changed files with 504 additions and 129 deletions.
198 changes: 126 additions & 72 deletions README.md
View file
Expand Up @@ -13,6 +13,14 @@ TypeScript typings are provided within the package.

Uses libphonenumber v8.12.48


### Versions

- v3:
- Changed API (although with backwards compatible ABI)
- Added ESM export


## 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).
Expand All @@ -35,10 +43,10 @@ node_modules files | 8 | 7 ✅ |


## Basic usage
```js
var PhoneNumber = require( 'awesome-phonenumber' );
```ts
import { parsePhoneNumber } from 'awesome-phonenumber'

var pn = new PhoneNumber( '0707123456', 'SE' );
const pn = parsePhoneNumber( '0707123456', 'SE' );
pn.isValid( ); // -> true
pn.isMobile( ); // -> true
pn.canBeInternationallyDialled( ); // -> true
Expand Down Expand Up @@ -73,25 +81,86 @@ JSON.stringify( pn, null, 4 ); // -> This:

## API

When constructed with a phone number on `e164` format (i.e. prefixed with a `+`), awesome-phonenumber will auto-detect the country:
```ts
import {
parsePhoneNumber,
getCountryCodeForRegionCode,
getRegionCodeForCountryCode,
getSupportedCallingCodes,
getSupportedRegionCodes,
getExample,
getAsYouType,
} from 'awesome-phonenumber'
```

```js
const pn = PhoneNumber( '+46707123456' );
pn.getRegionCode( ); // -> 'SE'

### parsePhoneNumber

`parsePhoneNumber( phoneNumber, regionCode )` creates a PhoneNumber instance.

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 `regionCode` is required, e.g. 'SE' for Sweden, 'CH' for Switzerland, etc.

The return is an instance of the PhoneNumber class, with the methods:

```ts
class PhoneNumber {
isValid( ): boolean;

canBeInternationallyDialled( ): boolean;

isPossible( ): boolean;

// any of the "Phone number types" defined above
getType( ): PhoneNumberTypes;

// true if type is 'mobile' or 'fixed-line-or-mobile'
isMobile( ): boolean;

// true if type is 'fixed-line' or 'fixed-line-or-mobile'
isFixedLine( ): boolean;

getNumber( type?: PhoneNumberFormat ): string;

// Formatted number when calling from regionCode
getNumberFrom( regionCode: string ): string;

getRegionCode( ): string;
getCountryCode( ): number;

// JSON blob output as seen in "Basic usage" above
toJSON( ): any;
}
```

#### getNumberFrom

```ts
// Calling the Swedish number 0707123456 from Japan:
parsePhoneNumber( '0707123456', 'SE' ).getNumberFrom( 'JP' );
// -> '010 46 70 712 34 56'
```

Otherwise, the constructor takes the phone number in _national_ format as first argument, and the region code as second:
#### Example

```ts
import { parsePhoneNumber } from 'awesome-phonenumber'

const pn = parsePhoneNumber( '+46707123456' );
pn.getRegionCode( ); // -> 'SE'
```

```ts
const pn = PhoneNumber( '0707123456', 'SE' );
import { parsePhoneNumber } from 'awesome-phonenumber'

const pn = parsePhoneNumber( '0707123456', 'SE' );
```

## API types

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

### <a name="phone-number-types"></a>Phone number types
```js
```ts
'fixed-line'
'fixed-line-or-mobile'
'mobile'
Expand All @@ -107,7 +176,7 @@ The API consists of the `PhoneNumber` class which sometimes uses *enums*. These

### Phone number possibilities

```js
```ts
'is-possible'
'invalid-country-code'
'too-long'
Expand All @@ -117,104 +186,87 @@ The API consists of the `PhoneNumber` class which sometimes uses *enums*. These

### Phone number formats

```js
```ts
'international'
'national'
'e164'
'rfc3966'
'significant'
```

## API functions

### Library
```js
var PhoneNumber = require( 'awesome-phonenumber' );
```

### Country codes
## 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.

```js
PhoneNumber.getCountryCodeForRegionCode( regionCode ); // -> countryCode
PhoneNumber.getRegionCodeForCountryCode( countryCode ); // -> regionCode
```ts
import {
getCountryCodeForRegionCode,
getRegionCodeForCountryCode,
getSupportedCallingCodes,
getSupportedRegionCodes,
} from 'awesome-phonenumber'

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

#### Example
### Example

```js
PhoneNumber.getCountryCodeForRegionCode( 'SE' ); // -> 46
PhoneNumber.getRegionCodeForCountryCode( 46 ); // -> 'SE'
```ts
getCountryCodeForRegionCode( 'SE' ); // -> 46
getRegionCodeForCountryCode( 46 ); // -> 'SE'
```

### Supported calling codes

```js
PhoneNumber.getSupportedCallingCodes( ); // -> [ calling codes... ]
```ts
getSupportedCallingCodes( ); // -> [ calling codes... ]
```

### Supported region codes

```js
PhoneNumber.getSupportedRegionCodes( ); // -> [ region codes... ]
```ts
getSupportedRegionCodes( ); // -> [ region codes... ]
```

### Phone numbers

An instance of the `PhoneNumber` class will be created even if `PhoneNumber` is called as a function.

```js
var pn = PhoneNumber( number, regionCode );
// is the same as
var pn = new PhoneNumber( number, regionCode );
```
## <a name="example"></a>Example phone numbers for country

PhoneNumber objects can also be created using the `getExample( regionCode[, type ] )` function, see section [Example phone numbers for country](#example) below.
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.

```js
pn.toJSON( ); // -> json blob as seen in "Basic usage" above
pn.isValid( ); // -> Boolean
pn.isPossible( ); // -> Boolean
pn.getType( ); // -> Any of the "Phone number types" defined above
pn.isMobile( ); // -> true if type is 'mobile' or 'fixed-line-or-mobile'
pn.isFixedLine( ); // -> true if type is 'fixed-line' or 'fixed-line-or-mobile'
pn.getNumber( [ format ] ); // -> Formatted number, see "Basic usage" for examples
```ts
import { getExample } from 'awesome-phonenumber'

// Returns the number formatted to how to dial it from another region.
pn.getNumberFrom( fromRegionCode );
getExample( regionCode[, phoneNumberType] ); // PhoneNumber object
```

#### Example

```js
// Calling the Swedish number 0707123456 from Japan:
PhoneNumber( '0707123456', 'SE' ).getNumberFrom( 'JP' ); // '010 46 70 712 34 56'
```
The `phoneNumberType` is any of the [types defined above](#phone-number-types).

### <a name="example"></a>Example phone numbers for country
### Example

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.
```ts
import { getExample } from 'awesome-phonenumber'

```js
PhoneNumber.getExample( regionCode[, phoneNumberType] ); // PhoneNumber object
// Get an example Swedish phone number
getExample( 'SE' ).getNumber( ); // '+468123456'
getExample( 'SE', 'mobile' ).getNumber( ); // '+46701234567'
getExample( 'SE', 'mobile' ).getNumber( 'national' ); // '070 123 45 67'
```

The `phoneNumberType` is any of the [types defined above](#phone-number-types).
## As-you-type formatting

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

```js
PhoneNumber.getExample( 'SE' ).getNumber( ); // '+468123456'
PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( ); // '+46701234567'
PhoneNumber.getExample( 'SE', 'mobile' ).getNumber( 'national' ); // '070 123 45 67'
```
```ts
import { getAsYouType } from 'awesome-phonenumber'

### As-you-type formatting
const ayt = getAsYouType( 'SE' );
```

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:
The returned class instance has the following methods

```js
```ts
// Add a character to the end of the number
ayt.addChar( nextChar );

Expand All @@ -231,12 +283,14 @@ 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).
All the functions above except `getPhoneNumber( )` return the current formatted number as a string.

#### Example

```js
var ayt = PhoneNumber.getAsYouType( 'SE' );
```ts
import { getAsYouType } from 'awesome-phonenumber'

const ayt = getAsYouType( 'SE' );
ayt.addChar( '0' ); // -> '0'
ayt.addChar( '7' ); // -> '07'
ayt.addChar( '0' ); // -> '070'
Expand Down

0 comments on commit 09e0aeb

Please sign in to comment.