DEV Community: DaikuanTool

Modeling Loan Prepayments in JavaScript: Shorter Term vs Lower Monthly Payment

DaikuanTool — Sat, 31 Oct 2026 03:09:30 +0000

A partial loan prepayment sounds like a subtraction problem: take the extra payment off the remaining balance. That part is easy. The next step is where implementations often go wrong.

After the balance falls, a lender can usually rebuild the plan in at least two ways:

keep the remaining number of payments and lower the payment amount;
keep the payment near its old level and shorten the remaining term.

Both plans start with the same reduced balance. They do not have the same future cash flows, interest cost, or end date. In code, that means they need separate functions and tests, rather than a single prepay() flag bolted onto an amortization loop.

This article models a fixed-rate, monthly, level-payment loan. It assumes a payment is made at the end of each month, the rate does not change, and the prepayment happens immediately after a scheduled payment. It does not model lender-specific rounding, daily interest between payment dates, fees, or contractual eligibility rules.

Start with the balance at the prepayment date

Let:

P be the original principal;
r be the monthly rate;
N be the original number of monthly payments;
k be the number of payments already made.

For a level-payment loan, the original payment is:

A = P × r × (1 + r)^N / ((1 + r)^N - 1)

The balance immediately after payment k can be calculated without retaining every previous schedule row:

B(k) = P × (1 + r)^k - A × (((1 + r)^k - 1) / r)

The zero-rate case needs its own branch. Dividing by r is not a harmless detail; it is a real bug when a test uses 0% financing.

function monthlyPayment(principal, annualRate, months) {
  if (months <= 0) throw new RangeError("months must be positive");

  const r = annualRate / 12;
  if (r === 0) return principal / months;

  const growth = (1 + r) ** months;
  return (principal * r * growth) / (growth - 1);
}

function balanceAfterPayments({ principal, annualRate, months }, paidMonths) {
  if (paidMonths <= 0) return principal;
  if (paidMonths >= months) return 0;

  const r = annualRate / 12;
  const payment = monthlyPayment(principal, annualRate, months);

  if (r === 0) {
    return principal - payment * paidMonths;
  }

  const growth = (1 + r) ** paidMonths;
  const balance = principal * growth - payment * ((growth - 1) / r);

  // Formula arithmetic can leave a tiny negative value at the final payment.
  return Math.max(0, balance);
}

For an original loan of 1,000,000 at 3.5% for 360 months, the monthly payment is about 4,490.45. After 60 payments, the model gives a balance of about 896,970.73.

If the borrower then prepays 200,000, the common starting point for both revised plans is:

896,970.73 - 200,000.00 = 696,970.73

Do this subtraction once. From this point on, the two choices diverge.

Option 1: keep the term, lower the payment

In the lower-payment option, the remaining term stays at N - k. The new payment is simply a new annuity payment for the reduced balance.

function lowerPaymentAfterPrepayment(loan, paidMonths, prepayment) {
  const oldBalance = balanceAfterPayments(loan, paidMonths);
  const newPrincipal = Math.max(0, oldBalance - prepayment);
  const remainingMonths = loan.months - paidMonths;

  if (newPrincipal === 0) {
    return { newPrincipal, payment: 0, remainingMonths: 0 };
  }

  return {
    newPrincipal,
    payment: monthlyPayment(newPrincipal, loan.annualRate, remainingMonths),
    remainingMonths,
  };
}

With the example inputs, there are 300 months left. The revised payment is about 3,489.20 per month.

This is a useful option when the product goal is a lower required monthly outflow. It still reduces future interest because the balance falls, but interest continues to accrue across the same 300 remaining periods.

Option 2: keep the payment, shorten the term

For the shorter-term option, keep a target payment close to the original monthly payment and solve for a new number of periods. Rearranging the payment formula gives:

n = -log(1 - B × r / A) / log(1 + r)

n is normally fractional. A real repayment plan needs whole payment periods, so round up and let the final payment absorb the small residual. Rounding down can create a negative final balance or an impossible payment schedule.

function monthsForPayment(principal, annualRate, payment) {
  const r = annualRate / 12;

  if (principal === 0) return 0;
  if (payment <= 0) throw new RangeError("payment must be positive");
  if (r === 0) return Math.ceil(principal / payment);
  if (payment <= principal * r) {
    throw new RangeError("payment does not cover monthly interest");
  }

  return Math.ceil(
    -Math.log(1 - (principal * r) / payment) / Math.log(1 + r)
  );
}

