Skip to content

# TehShrike/financial-number

Do math with money! Without risking loss of data to floating point representations!
JavaScript
Latest commit 6c14cc7 May 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information. test Feb 13, 2019 .gitignore May 21, 2019 .npmignore .travis.yml Apr 4, 2018 index.js Feb 13, 2019 package-lock.json May 21, 2019 package.json May 21, 2019 readme.md Aug 16, 2018 rollup.config.js May 21, 2019

### readme.md

A number object that is safe to use for financial numbers. Won't ever convert your numbers to floating point!

If you're doing math on financial numbers - invoice items, tax rates, those sorts of things - you can't ever afford to represent your numbers with floating point numbers.

Store them as fixed-point types in the database, and in JavaScript, pass them around as strings to keep from possibly losing data.

Looking on npm I only found one other module that didn't taint values by converting them to or from the Number type, and it's hard-coded to a precision of two digits after the decimal point.

So I made this library. It is built on financial-arithmetic-functions, which is in turn built on the jsbn library.

I will add more methods as I need them. If you run into an operation you need that is not yet implemented, feel free to open a pull request.

## Precision

This library increases the precision of the result based on its inputs.

With multiplication, the number of digits after the decimal point is the sum of the precision of both operands, e.g. `12.00 * 5.0` is `60.000`.

Addition and subtraction always result in the precision of the highest-precision of the operands: `12.00 + 5` is `17.00`.

### Rounding

Even if you calculate the `15%` tax on a `99.99\$` item to be `114.9885\$`, that's not what you're going to print on the invoice or save to the database.

#### For display or storage

When you call `toString` to get a value to show the user, or to save in the database, you have the option of passing in a precision for the number to be displayed as.

By default, numbers will be trimmed - `number('114.9885').toString(2)` will return `114.98`.

If you prefer rounding, you can pass in the provided rounding strategy: `number('114.9885').toString(2, number.round)` will produce `114.99`.

If your business requirements call for a different rounding strategy, you can provide your own. I would be happy to help you write it if you open an issue.

#### For calculation purposes

Say somebody buys `0.50` pounds of peanuts at `5.99` a pound, their subtotal would be `2.9950`. You could calculate tax based on that subtotal, but that could produce a tax a penny different from what the user would calculate themselves based on the `2.99` subtotal printed on their receipt.

When you need to change the precision in cases like this, you can use the `changePrecision` function, which takes the new precision (and an optional rounding strategy like `toString`). Like `toString`, it defaults to trimming.

```var subtotal = number('2.9950').changePrecision(2)
subtotal.toString() // => '2.99'```

## Usage

`npm install financial-number`, `var number = require('financial-number')`

```number('11.0').minus('9').times('3.75').toString() // => '7.500'
number('99.99').times('1.15').gt('100') // => true
```

## API

• `number(string)`
`var numberValue = number('50.0')`

Pass in the string representation of a number, get back a financial number object.

Financial numbers are immutable, and functions return a new number object.

Financial number objects have these methods. The operations and comparisons all take strings, or financial number objects.

### Operations

• `numberValue.plus(num)`
• `numberValue.minus(num)`
• `numberValue.times(num)`

### Comparisons

They return true or false.

• `numberValue.gt(num)`
• `numberValue.gte(num)`
• `numberValue.lt(num)`
• `numberValue.lte(num)`
• `numberValue.equal(num)`

### Other utility methods

#### `numberValue.changePrecision(newPrecision, [roundingStrategy])`

Takes a new precision, and an optional rounding strategy. Returns a new number object. See Rounding

`number('14.556').changePrecision(2, number.trim).toString() // => '14.55'`

#### `numberValue.toString([[displayPrecision], roundingStrategy])`

Returns a string representation of the number for display or storage. You can specify the precision and rounding strategy to be passed to `changePrecision` if you like - by default, the number will display at its current precision. See Rounding

`number('99.99').toString() // => '99.99'`

#### `numberValue.getPrecision()`

`number('99.99').getPrecision() // => 2`

#### `numberValue.isNegative()`

```number('13').isNegative() // => false
number('13').times('-1').isNegative() // => true```

## Running the tests/contributing

```git clone https://github.com/TehShrike/financial-number.git
cd financial-number
npm install
npm test```

## Other

I never use `this`, so you don't have to mess around with `bind` to do whatever wacky functional things you want, like this:

`var halved = ['10', '13', '50'].map(number('0.5').times)`

Licensed WTFPL

You can’t perform that action at this time.