currency-data

A module that exposes comprehensive data on the worlds currencies

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
currency-data
1.0.08 years ago8 years agoMinified + gzip package size for currency-data in KB

Readme

currency-data

Circle CI
Coverage Status Dependency status Dependency status npm version
Currency data is an npm package for exposing information about the world's currencies and their usage. It's core value lies in ./data.json and it exposes a number of utility methods for interacting with it's content, however, requiring that data yourself is of course possible (and encouraged). You can do so thusly:
const rawCurrencyData = require('./node_modules/currency-data/data'); 

There are a number of other NPM modules that have similar functionality, but most of them have incomplete data (e.g. only returning one currency that uses the '£' symbol?! There are dozens!). As a result this module attempts to offer a complete and comprehensive set of data about the worlds currencies.
Need information about the currency used in the Nagorno-Karabakh Republic? This is the module for you! The answer is it uses two currencies: the Nagorno-Karabakh Dram and the Armenian Dram!

Usage

const currencyData = require('currency-data');

currencyData.getCurrenciesBySymbol('£'); // Returns an Array of all currencies that use the '£' symbol

Data structure

The core data structure is as follows:
{
	"countryName": "United States",
	"countryISOCode":"USA",
	"currency": { 
		"name": "United States Dollar",
		"symbol": "$",
		"isoCode": "USD",
		"fractionalUnit": {
			"name":"Cent",
			"numberToBasic":100
		}
	}
}

The public API

The public API is very high level, and frankly, verbose. It was deliberatley designed that way to be self explanatory. I know I got confused with the different ISO standards for describing counties and currencies, so I wanted to make the public methods eaiser to grok.
| API Method | Arguments | Return type |Description | |---|---|---|---| | .getData() | None | Array | A utility method to return all of the data from the module in a single large Array | | .getCurrencyByCountryISOCode() | String / An ISO 3166-1 alpha-3 country code | Object | Returns the currency used in a specified country | | .getCountriesByCurrencyISOCode() | String / An ISO4217 currency code | Array | Returns an Array of country objects that use a currency e.g. all the countries that use the USD | | .getCurrencyByCurrencyISOCode() | String / An ISO4217 currency code | Object | Returns just the currency object (see Data Structure above) for a currency | | .getCurrenciesBySymbol() | String / a currency symbol e.g. $/£/€ | Array | Returns an Array of all currencies that use that symbol | | .getCurrencyByName() | String e.g. British Pound | Object | Returns just the currency object (see Data Structure above) for a currency | | .getCurrenciesByFractionalUnit() | String e.g. Cent | Array | Returns an Array of all the currencies that use a fractional unit | | .getCurrenciesByFractionalUnitNumberToBasic() | Integer e.g. 100 | Array | A niche method, but it returns all the currencies that share the property of number of fractional units to a basic unit | | .getCurrencyISOCodes() | None | Array | Utility method that returns all of the available currency ISO codes, please remember some currencies do not have assigned ISO codes and so won't be returned | | .getCurrencyNames() | None | Array | Utility method that returns the names of all the available currencies | | .getCountryISOCodes() | None | Array | Utility method that returns the names of the ISO codes of all available countries | | .getCountryNames() | None | Array | Utility method that returns the names of the all the available countries |
If you have any requests for public methods please file an issue, these were created to meet my own use case for this module but I can see how others would also be useful.

Testing

npm test
npm local-coverage // runs tests and generates coverage report

TODO

  • Return all available currency denominations for a currency

Contrubuting

All contributors will abide by the CODE_OF_CONDUCT.md.

License

MIT