📞 Phone Utils

A lightweight and fully TypeScript-ready utility library for phone number parsing, formatting, and country detection. Handles tricky scenarios like shared country codes (e.g., +1, +44, +7) and dependencies (UK Crown dependencies, US territories, Canadian area codes).

Features

• Parse phone numbers into country, calling code, national number, and formatted string.

• Detect countries with shared dialing codes:

  • +1 → US, Canada, Puerto Rico, Caribbean nations
  • +44 → UK, Isle of Man, Jersey, Guernsey
  • +7 → Russia, Kazakhstan
  • +672 → Australian territories

• Format phone numbers dynamically with custom group sizes and separators:

  • Separators: space ( ), dash (-), parentheses (())

• Fully TypeScript-ready with types and interfaces

• Minimal dependency-free footprint

Installation

npm install tele_number_utils
# or
yarn add tele_number_utils

Usage

Parsing Phone Numbers

import { parsePhoneNumber } from "tele_number_utils";

const parsed = parsePhoneNumber("+14165551234");
console.log(parsed);
/*
{
  country: "CA",
  callingCode: "1",
  nationalNumber: "4165551234",
  formatted: "+1 4165551234"
}
*/

Detecting Country from Number

import { getCountry } from "tele_number_utils";

console.log(getCountry("+12015551234")); // US
console.log(getCountry("+14165551234")); // Canada
console.log(getCountry("+17875551234")); // Puerto Rico
console.log(getCountry("+442071234567")); // United Kingdom
console.log(getCountry("+441632960123")); // Isle of Man
console.log(getCountry("+79161234567")); // Russia
console.log(getCountry("+76171234567")); // Kazakhstan

interface Country {
  name: string;
  dialingCode: string;
  flagUrl: string;
  alphaTwoCode: string;
}

Formatting Numbers

import { formatter } from "tele_number_utils";

// Default grouping [3,3,4]
console.log(formatter("+12345678901")); // "+1 234 567 8901"

// Custom grouping with dash separator
console.log(formatter("+123456789012345", [4, 4, 4, 4], "-")); // "+1 2345-6789-0123-45"

// Parentheses style
console.log(formatter("+12345678901", [3, 3, 4], "()")); // "(+1) 234 567 8901"

// Short numbers <= 6 digits remain unchanged
console.log(formatter("12345")); // "12345"

Live Console Demo

import { getCountry } from "tele_number_utils";

const testNumbers = [
  "+12015551234", // US
  "+14165551234", // Canada
  "+17875551234", // Puerto Rico
  "+442071234567", // UK main
  "+441632960123", // Isle of Man
  "+441534123456", // Jersey
  "+441481987654", // Guernsey
  "+79161234567", // Russia
  "+76171234567", // Kazakhstan
  "+67212345678", // Australian territory
  "+919876543210", // India
  "+4915123456789", // Germany
  "4915123456789", // Missing +
  "+999123456789", // Unknown
];

console.log("===== Phone Number Country Detection =====");
for (const number of testNumbers) {
  const country = getCountry(number);
  console.log(`${number} =>`, country);
}

Sample Output:

+12015551234 => United States
+14165551234 => Canada
+17875551234 => Puerto Rico
+442071234567 => United Kingdom
+441632960123 => Isle of Man
+441534123456 => Jersey
+441481987654 => Guernsey
+79161234567 => Russia
+76171234567 => Kazakhstan
+67212345678 => Australia
+919876543210 => India
+4915123456789 => Germany
4915123456789 => Invalid Phone number
+999123456789 => Country not found

API

parsePhoneNumber(phone: string): ParsedPhoneNumber

Parses a phone number string into:

interface ParsedPhoneNumber {
  country?: string; // ISO Alpha-2 country code
  callingCode?: string; // Dialing code
  nationalNumber?: string;
  formatted?: string; // Formatted string
}

getCountry(number: string): Country | string

Returns country information for a given number:

interface Country {
  name: string;
  dialingCode: string;
  flagUrl: string;
  alphaTwoCode: string;
}

Returns "Invalid Phone number" or "Country not found" for invalid/unknown numbers.

formatter(value: string, groupSizes?: number[], separator?: " " | "-" | "/" | "()"): string

Formats digits into custom groups.

• groupSizes – array of numbers specifying group lengths, default [3,3,4]
• separator – separator between groups, default " "

import { country_list } from "tele_number_utils";

console.log(country_list[0]);
/*
{
  name: "United States",
  dialingCode: "1",
  flagUrl: "https://flagcdn.com/us.svg",
  alphaTwoCode: "US"
}
*/

Contributing

Feel free to open an issue or PR to improve country detection, formatting options, or add more NANPA countries.

☕ Support the Project

If this package helps you, you can support my work ❤️

• Payoneer Email: [email protected]

(Thank you for your support 🙏)

License

MIT