module.exports = {
  slug: "percent-change-and-cagr",
  title: "Percent change and CAGR",
  deck_category: "finance",
  description: "Computes the simple percent change between a starting and ending value, and the compound annual growth rate (CAGR) over a stated number of years.",
  inputs: [
    { name: "start_value", type: "number", unit: "currency units", required: true, description: "Starting value", min: 0.0001 },
    { name: "end_value", type: "number", unit: "currency units", required: true, description: "Ending value", min: 0 },
    { name: "years", type: "number", unit: "years", required: true, description: "Number of years between start and end", min: 0.0001 }
  ],
  outputs: [
    { name: "percent_change", unit: "%", description: "Simple percent change from start_value to end_value" },
    { name: "cagr_percent", unit: "%", description: "Compound annual growth rate" }
  ],
  steps: [
    "percent_change = (end_value - start_value) / start_value * 100.",
    "CAGR as a decimal = (end_value / start_value) ^ (1 / years) - 1.",
    "cagr_percent = CAGR decimal * 100.",
    "Round percent_change and cagr_percent to 2 decimals."
  ],
  constants: [],
  sources: [
    { kind: "edition_page", value: "Brealey, Myers, Allen, Principles of Corporate Finance, 13th ed., Chapter 3, discussion of compound growth rates", title: "Principles of Corporate Finance", publisher: "McGraw-Hill", retrieved_utc: "2026-09-30T19:31:29Z", note: "CAGR = (End/Start)^(1/n) - 1; percent change = (End-Start)/Start" }
  ],
  disclaimer: null,
  questionText(inputs) {
    return `What is the percent change and the compound annual growth rate (CAGR) for a value that went from $${inputs.start_value} to $${inputs.end_value} over ${inputs.years} years?`;
  },
  run(inputs) {
    const { start_value, end_value, years } = inputs;
    if (typeof start_value !== "number" || start_value <= 0) throw new Error("start_value must be a positive number");
    if (typeof end_value !== "number" || end_value < 0) throw new Error("end_value must be a non-negative number");
    if (typeof years !== "number" || years <= 0) throw new Error("years must be a positive number");
    const percent_change = Math.round(((end_value - start_value) / start_value) * 100 * 100) / 100;
    const cagr_percent = Math.round((Math.pow(end_value / start_value, 1 / years) - 1) * 100 * 100) / 100;
    return {
      answer: `Percent change ${percent_change.toFixed(2)}%, CAGR ${cagr_percent.toFixed(2)}%`,
      values: { percent_change, cagr_percent }
    };
  },
  examples: [
    {
      name: "worked example",
      inputs: { start_value: 1000, end_value: 2000, years: 5 },
      expected: { answer: "Percent change 100.00%, CAGR 14.87%" },
      check: "hand computation: percent_change = (2000-1000)/1000*100 = 100.00; CAGR = (2)^(1/5)-1 = 0.148698..., 14.8698% rounds to 14.87%"
    },
    {
      name: "test vector: decline",
      inputs: { start_value: 5000, end_value: 4000, years: 2 },
      expected: { answer: "Percent change -20.00%, CAGR -10.56%" },
      check: "hand computation: percent_change = (4000-5000)/5000*100 = -20.00; CAGR = (4000/5000)^(1/2)-1 = 0.8^0.5-1 = 0.894427-1 = -0.105573, -10.5573% rounds to -10.56%"
    }
  ]
};