function shorterTermAfterPrepayment(loan, paidMonths, prepayment) {
  const oldBalance = balanceAfterPayments(loan, paidMonths);
  const newPrincipal = Math.max(0, oldBalance - prepayment);

  if (newPrincipal === 0) {
    return { newPrincipal, payment: 0, remainingMonths: 0 };
  }

  const targetPayment = monthlyPayment(
    loan.principal,
    loan.annualRate,
    loan.months
  );
  const remainingMonths = monthsForPayment(
    newPrincipal,
    loan.annualRate,
    targetPayment
  );

  return {
    newPrincipal,
    payment: monthlyPayment(newPrincipal, loan.annualRate, remainingMonths),
    remainingMonths,
  };
}

The same example finishes in about 207 remaining payments, rather than 300. Because the period count has changed, the recalculated regular payment may differ from the old payment by a few cents or units depending on the rounding policy. In this implementation it is about 4,489.85.

That small difference is intentional. The term is the constraint; the payment is derived from it. If a lender promises an exact payment instead, generate the schedule with that exact payment and calculate a final, nonstandard payment.

Keep prepayment fees outside the balance reduction

A common modeling mistake is subtracting a fee from the loan balance alongside the prepayment. These are different cash flows.

If a borrower pays 200,000 toward principal and 2,000 in a penalty, the revised principal is still reduced by 200,000. The 2,000 is a separate out-of-pocket cost. It belongs in a comparison of net interest saved, not in the amortized principal.

function netInterestSaved(oldFutureInterest, newFutureInterest, penalty = 0) {
  return oldFutureInterest - newFutureInterest - penalty;
}

To obtain oldFutureInterest and newFutureInterest, create schedules for the remaining old plan and the revised plan, then sum their interest fields. That is one of the places where a schedule is useful. The balance formula avoids storing 360 historical rows; it does not mean an application should never generate future rows for a user-facing table.

Test the invariants, not just one displayed number

Financial code gets fragile when tests only assert a screenshot value. These checks cover the two paths and a few failure cases.

import test from "node:test";
import assert from "node:assert/strict";

const loan = {
  principal: 1_000_000,
  annualRate: 0.035,
  months: 360,
};

test("balance after 60 payments matches the model", () => {
  const balance = balanceAfterPayments(loan, 60);
  assert.ok(Math.abs(balance - 896_970.73) < 0.01);
});

test("lower-payment option preserves the remaining term", () => {
  const result = lowerPaymentAfterPrepayment(loan, 60, 200_000);
  assert.equal(result.remainingMonths, 300);
  assert.ok(Math.abs(result.payment - 3_489.20) < 0.01);
});

test("shorter-term option preserves a payment near the original", () => {
  const result = shorterTermAfterPrepayment(loan, 60, 200_000);
  assert.equal(result.remainingMonths, 207);
  assert.ok(Math.abs(result.payment - 4_489.85) < 0.01);
});

test("0% loans do not divide by zero", () => {
  const result = lowerPaymentAfterPrepayment(
    { principal: 12_000, annualRate: 0, months: 12 },
    3,
    3_000
  );
  assert.equal(result.remainingMonths, 9);
  assert.equal(result.payment, 666.6666666666666);
});

Production code should add tests for a full payoff, an attempt to prepay more than the balance, a payment too small to cover interest, and the final scheduled payment. Whether currency is rounded every month or only for display also needs an explicit policy. Do not let toFixed(2) quietly become the accounting model.

Validate the cash flows people will actually see

The formula is only one layer of the feature. A useful interface should make the changed constraint visible:

After the prepayment	What stays fixed	What changes
Lower payment	Remaining months	Monthly payment falls
Shorter term	Payment near the old amount	Payoff date moves earlier

An interactive check is also handy when debugging input handling. To try the same kind of comparison with a remaining balance, a partial prepayment, and either recalculation path, use this loan prepayment calculator. Treat its result as a model output and compare it with the lender's revised schedule before making a payment decision.

The practical lesson is simple: a partial prepayment changes the principal first. The choice to hold the term or the payment constant is a separate business rule. Put that choice in your API, code paths, tests, and UI. It should never be an accidental side effect of the amortization formula.

How to Calculate a Remaining Loan Balance Without Storing 360 Payments

DaikuanTool — Wed, 28 Oct 2026 10:06:29 +0000

A 30-year monthly loan has 360 payments. Generating every row is useful when a UI needs an amortization table, but it is unnecessary when the product only needs one answer:

