compound interest

A finance calculator to:

calculate compound interest over a period of time with different investment types.
calculate mortgage repayments and interest only payments.

Features

This calculator can be used to calculate the future value of a present lump sum with contributions, debt repayment or mortgage. The calculator compounds interest per period and can be used to calculate the value of investments or debt over a period of time.

For example, if you invest $1,000 today at a 7% annual interest rate, how much will $1,000 be worth if invested for 10 years?

Compound Interest

1. calculate compound interest of a lump sum over time
2. calculate compound interest with additional contributions
3. calculate compound interest with interest only payments towards the principal borrowed
4. calculate compound interest with repayments towards the principal

Mortgage

1. calculate mortgage - repayment
2. calculate mortgage - interest only

Installation

This library will work both client and server side, it is bundled using esbuild and is written in TypeScript.

If this package is being used on the server then it requires node 18 and above however it exports for both CJS and ESM.

npm install @jdizm/finance-calculator

Usage

Importing the library:

// CommonJS
const { compoundInterestPerPeriod, mortgageCalculator } = require("@jdizm/finance-calculator");

// ESM
import { compoundInterestPerPeriod, mortgageCalculator } from "@jdizm/finance-calculator";

Mortgage Calculator

// example interest only mortgage repayment
const result = mortgageCalculator(
  {
    homeValue: 150_000,
    deposit: 15_000,
    interestRate: 6,
    years: 25
  },
  "interestOnly"
);

Compound Interest Calculator

// calculate a lump sum over 2 years
const lumpSum = compoundInterestPerPeriod({
  type: "lumpSum",
  principal: 500,
  rate: 3.4,
  years: 2,
  paymentsPerAnnum: 12 // displays monthly interest balance
});

// calculate a lump sum over 2 years with additional contributions of 500 per month
const additionalContributions = compoundInterestPerPeriod({
  type: "contribution",
  principal: 500,
  rate: 3.4,
  years: 2,
  paymentsPerAnnum: 12,
  amountPerAnnum: 6_000,
  accrualOfPaymentsPerAnnum: true
});

// example interest only payment that compounds at 4% per annum
// with an interest rate of 6% on a principal of 250,000
const interestOnly = compoundInterestPerPeriod({
  type: "debtRepayment",
  principal: 250_000,
  rate: 4,
  years: 25,
  paymentsPerAnnum: 12,
  debtRepayment: {
    interestRate: 6,
    type: "interestOnly"
  }
});

// example debtRepayment that compounds at 4% per annum
// with an interest rate of 6% on a principal of 150,000
const repayment = compoundInterestPerPeriod({
  type: "debtRepayment",
  principal: 150_000,
  rate: 4,
  years: 25,
  paymentsPerAnnum: 12,
  debtRepayment: {
    interestRate: 6,
    type: "repayment"
  }
});

Options

type: 'lumpSum' | 'contribution' | 'debtRepayment - the type of investment to calculate
principal: number The initial amount invested or borrowed
rate: number The interest rate (or growth rate) per annum
years: number The number of years invested
paymentsPerAnnum: number The number of contribution payments per annum (eg 12 for monthly) will be used to show the interest balance per period. So if you want the interest to show monthly for each year then make sure you define the paymentsPerAnnum as 12.
currentPositionInYears: number The current position in years (eg 2 for the second year of the investment)

Contribution Options

amountPerAnnum: number The amount of contributions per annum (eg 6_000 for 500 per month)
accrualOfPaymentsPerAnnum: number If provided payments accrue interest per annum; Otherwise interest is only accrued on the principal payment.

Debt Repayment Options

debtRepayment: object if provided this denotes that the principal is borrowed.

It will calculate the monthly interest payments for a given interest rate and principal borrowed.

interestRate: number - the interest rate of borrowing
type: "interestOnly" // this is the default

Investment Types

What are investment types? These are used to calculate the final results:

lumpSum - a single investment calculated over a period of time
debtRepayment - a borrowed investment calculated over a period of time with a decreasing principal or interest only payments
contribution - a single investment calculated over a period of time with additional contribution

Building with Typescript

Only certain tsconfig.json fields are respected when building with esbuild.

tsconfig.json

"target": "es2022", // recommended over ESNext
"module": "preserve", // added in ts 5.4 and implies "moduleResolution": "bundler"

References

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

chore(deps): update dependency eslint to v9

Detected dependencies

github-actions

.github/workflows/node.yml

actions/checkout v4

volta-cli/action v4

.github/workflows/release.yml

actions/checkout v4

volta-cli/action v4

actions/checkout v4

actions/setup-node v4

npm

package.json

@types/node ^20.2.1

@typescript-eslint/eslint-plugin ^7.0.0

@typescript-eslint/parser ^7.0.0

@vitest/coverage-v8 ^1.2.2

eslint ^8.37.0

eslint-config-prettier ^9.0.0

eslint-import-resolver-alias ^1.1.2

eslint-plugin-import ^2.27.5

npm-dts ^1.3.12

prettier ^3.0.0

typescript ^5.4.0

vite-node ^1.2.2

vitest ^1.2.2

node ^18.0.0 || >= 20.0.0

node 20.13.1

test-package/package.json

@types/node ^20.2.1

tsx ^4.7.1

typescript ^5.0.4

vite-node ^1.2.2

node 20.13.1

Check this box to trigger a request for Renovate to run again on this repository

jdizm / compound-interest Goto Github PK