FIRE & Coast FIRE

// src/lib/finance/fire.ts
//
// FIRE (Financial Independence, Retire Early) calculations.
//   FIRE Number = annual spending / safe withdrawal rate
//   Coast FIRE   = FIRE Number / (1 + return)^years_to_retirement
//
// Once you hit Coast FIRE you can stop contributing and your portfolio still
// grows to the FIRE number by retirement.

/** Lump-sum portfolio size that supports `annualSpending` at `swr`. */
export function fireNumber(annualSpending: number, swr: number): number {
  if (swr <= 0) throw new Error(`fireNumber: swr must be > 0, got ${swr}`);
  return annualSpending / swr;
}

/**
 * Coast FIRE number: how much you'd need invested today, with no further
 * contributions, to grow to {@link target} in {@link yearsToRetirement} years
 * at the given return rate.
 */
export function coastFireNumber(target: number, returnRate: number, yearsToRetirement: number): number {
  if (yearsToRetirement <= 0) return target;
  return target / Math.pow(1 + returnRate, yearsToRetirement);
}

/**
 * Iterate year by year and find the first year where balance ≥ target.
 * Returns Infinity if the target isn't reached within maxYears (default 100).
 */
export function yearsToReach(
  startBalance: number,
  annualContribution: number,
  returnRate: number,
  target: number,
  maxYears = 100
): number {
  let bal = startBalance;
  for (let y = 1; y <= maxYears; y++) {
    bal = bal * (1 + returnRate) + annualContribution;
    if (bal >= target) return y;
    if (!Number.isFinite(bal)) return Infinity;
  }
  return Infinity;
}