Money is a unified Javascript RequireJS/CommonJS module for the browser or server (SSJS) which provides monetary mathematical operations and textual formatting.
Monetary values are treated as numbers with their number of decimal places fixed at 2. Thus all mathematical and comparison operations produce proper results for all currencies based on 1/100 of a unit (such as dollars).
- Dependencies
- Script Files
- Example
- Constants
- Money Object Creation
- Money Object Methods
- abs ()
- dividedBy (value)
- getValue ()
- isEqualTo (value)
- isGreaterThan (value)
- isGreaterThanOrEqualTo (value)
- isLessThan (value)
- isLessThanOrEqualTo (value)
- minus (value)
- negate ()
- plus (value)
- setValue (value)
- times (value)
- toString (symbol, negativeFormat, symbolPosition, thousandsSeparator, decimalSeparator)
- Module Functions
- Testing
- Contributions
- License
- money.js - Fully commented script. Update to contribute.
- money.min.js - Minimized script. For normal use.
- money.no-md.js - Commented script without markdown comments. Use for debugging.
var orderAmount = money.make(25);
var salesTaxRate = 0.06125;
var saleTaxAmount = orderAmount.times(salesTaxRate); // 1.53, not 1.53125
- MINUS_SIGN - Use a minus sign for negative monetary amounts when calling toString().
- PARENTHESES - Use parentheses for negative monetary amounts when calling toString().
Examples:
var debit = money.make(-25.34);
debit.toString('$', money.NEGATIVE_FORMATS.MINUS_SIGN); // '-$25.34'
debit.toString('$', money.NEGATIVE_FORMATS.PARENTHESES); // '$(25.34)'
- AFTER - Place the currency symbol at the end when calling toString().
- BEFORE - Place the currency symbol in the front when calling toString().
Examples:
var price = money.make(25);
price.toString(); // '$25.00'
money.defaults.symbolPosition(money.SYMBOL_POSITIONS.AFTER);
price.toString(); // '25.00$'
To create a Money object, simply call the make() function with an optional initial numeric
value
. If no value is passed, the money object's amount is set to 0.00. If the given value
is
already a money object, it is simply returned "as is."
Examples:
// Using RequireJS:
require(['money'], function (money) {
var expense = money.make(24.50); // 24.50
var discount = money.make(); // 0.00
});
// Using CommonJS:
var money = require('money');
var expense = money.make(24.50); // 24.50
var discount = money.make(); // 0.00
Returns the absolute value of the value of the money object as a new money object.
Examples:
money.make(-24.50).abs(); // 24.50
money.make(24.50).abs(); // 24.50
money.make(0.00).abs(); // 0.00
Divides the money amount by the given money or numeric value
and returns the result. If the
given value
is numeric, a money value is returned. If it is a money value, a numeric value is
returned.
Examples:
money.make(24.50).dividedBy(2); // 12.25
var sales = money.make(100000);
var expenses = money.make(80000);
expenses.dividedBy(sales); // 0.8
Returns the numeric value of the money object.
Examples:
money.make(24.50).getValue(); // 24.50
Returns true if the given numeric or money value
is equal to the value of the money object and
returns false otherwise. If value
is numeric, it is converted into a money object before
making the comparison.
Examples:
var value1 = money.make(24.5);
var value2 = money.make(24.5);
var value3 = money.make(10);
value1.isEqualTo(value2); // true
value1.isEqualTo(value3); // false
value1.isEqualTo(24.502); // true
value1.isEqualTo(20); // false
Returns true if the value of the money object is greater than the given numeric or money value
and returns false otherwise. If value
is numeric, it is converted into a money object before
making the comparison.
Examples:
var value1 = money.make(24.5);
var value2 = money.make(24.5);
var value3 = money.make(10);
value1.isGreaterThan(value3); // true
value1.isGreaterThan(value2); // false
value1.isGreaterThan(24.502); // false
value1.isGreaterThan(20); // true
Returns true if the value of the money object is greater than or equal to the given numeric or
money value
and returns false otherwise. If value
is numeric, it is converted into a money
object before making the comparison.
Examples:
var value1 = money.make(24.5);
var value2 = money.make(24.5);
var value3 = money.make(10);
var value4 = money.make(30);
value1.isGreaterThanOrEqualTo(value2); // true
value1.isGreaterThanOrEqualTo(value3); // true
value1.isGreaterThanOrEqualTo(value4); // false
value1.isGreaterThanOrEqualTo(24.502); // true
value1.isGreaterThanOrEqualTo(30); // false
Returns true if the value of the money object is less than the given numeric or money value
and returns false otherwise. If value
is numeric, it is converted into a money object before
making the comparison.
Examples:
var value1 = money.make(24.5);
var value2 = money.make(24.5);
var value3 = money.make(10);
var value4 = money.make(30);
value1.isLessThan(value2); // false
value1.isLessThan(value3); // false
value1.isLessThan(value4); // true
value1.isLessThan(24.502); // false
value1.isLessThan(30); // true
Returns true if the value of the money object is less than or equal to the given numeric or
money value
and returns false otherwise. If value
is numeric, it is converted into a money
object before making the comparison.
Examples:
var value1 = money.make(24.5);
var value2 = money.make(24.5);
var value3 = money.make(10);
var value4 = money.make(30);
value1.isLessThanOrEqualTo(value2); // true
value1.isLessThanOrEqualTo(value3); // false
value1.isLessThanOrEqualTo(value4); // true
value1.isLessThanOrEqualTo(24.502); // true
value1.isLessThanOrEqualTo(30); // true
Subtracts the given money or numeric value
from the money amount and returns the result as a
new money object.
Examples:
money.make(24.50).minus(10.503); // 14.00
var sales = money.make(100000);
var expenses = money.make(80000);
sales.minus(expenses); // 20,000.00
Returns the negative of the value of the money object as a new money object.
Examples:
money.make(24.50).negate(); // -24.50
money.make(-24.50).negate(); // 24.50
Adds the given money or numeric value
to the money amount and returns the result as a new
money object.
Examples:
money.make(24.50).plus(10.503); // 35.00
var sales = money.make(100000);
var otherIncome = money.make(2000);
sales.plus(otherIncome); // 102,000.00
Sets the value of the money object to the given numeric or money value
.
Examples:
var shipping = money.make();
var handling = money.make();
shipping.setValue(5).getValue(); // 5.00
handling.setValue(shipping).getValue(); // 5.00
Multiplies the money amount by the given numeric value
and returns the result as a new money object.
Examples:
money.make(24).times(10); // 240.00
var orderAmount = money.make(100);
var salesTaxRate = 0.05;
orderAmount.times(salesTaxRate); // 5.00
Returns a string which represents the money object's value.
-
symbol
Optional - A character that denotes the type of currency. For example, the symbol for U.S. dollars is "$". Pass a null string for no symbol. If not given, the default value is used. The inital default symbol is set to "$". To change the default symbol or to pass it to this method when specifying a subsequent argument (like decimalSeparator), see the defaults.currencySymbol() module function. -
negativeFormat
Optional - Specifies whether to indicate a negative value with a minus sign or parentheses. See the NEGATIVE_FORMATS constants. If not given, the default value is used. The inital default is to use a minus sign. To change the default or to pass it to this method when specifying a subsequent argument (like decimalSeparator), see the defaults.negativeFormat() module function. -
symbolPosition
Optional - Specifies where the currency symbol should appear. See the SYMBOL_POSITIONS constants. If not given, the default value is used. The inital default is to place the symbol in the front of the returned string. To change the default or to pass it to this method when specifying a subsequent argument (like decimalSeparator), see the defaults.symbolPosition() module function. -
thousandsSeparator
Optional - A character used to separate groups of 3 digits. For example, if the character is a comma, then a monetary amount of 12345.00 would return "12,345.00". If not given, the default value is used. The inital default separator is set to a comma ",". To change the default separator or to pass it to this method when specifying a subsequent argument (like decimalSeparator), see the defaults.thousandsSeparator() module function. -
decimalSeparator
Optional - A character used to separate the integer and decimal parts of the monetary amount. For example, if the character is a period, then a monetary amount of 12 would return "12.00". If not given, the default value is used. The inital default separator is set to a period ".". To change the default separator, see the defaults.decimalSeparator() module function.
toString() can call a function defined by the setFormatFunction() module function to set one or more of the formatting defaults each time toString() is called. This facilitates applying different formatting depending on the current calling environment. For example, toString() may be called for different users with different money format preferences. The function passed to setFormatFunction() can determine the correct format preferences for each user and pass them back to toString(). See the setFormatFunction() module function.
Examples:
var price = money.make(19.95);
price.toString(); // '$19.95'
price.toString(''); // '19.95'
price.toString('$', money.NEGATIVE_FORMATS.MINUS_SIGN, money.SYMBOL_POSITIONS.AFTER, '.', ','); // '19,95$'
money.defaults.currencySymbol(''); // default is no currency symbol
price.toString(); // '19.95'
Returns the default currency symbol when calling the toString() method. If the optional symbol
string argument is passed, sets the default currency symbol to the argument's value. The initial
default value is "$".
Examples:
money.defaults.currencySymbol(); // '$'
money.defaults.currencySymbol(''); // '', do not use a currency symbol by default
Returns the default decimal separator (a character used to separate the integer and decimal parts
of a monetary amount) when calling the toString() method. For example, if the character is a
period, then a monetary amount of 12 would return "12.00" from toString(). If the optional
separator
string argument is passed, sets the default separator to the argument's value. The
initial default value is a period ".".
Examples:
money.defaults.decimalSeparator(); // '.'
money.defaults.decimalSeparator(','); // ','
Returns the default negative format when calling the toString() method. If the optional format
argument is passed, sets the default format to the argument's value. See the NEGATIVE_FORMATS
constants for valid values. The initial default value is NEGATIVE_FORMATS.MINUS_SIGN
Examples:
money.defaults.negativeFormat(); // money.NEGATIVE_FORMATS.MINUS_SIGN
money.defaults.negativeFormat(money.NEGATIVE_FORMATS.PARENTHESES); // money.NEGATIVE_FORMATS.PARENTHESES
Returns the default symbol position when calling the toString() method. If the optional position
argument is passed, sets the default position to the argument's value. See the SYMBOL_POSITIONS
constants for valid values. The initial default value is SYMBOL_POSITIONS.BEFORE.
Examples:
money.defaults.symbolPosition(); // money.SYMBOL_POSITIONS.BEFORE
money.defaults.symbolPosition(money.SYMBOL_POSITIONS.AFTER); // money.SYMBOL_POSITIONS.AFTER
Returns the default thousands separator (a character used to separate groups of 3 digits) when
calling the toString() method. For example, if the character is a comma, then a monetary amount
of 12345.00 would return "12,345.00" from toString(). If the optional separator
string
argument is passed, sets the default separator to the argument's value. The initial
default value is a comma ",".
Examples:
money.defaults.thousandsSeparator(); // ','
money.defaults.thousandsSeparator('.'); // '.'
Returns true if the given object
is an instance of a money object and returns false
otherwise.
Examples:
var price = money.make(19.95);
money.isMoney(price); // true
money.isMoney(19.95); // false
Sets a function to be called each time the toString() method is called to set defaults for the format. This facilitates applying different formatting depending on the current calling environment. For example, toString() may be called for different users with different money format preferences. The function passed to setFormatFunction() can determine the correct format preferences for each user and pass them back to toString().
formatFunction
should return an object containing one or more of the following properties:
-
symbol
Optional - A character that denotes the type of currency. Example: '$'. -
negativeFormat
Optional - Specifies whether to indicate a negative value with a minus sign or parentheses. See the NEGATIVE_FORMATS constants. Example: money.NEGATIVE_FORMATS.PARENTHESES. -
symbolPosition
Optional - Specifies where the currency symbol should appear. See the SYMBOL_POSITIONS constants. Example: money.SYMBOL_POSITIONS.AFTER. -
thousandsSeparator
Optional - A character used to separate groups of 3 digits. For example, if the character is a comma, then money.make(12345).toString() would return "12,345.00". -
decimalSeparator
Optional - A character used to separate the integer and decimal parts of the monetary amount. For example, if the character is a period, then money.make(12).toString() would return "12.00".
Examples:
money.setFormatFunction (
function () {
// This is just an example. Normally, this function would return something other than static values.
return { symbol : '$',
negativeFormat : money.NEGATIVE_FORMATS.PARENTHESES,
symbolPosition : money.SYMBOL_POSITIONS.AFTER,
thousandsSeparator : '.',
decimalSeparator : ','
};
});
var netProfit = money.make(-12345.67);
netProfit.toString(); // '(12.345,67)$'
netProfit.toString('', money.NEGATIVE_FORMATS.MINUS_SIGN); // '-$12.345,67' (override symbol and negative format)
Returns a money object representing the sum of the given array of values
. Each value in the
array can be a number or a money object. Each numeric value is treated as a monetary value by
converting it to a money object before adding it to the total.
Examples:
var expenses = [money.make(10), money.make(20), 30.345];
money.sum(expenses); // 60.35
money uses Wakanda's implementation of YUI Test.
- In Wakanda Studio, open WebFolder/index/index.html.
- Click Run. The results should appear in your browser.
- In Wakanda Studio, open scripts/test.js.
- Click Run File. The results should appear in your browser.
If you contribute to this library, just modify WebFolder/scripts/money.js
and
WebFolder/scripts/testCases.js
or Modules/money.js
and Modules/money.js
and send a
pull request. Please remember to update the markdown if the public interface changes.
Licensed under MIT.
Copyright (C) 2013 Jeff Grann [email protected]
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.