What is the remaining balance after payment 60?

For a fixed-rate, fixed-payment loan, the answer has a closed form. You can calculate it in constant time and constant extra space—no 360-element array, no loop through every previous payment.

This post derives that formula, implements it in TypeScript, and tests it against an iterative reference implementation. The goal is not to replace a full schedule everywhere; it is to choose the smallest correct computation for the feature you are building.

The model assumes a fixed annual rate, monthly payments, an annuity (level-payment) repayment method, no fees, no prepayments, and a first payment one month after disbursement. It is a programming example, not a loan quote or financial advice.

Define the inputs precisely

We need four values:

type FixedRateLoan = {
  principal: number;  // P: amount borrowed
  annualRate: number; // for example, 0.035 for 3.5%
  months: number;     // total scheduled monthly payments
};

Let:

P be the original principal;
r be the monthly rate, annualRate / 12;
n be the total number of payments;
A be the fixed monthly payment; and
k be the number of payments already made.

The balance we want is the balance immediately after payment k. That timing matters. A balance before the 60th payment includes one more month's interest than a balance after it.

First calculate the fixed payment

For a positive monthly rate, the annuity payment is:

A = P × r × (1 + r)^n / ((1 + r)^n - 1)

The zero-rate case must be handled separately. If r is zero, the payment is simply P / n; substituting zero into the expression above creates 0 / 0.

export function annuityPayment(loan: FixedRateLoan): number {
  const { principal, annualRate, months } = loan;

  if (principal < 0 || annualRate < 0 || months < 1) {
    throw new Error("principal and annualRate must be non-negative; months must be positive");
  }

  const r = annualRate / 12;
  if (r === 0) return principal / months;

  const factor = Math.pow(1 + r, months);
  return (principal * r * factor) / (factor - 1);
}

This payment formula is not yet the remaining balance. It only tells us the fixed amount paid each month. The balance also depends on how interest accumulates and how each payment reduces it.

Derive the balance formula

At the start, the balance is P. After one period of interest and one payment:

B₁ = P × (1 + r) - A

After two periods:

B₂ = (P × (1 + r) - A) × (1 + r) - A

Expanding that recurrence produces a geometric series. After k payments:

Bₖ = P × (1 + r)^k - A × (((1 + r)^k - 1) / r)

The first term grows the original balance through k interest periods. The second term is the future-value-at-month-k effect of the k payments already made.

An equivalent, and sometimes more intuitive, expression discounts the remaining payments back to month k:

Bₖ = A × (1 - (1 + r)^-(n - k)) / r

Both are valid for r > 0. In code, the first form makes the relationship to the recurrence explicit; the second is a useful independent check in a test.

Implement the O(1) balance calculation

The function below keeps the inputs immutable, clamps the paid-payment count to the loan term, and handles the zero-rate case.

const clamp = (value: number, min: number, max: number): number =>
  Math.min(max, Math.max(min, value));

export function remainingAnnuityBalance(
  loan: FixedRateLoan,
  paidPayments: number,
): number {
  const { principal, annualRate, months } = loan;

  if (principal < 0 || annualRate < 0 || months < 1) {
    throw new Error("principal and annualRate must be non-negative; months must be positive");
  }

  // This function models completed whole monthly payments.
  const k = clamp(Math.trunc(paidPayments), 0, months);
  if (k === 0) return principal;
  if (k === months) return 0;

  const r = annualRate / 12;
  if (r === 0) return principal * (1 - k / months);

  const payment = annuityPayment(loan);
  const growth = Math.pow(1 + r, k);
  const balance = principal * growth - payment * ((growth - 1) / r);

  // A tiny negative number can occur because JavaScript uses binary floats.
  return Math.max(0, balance);
}

This is O(1) time and O(1) extra memory. Math.pow is not a loop over the loan periods from your application's perspective; the function does not allocate or retain 360 schedule rows.

Avoid rounding payment, growth, or balance to cents inside this function. Round only at the boundary where a number is displayed. Rounding the balance at every simulated period is exactly the sort of detail that makes two implementations disagree by a few cents.

Check it against a 30-year example

Take a principal of 1,000,000 currency units, a 3.5% annual rate, and 360 monthly payments:

const loan = {
  principal: 1_000_000,
  annualRate: 0.035,
  months: 360,
};

console.log(annuityPayment(loan).toFixed(2));
// 4490.45

console.log(remainingAnnuityBalance(loan, 60).toFixed(2));
// 896970.73

