@jakguru/phone-object
Version:
An immutable data structure representing a specific phone number and accompanying methods. It contains class and instance methods of creating, parsing, validating, and formatting phone numbers. Based on google-libphonenumber, which is in turn based on Goo
428 lines • 16.2 kB
TypeScript
/**
* The `libPhoneNumber` module is imported from the `google-libphonenumber` library and contains functions for parsing, formatting, and validating international phone numbers.
* @namespace
* @alias libPhoneNumber
*/
import * as libPhoneNumber from 'google-libphonenumber';
/**
* The `Country` type is imported from the `./countries` module and represents a country's ISO 3166-1 alpha-2 code
*/
import type { Country } from './countries';
/**
* The `CountryOrUnknown` type is imported from the `./countries` module and represents a country's ISO 3166-1 alpha-2 code, or an unknown country represented by the `'XX'` code.
* @typedef {Country | 'XX'} CountryOrUnknown
*/
import type { CountryOrUnknown } from './countries';
/**
* The `CountryTimezone` type is imported from the `./countries` module and represents a luxon timezone name
* @typedef {string} CountryTimezone
*/
import type { CountryTimezone } from './countries';
/**
* The `RawPhoneType` type represents the phone number which should be parsed. It can be either a string or a number.
* @typedef {string | number} RawPhoneType
*/
export type RawPhoneType = string | number;
/**
* The `RawCountryType` type represents the country which should be used to parse the phone number. It is of type `Country`.
* @typedef {Country} RawCountryType
*/
export type RawCountryType = Country;
/**
* The `PossiblePhoneTimezone` type represents the estimated timezone of a phone number based on the phone number's country. It can be either a `CountryTimezone` or `'UTC'`.
* @typedef {CountryTimezone | 'UTC'} PossiblePhoneTimezone
* @remarks
*
* In cases where the phone number's country has several timezones, the timezone with the greatest population is used.
* In cases where the phone number's country is not recognized or has no timezone defined, `'UTC'` is used.
*/
export type PossiblePhoneTimezone = CountryTimezone | 'UTC';
/**
* The `PhoneTypes` type represents the possible types of a phone number. It can be any of the keys of the `PhoneNumberType` object in the `google-libphonenumber` library, or `'INVALID'` if the phone number is not valid.
* @typedef {keyof typeof libPhoneNumber.PhoneNumberType | 'INVALID'} PhoneTypes
*/
export type PhoneTypes = keyof typeof libPhoneNumber.PhoneNumberType | 'INVALID';
/**
* The `PhoneModelInstanceObject` interface represents the properties of a `Phone` instance.
* @interface
*/
export interface PhoneModelInstanceObject {
/**
* The `phone` property represents the raw phone number string that was used to create the `Phone` instance.
* @type {string}
*/
phone: string;
/**
* The `country` property represents the country that was used to create the `Phone` instance.
* @type {CountryOrUnknown}
* @remarks
*
* In cases where the country was not recognized and could not be guessed from the phone number, `'XX'` is used.
*/
country: CountryOrUnknown;
/**
* The `valid` property represents whether the phone number uses a valid format for the parsed country or not.
* @type {boolean}
*/
valid: boolean;
/**
* The `type` property represents the type of the phone number. It can be any of the keys of the `PhoneNumberType` object in the `google-libphonenumber` library, or `'INVALID'` if the phone number is not valid.
* @type {PhoneTypes}
*/
type: PhoneTypes;
/**
* The `mobile` property represents whether the phone number is possibly a mobile phone number or not.
* @type {boolean}
* @remarks
*
* This property is `true` if the phone number type is either `'MOBILE'` or `'FIXED_LINE_OR_MOBILE'`.
* This covers cases like in the United States and Canada where it is not possible to tell if a phone number is a mobile phone number or not based on the phone number alone.
*/
mobile: boolean;
/**
* The `raw` property represents the phone number as a string stripped of all non-numeric characters.
* @type {string}
*/
raw: string;
/**
* The `national` property represents the phone number as a string in the national format for the parsed country.
* @type {string}
*/
national: string;
/**
* The `international` property represents the phone number as a string in the international format for the parsed country.
* @type {string}
*/
international: string;
/**
* The `e164` property represents the phone number as a string in the E.164 format.
* @type {string}
*/
e164: string;
/**
* The `timezone` property represents the estimated timezone of the phone number based on the phone number's country. It can be either a `CountryTimezone` or `'UTC'`.
* @type {PossiblePhoneTimezone}
* @remarks
*
* In cases where the phone number's country has several timezones, the timezone with the greatest population is used.
* In cases where the phone number's country is not recognized or has no timezone defined, `'UTC'` is used.
*/
timezone: PossiblePhoneTimezone;
}
/**
* The `PhoneModel` interface represents a phone number object with various properties and methods.
* @interface
*/
export interface PhoneModel {
/**
* The `country` property represents the country that was used to create the `Phone` instance.
* @type {CountryOrUnknown}
* @remarks
*
* In cases where the country was not recognized and could not be guessed from the phone number, `'XX'` is used.
*/
country: CountryOrUnknown;
/**
* The `valid` property represents whether the phone number uses a valid format for the parsed country or not.
* @type {boolean}
*/
valid: boolean;
/**
* The `type` property represents the type of the phone number. It can be any of the keys of the `PhoneNumberType` object in the `google-libphonenumber` library, or `'INVALID'` if the phone number is not valid.
* @type {PhoneTypes}
*/
type: PhoneTypes;
/**
* The `mobile` property represents whether the phone number is possibly a mobile phone number or not.
* @type {boolean}
* @remarks
*
* This property is `true` if the phone number type is either `'MOBILE'` or `'FIXED_LINE_OR_MOBILE'`.
* This covers cases like in the United States and Canada where it is not possible to tell if a phone number is a mobile phone number or not based on the phone number alone.
*/
mobile: boolean;
/**
* The `raw` property represents the phone number as a string stripped of all non-numeric characters.
* @type {string}
*/
raw: string;
/**
* The `national` property represents the phone number as a string in the national format for the parsed country.
* @type {string}
*/
national: string;
/**
* The `international` property represents the phone number as a string in the international format for the parsed country.
* @type {string}
*/
international: string;
/**
* The `e164` property represents the phone number as a string in the E.164 format.
* @type {string}
*/
e164: string;
/**
* The `timezone` property represents the estimated timezone of the phone number based on the phone number's country. It can be either a `CountryTimezone` or `'UTC'`.
* @type {PossiblePhoneTimezone}
* @remarks
*
* In cases where the phone number's country has several timezones, the timezone with the greatest population is used.
* In cases where the phone number's country is not recognized or has no timezone defined, `'UTC'` is used.
*/
timezone: PossiblePhoneTimezone;
/**
* The `toObject` method returns an object with the same properties as the `PhoneModelInstanceObject` interface.
* @returns {PhoneModelInstanceObject}
*/
toObject(): PhoneModelInstanceObject;
/**
* The `toJSON` method returns an object with the same properties as the `PhoneModelInstanceObject` interface.
* @returns {PhoneModelInstanceObject}
*/
toJSON(): PhoneModelInstanceObject;
/**
* The `toString` method returns the phone number as a string in the international format for the parsed country.
* @returns {string}
*/
toString(): string;
}
/**
* The `Phone` class represents a phone number and provides methods to retrieve information about it.
* It implements the `PhoneModel` interface.
* @class
* @implements {PhoneModel}
*/
export declare class Phone implements PhoneModel {
#private;
/**
* The `Phone` class constructor takes a `phone` argument of type `RawPhoneType` and an optional `country` argument of type `RawCountryType`.
* It initializes `Phone` instance.
* @constructor
* @param {RawPhoneType} phone - The phone number to be parsed and validated.
* @param {RawCountryType} [country] - The country code of the phone number. If not provided, the country will be guessed based on the phone number.
*/
constructor(phone: RawPhoneType, country?: RawCountryType);
/**
* Returns the country code of the phone number.
* @readonly
* @type {CountryOrUnknown}
*/
get country(): CountryOrUnknown;
/**
* Returns whether the phone number uses a valid format for the parsed country or not.
* @readonly
* @type {boolean}
*/
get valid(): boolean;
/**
* Returns the type of the phone number.
* @readonly
* @type {PhoneTypes}
*/
get type(): PhoneTypes;
/**
* Returns whether the phone number is a mobile number or not.
* @readonly
* @type {boolean}
*/
get mobile(): boolean;
/**
* Returns the raw phone number.
* @readonly
* @type {string}
*
* @remarks
* If the phone number is not a valid phone number, the initial phone number which was passed to the constructor is returned.
*/
get raw(): string;
/**
* Returns the national format of the phone number.
* @readonly
* @type {string}
*
* @remarks
* If the phone number is not a valid phone number, the initial phone number which was passed to the constructor is returned.
*/
get national(): string;
/**
* Returns the international format of the phone number.
* @readonly
* @type {string}
*
* @remarks
* If the phone number is not a valid phone number, the initial phone number which was passed to the constructor is returned.
*/
get international(): string;
/**
* Returns the E.164 format of the phone number.
* @readonly
* @type {string}
*
* @remarks
* If the phone number is not a valid phone number, the initial phone number which was passed to the constructor is returned.
*/
get e164(): string;
/**
* Returns the timezone of the phone number.
* @readonly
* @type {PossiblePhoneTimezone}
*/
get timezone(): PossiblePhoneTimezone;
/**
* Returns an object representation of the phone number.
* @returns {{
* phone: string;
* country: string;
* valid: boolean;
* type: PhoneTypes;
* mobile: boolean;
* raw: string;
* national: string;
* international: string;
* e164: string;
* timezone: PossiblePhoneTimezone;
* }} - An object representation of the phone number.
*/
toObject(): {
/**
* The phone number as a string stripped of all non-numeric characters.
*/
phone: string;
/**
* The country code of the phone number.
* @remarks
* In cases where the country was not recognized and could not be guessed from the phone number, `'XX'` is used.
* @type {CountryOrUnknown}
*/
country: CountryOrUnknown;
/**
* Whether the phone number uses a valid format for the parsed country or not.
* @type {boolean}
*/
valid: boolean;
/**
* The type of the phone number.
* @type {PhoneTypes}
*/
type: PhoneTypes;
/**
* Whether the phone number is possibly a mobile number or not.
* @type {boolean}
*/
mobile: boolean;
/**
* The phone number as a string stripped of all non-numeric characters.
* @type {string}
*/
raw: string;
/**
* The phone number as a string in the national format for the parsed country.
* @type {string}
*/
national: string;
/**
* The phone number as a string in the international format for the parsed country.
* @type {string}
*/
international: string;
/**
* The phone number as a string in the E.164 format.
* @type {string}
*/
e164: string;
/**
* The estimated timezone of the phone number based on the phone number's country. It can be either a `CountryTimezone` or `'UTC'`.
*/
timezone: PossiblePhoneTimezone;
};
/**
* Returns a JSON representation of the phone number.
* @returns {{
* phone: string;
* country: string;
* valid: boolean;
* type: PhoneTypes;
* mobile: boolean;
* raw: string;
* national: string;
* international: string;
* e164: string;
* timezone: PossiblePhoneTimezone;
* }} - A JSON-safe representation of the phone number.
*/
toJSON(): {
/**
* The phone number as a string stripped of all non-numeric characters.
*/
phone: string;
/**
* The country code of the phone number.
* @remarks
* In cases where the country was not recognized and could not be guessed from the phone number, `'XX'` is used.
* @type {CountryOrUnknown}
*/
country: CountryOrUnknown;
/**
* Whether the phone number uses a valid format for the parsed country or not.
* @type {boolean}
*/
valid: boolean;
/**
* The type of the phone number.
* @type {PhoneTypes}
*/
type: PhoneTypes;
/**
* Whether the phone number is possibly a mobile number or not.
* @type {boolean}
*/
mobile: boolean;
/**
* The phone number as a string stripped of all non-numeric characters.
* @type {string}
*/
raw: string;
/**
* The phone number as a string in the national format for the parsed country.
* @type {string}
*/
national: string;
/**
* The phone number as a string in the international format for the parsed country.
* @type {string}
*/
international: string;
/**
* The phone number as a string in the E.164 format.
* @type {string}
*/
e164: string;
/**
* The estimated timezone of the phone number based on the phone number's country. It can be either a `CountryTimezone` or `'UTC'`.
*/
timezone: PossiblePhoneTimezone;
};
/**
* Returns the E.164 format of the phone number as a string.
* @returns {string} - The E.164 format of the phone number.
*/
toString(): string;
/**
* Returns a stringified representation of the phone number.
* @returns {string} - A string representation of the phone number.
*/
inspect(): string;
/**
* Serializes the phone object to an obfuscated string which can be used to recreate the phone object from the `Phone.deserialize` method.
* @returns {string} - The serialized phone object.
*/
serialize(): string;
/**
* Creates a new phone object from a serialized phone object.
* @param serialized The serialized phone object returned from the `Phone.serialize` method.
* @returns A Phone instance with the same properties as the original phone object.
* @throws An error if the serialized phone object is not valid.
*/
static deserialize(serialized: string): Phone;
}
//# sourceMappingURL=phone.d.ts.map