tessl/npm-awesome-phonenumber

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Awesome PhoneNumber

Name: tessl/npm-awesome-phonenumber
Author: tessl

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;
}

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/awesome-phonenumber@7.5.x
Publish Source: CLI
Badge