Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

awesome-phonenumber

Package Overview
Dependencies
Maintainers
1
Versions
166
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

awesome-phonenumber - npm Package Compare versions

Comparing version 3.4.0 to 4.0.0

200

index.d.ts
export type PhoneNumberFormat =
'e164' |
'international' |
'national' |
'rfc3966' |
'significant';
| 'e164'
| 'international'
| 'national'
| 'rfc3966'
| 'significant';
export type PhoneNumberTypes =
'fixed-line' |
'fixed-line-or-mobile' |
'mobile' |
'pager' |
'personal-number' |
'premium-rate' |
'shared-cost' |
'toll-free' |
'uan' |
'voip' |
'unknown';
| 'fixed-line'
| 'fixed-line-or-mobile'
| 'mobile'
| 'pager'
| 'personal-number'
| 'premium-rate'
| 'shared-cost'
| 'toll-free'
| 'uan'
| 'voip'
| 'unknown';
export type PhoneNumberPossibility =
| 'is-possible'
| 'invalid'
| 'invalid-country-code'
| 'too-long'
| 'too-short';
export class PhoneNumber
{
/** @deprecated use `getPhoneNumber()` instead */
constructor( phoneNumber: string, regionCode?: string );
isValid( ): boolean;
canBeInternationallyDialled( ): boolean;
isPossible( ): boolean;
getType( ): PhoneNumberTypes;
isMobile( ): boolean;
isFixedLine( ): boolean;
getNumber( type?: PhoneNumberFormat ): string;
getNumberFrom( regionCode: string ): string;
getRegionCode( ): string;
getCountryCode( ): number;
toJSON( ): any;
/**
* @deprecated Use the exported {@link getCountryCodeForRegionCode} function instead.
*/
static getCountryCodeForRegionCode( regionCode: string ): number;
/**
* @deprecated Use the exported {@link getRegionCodeForCountryCode} function instead.
*/
static getRegionCodeForCountryCode( countryCode: number ): string;
/**
* @deprecated Use the exported {@link getSupportedCallingCodes} function instead.
*/
static getSupportedCallingCodes( ): string[ ];
/**
* @deprecated Use the exported {@link getSupportedRegionCodes} function instead.
*/
static getSupportedRegionCodes( ): string[ ];
/**
* @deprecated Use the exported {@link getExample} function instead.
*/
static getExample( regionCode: string, type?: PhoneNumberTypes ): PhoneNumber;
/**
* @deprecated Use the exported {@link getAsYouType} function instead.
*/
static getAsYouType( regionCode: string ): AsYouType;
}
/** @deprecated use `parsePhoneNumber()` instead */
export function PhoneNumber( phoneNumber: string, regionCode?: string ): PhoneNumber;
/**
* Parse a phone number into a PhoneNumber class.
* Parse a phone number into an object describing the number.
*
* @example
* ```ts
* // Using a national phone number format
* parsePhoneNumber( '0707123456', 'SE' )
* parsePhoneNumber( '0707123456', { regionCode: 'SE' } )
* // Using an international (e164) phone number format
* parsePhoneNumber( '+46707123456' )
* ```
*
* The options object is on the form:
* ```ts
* {
* regionCode?: string;
* }
* ```
*
* @param phoneNumber Either an `e164` formatted (international) phone number
* or a _national_ phone number.
* @param regionCode Region code for the phone number (only required if
* {@link phoneNumber} is on a _national_ format).
* Example: 'SE' for Sweden, 'CH' for Switzerland, etc.
* @param options Object of type {@link PhoneNumberParseOptions}.
* @returns A {@link ParsedPhoneNumber}
*/
export function parsePhoneNumber( phoneNumber: string, regionCode?: string ): PhoneNumber;
export function parsePhoneNumber(
phoneNumber: string,
options?: PhoneNumberParseOptions
): ParsedPhoneNumber;
export interface PhoneNumberParseOptions
{
/**
* If the phone number is on national form, this region code specifies the
* region of the phone number, e.g. "SE" for Sweden.
*/
regionCode?: string;
}
export interface ParsedPhoneNumberFull
{
number: {
input: string;
international: string;
national: string;
e164: string;
rfc3966: string;
significant: string;
};
possibility: PhoneNumberPossibility;
regionCode: string;
valid: boolean;
possible: boolean;
canBeInternationallyDialled: boolean;
type: PhoneNumberTypes;
countryCode: string;
typeIsMobile: boolean;
typeIsFixedLine: boolean;
}
export type ParsedPhoneNumberValid =
& Omit< ParsedPhoneNumberFull, 'valid' >
& { valid: true; };
export type ParsedPhoneNumberInvalid =
& Partial< Omit< ParsedPhoneNumberFull, 'valid' | 'possible' | 'possibility' > >
& {
valid: false;
possible: boolean;
possibility: PhoneNumberPossibility;
error?: unknown;
};
export type ParsedPhoneNumber =
| ParsedPhoneNumberValid
| ParsedPhoneNumberInvalid;
export function getCountryCodeForRegionCode( regionCode: string ): number;

