Core parsing functionality for converting phone number strings into structured, validated objects with comprehensive metadata including formatting options, validity checks, and phone number type detection.
Parses a phone number string into a structured object containing validation results, formatting options, and metadata.
/**
* Parse a phone number into an object describing the number.
*
* @param phoneNumber Either an e164 formatted (international) phone number or a national phone number
* @param options Object containing optional regionCode for parsing national numbers
* @returns ParsedPhoneNumber object with validation and formatting information
*/
function parsePhoneNumber(
phoneNumber: string,
options?: PhoneNumberParseOptions
): ParsedPhoneNumber;
interface PhoneNumberParseOptions {
/** If the phone number is on national form, this region code specifies the region of the phone number, e.g. "SE" for Sweden */
regionCode?: string;
}
type ParsedPhoneNumber = ParsedPhoneNumberValid | ParsedPhoneNumberInvalid;Usage Examples:
import { parsePhoneNumber } from "awesome-phonenumber";
// Parse national format with region code
const swedenNumber = parsePhoneNumber("0707123456", { regionCode: "SE" });
if (swedenNumber.valid) {
console.log(swedenNumber.number.international); // "+46 70 712 34 56"
console.log(swedenNumber.type); // "mobile"
console.log(swedenNumber.countryCode); // 46
}
// Parse international E164 format
const intlNumber = parsePhoneNumber("+46707123456");
if (intlNumber.valid) {
console.log(intlNumber.number.national); // "070-712 34 56"
console.log(intlNumber.regionCode); // "SE"
}
// Handle invalid numbers (but check for short numbers)
const invalid = parsePhoneNumber("invalid");
if (!invalid.valid) {
console.log(invalid.possibility); // e.g., "too-short", "invalid"
console.log(invalid.possible); // false
console.log(invalid.shortValid); // false (not a valid short number either)
}Base interface containing all possible properties for a parsed phone number. This interface defines the complete structure that valid parsed phone numbers extend from.
interface ParsedPhoneNumberFull {
/** Phone number in various formats */
number: {
/** Original input string */
input: string;
/** International format: "+46 70 712 34 56" */
international: string;
/** National format: "070-712 34 56" */
national: string;
/** E164 format: "+46707123456" */
e164: string;
/** RFC3966 format: "tel:+46-70-712-34-56" */
rfc3966: string;
/** Significant digits only: "707123456" */
significant: string;
};
/** Validation state of the number */
possibility: PhoneNumberPossibility;
/** ISO region code (e.g., "SE" for Sweden) */
regionCode: string;
/** Whether number is valid */
valid: boolean;
/** Whether number is possible in the given region */
possible: boolean;
/** Whether number is valid as a short number (e.g., emergency numbers, service codes) */
shortValid: boolean;
/** Whether number is possible as a short number (e.g., emergency numbers, service codes) */
shortPossible: boolean;
/** Whether number can be dialed internationally */
canBeInternationallyDialled: boolean;
/** Phone number type classification */
type: PhoneNumberTypes;
/** Numeric country calling code */
countryCode: number;
/** True if type is mobile */
typeIsMobile: boolean;
/** True if type is fixed-line */
typeIsFixedLine: boolean;
}Result type for successfully parsed phone numbers. Extends ParsedPhoneNumberFull with the valid property set to true.
type ParsedPhoneNumberValid = Omit<ParsedPhoneNumberFull, 'valid'> & { valid: true }Result type for failed phone number parsing attempts. Contains partial information from ParsedPhoneNumberFull with the valid property set to false. Note that even invalid numbers still provide short number validation results.
type ParsedPhoneNumberInvalid = Partial<Omit<ParsedPhoneNumberFull, 'valid' | 'possible' | 'possibility'>> & {
valid: false;
possible: boolean;
possibility: PhoneNumberPossibility;
shortValid: boolean;
shortPossible: boolean;
error?: unknown;
}Enumeration of possible validation states for phone numbers.
type PhoneNumberPossibility =
| 'is-possible' // Number is valid and possible
| 'invalid' // Number is completely invalid
| 'invalid-country-code' // Country code is not recognized
| 'too-long' // Number has too many digits
| 'too-short' // Number has too few digits
| 'unknown'; // Validation state cannot be determinedClassification of phone number types based on usage patterns.
type PhoneNumberTypes =
| 'fixed-line' // Traditional landline numbers
| 'fixed-line-or-mobile' // Could be either fixed-line or mobile
| 'mobile' // Mobile/cellular numbers
| 'pager' // Pager numbers
| 'personal-number' // Personal numbering service
| 'premium-rate' // Premium rate numbers (expensive to call)
| 'shared-cost' // Shared cost service numbers
| 'toll-free' // Free to call numbers (800 numbers)
| 'uan' // Universal Access Numbers
| 'voip' // Voice over IP numbers
| 'unknown'; // Type cannot be determinedAvailable formatting options for phone numbers.
type PhoneNumberFormat =
| 'e164' // E164 international format: "+46707123456"
| 'international' // International with spaces: "+46 70 712 34 56"
| 'national' // National format: "070-712 34 56"
| 'rfc3966' // RFC3966 URI format: "tel:+46-70-712-34-56"
| 'significant'; // Significant digits only: "707123456"The library provides comprehensive support for short numbers, which are special service numbers like emergency numbers (911, 112), directory assistance, and other region-specific service codes.
Every parsed phone number, whether valid or invalid as a regular phone number, includes short number validation:
import { parsePhoneNumber } from "awesome-phonenumber";
// Emergency number example
const emergency = parsePhoneNumber("112", { regionCode: "SE" });
console.log(emergency.valid); // false (not a valid regular number)
console.log(emergency.shortValid); // true (valid emergency number)
console.log(emergency.shortPossible); // true
// Invalid input but check short number possibility
const invalid = parsePhoneNumber("11", { regionCode: "US" });
console.log(invalid.valid); // false
console.log(invalid.shortValid); // false
console.log(invalid.shortPossible); // true (could be start of 911)Short numbers are region-specific and follow different validation rules than regular phone numbers. They're essential for emergency services, customer service lines, and other special services.