Calculators

A TypeScript library of 15 financial calculators covering interest, loans, investments, taxes, and business analysis. Zero dependencies, fully typed, with strict mode enabled.

---

Table of Contents

• Installation
• Quick Start
• Calculators
  • Interest & Growth
  • Loans & Debt
  • Investments & Savings
  • Tax & Business
• Scripts
• Testing
• Contributing
• License

---

Installation

npm install calculators

Or clone and build from source:

git clone https://github.com/your-username/Calculators.git
cd Calculators
npm install
npm run build

Quick Start

import { Mortgage, CompoundInterest, Compound } from "calculators";

// Calculate monthly mortgage payment
const mortgage = new Mortgage(350000, 70000, 6.5, 30);
const result = mortgage.calculate();
console.log(result.monthlyPayment); // 1770.27

// Calculate compound interest
const ci = new CompoundInterest(10000, 5, 10, Compound.Monthly);
console.log(ci.calculate()); // 16470.09

Calculators

Interest & Growth

SimpleInterest

Calculates simple interest using A = P(1 + rt).

import { SimpleInterest } from "calculators";

const si = new SimpleInterest(1000, 5, 3);
// constructor(principal, ratePercentage, years)
console.log(si.calculate()); // 1150.00

Parameter	Type	Description
principal	number	Initial amount (must be > 0)
ratePercentage	number	Annual rate as a percentage, 0-100
years	number	Time period in years (>= 0)

Returns: number — the total amount (principal + interest).

---

CompoundInterest

Calculates compound interest using A = P(1 + r/n)^(nt).

import { CompoundInterest, Compound } from "calculators";

const ci = new CompoundInterest(5000, 8, 5, Compound.Quarterly);
console.log(ci.calculate()); // 7429.74

Parameter	Type	Description
principal	number	Initial amount (must be > 0)
ratePercentage	number	Annual rate, 0-100
years	number	Time period (must be > 0)
compound	Compound	Compound.Monthly, Compound.Quarterly, or Compound.Annually

Returns: number — the total amount after compounding.

---

RuleOf72

Estimates the time required to double an investment.

import { RuleOf72 } from "calculators";

const r72 = new RuleOf72(8);
const result = r72.calculate();
console.log(result.estimatedYears); // 9
console.log(result.exactYears);     // 9.01

Parameter	Type	Description
ratePercentage	number	Annual rate, 0 < rate < 100

Returns: RuleOf72Result

Field	Type	Description
estimatedYears	number	72 / rate (rounded to 2 decimals)
exactYears	number	ln(2) / ln(1 + rate/100)

---

Loans & Debt

Mortgage

Calculates monthly and yearly mortgage payments.

import { Mortgage } from "calculators";

const m = new Mortgage(300000, 60000, 6, 30);
// constructor(amount, downPayment, ratePercentage, years)
const result = m.calculate();
console.log(result.monthlyPayment);        // 1438.92
console.log(result.yearlyPayment);         // 17267.04
console.log(result.totalNumberOfPayments); // 360

Parameter	Type	Description
amount	number	Total property price (must be > 0)
downPayment	number	Down payment (>= 0, must be < amount)
ratePercentage	number	Annual rate, 0 < rate < 100
years	number	Loan term as a positive integer

Returns: MortgageResult

Field	Type	Description
monthlyPayment	number	Monthly payment amount
yearlyPayment	number	Annual payment amount
totalNumberOfPayments	number	Total number of monthly payments

---

LoanAmortization

Generates a full amortization schedule with principal/interest breakdown per payment.

import { LoanAmortization } from "calculators";

const la = new LoanAmortization(200000, 6, 30);
const result = la.calculate();

console.log(result.monthlyPayment); // 1199.10
console.log(result.totalInterest);  // 231677.04
console.log(result.schedule[0]);
// { payment: 1, principal: 199.10, interest: 1000.00, remainingBalance: 199800.90 }

Parameter	Type	Description
loanAmount	number	Loan principal (must be > 0)
ratePercentage	number	Annual rate, 0 < rate < 100
years	number	Loan term as a positive integer (max 100)

Returns: AmortizationResult

Field	Type	Description
monthlyPayment	number	Fixed monthly payment
totalPayments	number	Total number of payments
totalInterest	number	Total interest paid over the life of the loan
schedule	AmortizationEntry[]	Per-payment breakdown

Each AmortizationEntry:

Field	Type	Description
payment	number	Payment number (1-indexed)
principal	number	Principal portion of the payment
interest	number	Interest portion of the payment
remainingBalance	number	Balance remaining after payment

---

AutoLoan

Calculates auto loan payments using the standard amortization formula, with term in months.

import { AutoLoan } from "calculators";

const al = new AutoLoan(35000, 5000, 4.5, 60);
// constructor(vehiclePrice, downPayment, ratePercentage, termMonths)
const result = al.calculate();
console.log(result.monthlyPayment); // 559.28
console.log(result.totalInterest);  // 3556.80

