Math Reference

Coverage $License$ $NPM Version$ Open Issues $Size$

🧮 Precise basic math operations. Using this library, adding 0.1 to 0.2 will give you 0.3, which might sound like nothing, but that’s not the default behavior of JavaScript.

Usage

📦 Node

Install @lou.codes/math as a dependency:

1
pnpm add @lou.codes/math
2
# or
3
npm install @lou.codes/math
4
# or
5
yarn add @lou.codes/math

Import it and use it:

1
import { chain } from "@lou.codes/math";
2

3
chain(0.2).add(0.1); // 0.3 🪄

🦕 Deno

Import @lou.codes/math using the npm: prefix, and use it directly:

1
import { chain } from "npm:@lou.codes/math";
2

3
chain(0.2).add(0.1); // 0.3 🪄

🌎 Browser

Import @lou.codes/math using esm.sh, and use it directly:

1
<script type="module">
2
	import { chain } from "https://esm.sh/@lou.codes/math";
3

4
	chain(0.2).add(0.1); // 0.3 🪄
5
</script>

Useful links

📝 Documentation: TypeDoc generated documentation.
⏳ Changelog: List of changes between versions.
✅ Tests Coverage: Coveralls page with tests coverage.

Internal

MaybeInfinity

1
type MaybeInfinity: bigint | typeof Infinity;

Dividing by zero would yield Infinity.

Precise

1
type Precise: readonly [MaybeInfinity, bigint];

Type to precisely represent a number as a tuple [base, exponent]. It can be [Infinity].

bigIntMin()

1
function bigIntMin(...bigints: readonly bigint[]): bigint;

Like Math.min but for bigint values.

Parameters

Parameter	Type
…`bigints`	readonly `bigint`[]

Returns

bigint

Minimum value of the bigint array.

Example

1
bigIntMin(5n, 1n, 10n); // 1n

See

Math.min

createPrecise()

createPrecise(base, exponent)

1
function createPrecise(base: bigint, exponent?: bigint): Precise;

Takes a base and exponent and normalizes it returning a Precise.

Parameters

Parameter	Type	Description
`base`	`bigint`	Base of the Precise.
`exponent`?	`bigint`	Exponent of the Precise.

Returns

Precise

A normalized Precise value.

Example

1
createPrecise(13n); // [13n]
2
createPrecise(13n, -1n); // [13n, -1n]
3
createPrecise(1300n, 0n); // [13n, 2n]

See

Precise

createPrecise(base)

1
function createPrecise(base: number): Precise;

Takes a base and exponent and normalizes it returning a Precise.

Parameters

Parameter	Type	Description
`base`	`number`	Base of the Precise.

Returns

Precise

A normalized Precise value.

Example

1
createPrecise(13n); // [13n]
2
createPrecise(13n, -1n); // [13n, -1n]
3
createPrecise(1300n, 0n); // [13n, 2n]

See

Precise

numberToPrecise()

1
function numberToPrecise(number: number): Precise;

Turns a number into a Precise.

Parameters

Parameter	Type	Description
`number`	`number`	Number to convert.

Returns

Precise

A Precise representation of the given number.

Example

1
numberToPrecise(13); // [13n]
2
numberToPrecise(1.3); // [13n, -1n]
3
numberToPrecise(1300); // [13n, 2n]

See

createPrecise

pipe()

1
function pipe<PreciseOperation>(
2
	preciseOperation: PreciseOperation,
3
): (right: number) => (left: number) => number;

Turns a Precise operation into a number operation.

Type parameters

Type parameter
`PreciseOperation` extends (…`right`: `Precise`) => (…`left`: `Precise`) => `Precise`

Parameters

Parameter	Type	Description
`preciseOperation`	`PreciseOperation`	Precise operation function.

Returns

Function

Number to number operation generated from preciseOperation.

Parameters

Parameter	Type
`right`	`number`

Returns

Function

Parameters