console.log(remainingAnnuityBalance(loan, 120).toFixed(2));
// 774268.75

console.log(remainingAnnuityBalance(loan, 240).toFixed(2));
// 454104.01

It can be surprising that 60 payments of 4,490.45 do not reduce a 1,000,000 principal by 269,427. The difference is interest. In an annuity schedule, early payments contain a larger interest portion because the opening balance is still high. The formula is a concise way to expose that fact; it is not a shortcut that changes the underlying economics.

Keep a loop as a reference implementation

The closed form is ideal when you need one balance, but an iterative version is still valuable in tests. It acts as an executable definition of the recurrence:

export function remainingBalanceByIteration(
  loan: FixedRateLoan,
  paidPayments: number,
): number {
  const k = clamp(Math.trunc(paidPayments), 0, loan.months);
  const r = loan.annualRate / 12;
  const payment = annuityPayment(loan);
  let balance = loan.principal;

  for (let period = 0; period < k; period += 1) {
    const interest = balance * r;
    const principalPaid = payment - interest;
    balance = Math.max(0, balance - principalPaid);
  }

  return balance;
}

This reference implementation is O(k) time but still uses O(1) extra memory because it holds only the current balance. Building an array of rows is a separate choice. It is appropriate for a table or CSV export, but not required just to find a balance.

Test formula, boundaries, and invariants

Formula code benefits from tests that compare two implementations rather than tests that only repeat the formula. Here is a Vitest example:

import { describe, expect, it } from "vitest";

const loan = {
  principal: 1_000_000,
  annualRate: 0.035,
  months: 360,
};

describe("remainingAnnuityBalance", () => {
  it("matches an iterative recurrence at several checkpoints", () => {
    for (const paid of [0, 1, 60, 120, 240, 359, 360]) {
      expect(remainingAnnuityBalance(loan, paid)).toBeCloseTo(
        remainingBalanceByIteration(loan, paid),
        7,
      );
    }
  });

  it("returns known balances for the 3.5%, 30-year example", () => {
    expect(annuityPayment(loan)).toBeCloseTo(4490.45, 2);
    expect(remainingAnnuityBalance(loan, 60)).toBeCloseTo(896970.73, 2);
    expect(remainingAnnuityBalance(loan, 120)).toBeCloseTo(774268.75, 2);
  });

  it("handles a zero-rate installment loan", () => {
    const zeroRateLoan = { principal: 120_000, annualRate: 0, months: 12 };

    expect(remainingAnnuityBalance(zeroRateLoan, 0)).toBe(120_000);
    expect(remainingAnnuityBalance(zeroRateLoan, 5)).toBe(70_000);
    expect(remainingAnnuityBalance(zeroRateLoan, 12)).toBe(0);
  });

  it("does not return a negative balance outside the term", () => {
    expect(remainingAnnuityBalance(loan, -3)).toBe(loan.principal);
    expect(remainingAnnuityBalance(loan, 999)).toBe(0);
  });
});

The test has two complementary parts. Known-value assertions catch an accidental change in the business definition. Comparing with the recurrence catches algebra or indexing mistakes, such as treating k as payments remaining instead of payments completed.

Know when not to use the shortcut

The closed form is correct only while its assumptions remain true. Do not use it unchanged when the loan has:

a variable rate or a rate reset;
an irregular first period or non-monthly payment dates;
fees added to each payment;
a partial prepayment that changes future payment or term;
payment holidays, arrears, or a balloon payment; or
equal-principal rather than fixed-payment amortization.

For those cases, model the actual cash-flow events in chronological order. The good news is that you still do not need to store every intermediate row unless the product needs to display them. A reducer over events can keep just the current balance while applying each event.

Use the right computation for the screen

A full amortization schedule is the right output for “show me every payment.” A closed form is the right tool for “show me the balance after 60 payments,” a dashboard checkpoint, or a what-if calculation that would otherwise create disposable arrays on every keystroke.

To verify the same fixed-rate, monthly annuity inputs interactively, try this remaining mortgage balance calculator. Compare the result with a lender's schedule, keeping in mind that actual first-period day counts, rounding rules, rate changes, and prepayments can produce a different contractual balance.

The main implementation lesson is simple: retain a full schedule when a feature needs the rows; use the formula when it only needs one state. Both should agree under the same assumptions.

Annuity vs Equal Principal: Building Both Amortization Schedules in TypeScript

DaikuanTool — Wed, 30 Sep 2026 16:13:32 +0000

Two loans can have the same principal, rate, and term while producing very different monthly bills.

The difference is often the amortization method:

Annuity (also called a fixed-payment or level-payment schedule) keeps the total scheduled payment constant when the rate is fixed.
Equal principal pays the same amount of principal every month, so the total payment starts higher and falls over time.

Neither method is a mysterious financial product. Both follow the same monthly loop: calculate interest from the opening balance, decide how much principal is paid, reduce the balance, and record the row. The implementation choice is about the rule that determines the principal portion.

In this post, we will build both schedules in TypeScript, compare their output, and add tests that protect the edge cases most likely to break an amortization table.

The examples assume a fixed annual rate, monthly payments, no fees, no prepayments, and a first payment one month after disbursement. They are a software model, not a quote or lending advice.

Start with a schedule, not a single payment

It is tempting to write a function that returns only a monthly payment. That is enough for a simple calculator card, but it is not enough for a useful loan feature.

An amortization schedule lets a user—or another part of the application—inspect:

the opening balance used to calculate each month's interest;
the split between interest and principal;
the payment for each period;
the remaining balance after the payment; and
totals that can be checked against a contract or another implementation.

Let's model one row and the inputs first:

type RepaymentMethod = "annuity" | "equal-principal";

type LoanInput = {
  principal: number;
  annualRate: number; // 0.035 means 3.5%
  months: number;
  method: RepaymentMethod;
};

type ScheduleRow = {
  period: number;
  payment: number;
  principalPaid: number;
  interest: number;
  balance: number;
};

type LoanSchedule = {
  rows: ScheduleRow[];
  totalInterest: number;
  totalPaid: number;
};

The important convention is that balance is the balance after the row's principal payment. Interest for the row is calculated from the opening balance, which is the previous row's closing balance.

The two formulas

Let P be principal, r be the monthly rate, and n be the number of monthly payments.

For an annuity schedule, the fixed payment is:

payment = P × r × (1 + r)^n / ((1 + r)^n - 1)

Each month:

interest      = openingBalance × r
principalPaid = fixedPayment - interest

The payment stays fixed, but the mix changes. Early payments contain more interest because the opening balance is larger. Later payments contain more principal.

For an equal-principal schedule, the principal portion is fixed instead:

principalPaid = P / n
interest      = openingBalance × r
payment       = principalPaid + interest

As the balance falls by the same principal amount every month, interest also falls every month. The first payment is therefore the highest.

Implement both schedules in one loop

The following function keeps the shared accounting in one place and changes only the repayment rule. It preserves precision while calculating and rounds only values stored in the display schedule.

const money = (value: number): number =>
  Math.round((value + Number.EPSILON) * 100) / 100;

function fixedAnnuityPayment(
  principal: number,
  monthlyRate: number,
  months: number,
): number {
  if (monthlyRate === 0) return principal / months;

  const factor = Math.pow(1 + monthlyRate, months);
  return (principal * monthlyRate * factor) / (factor - 1);
}

export function buildSchedule(input: LoanInput): LoanSchedule {
  const principal = Math.max(0, input.principal);
  const months = Math.max(1, Math.round(input.months));
  const monthlyRate = Math.max(0, input.annualRate) / 12;

  const fixedPayment =
    input.method === "annuity"
      ? fixedAnnuityPayment(principal, monthlyRate, months)
      : 0;

  let balance = principal;
  const rows: ScheduleRow[] = [];

  for (let period = 1; period <= months; period += 1) {
    const interest = balance * monthlyRate;
    let principalPaid =
      input.method === "annuity"
        ? fixedPayment - interest
        : principal / months;

    // Absorb floating-point residue in the last scheduled payment.
    if (period === months || principalPaid > balance) {
      principalPaid = balance;
    }

    const payment = principalPaid + interest;
    balance = Math.max(0, balance - principalPaid);

    rows.push({
      period,
      payment: money(payment),
      principalPaid: money(principalPaid),
      interest: money(interest),
      balance: money(balance),
    });
  }

  return {
    rows,
    totalInterest: money(rows.reduce((sum, row) => sum + row.interest, 0)),
    totalPaid: money(rows.reduce((sum, row) => sum + row.payment, 0)),
  };
}

There are two small details worth calling out.

First, monthlyRate === 0 is not an unusual error path—it is the correct formula for a zero-interest installment plan. Dividing by (1 + r)^n - 1 when r is zero yields 0 / 0, so handle that case explicitly.

