or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

examples-formatting.mdfinding.mdindex.mdnumber-from.mdparsing.mdregion-utilities.md
tile.json

tessl/npm-awesome-phonenumber

Google's libphonenumber pre-compiled with the closure compiler for comprehensive phone number parsing, validation, and formatting.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/awesome-phonenumber@7.5.x

To install, run

npx @tessl/cli install tessl/npm-awesome-phonenumber@7.5.0

index.mddocs/

Awesome PhoneNumber

Awesome PhoneNumber is a pre-compiled TypeScript/JavaScript library wrapping Google's libphonenumber with a simplified interface. It provides comprehensive phone number parsing, validation, formatting, and finding capabilities with zero runtime dependencies and optimal performance.

Package Information

  • Package Name: awesome-phonenumber
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install awesome-phonenumber

Core Imports

import { 
  parsePhoneNumber, 
  findNumbers, 
  getExample, 
  getAsYouType,
  getNumberFrom,
  getCountryCodeForRegionCode,
  getRegionCodeForCountryCode,
  getSupportedCallingCodes,
  getSupportedRegionCodes
} from "awesome-phonenumber";

For CommonJS:

const { 
  parsePhoneNumber, 
  findNumbers, 
  getExample, 
  getAsYouType,
  getNumberFrom,
  getCountryCodeForRegionCode,
  getRegionCodeForCountryCode,
  getSupportedCallingCodes,
  getSupportedRegionCodes
} = require("awesome-phonenumber");

Basic Usage

import { parsePhoneNumber, findNumbers } from "awesome-phonenumber";

// Parse phone numbers
const phoneNumber = parsePhoneNumber("0707123456", { regionCode: "SE" });
// Or international format
const intlNumber = parsePhoneNumber("+46707123456");

if (phoneNumber.valid) {
  console.log(phoneNumber.number.international); // "+46 70 712 34 56"
  console.log(phoneNumber.type); // "mobile"
}

// Find phone numbers in text
const matches = findNumbers("Call me at 0707123456 or +1-555-123-4567", {
  defaultRegionCode: "SE"
});
console.log(matches.length); // 2

// Short number validation (emergency numbers, service codes)
const emergency = parsePhoneNumber("112", { regionCode: "SE" });
console.log(emergency.valid);      // false (not a regular phone number)
console.log(emergency.shortValid); // true (valid emergency number)

Architecture

Awesome PhoneNumber is built around several key components:

  • Core Parser: Primary parsePhoneNumber function for converting strings to structured phone number objects
  • Text Scanner: findNumbers function for extracting phone numbers from unstructured text
  • Short Number Support: Built-in validation for emergency numbers, service codes, and special numbers
  • Region Utilities: Functions for working with country codes and region codes
  • Example Generator: getExample function for generating sample phone numbers
  • Incremental Formatter: AsYouType class for real-time formatting as users type
  • Type System: Complete TypeScript definitions with union types for valid/invalid results

Capabilities

Phone Number Parsing

Core parsing functionality for converting phone number strings into structured, validated objects with comprehensive metadata.

function parsePhoneNumber(
  phoneNumber: string,
  options?: PhoneNumberParseOptions
): ParsedPhoneNumber;

interface PhoneNumberParseOptions {
  regionCode?: string;
}

type ParsedPhoneNumber = ParsedPhoneNumberValid | ParsedPhoneNumberInvalid;

Phone Number Parsing

Phone Number Finding

Text scanning functionality to locate and extract phone numbers from unstructured text with configurable leniency and region settings.

function findNumbers(
  text: string,
  options?: FindNumbersOptions
): PhoneNumberMatch[];

interface FindNumbersOptions {
  defaultRegionCode?: string;
  leniency?: FindNumbersLeniency;
  maxTries?: number;
}

Phone Number Finding

Country and Region Code Utilities

Utilities for converting between country calling codes and ISO region codes, plus discovery of supported regions.

function getCountryCodeForRegionCode(regionCode: string): number;
function getRegionCodeForCountryCode(countryCode: number): string;
function getSupportedCallingCodes(): string[];
function getSupportedRegionCodes(): string[];

Country and Region Utilities

Example Generation and As-You-Type Formatting

Tools for generating example phone numbers and providing real-time formatting as users input phone numbers.

function getExample(regionCode: string, type?: PhoneNumberTypes): ParsedPhoneNumber;
function getAsYouType(regionCode: string): AsYouType;

class AsYouType {
  addChar(char: string): string;
  number(): string;
  removeChar(): string;
  reset(number?: string): string;
  getPhoneNumber(): ParsedPhoneNumber;
}

Examples and Formatting

Phone Number From Functionality

Utility for determining how a phone number would be dialed from a specific country, useful for international calling applications.

function getNumberFrom(
  parsedPhoneNumber: ParsedPhoneNumberValid,
  regionCode?: string
): PhoneNumberFrom;

type PhoneNumberFrom = PhoneNumberFromValid | PhoneNumberFromInvalid;

Phone Number From

Core Types

type PhoneNumberFormat = 'e164' | 'international' | 'national' | 'rfc3966' | 'significant';

type PhoneNumberTypes = 'fixed-line' | 'fixed-line-or-mobile' | 'mobile' | 'pager' 
  | 'personal-number' | 'premium-rate' | 'shared-cost' | 'toll-free' | 'uan' 
  | 'voip' | 'unknown';

type PhoneNumberPossibility = 'is-possible' | 'invalid' | 'invalid-country-code' 
  | 'too-long' | 'too-short' | 'unknown';

type FindNumbersLeniency = 'possible' | 'valid';

interface ParsedPhoneNumberValid {
  valid: true;
  number: {
    input: string;
    international: string;
    national: string;
    e164: string;
    rfc3966: string;
    significant: string;
  };
  possibility: PhoneNumberPossibility;
  regionCode: string;
  possible: boolean;
  shortValid: boolean;
  shortPossible: boolean;
  canBeInternationallyDialled: boolean;
  type: PhoneNumberTypes;
  countryCode: number;
  typeIsMobile: boolean;
  typeIsFixedLine: boolean;
}

interface ParsedPhoneNumberInvalid {
  valid: false;
  possible: boolean;
  possibility: PhoneNumberPossibility;
  shortValid: boolean;
  shortPossible: boolean;
  error?: unknown;
}