Parameter	Type
`left`	`number`

Returns

number

Example

1
const add = pipe(preciseAdd);
2

3
add(0.1)(0.2); // 0.3

preciseAdd()

1
function preciseAdd(
2
	addendRightBase: MaybeInfinity,
3
	addendRightExponent: bigint,
4
): (addendLeftBase: MaybeInfinity, addendLeftExponent: bigint) => Precise;

Curried add operation using the internal Precise type.

Parameters

Parameter	Type	Description
`addendRightBase`	`MaybeInfinity`	Addend base to use in the right side of the addition.
`addendRightExponent`	`bigint`	Addend exponent to use in the right side of the addition.

Returns

Function

Curried function with addendRightBase and addendRightExponent in context.

Parameters

Parameter	Type
`addendLeftBase`	`MaybeInfinity`
`addendLeftExponent`	`bigint`

Returns

Precise

Example

1
const addDot2 = preciseAdd(2n);
2

3
addDot2(1n, -1n); // [3n, -1n]

See

bigIntMin
createPrecise
Precise
preciseToNumber

preciseDivide()

1
function preciseDivide(
2
	divisorBase: MaybeInfinity,
3
	divisorExponent: bigint,
4
): (dividendBase: MaybeInfinity, dividendExponent?: bigint) => Precise;

Curried divide operation using the internal Precise type.

Parameters

Parameter	Type	Description
`divisorBase`	`MaybeInfinity`	Divisor base to use in the division.
`divisorExponent`	`bigint`	Divisor exponent to use in the division.

Returns

Function

Curried function with divisorBase and divisorExponent in context.

Parameters

Parameter	Type
`dividendBase`	`MaybeInfinity`
`dividendExponent`?	`bigint`

Returns

Precise

Example

1
const half = preciseDivide(2n);
2

3
half(1n); // [5n, -1n]

See

numberToPrecise
Precise
preciseMultiply
preciseToNumber

preciseMultiply()

1
function preciseMultiply(
2
	multiplierBase: MaybeInfinity,
3
	multiplierExponent: bigint,
4
): (multiplicandBase: MaybeInfinity, multiplicandExponent: bigint) => Precise;

Curried multiply operation using the internal Precise type.

Parameters

Parameter	Type	Description
`multiplierBase`	`MaybeInfinity`	Multiplier base to use in the multiplication.
`multiplierExponent`	`bigint`	Multiplier exponent to use in the multiplication.

Returns

Function

Curried function with multiplierBase and multiplierExponent in context.

Parameters

Parameter	Type
`multiplicandBase`	`MaybeInfinity`
`multiplicandExponent`	`bigint`

Returns

Precise

Example

1
const double = preciseMultiply(2n);
2

3
double(65n, -1n); // [13n]

See

createPrecise
Precise

preciseSubtract()

1
function preciseSubtract(
2
	subtrahendBase: MaybeInfinity,
3
	subtrahendExponent: bigint,
4
): (minuendBase: MaybeInfinity, minuendExponent?: bigint) => Precise;

Curried subtract operation using the internal Precise type.

Parameters

Parameter	Type	Description
`subtrahendBase`	`MaybeInfinity`	Subtrahend base to use in the subtraction.
`subtrahendExponent`	`bigint`	Subtrahend exponent to use in the subtraction.

Returns

Function

Curried function with subtrahendBase and subtrahendExponent in context.

Parameters

Parameter	Type
`minuendBase`	`MaybeInfinity`
`minuendExponent`?	`bigint`

Returns

Precise

Example

1
const previous = preciseSubtract(1n);
2

3
previous(14n); // [13n]

See

Precise
preciseAdd

preciseToNumber()

1
function preciseToNumber(base: number | bigint, exponent: bigint): number;

Turns a Precise into a number.

Parameters

Parameter	Type
`base`	`number` \| `bigint`
`exponent`	`bigint`

Returns

number

