finworth

Complete Indian financial calculator library for JavaScript & TypeScript. Works in React, React Native, and Node.js.

npm install finworth

Zero dependencies. Full TypeScript types. 21 tests.

Also available as a Python package on PyPI.

What's Inside

| Module | Calculators | |--------|------------| | Core | XIRR, CAGR, absolute return, inflation-adjusted return | | Mutual Funds | SIP maturity, SWP projection, capital gains (LTCG/STCG) | | Fixed Deposits | Maturity, post-tax returns | | Recurring Deposits | Maturity with quarterly compounding | | PPF | 15-year maturity calculator | | NPS | Corpus projection, monthly pension | | EPF | Corpus with employer match and increments | | EMI | Monthly EMI, year-wise amortization | | Gratuity | Payment of Gratuity Act (private + government) | | Salary | HRA exemption | | Planning | SSY, lumpsum, future cost, retirement corpus | | Stocks | P&L with all charges (STT, GST, stamp duty, SEBI, DP) | | Tax | Income tax slabs (old + new regime), STT |

All calculations follow Indian tax rules (FY 2024-25).

Quick Start

import { sipMaturity, emi, incomeTaxSlab, stockPnl, fdMaturity } from 'finworth';

// SIP — ₹10K/month at 12% for 10 years
sipMaturity(10000, 0.12, 10)
// → { invested: 1200000, returns: 1123391, maturity: 2323391 }

// EMI — ₹50L home loan at 8.5% for 20 years
emi(5000000, 0.085, 20)
// → { emi: 43391, totalPayment: 10413816, totalInterest: 5413816 }

// Income Tax — new regime
incomeTaxSlab(1500000, 'new')
// → { totalTax: 130000, effectiveRate: 0.086667 }

// Stock P&L with all charges
stockPnl(500, 580, 200, 'delivery')
// → { grossPnl: 16000, netPnl: 15798.08, charges: { stt: 116, gst: 8.35, ... } }

// FD maturity
fdMaturity(500000, 0.07, 3)
// → { maturity: 615720, interestEarned: 115720, effectiveRate: 0.071859 }

All Functions

Core

xirr(cashflows: [Date, number][])                    // XIRR for irregular cashflows
cagr(initial: number, final: number, years: number)  // Compound annual growth rate
absoluteReturn(invested: number, current: number)     // Simple return
inflationAdjusted(nominalReturn: number, inflation: number)

Mutual Funds

sipMaturity(monthly: number, rate: number, years: number)
swpProjection(corpus: number, monthlyWithdrawal: number, rate: number, years: number)
mfCapitalGains(buyNav: number, sellNav: number, units: number, holdingDays: number, fundType?: 'equity' | 'debt')

FD & RD

fdMaturity(principal: number, rate: number, years: number, compounding?: 'quarterly' | 'monthly' | 'half-yearly' | 'yearly')
fdPostTax(principal: number, rate: number, years: number, taxSlab?: number)
rdMaturity(monthly: number, rate: number, years: number)

PPF, NPS, EPF

ppfMaturity(yearly: number, rate?: number, years?: number)
npsMaturity(monthly: number, rate?: number, years?: number, annuityPercent?: number)
epfMaturity(basicDa: number, rate?: number, years?: number, annualIncrement?: number)

EMI & Gratuity

emi(principal: number, rate: number, years: number)
emiAmortization(principal: number, rate: number, years: number)
gratuity(basicDa: number, yearsOfService: number, employeeType?: 'private' | 'government')

Salary & Planning

hraExemption(basic: number, hraReceived: number, rentPaid: number, metro?: boolean)
ssyMaturity(yearly: number, rate?: number, depositYears?: number)
lumpsumMaturity(amount: number, rate: number, years: number)
futureCost(currentCost: number, inflation?: number, years?: number)
retirementCorpus(monthlyExpense: number, currentAge?: number, retirementAge?: number)

Stocks & Tax

stockPnl(buyPrice: number, sellPrice: number, quantity: number, tradeType?: 'delivery' | 'intraday')
stt(value: number, tradeType?: 'equity_delivery' | 'equity_intraday' | 'futures' | 'options')
incomeTaxSlab(income: number, regime?: 'old' | 'new', fy?: string)

Usage in React / React Native

import { sipMaturity, emi } from 'finworth';

function SIPCalculator({ monthly, rate, years }) {
  const result = sipMaturity(monthly, rate, years);
  return <Text>Maturity: ₹{result.maturity.toLocaleString('en-IN')}</Text>;
}

Tax Rules Applied

| Rule | Implementation | |------|---------------| | Equity LTCG (>1 year) | 12.5% above ₹1.25L exemption | | Equity STCG (≤1 year) | 20% flat | | STT (delivery) | 0.1% on sell side | | Income tax (new regime) | 0/5/10/15/20/30% slabs, ₹75K std deduction | | Section 87A rebate | No tax up to ₹7L (new regime) | | Gratuity | 15/26 formula, ₹20L tax-exempt cap | | PPF | 7.1%, tax-free | | NPS | Min 40% annuity | | EPF | 8.1%, 12% employee + 3.67% employer |

MCP Server (Claude, Kiro, Cursor)

Add to .mcp.json — any AI agent can call all finworth calculators as native tools:

{
  "finworth": {
    "command": "npx",
    "args": ["-y", "finworth", "--mcp"]
  }
}

Or if installed globally:

{
  "finworth": {
    "command": "finworth-mcp"
  }
}

20 tools exposed: SIP, FD, RD, PPF, NPS, EPF, EMI, gratuity, HRA, income tax, stock P&L, capital gains, SWP, SSY, lumpsum, future cost, retirement, XIRR, CAGR.

Contributing

PRs welcome. Ideas:

• [ ] Workflows (financial health check, investment comparison)
• [ ] Gold/Silver returns
• [ ] Crypto tax (30% + 1% TDS)

License

MIT

Built by Vikas Singh