Second, do not round balance before calculating the next period's interest. Display-level rounding is normal, but feeding rounded values back into the calculation can produce a non-zero final balance or a drift in total interest. The final-period guard absorbs the remaining floating-point residue instead.

Compare the schedules with the same input

Now give both methods identical loan terms: 1,000,000 currency units, a fixed 3.5% annual rate, and 360 monthly payments.

const baseLoan = {
  principal: 1_000_000,
  annualRate: 0.035,
  months: 360,
} as const;

const annuity = buildSchedule({ ...baseLoan, method: "annuity" });
const equalPrincipal = buildSchedule({
  ...baseLoan,
  method: "equal-principal",
});

console.table({
  annuityFirstPayment: annuity.rows[0].payment,
  annuityTotalInterest: annuity.totalInterest,
  equalPrincipalFirstPayment: equalPrincipal.rows[0].payment,
  equalPrincipalLastPayment: equalPrincipal.rows.at(-1)!.payment,
  equalPrincipalTotalInterest: equalPrincipal.totalInterest,
});

The output is approximately:

Metric	Annuity	Equal principal
First payment	4,490.45	5,694.44
Last payment	4,490.45	2,785.88
Total interest	616,560.90	526,458.33

The equal-principal schedule pays about 90,102.57 less interest in this example. It is not a discount: more principal is paid earlier, so there is less balance left to accrue interest in later months.

The balance paths make that visible. After 120 payments, the annuity schedule still has a balance of about 774,268.75. The equal-principal schedule has exactly 666,666.67 left before display rounding. A comparison component that shows only total interest misses this cash-flow difference.

Write tests for invariants and known values

Financial schedule tests should do more than snapshot a table. Test a few known outputs, then assert the properties that must hold for every valid schedule.

The following tests use Node's built-in test runner, but the same ideas work with Vitest or Jest:

import assert from "node:assert/strict";
import test from "node:test";

test("annuity keeps the scheduled payment level", () => {
  const schedule = buildSchedule({
    principal: 1_000_000,
    annualRate: 0.035,
    months: 360,
    method: "annuity",
  });

  assert.equal(schedule.rows[0].payment, 4490.45);
  assert.equal(schedule.rows.at(-1)?.balance, 0);
  assert.ok(schedule.rows.every(row => row.balance >= 0));
});

test("equal principal has a declining payment and a fixed principal portion", () => {
  const schedule = buildSchedule({
    principal: 1_000_000,
    annualRate: 0.035,
    months: 360,
    method: "equal-principal",
  });

  assert.equal(schedule.rows[0].payment, 5694.44);
  assert.equal(schedule.rows.at(-1)?.payment, 2785.88);
  assert.equal(schedule.totalInterest, 526458.33);

  for (const row of schedule.rows.slice(0, -1)) {
    assert.equal(row.principalPaid, 2777.78);
  }
});

test("zero interest divides principal evenly for either method", () => {
  for (const method of ["annuity", "equal-principal"] as const) {
    const schedule = buildSchedule({
      principal: 120_000,
      annualRate: 0,
      months: 12,
      method,
    });

    assert.equal(schedule.rows[0].payment, 10_000);
    assert.equal(schedule.totalInterest, 0);
    assert.equal(schedule.rows.at(-1)?.balance, 0);
  }
});

One caution about the equal-principal test: its stored rows are rounded to cents, so a displayed monthly principal value of 2,777.78 cannot sum exactly to 1,000,000 across 360 rows. That is why the code keeps the unrounded balance during calculation and corrects the final period. If your contract specifies a particular rounding allocation, encode that rule explicitly and test the exact final installment.

Where a production calculator needs more inputs

This implementation is deliberately narrow. A production system may need to model:

fees paid upfront or alongside each payment;
a first period with a non-standard number of days;
rate resets and changing payment dates;
prepayments that shorten the term or lower future payments; and
a balloon payment at maturity.

Each is easier to add when the schedule is a first-class result rather than an afterthought. For example, a monthly fee can become another field in ScheduleRow; a prepayment can reduce balance before interest is calculated for the next period. The core invariant remains the same: opening balance minus principal paid must equal closing balance.

Make the trade-off inspectable

When users compare repayment methods, show the first payment, the final payment, total interest, and at least a few remaining-balance checkpoints. Those values explain the trade-off more honestly than a label such as “cheaper” or “easier.”

To compare the same two fixed-rate monthly schedules interactively, use this repayment method comparison calculator. Enter the principal, rate, and term, then inspect both the early-payment pressure and total-interest difference.

