Comprehensive type definitions including phone number formats, number types, country code sources, parsed phone number objects, and metadata structures used throughout google-libphonenumber.
Enumeration defining the different ways phone numbers can be formatted.
/**
* Formats for phone number display and output
*/
enum PhoneNumberFormat {
/** E.164 format: +12024561414 */
E164 = 0,
/** International format: +1 202-456-1414 */
INTERNATIONAL = 1,
/** National format: (202) 456-1414 */
NATIONAL = 2,
/** RFC3966 format: tel:+1-202-456-1414 */
RFC3966 = 3
}Usage Examples:
const { PhoneNumberUtil, PhoneNumberFormat } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('+1-202-456-1414', 'US');
// Format in different styles
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.format(number, PhoneNumberFormat.RFC3966)); // "tel:+1-202-456-1414"Enumeration defining the different categories of phone numbers.
/**
* Types of phone numbers as determined by getNumberType()
*/
enum PhoneNumberType {
/** Fixed line numbers (landlines) */
FIXED_LINE = 0,
/** Mobile numbers (cell phones) */
MOBILE = 1,
/** Numbers that could be either fixed line or mobile */
FIXED_LINE_OR_MOBILE = 2,
/** Toll-free numbers (free to caller) */
TOLL_FREE = 3,
/** Premium rate numbers (expensive to call) */
PREMIUM_RATE = 4,
/** Shared cost numbers */
SHARED_COST = 5,
/** Voice over IP numbers */
VOIP = 6,
/** Personal numbers */
PERSONAL_NUMBER = 7,
/** Pager numbers */
PAGER = 8,
/** Universal access numbers */
UAN = 9,
/** Voicemail access numbers */
VOICEMAIL = 10,
/** Unknown number type */
UNKNOWN = -1
}Usage Examples:
const { PhoneNumberUtil, PhoneNumberType } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
// Analyze different number types
const fixedLine = phoneUtil.parse('+1-202-456-1414', 'US');
const mobile = phoneUtil.parse('+1-555-123-4567', 'US');
const tollFree = phoneUtil.parse('+1-800-555-1234', 'US');
console.log(phoneUtil.getNumberType(fixedLine) === PhoneNumberType.FIXED_LINE_OR_MOBILE); // true
console.log(phoneUtil.getNumberType(mobile) === PhoneNumberType.MOBILE); // depends on number
console.log(phoneUtil.getNumberType(tollFree) === PhoneNumberType.TOLL_FREE); // trueEnumeration indicating how the country code was determined during parsing.
/**
* Source of the country code in a parsed phone number
*/
enum CountryCodeSource {
/** Country code source is unspecified */
UNSPECIFIED = 0,
/** Country code came from number with plus sign (+1...) */
FROM_NUMBER_WITH_PLUS_SIGN = 1,
/** Country code came from number with international dialing prefix (00...) */
FROM_NUMBER_WITH_IDD = 5,
/** Country code came from number without plus sign but appears to be international */
FROM_NUMBER_WITHOUT_PLUS_SIGN = 10,
/** Country code was inferred from the default region parameter */
FROM_DEFAULT_COUNTRY = 20
}Usage Examples:
const { PhoneNumberUtil, CountryCodeSource } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
// Parse numbers with different country code sources
const withPlus = phoneUtil.parseAndKeepRawInput('+1-202-456-1414', 'US');
const withoutPlus = phoneUtil.parseAndKeepRawInput('202-456-1414', 'US');
const withIDD = phoneUtil.parseAndKeepRawInput('011-1-202-456-1414', 'US');
console.log(withPlus.getCountryCodeSource() === CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN); // true
console.log(withoutPlus.getCountryCodeSource() === CountryCodeSource.FROM_DEFAULT_COUNTRY); // true
console.log(withIDD.getCountryCodeSource() === CountryCodeSource.FROM_NUMBER_WITH_IDD); // trueThe main data object representing a parsed phone number with all its components.
/**
* Parsed phone number object containing all number components and metadata
*/
class PhoneNumber {
/**
* Get the country code (e.g., 1 for US/Canada, 44 for UK)
* @returns {number} The country code
*/
getCountryCode(): number;
/**
* Get the country code or default value if not set
* @returns {number} The country code or 0 if not set
*/
getCountryCodeOrDefault(): number;
/**
* Get the source of the country code
* @returns {CountryCodeSource} How the country code was determined
*/
getCountryCodeSource(): CountryCodeSource;
/**
* Get the national number (without country code)
* @returns {number} The national number as a number
*/
getNationalNumber(): number;
/**
* Get the extension (if any)
* @returns {string} The extension or empty string
*/
getExtension(): string;
/**
* Get whether this number has an Italian leading zero
* @returns {boolean} True if Italian leading zero is present
*/
getItalianLeadingZero(): boolean;
/**
* Get the raw input string (only available if parsed with parseAndKeepRawInput)
* @returns {string} The original input string or empty string
*/
getRawInput(): string;
/**
* Check if this number has a country code set
* @returns {boolean} True if country code is present
*/
hasCountryCode(): boolean;
/**
* Check if this number has a national number set
* @returns {boolean} True if national number is present
*/
hasNationalNumber(): boolean;
/**
* Check if this number has an extension set
* @returns {boolean} True if extension is present
*/
hasExtension(): boolean;
/**
* Check if this number has raw input preserved
* @returns {boolean} True if raw input is available
*/
hasRawInput(): boolean;
}Usage Examples:
const { PhoneNumberUtil } = require('google-libphonenumber');
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parseAndKeepRawInput('+1 (202) 456-1414 ext. 123', 'US');
// Access all components
console.log(number.getCountryCode()); // 1
console.log(number.getNationalNumber()); // 2024561414
console.log(number.getExtension()); // "123"
console.log(number.getRawInput()); // "+1 (202) 456-1414 ext. 123"
console.log(number.getItalianLeadingZero()); // false
// Check what's available
console.log(number.hasCountryCode()); // true
console.log(number.hasNationalNumber()); // true
console.log(number.hasExtension()); // true
console.log(number.hasRawInput()); // trueError enumeration for phone number parsing and validation operations.
/**
* Error types that can occur during phone number operations
*/
enum Error {
/** Invalid country code provided */
INVALID_COUNTRY_CODE = 0,
/** Number is not a valid national number */
NOT_A_NUMBER = 1,
/** Number is too short to be valid */
TOO_SHORT_NSN = 2,
/** Number is too short after IDD removal */
TOO_SHORT_AFTER_IDD = 3,
/** Number is too long to be valid */
TOO_LONG = 4
}Data structures containing formatting and validation rules for phone numbers.
/**
* Metadata for a specific region's phone number patterns and rules
*/
class PhoneMetadata {
/**
* Get the general description for this region
* @returns {PhoneNumberDesc} General number description
*/
getGeneralDesc(): PhoneNumberDesc;
/**
* Get the fixed line number description
* @returns {PhoneNumberDesc} Fixed line number patterns
*/
getFixedLine(): PhoneNumberDesc;
/**
* Get the mobile number description
* @returns {PhoneNumberDesc} Mobile number patterns
*/
getMobile(): PhoneNumberDesc;
/**
* Get the toll-free number description
* @returns {PhoneNumberDesc} Toll-free number patterns
*/
getTollFree(): PhoneNumberDesc;
/**
* Get the premium rate number description
* @returns {PhoneNumberDesc} Premium rate number patterns
*/
getPremiumRate(): PhoneNumberDesc;
}
/**
* Description of number patterns and rules for a specific number type
*/
class PhoneNumberDesc {
/**
* Get the national number pattern regex
* @returns {string} Regular expression pattern
*/
getNationalNumberPattern(): string;
/**
* Get possible number lengths
* @returns {number[]} Array of possible lengths
*/
getPossibleLengthArray(): number[];
/**
* Get example number for this pattern
* @returns {string} Example number or empty string
*/
getExampleNumber(): string;
}
/**
* Collection of phone metadata for multiple regions
*/
class PhoneMetadataCollection {
/**
* Get metadata array for all regions
* @returns {PhoneMetadata[]} Array of region metadata
*/
getMetadataArray(): PhoneMetadata[];
}
/**
* Formatting rules for displaying phone numbers
*/
class NumberFormat {
/**
* Get the pattern that triggers this format
* @returns {string} Regular expression pattern
*/
getPattern(): string;
/**
* Get the format template
* @returns {string} Format string with $1, $2, etc. placeholders
*/
getFormat(): string;
/**
* Get the leading digits pattern
* @returns {string} Pattern for leading digits
*/
getLeadingDigitsPattern(): string;
/**
* Get the national prefix formatting rule
* @returns {string} Rule for formatting national prefix
*/
getNationalPrefixFormattingRule(): string;
}Enumeration for short number cost categories used by ShortNumberInfo.
/**
* Cost categories for short numbers
*/
enum ShortNumberCost {
/** Free to call */
TOLL_FREE = 0,
/** Standard rate applies */
STANDARD_RATE = 1,
/** Premium rate applies (higher cost) */
PREMIUM_RATE = 2,
/** Cost category unknown */
UNKNOWN_COST = 3
}The package also exports metadata objects containing phone number patterns and rules for all regions worldwide.
/**
* Phone number metadata for all regions worldwide
* Contains patterns, formatting rules, and validation data
*/
const metadata = libphonenumber.metadata;
/**
* Short number metadata for all regions worldwide
* Contains emergency numbers, service codes, and cost information
*/
const shortnumbermetadata = libphonenumber.shortnumbermetadata;These metadata objects are primarily used internally by the library but can be accessed for advanced use cases or custom implementations.
Phone numbers in google-libphonenumber are represented as proto buffer objects, not plain JavaScript objects. Always use the provided getter methods:
// Correct way to access phone number data
const countryCode = phoneNumber.getCountryCode();
const nationalNumber = phoneNumber.getNationalNumber();
// Incorrect - these properties don't exist on the object
const wrongCode = phoneNumber.countryCode; // undefined
const wrongNumber = phoneNumber.nationalNumber; // undefinedCheck for the presence of data before accessing it:
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('555-1234', 'US'); // might not have extension
// Safe access pattern
if (number.hasExtension()) {
console.log('Extension:', number.getExtension());
} else {
console.log('No extension provided');
}
// Check for raw input availability
if (number.hasRawInput()) {
console.log('Original input:', number.getRawInput());
}Always use strict equality when comparing enum values:
const numberType = phoneUtil.getNumberType(number);
// Correct enum comparison
if (numberType === PhoneNumberType.MOBILE) {
console.log('This is a mobile number');
}
// Also works with switch statements
switch (numberType) {
case PhoneNumberType.FIXED_LINE:
console.log('Fixed line number');
break;
case PhoneNumberType.MOBILE:
console.log('Mobile number');
break;
case PhoneNumberType.TOLL_FREE:
console.log('Toll-free number');
break;
default:
console.log('Other number type');
}