PhoneNumber

A parsed number, returned by parsePhoneNumber and by a controller’s getPhoneNumber. Fourteen methods query and format it. Every answer derives from the state resolved at parse time.

The examples share one number:

const number = parsePhoneNumber('+1 (415) 555-0132');

Validity

isValid

Whether the number exists in its region’s numbering plan.

number.isValid(); // true

isValidForRegion

Whether the number is valid for one region specifically. Mirrors Google libphonenumber’s isValidNumberForRegion.

number.isValidForRegion('US'); // true
number.isValidForRegion('CA'); // false

isPossible

Whether the calling code resolves and the length is one the region dials. The digits themselves go unchecked. A possible number can still be invalid.

number.isPossible(); // true
parsePhoneNumber('+1 123-456-7890').isPossible(); // true, ten digits is a US length

isPossibleWithReason

The possibility check as a PossibilityResult reason code. A failed isPossible says why.

number.isPossibleWithReason(); // 'IS_POSSIBLE'
parsePhoneNumber('+1 415').isPossibleWithReason(); // 'TOO_SHORT'

getValidationError

The fault to correct, or null when none applies. One of the nine typed ValidationError variants. A valid number can still carry the NATIONAL_PREFIX_MISSING advisory. Gate on isValid for validity and read the error for guidance.

number.getValidationError(); // null
parsePhoneNumber('+1 415').getValidationError(); // { kind: 'TOO_SHORT', minLength: 10 }

PossibilityResult

The six reason codes isPossibleWithReason returns. Mirrors Google libphonenumber’s ValidationResult.

Value	Meaning
IS_POSSIBLE	The calling code resolves and the length is dialed nationally
IS_POSSIBLE_LOCAL_ONLY	The length is dialed only inside its own area
INVALID_CALLING_CODE	The digits begin with no known calling code
TOO_SHORT	Fewer digits than the region’s shortest number
TOO_LONG	More digits than the region’s longest number
INVALID_LENGTH	The length falls in a gap between valid lengths

Identity

getRegion

The region the number resolves to, or null when none does.

number.getRegion(); // 'US'

getCallingCode

The country calling code read from the digits, without the +, or null when the digits carry none.

number.getCallingCode(); // '1'

getNationalNumber

The national significant number, digits only, with the national prefix stripped.

number.getNationalNumber(); // '4155550132'

getExtension

The extension captured at parse, as typed, or null when the input carried none. The notations (ext., x, #, ;ext=, and the rest) are listed under parsePhoneNumber.

parsePhoneNumber('+1 415 555 0132 ext. 22').getExtension(); // '22'
number.getExtension(); // null

getNumberType

The line type, such as MOBILE or FIXED_LINE, or FIXED_LINE_OR_MOBILE where a region assigns both. UNKNOWN means the number is not valid. The full value list is NUMBER_TYPES.

number.getNumberType(); // 'FIXED_LINE_OR_MOBILE'
parsePhoneNumber('+1 800 234 5678').getNumberType(); // 'TOLL_FREE'

Formats

Each format method returns null when the number is not possible:

parsePhoneNumber('+1 415').formatE164(); // null

formatE164

Canonical E.164, with the calling code and no formatting.

number.formatE164(); // '+14155550132'

formatNational

The region’s own national convention. A captured extension follows, written the way the calling code’s main region writes it.

number.formatNational(); // '(415) 555-0132'
parsePhoneNumber('+44 20 7183 8750 ext. 22').formatNational(); // '020 7183 8750 x22'

formatInternational

The international convention, with the calling code spelled out. A captured extension follows, as in formatNational.

number.formatInternational(); // '+1 415-555-0132'

formatRfc3966

An RFC 3966 tel: URI. A captured extension is carried as the ;ext= parameter.

number.formatRfc3966(); // 'tel:+1-415-555-0132'
parsePhoneNumber('+1 415 555 0132 ext. 22').formatRfc3966(); // 'tel:+1-415-555-0132;ext=22'

Conformance

Thirteen of the fourteen methods have a Google libphonenumber counterpart, each compared with Google’s implementation on every corpus input. getValidationError is Telixon’s own surface, with no counterpart to compare. The numbers, the method, and the cadence are on Verified.