The Quantitative Economics of Commercial Loans: Reducing Balance vs Flat Rates & Debt Restructuring

/**
 * Commercial Loan & Debt Amortization Engine
 * Implements Reducing Balance EMI, Flat Rate Conversions, and Prepayment Analysis.
 */
export interface LoanScheduleInput {
  principalAmount: number;   // Total loan amount ($)
  annualInterestRate: number; // Annual nominal rate (e.g. 0.075 for 7.5%)
  tenureYears: number;       // Duration in years
  extraMonthlyPayment?: number; // Optional accelerated prepayment ($)
}

export interface AmortizationMonth {
  month: number;
  payment: number;
  principalPortion: number;
  interestPortion: number;
  remainingBalance: number;
  cumulativeInterest: number;
}

export interface LoanAnalysisOutput {
  monthlyEMI: number;
  totalRepayment: number;
  totalInterestPaid: number;
  effectiveAPR: number;
  totalMonths: number;
  interestToPrincipalRatio: number;
  schedule: AmortizationMonth[];
}

export class LoanCalculatorEngine {
  public static calculateReducingBalance(input: LoanScheduleInput): LoanAnalysisOutput {
    const P = input.principalAmount;
    const r = input.annualInterestRate / 12; // Monthly periodic rate
    const n = input.tenureYears * 12;        // Total scheduled months
    const extra = input.extraMonthlyPayment || 0;

    // Standard Capital Recovery Factor: EMI = [P * r * (1+r)^n] / [(1+r)^n - 1]
    const factor = Math.pow(1 + r, n);
    const standardEMI = Math.round((P * (r * factor) / (factor - 1)) * 100) / 100;

    let balance = P;
    let cumulativeInterest = 0;
    const schedule: AmortizationMonth[] = [];
    let month = 0;

    while (balance > 0.01 && month < n + 120) {
      month++;
      const interestPortion = Math.round((balance * r) * 100) / 100;
      let totalPayment = standardEMI + extra;

      // Final payment adjustment to prevent negative balances
      if (balance + interestPortion < totalPayment) {
        totalPayment = balance + interestPortion;
      }

      const principalPortion = Math.round((totalPayment - interestPortion) * 100) / 100;
      balance = Math.max(0, Math.round((balance - principalPortion) * 100) / 100);
      cumulativeInterest = Math.round((cumulativeInterest + interestPortion) * 100) / 100;

      schedule.push({
        month,
        payment: totalPayment,
        principalPortion,
        interestPortion,
        remainingBalance: balance,
        cumulativeInterest
      });
    }

    const totalRepayment = Math.round((P + cumulativeInterest) * 100) / 100;
    const interestToPrincipalRatio = Math.round((cumulativeInterest / P) * 10000) / 100;

    return {
      monthlyEMI: standardEMI,
      totalRepayment,
      totalInterestPaid: cumulativeInterest,
      effectiveAPR: input.annualInterestRate * 100,
      totalMonths: month,
      interestToPrincipalRatio,
      schedule
    };
  }

  /**
   * Converts a deceptive Flat Interest Rate into its true reducing-balance APR.
   */
  public static flatToEffectiveAPR(flatRate: number, tenureYears: number): number {
    const n = tenureYears * 12;
    // Actuarial rule: APR_eff ≈ flatRate * [2n / (n + 1)]
    return Math.round((flatRate * (2 * n / (n + 1))) * 100) / 100;
  }
}