@@ -102,5 +115,38 @@ export function getRegionCodeForCountryCode( countryCode: number ): string;

*/
export function getExample( regionCode: string, type?: PhoneNumberTypes ): PhoneNumber;
export function getExample(
regionCode: string,
type?: PhoneNumberTypes
): ParsedPhoneNumber;
/**
* Get a phonenumber string as it would be called from another country.
*
* @param parsedPhoneNumber A phone number object as returned from {@link parsePhoneNumber `parsePhoneNumber()`}
* @param regionCode Region code of the country to call from
*/
export function getNumberFrom(
parsedPhoneNumber: ParsedPhoneNumberValid,
regionCode?: string
): PhoneNumberFrom;
export type PhoneNumberFrom =
| PhoneNumberFromValid
| PhoneNumberFromInvalid;
export interface PhoneNumberFromValid
{
valid: true;
number: string;
}
export interface PhoneNumberFromInvalid
{
valid: false;
number?: string;
error?: unknown;
}
/**
* Get an instance of the AsYouType class, based on a region code.

@@ -121,6 +167,6 @@ *

reset( number?: string ): string;
getPhoneNumber( ): PhoneNumber;
getPhoneNumber( ): ParsedPhoneNumber;
}
/** @deprecated use `parsePhoneNumber()` instead */
export default PhoneNumber;
// /** @deprecated use `parsePhoneNumber()` instead */
// export default PhoneNumber;

26

index.js

@@ -21,5 +21,26 @@ const exportedName = 'PhoneNumber$$module$src$index';

module.exports.default = module.exports;
module.exports.parsePhoneNumber = ( ...args ) =>
{
try
{
const ret = module.exports( ...args ).toJSON( );
if ( !ret.valid && !ret.possible )
{
ret.possible = false;
if ( !ret.possibility )
ret.possibility = 'invalid';
}
return ret;
}
catch ( error )
{
return {
valid: false,
possible: false,
possibility: 'invalid',
error,
};
}
};
module.exports.parsePhoneNumber = module.exports;
module.exports.getCountryCodeForRegionCode = module.exports.getCountryCodeForRegionCode;

@@ -31,1 +52,2 @@ module.exports.getRegionCodeForCountryCode = module.exports.getRegionCodeForCountryCode;

module.exports.getAsYouType = module.exports.getAsYouType;
module.exports.getNumberFrom = module.exports.getNumberFrom;

9

package.json

