intl-phone

A library that formats and validates phone numbers.

formatPhone Example usage

See ./src/formatPhone.test.js for more examples

import { formatPhone } 'intl-phone';

formatPhone('2015550123', 'US')
// ==> "(201) 555-0123"

formatPhone('612345678', 'FR')
// ==> "6 12 34 56 78"

formatPhone('612345678', 'FR', { format: 'international' })
// ==> "+33 6 12 34 56 78"

formatPhone('612345678', 'FR', { format: 'international', plusSymbol: false })
// ==> "33 6 12 34 56 78"

formatPhone('612345678', 'FR', { format: 'national' })
// ==> "06 12 34 56 78"

formatPhone('612345678', 'FR', { outOf: 'US' })
// ==> "011 33 6 12 34 56 78"

formatPhone('612345678', 'FR', { outOf: 'CH' })
// ==> "00 33 6 12 34 56 78"

validatePhone Example usage

See ./src/validatePhone.test.js for more examples

import { validatePhone } 'intl-phone';

validatePhone('1015550123', 'US')
// ==> false

Future Work

Eventually we should add options that allow user to chose format="E164".

Background

Problem Statement

• input formatting ( making it look correct )
• input validation ( checking that the number is valid )

Standards

E.164

Terminology

Trunk Prefix

A trunk prefix is a digit sequence to be dialed before a telephone number to initiate a call for the purpose of selecting an appropriate telecommunications circuit by which the call is to be routed.

IDD is a trunk prefix NDD is a trunk prefix

————————————————————————————————————————

IDD ( International Direct Dialing )

Layman's Terms: How do I get out of my country !

Also known as: Exit Prefix, International Dialing Code, and International Call Prefix

Example: I want to get Out of the USA and into Australia:

011 61 7 3333 3333
^^^

So the USA’s IDD is 011

Note: this can be replaced by + symbol when formatting a phone number to match E.164

011 61 7 3333 3333 ------> + 61 7 3333 3333

————————————————————————————————————————

Country Code

Layman's Terms: How do I get into a country !

Example: I want to get Into Australia from the USA:

011 61 7 3333 3333
    ^^

————————————————————————————————————————

NDD ( National Direct Dialing )

Layman’s Terms: Extra numbers when dialing within a country

Background: in a number of countries, local dialing may require the addition of a '0' in front of the subscriber number. With E.164 formatting, this '0' must usually be removed.

Example:

Dial Within Australia: 07 3333 3333
                        ^

Dial Into Australia ( from US )	: 011 61 7 3333 3333

                                 ^^^NO 0 in front of 7^^^

E.164 Format: + 61 7 3333 3333

Different formats

Why are phone numbers so hard to format?

The following examples of how people will type phone numbers in england.

International

| Number | Formatted | Type | | ---------- | ---------------- | -------------------------------------------------- | | 1212345678 | +44 121 234 5678 | landline in birmingham | | 2012345678 | +44 20 1234 5678 | landline in london | | 1525123456 | +44 1525 123456 | landline in Leighton Buzzard | | 1525123456 | +44 1525 123 456 | landline in Leighton Buzzard formatted differently | | 7400123456 | +44 7400 123456 | mobile | | 7400123456 | +44 7400 123 456 | mobile formatted differently |

Domestic

| Number | Formatted | Type | | ---------- | ------------- | -------------------------------------------------- | | 1212345678 | 0121 234 5678 | landline in birmingham | | 2012345678 | 020 1234 5678 | landline in london | | 1525123456 | 01525 123456 | landline in Leighton Buzzard | | 1525123456 | 01525 123 456 | landline in Leighton Buzzard formatted differently | | 7400123456 | 07400 123456 | mobile | | 7400123456 | 07400 123 456 | mobile formatted differently |

Note: This library currently only supports the international ( E.164 ) formats.

Storage

Using the above, we break a phone number down into its components.

Given 011 61 07 3333 3333 you can get:

{
  "iddPrefix": "011",
  "countryCode": "61",
  "nddPrefix": "0",
  "areaCode": "7",
  "number": "33333333"
}

However whats required to be stored is:

{
  "country": "AU",
  "areaCode": "7",
  "number": "33333333"
}

The rest can be derived from the above

Also acceptable storage

{
  "country": "AU",
  "countryCode": "61",
  "number": "733333333"
}

{
  "country": "AU",
  "number": "733333333"
}

Developing

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installing

npm install

Running the tests

npm run test

Building the code

npm run build

Design Thought Process

Read this for a code thought process.

Adding/Updating countries

This lib is based on googles libphonenumber. To generate our configs, we eat googles meta.json. We have added a script in the runnable directory that can be used as follows:

npm run generate:meta /../../libphonenumber-js/metadata.json

Were the arg is your path to googles metadata.json file

Typescript

The author of this package hates Typescript, however, realizes many people use it and therefore has added a index.d.ts file. This file is generated from the JSdocs found in every file. See the tsconfig for more details :)

Also check out this link

Generating json.js files

NOTE Below is actually not done for now but I kept it in the readme in case this becomes a problem.

Due to a known issue with browsers importing json files. This package must also contain the .js variants of the raw json files.

Therefore, not unlike googles lib-phonenumber library, we need to ship this along with the .json.js files.