Financial math for JavaScript and TypeScript with deterministic decimal arithmetic. @fin.cx/calculation wraps decimal.js in focused classes for precision arithmetic, time-value-of-money formulas, interest calculations, amortization schedules, and currency formatting/conversion.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Why It Exists

JavaScript numbers are binary floating-point values, which is not what you want for money:

0.1 + 0.2; // 0.30000000000000004

This package keeps calculations in Decimal values so financial code can avoid accidental floating-point drift:

import { Calculator } from '@fin.cx/calculation';

const calc = new Calculator();
calc.add(0.1, 0.2).toString(); // '0.3'

What You Get

Calculator: high-precision arithmetic helpers around decimal.js
Financial: present value, future value, payments, NPV, IRR, MIRR, XIRR, periods, and rates
Interest: simple, compound, continuous, nominal, effective, real, periodic, APY, and doubling-time calculations
Amortization: loan schedules, remaining balances, payoff dates, interest savings, LTV, DTI, and capacity calculations
Currency: currency registration, formatting, parsing, exchange-rate conversion, money objects, discounts, tax, and percentages
Browser and Node.js support through ESM TypeScript sources and bundled output

Installation

pnpm add @fin.cx/calculation

Quick Start

import { Amortization, Calculator, Currency, Financial, Interest } from '@fin.cx/calculation';

const calc = new Calculator({ precision: 20 });
const exactSum = calc.add(0.1, 0.2);
console.log(exactSum.toString()); // '0.3'

const financial = new Financial();
const monthlyPayment = financial.payment(200000, 0.045 / 12, 360);
console.log(monthlyPayment.toFixed(2)); // '1013.37'

const interest = new Interest();
const monthlyCompoundInterest = interest.compound(1000, 0.12, 1, 'monthly');
console.log(monthlyCompoundInterest.toFixed(2)); // '126.83'

const amortization = new Amortization();
const schedule = amortization.schedule({
  principal: 250000,
  annualRate: 0.045,
  termYears: 30,
  extraPayment: 200,
});
console.log(schedule.payments.length);

const currency = new Currency();
currency.setExchangeRate('USD', 'EUR', 0.85);
console.log(currency.format(currency.convert(100, 'USD', 'EUR'), 'EUR')); // '€85,00'

Precision Model

All calculation methods return Decimal instances unless documented otherwise. Convert at the edge of your application with toString(), toNumber(), toFixed(), or the helpers on Calculator.

Calculator passes its precision option to decimal.js, where precision means significant digits. Each calculator constructor configures the shared Decimal constructor, so create calculators with the precision you want before running a batch of calculations.

import { Calculator } from '@fin.cx/calculation';

const calc = new Calculator({ precision: 10 });

calc.add(10.5, 20.3).toString(); // '30.8'
calc.subtract(100, 45.5).toString(); // '54.5'
calc.multiply(15, 3.5).toString(); // '52.5'
calc.divide(1, 3).toString(); // '0.3333333333'
calc.power(2, 8).toString(); // '256'
calc.sqrt(16).toString(); // '4'
calc.round(3.14159, 2).toString(); // '3.14'

Financial Calculations

import { Financial } from '@fin.cx/calculation';

const financial = new Financial();

const presentValue = financial.presentValue(10000, 0.05, 5);
const futureValue = financial.futureValue(5000, 0.07, 10);
const payment = financial.payment(200000, 0.045 / 12, 360);
const cashFlows = [-50000, 15000, 15000, 15000, 15000, 20000];
const npv = financial.npv(0.1, cashFlows);
const irr = financial.irr(cashFlows);
const mirr = financial.mirr(cashFlows, 0.08, 0.1);

console.log({
  presentValue: presentValue.toFixed(2),
  futureValue: futureValue.toFixed(2),
  payment: payment.toFixed(2),
  npv: npv.toFixed(2),
  irr: irr.toFixed(4),
  mirr: mirr.toFixed(4),
});

The Financial class includes these methods:

presentValue(futureValue, rate, periods)
futureValue(presentValue, rate, periods)
payment(principal, rate, periods)
npv(rate, cashFlows)
irr(cashFlows, guess?, tolerance?, maxIterations?)
mirr(cashFlows, financeRate, reinvestRate)
periods(presentValue, futureValue, rate)
rate(presentValue, futureValue, periods)
xirr(cashFlows, dates, guess?)

Interest Calculations

import { Interest } from '@fin.cx/calculation';

const interest = new Interest();

interest.simple(1000, 0.05, 2).toString(); // '100'
interest.simpleAmount(1000, 0.05, 2).toString(); // '1100'
interest.compound(1000, 0.05, 2, 'annually').toFixed(2); // '102.50'
interest.compound(1000, 0.12, 1, 'monthly').toFixed(2); // '126.83'
interest.effectiveAnnualRate(0.12, 'monthly').toFixed(4); // '0.1268'
interest.realRate(0.08, 0.03).toFixed(4); // '0.0485'
interest.ruleOf72(8).toString(); // '9'

Supported compounding frequencies are annually, semiannually, quarterly, monthly, weekly, daily, and continuous.

Amortization Schedules

import { Amortization } from '@fin.cx/calculation';

const amortization = new Amortization();

const schedule = amortization.schedule({
  principal: 250000,
  annualRate: 0.045,
  termYears: 30,
  extraPayment: 200,
});

console.log(schedule.monthlyPayment.toFixed(2));
console.log(schedule.totalInterest.toFixed(2));
console.log(schedule.payments[0]);

Loan options accept any decimal.js value-compatible input, including numbers, strings, and Decimal instances:

type DecimalInput = number | string;

interface ILoanOptions {
  principal: DecimalInput;
  annualRate: DecimalInput;
  termYears?: DecimalInput;
  termMonths?: DecimalInput;
  paymentFrequency?: 'monthly' | 'biweekly' | 'weekly';
  extraPayment?: DecimalInput;
}

Schedule entries contain period, payment, principal, interest, balance, cumulativePrincipal, and cumulativeInterest as Decimal values where applicable.

Currency Formatting And Conversion

import { Currency } from '@fin.cx/calculation';

const currency = new Currency();

currency.setExchangeRates([
  { from: 'USD', to: 'EUR', rate: 0.85 },
  { from: 'USD', to: 'GBP', rate: 0.73 },
]);

const euros = currency.convert(1000, 'USD', 'EUR');
currency.format(euros, 'EUR'); // '€850,00'
currency.parse('$1,234.56', 'USD').toString(); // '1234.56'

const first = currency.money(100, 'USD');
const second = currency.money(50, 'USD');
const total = currency.addMoney(first, second);
console.log(currency.format(total.amount, total.currency)); // '$150.00'

currency.discount(100, 20).toString(); // '80'
currency.withTax(100, 0.08).toString(); // '108'

Custom currencies can be registered at runtime:

currency.registerCurrency({
  code: 'BTC',
  symbol: '₿',
  decimals: 8,
  thousandsSeparator: ',',
  decimalSeparator: '.',
  symbolPosition: 'before',
});

currency.format(0.00042, 'BTC'); // '₿0.00042000'

TypeScript Interfaces

Core interfaces are exported from the package:

import type {
  CompoundingFrequency,
  ICashFlow,
  IAmortizationPayment,
  IAmortizationSchedule,
  ICalculatorOptions,
  ICurrencyOptions,
  IExchangeRate,
  IInterestOptions,
  ILoanOptions,
  IMoneyValue,
} from '@fin.cx/calculation';

Development

pnpm install
pnpm test
pnpm run build

The test suite runs the shared test file in Node.js and Chromium, matching the package's cross-platform target.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@fin.cx/calculation