country-currency-utils

A lightweight TypeScript utility library for working with country and currency metadata.

Features

• 250 country and territory records
• 154 currency records
• Country lookup by ISO-2 code
• Currency symbol and rate lookup
• Basic currency conversion helper
• TypeScript declarations included (dist/*.d.ts)

Installation

npm install country-currency-utils

Local Development

npm install
npm run typecheck
npm run build

Build output is generated in dist/.

Usage

import { CountryService, CurrencyService } from "country-currency-utils";

const countries = CountryService.getAll();
const usCurrency = CountryService.getCurrency("US");
const usdSymbol = CurrencyService.getSymbol("USD");
const converted = CurrencyService.convert(100, "USD", "JPY");

console.log(countries.length);
console.log(usCurrency);
console.log(usdSymbol);
console.log(converted);

API

CountryService

• getAll(): Country[] Returns all country entries.

• getByCode(code: string): Country | undefined Returns a country by ISO-2 code (for example, "US", "LK", "JP").

• getCurrency(countryCode: string): string | undefined Returns the currency code for a country.

CurrencyService

• getSymbol(code: string): string | undefined Returns a currency symbol by currency code.

• getRate(code: string): number | undefined Returns the configured rate for a currency code.

• convert(amount: number, from: string, to: string): number Converts using the formula:

$$ ext{result} = \left(\frac{\text{amount}}{\text{fromRate}}\right) \times \text{toRate} $$

Throws an error when from or to currency is invalid.

Data Shape

export interface Country {
	name: string;
	code: string;
	currency: string;
	symbol: string;
	locale: string;
}

export interface Currency {
	symbol: string;
	rate: number;
}

Notes

• Current rate values are placeholders (1) in the bundled dataset.
• For real-world conversion, plug in live exchange rates before calling convert.

License

MIT