bigmath

This module provides mathematical utility functions for working with BigInt values, offering operations like absolute value, multiplication with division, min/max calculations, averaging, and various rounding strategies.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

Methods

All methods are accessed through the bigMath object exported from @gmx-io/sdk/utils/bigmath. Import it once and call any method directly.

abs

abs(x: bigint): bigint

Returns the absolute value of a bigint.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.abs(-100n); // 100n
bigMath.abs(50n); // 50n

mulDiv

mulDiv(x: bigint, y: bigint, z: bigint, roundUpMagnitude?: boolean): bigint

Computes (x * y) / z. When roundUpMagnitude is true and there is a nonzero remainder (checked via mulmod), the result rounds away from zero by adding 1n. Default is false.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.mulDiv(100n, 3n, 2n); // 150n
bigMath.mulDiv(100n, 3n, 7n, true); // 43n (rounds up from 42.857...)

max

max(first: bigint, ...rest: bigint[]): bigint

Returns the largest value from the provided bigint arguments.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.max(10n, 25n, 5n, 100n); // 100n
bigMath.max(42n); // 42n

min

min(first: bigint, ...rest: bigint[]): bigint

Returns the smallest value from the provided bigint arguments.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.min(10n, 25n, 5n, 100n); // 5n
bigMath.min(42n); // 42n

avg

avg(...values: (bigint | undefined)[]): bigint | undefined

Computes the average of the provided bigint values, ignoring undefined entries. Returns undefined if no valid values are provided (truncates fractional result using integer division).

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.avg(10n, 20n, 30n); // 20n
bigMath.avg(10n, undefined, 30n); // 20n (undefined ignored)
bigMath.avg(undefined, undefined); // undefined

divRound

divRound(x: bigint, y: bigint): bigint

Divides x by y, rounding to the nearest integer. Rounds up when the remainder is more than half the divisor.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.divRound(7n, 3n); // 2n (remainder 1, less than half of 3)
bigMath.divRound(8n, 3n); // 3n (remainder 2, more than half of 3)

divRoundUp

divRoundUp(x: bigint, y: bigint): bigint

Divides x by y, always rounding up (ceiling division). Equivalent to (x + y - 1n) / y.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.divRoundUp(7n, 3n); // 3n (ceiling of 2.33...)
bigMath.divRoundUp(6n, 3n); // 2n (exact, no rounding)

mulmod

mulmod(x: bigint, y: bigint, m: bigint): bigint

Returns (x * y) % m — the remainder of the product when divided by the modulus m. Used internally by mulDiv to check for nonzero remainders.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.mulmod(7n, 8n, 10n); // 6n  (56 % 10)
bigMath.mulmod(5n, 4n, 10n); // 0n  (20 % 10)

clamp

clamp(value: bigint, min: bigint, max: bigint): bigint

Constrains value to the [min, max] range (inclusive), returning min if below or max if above.

import { bigMath } from "@gmx-io/sdk/utils/bigmath";

bigMath.clamp(50n, 0n, 100n); // 50n (within range)
bigMath.clamp(-5n, 0n, 100n); // 0n  (below min)
bigMath.clamp(150n, 0n, 100n); // 100n (above max)