包详细信息

ddi-country-data

amomvga901MIT1.2.0

TypeScript library mapping DDI codes to country data (names, flags, masks)

ddi, country, phone, flag

自述文件

ddi-country-data

Lightweight TypeScript library mapping international dialing codes (DDI) to country data including name, flag, continent, and phone number mask.

✨ Features

  • 🔍 Advanced search by DDI, country name (PT/EN), or continent (PT/EN)
  • 🔢 Exact DDI lookup
  • 🏳️‍🌈 Flag via image URL
  • 🌍 Country name and continent in Portuguese (pt-BR) and English (en)
  • 📏 Configurable phone number mask
  • 🛡️ Zero external dependencies
  • 📦 Lightweight (~70 kB)

🚀 Installation

# Yarn
yarn add ddi-country-data

# npm
npm install ddi-country-data

📚 Quick Usage

Exact DDI lookup

import { getCountryByDDI } from 'ddi-country-data';

const countryData = getCountryByDDI(55);
console.log(countryData);
/*
{
  ddi: '55',
  countryPt: 'Brasil',
  countryEn: 'Brazil',
  img: 'https://.../Flag_of_Brazil.svg',
  continentPt: 'América',
  continentEn: 'Americas',
  mask: '+55 (##) #####-####'
}
*/

Advanced multi-field search

import { searchDDI } from 'ddi-country-data';

// Search by country name (any language)
const results1 = searchDDI('Estados', 5); // up to 5 matches containing 'Estados'

// Search by continent
const americanCountries = searchDDI('América');

// Search by DDI
const ddiResults = searchDDI('1', 3); // up to 3 countries with DDI 1

// Mixed search (any field)
const globalResults = searchDDI('uni', 10); // searches across all fields

Accessing raw dataset

import { ddiData } from 'ddi-country-data';
console.log(ddiData[0]); // First entry in dataset

🧩 API

getCountryByDDI(ddi: string | number): CountryInfo | null

Returns a CountryInfo object for the given DDI or null if not found.

searchDDI(query: string | number, limit: number = 10): CountryInfo[]

Returns an array of CountryInfo objects matching the query in:

  • DDI code
  • Country name (Portuguese or English)
  • Continent (Portuguese or English)

The limit parameter controls the maximum number of results (default: 10).

ddiData: CountryInfo[]

Full dataset for direct access or custom processing.

🔧 Interface CountryInfo

export interface CountryInfo {
  ddi: string; // DDI code (e.g. '55')
  countryPt: string; // Country name in Portuguese
  countryEn: string; // Country name in English
  img: string; // Flag image URL
  continentPt: string; // Continent in Portuguese
  continentEn: string; // Continent in English
  mask: string; // Phone number format mask
}

🔍 Search Behavior

  • Multi-language: matches in both Portuguese and English fields.
  • Partial matches: returns entries containing the search term.
  • Case-insensitive: ignores letter casing.
  • Automatic '+' handling: searches for DDI treat '+' prefix optionally.
  • Limit control: returns up to the specified number of results.

🗺️ Roadmap

  • Support for ISO 3166-1 country codes
  • Phone number formatting utilities
  • Improved search relevance scoring
  • Accent-insensitive search
  • Community contributions for additional masks or regional adjustments

🛠️ Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/your-feature
  3. Commit changes: git commit -m 'Add feature X'
  4. Push to remote: git push origin feature/your-feature
  5. Open a Pull Request describing changes and rationale.

Feel free to open issues for bugs, suggestions, or improvements.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

👤 Author

Created by Amom Augusto