country-js

country-js is an npm package designed to provide extensive information about countries, encompassing details such as country code, name, currency symbol, capital city, phone code, latitude, and longitude.

Installation

You can easily install country-js via npm:

``bash
npm install country-js --save
`

Features

- ✅ Search countries by code, name, currency, capital, or phone
- ✅ Direct country lookup by code or name
- ✅ Get all countries or count total
- ✅ Optimized search with exact match prioritization
- ✅ No duplicate results
- ✅ Input validation & error handling
- ✅ TypeScript support with type definitions
- ✅ Comprehensive test coverage

Usage

$3

`js
const countryInfo = require('country-js');
`

$3

Search by country code, name, currency code, currency name, currency symbol, capital, or phone code.

`js
// Search by country code
countryInfo.search('US'); // Returns USA
countryInfo.search('at'); // Returns Austria (case-insensitive)

// Search by country name
countryInfo.search('austria'); // Returns Austria
countryInfo.search('FRANCE'); // Returns France

// Search by currency
countryInfo.search('euro'); // Returns all Euro countries
countryInfo.search('eur'); // Returns all EUR countries
countryInfo.search('€'); // Returns all Euro countries

// Search by capital
countryInfo.search('PARIS'); // Returns France

// Search by phone code
countryInfo.search('1'); // Returns USA, Canada, etc.
`

Returns: Array of country objects (prioritizes exact matches first)

`js
// Example output:
/*
[
{
code: 'AT',
name: 'AUSTRIA',
currency: {
currencyName: 'EURO',
currencyCode: 'EUR',
currencySymbol: '€'
},
geo: { latitude: 47.516231, longitude: 14.550072 },
capital: 'VIENNA',
phone: '43'
}
]
*/
`

$3

Directly retrieve a country by its ISO code (faster than search).

`js
const country = countryInfo.getByCode('US');
const country = countryInfo.getByCode('sg'); // case-insensitive

// Returns: Country object or null if not found
`

$3

Directly retrieve a country by its name.

`js
const country = countryInfo.getByName('AUSTRIA');
const country = countryInfo.getByName('france'); // case-insensitive

// Returns: Country object or null if not found
`

$3

Retrieve all available countries.

`js
const allCountries = countryInfo.getAll();

// Returns: Array of all country objects
// Example: Array with 250+ countries
`

$3

Get the total number of countries in the database.

`js
const total = countryInfo.count();

// Returns: 250 (or similar number)
`

Error Handling

The library validates input and throws TypeError for invalid parameters:

`js
try {
countryInfo.search(123); // Throws TypeError
} catch (error) {
console.error(error.message);
}
`

Valid inputs: search(), getByCode(), getByName() accept strings only
Invalid inputs: null, undefined, numbers, objects, arrays (except empty strings return empty array)

Response Structure

Each country object contains:

`ts
{
code: string; // ISO 3166-1 alpha-2 code (e.g., 'US')
name: string; // Country name in uppercase
currency: {
currencyName: string; // Currency name
currencyCode: string; // ISO 4217 code
currencySymbol: string; // Currency symbol
};
geo: {
latitude: number; // Geographic latitude
longitude: number; // Geographic longitude
};
capital: string; // Capital city name
phone: string; // International phone code
}
`

TypeScript Support

Type definitions are included with the package:

`ts
import * as country from 'country-js';

const result: country.Country[] = country.search('US');
const usa: country.Country | null = country.getByCode('US');
const count: number = country.count();
`

Examples

`js
const countryInfo = require('country-js');

// Get all Euro countries
const euroCountries = countryInfo.search('EUR');

// Get information about a specific country
const usa = countryInfo.getByCode('US');
console.log(usa.capital); // Output: 'WASHINGTON'

// Find countries by capital
const parisCountry = countryInfo.search('PARIS');

// Check total countries
console.log('Total countries:', countryInfo.count());

// Get all countries
const all = countryInfo.getAll();
console.log(Database contains ${all.length} countries);
`

Performance Notes

- search(): O(n) complexity, optimized with Set for deduplication
- getByCode(): O(n) complexity (faster for direct lookups)
- getByName(): O(n) complexity (faster for direct lookups)
- getAll(): O(1) - instant

For best performance with frequent lookups by code or name, use getByCode() or getByName() instead of search().

Testing

Run the comprehensive test suite:

`bash
npm test
``

Tests cover:
- Search functionality (by code, name, currency, capital, phone)
- Direct getters (getByCode, getByName)
- Edge cases (null, undefined, empty strings)
- Error handling (invalid input types)
- Data integrity (unique codes, valid coordinates)