MoneyJS
Nodejs library to represent monetary amounts.
Note: Instances of Money are immutable and each arithmetic operation will return a new instance of the money object.
Installation
$ npm install --save async lodash moneyjs
Usage
//require moneyvar Money = ; //instantiate a new moneyvar purchasePrice = 12MoneyUSDvar margin = 156MoneyTZS; //compute selling price//by adding purchase price and marginpurchasePrice; var profit = MoneyTHOUSAND;var tax = MoneyFIFTY;//compute net profit by subtract tax from profitprofit; //check if net profit is zeronetProfit; //check if net profit is negativenetProfit; //check if net profit is positivenetProfit; var expectedProfit = MoneyHUNDRED; //check if net profit is greater than//expected profitnetProfit; //check if net profit is less than//expected profitnetProfit; //check if net profit is equal to//expected profitnetProfit; //exchange net profit to TZSnextProfit; ...
API
Configuration
Money.BASE
Set a base currency to be used with Money
. Default to Money.USD
. Currency value to set must be obtained from Money
static currencies helper. Money.BASE
is heavily used in exchanging
money instance from one currency to another.
Example
//require moneyvar Money = ; //set base currencyMoneyBASE = MoneyUSD...//continue with money usage
Money.getExchangeRates(date,done)
Used to get exchange rates
when exchange
money instance from one currency to another. This method must be ovverided
if exchanging operation is going to be used. date
respresent a date when the money instance has been created. This will allow you to fetch or provide exchange rates of that exactly moment or otherwise.
Note: Returned exchange rates must be in the format {USD:1,TZS:1900,KES:90}
;
Example of implementation
var rates = USD: 1 TZS: 1900 KES: 90; { //fetch exchange rates //from API or anywhere else //based on date passed ;} //then set it to moneyMoneygetExchangeRates = getRates;
Instance creation
new Money(amount,currency,date)
Instantiate a new instance of money with amount
you want to set on money, a currency
to set on money and a date
when this money created, if not provided will default to new Date()
//require moneyvar Money = ; //instantiate a new moneyvar price = 12MoneyUSD...
Money.ZERO
Return new instance of money with amount set-ed
to zero, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyZERO;...
Money.ONE
Return new instance of money with amount set-ed
to one, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyONE;...
Money.TEN
Return new instance of money with amount set-ed
to ten, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyTEN;...
Money.TWENTY
Return new instance of money with amount set-ed
to twenty, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyTWENTY;...
Money.FIFTY
Return new instance of money with amount set-ed
to fifty, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyFIFTY;...
Money.HUNDRED
Return new instance of money with amount set-ed
to hundred, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyHUNDRED;...
Money.THOUSAND
Return new instance of money with amount set-ed
to thousand, currency set to Money base currency and time
set to current timestamp.
Example
//require moneyvar Money = ; //instantiate a new moneyvar price = MoneyTHOUSAND;...
Arithmetic Operations
multiply(multiplier)
, multiplyBy(multiplier)
Perform scalar multiplication on the amount of money instance. It return new money instance holding result of operation
Example
var Money = var price = 12 MoneyUSD;price = price; //price.multiply(4);...
divide(divisor)
, divideBy(multiplier)
Perform scalar division on the amount of money instance. It return new money instance holding result of operation
Example
var Money = var price = 12 MoneyUSD;price = price; //price.divide(4);...
add(money)
, plus(money)
Add another money instance to this money instance. It returns new money instance holding result of operation. The returned money instance will have the currency of the money instance where plus has been invoked.
Note: Instance of money with different currencies are supported
Example
var Money = var price = 12 MoneyUSD;price; ...
If two money instances
are of same currency you may opt for synchronous addition
Example
var price = 12 MoneyUSD;var tax = 2 MoneyUSD;var priceAfterTax = price;
minus(money)
, subtract(money)
Subtract another money instance from this money instance. It returns new money instance holding result of operation.The returned money instance will have the currency of the money instance where minus has been invoked.
Note: Instance of money with different currencies are supported
Example
var Money = var price = 12 MoneyUSD;price = price; ...
If two money instances
are of same currency you may opt for synchronous subtraction
Example
var profit = 12 MoneyUSD;var tax = 2 MoneyUSD;var netProfit = profit;
Logical Operations
equals(money)
, equalTo(money)
Check if this money instance is equal to the given money instance. It returns boolean true
otherwise boolean false
Example
var Money = ; var tax = 200 MoneyUSD;var rent = 1200 MoneyUSD;var any = 1200 MoneyUSD; tobetrue;tobefalse;tobefalse; tobetrue;tobetrue;tobefalse; ...
lessThan(money)
, isLessThan(money)
Check if this money instance is less than given money instance. It returns boolean true
if so otherwise boolena false
Example
var Money = ; var price = 12 MoneyUSD;var tax = 2 MoneyUSD; tobetrue;tobefalse; ...
greaterThan(money)
, isGreaterThan(money)
Check if this money instance is less than given money instance. It returns boolean true
if so otherwise boolena false
Example
var Money = ; var price = 12 MoneyUSD;var tax = 2 MoneyUSD; tobetrue;tobefalse; ...
isZero(money)
Check if this money instance has amount equal to zero.
Example
var Money = ; var tax = 0 MoneyUSD;var any = 000 MoneyUSD;var rent = 1200 MoneyUSD; tobetrue;tobetrue;tobefalse; ...
isNegative(money)
Check if this money instance has amount which is less than zero.
Example
var Money = var profit = 1200 MoneyUSD;var loss = -1200 MoneyUSD; tobefalse;tobetrue; ...
isPositive(money)
Check if this money instance has amount greater than zero.
Example
var Money = ; ar profit = 1200 MoneyUSD;var loss = -1200 MoneyUSD; tobetrue;tobefalse; ...
Testing
-
Clone this repository
-
Install all development dependencies
$ npm install
- Then run test
$ npm test
Contribute
It will be nice, if you open an issue first so that we can know what is going on, then, fork this repo and push in your ideas. Do not forget to add a bit of test(s) of what value you adding.
Licence
The MIT License (MIT)
Copyright (c) 2015 lykmapipo & Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.