big.js literal

Small library that improves big.js complex expressions readability.

import Big from "big.js";
import b from "bigjs-literal";

const x = Big(0.1);
const y = 0.2;
const z = "0.3";

// Instead of this:
const res1 = Big(0.5).times(Big(x)).plus(Big(y).div(Big(z).plus(Big(3))));

// You can write this:
const res2 = b`0.5 * ${x} + ${y} / (${z} + 3)`;

res1.eq(res2); // true

Install

Make sure you have big.js installed:

$ npm install --save big.js bigjs-literal

Usage

Use the template literal to write your expressions, interpolations will safelly be treated as Big.js objects.

import b from "bigjs-literal";

// Same as new Big(0.1).plus(new Big(0.2))
b`0.1 + 0.2`

// Same as new Big(1).plus(new Big(10.5))
b`1 + ${10.5}`

// Precedence rules are properly followed
// Big(2).plus(Big(4).times(Big(3)))
b`2 + 4 * 3`

// Expressions can be as complex as you like
b`(14 * 3) + 5 / ${10.5} - 2 * ${"3.5521"}`

// Same as new Big(1).mod(new Big(10.5))
b`1 % ${10.5}`

// Comparators are also supported
b`1 == 1`
b`2 >= ${1}`
b`2 gte 1`

// bigjs prototype functions use prefix notation
b`sqrt(9) + abs(-10)`

// As you might expect, you can chain all other big.js methods
b`0.1 + 0.2`.times(3).toFixed(2) === "0.90"

All binary operations can be written using infix notation:

b`1 plus 2`
b`1 minus 2`
b`2 times 5`
b`2 pow 2`

There are also operators for both pow and mod:

// Same as new Big(2).pow(4)
b`2 ^ 4`
b`2 ** 4`

// Same as new Big(10).mod(new Big(3))
b`10 % 3`

Performance

Since we have to parse the expression in runtime, code using this library will perform worse than pure big.js expressions.

This performance impact can be eliminated by using a Babel. The library comes with a macro that will parse and transform the expressions during Babel compilation.

To use the macro, add the babel-plugin-macros plugin and import the library as bigjs-literal/macro. Note that if you are using create-react-app) the babel-plugin-macros is already included by default.

import b from "bigjs-literal/macro";

// This will be parsed in compile time
b`(14 * 3) + 5 / ${10.5} - 2 * ${"3.5521"}`