@one-broker-services/money

A simple and tiny library for monetary operations

Usage no npm install needed!

<script type="module">
  import oneBrokerServicesMoney from 'https://cdn.skypack.dev/@one-broker-services/money';
</script>

README

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

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

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

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

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

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

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

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

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

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

fx(100, 1.55235) // 155.24
fx('100', 0.01) // 1
fx(100, 0.0000155235) // 0.01
fx(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

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

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

subtract(1.01, 0.99) // 0.02
subtract(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

add(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

fx(100, 1.55235) // 155.24
fx('100', 0.01) // 1
fx(100, 0.0000155235) // 0.01
fx(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

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