{"id":20516173,"url":"https://github.com/aftership/phone","last_synced_at":"2025-05-13T18:14:34.047Z","repository":{"id":9576874,"uuid":"11491572","full_name":"AfterShip/phone","owner":"AfterShip","description":"With a given country and phone number, validate and reformat the mobile phone number to the E.164 standard. The purpose of this is to allow us to send SMS to mobile phones only.","archived":false,"fork":false,"pushed_at":"2025-04-17T14:26:07.000Z","size":1892,"stargazers_count":891,"open_issues_count":0,"forks_count":282,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-05-12T06:05:47.870Z","etag":null,"topics":["e164","mobile","phone","phone-number","sms"],"latest_commit_sha":null,"homepage":"https://www.aftership.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AfterShip.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2013-07-18T01:31:24.000Z","updated_at":"2025-05-07T19:08:29.000Z","dependencies_parsed_at":"2023-02-15T14:05:35.552Z","dependency_job_id":"a3d5ae7c-65ed-4545-8023-f0d072728bc7","html_url":"https://github.com/AfterShip/phone","commit_stats":{"total_commits":439,"total_committers":99,"mean_commits":4.434343434343434,"dds":0.6104783599088839,"last_synced_commit":"c101e5116ed31068b6fe29a541da6c4d02334b19"},"previous_names":[],"tags_count":128,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fphone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fphone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fphone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AfterShip%2Fphone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AfterShip","download_url":"https://codeload.github.com/AfterShip/phone/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253891783,"owners_count":21979856,"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":["e164","mobile","phone","phone-number","sms"],"created_at":"2024-11-15T21:27:07.583Z","updated_at":"2025-05-13T18:14:34.016Z","avatar_url":"https://github.com/AfterShip.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phone \u0026middot; [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FAfterShip%2Fphone.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FAfterShip%2Fphone?ref=badge_shield)\n\n## What is phone?\n`phone` is used to normalize mobile phone numbers into E.164 format.\n\nA common problem is that users normally input phone numbers in this way:\n\n```\n`(817) 569-8900` or\n`817569-8900` or\n`1(817) 569-8900` or\n`+1(817) 569-8900` or ...\n```\n\nWe always want:\n\n```\n+18175698900\n```\n\n## Install\n```\nnpm install phone\n\n// or\n\nyarn add phone\n```\n\n## Usage\n\n```javascript\nconst {phone} = require('phone');\n\n// or\n\nimport {phone} from 'phone';\n```\n\n### 1. Simple usage\n\n```javascript\nphone('+852 6569-8900');\n// { isValid: true, phoneNumber: '+85265698900',  countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n```\n\n### 2. With Country\n\n```javascript\nphone('+1(817) 569-8900', {country: ''}); \n// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1'}\n\nphone('(817) 569-8900', {country: 'USA'});\n// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1'}\n\nphone('(817) 569-8900', {country: 'HKG'});\n// { isValid: false }\n// not a valid HKG mobile phone number\n\nphone('+1(817) 569-8900', {country: 'HKG'});\n// { isValid: false }\n// not a valid HKG mobile phone number\n\nphone('6123-6123', {country: 'HKG'});\n// { isValid: true, phoneNumber: '+85261236123', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n```\n\n### 3. Without country code and no phone prefix\n\nIf both country code and country phone prefix are not provided, the phone number will be treated as USA or Canada by default.\n\n```javascript\nphone('(817) 569-8900');\n// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1' }\n\nphone('(817) 569-8900', {country: ''});\n// { isValid: true, phoneNumber: '+18175698900', countryIso2: 'US', countryIso3: 'USA', countryCode: '+1' }\n\nphone('780-569-8900', {country: null});\n// { isValid: true, phoneNumber: '+17805698900', countryIso2: 'CA', countryIso3: 'CAN', countryCode: '+1' }\n// 780 is a Canada phone prefix\n\nphone('6123-6123', {country: null});\n// { isValid: false }\n// as default country is USA / CAN and the phone number does not fit such countries' rules\n```\n\n### 4. With country code / phone prefix, but no `+` sign\n\nEven you input a valid phone number with a valid prefix, if there is no plus sign, it will not work as expected:\n\n```javascript\nphone('85291234567');\n// or\nphone('85291234567', {country: null});\n\n// { isValid: false }\n```\n\n`852` is a valid Hong Kong phone prefix, and `91234567` is a valid Hong Kong mobile phone number.\nHowever, there is no plus sign provided, the module will assume the phone number is a USA or Canada phone number, \nhence no result will be found.   \n\nIf you know you have provided country phone prefix, make sure you also provide a plus sign:\n\n```javascript\nphone('+85291234567');\n// or\nphone('+85291234567', {country: null});\n\n// { isValid: true, phoneNumber: '+85291234567', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n```\n\nor, if you know the country, and only want to reformat the phone number to E.164 format:\n\n```javascript\nphone('91234567',  {country: 'HKG'})\n// { isValid: true, phoneNumber: '+85291234567', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n```\n\n### 5. Skipping phone number initial digit checking\n\nIf you want to skip phone number initial digit checking, set `validateMobilePrefix` to false:\n\n```javascript\nphone('+(852) 2356-4902');\n// { isValid: false }\n// '2' is a Hong Kong landline phone number prefix, not a valid mobile phone number prefix\n\nphone('+(852) 2356-4902', {validateMobilePrefix: true});\n// { isValid: false }\n// same as above, default value of validateMobilePrefix = true\n\nphone('+(852) 2356-4902', {validateMobilePrefix: false});\n// { isValid: true, phoneNumber: '+85223564902', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n// skipping mobile prefix checking\n```\n\nWith `validateMobilePrefix` set to `false`, the initial digit checking logic will be disabled completely, even you enter a phone number start with a non-exist digit:\n\n```javascript\nphone('+(852) 0356-4902', {validateMobilePrefix: false});\n// { isValid: true, phoneNumber: '+85203564902', countryIso2: 'HK', countryIso3: 'HKG', countryCode: '+852' }\n// even the phone number start with `0` is not a valid landline phone number\n```\nNote that the module does not have the capability to determine if the prefix is a valid `landline` prefix number.\n\n### 6. Trunk Code Detection Logic\n\nFor some phone numbers, such as this sample UK phone number:\n\n```\n+44 07911 123456\n```\n\nThere is a trunk code `0` after the country code `+44` so that it is unable to match any correct country.\n\nHence the module will try to remove 1 digit after the country code,\n\nand try to detect:\n\n```\n+44 7911 123456\n```\n\nand it would become a valid UK phone number now.\n\n```javascript\nphone('+4407911 123456')\n// { isValid: true, phoneNumber: '+447911123456', countryIso2: 'GB', countryIso3: 'GBR', countryCode: '+44' }\n```\n\nIf you want to disable this behavior, \nplease set `strictDetection` to `true`:\n\n```javascript\nphone('+4407911 123456', {strictDetection: true})\n// { isValid: false }\n```\n\n## API\n\n```typescript\nconst {phone} = require('phone');\n\n// or\n\nimport {phone} from 'phone';\n\nphone(phoneNumber: string, { country, validateMobilePrefix, strictDetection }?: {\n    country?: string;\n    validateMobilePrefix?: boolean;\n    strictDetection?: boolean;\n})\n```\n\n#### Input\n\nParameter | Type | Required | Default | Description\n--- | --- | --- | --- | ---\nphoneNumber | String | Yes | - | The phone number text you want to process\ncountry | String | No | null | Provided country code in iso-3166 alpha 2 or 3 format\nvalidateMobilePrefix | Boolean | No | true | Set to false if you want to skip phone number initial digit checking\nstrictDetection | Boolean | No | false | Set to true if you want to disable trunk code detection logic. \n\n#### Returns\n\n```typescript\ntype PhoneResult = PhoneInvalidResult | PhoneValidResult;\n\ninterface PhoneValidResult {\n\tisValid: true;\n\tphoneNumber: string;\n\tcountryIso2: string;\n\tcountryIso3: string;\n\tcountryCode: string;\n}\n\ninterface PhoneInvalidResult {\n\tisValid: false;\n\tphoneNumber: null;\n\tcountryIso2: null;\n\tcountryIso3: null;\n\tcountryCode: null;\n}\n```\n\nParameter | Type | Description\n--- | --- | ---\nisValid | Boolean | To indicate if the result valid\nphoneNumber | String or null | Normalized phone number in E.164 format\ncountryIso2 | String or null | Detected phone number country code in iso-3166 alpha 2 format\ncountryIso3 | String or null | Detected phone number country code in iso-3166 alpha 3 format\ncountryCode | String or null | Detected phone number country calling code with `+` sign\n\n[comment]: \u003c\u003e (## Demo)\n\n[comment]: \u003c\u003e ([Try it on CodeSandbox]\u0026#40;https://codesandbox.io/s/phone-browser-example-react-o5vt5?file=/src/App.js\u0026#41;)\n\n## Test\n\n```\nyarn test\n```\n\n## Interactive Web Example \n\n```\nyarn start:example\n```\n\nor \n\n```\nyarn dev\n```\n\nAnd then visit http://localhost:8080\n\n## Build\n\n```\nyarn build\n```\n\n[comment]: \u003c\u003e (## Supported Environment)\n\n[comment]: \u003c\u003e (We currently transpile script to work on target environments for which the browser's global usage is \u003e1%, and Node.js 6.10+.)\n\n[comment]: \u003c\u003e (You can check browser usage statistics on the [browserlist]\u0026#40;http://browserl.ist/?q=%3E1%25\u0026#41;.)\n\n[comment]: \u003c\u003e (You may need polyfills for some older browsers; for more details, please read the `example/README` file.)\n\n\n## FAQ\n\n1. Does `phone` do any logical validation?\n\n\tYes. If you provide `country`, and the phone number does not start with `+` sign,\n\n\tthe module will validate `phone_number_lengths` and `mobile_begin_with`\n\n2. Why is `phone` returning an invalid result for a valid phone number?\n\n\tBy default, the function will validate a mobile phone number only, to validate a landline phone number, please set `validateMobilePrefix` to `false`.\n\n\tIf you find the result is still incorrect, please submit a ticket to improve our validation rules.\n\n3. Why is `phone` returning an object with `isValid = false` instead of returning a null directly?\n\n    It reserves the flexibility to extend the response interface for invalid results in the future.\n\n## Migrate from v2\n\nThe interface of v3 has been changed for better usability, maintainability, and flexibility, this shows all the changes from v2:\n\n#### Function Interface\n\nVersion | Interface\n--- | ---\nv2 | phone(phoneNumber, country, allowLandline) \nv3 | phone(phoneNumber,{country: String, validateMobilePrefix: Boolean, strictDetection: Boolean})\n\n#### Function Response\n\nVersion | Result | Interface\n--- | --- | ---\nv2 | - | [phoneNumber, country]\nv3 | Valid | {isValid: true, phoneNumber: string, countryIso2: string, countryIso3: string, countryCode: string}\nv3 | Invalid | {isValid: false, phoneNumber: null, countryIso2: null, countryIso3: null, countryCode: null}\n\n#### allowLandline vs validateMobilePrefix\n\n`allowLandline` in v2 is essentially equal to `validateMobilePrefix` in v3, however, the value is the opposite.\n\nBecause `allowLandline = true` in v2 means \"Skip the mobile phone number prefix validation\", and there is NO capability to verify if the input phone number is a valid landline phone number.\n\nTo avoid misleading information, the parameter name has been changed to `validateMobilePrefix`, and the input value is the opposite, while `validateMobilePrefix = false` means \"Skip the mobile phone number prefix validation\".\n\n\n## Phone Number Format Improvement\n\nWe strive to ensure this package functions well across diverse scenarios. However, please note that the phone number formats may not be updated proactively or regularly, as this is a manual task and we lack a dedicated incentive for continuous updates. If you find any incorrect rules for a country or other specific case, please create a pull request to inform us.\n\nWhen submitting pull requests to add or modify phone number formats, it is essential to include reference information such as PDFs, websites, etc. **PRs submitted without references will not be accepted.** Thank you for your understanding and cooperation.\n\n**The library supports mobile phone number format only.** We are unable to provide landline phone number support as we do not have landline phone number format data, hence we do not accept PRs for landline phone numbers.\n\n## License\n\nThis project is licensed under the [MIT license](https://github.com/AfterShip/phone/blob/master/LICENSE).\n\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FAfterShip%2Fphone.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FAfterShip%2Fphone?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faftership%2Fphone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faftership%2Fphone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faftership%2Fphone/lists"}