google-libphonenumber

What is google-libphonenumber?

The google-libphonenumber npm package is a JavaScript port of Google's libphonenumber library, which provides robust tools for parsing, formatting, and validating international phone numbers. It is designed to help developers work with phone numbers in various formats and provides functionalities such as number validation, formatting numbers for display, and extracting possible number types.

What are google-libphonenumber's main functionalities?

Parsing and validating phone numbers

This feature allows you to parse a phone number from a string and validate whether it is a possible number. The example demonstrates parsing and validating a US phone number.

const { PhoneNumberUtil } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parseAndKeepRawInput('202-456-1111', 'US');
const isValid = phoneUtil.isValidNumber(number);

Formatting phone numbers

This feature enables the formatting of parsed phone numbers into various formats, such as international and national formats. The code sample shows how to format a US phone number into an international format.

const { PhoneNumberFormat, PhoneNumberUtil } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('2024561111', 'US');
const formattedNumber = phoneUtil.format(number, PhoneNumberFormat.INTERNATIONAL);

Getting the type of a number

This functionality allows you to determine the type of a phone number (e.g., mobile, fixed-line). The example demonstrates how to parse a US phone number and get its type.

const { PhoneNumberType, PhoneNumberUtil } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('202-456-1111', 'US');
const numberType = phoneUtil.getNumberType(number);

Other packages similar to google-libphonenumber

awesome-phonenumber

Similar to google-libphonenumber, awesome-phonenumber provides functionalities for parsing, validating, and formatting international phone numbers. It is lighter and has a simpler API, but might not be as comprehensive in terms of number validation rules and country coverage.

libphonenumber-js

libphonenumber-js is another alternative that offers parsing, formatting, and validation of phone numbers. It aims to be a smaller and faster implementation compared to google-libphonenumber, by focusing on the most common use cases and dropping some of the less frequently used features.

README

google-libphonenumber

A browserify-compatible wrapper for Google's libphonenumber, a library to parse, format, store and validate international phone numbers. Zero dependencies, always up-to-date.

Status

Installation

Install the package via npm:

npm install google-libphonenumber --save

Usage

Here's a simple example on how to format a US-based number in the international phone number format:

// Require `PhoneNumberFormat`.
var PNF = require('google-libphonenumber').PhoneNumberFormat;

// Get an instance of `PhoneNumberUtil`.
var phoneUtil = require('google-libphonenumber').PhoneNumberUtil.getInstance();

// Parse number with country code.
var phoneNumber = phoneUtil.parse('202-456-1414', 'US');

// Print number in the international format.
console.log(phoneUtil.format(phoneNumber, PNF.INTERNATIONAL));
// => [phone]

Using the "As You Type" Formatter

// Require `AsYouTypeFormatter`.
var AsYouTypeFormatter = require('google-libphonenumber').AsYouTypeFormatter;
var formatter = new AsYouTypeFormatter('US');

console.log(formatter.inputDigit('6')); // => 6
console.log(formatter.inputDigit('5')); // => 65
console.log(formatter.inputDigit('0')); // => 650
console.log(formatter.inputDigit('2')); // => 650-2
console.log(formatter.inputDigit('5')); // => 650-25
console.log(formatter.inputDigit('3')); // => 650-253
console.log(formatter.inputDigit('2')); // => 650-2532
console.log(formatter.inputDigit('2')); // => (650) 253-22

formatter.clear();

Notes

Differences from other forks

• All classes available from libphonenumber are exported as-is. No magic methods.
• Always based on the latest google-closure library version available from Google with performance and bug fixes.
• Relies on a simplified and well documented update process to keep the underlying libphonenumber library always up-to-date.
• Throws errors instead of strings.

Errors

The javascript port of the original libphonenumber library throws errors as string, e.g. throw "Invalid country code" and, as Guillermo Rauch puts it, a string is not an error. However, the libphonenumber team has refused change this behaviour due to breaking changes, so a patch is applied on top of the source files to make sure that stacktraces are available and useful.

Tests

A small subset of tests guarantees that the main library functions are working as expected and are correctly exported. The actual heavy lifting is done by libphonenumber's extensive test suite.

npm test

Release

npm version [<newversion> | major | minor | patch] --no-git-tag-version

Acknowledgments

The exceptional work on libphonenumber was made possible by these committers and contributors.

Licenses

This package is licensed under MIT. The bundled libphonenumber library is licensed under Apache 2.0.