@finam/decimal

Библиотека для точной арифметики с десятичными дробями на основе BigInt. Позволяет работать с денежными суммами, курсами и другими числами, где недопустима потеря точности при округлении number.

Установка

npm install @finam/decimal

Создание экземпляра

import { Decimal } from '@finam/decimal';

// Из строки (целое, дробное, научная нотация)
Decimal.fromString('123.456');    // Decimal(123456, 3)
Decimal.fromString('1.5e5');     // Decimal(150000, 0)
Decimal.fromString('1e-10');     // Decimal(1, 10)

// Из числа
Decimal.fromNumber(1.5);         // Decimal(15, 1)

// Из bigint + scale
new Decimal(BigInt(12345), 2);  // Decimal(12345, 2) → "123.45"

// Универсальный метод
Decimal.fromAny('1.5');          // строка
Decimal.fromAny(BigInt(100));    // bigint
Decimal.fromAny(3.14);           // number
Decimal.fromAny(someDecimal);    // Decimal

// Константа
Decimal.ZERO;                    // 0

Арифметические операции

const a = Decimal.fromString('1.5');
const b = Decimal.fromString('2.3');

a.plus(b);    // 3.8
a.minus(b);   // -0.8
a.mul(b);     // 3.45
a.div(b);     // 0.652173913043478 (precision по умолчанию 15)
a.div(b, 5);  // 0.65217
a.pow(3);     // 3.375
a.round();    // 2

pow принимает целую неотрицательную степень.

round округляет до заданного числа знаков после запятой по правилу half-up - отличается от Math.round, который округляет середину всегда в сторону +Infinity:

Сравнение

const x = Decimal.fromString('1.5');
const y = Decimal.fromString('2.0');

x.compare(y); // -1
x.eq(y);      // false
x.gt(y);      // false
x.lt(y);      // true
x.gte(y);     // false
x.lte(y);     // true

Проверки и преобразования

const d = Decimal.fromString('0.05');

d.isZero();      // false
d.isPositive();  // true
d.isNegative();  // false

d.toString();    // "0.05"
d.toNumber();    // 0.05
d.clone();       // новый экземпляр Decimal

d.unscaledValue; // BigInt(5)
d.scale;         // 2

Особенности

• Операции выполняются через BigInt — нет потери точности для любых значений
• Автоматическое удаление конечных нулей при создании (123.1000 → 123.1)
• Поддержка научной нотации при парсинге (1.5e10, 1e-5)
• Настраиваемая точность деления (по умолчанию 15 знаков)
• Числа больше Number.MAX_SAFE_INTEGER обрабатываются без потери точности