Decimal math

jg-bignumber

Exact decimal math on bignumber.js: rounding modes, formatting, and financial calculations such as percentage changes.

v1.4.0UniversalESMMIT

npm install jg-bignumber

pnpm add jg-bignumber

On this page

Usage

Every calculation is exact, then rounded to 2 decimal places with ROUND_HALF_UP and returned as a number, unless the configuration asks otherwise:

import { calculateSum, processValue, prettifyValue } from 'jg-bignumber';

calculateSum([0.1, '0.2', 0.3]); // 0.6, not 0.6000000000000001
processValue(512.155); // 512.16
processValue(19.991, { roundingMode: 'ROUND_CEIL' }); // 20
processValue('0.000001', { decimalPlaces: 6, type: 'string' }); // '0.000001'
prettifyValue(1234.5, { format: { prefix: '$' } }); // '$1,234.5'
prettifyValue(1234.5, { format: { prefix: '$', minimumDecimalPlaces: 2 } }); // '$1,234.50'
prettifyValue(-5, { format: { prefix: '$' } }); // '-$5'

Percentages and money:

import {
  adjustByPercentage,
  calculateExchange,
  calculatePercentageChange,
  calculateWeightedEntry,
} from 'jg-bignumber';

calculatePercentageChange(100, 125); // 25
adjustByPercentage(100, -10); // 90
calculateExchange(100, 65000, { decimalPlaces: 8 }); // 0.00153846
calculateWeightedEntry([
  [100, 2],
  [130, 1],
]); // 110, the average price weighted by amount

Store money as an integer count of its smallest unit, such as microcents in a PostgreSQL BIGINT, and convert it exactly, never rounding:

import { applyBasisPoints, fromScaledInteger, toScaledInteger } from 'jg-bignumber';

toScaledInteger('1.23', 8); // 123000000n
toScaledInteger('0.123456789', 8); // throws INVALID_VALUE: the 9th decimal would be lost
toScaledInteger(1e-8, 8); // throws INVALID_VALUE: JavaScript writes it as '1e-8'
fromScaledInteger(123000000n, 8); // '1.23000000'
applyBasisPoints(100000000n, 500); // 5000000n: a 5% commission, rounded down to a whole unit

BigNumber is the package’s own bignumber.js constructor, so creating values with it never changes the global bignumber.js configuration.

Generated from TSDoc

API reference

Every export of [email protected], 33 in all, with its signature, its errors, and an example.

Functions

adjustByPercentage

function

Changes a value by a percentage: a positive percentage increases it, and a negative one decreases it, to 0 at most. A value of 0 stays 0.

Signature

adjustByPercentage<T extends Partial<IConfig>>(
  value: Value,
  percentage: Value,
  config?: T,
): IOutput<T>

Parameters

valueValue: The value to change.
percentageValue: The percentage to change it by.
config?T: How the result is processed.

Returns

IOutput<T>

The changed value.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
NEGATIVE_VALUE_NOT_ALLOWEDif the value is negative

Example

import { adjustByPercentage } from 'jg-bignumber';

adjustByPercentage(100, 25); // => 125
adjustByPercentage(100, -10); // => 90

Applies a rate in basis points to an integer count of an amount's smallest unit, such as a 5% commission on a payment in microcents, rounding down to a whole unit, so the result never exceeds what the rate gives. 100 basis points are 1%, and 10,000 are 100%.

Signature

applyBasisPoints(value: bigint, basisPoints: number): bigint

Parameters

valuebigint: The amount in the smallest unit, 0 or more.
basisPointsnumber: The rate, a non-negative safe integer; it may exceed 10,000 for more than 100%.

Returns

bigint

value × basisPoints / 10,000, rounded down.

Throws

INVALID_VALUEThe value must be a bigint.
NEGATIVE_VALUE_NOT_ALLOWEDThe value must be greater than or equal to 0.
INVALID_VALUEThe basis points must be a non-negative safe integer.

Example

import { applyBasisPoints } from 'jg-bignumber';

applyBasisPoints(100_000_000n, 500); // => 5000000n
applyBasisPoints(123_000_000n, 1500); // => 18450000n
applyBasisPoints(10_001n, 1); // => 1n

calculateExchange

function

Calculates the amount of an asset an exchange gives for a value at a rate, such as how much BTC 100 USDT buys at 65,000 USDT per BTC.

Signature

calculateExchange<T extends Partial<IConfig>>(
  value: Value,
  rate: Value,
  config?: T,
): IOutput<T>

Parameters

valueValue: The amount being exchanged.
rateValue: The price of one unit of the asset received.
config?T: How the result is processed.

Returns

IOutput<T>

