Countries Library

A comprehensive TypeScript library for country data collection and management. Provides easy access to country information including names, codes, flags, currencies, timezones, and more.

Features

✨ Complete Country Data: Access to 250+ countries with detailed information
🔍 Search & Filter: Powerful search and filtering capabilities
📄 Pagination Support: Built-in pagination with customizable options
🌍 Currency & Timezone Data: Complete currency and timezone information
🚩 Country Flags: Unicode flags and emoji support
📞 Dial Codes: International dialing codes
💪 Type-Safe: Full TypeScript support with comprehensive type definitions
🎯 Zero Dependencies: No external runtime dependencies

Installation

npm install countries-lib
# or
yarn add countries-lib
# or
pnpm add countries-lib

Usage

Basic Usage

import { Countries, Country } from 'countries-lib';

// Get all countries
const allCountries = Countries.getAll();

// Get a specific country
const usa = Countries.getOne({ code: 'US' });
console.log(usa?.title); // "United States of America"

// Search countries
const results = Countries.search({ search: 'united' });

// Get minimal country data
const minimalCountries = Countries.getAllMinimal();

Using the Country Class

import { Country } from 'countries-lib';

// Initialize with a country code
const country = new Country('US');

// Get country information
console.log(country.getCountryTitle()); // "United States of America"
console.log(country.getCountryDialCode()); // "+1"
console.log(country.getCountryEmoji()); // "🇺🇸"
console.log(country.getCountryCurrency()); // "USD"

// Chain methods for filtering
country.setSearch('united').setLimit(10).setPage(1);

const countries = country.getAllCountries();

Pagination

import { Countries } from 'countries-lib';

// Paginate countries with options
const paginated = Countries.paginate({
    page: 1,
    limit: 20,
    search: 'asia',
    sortBy: 'title',
    sortOrder: 'asc',
    baseUrl: '/api/countries',
});

console.log(paginated.data); // Array of countries
console.log(paginated.total); // Total count
console.log(paginated.hasNextPage); // Boolean
console.log(paginated.links); // Pagination links

Filtering Countries

import { Countries } from 'countries-lib';

// Include specific countries
const filtered = Countries.getAll({
    includedCodes: ['US', 'CA', 'MX'],
});

// Exclude specific countries
const filtered2 = Countries.getAll({
    excludedCodes: ['US', 'CA'],
});

// Both include and exclude
const filtered3 = Countries.getAll({
    includedCodes: ['US', 'CA', 'MX', 'GB'],
    excludedCodes: ['GB'],
});

Search Options

import { Countries } from 'countries-lib';

// Search by name
const byName = Countries.search({ search: 'united' });

// Search by dial code
const byDialCode = Countries.search({ dialCode: '+1' });

// Search by country code
const byCode = Countries.search({ countryCode: 'US' });

// Use 'q' parameter (alias for search)
const byQ = Countries.search({ q: 'kingdom' });

Get My Country (IP-based)

import { Countries } from 'countries-lib';

// Detect user's country based on IP
const myCountryData = await Countries.findMyCountry();
console.log(myCountryData.data?.country_code); // e.g., "US"

// Or use with Country class
const country = new Country(null, true); // Pass true to auto-detect
await country.setMyCountry();
console.log(country.getMyCountry());

API Reference

Countries Class (Static Methods)

Countries.getAll(options?)

Get all countries with optional filtering.

Options:

• includedCodes?: CountryCode[] - Only include these country codes
• excludedCodes?: CountryCode[] - Exclude these country codes

Countries.getAllMinimal(options?)

Get all countries with minimal data (smaller payload).

Countries.search(query?)

Search countries by various criteria.

Query Options:

• search?: string - Search term
• q?: string - Alias for search
• dialCode?: string - Filter by dial code
• countryCode?: CountryCode - Filter by country code

Countries.getOne(options?)

Get a single country.

Options:

• id?: number - Country ID
• code?: CountryCode - Country code (ISO 3166-1 alpha-2)
• timezone?: string - Filter by timezone
• currency?: string - Filter by currency code

Countries.paginate(options?)

Paginate through countries.

Options:

• page?: number - Page number (default: 1)
• limit?: number - Items per page (default: 10)
• search?: string - Search term
• sortBy?: string - Sort by field
• sortOrder?: 'asc' | 'desc' - Sort order
• baseUrl?: string - Base URL for pagination links
• select?: string[] - Select specific fields

Countries.findMyCountry()

Detect user's country based on IP address (async).

Country Class (Instance Methods)

Constructor

new Country(countryCode?: CountryCode | null, autoDetect?: boolean)

Setters (Chainable)

• setSelectedCountryCode(code: CountryCode): this
• setSearch(search: string): this
• setLimit(limit: number): this
• setPage(page: number): this
• setIncludedCodes(codes: CountryCode[]): this
• setExcludedCodes(codes: CountryCode[]): this
• setSortBy(field: string): this
• setSortOrder(order: 'asc' | 'desc'): this

Getters

• getCountry(): CountryType | null
• getCountryCode(): CountryCode | null
• getCountryTitle(): string | null
• getCountryDialCode(): string | null
• getCountryFlag(): string | null
• getCountryEmoji(): string | null
• getCountryCurrency(): string | null
• getCountryCurrencySymbol(): string | null
• getCountryTimezone(): string | null
• And many more...

Utils Class

Utils.isEmpty(value: any): boolean

Check if a value is empty (null, undefined, [], {}).

Utils.isNotEmpty(value: any): boolean

Check if a value is not empty.

Types

import type { CountryType, CountryMinimal, CountryCode, PaginationResult } from 'countries-lib';

Country Data Structure

{
    id: number;
    code: string; // ISO 3166-1 alpha-2
    title: string;
    dialCode: string;
    continent: string;
    capital: string;
    flag: string;
    largeFlag: string;
    unicode: string;
    emoji: string;
    timezone: string;
    currency: string;
    currencySymbol: string;
    timezones: string[];
    currencies: {...};
    name: {...};
    nativeNames: [...];
    active: boolean;
}

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Your Name

Keywords

countries, country-data, typescript, library, pagination, country-codes, dial-codes, country-flags, currencies, timezones, country-search, iso-codes