indian-finance-formulas

Zero-dependency finance formulas for India — loans, investments, GST, gratuity and income tax. No build step, no framework, ~9 KB of plain ES modules. 20 tests, no dependencies.

npm install indian-finance-formulas

import { emi, prepayment, gstInterest, gratuity } from "indian-finance-formulas";

emi(3000000, 8.5, 240);                    // 26034.70  — ₹30L at 8.5% over 20 years
prepayment({ principal: 3000000, annualRate: 8.5, months: 240, monthlyExtra: 5000 });
// { interestSaved: 1173056, monthsSaved: 76, newMonths: 164, ... }

Why this exists

These functions power the calculators at emicalcs.com. They were extracted because the arithmetic is the boring, reusable part — and because a surprising amount of Indian finance code on the internet gets three specific things wrong. Those three are called out below.

Statutory values are parameters, not constants

Tax slabs, gratuity ceilings and GST rates change by notification. Every function that depends on one takes it as an argument with a documented default, so you can update it the day it moves instead of waiting for a release:

gratuity(500000, 30);                          // ₹20,00,000 ceiling (most employees)
gratuity(500000, 30, { ceiling: 2500000 });    // ₹25,00,000 — Central Government civil employees

incomeTaxNewRegime(1600000);                   // FY 2026-27 slabs by default
incomeTaxNewRegime(1600000, { slabs: [...] }); // your own, when they change

Three things this library gets right

1. GST interest runs on the cash-ledger amount, not the gross bill. Rule 88B(1) charges interest on the tax actually debited from your electronic cash ledger. Running it on gross output liability is the single most common error in GST code, and it overstates the interest several times over.

gstInterest(30000, 30);    // 443.84  — correct: ₹30,000 paid in cash
gstInterest(100000, 30);   // 1479.45 — the common error, 3.3x too high

2. A step-up SIP does not beat a flat SIP of the same total outlay. Every step-up calculator shows the step-up winning. It wins only because more money goes in. Hold the money constant and it reverses — the flat schedule's rupees compound for longer. This is asserted by a test, not just documented:

const step = stepUpSip(10000, 12, 20, 10);        // ₹1,98,88,715 on ₹68,73,000 invested
const flat = sipFutureValue(step.invested / 240, 12, 240);  // ₹2,86,13,098 on the SAME ₹68,73,000

3. Section 87A marginal relief. Tax just above the ₹12,00,000 rebate threshold is capped at the income above it — otherwise earning ₹1 more would cost you more than ₹1. Also asserted by a test.

API

Loans

| Function | Returns | |---|---| | emi(principal, annualRate, months) | Reducing-balance monthly instalment | | totalInterest(principal, annualRate, months) | Interest over the full tenure | | amortisation(principal, annualRate, months) | [{month, opening, interest, principal, closing}] | | prepayment({principal, annualRate, months, monthlyExtra?, lumpSum?, lumpSumAtMonth?}) | {interestSaved, monthsSaved, newMonths, newInterest} |

Investments

| Function | Returns | |---|---| | sipFutureValue(monthly, annualRate, months) | Future value, contribution at month start | | stepUpSip(monthly, annualRate, years, stepUpPct) | {futureValue, invested, gain} | | swp({corpus, monthlyWithdrawal, annualRatePct, years, annualIncreasePct}) | {finalBalance, totalWithdrawn, gains, depletedAtMonth} | | lumpsum(principal, annualRate, years) | Future value of a one-off investment | | cagr(initial, final, years) | Compound annual growth rate, % |

GST

| Function | Returns | |---|---| | gstAdd(amount, ratePct) | {base, tax, total} | | gstRemove(grossAmount, ratePct) | {base, tax, total} | | gstInterest(cashTaxPaid, days, annualRatePct?) | Interest on late payment |

Statutory

| Function | Returns | |---|---| | gratuity(lastSalary, years, {ceiling?, minYears?}) | {eligible, amount, formulaValue, ceiling, capped} | | incomeTaxNewRegime(taxableIncome, {slabs?, rebateUpto?, cess?}) | {tax, cess, total} | | annualContributionMaturity(yearlyAmount, annualRatePct, years) | Maturity for PPF/SSY-style schemes |

What this is not

• Not tax advice. It is arithmetic. Statutory positions change and vary by circumstance.
• Not a full tax engine. incomeTaxNewRegime covers slabs, the 87A rebate and cess — not surcharge, capital gains, or the old regime's deductions.
• Not currency-formatted. Everything returns plain numbers; format them yourself.

Tests

npm test    # node --test, no test framework needed

The suite deliberately includes the traps above, so a regression that reintroduces one fails loudly.

Licence

MIT © Javeed Shaik. Built alongside EMICalcs, a set of free finance calculators for India.