Forex Rates

This is an unofficial client for the Forex Rates API and provides easy to use and implement, promise based functionality to retrieve forex 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.

Contents

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

Getting Started

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]:apiforfun/forexrates-nodejs.git
$ cd forexrates-nodejs
$ npm i

Installation

Install this Forex Rates API client via npm.

$ npm i --save forex-rates

This project only has a single dependency.

Usage

Import the file ForexExchangeRate client and instantiate a new instance.

import { ForexExchangeRate } from 'forex-rates'

const forexExchangeRate = new ForexExchangeRate()

.setBaseCurrency(string)

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 'forex-rates'

forexExchangeRate.setBaseCurrency(Currencies.GBP)

.setCurrencies(array)

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 'forex-rates'

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

forexExchangeRate.setCurrencies(currencies)

.setDate(Date)

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')

forexExchangeRate.setDate(date)

.setHistoricalDate(Date, Date)

Set the historical dates for which the forex 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')

forexExchangeRate.setHistoricalDate(startDate, endDate)

.getRates()

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 { ForexExchangeResponse } from 'forex-rates'

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

Chaining Setters

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

import { ForexExchangeRate, Currencies, ForexExchangeResponse } from 'forex-rates'

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

const forexExchangeRate = new ForexExchangeRate()

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

Responses

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

Supported Currencies

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)

Running Tests

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.

Issues

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

Contributions

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.

License

MIT License