Google Libphonenumber

Google Libphonenumber is the up-to-date and reliable Google's libphonenumber package for Node.js. It provides comprehensive phone number parsing, formatting, storage, and validation capabilities with zero dependencies. This package wraps Google's original libphonenumber library (used by Android since version 4.0) and makes it easily consumable in Node.js environments without the complexities of the Google Closure library.

Package Information

• Package Name: google-libphonenumber
• Package Type: npm
• Language: JavaScript
• Installation: npm install google-libphonenumber

Core Imports

const libphonenumber = require('google-libphonenumber');
const PhoneNumberUtil = libphonenumber.PhoneNumberUtil;
const PhoneNumberFormat = libphonenumber.PhoneNumberFormat;
const AsYouTypeFormatter = libphonenumber.AsYouTypeFormatter;

Destructured imports:

const { 
  PhoneNumberUtil, 
  PhoneNumberFormat, 
  PhoneNumberType,
  CountryCodeSource,
  AsYouTypeFormatter,
  ShortNumberInfo 
} = require('google-libphonenumber');

Basic Usage

const { PhoneNumberUtil, PhoneNumberFormat } = require('google-libphonenumber');

// Get an instance of PhoneNumberUtil
const phoneUtil = PhoneNumberUtil.getInstance();

// Parse a phone number
const number = phoneUtil.parseAndKeepRawInput('202-456-1414', 'US');

// Format in different ways
console.log(phoneUtil.format(number, PhoneNumberFormat.E164));
// => +12024561414

console.log(phoneUtil.format(number, PhoneNumberFormat.INTERNATIONAL));
// => +1 202-456-1414

// Validate the number
console.log(phoneUtil.isValidNumber(number));
// => true

console.log(phoneUtil.isValidNumberForRegion(number, 'US'));
// => true

Architecture

Google Libphonenumber is built around several key components:

• PhoneNumberUtil: Singleton utility class providing the main phone number operations (parsing, formatting, validation)
• PhoneNumber Objects: Proto buffer format objects representing parsed phone numbers with rich metadata
• AsYouTypeFormatter: Real-time formatting as users type phone numbers
• ShortNumberInfo: Utilities for emergency numbers and short service codes
• Enums and Constants: Format types, number types, error codes, and country code sources
• Metadata: Comprehensive carrier and formatting data for worldwide phone number patterns

Capabilities

Phone Number Utilities

Core phone number parsing, formatting, and validation functionality. This is the primary interface for most phone number operations.

class PhoneNumberUtil {
  static getInstance(): PhoneNumberUtil;
  parse(numberToParse: string, defaultRegion: string): PhoneNumber;
  parseAndKeepRawInput(numberToParse: string, defaultRegion: string): PhoneNumber;
  format(number: PhoneNumber, numberFormat: PhoneNumberFormat): string;
  isValidNumber(number: PhoneNumber): boolean;
  isValidNumberForRegion(number: PhoneNumber, regionCode: string): boolean;
}

Phone Number Utilities

Real-time Formatting

AsYouTypeFormatter provides progressive phone number formatting as users input digits, showing the expected format as they type.

class AsYouTypeFormatter {
  constructor(regionCode: string);
  inputDigit(digit: string): string;
  clear(): void;
}

As You Type Formatter

Short Number Information

Utilities for working with short numbers including emergency services, toll-free numbers, and premium rate services.

class ShortNumberInfo {
  static getInstance(): ShortNumberInfo;
  connectsToEmergencyNumber(number: string, regionCode: string): boolean;
  isValidShortNumber(number: PhoneNumber): boolean;
  isValidShortNumberForRegion(number: PhoneNumber, regionDialingFrom: string): boolean;
}

Short Number Information

Enums and Data Types

Comprehensive type definitions including phone number formats, number types, country code sources, and parsed phone number objects.

enum PhoneNumberFormat {
  E164,
  INTERNATIONAL, 
  NATIONAL,
  RFC3966
}

enum PhoneNumberType {
  FIXED_LINE,
  MOBILE,
  FIXED_LINE_OR_MOBILE,
  TOLL_FREE,
  PREMIUM_RATE,
  // ... additional types
}

Enums and Data Types

Important Notes

Proto Buffer Objects

Most libphonenumber functions expect to receive an instance of PhoneNumber which can be obtained by calling phoneUtil.parse() or phoneUtil.parseAndKeepRawInput() on a raw string number. Methods will throw errors like TypeError: a.getCountryCodeOrDefault is not a function if you pass raw strings instead of parsed PhoneNumber objects.

This will work:

phoneUtil.isValidNumberForRegion(phoneUtil.parse('202-456-1414', 'US'), 'US');

This will not work:

phoneUtil.isValidNumberForRegion('202-456-1414', 'US');

Region Codes

Most operations require ISO 3166-1 alpha-2 region codes (e.g., 'US', 'GB', 'FR'). These are used for parsing context and validation rules.

Error Handling

The library throws exceptions for invalid inputs. Wrap parsing operations in try-catch blocks when dealing with user input or external data sources.