ts-countries

A modern TypeScript library for managing and retrieving comprehensive country data with a simple and intuitive API.

Features

• 🌍 Comprehensive Data Extensive country info including names, codes, currencies, languages, and more
• 🔍 Smart Search Powerful filtering and search capabilities
• 🌐 i18n Ready Support for multiple languages and translations
• 💪 Type-Safe Full TypeScript support with comprehensive type definitions
• 🎯 ISO Compliant Implements ISO 3166-1 standards for country codes
• 🧪 Well-Tested Comprehensive test suite ensuring reliability
• 📦 Zero Dependencies Lightweight and self-contained
• 🔄 Caching Built-in caching system for optimal performance

Installation

# Using npm
npm install ts-countries

# Using yarn
yarn add ts-countries

# Using pnpm
pnpm add ts-countries

# Using bun
bun add ts-countries

Usage

Basic Usage

import { countries, country } from 'ts-countries'

// Get a single country
const usa = country('US')
console.log(usa.getName()) // Returns 'United States'
console.log(usa.getIsoAlpha2()) // Returns 'US'
console.log(usa.getIsoAlpha3()) // Returns 'USA'

// Get all countries
const allCountries = countries()

// Get detailed country list
const detailedCountries = countries(true) // longlist format

// Get hydrated Country instances
const countryInstances = countries(false, true) // returns Country[]

Advanced Usage

import { Country, CountryLoader } from 'ts-countries'

// Working with country data
const usa = country('US')

// Access various country properties
console.log(usa.getCapital()) // Get capital city
console.log(usa.getCurrencies()) // Get currency information
console.log(usa.getLanguages()) // Get official languages
console.log(usa.getTimezones()) // Get timezone information
console.log(usa.getGeodata()) // Get geographic data

// Get translations
console.log(usa.getTranslations()) // Get all translations
console.log(usa.getTranslation('fra')) // Get French translation

// Working with native names
console.log(usa.getNativeName()) // Get native name
console.log(usa.getNativeNames()) // Get all native names

// Geographic information
console.log(usa.getRegion()) // Get region
console.log(usa.getSubregion()) // Get subregion
console.log(usa.getContinent()) // Get continent
console.log(usa.getBorders()) // Get bordering countries

// Additional metadata
console.log(usa.getDemonym()) // Get demonym
console.log(usa.getCallingCode()) // Get calling code
console.log(usa.getTld()) // Get top-level domain

Filtering Countries

import { CountryCollection } from 'ts-countries'

const collection = new CountryCollection(countries(false, true))

// Filter by region
const europeanCountries = collection.where('geo.region', 'Europe')

// Filter by currency
const euroCountries = collection.where('currency.EUR')

// Filter using comparison operators
const largeCountries = collection.where('geo.area', '>', 1000000)

// Complex filtering
const northAmericanEnglishSpeaking = collection
  .where('geo.subregion', 'North America')
  .where('languages.eng', 'English')

API Reference

Main Classes

Country

Represents a single country with comprehensive data and helper methods.

CountryLoader

Static class for loading country data with built-in caching.

CountryCollection

Collection class for working with multiple countries and filtering.

Key Methods

Country Class Methods

• getName(): Get country name
• getOfficialName(): Get official country name
• getNativeName(languageCode?): Get native name
• getIsoAlpha2(): Get ISO 3166-1 alpha-2 code
• getIsoAlpha3(): Get ISO 3166-1 alpha-3 code
• getIsoNumeric(): Get ISO 3166-1 numeric code
• getCurrencies(): Get currency information
• getLanguages(): Get official languages
• And many more...

CountryLoader Methods

• country(code: string, hydrate?: boolean): Load single country
• countries(longlist?: boolean, hydrate?: boolean): Load all countries
• where(key: string, operator: string, value?: any): Filter countries

Error Handling

The library throws descriptive exceptions for various error conditions:

• Invalid Country Code: When a country code doesn't exist
• Missing Data: When required country data is missing
• Invalid Format: When data format is incorrect

Contributing

Please see CONTRIBUTING for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Credits

• Rinvex for the original PHP library
• Chris Breuer for the TypeScript conversion

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