indianfinance

README

indian-finance-formulas-go

Zero-dependency finance formulas for India — EMI, prepayment, SIP, step-up SIP, GST, gratuity, income tax. Go port of indian-finance-formulas.

go get github.com/javeed450-sudo/indian-finance-formulas-go

import indianfinance "github.com/javeed450-sudo/indian-finance-formulas-go"

emi := indianfinance.EMI(3000000, 8.5, 240) // 26034.70

Why it exists

Every function is extracted from the calculators running at emicalcs.com. The point of publishing them is that a finance formula should be checkable, not taken on trust.

The test suite is a direct port of the JavaScript one — same 22 cases, same expected values, same tolerances — so both implementations are held to a single standard rather than drifting into two.

go test ./...

Statutory values are options, not constants

Tax slabs, the gratuity ceiling and the GST interest rate change by notification. Every one of them is a documented option with a default, so you can update it the day it moves instead of waiting for a release:

// Central Government civil employees: Rs 25,00,000 ceiling
indianfinance.ComputeGratuity(500000, 30, indianfinance.GratuityOptions{Ceiling: 2500000})

// your own slabs when they change
indianfinance.IncomeTaxNewRegime(1600000, indianfinance.TaxOptions{Slabs: mySlabs})

Three things this gets right that most implementations do not

GST interest runs on the cash-ledger portion. Rule 88B(1) charges interest on tax actually paid in cash, not on the gross output liability. Running it on the gross bill overstates the interest — on the worked example in the tests, by 3.3×.

The 87A rebate carries marginal relief. Tax cannot exceed the income above the rebate threshold. Without it, earning one rupee more than ₹12,00,000 would cost more than one rupee.

A step-up SIP does not beat a flat SIP of the same total outlay. It wins in headline terms only because more money goes in. Hold the money constant and the flat schedule wins, because its rupees compound for longer. That is asserted in the test suite, not just claimed here.

Tenure ceiling

Schedule functions step one period at a time, so an absurd tenure is an out-of-memory crash in the caller's process rather than a slow answer. Tenure is capped at 1200 months / 100 years — far beyond the longest real home loan — and exceeding it returns an *ErrTenure instead.

Licence

MIT. Not financial advice.

Documentation

Overview

Package indianfinance implements zero-dependency finance formulas for India — loans, investments, GST, gratuity and income tax.

Every function here is extracted from the calculators running at https://emicalcs.com and is covered by the test suite in finance_test.go, which is a direct port of the JavaScript suite the same formulas ship with.

Statutory figures — tax slabs, gratuity ceilings, GST rates — change by notification. Where a function depends on one, the value is a documented OPTION with a default rather than a hidden constant, so you can update it yourself the day it moves without waiting for a release.

A note on types

The JavaScript original takes months and years as numbers and rounds them. This port takes them as int where the underlying loop is integer-stepped, which removes the NaN and Infinity cases the JS version has to guard against at runtime. The tenure ceiling below is kept regardless.

MIT licensed.

Index

• Constants
• func AnnualContributionMaturity(yearlyAmount, annualRatePct float64, years int) (float64, error)
• func CAGR(initial, final, years float64) float64
• func EMI(principal, annualRate float64, months int) float64
• func GSTInterest(cashTaxPaid float64, days int, annualRatePct float64) float64
• func Lumpsum(principal, annualRate, years float64) float64
• func SIPFutureValue(monthly, annualRate float64, months int) float64
• func TotalInterest(principal, annualRate float64, months int) float64
• type AmortRow
  • func Amortisation(principal, annualRate float64, months int) ([]AmortRow, error)
• type ErrTenure
  • func (e *ErrTenure) Error() string
• type GST
  • func GSTAdd(amount, ratePct float64) GST
  • func GSTRemove(grossAmount, ratePct float64) GST
• type Gratuity
  • func ComputeGratuity(lastSalary, years float64, opts GratuityOptions) Gratuity
• type GratuityOptions
• type PrepaymentInput
• type PrepaymentResult
  • func Prepayment(in PrepaymentInput) (PrepaymentResult, error)
• type Slab
  • func DefaultSlabs() []Slab
• type StepUpResult
  • func StepUpSIP(monthly, annualRate float64, years int, stepUpPct float64) (StepUpResult, error)
• type Tax
  • func IncomeTaxNewRegime(taxableIncome float64, opts TaxOptions) Tax
• type TaxOptions

Constants

const (
	MaxMonths = 1200
	MaxYears  = MaxMonths / 12
)

Every schedule function below steps one period at a time, so the loop is bounded only by the tenure it is handed. Left unchecked, a bad tenure is an out-of-memory crash in the CALLER's process — not a slow answer — and there is no UI here to clamp the input first. 1200 months / 100 years is far beyond anything real (the longest home loan on offer runs 30-40 years), so the ceiling only ever fires on input that was never going to mean anything.

const DefaultGSTInterestRate = 18.0

DefaultGSTInterestRate is the notified annual rate under Section 50(1).

Functions

func AnnualContributionMaturity

func AnnualContributionMaturity(yearlyAmount, annualRatePct float64, years int) (float64, error)

AnnualContributionMaturity returns the maturity of an annual-contribution scheme such as PPF or SSY. It returns an *ErrTenure if years exceeds MaxYears.

func CAGR

func CAGR(initial, final, years float64) float64

CAGR returns the compound annual growth rate as a percentage.

func EMI

func EMI(principal, annualRate float64, months int) float64

EMI returns the reducing-balance monthly instalment. annualRate is a percentage, e.g. 8.5 for 8.5% p.a.

