calculator.js — Calculation, Storage, and Export Functions

js/lib/calculator.js is the core shared library. It exports the compound interest calculation function, a currency formatter, localStorage helpers for the current calculation and saved plans, and the CSV download utility. Every page that needs calculation or storage imports from this module.

Import

import {
  calculateCompoundInterest,
  money,
  saveCurrentCalculation,
  getCurrentCalculation,
  getSavedPlans,
  setSavedPlans,
  downloadCsv
} from '../lib/calculator.js';

`calculateCompoundInterest(inputs)`

Runs a monthly compound interest projection for two parallel scenarios — one that includes monthly deposits and one that does not. The simulation steps through each month of every year, compounding at the given annual rate, and records a snapshot at the end of each year. Returns an array of year rows from year 0 to year N.

inputs

object

required

An object containing the four projection parameters.

startingBalance

string | number

The initial balance at year 0. Coerced to a number and clamped to ≥ 0.

monthlyDeposit

string | number

The fixed amount added each month. Coerced to a number and clamped to ≥ 0.

annualRate

string | number

The annual interest rate expressed as a percentage (e.g. "5" for 5%). Coerced to a number and clamped to ≥ 0.

years

string | number

The projection length in years. Coerced to a number, rounded to the nearest integer, and clamped to the range 0–80.

Returns: An array of row objects, one per year from year 0 to year N inclusive.

year

number

The year index. 0 is the starting snapshot; subsequent values are 1, 2, … N.

withDeposits

number

The rounded projected balance when monthly deposits are included.

withoutDeposits

number

The rounded projected balance when no monthly deposits are made (interest-only growth).

totalDeposits

number

The rounded cumulative total of the starting balance plus all monthly deposits made up to this year.

interestEarned

number

The rounded difference between withDeposits and totalDeposits — i.e. the interest earned so far. Always 0 in the year-0 row.

import { calculateCompoundInterest } from '../lib/calculator.js';

const rows = calculateCompoundInterest({
  startingBalance: 5000,
  monthlyDeposit: 200,
  annualRate: 7,
  years: 20
});

const lastRow = rows[rows.length - 1];
console.log(lastRow);
// {
//   year: 20,
//   withDeposits: 103389,
//   withoutDeposits: 19348,
//   totalDeposits: 53000,
//   interestEarned: 50389
// }

years is capped at 80 regardless of the value passed in. Values above 80 are silently clamped.

`money(value)`

Formats a numeric value as a US dollar string with locale-separated thousands. Useful anywhere a human-readable currency display is needed.

value

number | string

required

The amount to format. Coerced to a number via Number(value). Non-numeric values (including null and undefined) default to 0.

Returns: string — the value rounded to the nearest integer and formatted as '$' + Math.round(Number(value)||0).toLocaleString().

import { money } from '../lib/calculator.js';

money(5000);      // "$5,000"
money(1234567);   // "$1,234,567"
money(99.75);     // "$100"
money(null);      // "$0"
money('abc');     // "$0"

`saveCurrentCalculation(inputs, results)`

Serializes inputs and results to localStorage under the key airgead_current_calc, alongside a UTC timestamp in ISO 8601 format. This is how the Calculator page passes data to the Results page.

inputs

object

required

The raw form inputs object (the same shape passed to calculateCompoundInterest).

results

array

required

The rows array returned by calculateCompoundInterest.

Returns: void

Calling this function overwrites any previously stored current calculation. Only the most recent calculation is retained.

import { calculateCompoundInterest, saveCurrentCalculation } from '../lib/calculator.js';

const inputs  = { startingBalance: 1000, monthlyDeposit: 100, annualRate: 6, years: 10 };
const results = calculateCompoundInterest(inputs);

saveCurrentCalculation(inputs, results);

`getCurrentCalculation()`

Reads and parses airgead_current_calc from localStorage. Returns null if no calculation has been stored yet, or if the stored value cannot be parsed as JSON. Returns: { inputs, results, updatedAt } | null

