Package docs

@finengine/math

Financial math starter utilities for FinEngine. The current examples focus on EMI planning, amortization schedules, and irregular cashflow return reasoning with Bangladesh-friendly BDT examples and local finance learning context.

Install packages

npm i @finengine/math

Vanilla-JS browser developers can load the module straight from the GitHub CDN:

<script type="module" src="https://cdn.jsdelivr.net/gh/gmrafi/FinEngine@main/packages/math/dist/index.js"></script>

Precision model

FinEngine math currently uses JavaScript number arithmetic and rounds public outputs to stable decimal values. That works well for browser-side calculators, schedule previews, and documentation examples. Teams building regulated financial systems should still decide whether settlement-critical paths need integer minor units or a decimal engine above this starter layer.

TypeScript return shapes

interface ScheduleRow {
  month: number;
  payment: number;
  principalPaid: number;
  interestPaid: number;
  remainingBalance: number;
}

interface AmortizeResult {
  monthlyPayment: number;
  totalInterest: number;
  totalPayable: number;
  schedule: ScheduleRow[];
}

API

monthlyPayment(principal, annualRate, months)

Returns the rounded monthly installment.

amortize({ principal, annualRate, months })

Builds the payment schedule and returns totals plus month-by-month rows.

xirr(cashflows, guess?)

Estimates annualized return for irregular cashflows.

Executed example

import { monthlyPayment, amortize, xirr } from '@finengine/math'

monthlyPayment(500000, 13.5, 36)
// 16967.64

const plan = amortize({ principal: 500000, annualRate: 13.5, months: 36 })
plan.totalInterest
// 110835.2
plan.schedule[0]
// { month: 1, payment: 16967.64, principalPaid: 11342.64, interestPaid: 5625, remainingBalance: 488657.36 }

xirr([
  { amount: -100000, date: '2026-01-01' },
  { amount: 25000, date: '2026-04-01' },
  { amount: 25000, date: '2026-07-01' },
  { amount: 70000, date: '2027-01-10' }
])
// 0.28