@@ -5,3 +5,3 @@ {

"license": "MIT",
"version": "3.4.0",
"version": "4.0.0",
"author": "Gustaf Räntilä <g.rantila@gmail.com>",

@@ -19,2 +19,3 @@ "repository": {

".": {
"types": "./index.d.ts",
"require": "./index.js",

@@ -66,4 +67,4 @@ "default": "./index-esm.mjs"

"cz-conventional-changelog": "^3.3.0",
"google-closure-compiler": "20220502.0.0",
"google-closure-library": "^20220502.0.0",
"google-closure-compiler": "20221102.0.0",
"google-closure-library": "^20221102.0.0",
"gulp": "^4.0.2",

@@ -75,4 +76,4 @@ "jest": "^28.1.0",

"rmfr": "^2.0.0",
"rollup": "^2.66.0",
"ts-jest-resolver": "^2.0.0",
"rollup": "^2.66.0",
"ts-node": "^10.7.0",

@@ -79,0 +80,0 @@ "typescript": "^4.2.4"

269

README.md

@@ -14,3 +14,3 @@ [![npm version][npm-image]][npm-url]

Uses libphonenumber v8.12.56
Uses libphonenumber v8.13.1

@@ -23,2 +23,10 @@

- 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

@@ -51,35 +59,69 @@

const pn = parsePhoneNumber( '0707123456', 'SE' );
pn.isValid( ); // -> true
pn.isMobile( ); // -> true
pn.canBeInternationallyDialled( ); // -> true
pn.getNumber( ); // -> '+46707123456'
pn.getNumber( 'e164' ); // -> '+46707123456' (default)
pn.getNumber( 'international' ); // -> '+46 70 712 34 56'
pn.getNumber( 'national' ); // -> '070-712 34 56'
pn.getNumber( 'rfc3966' ); // -> 'tel:+46-70-712-34-56'
pn.getNumber( 'significant' ); // -> '707123456'
pn.getRegionCode( ); // -> 'SE'
pn.getCountryCode( ); // -> 46
const pn = parsePhoneNumber( '0707123456', { regionCode: 'SE' } );
// or on e164 format:
const pn = parsePhoneNumber( '+46707123456' );
pn.toJSON( ); // -> json blob, so that:
JSON.stringify( pn, null, 4 ); // -> This:
// {
// "canBeInternationallyDialled": true,
// "number": {
// "input": "0707123456",
// "international": "+46 70 712 34 56",
// "national": "070-712 34 56",
// "e164": "+46707123456",
// "rfc3966": "tel:+46-70-712-34-56",
// "significant": "707123456"
// },
// "regionCode": "SE",
// "valid": true,
// "possible": true,
// "type": "mobile",
// "possibility": "is-possible"
// }
// pn is now the same as:
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,
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:
```ts
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;
canBeInternationallyDialled: boolean;
type: PhoneNumberTypes; // a string union, see below
countryCode: string;
typeIsMobile: boolean;
typeIsFixedLine: boolean;
}
```
If the number failed to be parsed, or there was another error, the return type is:
```ts
interface ParsedPhoneNumberInvalid {
valid: false;
possible: false;
possibility: 'invalid';
error?: unknown;
};
```
## API

@@ -90,2 +132,4 @@

parsePhoneNumber,
getNumberFrom,
getExample,
getCountryCodeForRegionCode,

@@ -95,3 +139,2 @@ getRegionCodeForCountryCode,

getSupportedRegionCodes,
getExample,
getAsYouType,

@@ -104,101 +147,70 @@ } from 'awesome-phonenumber'

`parsePhoneNumber( phoneNumber, regionCode )` creates a PhoneNumber instance.
`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 `regionCode` is required, e.g. 'SE' for Sweden, 'CH' for Switzerland, etc.
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.
The return is an instance of the PhoneNumber class, with the methods:
### getNumberFrom
```ts
class PhoneNumber {
isValid( ): boolean;
import { parsePhoneNumber, getNumberFrom } from 'awesome-phonenumber'
canBeInternationallyDialled( ): boolean;
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";
}
```
isPossible( ): boolean;
The return value from `getNumberFrom` is a `PhoneNumberFrom` which is either a `PhoneNumberFromValid` or a `PhoneNumberFromInvalid`.
// any of the "Phone number types" defined above
getType( ): PhoneNumberTypes;
The `PhoneNumberFromValid` is defined as:
// 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;
```ts
interface PhoneNumberFromValid
{
valid: true;
number: string;
}
```
#### getNumberFrom
The `PhoneNumberFromInvalid` is defined as:
```ts
// Calling the Swedish number 0707123456 from Japan:
parsePhoneNumber( '0707123456', 'SE' ).getNumberFrom( 'JP' );
// -> '010 46 70 712 34 56'
interface PhoneNumberFromInvalid
{
valid: false;
error?: unknown;
}
```
#### Example
```ts
import { parsePhoneNumber } from 'awesome-phonenumber'
## <a name="example"></a>getExample
const pn = parsePhoneNumber( '+46707123456' );
pn.getRegionCode( ); // -> 'SE'
```
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 { parsePhoneNumber } from 'awesome-phonenumber'
import { getExample } from 'awesome-phonenumber'
const pn = parsePhoneNumber( '0707123456', 'SE' );
getExample( regionCode[, phoneNumberType] ); // Parsed phone number
```
## API types
The `phoneNumberType` is any of the [types defined above](#phone-number-types).
The API consists of the `PhoneNumber` class which sometimes uses *enums*. These are:
### Example
### <a name="phone-number-types"></a>Phone number types
```ts
'fixed-line'
'fixed-line-or-mobile'
'mobile'
'pager'
'personal-number'
'premium-rate'
'shared-cost'
'toll-free'
'uan'
'voip'
'unknown'
```
import { getExample } from 'awesome-phonenumber'
### Phone number possibilities
// Get an example Swedish phone number
const example = getExample( 'SE' ); // A ParsedPhoneNumberValid
const exampleMobile = getExample( 'SE', 'mobile' ); // A ParsedPhoneNumberValid
```ts
'is-possible'
'invalid-country-code'
'too-long'
'too-short'
'unknown'
example.number.e164; // e.g. '+468123456'
exampleMobile.number.e164; // e.g. '+46701234567'
exampleMobile.number.national; // e.g. '070 123 45 67'
```
### Phone number formats
```ts
'international'
'national'
'e164'
'rfc3966'
'significant'
```
## Country codes

@@ -240,25 +252,46 @@

## <a name="example"></a>Example phone numbers for country
## API types
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.
The API consists of the `PhoneNumber` class which sometimes uses *enums*. These are:
### <a name="phone-number-types"></a>Phone number types
```ts
import { getExample } from 'awesome-phonenumber'
type PhoneNumberTypes =
| 'fixed-line'
| 'fixed-line-or-mobile'
| 'mobile'
| 'pager'
| 'personal-number'
| 'premium-rate'
| 'shared-cost'
| 'toll-free'
| 'uan'
| 'voip'
| 'unknown'
```
getExample( regionCode[, phoneNumberType] ); // PhoneNumber object
### Phone number possibilities
```ts
type PhoneNumberPossibility =
| 'is-possible'
| 'invalid-country-code'
| 'too-long'
| 'too-short'
| 'unknown'
```
The `phoneNumberType` is any of the [types defined above](#phone-number-types).
### Phone number formats
### Example
```ts
import { getExample } from 'awesome-phonenumber'
// Get an example Swedish phone number
getExample( 'SE' ).getNumber( ); // '+468123456'
getExample( 'SE', 'mobile' ).getNumber( ); // '+46701234567'
getExample( 'SE', 'mobile' ).getNumber( 'national' ); // '070 123 45 67'
'international'
'national'
'e164'
'rfc3966'
'significant'
```
## As-you-type formatting

@@ -278,3 +311,3 @@

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

@@ -287,6 +320,6 @@ // Get the current formatted number

// Replace the whole number with a new number (or an empty number if null)
ayt.reset( [ number ] );
// Replace the whole number with a new number (or an empty number if undefined)
ayt.reset( number?: string );
// Get a PhoneNumber object representing the current number
// Get a ParsedPhoneNumber object representing the current number
ayt.getPhoneNumber( );

@@ -293,0 +326,0 @@ ```

index-esm.mjs

Sorry, the diff of this file is not supported yet

lib/index.js

Sorry, the diff of this file is too big to display

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc