@finket/finketcurrencies

A lightweight Node.js library for retrieving ISO 4217 currency data.
Provides intuitive methods to access currency details by their alphabetic code ("USD", "ARS") or numeric code ("840", "032").
Perfect for financial applications, internationalization, and currency-related tasks.

Features

• Access currency info: code, number, name, minor unit exponent, countries.
• Search by ISO 4217 alphabetic or numeric codes (case-insensitive).
• Minimal dependencies for lightweight footprint.
• Robust input validation.
• Easy integration into Node.js projects.

Installation

npm install @finket/finketcurrencies

For private registries (e.g., AWS CodeArtifact), configure your .npmrc or authenticate before installing. See Private Registry.

Usage

The library offers two main methods: findByCode and findByNumber.
You can retrieve full details for any ISO 4217 currency.

Example 1: Finding Currencies by Alphabetic Code

const { findByCode } = require("@finket/finketcurrencies");

// Find USD
const usd = findByCode("USD");
console.log(usd);

// Find ARS
const ars = findByCode("ARS");
console.log(ars);

Expected Output:

{
  "code": "USD",
  "number": "840",
  "name": "US Dollar",
  "exponent": 2,
  "countries": ["UNITED STATES"]
}
{
  "code": "ARS",
  "number": "032",
  "name": "Argentine Peso",
  "exponent": 2,
  "countries": ["ARGENTINA"]
}

Example 2: Finding Currencies by Numeric Code

const { findByNumber } = require("@finket/finketcurrencies");

// Find by numeric code
const usd = findByNumber("840");
const ars = findByNumber(32); // numeric input also allowed

console.log(usd);
console.log(ars);

Example 3: Processing Multiple Currencies

const { findByCode } = require("@finket/finketcurrencies");

const codes = ["USD", "ARS", "EUR"];
codes.forEach(code => {
  const currency = findByCode(code);
  if (currency) {
    console.log(`${currency.name} (${currency.code}): ${currency.countries.join(", ")}`);
  } else {
    console.log(`Currency not found: ${code}`);
  }
});

Expected Output (partial):

US Dollar (USD): UNITED STATES
Argentine Peso (ARS): ARGENTINA
Euro (EUR): ÅLAND ISLANDS, EUROPEAN UNION, ...

API Reference

findByCode(code)

Retrieves a currency by its ISO 4217 alphabetic code.

• Parameters:
  code (string): Alphabetic code (e.g., "USD"). Case-insensitive.
• Returns:
  A currency object or null if not found.
• Throws:
  Error if code is not a valid non-empty string.

findByNumber(number)

Retrieves a currency by its ISO 4217 numeric code.

• Parameters:
  number (string | number): Numeric code (e.g., "840" or 840).
• Returns:
  A currency object or null if not found.
• Throws:
  Error if number is not provided.

Currency Object Structure

Each currency object contains:

| Field | Type | Example | |-----------|----------|-------------| | code | string | "USD" | | number | string | "840" | | name | string | "US Dollar" | | exponent | number | 2 | | countries | string[] | ["UNITED STATES"] |

Requirements

• Node.js v14 or higher
• Dependency: csv-parse (^5.5.6)

Private Registry

If you're using a private registry like AWS CodeArtifact:

aws codeartifact login --tool npm --domain finket --domain-owner 194122164712 --repository finket --region us-east-1
npm install @finket/finketcurrencies

Contact your registry administrator for more details.

Contributing

Contributions are welcome! 🚀

1. Fork the repo.
2. Create your branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "Add feature"
4. Push to the branch: git push origin feature/your-feature
5. Open a pull request.

Please ensure your code includes tests and follows project standards.

Issues

Report bugs or request features by opening an issue.

License

This project is licensed under the MIT License.
See the LICENSE file for details.

Acknowledgments

• Currency data based on ISO 4217 official standard.
• CSV parsing powered by the csv-parse library.