Private validatePrivate validatePrivate validatePrivate validatePrivate validatePrivate validatePrivate validatePrivate validatePrivate validatePrivate Validate a DynamicGlidepathConfig against GLIDEPATH_VALIDATION constraints. Mode-dispatched; throws a descriptive Error for any invariant violation.
Private getPrivate getPrivate Calculate the total number of periods based on years and periods per year. May be fractional when the years do not end on a period boundary; values within rounding error of a whole number are snapped to it.
Private getPrivate calculatePrivate Compute the time-weighted annual return from a sequence of periodic returns.
Formula: TWR = (product of (1 + r_i))^(periodsPerYear / n) - 1
TWR isolates investment performance from contribution timing and is the standard metric for comparing portfolio performance to a benchmark (e.g., the S&P 500 over the same window).
Private calculatePrivate Compute the money-weighted annual return (internal rate of return).
Finds the single periodic rate i that grows every deposit to the final balance: sum(amount_k * (1 + i)^periodsInvested_k) = finalBalance. Unlike the time-weighted return, this weights each period's return by how much money was invested during it.
The left-hand side increases with i, so the root is found by bisection.
Private getPrivate Count the contributions that fall due during a span of periods.
Contribution k falls due k / contributionFrequency years in, so the number due by the end of period p is floor(p * contributionFrequency / periodsPerYear). Differencing the two ends of the span gives an exact schedule for any pair of whole-number frequencies: yearly contributions on a monthly grid land in every 12th period, and weekly contributions land 4 or 5 to a month, totalling 52 a year.
Periods elapsed at the start of the span
Periods elapsed at the end of the span (may be fractional)
Determine the amount to contribute, at the given contribution frequency, to reach a desired balance. Feeding the result back into getCompoundInterestWithAdditionalContributions reproduces the target.
Calculate compound interest with additional contributions made over a given period of time.
Contributions are credited at the start of the compounding period in which they fall due, so each earns interest for that period.
The initial balance.
The amount of each contribution.
The number of years. If this does not end on a compounding boundary, the remainder runs as a final partial period earning simple interest.
The nominal annual interest rate; each period earns interestRate / compoundingFrequency.
Contributions per year (whole number).
Compounding periods per year (whole number).
An object that contains the results, and a history.
Aggregates detailed compounding period data into yearly data. This method is useful for visualizing the growth of an investment on an annual basis.
The detailed compounding data from the interest calculation.
An array of aggregated yearly data. If the calculation ended part-way through a year, the last row covers that partial year.
Calculate compound interest with age-aware glidepath strategies. Supports fixed returns, allocation-based strategies, and custom waypoints.
Starting account balance
Amount contributed per contribution period
Starting age for calculation
Ending age for calculation
Strategy configuration (fixed, allocation-based, or custom)
Number of contributions per year (default: 12). Contributions are placed in the month in which they fall due.
How many times a year earned interest is credited to the balance (default: 12). The simulation steps monthly and treats returns as effective annual rates, so values above 12 behave exactly like 12. Below 12, interest accrues monthly on the credited balance and is added to it at the end of each compounding period (or at the end of the simulation, if that comes first).
When contributions are added ('start' or 'end' of the month)
Detailed glidepath calculation results with timeline data
Private calculatePrivate Calculate the annual return rate for a given age using the specified glidepath strategy.
Current age for calculation
Glidepath configuration
Starting age for age-based calculations
Ending age for age-based calculations
Annual return rate (decimal format)
Private calculatePrivate calculatePrivate Calculate return for fixed-return glidepath (linear interpolation).
Current age
Fixed return configuration
Starting age for calculation
Ending age for calculation
Annual return rate
Private calculatePrivate Calculate return for stepped-return glidepath (Money Guy style).
Current age
Stepped return configuration
Annual return rate
Private calculatePrivate Calculate return for allocation-based glidepath.
Current age
Allocation-based configuration
Starting age for calculation
Ending age for calculation
Annual return rate
Private interpolatePrivate calculatePrivate Calculate blended return based on equity and bond allocation.
Equity allocation weight (0.0 to 1.0)
Expected annual equity return
Expected annual bond return
Blended annual return rate
Private calculatePrivate Calculate return for custom waypoints glidepath.
Current age
Custom waypoints configuration
Annual return rate
Private getPrivate Get the current equity weight for allocation-based and custom waypoints configurations. Used for timeline data enrichment.
Current age
Glidepath configuration
Starting age for age-based calculations
Ending age for age-based calculations
Equity weight (0.0 to 1.0) or undefined for non-allocation modes
Private getPrivate Number of months in the compounding period that contains a given month.
Credit j lands in month ceil(12 * j / creditsPerYear), so periods are all 12 / creditsPerYear months long when that divides evenly, and a mix of the two nearest whole lengths otherwise (e.g. 2 and 3 months for 5 a year).
Private convertPrivate Convert an effective annual rate to the equivalent rate per period. Formula: periodicRate = (1 + annualRate)^(1/periodsPerYear) - 1
Effective annual rate (decimal)
Number of compounding periods per year
Rate per period (decimal)
Private normalizePrivate Normalize glidepath config by pre-sorting waypoints if applicable. This optimization avoids repeated sorting during monthly simulation loops.
Original glidepath configuration
Configuration with sorted waypoints (if custom-waypoints mode)
Generated using TypeDoc
RetirementCalculator provides various methods to calculate retirement finances, including inflation adjustments, balance after inflation, and compound interest calculations.