{"id":19888822,"url":"https://github.com/paypal/fullstack-phone","last_synced_at":"2025-04-04T12:05:59.484Z","repository":{"id":47156537,"uuid":"89301461","full_name":"paypal/fullstack-phone","owner":"paypal","description":"A dual-module phone number system with dynamic regional metadata ☎️","archived":false,"fork":false,"pushed_at":"2025-03-17T13:47:10.000Z","size":2423,"stargazers_count":91,"open_issues_count":2,"forks_count":19,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-28T11:08:56.370Z","etag":null,"topics":["libphonenumber","phone"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paypal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-25T01:01:27.000Z","updated_at":"2025-03-17T13:47:12.000Z","dependencies_parsed_at":"2022-08-12T13:11:53.386Z","dependency_job_id":"485232bb-526e-4e26-9b09-b29e7b6aceb0","html_url":"https://github.com/paypal/fullstack-phone","commit_stats":{"total_commits":423,"total_committers":7,"mean_commits":60.42857142857143,"dds":"0.36170212765957444","last_synced_commit":"5dbb1a171c8eeab67a2784471ecefc2c1e37df41"},"previous_names":[],"tags_count":177,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Ffullstack-phone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Ffullstack-phone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Ffullstack-phone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paypal%2Ffullstack-phone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paypal","download_url":"https://codeload.github.com/paypal/fullstack-phone/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174415,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["libphonenumber","phone"],"created_at":"2024-11-12T18:08:21.261Z","updated_at":"2025-04-04T12:05:59.476Z","avatar_url":"https://github.com/paypal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"fullstack-phone ☎️\n======================\n\n| npm                                                          | Libphonenumber version                                       |\n| ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [![npm version](https://badge.fury.io/js/fullstack-phone.svg)](https://www.npmjs.com/package/fullstack-phone) | [v9.0.2](https://github.com/googlei18n/libphonenumber/blob/master/release_notes.txt) |\n\n**fullstack-phone** provides formatting, validation, and parsing of phone numbers per-region. The system is optimized for use as two modules:\n\n1. a metadata server providing dynamic regional metadata\n2. a lightweight, Closure-compiled phone client (27KB, 10KB gzipped)\n\nThis project was extended from [Nathan Hammond's project](https://github.com/nathanhammond/libphonenumber), which itself is an adaptation of [Google's libphonenumber](https://github.com/googlei18n/libphonenumber/) library.\n\nContents\n--------\n- [Installation](#installation)\n- [Usage](#usage)\n- [Why](#why)\n- [Canonical Phone Object](#canonical-phone-object)\n- [APIs](#apis)\n  - [Server](#server)\n  - [Client](#client)\n  - [Phone Handler](#phone-handler)\n- [Development](#development)\n\n## Installation\n\n```bash\nnpm install fullstack-phone\n```\n\n## Usage\n\n**Demo App:** [fullstack-phone-demo](https://github.com/dwbruhn/fullstack-phone-demo)\n\nThe modules are optimized for use in two environments.\n\nOn the server (requires Node 4+):\n\n```javascript\n// Node.js:\nvar phoneServer = require('fullstack-phone/server');\n\nvar metadata = phoneServer.loadMeta(['US', 'RU']); // load US and RU phone metadata\n// now serve the metadata via some REST API or write it to a file for bundling with client code\n```\n\nOn the client (assuming a client-side bundler that provides `require`, like [webpack](https://webpack.github.io/)):\n\n```javascript\n// Browser:\nvar phoneClient = require('fullstack-phone/client');\n\n// fetch the metadata somehow, then pass to createPhoneHandler to instantiate a handler:\nvar phoneHandler = phoneClient.createPhoneHandler(metadata);\n```\n\nOnce initialized, the phone handler can be used to process phone numbers:\n\n```javascript\n// phone handler functions:\n\nphoneHandler.getSupportedRegions(); // \u003e ['US', 'RU']\n\nphoneHandler.formatPhoneNumber(\n  { countryCode: '1', nationalNumber: '5101234567'},\n  { style: 'national'}\n);\n// \u003e '(510) 123-4567'\n\nphoneHandler.parsePhoneNumber('5101234567', 'US');\n// \u003e { countryCode: '1', nationalNumber: '5101234567' }\n\nphoneHandler.validatePhoneNumber(\n  { countryCode: '1', nationalNumber: '5101234567'},\n  'US'\n);\n// \u003e [Error: PHONE_INVALID_FOR_REGION]\n```\n\nIt's also possible to use both within the same environment. Using the server module in the browser, however, nullifies the advantages of the per-region metadata slicing.\n\n## Why\n\n[Google’s libphonenumber library](https://github.com/googlei18n/libphonenumber/) is the de-facto industry standard for processing international phone numbers, providing support for formatting, validating, and normalizing phone numbers in 250+ regions. However, the default phone metadata is quite heavy. Various custom JS packages have reduced the code \u0026 metadata footprint by:\n\n- Simplifying the API and pre-compiling with Closure ([grantila/awesome-phonenumber](https://github.com/grantila/awesome-phonenumber))\n- Providing individually compiled code+metadata bundles for each region ([leodido/i18n.phonenumbers.js](https://github.com/leodido/i18n.phonenumbers.js), [nathanhammond/libphonenumber](https://github.com/nathanhammond/libphonenumber))\n- Rewriting the entire library without Closure and providing the option to dynamically load metadata for groups of regions ([catamphetamine/libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js))\n\nThis package fills a different niche by providing:\n- The official libphonenumber code (not a pure JS re-write)\n- A small, static code base that doesn’t change for different regions\n- Pluggable metadata bundles for individual regions\n\n## Canonical Phone Object\n\nWhen using Google libphonenumber directly, processing a phone number requires [parsing a string](https://github.com/googlei18n/libphonenumber/blob/11ad0018a9940ec60ea2c8287d5d0ebc0bd0c188/javascript/i18n/phonenumbers/phonenumberutil_test.js#L1334) or [initializing a protocol buffer phone number object and calling setters for its various properties](https://github.com/googlei18n/libphonenumber/blob/11ad0018a9940ec60ea2c8287d5d0ebc0bd0c188/javascript/i18n/phonenumbers/phonenumberutil_test.js#L521-L525).\n\nIn contrast, fullstack-phone provides a more idiomatic JavaScript phone object, removing the need to call multiple setters. Most of the phone number functions here operate on a canonical `phoneObj`, as follows:\n\n```javascript\n{\n  countryCode : '1',\n  nationalNumber : '5105551234',\n  extension : '999'\n}\n```\n\n* `countryCode`\n  * **Required**. A *number* or *string* of digits representing a country phone code, e.g., `'1'`.\n\n\n* `nationalNumber`\n  * **Required**. A *number* or *string* of digits representing a phone number, as defined by [E.164](https://en.wikipedia.org/wiki/E.164), e.g., `'4085551212'`.\n  * Note that this excludes the leading national prefix (or \"trunk code\"), which is 0 or 1 in most territories.\n  * [Italian leading zeros](https://github.com/googlei18n/libphonenumber/blob/11ad0018a9940ec60ea2c8287d5d0ebc0bd0c188/resources/phonenumber.proto#L57-L74) **should** be included here.\n\n\n* `extension`\n  * **Optional**. A string representing the phone number extension, e.g., `'123'`.\n\n### Notes\n\nFor proper formatting and validation results, `nationalNumber` and `countryCode` must only contain digits. In addition, `countryCode` must be the calling code of a country for which the phone handler was initialized. (For example, if a `phoneObj` is passed with `countryCode: 44`, the phone handler must have been loaded with [GB](https://en.wikipedia.org/wiki/Telephone_numbers_in_the_United_Kingdom) metadata for proper results.)\n\nThe `phoneObj` object can be created by calling [`parsePhoneNumber`](#parsephonenumber) on a phone number string.\n\n## APIs\n\n### Server\n\n```javascript\nvar phoneServer = require('fullstack-phone/server');\n```\n\nThe phone server exposes only one function:\n\n#### loadMeta\n\n##### `phoneServer.loadMeta(regionCodeArray)`\n\nGiven an array of two-letter region codes ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), return a metadata bundle for those regions, to be passed to [`phoneClient.createPhoneHandler()`](#createphonehandler).\n\n##### Notes:\n\n* If `regionCodeArray` is undefined, **all regional metadata** is returned.\n* `loadMeta` adds support for the following regions to Google libphonenumber:\n  * PN: Pitcairn Islands (copied from New Zealand metadata)\n  * AN: Netherlands Antilles (copied from Bonaire, Sint Eustatius and Saba)\n* Some regions depend on metadata of other regions. For example, the Bahamas (BS) shares a telephone country code (1) with the United States (US). Since the US is considered the main region for country code 1, the US metadata must be included to support processing of Bahamas phone numbers. `loadMeta` takes care of this automatically.\n\nThe full list of region codes supported is:\n\n```javascript\n['001', 'AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AN', 'AO', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', 'BF', 'BG', 'BH', 'BI', 'BJ', 'BL', 'BM', 'BN', 'BO', 'BQ', 'BR', 'BS', 'BT', 'BW', 'BY', 'BZ', 'CA', 'CC', 'CD', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CR', 'CU', 'CV', 'CW', 'CX', 'CY', 'CZ', 'DE', 'DJ', 'DK', 'DM', 'DO', 'DZ', 'EC', 'EE', 'EG', 'EH', 'ER', 'ES', 'ET', 'FI', 'FJ', 'FK', 'FM', 'FO', 'FR', 'GA', 'GB', 'GD', 'GE', 'GF', 'GG', 'GH', 'GI', 'GL', 'GM', 'GN', 'GP', 'GQ', 'GR', 'GT', 'GU', 'GW', 'GY', 'HK', 'HN', 'HR', 'HT', 'HU', 'ID', 'IE', 'IL', 'IM', 'IN', 'IO', 'IQ', 'IR', 'IS', 'IT', 'JE', 'JM', 'JO', 'JP', 'KE', 'KG', 'KH', 'KI', 'KM', 'KN', 'KP', 'KR', 'KW', 'KY', 'KZ', 'LA', 'LB', 'LC', 'LI', 'LK', 'LR', 'LS', 'LT', 'LU', 'LV', 'LY', 'MA', 'MC', 'MD', 'ME', 'MF', 'MG', 'MH', 'MK', 'ML', 'MM', 'MN', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MU', 'MV', 'MW', 'MX', 'MY', 'MZ', 'NA', 'NC', 'NE', 'NF', 'NG', 'NI', 'NL', 'NO', 'NP', 'NR', 'NU', 'NZ', 'OM', 'PA', 'PE', 'PF', 'PG', 'PH', 'PK', 'PL', 'PM', 'PN', 'PR', 'PS', 'PT', 'PW', 'PY', 'QA', 'RE', 'RO', 'RS', 'RU', 'RW', 'SA', 'SB', 'SC', 'SD', 'SE', 'SG', 'SH', 'SI', 'SJ', 'SK', 'SL', 'SM', 'SN', 'SO', 'SR', 'SS', 'ST', 'SV', 'SX', 'SY', 'SZ', 'TA', 'TC', 'TD', 'TG', 'TH', 'TJ', 'TK', 'TL', 'TM', 'TN', 'TO', 'TR', 'TT', 'TV', 'TW', 'TZ', 'UA', 'UG', 'US', 'UY', 'UZ', 'VA', 'VC', 'VE', 'VG', 'VI', 'VN', 'VU', 'WF', 'WS', 'XK', 'YE', 'YT', 'ZA', 'ZM', 'ZW']\n```\n\nNote that `'001'` is used to load metadata for global numbers, such as 1-800 numbers.\n\n\n##### Examples\n\n```javascript\nvar meta = phoneServer.loadMeta(['DE', 'AU']);\n// \u003e metadata object for DE and AU\n\nvar meta = phoneServer.loadMeta();\n// \u003e metadata object for all regions\n```\n\n### Client\n\n```javascript\nvar phoneClient = require('fullstack-phone/client');\n```\n\nThe phone client exposes only one function:\n\n#### createPhoneHandler\n\n##### `phoneClient.createPhoneHandler(metadata)`\n\nGiven a metadata bundle from [`phoneServer.loadMeta()`](#loadmeta), return a phone handler instantiated for that metadata.\n\n### Phone Handler\n\n```javascript\nvar phoneHandler = phoneClient.createPhoneHandler(metadata);\n```\n\nThe phone handler returned by `createPhoneHandler` provides the following methods:\n\n- [getSupportedRegions](#getsupportedregions)\n- [countryCodeToRegionCodeMap](#countrycodetoregioncodemap)\n- [getCountryCodeForRegion](#getcountrycodeforregion)\n- [formatPhoneNumber](#formatphonenumber)\n- [validatePhoneNumber](#validatephonenumber)\n- [validateLength](#validatelength)\n- [parsePhoneNumber](#parsephonenumber)\n- [getExampleNumberForType](#getexamplenumberfortype)\n- [inferPhoneNumberRegion](#inferphonenumberregion)\n- [inferPhoneNumberType](#inferphonenumbertype)\n- [getAsYouTypeFormatter](#getasyoutypeformatter)\n  - [inputDigit](#inputdigit)\n  - [clear](#clear)\n  - [inputDigitAndRememberPosition](#inputdigitandrememberposition)\n  - [getRememberedPosition](#getrememberedposition)\n\n#### Exceptions\n\nAny method that takes a `phoneObj` parameter can throw the following exception if called with an invalid [canonical phone object](#canonical-phone-object):\n\n```javascript\nphoneHandler.inferPhoneNumberType(123);\n// Uncaught Error: Phone object conversion failed\n\nphoneHandler.inferPhoneNumberType({ countryCode: 1, nationalNumber: false });\n// Uncaught Error: Phone object conversion failed\n```\n\nAny method that takes a `regionCode` string can throw the following exception if called with a region code for which the handler has not been initialized:\n\n```javascript\nphoneHandler.getCountryCodeForRegion();\n// Uncaught Error: Metadata not loaded for region: undefined\n\nphoneHandler.getCountryCodeForRegion('XX');\n// Uncaught Error: Metadata not loaded for region: XX\n```\n\n#### getSupportedRegions\n\n##### `phoneHandler.getSupportedRegions()`\n\nReturn array of supported region codes.\n\nNote that if a dependent region was loaded (such as the Bahamas), the main region for the shared country code is also reported a supported region (e.g., US).\n\n##### Example\n\n```javascript\nphoneHandler.getSupportedRegions();\n// \u003e ['US', 'RU']\n```\n\n#### countryCodeToRegionCodeMap\n\n##### `phoneHandler.countryCodeToRegionCodeMap()`\n\nReturn map from country calling codes to array of supported regions.\n\n##### Example\n\n```javascript\nphoneHandler.countryCodeToRegionCodeMap();\n// \u003e { '1': [ 'US', 'BS' ], '7': [ 'RU' ] }\n```\n\n#### getCountryCodeForRegion\n\n##### `phoneHandler.getCountryCodeForRegion(regionCode)`\n\nReturn a country calling code as a number, given a `regionCode` string (assuming metadata has already been loaded for that region).\n\n##### Example\n\n```javascript\nphoneHandler.getCountryCodeForRegion('RU');\n// \u003e 7\n```\n\n#### formatPhoneNumber\n\n##### `phoneHandler.formatPhoneNumber(phoneObj, options)`\n\nReturn a formatted phone number as a string, given a [`phoneObj` object](#canonical-phone-object) and `options` object with a valid `style` property (`'national'`, `'international'`, `'e164'`, or `'rfc3966'`).\n\nThe `options` object has a single string property to indicate the formatting style desired:\n\n```javascript\n{\n    style: 'national' // or 'international', 'e164', 'rfc3966'\n}\n```\n\n##### Examples\n\n```javascript\nvar phone = { countryCode: '1', nationalNumber: '5101234567' };\n\nphoneHandler.formatPhoneNumber(phone, { style: 'international' });\n// \u003e '+1 510-123-4567'\n\nphoneHandler.formatPhoneNumber(phone, { style: 'national' });\n// \u003e '(510) 123-4567'\n\nphoneHandler.formatPhoneNumber(phone, { style: 'e164' });\n// \u003e '+15101234567'\n\nphoneHandler.formatPhoneNumber(phone, { style: 'rfc3966' })\n// \u003e 'tel:+1-510-123-4567'\n```\n\n#### validatePhoneNumber\n\n##### `phoneHandler.validatePhoneNumber(phoneObj, ?regionCode)`\n\nPerform **full** validation on a phone number: Given a [`phoneObj` object](#canonical-phone-object) and optional `regionCode` string, return an Error object indicating any problems with the phone object (or `true` if it passed validation).\n\nIf `regionCode` is provided, the phone number is validated for the given region. If it is omitted, the phone number is validated for the region inferred from the number itself. In both cases, the handler needs to have already been instantiated with metadata for the expected region(s).\n\nThe possible error messages are:\n\n* `'PHONE_INVALID_FOR_REGION'`\n  * Phone number is not valid for some reason. (See the examples below.)\n* `'PHONE_INVALID_COUNTRY_CODE'`\n  * The `phoneObj.countryCode` is not recognized for one of these reasons:\n    * It's completely invalid (like '9999'),\n    * Metadata has not been loaded for the region corresponding to `phoneObj.countryCode`, or\n    * It does not correspond to to the `regionCode` passed.\n* `'PHONE_NUMBER_TOO_LONG'`\n* `'PHONE_NUMBER_TOO_SHORT'`\n* `'PHONE_NUMBER_INVALID_LENGTH'`\n  * Phone number is not too long, not too short, but not just right, either. For example, Andorra (AD) numbers are 6, 8, or 9 digits, so a 7-digit number yields this error.\n\n##### Examples\n\n```javascript\n// valid US phone number\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '5105261234' }, 'US');\n// \u003e true\n\n// regionCode is optional\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '5105261234' });\n// \u003e true\n\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '5' }, 'US');\n// \u003e [Error: PHONE_NUMBER_TOO_SHORT]\n\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '51052612341' }, 'US');\n// \u003e [Error: PHONE_NUMBER_TOO_LONG]\n\n// 10 digits (like a US phone number), but not an actual valid number\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '1234567890' }, 'US');\n// \u003e [Error: PHONE_INVALID_FOR_REGION]\nphoneHandler.validatePhoneNumber({ countryCode: '1', nationalNumber: '1234567890' });\n// \u003e [Error: PHONE_INVALID_FOR_REGION]\n\n// completely invalid countryCode\nphoneHandler.validatePhoneNumber({ countryCode: '999', nationalNumber: '5105261234' }, 'US');\n// \u003e [Error: PHONE_INVALID_COUNTRY_CODE]\n\n// countryCode 44 is for GB, but US regionCode was passed\nphoneHandler.validatePhoneNumber({ countryCode: '44', nationalNumber: '1212345678' }, 'US');\n// \u003e [Error: PHONE_INVALID_COUNTRY_CODE]\n\n// valid GB number\nphoneHandler.validatePhoneNumber({ countryCode: '44', nationalNumber: '1212345678' }, 'GB');\n// \u003e true\nphoneHandler.validatePhoneNumber({ countryCode: '44', nationalNumber: '1212345678' });\n// \u003e true\n```\n\n#### validateLength\n\n##### `phoneHandler.validateLength(phoneObj, ?regionCode)`\n\nPerform minimal validation (**length check only**) on a phone number: Given a [`phoneObj` object](#canonical-phone-object) and optional `regionCode` string, return an Error object indicating any length problems with the phone object (or `true` if it passed the length validation).\n\nIf `regionCode` is provided, the phone number is validated for the given region. If it is omitted, the phone number is validated for the region inferred from the number itself. In both cases, the handler needs to have already been instantiated with metadata for the expected region(s).\n\nThe possible error messages are:\n\n* `'PHONE_INVALID_COUNTRY_CODE'`\n  * The `phoneObj.countryCode` is not recognized for one of these reasons:\n    * It's completely invalid (like '9999'),\n    * Metadata has not been loaded for the region corresponding to `phoneObj.countryCode`, or\n    * It does not correspond to to the `regionCode` passed.\n* `'PHONE_NUMBER_TOO_LONG'`\n* `'PHONE_NUMBER_TOO_SHORT'`\n* `'PHONE_NUMBER_INVALID_LENGTH'`\n  * The phone number is not too long, not too short, but not just right, either. For example, Andorra (AD) numbers are 6, 8, or 9 digits, so a 7-digit number yields this error.\n* `'PHONE_NUMBER_POSSIBLE_LOCAL_ONLY'`\n  * The phone number could be dialed within a local area (e.g., US numbers without the area code) but is not long enough to be a full phone number dialable from anywhere.\n* `'PHONE_INVALID_FOR_REGION`'\n  * Fallback error: This error would only be returned if libphonenumber adds a new enum member to ValidationResult.\n\n##### Examples\n\n```javascript\n// any 10-digit phone number in the US passes validateLength\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '1234567890' }, 'US');\n// \u003e true\n\n// regionCode is optional\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '1234567890' });\n// \u003e true\n\n// 7-digit numbers are only possible locally in the US\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '1234567' }, 'US');\n// \u003e [Error: PHONE_NUMBER_POSSIBLE_LOCAL_ONLY]\n\n// 6-digit numbers are too short in the US\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '123456' }, 'US');\n// \u003e [Error: PHONE_NUMBER_TOO_SHORT]\n\n// 11-digit numbers are too long in the US\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '12345678901' }, 'US');\n// \u003e [Error: PHONE_NUMBER_TOO_LONG]\n\n// wrong regionCode yields PHONE_INVALID_COUNTRY_CODE (regionCode AD does not match countryCode 1)\nphoneHandler.validateLength({ countryCode: '1', nationalNumber: '1234567890' }, 'AD');\n// \u003e [Error: PHONE_INVALID_COUNTRY_CODE]\n\n// a completely invalid countryCode (999) also yields PHONE_INVALID_COUNTRY_CODE\nphoneHandler.validateLength({ countryCode: '999', nationalNumber: '1234567890' });\n// \u003e [Error: PHONE_INVALID_COUNTRY_CODE]\n\n// 7-digit number in Andorra (regionCode AD, countryCode 376) is in between valid number lengths\nphoneHandler.validateLength({ countryCode: '376', nationalNumber: '1234567' }, 'AD');\n// \u003e [Error: PHONE_NUMBER_INVALID_LENGTH]\n```\n\n#### parsePhoneNumber\n\n##### `phoneHandler.parsePhoneNumber(phoneNumberToParse, ?regionCode)`\n\nParse a string and return a [`phoneObj` object](#canonical-phone-object) (or an Error object if parsing failed), given the string parameters `phoneNumberToParse` and optional `regionCode`.\n\nThe optional `regionCode` parameter provides a fallback if the country code cannot be extracted from the `phoneNumberToParse` string. If the string contains `+` followed by the country code, then `regionCode` can be safely omitted. In both cases, however, the handler needs to have already been instantiated with metadata for the expected region(s).\n\nThe possible error messages are:\n\n* `'PHONE_INVALID_COUNTRY_CODE'`\n* `'PHONE_NUMBER_TOO_SHORT'`\n* `'PHONE_NUMBER_TOO_LONG'`\n* `'PHONE_NOT_A_NUMBER'`\n* `'PHONE_TOO_SHORT_AFTER_IDD'`\n\n##### Examples\n\n```javascript\nphoneHandler.parsePhoneNumber('5101234567', 'US');\n// \u003e { countryCode: '1', nationalNumber: '5101234567' }\n\nphoneHandler.parsePhoneNumber('ABC', 'US');\n// \u003e [Error: PHONE_NOT_A_NUMBER]\n\n// regionCode is optional if string has '+' followed by country code\nphoneHandler.parsePhoneNumber('+1 510-123-4567'); // international format\nphoneHandler.parsePhoneNumber('+15101234567'); // E.164 format\nphoneHandler.parsePhoneNumber('tel:+1-510-123-4567'); // RFC 3966 format\n// \u003e { countryCode: '1', nationalNumber: '5101234567' }\n\n// Do not omit regionCode if phoneNumberString is missing '+'\nphoneHandler.parsePhoneNumber('15101234567');\n// \u003e [Error: PHONE_INVALID_COUNTRY_CODE]\nh.parsePhoneNumber(\"15101234567\", \"US\");\n// \u003e { countryCode: '1', nationalNumber: '5101234567' }\n```\n\n#### getExampleNumberForType\n\n##### `phoneHandler.getExampleNumberForType(type, regionCode)`\n\nReturn an example [`phoneObj` object](#canonical-phone-object), given the string parameters `type` and `regionCode`.\n\nThe `type` parameter is an enum based on libphonenumber [i18n.phonenumbers.PhoneNumberType](https://github.com/googlei18n/libphonenumber/blob/b58ef8b8a607074845534cb2ebe19b208521747f/javascript/i18n/phonenumbers/phonenumberutil.js#L907-L941) and can be any of the following strings:\n\n* `'FIXED_LINE'`\n* `'MOBILE'`\n* `'FIXED_LINE_OR_MOBILE'`\n* `'TOLL_FREE'`\n* `'PREMIUM_RATE'`\n* `'SHARED_COST'`\n* `'VOIP'`\n* `'PERSONAL_NUMBER'`\n* `'PAGER'`\n* `'UAN'`\n* `'VOICEMAIL'`\n* `'UNKNOWN'`\n\n##### Example\n\n```javascript\nphoneHandler.getExampleNumberForType('MOBILE', 'US');\n// \u003e { countryCode: '1', nationalNumber: '2015550123' }\n```\n\n#### inferPhoneNumberType\n\n##### `phoneHandler.inferPhoneNumberType(phoneObj)`\n\nReturn a string indicating the phone number type (see [`getExampleNumberForType`](#getexamplenumberfortype)), given a valid `phoneobj`. Returns `'UNKNOWN'` if metadata has not been loaded for the region of the phone number or the number type otherwise cannot be inferred.\n\n##### Examples\n\n```js\nphoneHandler.inferPhoneNumberType({ countryCode: '1', nationalNumber: '5105261568' });\n// \u003e 'FIXED_LINE_OR_MOBILE'\n\n// GB landline\nphoneHandler.inferPhoneNumberType({ countryCode: '44', nationalNumber: '1212345678' });\n// \u003e 'FIXED_LINE'\n\n// GB mobile number\nphoneHandler.inferPhoneNumberType({ countryCode: '44', nationalNumber: '7400123456' })\n// \u003e 'MOBILE'\n\n// invalid GB phone number\nphoneHandler.inferPhoneNumberType({ countryCode: '44', nationalNumber: '999999' });\n// \u003e 'UNKNOWN'\n```\n\n#### inferPhoneNumberRegion\n\n##### `phoneHandler.inferPhoneNumberRegion(phoneObj)`\n\nReturn the two letter region code associated with a valid `phoneObj`.\n\nReturns `null` if the region cannot be determined. (This can happen if metadata has not been loaded for the region associated with the `phoneObj.countryCode`.)\n\n**Important:** This method only guarantees correct results for **valid** phone numbers. ([See the libphonenumber source code.](https://github.com/google/libphonenumber/blob/5c309c56a945ffdf74f69aa4166b1ec5d7f233ff/javascript/i18n/phonenumbers/phonenumberutil.js#L3104-L3107))\n\n```javascript\nphoneHandler.inferPhoneNumberRegion({ countryCode: '44', nationalNumber: '1212345678' });\n// \u003e 'GB'\n\nphoneHandler.inferPhoneNumberRegion({ countryCode: '99', nationalNumber: '1212345678' });\n// \u003e null\n```\n\n#### getAsYouTypeFormatter\n\n##### `phoneHandler.getAsYouTypeFormatter(regionCode)`\n\nReturn a new AsYouTypeFormatter object instantiated for the given `regionCode`.\n\n##### Example\n\n```javascript\nvar formatter = phoneHandler.getAsYouTypeFormatter('GB');\n// \u003e AsYouTypeFormatter object initialized to Great Britain\n```\n\n#### AsYouTypeFormatter methods\n\nThe initialized AsYouTypeFormatter object itself exposes the following methods:\n\n##### inputDigit\n\n###### `formatter.inputDigit(digit)`\n\nGiven a digit (number or string), output the phone number formatted thus far (given the history of inputted digits).\n\nNote that `digit` can also be `'+'` or `'*'`\n\n###### Example\n\n```javascript\nformatter.inputDigit('5'); // \u003e '5'\nformatter.inputDigit('1'); // \u003e '51'\nformatter.inputDigit('0'); // \u003e '510'\nformatter.inputDigit('1'); // \u003e '510-1'\nformatter.inputDigit('2'); // \u003e '510-12'\nformatter.inputDigit('3'); // \u003e '510-123'\nformatter.inputDigit('4'); // \u003e '510-1234'\nformatter.inputDigit('5'); // \u003e '(510) 123-45'\nformatter.inputDigit('6'); // \u003e '(510) 123-456'\nformatter.inputDigit('7'); // \u003e '(510) 123-4567'\n```\n\n##### clear\n\n###### `formatter.clear()`\n\nClear the formatter state.\n\n###### Example\n\n```javascript\nformatter.inputDigit('5'); // \u003e '5'\nformatter.inputDigit('1'); // \u003e '51'\nformatter.inputDigit('0'); // \u003e '510'\nformatter.inputDigit('1'); // \u003e '510-1'\nformatter.inputDigit('2'); // \u003e '510-12'\nformatter.clear();\nformatter.inputDigit('9'); // \u003e '9'\nformatter.inputDigit('1'); // \u003e '91'\nformatter.inputDigit('9'); // \u003e '919'\nformatter.inputDigit('4'); // \u003e '919-4'\nformatter.inputDigit('8'); // \u003e '919-48'\n...\n```\n\n##### inputDigitAndRememberPosition\n\n###### `formatter.inputDigitAndRememberPosition(digit)`\n\nSame as [inputDigit](#inputdigit), but remembers the (1-indexed) position where the digit was entered, to be retrieved later by [getRememberedPosition](#getrememberedposition). This position can update as formatting characters are inserted by the AsYouTypeFormatter.\n\n##### getRememberedPosition\n\n###### `formatter.getRememberedPosition()`\n\nReturns the (1-indexed) position (as a number) of the digit previously passed to [inputDigitAndRememberPosition](#inputdigitandrememberposition).\n\n###### Example\n\n```javascript\n// getRememberedPosition starts out as 0\nformatter.getRememberedPosition(); // \u003e 0\n\nformatter.inputDigitAndRememberPosition(5); // \u003e '5'\n\n// the 5 was inputted at position 1\nformatter.getRememberedPosition(); // \u003e 1\n\n// input additional digits until parens are inserted\nformatter.inputDigit(1); // \u003e '51'\nformatter.inputDigit(0); // \u003e '510'\nformatter.inputDigit(1); // \u003e '510-1'\nformatter.inputDigit(2); // \u003e '510-12'\nformatter.inputDigit(3); // \u003e '510-123'\nformatter.inputDigit(4); // \u003e '510-1234'\nformatter.inputDigit(5); // \u003e '(510) 123-45'\n\n// now the original 5 is at position 2, since an open paren was inserted before it\nformatter.getRememberedPosition(); // 2\n```\n\nDevelopment\n------------\n\nsee [DEVELOPMENT.md](./reference/DEVELOPMENT.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Ffullstack-phone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaypal%2Ffullstack-phone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaypal%2Ffullstack-phone/lists"}