decimal

A precision numeric library for TypeScript/JavaScript, backed by bigint for arbitrary-precision decimal arithmetic. Single file, zero runtime dependencies, optimized. Observed performance is 2x faster than decimal.js. It works for my use case, but it is not meant to be a drop-in replacement for decimal.js.

Features

• Exact decimal arithmetic — no floating-point drift
• BigInt-backed internals — configurable precision (default 20 digits)
• Full math API — arithmetic, comparison, trigonometry, logarithms, exponentials, power
• Object pool — pre-allocated instance pool (10,000 slots) to minimize GC pressure
• LRU caches — exp, ln, sqrt, pow results cached for hot paths
• decimal.js-compatible interface — familiar API, limited set of functions, precision control is different. The range is limited by the precision u set and bigint max size.

Install

pnpm install decimal

Usage

import { Decimal } from "decimal";

// Configure precision
Decimal.setPrecision(30); // sets global precision to 30 digits after the decimal point, N.[30] digits. N can be of any length
Decimal.setPrecision(-3); // sets global precision to 3 digits before the decimal point, N000. N can be of any length.

// Arithmetic
const a = Decimal("1.1");
const b = Decimal("2.2");
const sum = a.plus(b); // "3.3"  (exact)
const prod = a.times(b); // "2.42"

// Aliases: add/plus/sum, sub/minus, mul/times, div/divide

// Comparison
a.lt(b); // true
a.gt(Decimal("0.5")); // true

// Rounding
Decimal("3.14159").round(); // "3"
Decimal("3.14159").floor(); // "3"
Decimal("3.14159").ceil(); // "4"

// Transcendental functions
Decimal.exp("1"); // e
Decimal.ln("100"); // natural log
Decimal.sqrt("2"); // square root
Decimal.pow("2", "0.5"); // power

// Trigonometry (radians)
Decimal.sin("3.141592653589793");
Decimal.cos("0");
Decimal.tan("0.5");

// Static multi-argument helpers
Decimal.add("1", "2", "3"); // "6"
Decimal.times("2", "3", "4"); // "24"
Decimal.min("3", "1", "2"); // "1"
Decimal.max("3", "1", "2"); // "3"

API

Construction

| Syntax | Description | | ----------------------- | ----------- | | Decimal("1.23") | From string | | Decimal(1.23) | From number | | Decimal(otherDecimal) | Clone |

Static Configuration

| Method | Description | | -------------------------- | ---------------------------------- | | Decimal.setPrecision(n) | Set global precision (default 20) | | Decimal.setNotation(sci) | Enable/disable scientific notation | | Decimal.setPoolSize(n) | Resize the object pool |

Instance Methods

| Category | Methods | | ------------------ | -------------------------------------------------------------------------------------------------- | | Arithmetic | add, plus, sum, sub, minus, mul, times, div, divide, neg, abs, sqrt, pow | | Transcendental | ln, exp, sin, cos, tan, asin, acos, atan | | Rounding | round, floor, ceil, toPrecision(n), toFixed(n) | | Comparison | lt, lte, gt, gte, eq, neq, compare | | Checks | isZero, isNegative, isPositive, isInteger, isNaN | | Conversion | toString(), toNumber(), toJSON(), clone() |

Static Functions

Decimal.ln, Decimal.exp, Decimal.sqrt, Decimal.pow, Decimal.sin, Decimal.cos, Decimal.tan, Decimal.asin, Decimal.acos, Decimal.atan, Decimal.abs, Decimal.add, Decimal.times, Decimal.sub, Decimal.div, Decimal.min, Decimal.max, Decimal.random, Decimal.isPositive, Decimal.isNegative

Static vs Instance

Both forms are supported. Decimal.exp("2.718") is equivalent to Decimal("2.718").exp().

Precision

Global precision controls all operations. Set once at startup:

Decimal.setPrecision(30); // 30-digit precision

Build & Test

pnpm run build   # TypeScript compilation
pnpm test        # Run tests

License

MIT