README.md

📞 @worldkit/phone

Fast international phone code lookup, E.164 validation, and formatting library for JavaScript & TypeScript.

Lookup country dial codes, expected mobile lengths, validate E.164 phone numbers, and format numbers cleanly.

📚 Full Documentation: https://worldkit.in/docs/phone

---

⚡ Features

• ☎️ International Calling Codes: Get dial codes for 250+ countries (e.g. "IN" -> 91, "US" -> 1).
• 🛡️ Phone Length & Pattern Validation: Check mobile digit lengths and ITU E.164 specifications.
• 🎨 Clean Formatting: Formats phone numbers into standard readable international formats.
• ⚡ Zero Heavy RegEx Engine: Extremely fast (<0.01ms) suitable for Cloudflare Workers & High-Traffic APIs.
• 📦 Tiny Size: ~1.4 KB gzipped with zero external runtime dependencies.

---

📦 Install

npm install @worldkit/phone
# or
pnpm add @worldkit/phone
# or
yarn add @worldkit/phone

---

💡 Usage

import {
  phoneCode,
  mobileLength,
  validatePhone,
  formatPhone
} from "@worldkit/phone";

// 1. Get Country Phone Dial Code
console.log(phoneCode("IN")); // 91
console.log(phoneCode("US")); // 1
console.log(phoneCode("JP")); // 81

// 2. Get Expected Mobile Length
console.log(mobileLength("IN")); // 10
console.log(mobileLength("JP")); // 10

// 3. Validate International Phone Numbers
console.log(validatePhone("+919876543210", "IN")); // true
console.log(validatePhone("+14155552671", "US"));  // true
console.log(validatePhone("12345", "IN"));         // false

// 4. Format Phone Numbers
console.log(formatPhone("9876543210", "IN"));  // "+91 98765 43210"
console.log(formatPhone("+819012345678", "JP")); // "+81 9012345678"

---

📖 API Reference

phoneCode(countryIso2: string): number | undefined

Returns the international calling code (e.g. 91 for "IN").

mobileLength(countryIso2: string): number | undefined

Returns the expected number of mobile digits for that country.

validatePhone(phone: string, countryIso2?: string): boolean

Validates whether a phone string conforms to international length and calling prefix rules.

formatPhone(phone: string, countryIso2?: string): string

Formats raw digits into formatted E.164 phone string.

---

📐 TypeScript Support

Written in 100% strict TypeScript with built-in export signatures.

---

🔗 Related Packages

Explore the rest of the WorldKit ecosystem:

• @worldkit/core - Unified global data toolkit.
• @worldkit/countries - 250+ country dataset.
• @worldkit/validators - Phone, EU VAT & Postal code validators.
• @worldkit/formatters - Phone, Address & Currency formatters.

---

📜 License

MIT © WorldKit