Annuity and equal principal are ultimately two different rules for allocating principal over time. Once the code expresses that rule clearly and tests the balance invariants, the resulting schedules are much easier to extend, audit, and trust.

How to Calculate the Real APR of a Loan with Fees in TypeScript

DaikuanTool — Tue, 15 Sep 2026 01:41:09 +0000

An advertised interest rate is not always the rate implied by a borrower's cash flows.

Consider a 12-month loan for $100,000 at a 10% nominal annual rate. If the lender deducts a $3,000 origination fee before disbursement, the borrower receives $97,000 but still repays a schedule calculated from $100,000. The contractual rate has not changed; the amount of money actually available to the borrower has.

For software that compares loan offers, the useful question is therefore not just “what rate is printed on the quote?” It is:

What annual rate makes the present value of every scheduled outflow equal to the money the borrower actually receives?

That is an internal-rate-of-return problem. This post builds a small TypeScript implementation for regular monthly payments, explains the cash-flow convention, and shows how to test the awkward cases that simple formulas tend to hide.

This is a programming model for comparing disclosed cash flows, not financial, legal, or lending advice. Real products may have irregular dates, optional products, taxes, penalties, or rules that require a different disclosure method.

Why the nominal rate is not enough

The usual annuity-payment formula is useful when you know a principal P, a monthly rate r, and a number of payments n:

payment = P × r × (1 + r)^n / ((1 + r)^n - 1)

It answers, “what payment amortizes this contractual balance?” It does not answer, “what annual return is implied after an upfront fee reduces the disbursement?”

For that second question, define the borrower's cash flows:

Time	Borrower's cash flow
At disbursement	`+actualReceived`
At the end of month 1	`-payment - monthlyFee`
...	...
At the end of the final month	`-payment - monthlyFee - balloon`

The real annualized rate R is the rate that makes net present value (NPV) zero:

0 = actualReceived - Σ(payment[t] / (1 + R)^(t / 12))

The sign convention matters. Amounts received are positive; repayments and borrower-paid fees are negative. Pick one convention and preserve it throughout the model and its tests.

Build the payment schedule first

The IRR calculation should consume a cash-flow schedule. That keeps the pricing logic separate from the solver and makes it easier to extend later for monthly fees or a balloon payment.

export function annuityPayment(
  principal: number,
  nominalAnnualRate: number,
  months: number,
): number {
  if (principal < 0 || months < 1) {
    throw new Error("principal must be non-negative and months must be positive");
  }

  const monthlyRate = nominalAnnualRate / 12;

  if (monthlyRate === 0) {
    return principal / months;
  }

  const factor = Math.pow(1 + monthlyRate, months);
  return (principal * monthlyRate * factor) / (factor - 1);
}

export function regularPayments(
  payment: number,
  months: number,
  monthlyFee = 0,
  balloon = 0,
): number[] {
  if (months < 1) throw new Error("months must be positive");

  return Array.from({ length: months }, (_, index) =>
    payment + monthlyFee + (index === months - 1 ? balloon : 0),
  );
}

Notice that monthlyFee is added to every payment and balloon is added only to the final one. Both are part of the borrower's future outflows, so both belong in the rate calculation. An upfront fee is different: if it is deducted before the borrower receives the funds, it reduces actualReceived.

Do not round the schedule to cents before solving unless the contract itself requires every installment to be rounded that way. Keep full precision internally, then round values only for display. Repeated early rounding can create a small residual balance and move the solved rate.

Solve the annual rate with bisection

For a conventional loan—one initial inflow followed by only outflows—NPV falls as the discount rate rises. That makes bisection a clear, robust solver: find two rates that put NPV on opposite sides of zero, repeatedly halve the interval, and keep the half that contains the root.

export function annualIrr(
  actualReceived: number,
  payments: number[],
): number | null {
  if (actualReceived <= 0 || payments.length === 0 || payments.every(p => p <= 0)) {
    return null;
  }

  const npv = (annualRate: number): number =>
    actualReceived -
    payments.reduce(
      (sum, payment, index) =>
        sum + payment / Math.pow(1 + annualRate, (index + 1) / 12),
      0,
    );

  // Annual rates below -100% are not meaningful in this model.
  let low = -0.9999;
  let high = 1;

  // Expand the upper bound until NPV changes sign, if it can.
  while (npv(high) < 0 && high < 10_000) {
    high *= 2;
  }

  if (npv(low) * npv(high) > 0) {
    return null;
  }

  for (let iteration = 0; iteration < 180; iteration += 1) {
    const mid = (low + high) / 2;

    if (npv(mid) > 0) high = mid;
    else low = mid;
  }

  return (low + high) / 2;
}