inputs

object

The raw form inputs that were passed to saveCurrentCalculation.

results

array

The year rows that were passed to saveCurrentCalculation.

updatedAt

string

An ISO 8601 UTC timestamp recording when the calculation was saved.

import { getCurrentCalculation } from '../lib/calculator.js';

const saved = getCurrentCalculation();

if (saved === null) {
  // No calculation stored — redirect back to the calculator
  window.location.href = 'calculator.html';
} else {
  console.log('Saved at:', saved.updatedAt);
  console.log('Results:', saved.results);
}

The Results page redirects to the Calculator page if this function returns null.

`getSavedPlans()`

Reads and parses airgead_saved_plans from localStorage. Returns an empty array if the key is missing or if parsing fails — it never throws. Returns: array — the array of saved plan objects, or [] if none exist.

import { getSavedPlans } from '../lib/calculator.js';

const plans = getSavedPlans();
console.log(`${plans.length} saved plan(s) found`);

`setSavedPlans(plans)`

Serializes a plans array and writes it to airgead_saved_plans in localStorage. This is the single write path for the saved plans list — used both when appending a new plan (from the Results page) and when removing a plan (from the Saved Plans page).

plans

array

required

The full, updated array of plan objects to persist. Pass the complete array, not a diff.

Returns: void

import { getSavedPlans, setSavedPlans } from '../lib/calculator.js';

// Append a new plan
const plans = getSavedPlans();
plans.push({ label: '20-year plan', inputs, results, savedAt: new Date().toISOString() });
setSavedPlans(plans);

// Remove the plan at index 2
const updated = plans.filter((_, i) => i !== 2);
setSavedPlans(updated);

`downloadCsv(filename, rows)`

Creates a CSV file entirely in the browser using the Blob API and triggers an immediate download without any server interaction. Values are quoted, and any double-quote characters within a value are escaped by doubling them.

filename

string

required

The suggested filename for the downloaded file, including the .csv extension (e.g. "airgead-20-year-plan.csv").

rows

array of arrays

required

A two-dimensional array where each inner array represents one row in the CSV. Every value is converted to a string, wrapped in double-quotes, and escaped before writing.

Returns: void

import { calculateCompoundInterest, downloadCsv } from '../lib/calculator.js';

const rows = calculateCompoundInterest({ startingBalance: 5000, monthlyDeposit: 200, annualRate: 7, years: 20 });

// Build CSV rows: header + one row per year
const csvRows = [
  ['Year', 'With Deposits', 'Without Deposits', 'Total Deposits', 'Interest Earned'],
  ...rows.map(r => [r.year, r.withDeposits, r.withoutDeposits, r.totalDeposits, r.interestEarned])
];

downloadCsv('airgead-20-year-plan.csv', csvRows);

downloadCsv uses URL.createObjectURL and programmatic anchor click — both require a browser environment. It will not work in Node.js or other non-browser runtimes.

JavaScript API

C++ Source

calculator.js — Calculation, Storage, and Export Functions

Import

`calculateCompoundInterest(inputs)`

`money(value)`

`saveCurrentCalculation(inputs, results)`

`getCurrentCalculation()`

`getSavedPlans()`

`setSavedPlans(plans)`

`downloadCsv(filename, rows)`

Build docs developers (and LLMs) love

JavaScript API

C++ Source

Documentation Index

​Import

​calculateCompoundInterest(inputs)

​money(value)

​saveCurrentCalculation(inputs, results)

​getCurrentCalculation()

​getSavedPlans()

​setSavedPlans(plans)

​downloadCsv(filename, rows)

Build docs developers (and LLMs) love

Import

`calculateCompoundInterest(inputs)`

`money(value)`

`saveCurrentCalculation(inputs, results)`

`getCurrentCalculation()`

`getSavedPlans()`

`setSavedPlans(plans)`

`downloadCsv(filename, rows)`