Countries Mania JS

A fluent API for normalizing and aggregating country data with support for ISO codes, nationalities, and custom metadata. Built on top of i18n-iso-countries and i18n-nationality packages.

Installation

npm install countries-mania-js

Prerequisites

This package requires:

• i18n-iso-countries - For ISO codes and country names
• i18n-nationality - For nationality data

These will be installed automatically as dependencies.

Usage

Fluent API

The package provides a fluent API for building country data queries:

const countries = require("countries-mania-js");

// Basic usage
const data = countries.build();

// With extra data
const data = countries
  .withCurrency()
  .withPopulation()
  .withCapitalCity()
  .build();

// Export to JSON file
countries.withCurrency().withPopulation().toFile("output/countries.json");

// Get as JSON string
const json = countries.withCurrency().toJSON();

Available Methods

Basic Configuration

• .withCallingCode(include) - Include/exclude calling codes (default: true)
• .withNationality(include) - Include/exclude nationality data (default: true)
• .withNumericCode(include) - Include/exclude numeric codes (default: true)

Extra Data Methods

• .withCurrency() - Include currency code data
• .withCurrencyName() - Include currency name data
• .withPopulation() - Include population data
• .withCapitalCity() - Include capital city data
• .withContinent() - Include continent data
• .withSurfaceArea() - Include surface area data
• .withLanguages() - Include languages data
• .withRegion() - Include region in world data
• .withAll() - Include all commonly used extra data fields
• .withExtra(filename, key) - Include custom extra data file

Configuration Methods

• .setKeyType(keyType) - Set output key type: "alpha2" or "alpha3" (default: "alpha3")
• .setExtraDataDir(dir) - Set custom extra data directory
• .setArabicNationalitiesFile(filepath) - Set Arabic nationalities file path

Output Methods

• .build() - Build and return the normalized data object
• .toFile(outputFile) - Export data to JSON file
• .toJSON(indent) - Get data as JSON string

Examples

const countries = require("countries-mania-js");

// Example 1: Basic data with all defaults
const basicData = countries.build();

// Example 2: Minimal data (no calling codes, no numeric codes)
const minimalData = countries
  .withCallingCode(false)
  .withNumericCode(false)
  .build();

// Example 3: With multiple extra data sources
const richData = countries
  .withCurrency()
  .withPopulation()
  .withCapitalCity()
  .withContinent()
  .build();

// Example 4: Custom extra data file
const customData = countries
  .withExtra("country-by-temperature.json", "temperature")
  .build();

// Example 5: Export to file
countries.withCurrency().withPopulation().toFile("output/countries.json");

// Example 6: Use alpha-2 keys instead of default alpha-3
const dataWithAlpha2 = countries.setKeyType("alpha2").build();

// Example 7: Include all common extra data at once
const completeData = countries.withAll().build();

// Example 8: Multiple instances
const builder1 = countries.create();
const builder2 = countries.create();

const data1 = builder1.withCurrency().build();
const data2 = builder2.withPopulation().build();

TypeScript Usage

This package includes TypeScript definitions for full IDE autocomplete support:

import countries, {
  CountryDataBuilder,
  CountriesData,
} from "countries-mania-js";

// Full type inference
const data: CountriesData = countries.withCurrency().withPopulation().build();

// Builder with types
const builder: CountryDataBuilder = countries.create();
builder.withAll().toFile("output/countries.json");

Output Structure

By default, countries are keyed by alpha-3 codes (e.g., "LBN", "USA") for better readability. You can change this to alpha-2 codes (e.g., "LB", "US") using .setKeyType('alpha2').

Each country entry follows this structure:

{
  "LBN": {
    "name": {
      "en": "Lebanon",
      "ar": "لبنان"
    },
    "nationality": {
      "en": "Lebanese",
      "ar": "لبناني"
    },
    "codes": {
      "alpha2": "LB",
      "alpha3": "LBN",
      "numeric": "422",
      "calling": "961"
    },
    "extra": {
      "currency": "LBP",
      "population": 6825442,
      "capital": "Beirut"
    }
  }
}

Fields are conditionally included based on your query configuration.

Command Line Interface

You can also use the CLI script:

# Basic usage
npm run normalize

# With options
node normalize-countries.js \
  --output output/countries.json \
  --key-type alpha2 \
  --include-extra country-by-population.json \
  --include-extra country-by-capital-city.json

Arabic Nationalities

Arabic nationalities are loaded from extra/ar-nationalities-fallback.json by default. This file uses the package format:

{
  "locale": "ar",
  "nationalities": {
    "LB": "لبناني",
    "US": "أمريكي"
  }
}

You can provide a custom file using .setArabicNationalitiesFile(filepath).

Extra Data Files

Extra data files should be placed in the extra/ directory (or a custom directory specified with .setExtraDataDir()). Files should follow this format:

[
  {
    "country": "Lebanon",
    "currency_code": "LBP"
  }
]

The package will automatically match entries by country name (normalized) or ISO alpha-2 code.

Features

• 🎯 Fluent API - Chain methods for intuitive data querying
• 🌍 ISO 3166-1 Support - Alpha-2, Alpha-3, and numeric codes
• 🌐 Multi-language - Country names and nationalities in multiple languages (English & Arabic)
• 📊 Extensible - Easy integration of custom country metadata
• ⚡ Fast - Efficient data loading and normalization
• 🔧 Flexible - Configurable output format and key types
• 📝 TypeScript Support - Full TypeScript definitions included

License

MIT

Repository

https://github.com/HadiHz88/country-mania-js