Number represented by the passed precise value.

Example

1
preciseToNumber(3n, -1n); // 0.3

See

Precise

Operations

add()

1
function add(addendRight: number): (addendLeft: number) => number;

Curried add operation using pipe with preciseAdd.

Parameters

Parameter	Type	Description
`addendRight`	`number`	Addend value to be on the right side.

Returns

Function

Curried function with addendRight in context.

Parameters

Parameter	Type
`addendLeft`	`number`

Returns

number

Example

1
const addDot2 = add(2);
2

3
addDot2(0.1); // 0.3

See

preciseAdd
pipe

chain()

1
function chain(value: number): Readonly<object>;

A chainable set of operations.

Parameters

Parameter	Type	Description
`value`	`number`	Value to run operations on.

Returns

Readonly<object>

An object with divideBy, minus, plus and times methods and a value property.

Member	Type	Value	Description
`dividedBy`	(`divisor`: `number`) => Readonly<{ dividedBy: (divisor: number) => Readonly<…>; minus: (subtrahend: number) => Readonly<…>; plus: (addend: number) => Readonly<…>; times: (multiplier: number) => Readonly<…>; value: number; }>	…	Divide previous `value` in chain by the given `divisor`
`minus`	(`subtrahend`: `number`) => Readonly<{ dividedBy: (divisor: number) => Readonly<…>; minus: (subtrahend: number) => Readonly<…>; plus: (addend: number) => Readonly<…>; times: (multiplier: number) => Readonly<…>; value: number; }>	…	Subtracts given `subtrahend` to the current `value` in the chain.
`plus`	(`addend`: `number`) => Readonly<{ dividedBy: (divisor: number) => Readonly<…>; minus: (subtrahend: number) => Readonly<…>; plus: (addend: number) => Readonly<…>; times: (multiplier: number) => Readonly<…>; value: number; }>	…	Adds given `addend` to the current `value` in the chain.
`times`	(`multiplier`: `number`) => Readonly<{ dividedBy: (divisor: number) => Readonly<…>; minus: (subtrahend: number) => Readonly<…>; plus: (addend: number) => Readonly<…>; times: (multiplier: number) => Readonly<…>; value: number; }>	…	Multiplies previous `value` in chain times the given `multiplier`
`value`	`number`	-	-

Example

1
chain(0.1).add(0.2).value; // 0.3
2
chain(0.7).plus(0.3).dividedBy(4).times(2).minus(0.2).value; // 0.3

See

add
divide
multiply
subtract

divide()

1
function divide(divisor: number): (dividend: number) => number;

Curried divide operation using pipe with preciseDivide.

Parameters

Parameter	Type	Description
`divisor`	`number`	Divisor to be used in the division.

Returns

Function

Curried function with divisor in context.

Parameters

Parameter	Type
`dividend`	`number`

Returns

number

Example

1
const half = divide(2);
2

3
half(1); // 0.5

See

preciseDivide
pipe

multiply()

1
function multiply(multiplier: number): (multiplicand: number) => number;

Curried multiply operation using pipe with preciseMultiply.

Parameters

Parameter	Type	Description
`multiplier`	`number`	Multiplier value to be used in the multiplication.

Returns

Function

Curried function with multiplier in context.

Parameters

Parameter	Type
`multiplicand`	`number`

Returns

number

Example

1
const double = multiply(2);
2

3
double(6.5); // 13

See

preciseMultiply
pipe

subtract()

1
function subtract(subtrahend: number): (minuend: number) => number;

Curried subtract operation using pipe with preciseSubtract.

Parameters

Parameter	Type	Description
`subtrahend`	`number`	Subtrahend value to be used in the subtraction.

Returns

Function

Curried function with subtrahend in context.

Parameters

Parameter	Type
`minuend`	`number`

Returns

number

Example

1
const previous = subtract(1);
2

3
previous(14); // 13

See

preciseSubtract
pipe