This is an unofficial client for the Exchange Rates API and provides easy to use and implement, promise based functionality to retrieve exchange rates including historical data from the API and return it in an easy to use model. All functionality provided by the API has been encapsulated.

The codebase is covered by unit tests and has code analysis through sonar to help ensure no bugs creep in. There is documentation illustrating implementation of the code and how to get started should you wish to contribute.

• Getting Started
• Installation
• Usage
  • Setting base currency
  • Setting exchange currencies
  • Setting specific date
  • Setting historical date range
  • Get exchange rates
  • Chaining methods
  • Responses
• Supported Currencies
• Unit Tests
• Issues
• Contributions
• License

This is how to get a copy of this working locally. The only requirement is that Node is installed on the base machine.

$ git clone [email protected]:ToeFungi/exchange-rates-as-promised.git
$ cd exchange-rates-as-promised
$ npm i

Install this Exchange Rates API client via npm.

$ npm i --save exchange-rates-as-promised

This project only has a single dependency.

Import the file ExchangeRate client and instantiate a new instance.

import { ExchangeRate } from 'exchange-rates-as-promised'

const exchangeRate = new ExchangeRate()

Set the base currency that the returned currencies will be converted against. You can use the existing enumerated list of supported currencies to select this base currency.

import { Currencies } from 'exchange-rates-as-promised'

exchangeRate.setBaseCurrency(Currencies.GBP)

Set the currencies you want to be returned from the API. These currency will be converted against the currency stipulated as the base above, alternatively it will default to have a base of USD. Use the existing enumerated list of supported currencies to populate the requested list of currencies.

import { Currencies } from 'exchange-rates-as-promised'

const currencies: Currencies[] = [
    Currencies.USD,
    Currencies.ZAR
]

exchangeRate.setCurrencies(currencies)

Set the date for which you want the exchange rate data from. This can be any date as far back to 1999. It accepts a standard JavaScript Date object.

const date = new Date('2012-01-31')

exchangeRate.setDate(date)

Set the historical dates for which the exchange rates should be returned. Note that these rates may not be available for each day in the requested time period. The API provides historical data dated back to 1999.

const endDate = new Date('1999-01-04')
const startDate = new Date('1999-01-01')

exchangeRate.setHistoricalDate(startDate, endDate)

Generates and submits the request to the API and returns a typed response object within a promise containing the data that has been requested.

import { ExchangeResponse } from 'exchange-rates-as-promised'

exchangeRate.getRates()
  .then((response: ExchangeResponse) => console.log({
    base: response.base,
    date: response.date,
    rates: response.rates
  }))

All of the appropriate setters contained in this library return the instance of the ExchangeRate client that the method call is being executed on. This means that you can chain the setters for an easier and cleaner implementation.

import { ExchangeRate, Currencies, ExchangeResponse } from 'exchange-rates-as-promised'

const date = new Date('2012-01-30')
const currencies: Currencies[] = [
    Currencies.USD,
    Currencies.ZAR
]

const exchangeRate = new ExchangeRate()

exchangeRate.setBaseCurrency(Currencies.GBP)
  .setCurrencies(currencies)
  .setDate(date)
  .getRates()
  .then((response: ExchangeResponse) => console.log({
    base: response.base,
    date: response.date,
    rates: response.rates
  }))

There is a standardised response type of ExchangeResponse which is altered depending on the request. In the event of querying historical data, the rates within ExchangeResponse will contain the type of HistoricalRates whereas any other request will contain the type of Rates.

Only currencies listed on the European Central Bank are supported by this client at the moment. The following is a list of the currently available and supported currencies. The rates of these currencies are updated periodically.

Australian Dollar (AUD)
Brazilian Real (BRL)
British Pound Sterline (GBP)
Bulgarian Lev (BGN)
Canadian Dollar (CAD)
Chinese Yuan Renminbi (CNY)
Croatian Kuna (HRK)
Czech Koruna (CZK)
Danish Krone (DKK)
Euro (EUR)
Hong Kong Dollar (HKD)
Hungarian Forint (HUF)
Icelandic Króna (ISK)
Indonesian Rupiah (IDR)
Indian Rupee (INR)
Israeli Shekel (ILS)
Japanese Yen (JPY)
Malaysian Ringgit (MYR)
Mexican Peso (MXN)
New Zealand Dollar (NZD)
Norwegian Krone (NOK)
Philippine Peso (PHP)
Polish Złoty (PLN)
Romanian Leu (RON)
Russian Rouble (RUB)
Singapore Dollar (SGD)
South African Rand (ZAR)
South Korean Won (KRW)
Swedish Krona (SEK)
Swiss Franc (CHF)
Thai Baht (THB)
Turkish Lira (TRY)
US Dollar (USD)

To run tests, you should be able to simply run be able to run the following.

$ npm run test
$ npm run coverage

The testing framework used is Mocha. Chai, Chai-as-promised, nyc and nock are used for assertions, coverage reporting and mocking external requests, respectively. Should you make a change request, please ensure that the new changes are appropriately covered by accompanying unit tests.

If you find any problems while working with this library, please log an issue here so that development can begin to rectify the error.

Follow development on the Trello board here.

This project is completely open source and as such, you are invited to make contributions. Fork the project, make some changes and make the pull request. Should you have any feedback regarding the functionality, please don't hesitate to open an issue so this can be resolved. Please ensure that any pull requests have unit tests that cover any additional functionality.

MIT License

Copyright (c) 2019 Alex Pickering