Parameter	Type	Description
vehiclePrice	number	Vehicle price (must be > 0)
downPayment	number	Down payment (>= 0, must be < price)
ratePercentage	number	Annual rate, 0 < rate < 100
termMonths	number	Loan term in months (positive integer)

Returns: AutoLoanResult

Field	Type	Description
loanAmount	number	Financed amount (price - down payment)
monthlyPayment	number	Monthly payment
totalPaid	number	Total of all payments
totalInterest	number	Total interest paid

---

DebtPayoff

Calculates how long it takes to pay off a debt with a fixed monthly payment.

import { DebtPayoff } from "calculators";

const dp = new DebtPayoff(5000, 18, 200);
// constructor(balance, ratePercentage, monthlyPayment)
const result = dp.calculate();
console.log(result.months);        // 32
console.log(result.totalInterest); // 1313.97

Parameter	Type	Description
balance	number	Outstanding debt (must be > 0)
ratePercentage	number	Annual rate, 0 < rate < 100
monthlyPayment	number	Fixed payment (must exceed monthly interest)

Returns: DebtPayoffResult

Field	Type	Description
months	number	Number of months to pay off
totalPaid	number	Total amount paid
totalInterest	number	Total interest paid

---

Investments & Savings

RetirementSavings

Projects the future value of retirement savings with regular contributions.

import { RetirementSavings } from "calculators";

const rs = new RetirementSavings(50000, 500, 7, 25);
// constructor(initialBalance, monthlyContribution, ratePercentage, years)
const result = rs.calculate();
console.log(result.futureValue);       // 676,570+ (varies by rounding)
console.log(result.totalContributions); // 150000
console.log(result.totalInterest);      // futureValue - 50000 - 150000

Parameter	Type	Description
initialBalance	number	Starting balance (>= 0)
monthlyContribution	number	Monthly contribution (>= 0)
ratePercentage	number	Annual return rate, 0-100
years	number	Investment horizon (must be > 0)

Returns: RetirementResult

Field	Type	Description
futureValue	number	Projected total value
totalContributions	number	Sum of all contributions
totalInterest	number	Total growth from interest

---

PresentValue

Calculates the present value of a future sum: PV = FV / (1 + r)^n.

import { PresentValue } from "calculators";

const pv = new PresentValue(10000, 5, 10);
// constructor(futureValue, ratePercentage, years)
console.log(pv.calculate()); // 6139.13

Parameter	Type	Description
futureValue	number	Future amount (must be > 0)
ratePercentage	number	Discount rate, 0-100
years	number	Time period (must be > 0)

Returns: number — the present value.

---

SavingsGoal

Calculates the monthly savings needed to reach a financial goal.

import { SavingsGoal } from "calculators";

const sg = new SavingsGoal(50000, 10000, 5, 5);
// constructor(goalAmount, currentSavings, ratePercentage, years)
const result = sg.calculate();
console.log(result.monthlySavings);      // ~588
console.log(result.totalContributions);  // monthlySavings * 60
console.log(result.interestEarned);      // goal - currentSavings - contributions

Parameter	Type	Description
goalAmount	number	Target amount (must be > 0)
currentSavings	number	Current savings (>= 0, must be < goal)
ratePercentage	number	Annual return rate, 0-100
years	number	Time horizon (must be > 0)

Returns: SavingsGoalResult

Field	Type	Description
monthlySavings	number	Required monthly savings
totalContributions	number	Total amount contributed
interestEarned	number	Total interest earned

---

DollarCostAveraging

Simulates periodic fixed-amount investments at varying prices.

import { DollarCostAveraging } from "calculators";

const prices = [50, 45, 55, 40, 60];
const dca = new DollarCostAveraging(100, prices);
// constructor(investmentPerPeriod, prices)
const result = dca.calculate();
console.log(result.totalShares);
console.log(result.averageCostPerShare);
console.log(result.totalInvested); // 500

Parameter	Type	Description
investmentPerPeriod	number	Fixed investment amount (must be > 0)
prices	number[]	Array of prices per period (all must be > 0)

Returns: DCAResult

Field	Type	Description
totalInvested	number	Total amount invested
totalShares	number	Total shares purchased
averageCostPerShare	number	Average cost per share
currentValue	number	Value at the final price
gainLoss	number	Dollar gain or loss (currentValue - totalInvested)

---

ROI

Calculates return on investment with optional annualized ROI.

import { ROI } from "calculators";

const roi = new ROI(10000, 15000, 3);
// constructor(cost, revenue, years?)
const result = roi.calculate();
console.log(result.roi);           // 50.00
console.log(result.annualizedRoi); // 14.47
console.log(result.netProfit);     // 5000.00

Parameter	Type	Description
cost	number	Initial investment (must be > 0)
revenue	number	Total return (>= 0)
years	number?	Optional holding period for annualized ROI

Returns: ROIResult

Field	Type	Description
roi	number	ROI as a percentage
annualizedRoi	number?	Annualized ROI (if years provided)
netProfit	number	Revenue minus cost

---

InflationAdjustedReturn

