@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

pnpm add @finengine/math

yarn add @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 Interfaces & Types

type DayCountConvention = 'Actual/365' | 'Actual/360' | '30/360' | 'Actual/Actual';
type BusinessDayConvention = 'Following' | 'ModifiedFollowing' | 'Preceding' | 'Unadjusted';

interface AmortizeInput {
  principal: number;
  annualRate: number;
  months: number;
  startDate?: string | Date;
  gracePeriodMonths?: number;
  gracePeriodType?: 'interest-only' | 'capitalized';
  dayCountConvention?: DayCountConvention;
  balloonPayment?: number;
}

interface ScheduleRow {
  month: number;
  date?: string;
  payment: number;
  principalPaid: number;
  interestPaid: number;
  remainingBalance: number;
  isGracePeriod?: boolean;
}

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

API Reference

monthlyPayment(principal, annualRate, months)

Calculates standard compound annuity monthly installment (EMI).

amortize(input: AmortizeInput)

Generates an actuarial reducing-balance amortization schedule with optional grace periods (interest-only or capitalized moratorium), custom day-count conventions, and terminal float reconciliation.

daysBetween(startDate, endDate, convention?)

Computes the exact number of days between two dates according to standard day-count conventions (Actual/365, Actual/360, 30/360).

yearFraction(startDate, endDate, convention?)

Computes the annual accrual factor between dates under the chosen day-count convention.

adjustBusinessDay(date, convention?, holidays?)

Adjusts payment dates for weekends and statutory banking holidays using Following, ModifiedFollowing, or Preceding rolling rules.

xirr(cashflows, guess?)

Solves the Extended Internal Rate of Return for irregular cash flows using a hybrid Newton-Raphson method with automatic fallback to bounded Bisection search.

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