The amount received.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
NEGATIVE_VALUE_NOT_ALLOWEDif the value or rate are not positive

Example

import { calculateExchange } from 'jg-bignumber';

calculateExchange(100, 65000, { decimalPlaces: 8 }); // => 0.00153846

calculateExchangeFee

function

Calculates the fee charged for an exchange, as a percentage of the value exchanged.

Signature

calculateExchangeFee<T extends Partial<IConfig>>(
  value: Value,
  feePercentage: Value,
  config?: T,
): IOutput<T>

Parameters

valueValue: The amount being exchanged.
feePercentageValue: The fee, as a percentage.
config?T: How the result is processed.

Returns

IOutput<T>

The fee.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
NEGATIVE_VALUE_NOT_ALLOWEDif the value or feePercentage are not positive

Example

import { calculateExchangeFee } from 'jg-bignumber';

calculateExchangeFee(1000, 0.1); // => 1

calculateMax

function

Finds the largest value in a list. An empty list returns 0.

Signature

calculateMax<T extends Partial<IConfig>>(
  values: Value[],
  config?: T,
): IOutput<T>

Parameters

valuesValue[]: The values.
config?T: How the result is processed.

Returns

IOutput<T>

The largest value.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateMax } from 'jg-bignumber';

calculateMax([3, '1.5', 2]); // => 3

calculateMean

function

Calculates the mean of a list of values. An empty list returns 0.

Signature

calculateMean<T extends Partial<IConfig>>(
  values: Value[],
  config?: T,
): IOutput<T>

Parameters

valuesValue[]: The values.
config?T: How the result is processed.

Returns

IOutput<T>

The mean.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateMean } from 'jg-bignumber';

calculateMean([1, 2, 4]); // => 2.33

calculateMedian

function

Calculates the median of a list of values: the middle value, or the mean of the two middle values when the list has an even length. An empty list returns 0.

Signature

calculateMedian<T extends Partial<IConfig>>(
  values: Value[],
  config?: T,
): IOutput<T>

Parameters

valuesValue[]: The values.
config?T: How the result is processed.

Returns

IOutput<T>

The median.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateMedian } from 'jg-bignumber';

calculateMedian([5, 1, 3]); // => 3
calculateMedian([4, 1, 3, 2]); // => 2.5

calculateMin

function

Finds the smallest value in a list. An empty list returns 0.

Signature

calculateMin<T extends Partial<IConfig>>(
  values: Value[],
  config?: T,
): IOutput<T>

Parameters

valuesValue[]: The values.
config?T: How the result is processed.

Returns

IOutput<T>

The smallest value.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateMin } from 'jg-bignumber';

calculateMin([3, '1.5', 2]); // => 1.5

calculatePercentageChange

function

Calculates the percentage a value changed by: positive when it increased, negative when it decreased, and 0 when it didn't change. The largest decrease is -100%, returned whenever the new value is 0 or less.

Signature

calculatePercentageChange<T extends Partial<IConfig>>(
  oldValue: Value,
  newValue: Value,
  config?: T,
): IOutput<T>

Parameters

oldValueValue: The value before the change.
newValueValue: The value after the change.
config?T: How the result is processed.

Returns

IOutput<T>

The percentage change.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
NEGATIVE_VALUE_NOT_ALLOWEDif the oldValue is not positive

Example

import { calculatePercentageChange } from 'jg-bignumber';

calculatePercentageChange(100, 125); // => 25
calculatePercentageChange(100, 80); // => -20
calculatePercentageChange(100, 0); // => -100

calculatePercentageRepresentation

function

Calculates what percentage of a total a value represents.

Signature

calculatePercentageRepresentation<T extends Partial<IConfig>>(
  value: Value,
  total: Value,
  config?: T,
): IOutput<T>

Parameters

valueValue: The part.
totalValue: The total.
config?T: How the result is processed.

Returns

IOutput<T>

The percentage.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
NEGATIVE_VALUE_NOT_ALLOWEDif the value or total are not positive

Example

import { calculatePercentageRepresentation } from 'jg-bignumber';

calculatePercentageRepresentation(25, 200); // => 12.5

calculateSum

function

Adds up a list of values. An empty list sums to 0.

Signature

calculateSum<T extends Partial<IConfig>>(
  values: Value[],
  config?: T,
): IOutput<T>

Parameters

valuesValue[]: The values.
config?T: How the result is processed.

Returns

IOutput<T>

The sum.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateSum } from 'jg-bignumber';

calculateSum([0.1, '0.2', 0.3]); // => 0.6
calculateSum([0.1, 0.2], { type: 'string' }); // => '0.3'

calculateWeightedEntry

function

