Every time I needed to add financial calculations to a project, I'd either:

• 1.Find a package that did 80% of what I needed
• 2.Copy-paste code from StackOverflow and hope the math was right
• 3.Implement it myself and spend hours testing edge cases

So I built the package I kept wishing existed.

retirement-calculator is a TypeScript library for financial calculations. No dependencies, no bloat, just pure math that's been tested to death.

npm install @introvertedspud/retirement-calculator

Goal-Based Retirement Planning

import { calculateMonthlySavingsNeeded } from "@introvertedspud/retirement-calculator";

const monthlySavings = calculateMonthlySavingsNeeded({
  currentAge: 35,
  retirementAge: 65,
  currentSavings: 50000,
  targetAmount: 2000000,
  annualReturn: 0.07,
});

console.log(`Save $${monthlySavings.toFixed(2)} per month`);
// Output: Save $1,847.23 per month

Compound Interest Projections

import { calculateFutureValue } from "@introvertedspud/retirement-calculator";

const futureValue = calculateFutureValue({
  principal: 10000,
  monthlyContribution: 500,
  annualReturn: 0.07,
  years: 30,
});

console.log(`You'll have $${futureValue.toFixed(2)}`);
// Output: You'll have $566,764.21

Glidepath Allocation

import { calculateGlidepath } from "@introvertedspud/retirement-calculator";

const allocation = calculateGlidepath({
  currentAge: 35,
  retirementAge: 65,
  stockAllocationAtStart: 0.9, // 90% stocks at 35
  stockAllocationAtRetirement: 0.3, // 30% stocks at 65
});

console.log(`Current allocation: ${(allocation * 100).toFixed(0)}% stocks`);
// Output: Current allocation: 90% stocks

I wanted the API to be obvious. No magic strings, no guessing units, no hidden assumptions.

// Bad (ambiguous)
calculate(50000, 2000000, 35, 65, 7);

// Good (clear)
calculateMonthlySavingsNeeded({
  currentSavings: 50000,
  targetAmount: 2000000,
  currentAge: 35,
  retirementAge: 65,
  annualReturn: 0.07, // 7% as decimal, not integer
});

Every function returns a number in the most useful unit:

• •Savings needed? Monthly amount in dollars
• •Future value? Total in dollars
• •Allocation? Percentage as decimal (0.0 to 1.0)

Full type definitions included. Your editor will tell you what parameters are needed and what you'll get back.

The goal-based calculator uses the future value of an annuity formula, solved for payment:

PMT = (FV - PV(1 + r)^n) × r / ((1 + r)^n - 1)

Where:
- PMT = monthly payment needed
- FV = future value target
- PV = present value (current savings)
- r = monthly interest rate (annual / 12)
- n = number of months

Most calculators use the formula forwards: "here's what you'll have." But solving for PMT lets us answer the more useful question: "here's what you need to save."

Standard future value formula with monthly contributions:

FV = PV(1 + r)^n + PMT × [((1 + r)^n - 1) / r]

Where:
- First term = growth of initial savings
- Second term = growth of monthly contributions

Linear interpolation between start and end allocations:

allocation = start - ((start - end) × (currentAge - startAge) / (retirementAge - startAge))

Simple, but effective for modeling target-date fund behavior.

Financial calculations need to be right. No "close enough."

• •Unit tests for every function
• •Edge case handling (zero savings, negative returns, etc.)
• •Comparison against known-correct values from financial calculators
• •Boundary testing (age limits, percentage ranges)

test("monthly savings matches online calculator", () => {
  const result = calculateMonthlySavingsNeeded({
    currentAge: 30,
    retirementAge: 65,
    currentSavings: 25000,
    targetAmount: 1000000,
    annualReturn: 0.07,
  });

  // Verified against multiple online calculators
  expect(result).toBeCloseTo(646.98, 2);
});

Currently powering:

• •Common Cents Academy - All retirement calculators
• •My personal finance spreadsheets
• •Client projects that need financial projections

Because financial calculations shouldn't be proprietary. The math is public knowledge. The formulas are in textbooks. Making people reimplement this over and over is wasteful.

Also, open source means:

• •Community can verify the math is correct
• •Bug reports from real-world usage
• •Contributions for features I haven't thought of

Planning to add:

• •Inflation adjustment calculations
• •Tax-advantaged account modeling (Roth vs Traditional)
• •Social Security integration
• •Monte Carlo simulation for risk analysis
• •Investment portfolio rebalancing calculations

Found a bug? Have a feature request? PRs welcome at github.com/introvertedspud/retirement-calculator.

Especially interested in:

• •Additional test cases
• •Documentation improvements
• •Real-world usage examples
• •Bug reports with reproducible cases

Zero Dependencies

• •Pure TypeScript implementation
• •No runtime dependencies
• •Tree-shakeable for optimal bundle size

Modern Build

• •ESM and CommonJS builds
• •TypeScript definitions included
• •Works in Node.js and browsers

Quality

• •100% TypeScript
• •Comprehensive test suite
• •Semantic versioning
• •Automated CI/CD

Building this package taught me more about financial math than years of reading articles. You don't really understand compound interest until you've implemented it. You don't appreciate the edge cases until you've tested them.

If you need financial calculations in your project, give it a try:

npm install @introvertedspud/retirement-calculator

And if you find bugs (there are always bugs), let me know.