social-security-calculator 2.0.0 → 3.0.0

package/lib/constants.d.ts

@@ -8,6 +8,7 @@ export declare const ELAPSED_YEARS_START_AGE = 22;
 export declare const BEND_POINT_DIVISOR = 9779.44;
 export declare const FIRST_BEND_POINT_MULTIPLIER = 180;
 export declare const SECOND_BEND_POINT_MULTIPLIER = 1085;
+export declare const FAM_MAX_BASES: number[];
 export declare const CHILD_SURVIVOR_BENEFIT_PERCENTAGE = 0.75;
 export declare const PIA_PERCENTAGES: {
     readonly FIRST_BRACKET: 0.9;

package/lib/constants.js

@@ -13,6 +13,7 @@ export const ELAPSED_YEARS_START_AGE = 22;
 export const BEND_POINT_DIVISOR = 9779.44; // 1977's AWI - used by dividing against current AWI
 export const FIRST_BEND_POINT_MULTIPLIER = 180;
 export const SECOND_BEND_POINT_MULTIPLIER = 1085;
+export const FAM_MAX_BASES = [230, 332, 433];
 export const CHILD_SURVIVOR_BENEFIT_PERCENTAGE = 0.75; // 75% of PIA for child survivor benefits
 export const PIA_PERCENTAGES = {
     FIRST_BRACKET: 0.9,
@@ -21,6 +22,6 @@ export const PIA_PERCENTAGES = {
 };
 export const EARLY_RETIREMENT_REDUCTION = {
     FIRST_MONTHS: 36,
-    FIRST_MONTHS_RATE: 5 / 9 * 0.01,
+    FIRST_MONTHS_RATE: 5 / 9 * 0.01, // 5/9 of 1%
     ADDITIONAL_MONTHS_RATE: 5 / 12 * 0.01 // 5/12 of 1%
 };

package/lib/index.d.ts

@@ -1,9 +1,15 @@
 import { BenefitCalculationResult, RetirementDates, Earnings } from './model';
 export declare function calc(birthday: Date, retirementDate: Date, earnings: Earnings): BenefitCalculationResult;
-export declare function retirementDateAdjustedPayment(dates: RetirementDates, colaAdjustedPIA: number): number;
+export declare function calcRetirement(birthday: Date, retirementDate: Date, earnings: Earnings): Partial<BenefitCalculationResult>;
 export declare function calculateRetirementDates(birthday: Date, retirementDate: Date): RetirementDates;
+export declare function retirementDateAdjustedPayment(dates: RetirementDates, colaAdjustedPIA: number): number;
 export declare function calculatePIA(AIME: number, baseYear?: number): number;
+export declare function calculateAIME(earnings: Earnings, lookbackYears: number, baseYear?: number): number;
 export declare function getLookbackYears(elapsedYears: number): number;
-export declare function calculateAIME(earnings: Earnings, yearStartCounter: number, effectiveDay: Date, baseYear?: number): number;
-export declare function getEnglishCommonLawDate(date: Date): Date;
+export declare function getLookbackYearsDisability(elapsedYears: number): number;
 export declare function getFullRetirementMonths(commonLawBirthDate: Date): number;
+/** Compute Family-Max bend points for an eligibility year given AWI_{year-2}. */
+export declare function getFamilyMaxBendPoints(baseYear: number): [number, number, number];
+/** Apply the family-maximum formula to a PIA using already-computed bend points. */
+export declare function calculateFamilyMaximum(pia: number, [bp1, bp2, bp3]: [number, number, number]): number;
+export declare function getEnglishCommonLawDate(date: Date): Date;

package/lib/index.js

@@ -1,56 +1,84 @@
 import { wageIndex } from './wage-index';
-import { EARLY_RETIREMENT_AGE, WAGE_INDEX_CUTOFF, MAX_RETIREMENT_AGE, MAX_DROP_OUT_YEARS, DROP_OUT_YEARS_DIVISOR, BEND_POINT_DIVISOR, FIRST_BEND_POINT_MULTIPLIER, SECOND_BEND_POINT_MULTIPLIER, PIA_PERCENTAGES, EARLY_RETIREMENT_REDUCTION, ELAPSED_YEARS_START_AGE, LOOKBACK_YEARS, CHILD_SURVIVOR_BENEFIT_PERCENTAGE, } from './constants';
-// Main calculation function
+import { EARLY_RETIREMENT_AGE, WAGE_INDEX_CUTOFF, MAX_RETIREMENT_AGE, MAX_DROP_OUT_YEARS, DROP_OUT_YEARS_DIVISOR, BEND_POINT_DIVISOR, FIRST_BEND_POINT_MULTIPLIER, SECOND_BEND_POINT_MULTIPLIER, PIA_PERCENTAGES, EARLY_RETIREMENT_REDUCTION, ELAPSED_YEARS_START_AGE, LOOKBACK_YEARS, CHILD_SURVIVOR_BENEFIT_PERCENTAGE, FAM_MAX_BASES } from './constants';
+// Main entry point
 export function calc(birthday, retirementDate, earnings) {
-    // Validation
-    if (!birthday || !retirementDate) {
-        throw new Error('Birthday and retirement date are required');
-    }
+    const retirementCalc = calcRetirement(birthday, retirementDate, earnings);
+    const survivorCalc = calcSurvivor(birthday, retirementDate, earnings);
+    retirementCalc.SurvivorBenefits = survivorCalc;
+    return retirementCalc;
+}
+// Core retirement calculation
+export function calcRetirement(birthday, retirementDate, earnings) {
+    const context = createCalculationContext(birthday, retirementDate, earnings);
+    const regularBenefit = calculateBenefitPipeline(earnings, context.yearAge60, getLookbackYears(context.totalYears));
+    const disabilityBenefit = calculateBenefitPipeline(earnings, context.yearAge60, getLookbackYearsDisability(context.totalYears));
+    const monthlyBenefit = retirementDateAdjustedPayment(context.dates, regularBenefit.colaAdjustedPIA);
+    const disabilityPIAFloored = context.retirementDate > context.dates.fullRetirement ? 0 : Math.floor(disabilityBenefit.colaAdjustedPIA);
+    return {
+        AIME: regularBenefit.aime,
+        PIA: regularBenefit.pia,
+        NormalMonthlyBenefit: monthlyBenefit,
+        DisabilityEarnings: disabilityPIAFloored,
+    };
+}
+// Reusable benefit calculation pipeline
+function calculateBenefitPipeline(earnings, yearAge60, lookbackYears) {
+    const aime = calculateAIME(earnings, lookbackYears, yearAge60);
+    const pia = calculatePIA(aime, yearAge60);
+    const colaAdjustedPIA = calculateCOLAAdjustments(pia, yearAge60 + 2);
+    return { aime, pia, colaAdjustedPIA };
+}
+// Survivor benefits calculation
+function calcSurvivor(birthday, retirementDate, earnings) {
+    const context = createCalculationContext(birthday, retirementDate, earnings);
+    const benefit = calculateBenefitPipeline(earnings, context.yearAge60, getLookbackYears(context.totalYears));
+    const survivorPIA = Math.floor(benefit.colaAdjustedPIA * CHILD_SURVIVOR_BENEFIT_PERCENTAGE);
+    const effectiveYear = Math.min(context.yearAge60, WAGE_INDEX_CUTOFF);
+    const wageIndexEntry = getWageIndexEntry(effectiveYear);
+    const wageIndexLastYear = wageIndexEntry.awi;
+    const familyMax = calculateFamilyMaximum(benefit.pia, getFamilyMaxBendPoints(wageIndexLastYear));
+    const colaAdjustedFamMax = calculateCOLAAdjustments(familyMax, context.yearAge60 + 2);
+    return {
+        survivingChild: survivorPIA,
+        careGivingSpouse: survivorPIA,
+        normalRetirementSpouse: Math.floor(benefit.colaAdjustedPIA),
+        familyMaximum: colaAdjustedFamMax
+    };
+}
+// Create shared calculation context to avoid duplication
+function createCalculationContext(birthday, retirementDate, earnings) {
+    validateInputs(birthday, retirementDate, earnings);
     const dates = calculateRetirementDates(birthday, retirementDate);
-    if (!earnings || earnings.length === 0) {
-        throw new Error('Earnings history cannot be empty');
-    }
-    if (retirementDate < birthday) {
-        throw new Error('Retirement date cannot be before birthday');
-    }
-    /**
-     * An individual's earnings are always indexed to the average wage level two years prior to the year of first eligibility.
-     * Thus, for a person retiring at age 62 in 2025, the person's earnings would be indexed to the average wage index for 2023.
-     */
     const yearAge60 = birthday.getFullYear() + 60;
     const yearStartCounting = birthday.getFullYear() + ELAPSED_YEARS_START_AGE - 1;
-    const averageIndexedMonthlyEarnings = calculateAIME(earnings, yearStartCounting, retirementDate, yearAge60);
-    const age60Year = dates.eclBirthDate.getFullYear() + 60;
-    const primaryInsuranceAmount = calculatePIA(averageIndexedMonthlyEarnings, age60Year);
-    const survivorPIA = primaryInsuranceAmount * CHILD_SURVIVOR_BENEFIT_PERCENTAGE;
-    console.log(`Survivor PIA: ${survivorPIA}`);
-    console.log(`Primary Insurance Amount: ${retirementDateAdjustedPayment(dates, survivorPIA)}`);
-    const colaAdjustedPIA = calculateCOLAAdjustments(primaryInsuranceAmount, age60Year + 2);
-    const disabilityPIA = retirementDate > dates.fullRetirement ? 0 : Math.floor(colaAdjustedPIA);
-    const results = retirementDateAdjustedPayment(dates, colaAdjustedPIA);
+    const dateStartCounting = new Date(birthday);
+    dateStartCounting.setFullYear(yearStartCounting);
+    const monthsDiff = monthsDifference(retirementDate, dateStartCounting) / 12;
+    const totalYears = Math.min(LOOKBACK_YEARS, monthsDiff);
     return {
-        AIME: averageIndexedMonthlyEarnings,
-        PIA: primaryInsuranceAmount,
-        NormalMonthlyBenefit: results,
-        DisabilityEarnings: disabilityPIA,
+        birthday,
+        retirementDate,
+        earnings,
+        dates,
+        yearAge60,
+        yearStartCounting,
+        dateStartCounting,
+        totalYears
     };
 }
-export function retirementDateAdjustedPayment(dates, colaAdjustedPIA) {
-    // Calculate early/delayed retirement adjustments
-    const earlyRetireMonths = monthsDifference(dates.adjusted, dates.fullRetirement);
-    let adjustedBenefits = colaAdjustedPIA;
-    if (dates.retirementDate < dates.earliestRetirement) {
-        adjustedBenefits = 0;
+// Extracted validation logic
+function validateInputs(birthday, retirementDate, earnings) {
+    if (!birthday || !retirementDate) {
+        throw new Error('Birthday and retirement date are required');
     }
-    else if (earlyRetireMonths < 0) {
-        adjustedBenefits = calculateEarlyRetirementReduction(colaAdjustedPIA, Math.abs(earlyRetireMonths));
+    if (!earnings || earnings.length === 0) {
+        throw new Error('Earnings history cannot be empty');
     }
-    else if (earlyRetireMonths > 0) {
-        adjustedBenefits = calculateDelayedRetirementIncrease(dates.eclBirthDate, colaAdjustedPIA, earlyRetireMonths);
+    if (retirementDate < birthday) {
+        throw new Error('Retirement date cannot be before birthday');
     }
-    const monthlyBenefit = Math.floor(adjustedBenefits);
-    return monthlyBenefit;
 }
+// Retirement date calculations
 export function calculateRetirementDates(birthday, retirementDate) {
     const eclBirthDate = getEnglishCommonLawDate(birthday);
     const fraMonths = getFullRetirementMonths(eclBirthDate);
@@ -67,6 +95,22 @@ export function calculateRetirementDates(birthday, retirementDate) {
         retirementDate
     };
 }
+// Benefit amount calculations
+export function retirementDateAdjustedPayment(dates, colaAdjustedPIA) {
+    const earlyRetireMonths = monthsDifference(dates.adjusted, dates.fullRetirement);
+    let adjustedBenefits = colaAdjustedPIA;
+    if (dates.retirementDate < dates.earliestRetirement) {
+        adjustedBenefits = 0;
+    }
+    else if (earlyRetireMonths < 0) {
+        adjustedBenefits = calculateEarlyRetirementReduction(colaAdjustedPIA, Math.abs(earlyRetireMonths));
+    }
+    else if (earlyRetireMonths > 0) {
+        adjustedBenefits = calculateDelayedRetirementIncrease(dates.eclBirthDate, colaAdjustedPIA, earlyRetireMonths);
+    }
+    return Math.floor(adjustedBenefits);
+}
+// COLA adjustments
 function calculateCOLAAdjustments(PIA, startYear) {
     const currentYear = new Date().getFullYear();
     const colaRates = wageIndex
@@ -77,12 +121,10 @@ function calculateCOLAAdjustments(PIA, startYear) {
         return roundToFloorTenCents(adjustedAmount * multiplier);
     }, PIA);
 }
+// PIA calculation
 export function calculatePIA(AIME, baseYear) {
     const effectiveYear = baseYear ? Math.min(baseYear, WAGE_INDEX_CUTOFF) : WAGE_INDEX_CUTOFF;
-    const wageIndexEntry = wageIndex.find(val => val.year === effectiveYear);
-    if (!wageIndexEntry) {
-        throw new Error(`No wage index data found for year ${effectiveYear}`);
-    }
+    const wageIndexEntry = getWageIndexEntry(effectiveYear);
     const wageIndexLastYear = wageIndexEntry.awi;
     // Calculate bend points (rounded to nearest dollar per SSA rules)
     const firstBendPoint = Math.round(FIRST_BEND_POINT_MULTIPLIER * wageIndexLastYear / BEND_POINT_DIVISOR);
@@ -104,23 +146,13 @@ export function calculatePIA(AIME, baseYear) {
     }
     return roundToFloorTenCents(monthlyBenefit);
 }
-export function getLookbackYears(elapsedYears) {
-    const minComputationYears = 2;
-    const dropOutYears = Math.min(Math.floor(elapsedYears / DROP_OUT_YEARS_DIVISOR), MAX_DROP_OUT_YEARS);
-    const adjustedLookbackYears = elapsedYears - dropOutYears;
-    return Math.max(minComputationYears, adjustedLookbackYears);
-}
-export function calculateAIME(earnings, yearStartCounter, effectiveDay, baseYear) {
-    const totalYears = Math.min(LOOKBACK_YEARS, effectiveDay.getFullYear() - yearStartCounter);
-    const lookbackYears = getLookbackYears(totalYears);
+// AIME calculation
+export function calculateAIME(earnings, lookbackYears, baseYear) {
     if (!earnings || earnings.length === 0) {
         return 0;
     }
     const effectiveYear = baseYear ? Math.min(baseYear, WAGE_INDEX_CUTOFF) : WAGE_INDEX_CUTOFF;
-    const wageIndexEntry = wageIndex.find(val => val.year === effectiveYear);
-    if (!wageIndexEntry) {
-        throw new Error(`No wage index data found for year ${effectiveYear}`);
-    }
+    const wageIndexEntry = getWageIndexEntry(effectiveYear);
     const wageIndexLastYear = wageIndexEntry.awi;
     const futureYearsFactor = 1;
     // Calculate wage index factors
@@ -133,15 +165,27 @@ export function calculateAIME(earnings, yearStartCounter, effectiveDay, baseYear
         acc[year] = earnings * (wageIndexFactors[year] || futureYearsFactor);
         return acc;
     }, {});
-    // Get top 35 years of earnings
-    const top35YearsEarningsArr = Object.values(adjustedEarnings)
+    // Get top years of earnings based on lookback period
+    const topYearsEarningsArr = Object.values(adjustedEarnings)
         .sort((a, b) => b - a)
         .slice(0, lookbackYears);
-    const totalEarnings = top35YearsEarningsArr.reduce((sum, earnings) => sum + earnings, 0);
+    const totalEarnings = topYearsEarningsArr.reduce((sum, earnings) => sum + earnings, 0);
     // Calculate AIME (rounded down to next lower dollar)
-    const averageIndexedMonthlyEarnings = Math.floor(totalEarnings / (12 * lookbackYears));
-    return averageIndexedMonthlyEarnings;
+    return Math.floor(totalEarnings / (12 * lookbackYears));
+}
+// Lookback year calculations
+export function getLookbackYears(elapsedYears) {
+    const minComputationYears = 2;
+    const adjustedLookbackYears = Math.floor(elapsedYears) - 5;
+    return Math.max(minComputationYears, adjustedLookbackYears);
+}
+export function getLookbackYearsDisability(elapsedYears) {
+    const minComputationYears = 2;
+    const dropOutYears = Math.min(Math.floor(elapsedYears / DROP_OUT_YEARS_DIVISOR), MAX_DROP_OUT_YEARS);
+    const adjustedLookbackYears = elapsedYears - dropOutYears;
+    return Math.max(minComputationYears, adjustedLookbackYears);
 }
+// Early retirement reduction
 function calculateEarlyRetirementReduction(amount, months) {
     if (months <= 0)
         return amount;
@@ -156,6 +200,7 @@ function calculateEarlyRetirementReduction(amount, months) {
     }
     return amount * (1 - reduction);
 }
+// Delayed retirement increase
 function calculateDelayedRetirementIncrease(birthday, initialAmount, numberOfMonths) {
     if (numberOfMonths <= 0)
         return initialAmount;
@@ -164,11 +209,11 @@ function calculateDelayedRetirementIncrease(birthday, initialAmount, numberOfMon
     const totalIncrease = monthlyRate * numberOfMonths;
     return initialAmount * (1 + totalIncrease);
 }
+// Delayed retirement rate lookup
 function getDelayedRetirementRate(birthYear) {
     if (birthYear < 1933) {
         throw new Error(`Invalid birth year for delayed retirement: ${birthYear}`);
     }
-    // Rates based on SSA rules
     if (birthYear <= 1934)
         return 11 / 24 / 100; // 11/24 of 1%
     if (birthYear <= 1936)
@@ -181,30 +226,19 @@ function getDelayedRetirementRate(birthYear) {
         return 5 / 8 / 100; // 5/8 of 1%
     return 2 / 3 / 100; // 2/3 of 1%
 }
-function roundToFloorTenCents(amount) {
-    // Convert to dimes, floor, then convert back to dollars
-    return Math.floor(amount * 10) / 10;
-}
-export function getEnglishCommonLawDate(date) {
-    // Create a new date to avoid mutating the original
-    const eclDate = new Date(date);
-    eclDate.setDate(eclDate.getDate() - 1);
-    return eclDate;
-}
+// Full retirement age calculation
 export function getFullRetirementMonths(commonLawBirthDate) {
     const year = commonLawBirthDate.getFullYear();
     if (year <= 1937) {
         return 65 * 12;
     }
     else if (year <= 1942) {
-        // Gradual increase from 65 years to 65 years 10 months
         return ((year - 1937) * 2) + (65 * 12);
     }
     else if (year <= 1954) {
         return 66 * 12;
     }
     else if (year <= 1959) {
-        // Gradual increase from 66 years to 66 years 10 months
         return ((year - 1954) * 2) + (66 * 12);
     }
     else if (year >= 1960) {
@@ -214,8 +248,42 @@ export function getFullRetirementMonths(commonLawBirthDate) {
         throw new Error(`Invalid birth year: ${year}`);
     }
 }
+/** Compute Family-Max bend points for an eligibility year given AWI_{year-2}. */
+export function getFamilyMaxBendPoints(baseYear) {
+    const [f1, f2, f3] = FAM_MAX_BASES.map(b => Math.round((b * baseYear / BEND_POINT_DIVISOR)));
+    return [f1, f2, f3];
+}
+/** Apply the family-maximum formula to a PIA using already-computed bend points. */
+export function calculateFamilyMaximum(pia, [bp1, bp2, bp3]) {
+    let max = 0;
+    max += 1.50 * Math.min(pia, bp1);
+    if (pia > bp1)
+        max += 2.72 * (Math.min(pia, bp2) - bp1);
+    if (pia > bp2)
+        max += 1.34 * (Math.min(pia, bp3) - bp2);
+    if (pia > bp3)
+        max += 1.75 * (pia - bp3);
+    // SSA: round total down to next lower $0.10
+    return Math.floor(max * 10) / 10;
+}
+// Utility functions
+export function getEnglishCommonLawDate(date) {
+    const eclDate = new Date(date);
+    eclDate.setDate(eclDate.getDate() - 1);
+    return eclDate;
+}
 function monthsDifference(date1, date2) {
     const months1 = date1.getFullYear() * 12 + date1.getMonth();
     const months2 = date2.getFullYear() * 12 + date2.getMonth();
     return months1 - months2;
 }
+function roundToFloorTenCents(amount) {
+    return Math.floor(amount * 10) / 10;
+}
+function getWageIndexEntry(effectiveYear) {
+    const wageIndexEntry = wageIndex.find(val => val.year === effectiveYear);
+    if (!wageIndexEntry) {
+        throw new Error(`No wage index data found for year ${effectiveYear}`);
+    }
+    return wageIndexEntry;
+}

package/lib/model.d.ts

@@ -13,6 +13,12 @@ export interface BenefitCalculationResult {
     PIA: number;
     NormalMonthlyBenefit: number;
     DisabilityEarnings: number;
+    SurvivorBenefits: {
+        survivingChild: number;
+        careGivingSpouse: number;
+        normalRetirementSpouse: number;
+        familyMaximum: number;
+    };
 }
 export interface RetirementDates {
     earliestRetirement: Date;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-security-calculator",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Calculate estimated Social Security Benefits",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -47,7 +47,7 @@
     "minimist": "^1.2.8",
     "playwright": "^1.54.1",
     "ts-jest": "^29.1.1",
-    "typescript": "^4.8.3"
+    "typescript": "^5.9.2"
   },
   "dependencies": {
     "xml2js": "^0.6.2"