1. The Foundation: Exact Decimal Arithmetic (money.ts)
Standard JavaScript represents all numbers as IEEE 754 double-precision floating-point values. This causes well-known precision anomalies (e.g. 0.1 + 0.2 = 0.30000000000000004). Over a 360-row loan schedule or a 40-year retirement simulation, floating-point drift compounds into visible dollar errors.
// Global Decimal.js Configuration
Decimal.set({ precision: 34, rounding: Decimal.ROUND_HALF_UP });
The Reconciliation Rule: Any primitive generating a multi-period amortization schedule must expose reconcile(). This helper strictly proves that:
The payment and each period's interest are rounded to the cent as a lender posts them, so the balance carried forward is always a real amount of money. The final payment is the remaining balance plus that period's interest, which is why it differs from the others by a few dollars.
2. Time Value of Money (tvm.ts)
The Time Value of Money engine governs loan payments, annuity yields, future savings, and investment compounding. We implement all five closed-form solves with strict sign conventions (cash outflows negative, inflows positive):
Critical TVM Convergence Safeguards:
- Explicit Zero-Rate Branch ($i = 0$): When rate is zero, formulas branch to linear forms ($FV = -(PV + PMT \cdot n)$), preventing division by zero exceptions.
- Newton-Raphson with Bisection Fallback for RATE: Rate has no closed form. We solve numerically using analytical first-derivative Newton-Raphson with an automatic fallback to bisection on $[-0.9999, 10.0]$ with a strict residual tolerance of $1 \times 10^-10$.
- Annuity Due Support (type = 1): Supports both ordinary annuities (payments at end of period) and annuities due (payments at start of period).
3. Day Count Conventions (daycount.ts)
Underpinning bond pricing, commercial debt, and treasury yields:
Forces months to 30 days; incorporates February end-of-month leap year adjustments. Default for consumer mortgages.
Calculates exact calendar days, explicitly splitting fractions across leap-year boundaries (366 vs 365 days). Standard for US Treasuries.
Actual days elapsed divided by 365. Used in GBP money market instruments and consumer revolving credit.
Actual days divided by 360. Standard in US commercial lending and money market paper.
4. Primary Source Hierarchy & Golden Vector Protocol
To ensure zero copyright reproduction while maintaining 100% legal and statutory accuracy, our test vectors are sourced directly from authoritative institutional standards:
CFPB Truth in Lending (12 CFR Part 1026, Regulation Z), Homeowners Protection Act of 1998 (12 U.S.C. § 4901), Internal Revenue Code & Treasury Regulations.
IRS Publications (Pub 936, Pub 946 MACRS), Social Security Actuarial Period Life Tables, CMS Medicare IRMAA Determinations.
HP-12C Financial Calculator hardware parity, CFA Institute standards, and Excel standard financial function specifications.
Calculators outside the US are sourced against the equivalent primary authority for that jurisdiction: HMRC and gov.uk (UK), the Central Board of Direct Taxes and EPFO (India), the Canada Revenue Agency (Canada), the Australian Taxation Office (Australia), the Eidgenössische Steuerverwaltung / ESTV (Switzerland), Skatteverket (Sweden), Skatteetaten (Norway), and each country's equivalent national tax or social-security authority. Every internationally-scoped calculator states its currency and jurisdiction explicitly, and cites the specific authority its figures were verified against in its own Sources section.
5. Jurisdiction Table Freshness & Versioning
All tax brackets, FICA wage bases, and statutory phase-outs are stored in versioned JSON tables under /engine/tables/{year}/. Every table requires:
effectiveDate: Statutory date of enactmentsource: Specific government agency publication namesourceUrl: Resolvable HTTPS link to government bulletinverifiedOn: Timestamp of manual quantitative audit
If a calculator queries an un-tabled tax year, the engine throws a typed error rather than silently defaulting to obsolete historical tax brackets.