tessl/npm-google-libphonenumber

The up-to-date and reliable Google's libphonenumber package for Node.js with zero dependencies

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Phone Number Utilities

Name: tessl/npm-google-libphonenumber
Author: tessl

Core phone number parsing, formatting, and validation functionality provided by the PhoneNumberUtil class. This is the primary interface for most phone number operations in google-libphonenumber.

Capabilities

PhoneNumberUtil Class

The main utility class that provides phone number operations. Uses singleton pattern - access via getInstance().

/**
 * Main utility class for phone number operations
 * @singleton Access via PhoneNumberUtil.getInstance()
 */
class PhoneNumberUtil {
  /**
   * Get the singleton instance of PhoneNumberUtil
   * @returns {PhoneNumberUtil} The singleton instance
   */
  static getInstance(): PhoneNumberUtil;
}

Phone Number Parsing

Parse phone numbers from strings into PhoneNumber objects for further processing.

/**
 * Parse a string and return it in proto buffer format.
 * @param {string} numberToParse - The number to parse
 * @param {string} defaultRegion - ISO 3166-1 alpha-2 region code for context
 * @returns {PhoneNumber} Parsed phone number object
 * @throws {Error} If the string cannot be parsed
 */
parse(numberToParse: string, defaultRegion: string): PhoneNumber;

/**
 * Parse a string and return it in proto buffer format while keeping the raw input value.
 * @param {string} numberToParse - The number to parse  
 * @param {string} defaultRegion - ISO 3166-1 alpha-2 region code for context
 * @returns {PhoneNumber} Parsed phone number object with raw input preserved
 * @throws {Error} If the string cannot be parsed
 */
parseAndKeepRawInput(numberToParse: string, defaultRegion: string): PhoneNumber;

Usage Examples:

const phoneUtil = PhoneNumberUtil.getInstance();

// Basic parsing
const number1 = phoneUtil.parse('+1-202-456-1414', 'US');
const number2 = phoneUtil.parse('202-456-1414', 'US');

// Parse and keep raw input (useful for formatting in original style)
const numberWithRaw = phoneUtil.parseAndKeepRawInput('(202) 456-1414', 'US');
console.log(numberWithRaw.getRawInput()); // "(202) 456-1414"

Phone Number Formatting

Format parsed phone numbers in various international and national formats.

/**
 * Format a phone number in the specified format using default rules.
 * @param {PhoneNumber} number - The parsed phone number to format
 * @param {PhoneNumberFormat} numberFormat - The format to use
 * @returns {string} The formatted phone number string
 */
format(number: PhoneNumber, numberFormat: PhoneNumberFormat): string;

/**
 * Format a phone number using the original phone number format that the number is parsed from.
 * @param {PhoneNumber} number - The parsed phone number (must have raw input)
 * @param {string} regionCallingFrom - The region the call is being placed from
 * @returns {string} The formatted phone number in original format
 */
formatInOriginalFormat(number: PhoneNumber, regionCallingFrom: string): string;

/**
 * Format a phone number for out-of-country dialing purposes.
 * @param {PhoneNumber} number - The parsed phone number to format
 * @param {string} regionCallingFrom - The region the call is being placed from
 * @returns {string} The formatted phone number for international dialing
 */
formatOutOfCountryCallingNumber(number: PhoneNumber, regionCallingFrom: string): string;

Usage Examples:

const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parseAndKeepRawInput('202-456-1414', 'US');

// Different formatting options
console.log(phoneUtil.format(number, PhoneNumberFormat.E164));
// => "+12024561414"

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

console.log(phoneUtil.format(number, PhoneNumberFormat.NATIONAL));
// => "(202) 456-1414"

console.log(phoneUtil.formatInOriginalFormat(number, 'US'));
// => "(202) 456-1414" (matches original input format)

console.log(phoneUtil.formatOutOfCountryCallingNumber(number, 'CH'));
// => "00 1 202-456-1414" (Swiss international dialing format)

Phone Number Validation

Validate whether phone numbers are properly formatted and valid for specific regions.

/**
 * Test whether a phone number matches a valid pattern.
 * @param {PhoneNumber} number - The parsed phone number to validate
 * @returns {boolean} True if the number is valid
 */
isValidNumber(number: PhoneNumber): boolean;

/**
 * Test whether a phone number is valid for a certain region.
 * @param {PhoneNumber} number - The parsed phone number to validate
 * @param {string} regionCode - ISO 3166-1 alpha-2 region code
 * @returns {boolean} True if the number is valid for the region
 */
isValidNumberForRegion(number: PhoneNumber, regionCode: string): boolean;

/**
 * Returns true if the number is possible (contains area code and country code) 
 * or if it could be a possible local number (with country code but missing area code).
 * @param {PhoneNumber} number - The parsed phone number to check
 * @returns {boolean} True if the number is possible
 */
isPossibleNumber(number: PhoneNumber): boolean;

Usage Examples:

const phoneUtil = PhoneNumberUtil.getInstance();
const validNumber = phoneUtil.parse('+1-202-456-1414', 'US');
const invalidNumber = phoneUtil.parse('+1-555-0123', 'US');

// Validation checks
console.log(phoneUtil.isValidNumber(validNumber)); // => true
console.log(phoneUtil.isValidNumber(invalidNumber)); // => false

console.log(phoneUtil.isValidNumberForRegion(validNumber, 'US')); // => true
console.log(phoneUtil.isValidNumberForRegion(validNumber, 'CA')); // => false

console.log(phoneUtil.isPossibleNumber(validNumber)); // => true

Phone Number Analysis

Extract information about phone numbers including type and geographic region.

/**
 * Get the type of a valid phone number.
 * @param {PhoneNumber} number - The parsed phone number to analyze
 * @returns {PhoneNumberType} The type of the phone number
 */
getNumberType(number: PhoneNumber): PhoneNumberType;

/**
 * Return the region where a phone number is from.
 * @param {PhoneNumber} number - The parsed phone number to analyze
 * @returns {string} ISO 3166-1 alpha-2 region code or null
 */
getRegionCodeForNumber(number: PhoneNumber): string;

Usage Examples:

const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('+1-202-456-1414', 'US');

// Analyze the number
console.log(phoneUtil.getNumberType(number)); 
// => PhoneNumberType.FIXED_LINE_OR_MOBILE

console.log(phoneUtil.getRegionCodeForNumber(number));
// => "US"

Error Handling

Phone number parsing can throw errors for invalid input. Always wrap parsing operations in try-catch blocks when dealing with user input:

const phoneUtil = PhoneNumberUtil.getInstance();

try {
  const number = phoneUtil.parse(userInput, defaultRegion);
  // Process valid number
} catch (error) {
  // Handle parsing error
  console.error('Invalid phone number:', error.message);
}

Performance Notes

PhoneNumberUtil.getInstance() returns a singleton, so it's safe to call repeatedly
Parsed PhoneNumber objects can be reused for multiple operations
Use parseAndKeepRawInput() only when you need to format in the original style
Validation operations are generally fast and can be called frequently