# Decimal.js — Arbitrary-Precision Decimal Arithmetic for JavaScript

> A fast JavaScript library for arbitrary-precision decimal and non-decimal arithmetic.

## Install

Save in your project root:

# Decimal.js — Arbitrary-Precision Decimal Arithmetic for JavaScript

## Quick Use
```bash
npm install decimal.js
```
```js
const Decimal = require('decimal.js');
const x = new Decimal(0.1);
const y = new Decimal(0.2);
console.log(x.plus(y).toString());  // '0.3' (not 0.30000000000000004)
console.log(new Decimal(2).sqrt().toString());  // '1.4142135623730950488...'
```

## Introduction
Decimal.js provides an arbitrary-precision Decimal type for JavaScript. It solves the classic IEEE 754 floating-point problem (0.1 + 0.2 !== 0.3) by representing numbers as decimal strings internally. It supports all standard arithmetic operations, trigonometric functions, and configurable precision up to millions of digits.

## What Decimal.js Does
- Performs exact decimal arithmetic without floating-point rounding errors
- Supports configurable precision from 1 to millions of significant digits
- Provides sqrt, pow, log, exp, sin, cos, tan, and other transcendental functions
- Handles very large and very small numbers beyond Number.MAX_SAFE_INTEGER
- Returns Decimal objects that chain naturally for complex calculations

## Architecture Overview
Decimal.js stores each number as an array of digits with a sign and exponent. Arithmetic operations use classical algorithms (long multiplication, Newton-Raphson for division and roots). The library is self-contained with no dependencies. A configurable global Decimal constructor lets you set precision, rounding mode, and other defaults.

## Self-Hosting & Configuration
- Install via npm or include a single script file from a CDN
- Set global precision with Decimal.set({ precision: 50 })
- Choose from 9 rounding modes (ROUND_UP, ROUND_DOWN, ROUND_HALF_EVEN, etc.)
- Configure toExpPos and toExpNeg to control when exponential notation is used
- Zero dependencies; works in Node.js, Deno, and all browsers

## Key Features
- Eliminates floating-point errors for financial and scientific calculations
- Configurable precision up to 1 billion significant digits
- Full suite of mathematical functions including trigonometry and logarithms
- Immutable Decimal instances prevent accidental mutation
- Comprehensive test suite with thousands of test cases

## Comparison with Similar Tools
- **big.js** — Simpler API for basic arithmetic; Decimal.js adds trig and log functions
- **bignumber.js** — Same author; Decimal.js uses a different internal format and adds more math functions
- **mathjs** — Full math library; Decimal.js is focused purely on arbitrary precision numbers
- **Native BigInt** — Integers only; Decimal.js handles fractional values

## FAQ
**Q: When should I use Decimal.js over native numbers?**
A: Use it when exact decimal representation matters: finance, currency, scientific computation.

**Q: How fast is it compared to native arithmetic?**
A: Slower than native floats, but optimized for its class. Most operations complete in microseconds.

**Q: What is the difference between decimal.js, big.js, and bignumber.js?**
A: All three are by the same author. Decimal.js has the most features; big.js is the smallest; bignumber.js is in between.

**Q: Does it support serialization?**
A: Yes, toString() and toJSON() produce string representations that can reconstruct Decimal instances.

## Sources
- https://github.com/MikeMcl/decimal.js
- https://mikemcl.github.io/decimal.js/

---
Source: https://tokrepo.com/en/workflows/asset-aa1d6631
Author: AI Open Source