TypeScript Countries

TypeScript package for country data with classes and interfaces generated from ISO 3166-1 standard.

Features

• Fairly complete country data with 250+ countries
• Multi-language support (EN, HU, DE, ES, IT, FR, PT)
• TypeScript with full type definitions
• Individual class for each country
• ISO 3166-1 codes (alpha-2, alpha-3, numeric)
• Telephone country codes
• Capital cities
• Continent classification
• Built with Rolldown for optimal bundle size
• 100% functional test coverage
• Compatible with Node.js, Bun

Installation

Bun

bun add @omisai/countries

NPM

npm install @omisai/countries

PNPM

pnpm add @omisai/countries

YARN

yarn add @omisai/countries

Quick Start

import { UnitedStates } from "@omisai/countries";

const usa = new UnitedStates();
console.log(usa.en);        // "United States"
console.log(usa.alpha2);    // "US"
console.log(usa.callingCode);      // "1"

Usage

import { UnitedStates, Germany, Japan, Country } from "@omisai/countries";

// Use specific country classes
const usa = new UnitedStates();
console.log(usa.en); // "United States"
console.log(usa.alpha2); // "US"
console.log(usa.callingCode); // "1"
console.log(usa.capital); // "Washington"

// Get name in different languages
const germany = new Germany();
console.log(germany.getName("en")); // "Germany"
console.log(germany.getName("de")); // "Deutschland"
console.log(germany.getName("fr")); // "Allemagne"

// Convert to JSON
const japanData = new Japan().toJSON();
console.log(japanData);

Project Structure

ts-countries/
├── src/
│   ├── Country.ts           # Abstract base class
│   ├── types/
│   │   ├── Continent.ts     # Continent enum and names
│   │   └── ICountry.ts      # Country interface
│   ├── models/              # Generated country classes
│   │   ├── UnitedStates.ts
│   │   ├── Germany.ts
│   │   └── ... (all countries)
│   └── index.ts             # Main export file
├── compiler.ts              # Generates country classes from CSV
├── countries.csv            # Source data
├── package.json
└── tsconfig.json

Development Scripts

# Generate country classes from CSV
bun run compile

# Build for production (ESM + CJS)
bun run build

# Run tests
bun test

# Run tests with coverage
bun run test:coverage

# Type check
bun run typecheck

# Clean generated files
bun run clean

# Full rebuild
bun run rebuild

Runtime Compatibility

Node.js

import { UnitedStates } from "@omisai/countries";
// or
const { UnitedStates } = require("@omisai/countries");

Bun

import { UnitedStates } from "@omisai/countries";

Testing

The package includes comprehensive tests that run on Node.js, Bun:

# Node.js (Vitest)
npm test

# Bun
bun test tests/*.test.ts

## CI/CD

This project uses GitHub Actions for:
- ✅ Automated testing on Node.js 18, 20, 22
- ✅ Automated testing on Bun
- ✅ Code coverage reporting
- ✅ Automated releases to NPM and JSR
- ✅ Dependency updates via Dependabot

## Releasing

This project uses manual GitHub Actions workflow for releases. See [RELEASE.md](./RELEASE.md) for detailed instructions.

**Quick release**:
1. Go to Actions → Release workflow
2. Click "Run workflow"
3. Enter version (e.g., `1.0.0`)
4. Run!

The workflow automatically handles versioning, tagging, building, testing, and publishing to NPM and JSR.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.

## License

See the [LICENSE](./LICENSE) file for details.

## Acknowledgments

- Country data sourced from ISO 3166-1 standard
- Built with [Rolldown](https://rolldown.rs/) - Fast JavaScript/TypeScript bundler
- Tested with [Vitest](https://vitest.dev/) - Next generation testing framework