DEV Community: DaikuanTool

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.