Description
A simple and tiny library with no dependencies for monetary arithmetic. Solves javascript rounding problems and guarantees proper rounding to cents.
Recipes for useful operations included.
Instalation
npm -i @one-broker-services/money
How to use
const money = require(`@one-broker-services/money`)
const result = money. ... // for arithmetic
const result = money.recipes. ... // for recipes
Objects
-
recipes :
object
Functions
-
value(amount, [decimals]) ⇒
Number
-
Compute currency value from Number
-
cents(amount) ⇒
Number
-
Compute cents value from Number
-
cents2Amount(cents) ⇒
Number
-
Compute currency amount from cents
-
fx(amount, fxRate, [decimals]) ⇒
Number
-
Apply fx rate to currency amount
-
sum(...amounts) ⇒
Number
-
Aggregate amounts
-
percent(amount, p) ⇒
Number
-
Compute an amount fraction from a percent value
-
subtract(x, y) ⇒
Number
-
Difference of two amounts
-
add(x, y) ⇒
Number
-
add two amounts
-
multiply(amount, [factor], [decimals]) ⇒
Number
-
Multiply an amount by a factor
-
divide(amount, [divisor], [decimals]) ⇒
Number
-
Divide an amount by a divisor
object
recipes : Kind: global namespace
Summary: Recipes
Access: public
-
recipes :
object
-
.partition(amount, parts) ⇒
Number
-
.maxTax(amount, p, fee) ⇒
Number
-
.applyDiscount(amount, p) ⇒
Number
-
.applyTax(amount, p) ⇒
Number
-
.applyMaxTax(amount, p, fee) ⇒
Number
-
.applySumTax(amount, p, fee) ⇒
Number
-
.partition(amount, parts) ⇒
Number
recipes.partition(amount, parts) ⇒ Compute an amount partition
Kind: static method of recipes
Throws:
- Will throw an error if parts arguments is not a positive integer or is not a partition of 100
-
ArgumentError
parts must be a positive integer or an array with a partition of 100
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
parts |
Number | Array.<Number>
|
integer or percent partition (array of percent parts) |
Example
partition(1,2) // [0.5,0.5]
partition(1,3) // [0.34, 0.33, 0.33]
partition(1,11) // [0.1,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09]
partition(1,[50,50]) // [0.5,0.5]
partition(0.01,[41,33,15,9,2]) //[0.01,0,0,0,0]
partition(10,[41,33,15,9,2]) //[4.1,3.3,1.5,0.9,0.2]
partition(100,"qwert") // ArgumentError: parts must be a positive integer or an array with a partition of 100
partition(100,0) // ArgumentError: parts must be a positive integer or an array with a partition of 100
partition(100,[50,49]) // ArgumentError: parts must be a positive integer or an array with a partition of 100
Number
recipes.maxTax(amount, p, fee) ⇒ Compute tax to base amount, follow max policy from percent value and fee value
Kind: static method of recipes
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
p | Number |
porcentual value |
fee | Number |
numeric value |
Number
recipes.applyDiscount(amount, p) ⇒ Apply a percent discount to base amount
Kind: static method of recipes
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
p | Number |
porcentual value |
Number
recipes.applyTax(amount, p) ⇒ Apply a percent tax to base amount
Kind: static method of recipes
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
p | Number |
porcentual value |
Number
recipes.applyMaxTax(amount, p, fee) ⇒ Apply tax to base amount, follow max policy from percent value and fee value
Kind: static method of recipes
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
p | Number |
porcentual value |
fee | Number |
numeric value |
Number
recipes.applySumTax(amount, p, fee) ⇒ Apply tax to base amount, follow sum policy from percent value and fee value
Kind: static method of recipes
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
p | Number |
porcentual value |
fee | Number |
numeric value |
Number
value(amount, [decimals]) ⇒ Compute currency value from Number
Kind: global function
Returns: Number
- Monetary value of amount
Access: public
Param | Type | Default | Description |
---|---|---|---|
amount |
Number | String
|
numeric value | |
[decimals] | Number |
2 |
integer |
Example
value(10.253) // 10.26
value('10.990001',4) // 10.9901
value('10.990001') // 11.00
value('abcd') // NaN
value(null|undefined|any[]|object) // NaN
Number
cents(amount) ⇒ Compute cents value from Number
Kind: global function
Returns: Number
- Monetary value in cents of amount
Access: public
Param | Type | Description |
---|---|---|
amount |
Number | String
|
numeric value |
Example
cents(0.01) // 1
cents(0.17) // 17
cents('3.12') // 312
cents(0.11001) // 12
cents('abcd') // NaN
cents(null|undefined|any[]|object) // NaN
Number
cents2Amount(cents) ⇒ Compute currency amount from cents
Kind: global function
Returns: Number
- Monetary value of cents
Throws:
- Will throw an error if the argument is negative or not integer.
-
ArgumentError
cents must be positive integer
Access: public
Param | Type | Description |
---|---|---|
cents |
Number | String
|
numeric value (positive integer) |
Example
cents2Amount(157) // 1.57
cents2Amount('5513') // 55.13
cents2Amount(157) // 1.57
cents2Amount('abcd') // NaN
cents2Amount(null|undefined|any[]|object) // NaN
cents2Amount(12.5) // ArgumentError: cents must be positive integer
cents2Amount(-25) // ArgumentError: cents must be positive integer
Number
fx(amount, fxRate, [decimals]) ⇒ Apply fx rate to currency amount
Kind: global function
Returns: Number
- Monetary value of amount*fxRate
Access: public
Param | Type | Default | Description |
---|---|---|---|
amount |
Number | String
|
numeric value | |
fxRate | Number |
number | |
[decimals] | Number |
2 |
integer |
Example
fx(100, 1.55235) // 155.24
fx('100', 0.01) // 1
fx(100, 0.0000155235) // 0.01
fx(100, 0.0000155235,4) // 0.0016
Number
sum(...amounts) ⇒ Aggregate amounts
Kind: global function
Returns: Number
- Monetary value of total amount
Access: public
Param | Type | Description |
---|---|---|
...amounts |
Number | String | Array.<Number> | Array.<String>
|
numeric values |
Example
sum(0.1,0.2) // 0.3
sum(0.1,0.2,'-0.3') // 0
sum([0.1,0.2,-0.3]) // 0
sum(...['0.1','0.2','-0.3']) // 0
sum('abcd','{a: 1}') // NaN
Number
percent(amount, p) ⇒ Compute an amount fraction from a percent value
Kind: global function
Returns: Number
- Monetary value of amount*p/100
Access: public
Param | Type | Description |
---|---|---|
amount | Number |
base amount value |
p | Number |
percent value |
Number
subtract(x, y) ⇒ Difference of two amounts
Kind: global function
Returns: Number
- Monetary value of amount1 - amount2
Param | Type | Description |
---|---|---|
x | Number |
amount1 |
y | Number |
amount2 |
Example
subtract(1.01, 0.99) // 0.02
subtract(23.42, 19.13) // 4.29
Number
add(x, y) ⇒ add two amounts
Kind: global function
Returns: Number
- Monetary value of amount1 + amount2
Param | Type | Description |
---|---|---|
x | Number |
amount1 |
y | Number |
amount2 |
Example
add(0.1, 0.2) // 0.03
Number
multiply(amount, [factor], [decimals]) ⇒ Multiply an amount by a factor
Kind: global function
Returns: Number
- Monetary value of amount*factor
Param | Type | Default | Description |
---|---|---|---|
amount |
Number | String
|
numeric value | |
[factor] | Number |
1 |
integer |
[decimals] | Number |
2 |
integer |
Example
fx(100, 1.55235) // 155.24
fx('100', 0.01) // 1
fx(100, 0.0000155235) // 0.01
fx(100, 0.0000155235,4) // 0.0016
Number
divide(amount, [divisor], [decimals]) ⇒ Divide an amount by a divisor
Kind: global function
Returns: Number
- Monetary value of amount/factor
Throws:
- Will throw an error if the divisor is zero.
-
ArgumentError
cant divide by zero
Param | Type | Default | Description |
---|---|---|---|
amount |
Number | String
|
numeric value | |
[divisor] | Number |
1 |
integer |
[decimals] | Number |
2 |
integer |
Example
divide(123.451, 1) // 123.46
divide(123.45 , 2) // 61.73
divide(123.451 , 2) // 61.73
divide('123.451' , 2) // 61.73
divide(10 , 0) // ArgumentError: cant divide by zero
divide('abcd' , 2) // NaN
divide(null|undefined|any[]|object , 1) // NaN
Tests
npm run test