func GSTInterest

func GSTInterest(cashTaxPaid float64, days int, annualRatePct float64) float64

GSTInterest returns interest on a late GST payment.

Under Rule 88B(1) interest runs on the tax actually paid in cash from the electronic cash ledger — NOT on the gross output liability. Getting this wrong overstates the interest, often by several times. Pass cashTaxPaid as the cash-ledger portion, not the gross bill.

Pass annualRatePct as DefaultGSTInterestRate unless the notified rate has moved.

func Lumpsum

func Lumpsum(principal, annualRate, years float64) float64

Lumpsum returns the future value of a one-off investment.

func SIPFutureValue

func SIPFutureValue(monthly, annualRate float64, months int) float64

SIPFutureValue returns the future value of a monthly SIP, with the contribution made at the start of each month.

func TotalInterest

func TotalInterest(principal, annualRate float64, months int) float64

TotalInterest returns the total interest paid over the full tenure.

Types

type AmortRow

type AmortRow struct {
	Month     int
	Opening   float64
	Interest  float64
	Principal float64
	Closing   float64
}

AmortRow is one month of an amortisation schedule.

func Amortisation

func Amortisation(principal, annualRate float64, months int) ([]AmortRow, error)

Amortisation returns the month-by-month schedule. It returns an *ErrTenure if months exceeds MaxMonths.

type ErrTenure

type ErrTenure struct {
	Unit  string
	Got   int
	Limit int
}

ErrTenure is returned when a tenure exceeds the ceiling. Use errors.Is to match it; the wrapped message carries the offending value.

func (*ErrTenure) Error

func (e *ErrTenure) Error() string

type GST

type GST struct {
	Base  float64
	Tax   float64
	Total float64
}

GST is a base amount, its tax and the gross total.

func GSTAdd

func GSTAdd(amount, ratePct float64) GST

GSTAdd adds GST to a base amount.

func GSTRemove

func GSTRemove(grossAmount, ratePct float64) GST

GSTRemove strips GST out of a gross (GST-inclusive) amount.

type Gratuity

type Gratuity struct {
	Eligible     bool
	Amount       float64
	FormulaValue float64
	Ceiling      float64
	Capped       bool
}

Gratuity is the computed entitlement.

func ComputeGratuity

func ComputeGratuity(lastSalary, years float64, opts GratuityOptions) Gratuity

ComputeGratuity applies the Code on Social Security, 2020 (in force 21 Nov 2025). lastSalary is the last drawn monthly Basic + DA; years is completed years of service.

type GratuityOptions

type GratuityOptions struct {
	Ceiling  float64 // 0 -> 20,00,000. Use 25,00,000 for Central Government civil employees.
	MinYears float64 // 0 -> 5. Use 1 for fixed-term employees.
}

GratuityOptions carries the statutory figures that change by notification. The zero value means "use the defaults".

type PrepaymentInput

type PrepaymentInput struct {
	Principal      float64
	AnnualRate     float64
	Months         int // original tenure
	MonthlyExtra   float64
	LumpSum        float64
	LumpSumAtMonth int // 0 = before the first instalment
}

PrepaymentInput describes a prepayment scenario. The EMI is held fixed, so prepaying shortens the tenure rather than reducing the instalment.

type PrepaymentResult

type PrepaymentResult struct {
	InterestSaved float64
	MonthsSaved   int
	NewMonths     int
	NewInterest   float64
}

PrepaymentResult is what prepaying achieves.

func Prepayment

func Prepayment(in PrepaymentInput) (PrepaymentResult, error)

Prepayment computes the effect of prepaying with the EMI held fixed. It returns an *ErrTenure if Months exceeds MaxMonths.

type Slab

type Slab struct {
	Upto float64
	Rate float64
}

Slab is one income-tax bracket: everything up to Upto is taxed at Rate. The final slab must use math.Inf(1) as Upto.

func DefaultSlabs

func DefaultSlabs() []Slab

DefaultSlabs are the new-regime slabs for FY 2026-27 (AY 2027-28), unchanged by Budget 2026.

type StepUpResult

type StepUpResult struct {
	FutureValue float64
	Invested    float64
	Gain        float64
}

StepUpResult is the outcome of a step-up SIP.

func StepUpSIP

func StepUpSIP(monthly, annualRate float64, years int, stepUpPct float64) (StepUpResult, error)

StepUpSIP models a SIP whose contribution rises by stepUpPct every 12 months.

Worth knowing: a step-up SIP does NOT beat a flat SIP of the same total outlay. It wins in headline terms only because more money goes in. Hold the money constant and the flat schedule wins, because its rupees compound for longer. See https://emicalcs.com/step-up-sip-calculator/

It returns an *ErrTenure if years exceeds MaxYears.

type Tax

type Tax struct {
	Tax   float64
	Cess  float64
	Total float64
}

Tax is the computed liability.

func IncomeTaxNewRegime

func IncomeTaxNewRegime(taxableIncome float64, opts TaxOptions) Tax

IncomeTaxNewRegime computes tax under Section 115BAC, including the Section 87A rebate with marginal relief — tax cannot exceed the income above the rebate threshold, otherwise earning one rupee more would cost more than one rupee.

type TaxOptions

type TaxOptions struct {
	Slabs      []Slab  // nil -> DefaultSlabs
	RebateUpto float64 // 0 -> 12,00,000 (Section 87A)
	Cess       float64 // 0 -> 0.04
}

TaxOptions overrides the statutory defaults. The zero value means "use the FY 2026-27 defaults".