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

1npm -i @one-broker-services/money

How to use

1const money = require(`@one-broker-services/money`)
2
3const result = money. ... // for arithmetic
4const 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

recipes : object

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

recipes.partition(amount, parts) ⇒ Number

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

1partition(1,2) // [0.5,0.5]
2partition(1,3) // [0.34, 0.33, 0.33]
3partition(1,11) // [0.1,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09,0.09]
4partition(1,[50,50]) // [0.5,0.5]
5partition(0.01,[41,33,15,9,2]) //[0.01,0,0,0,0]
6partition(10,[41,33,15,9,2]) //[4.1,3.3,1.5,0.9,0.2]
7partition(100,"qwert") // ArgumentError: parts must be a positive integer or an array with a partition of 100
8partition(100,0) // ArgumentError: parts must be a positive integer or an array with a partition of 100
9partition(100,[50,49]) // ArgumentError: parts must be a positive integer or an array with a partition of 100

recipes.maxTax(amount, p, fee) ⇒ Number

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

recipes.applyDiscount(amount, p) ⇒ Number

Apply a percent discount to base amount

Kind: static method of recipes

Param	Type	Description
amount	Number | String	numeric value
p	Number	porcentual value

recipes.applyTax(amount, p) ⇒ Number

Apply a percent tax to base amount

Kind: static method of recipes

Param	Type	Description
amount	Number | String	numeric value
p	Number	porcentual value

recipes.applyMaxTax(amount, p, fee) ⇒ Number

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

recipes.applySumTax(amount, p, fee) ⇒ Number

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

value(amount, [decimals]) ⇒ Number

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

1value(10.253) // 10.26
2value('10.990001',4) // 10.9901
3value('10.990001') // 11.00
4value('abcd') // NaN
5value(null|undefined|any[]|object) // NaN

cents(amount) ⇒ Number

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

1cents(0.01) // 1
2cents(0.17) // 17
3cents('3.12') // 312
4cents(0.11001) // 12
5cents('abcd') // NaN
6cents(null|undefined|any[]|object) // NaN

cents2Amount(cents) ⇒ Number

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

1cents2Amount(157) // 1.57
2cents2Amount('5513') // 55.13
3cents2Amount(157) // 1.57
4cents2Amount('abcd') // NaN
5cents2Amount(null|undefined|any[]|object) // NaN
6cents2Amount(12.5) // ArgumentError: cents must be positive integer
7cents2Amount(-25) // ArgumentError: cents must be positive integer

fx(amount, fxRate, [decimals]) ⇒ Number

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

1fx(100, 1.55235) // 155.24
2fx('100', 0.01) // 1
3fx(100, 0.0000155235) // 0.01
4fx(100, 0.0000155235,4) // 0.0016

sum(...amounts) ⇒ Number

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

1sum(0.1,0.2) // 0.3
2sum(0.1,0.2,'-0.3') // 0
3sum([0.1,0.2,-0.3]) // 0
4sum(...['0.1','0.2','-0.3']) // 0
5sum('abcd','{a: 1}') // NaN

percent(amount, p) ⇒ Number

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

subtract(x, y) ⇒ Number

Difference of two amounts

Kind: global function
Returns: Number - Monetary value of amount1 - amount2

Param	Type	Description
x	Number	amount1
y	Number	amount2

Example

1subtract(1.01, 0.99) // 0.02
2subtract(23.42, 19.13) // 4.29

add(x, y) ⇒ Number

add two amounts

Kind: global function
Returns: Number - Monetary value of amount1 + amount2

Param	Type	Description
x	Number	amount1
y	Number	amount2

Example

1add(0.1, 0.2) // 0.03

multiply(amount, [factor], [decimals]) ⇒ Number

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

1fx(100, 1.55235) // 155.24
2fx('100', 0.01) // 1
3fx(100, 0.0000155235) // 0.01
4fx(100, 0.0000155235,4) // 0.0016

divide(amount, [divisor], [decimals]) ⇒ Number

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

1divide(123.451, 1) // 123.46
2divide(123.45 , 2) // 61.73
3divide(123.451 , 2) // 61.73
4divide('123.451' , 2) // 61.73
5divide(10 , 0) // ArgumentError: cant divide by zero
6divide('abcd' , 2) // NaN
7divide(null|undefined|any[]|object , 1) // NaN

Tests

1npm run test