Calculates the real rate of return after inflation using the Fisher equation.

import { InflationAdjustedReturn } from "calculators";

const iar = new InflationAdjustedReturn(10, 3);
// constructor(nominalRatePercentage, inflationRatePercentage)
const result = iar.calculate();
console.log(result.realReturn); // 6.80

Parameter	Type	Description
nominalRatePercentage	number	Nominal return rate, 0-100
inflationRatePercentage	number	Inflation rate, 0 to <100

Returns: InflationAdjustedResult

Field	Type	Description
realReturn	number	Real return percentage
nominalRate	number	Input nominal rate
inflationRate	number	Input inflation rate

---

Tax & Business

TaxBracket

Calculates progressive income tax with bracket breakdown.

import { TaxBracket } from "calculators";
import type { Bracket } from "calculators";

const brackets: Bracket[] = [
  { min: 0,     max: 11000,  rate: 10 },
  { min: 11000, max: 44725,  rate: 12 },
  { min: 44725, max: 95375,  rate: 22 },
  { min: 95375, max: 182100, rate: 24 },
];

const tb = new TaxBracket(100000, brackets);
const result = tb.calculate();
console.log(result.totalTax);      // Total tax owed
console.log(result.effectiveRate); // Effective tax rate %
console.log(result.marginalRate);  // Highest applicable bracket rate
console.log(result.brackets);      // Per-bracket breakdown

Parameter	Type	Description
income	number	Taxable income (must be > 0)
taxBrackets	Bracket[]	Array of tax brackets (non-overlapping)

Each Bracket:

Field	Type	Description
min	number	Bracket lower bound (>= 0)
max	number	Bracket upper bound (must be > min)
rate	number	Tax rate for this bracket, 0-100

Returns: TaxBracketResult

Field	Type	Description
totalTax	number	Total tax owed
effectiveRate	number	Effective tax rate as a percentage
marginalRate	number	Marginal (highest applicable) tax rate
brackets	BracketBreakdown[]	Per-bracket tax detail

---

BreakEven

Calculates the break-even point in units and revenue.

import { BreakEven } from "calculators";

const be = new BreakEven(50000, 100, 60);
// constructor(fixedCosts, pricePerUnit, variableCostPerUnit)
const result = be.calculate();
console.log(result.breakEvenUnits);   // 1250
console.log(result.breakEvenRevenue); // 125000
console.log(result.contributionMargin); // 40

Parameter	Type	Description
fixedCosts	number	Total fixed costs (must be > 0)
pricePerUnit	number	Selling price per unit (must be > 0)
variableCostPerUnit	number	Variable cost per unit (>= 0, must be < price)

Returns: BreakEvenResult

Field	Type	Description
breakEvenUnits	number	Units to sell to break even (rounded up)
breakEvenRevenue	number	Revenue at break-even point
contributionMargin	number	Price minus variable cost per unit
contributionMarginRatio	number	Contribution margin as a percentage of price

---

Scripts

Command	Description
npm test	Run all tests with Jest
npm run build	Compile TypeScript to dist/
npm run publish-lib	Build and publish to npm
npm run publish-beta	Build and publish with beta tag
npm run publish-dryrun	Build and simulate publish
npm run patch	Bump patch version
npm run minor	Bump minor version
npm run major	Bump major version

Testing

The library includes 173 tests across 15 test suites covering:

• Input validation (boundary values, negative inputs, zero values)
• Mathematical correctness (verified against known financial formulas)
• Edge cases (rounding precision, exact payoff, single-period calculations)
• Safety guards (loop limits, maximum term lengths)

npm test

Project Structure

Calculators/
  app/
    index.ts                  # Library entry point (all exports)
    calculators/
      SimpleInterest.ts
      CompoundInterest.ts
      mortgage.ts
      LoanAmortization.ts
      RetirementSavings.ts
      PresentValue.ts
      DebtPayoff.ts
      ROI.ts
      RuleOf72.ts
      InflationAdjustedReturn.ts
      DollarCostAveraging.ts
      AutoLoan.ts
      SavingsGoal.ts
      BreakEven.ts
      TaxBracket.ts
    __tests__/                # Jest test suites (one per calculator)
  dist/                       # Compiled output (generated)
  tsconfig.json               # Build config (strict mode)
  tsconfig.test.json          # Test config (extends build)
  jest.config.js              # Jest configuration

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-calculator
3. Write tests first (TDD) in app/__tests__/
4. Implement the calculator in app/calculators/
5. Export from app/index.ts
6. Ensure all tests pass: npm test
7. Ensure the build is clean: npm run build
8. Submit a pull request

All calculators follow the same pattern:

export interface MyCalculatorResult {
  // typed result fields
}

export default class MyCalculator {
  constructor(/* parameters */) { /* assign fields */ }

  _validate() {
    // throw descriptive errors for invalid inputs
  }

  calculate(): MyCalculatorResult {
    this._validate();
    // computation with toFixed(2) rounding
    return { /* result */ };
  }
}

License

MIT