💰 @worldkit/currencies

Fast ISO-4217 currency dataset and helper utilities for JavaScript & TypeScript.

Lookup 160+ ISO-4217 currencies, currency symbols, and country-to-currency mappings with $O(1)$ performance.

📚 Full Documentation: https://worldkit.in/docs/currencies

⚡ Features

• 💵 160+ ISO-4217 Currencies: Includes codes, names, symbols ($, €, ¥, ₹), and minor unit digits.
• 🗺️ Country Mapping: Instantly map country ISO2 codes to official national currencies.
• 🚀 Zero Latency ($O(1)$): Instant lookups in Node.js, Web Browsers, Cloudflare Workers, and Bun.
• 📦 Tree-Shakeable ESM: Lightweight package under 1.8 KB gzipped.

📦 Install

npm install @worldkit/currencies
# or
pnpm add @worldkit/currencies
# or
yarn add @worldkit/currencies

💡 Usage

import {
  currency,
  currencies,
  currencyByCountry,
  currencySymbol
} from "@worldkit/currencies";

// 1. O(1) Currency Lookup by ISO 4217 Code
const usd = currency("USD");
console.log(usd);
/*
{
  code: "USD",
  name: "US Dollar",
  symbol: "$",
  digits: 2,
  countries: ["US", "PR", "VI", ...]
}
*/

// 2. Get currency details by Country ISO2 Code
const japanCurrency = currencyByCountry("JP");
console.log(japanCurrency?.code); // "JPY"
console.log(japanCurrency?.symbol); // "¥"

// 3. Quick currency symbol helper
console.log(currencySymbol("EUR")); // "€"
console.log(currencySymbol("INR")); // "₹"

// 4. Get all currencies
const allCurrencies = currencies();

📖 API Reference

currency(code: string): Currency | undefined

Look up currency information by ISO-4217 code (e.g. "USD", "EUR", "GBP").

currencyByCountry(countryIso2: string): Currency | undefined

Look up official currency metadata by country ISO2 code (e.g. "JP" -> JPY, "IN" -> INR).

currencySymbol(code: string): string

Returns the currency symbol string (e.g. "€") or empty string if not found.

currencies(): Currency[]

Returns an array of all 160+ supported currencies.

📐 TypeScript Support

Includes strict TypeScript definitions out of the box:

import type { Currency } from "@worldkit/currencies";

🔗 Related Packages

Explore the rest of the WorldKit ecosystem:

• @worldkit/core - Unified global toolkit facade.
• @worldkit/countries - 250+ country dataset.
• @worldkit/formatters - Currency & price formatters.
• @worldkit/validators - Currency existence validator.
• @worldkit/react - React <CurrencySelect /> component.

📜 License

MIT © WorldKit