Calculates the average entry price of a position bought in several trades, weighting each price by the amount bought. An empty list, or one whose amounts add up to 0, returns 0.

Signature

calculateWeightedEntry<T extends Partial<IConfig>>(
  trades: [Value, Value][],
  config?: T,
): IOutput<T>

Parameters

trades[Value, Value][]: The trades, each as a [price, amount] tuple.
config?T: How the result is processed.

Returns

IOutput<T>

The weighted average price.

Throws

INVALID_VALUEif any of the given values isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_VALUES_ARRAYif the provided values arg is not a valid array

Example

import { calculateWeightedEntry } from 'jg-bignumber';

calculateWeightedEntry([[100, 2], [130, 1]]); // => 110
calculateWeightedEntry([]); // => 0

fromScaledInteger

function

Converts an integer count of an amount's smallest unit, such as microcents, back to the amount as an exact decimal string, with all decimals digits and no symbol, separators, or rounding. Pass it to prettifyValue to show it to people.

Signature

fromScaledInteger(value: string | bigint, decimals: number): string

Parameters

valuestring | bigint: The amount in the smallest unit, as a bigint or an integer string, such as a PostgreSQL BIGINT. A string may have surrounding spaces and a sign.
decimalsnumber: How many decimals the smallest unit has, such as 8 for microcents.

Returns

string

The amount.

Throws

INVALID_VALUEif the value isn't a bigint or an integer string
INVALID_DECIMAL_PLACESif decimals isn't an integer from 0 to 100

Example

import { fromScaledInteger } from 'jg-bignumber';

fromScaledInteger(123000000n, 8); // => '1.23000000'
fromScaledInteger('-1', 8); // => '-0.00000001'
fromScaledInteger(1250n, 0); // => '1250'

getBigNumber

function

Creates a BigNumber from a number, a numeric string, or a BigNumber, which is returned as is. Only finite values are accepted: NaN and ±Infinity are rejected.

Signature

getBigNumber(value: Value): BigNumber

Parameters

valueValue: The value.

Returns

BigNumber

The BigNumber.

Throws

INVALID_VALUEif the value isn't a finite number or BigNumber throws an error

Example

import { getBigNumber } from 'jg-bignumber';

getBigNumber('0.1').plus('0.2').toString(); // => '0.3'

isBigNumber

function

Checks whether a value is a BigNumber instance, from this package or any other copy of bignumber.js.

Signature

isBigNumber(value: unknown): value is BigNumber

Parameters

valueunknown: The value.

Returns

value is BigNumber

Whether it's a BigNumber.

Example

import { getBigNumber, isBigNumber } from 'jg-bignumber';

isBigNumber(getBigNumber(1)); // => true
isBigNumber(1); // => false

isFloat

function

Checks whether a value is a finite number with a fractional part, in any of the supported types.

Signature

isFloat(value: unknown): boolean

Parameters

valueunknown: The value.

Returns

boolean

Whether it's a float.

Example

import { isFloat } from 'jg-bignumber';

isFloat(12.5); // => true
isFloat('12'); // => false

isInteger

function

Checks whether a value is a finite integer, in any of the supported types.

Signature

isInteger(value: unknown): boolean

Parameters

valueunknown: The value.

Returns

boolean

Whether it's an integer.

Example

import { isInteger } from 'jg-bignumber';

isInteger('12'); // => true
isInteger(12.5); // => false

isNumber

function

Checks whether a value is a finite number, numeric string, or BigNumber.

Signature

isNumber(value: unknown): boolean

Parameters

valueunknown: The value.

Returns

boolean

Whether it's a finite number.

Example

import { isNumber } from 'jg-bignumber';

isNumber('12.5'); // => true
isNumber(Infinity); // => false
isNumber('abc'); // => false

prettifyValue

function

Processes a value and formats it for people, with group separators, a prefix, and a suffix. Trailing zeros are dropped, unless format.minimumDecimalPlaces keeps them. The sign goes before the prefix, as in -$5.

Signature

prettifyValue(
  value: Value,
  config?: { processing?: Partial<IConfig>; format?: IPrettifyFormat },
): string

Parameters

valueValue

The value.

config?{ processing?: Partial<IConfig>; format?: IPrettifyFormat }

How the value is processed and formatted.

Defaults to {}.

Returns

string

The formatted value.

Throws

INVALID_VALUEif the value isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported
INVALID_BIGNUMBER_FORMATif any of the format properties are invalid, or minimumDecimalPlaces
Errorexceeds decimalPlaces

Example

import { prettifyValue } from 'jg-bignumber';