This code solves an effective annual rate directly. The exponent (index + 1) / 12 means that a payment one month after disbursement is discounted for one-twelfth of a year. It is not equivalent to calculating a monthly rate and simply multiplying it by 12.

The expanded upper bound is intentional. A fee can make the implied annual rate much larger than the quoted rate, particularly for a short loan. Returning null when a bracket cannot be found is safer than presenting a plausible-looking number for unsupported cash flows.

Work through a loan with an upfront fee

Here is the $100,000, 12-month example. The quoted 10% annual rate determines the scheduled monthly payment; the $3,000 fee changes the amount received.

const contractAmount = 100_000;
const nominalAnnualRate = 0.10;
const months = 12;
const upfrontFee = 3_000;

const payment = annuityPayment(contractAmount, nominalAnnualRate, months);
const payments = regularPayments(payment, months);
const realApr = annualIrr(contractAmount - upfrontFee, payments);

console.log({
  payment: payment.toFixed(2),
  actualReceived: contractAmount - upfrontFee,
  realApr: `${(realApr! * 100).toFixed(2)}%`,
});
// { payment: '8791.59', actualReceived: 97000, realApr: '16.99%' }

The nominal rate is 10%, but the model returns approximately 16.99% annually because the borrower uses $97,000 while repaying the same 12 installments. With no fee, this exact schedule produces an effective annual rate of approximately 10.47%, which is the monthly-compounded equivalent of a 10% nominal annual rate.

That distinction is often missed in dashboards: a nominal annual rate is an input to an amortization formula, while an annualized IRR is an output of the entire cash-flow schedule.

Test the assumptions, not just the happy path

The solver is small enough that tests can be specific. The following examples use Vitest, but the assertions translate directly to Jest or another test runner.

import { describe, expect, it } from "vitest";

describe("annualIrr", () => {
  it("matches the effective annual rate when no fee is deducted", () => {
    const payment = annuityPayment(100_000, 0.10, 12);
    const rate = annualIrr(100_000, regularPayments(payment, 12));

    expect(rate).not.toBeNull();
    expect(rate!).toBeCloseTo(0.1047, 4);
  });

  it("increases when an upfront fee reduces the disbursement", () => {
    const payment = annuityPayment(100_000, 0.10, 12);
    const rate = annualIrr(97_000, regularPayments(payment, 12));

    expect(rate).not.toBeNull();
    expect(rate!).toBeCloseTo(0.1699, 4);
  });

  it("includes a final balloon payment", () => {
    const payments = regularPayments(900, 12, 0, 5_000);
    const rate = annualIrr(10_000, payments);

    expect(rate).not.toBeNull();
    expect(rate!).toBeGreaterThan(0);
  });

  it("rejects a schedule with no borrower payments", () => {
    expect(annualIrr(10_000, [0, 0, 0])).toBeNull();
  });
});

The third test does not hard-code a rate because its purpose is structural: it proves that the final balance enters the solver rather than silently disappearing. In production, add a known-value assertion once the product's payment convention is fixed.

Where this simple model stops

This implementation assumes payments occur exactly one month apart and the first payment is one month after disbursement. Do not use it unchanged when any of the following is true:

payment dates are irregular or have a first-period stub;
the borrower receives additional advances after origination;
fees are refundable, optional, or not directly tied to credit;
cash flows change direction more than once, which can yield multiple IRR roots;
the applicable disclosure rule specifies a particular APR method.

For dated, irregular cash flows, store Date values alongside each amount and use an XIRR-style calculation with actual day fractions. For a conventional monthly schedule, however, the model above is easy to audit: one disbursement, a list of borrower outflows, and a solver with an explicit failure case.

Make the numbers inspectable

When presenting the result in a UI, show the inputs that created it: actual amount received, every installment, recurring fees, and any final balloon. A rate without the supporting cash-flow list is difficult to reproduce and easy to misinterpret.

To enter the same regular monthly cash flows interactively, try this real APR calculator. It accepts the actual disbursement, monthly payment, payment count, optional monthly fees, and an optional final balloon payment.

The durable design lesson is simple: calculate the payment schedule from the contract, calculate the rate from what the borrower truly receives and repays, and keep the two calculations separate.