Country Information Library

Table of Contents

1. Introduction
2. Installation
3. Basic Usage
4. Detailed API
5. Advanced Examples
6. Usage Tips
7. Troubleshooting
8. Contributing
9. License

Introduction

This JavaScript library provides easy and flexible access to detailed information about countries worldwide. It allows developers to search, filter, and retrieve data about countries, such as flags, capitals, populations, and much more.

Installation

To install the library, use npm:

npm install countriesData

Basic Usage

Here's how to get started with the library:

import { CountriesData } from 'countriesData';

// Create an instance of CountryManager
const countriesData = CountriesData();

// Example: Get names of all European countries
const europeanCountries = countriesData.continent('europe').names;
console.log(europeanCountries);

Detailed API

CountryManager Class

Filtering Methods

• continent(continent: string): CountryManager

  • Filters countries by continent.
  • Example: countriesData.continent('africa')

• byPopulation(min: number, max?: number): CountryManager

  • Filters countries by population.
  • Example: countriesData.byPopulation(1000000, 5000000)

• byArea(min: number, max?: number): CountryManager

  • Filters countries by area.
  • Example: countriesData.byArea(100000)

• byName(name: string): CountryManager

  • Searches countries by name (common or official).
  • Example: countriesData.byName('france')

Data Retrieval Methods

• flags: { country: string, flag: string | undefined }[]

  • Returns an array of objects containing the country name and its flag URL.

• names: string[]

  • Returns an array of common country names.

• capitals: { country: string, capital: string | undefined }[]

  • Returns an array of objects containing the country name and its capital.

• getResults(limit?: number): Country[]

  • Returns complete results of filtered countries, with an optional limit.

• getCountryByCode(code: string): Country | undefined

  • Returns information about a specific country by its code (cca2, cca3, or ccn3).

Other Methods

• reset(): CountryManager
  • Resets filters, returning the country list to its initial state.

Country Interface

The Country interface represents the data structure for each country. It includes properties such as:

• name: Object containing common and official country names
• tld: Top-level domains
• cca2, cca3, ccn3: Country codes
• currencies: Currencies used
• capital: Capital(s)
• region, subregion: Region and subregion
• languages: Spoken languages
• borders: Bordering countries
• area: Area
• population: Population
• flags: Flag URLs
• ... and many more

Advanced Examples

Find Asian countries with a population over 100 million

const largeAsianCountries = countriesData
  .continent('asia')
  .byPopulation(100000000)
  .names;
console.log(largeAsianCountries);

Get flags of the 5 largest South American countries

const southAmericanFlags = countriesData
  .continent('south america')
  .sortByArea(false)
  .getResults(5)
  .map(country => ({
    name: country.name.common,
    flag: country.flags.svg
  }));
console.log(southAmericanFlags);

Usage Tips

1. Always reset filters with reset() after a search if you plan to make other queries.
2. Use method chaining for complex queries.
3. For optimal performance, create a single instance of CountryManager and reuse it.

Troubleshooting

• Problem: No results returned Solution: Check that you haven't applied overly restrictive filters. Use reset() to start over.

• Problem: Error "Cannot read property of undefined" Solution: Ensure that the property you're trying to access exists for all countries. Use null checks or default values.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

This library is licensed under the MIT License. See the LICENSE file for more details.