prettifyValue(1234567.891); // => '1,234,567.89'
prettifyValue(1234.5, { format: { prefix: '$' } }); // => '$1,234.5'
prettifyValue(1234.5, { format: { prefix: '$', minimumDecimalPlaces: 2 } }); // => '$1,234.50'
prettifyValue(-5, { format: { prefix: '$' } }); // => '-$5'

processValue

function

Rounds a value and returns it as the type the configuration asks for: a number by default, or a string or a BigNumber.

Signature

processValue<T extends Partial<IConfig>>(
  value: Value,
  configuration?: T,
): IOutput<T>

Parameters

valueValue: The value.
configuration?T: The decimal places, rounding mode, and output type.

Returns

IOutput<T>

The processed value.

Throws

INVALID_VALUEif the value isn't a finite number or BigNumber throws an error
INVALID_DECIMAL_PLACESif the number of decimal places is invalid for any reason
INVALID_ROUNDING_MODEif the rounding mode name is not supported
INVALID_TYPEif the processing type is not supported

Example

import { processValue } from 'jg-bignumber';

processValue(512.155); // => 512.16
processValue(512.155, { decimalPlaces: 1, roundingMode: 'ROUND_FLOOR' }); // => 512.1
processValue('0.000001', { decimalPlaces: 6, type: 'string' }); // => '0.000001'

toScaledInteger

function

Converts an amount, such as dollars, to an integer count of its smallest unit, such as microcents with 8 decimals, so it can be stored and added up exactly, as in a PostgreSQL BIGINT. It takes a number or a plain decimal string, with surrounding spaces and a leading + allowed, and never rounds: scientific notation, including a number JavaScript writes that way, such as 0.00000001, hex, malformed values, and digits beyond decimals other than trailing zeros are rejected. Only the text is read, so 0.1 + 0.2, which is 0.30000000000000004, fails rather than becoming a slightly wrong amount.

Signature

toScaledInteger(value: string | number, decimals: number): bigint

Parameters

valuestring | number: The amount.
decimalsnumber: How many decimals the smallest unit has, such as 8 for microcents.

Returns

bigint

The amount in the smallest unit.

Throws

INVALID_VALUEif the value isn't a plain decimal, or has more decimals than `decimals`
INVALID_DECIMAL_PLACESif decimals isn't an integer from 0 to 100

Example

import { toScaledInteger } from 'jg-bignumber';

toScaledInteger('1.23', 8); // => 123000000n
toScaledInteger(' +0.00000001 ', 8); // => 1n
toScaledInteger(-12.5, 2); // => -1250n

Constants

BigNumber

const

The BigNumber constructor every function uses: a clone of bignumber.js's, so the package never changes the global bignumber.js configuration other code relies on. It never switches to exponential notation, and with STRICT off an invalid value becomes NaN instead of throwing, which the package then reports as INVALID_VALUE.

Declaration

const BigNumber: typeof BigNumber

ERRORS

const

the codes of every error the package throws

Declaration

const ERRORS: { INVALID_VALUE: "INVALID_VALUE"; INVALID_TYPE: "INVALID_TYPE"; INVALID_ROUNDING_MODE: "INVALID_ROUNDING_MODE"; INVALID_DECIMAL_PLACES: "INVALID_DECIMAL_PLACES"; INVALID_BIGNUMBER_FORMAT: "INVALID_BIGNUMBER_FORMAT"; INVALID_VALUES_ARRAY: "INVALID_VALUES_ARRAY"; NEGATIVE_VALUE_NOT_ALLOWED: "NEGATIVE_VALUE_NOT_ALLOWED" }

type IConfig = {
    decimalPlaces: number;
    roundingMode: IBigNumberRoundingModeName;
    type: IType;
};

Members

decimalPlacesproperty
number
the maximum number of decimals in the output. Defaults to 2
roundingModeproperty
IBigNumberRoundingModeName
how the value is rounded when it has more decimals. Defaults to 'ROUND_HALF_UP'
typeproperty
IType
the output's type. Defaults to 'number'

IOutput

type

the return type of a function that processes a value, picked from its configuration's type

Declaration

type IOutput<T> = T extends {
    type: 'string';
} ? string : T extends {
    type: 'number';
} ? number : T extends {
    type: 'bignumber';
} ? IBigNumber : number;

IPrettifyFormat

type

The format prettifyValue takes: any of bignumber.js's toFormat settings, and the fewest decimals it shows, padded with trailing zeros, such as 2 for '$1,234.50'. minimumDecimalPlaces defaults to 0, and can't exceed the processing's decimalPlaces.

Declaration

type IPrettifyFormat = Partial<IBigNumberFormat> & {
    minimumDecimalPlaces?: number;
};

IType

type

the type a processed value is returned as

Declaration

type IType = 'string' | 'number' | 'bignumber';