CurrencyJS

A free currency converter for NodeJS - uses the European Central Bank's daily feed for accuracy

Contents

• Installation
• Usage
• Creating Data Tables
• Importing Data
• Converting Currencies
• The Convert Model
• Supported Currencies
• Supported Databases
• Bugs
• Licence

# Installation

The best way of installing this is through NPM:

npm install currencyjs

If you want to install a specific version:

npm install [email protected]

# Usage

The first thing you need to do is to include the library and create an instance.

var CurrencyJS = require('currencyjs');

var objCurrency = new CurrencyJS({
    type: 'mysql', // Select database to use
    host: 'host', // localhost or similar
    user: 'username', // Optional
    pass: 'password', // Optional
    db: 'database',
    port: 'port' // Optional
});

See the Supported Databases section for the databases you can use.

## Creating Data Tables

Once you've created your instance, you will need to create your data table. This is something you'll only probably do once, but it's written as a function to make it easier (and to run integration tests on it).

Depending upon your chosen database type (eg, Mongo), you may not actually need to run this. However, it's probably best to run it.

objCurrency.createTable(function(err, result) {
    
    // err should be null
    // result should be true
    
});

If you have some form of migration script of your own, you can use the actual query directly. You'll find this in /lib/db/DB_TYPE/store.js.

## Importing Data

Now we've got our data table created, we can start importing some data. The feed is from the European Central Bank, which publishes it in XML format. Again there is a method that you can execute, imaginatively titled import().

objCurrency.import(function(err, importCount) {
    
    // err should be null
    // importCount should be a number, at least 0
    
});

This is probably best run as a cron job. The feed gets updates at about 2pm in Central European Time - UTC + 1 (UTC + 2 in the summer). Also, the feed is only updated on weekdays, so not much point in querying it on a Saturday or Sunday.

## Converting Currencies

This is what you actually want. Once you've set up your database and imported some data, you can actually get on with doing the conversions. Best done with a series of examples

Get 1 USD in EUR at latest rate

Pass in just the currencies to get the currency rate

objCurrency.convert('USD', 'EUR', function(err, objConvert) {
    
    // err should be null
    // objConvert should be instance of Convert object
    
});

Get 10 GBP in AUD at latest rate

Pass in an object with value defined. THIS MUST BE A NUMBER

objCurrency.convert('GBP', 'AUD', {value: 10}, function(err, objConvert) {
    
    // err should be null
    // objConvert should be instance of Convert object
    
});

Get 45.85 EUR in CAD for a given date

Pass in an object with date defined. THIS MUST BE A DATE OBJECT

objCurrency.convert('EUR', 'CAD', {value: 45.85, date: new Date('2013-07-23')}, function(err, objConvert) {
    
    // err should be null
    // objConvert should be instance of Convert object
    
});

## The Convert Model

When you make a conversion request, you are returned an instance of the Convert model. This is quite useful as, once you have it, you can make further conversions without having to query the database.

Methods Available

calculate(value)

@returns Undefined

Converts the from value into the to value

You will need to do one of the below get methods to return the value.

calculateReverse(value)

@returns Undefined

Converts the to value into the from value

You will need to do one of the below get methods to return the value.

getFromFormatted(decimals = 2, decPoint = '.', thousandsSep = ',')

Gets the from value formatted as a string. By default, it would return 1234.5 as 1,234.50.

getFromValue()

@returns Number

Returns the from value as a number.

getRate()

@returns Number

Returns the converstion rate as a number. Multiply the from value by this and you will get the to value.

getReverseRate()

@returns Number

Returns the reverse converstion rate as a number. Multiply the to value by this and you will get the from value.

getToFormatted(decimals = 2, decPoint = '.', thousandsSep = ',')

@returns String

Gets the to value formatted as a string. By default, it would return 1234.5 as 1,234.50.

getToValue()

@returns Number

Returns the to value as a number.

# Supported Currencies

This is a list of all the supported currencies and their 3 letter code:

• AUD - Australian Dollar
• BGN - Bulgarian Lev
• BRL - Brazilian Real
• CAD - Canadian Dollar
• CHF - Swiss Franc
• CNY - Chinese Yuan
• CZK - Czech Koruna
• DKK - Danish Krone
• EUR - Euro
• GBP - British Pound
• HKD - Hong Kong Dollar
• HRK - Croatian Kuna
• HUF - Hungarian Forint
• IDR - Indonesian Rupiah
• ILS - Israeli New Shekel
• INR - Indian Rupee
• JPY - Japanese Yen
• KRW - South Korean Won
• LTL - Lithuanian Litas
• LVL - Latvian Lats
• MXN - Mexian Peso
• MYR - Malaysian Ringgit
• NOK - Norwegian Krone
• NZD - New Zealand Dollar
• PHP - Phillippine Peso
• PLN - Polish Zloty
• RON - Romanian New Leu
• RUB - Russian Rouble
• SEK - Swedish Krona
• SGD - Singapore Dollar
• THB - Thai Baht
• TRY - Turkish Lira
• USD - US Dollar
• ZAR - South African Rand

# Supported Databases

CurrencyJS supports the following databases and from which version. Simply set up the CurrencyJS object with the string in italics below.

• MySQL (v1.0.0) - mysql
• MongoDB (v1.1.0) - mongo

# Bugs

Please report any bugs on GitHub

# Licence

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Copyright (C) 2013 Simon Emms