social-security-calculator 1.0.1 → 1.0.2

package/lib/constants.d.ts

@@ -0,0 +1,16 @@
+export declare const EARLY_RETIREMENT_AGE = 62;
+export declare const WAGE_INDEX_CUTOFF = 2023;
+export declare const MAX_RETIREMENT_AGE = 70;
+export declare const LOOKBACK_YEARS = 35;
+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 PIA_PERCENTAGES: {
+    readonly FIRST_BRACKET: 0.9;
+    readonly SECOND_BRACKET: 0.32;
+    readonly THIRD_BRACKET: 0.15;
+};
+export declare const EARLY_RETIREMENT_REDUCTION_RATES: {
+    readonly FIRST_36_MONTHS: number;
+    readonly ADDITIONAL_MONTHS: number;
+};

package/lib/constants.js

@@ -0,0 +1,17 @@
+// Constants
+export const EARLY_RETIREMENT_AGE = 62;
+export const WAGE_INDEX_CUTOFF = 2023;
+export const MAX_RETIREMENT_AGE = 70;
+export const LOOKBACK_YEARS = 35;
+export const BEND_POINT_DIVISOR = 9779.44;
+export const FIRST_BEND_POINT_MULTIPLIER = 180;
+export const SECOND_BEND_POINT_MULTIPLIER = 1085;
+export const PIA_PERCENTAGES = {
+    FIRST_BRACKET: 0.9,
+    SECOND_BRACKET: 0.32,
+    THIRD_BRACKET: 0.15
+};
+export const EARLY_RETIREMENT_REDUCTION_RATES = {
+    FIRST_36_MONTHS: 5 / 9 * 0.01,
+    ADDITIONAL_MONTHS: 5 / 12 * 0.01 // 5/12 of 1%
+};

package/lib/estimatedEarnings/index.d.ts

@@ -1,2 +1,2 @@
-import { Wages } from '../model';
-export declare function getEstimatedEarnings(birthDate: Date, lastWage: number, lastYearWorked?: number, earningGrowthRate?: number): Wages;
+import { Earnings } from '../model';
+export declare function getEstimatedEarnings(birthDate: Date, lastWage: number, lastYearWorked?: number, earningGrowthRate?: number): Earnings;

package/lib/estimatedEarnings/index.js

@@ -1,11 +1,12 @@
-import { wageIndex, wageIndexFuture, taxableMaximum, } from '../wage-index';
+import { wageIndex } from '../wage-index';
+import { getEnglishCommonLawDate } from '../index';
 const YOUTH_FACTOR = 8;
 const YOUTH_FACTOR_AGE = 21;
 const WORK_START_AGE = 18;
 const CURRENT_YEAR = new Date().getFullYear();
 export function getEstimatedEarnings(birthDate, lastWage, lastYearWorked = CURRENT_YEAR, earningGrowthRate = 0) {
     var _a;
-    const birthDateMinusOneDay = new Date(birthDate.getFullYear(), birthDate.getMonth(), birthDate.getDate() - 1);
+    const birthDateMinusOneDay = getEnglishCommonLawDate(birthDate);
     const age = CURRENT_YEAR - birthDateMinusOneDay.getFullYear();
     if (age <= 22) {
         // return zero
@@ -30,7 +31,7 @@ export function getEstimatedEarnings(birthDate, lastWage, lastYearWorked = CURRE
     }
     // Cap wages at taxable maximum
     wageResults.forEach(({ year, earnings }) => {
-        const maxTaxable = taxableMaximum.find((entry) => entry.year === year).earnings;
+        const maxTaxable = wageIndex.find((entry) => entry.year === year).taxMax;
         const currentEarnings = wageResults.find((entry) => entry.year === year).earnings;
         const maxEarnings = Math.min(currentEarnings, maxTaxable);
         wageResults.find((entry) => entry.year === year).earnings = maxEarnings;
@@ -38,7 +39,7 @@ export function getEstimatedEarnings(birthDate, lastWage, lastYearWorked = CURRE
     return wageResults;
 }
 function getReductionFactor(year) {
-    const allIndexes = wageIndex.concat(wageIndexFuture);
+    const allIndexes = wageIndex;
     const lastYear = year - 1;
     const nextYear = year + 1;
     if (year === CURRENT_YEAR && !allIndexes.find((entry) => entry.year === lastYear)) {
@@ -48,6 +49,6 @@ function getReductionFactor(year) {
         return 1;
     }
     else {
-        return ((allIndexes.find((entry) => entry.year === year).earnings) / (allIndexes.find((entry) => entry.year === nextYear).earnings));
+        return ((allIndexes.find((entry) => entry.year === year).awi) / (allIndexes.find((entry) => entry.year === nextYear).awi));
     }
 }

package/lib/index.d.ts

@@ -1,12 +1,7 @@
-import { Wages } from './model';
-export declare function calc(birthday: Date, retirementDate: Date, earnings: Wages): {
-    AIME: number;
-    NormalMonthlyBenefit: number;
-};
-export declare function calcRetirementBenefit(birthday: Date, retirementDate: Date, AIME: number): {
-    AIME: number;
-    NormalMonthlyBenefit: number;
-};
+import { BenefitCalculationResult, Earnings } from './model';
+export declare function calc(birthday: Date, retirementDate: Date, earnings: Earnings): BenefitCalculationResult;
+export declare function calcRetirementBenefit(birthday: Date, lastYearEarnings: number, retirementDate: Date, AIME: number): BenefitCalculationResult;
 export declare function calculatePIA(AIME: number, baseYear?: number): number;
-export declare function calculateAIME(earnings: Wages, baseYear?: number): number;
+export declare function calculateAIME(earnings: Earnings, baseYear?: number): number;
+export declare function getEnglishCommonLawDate(date: Date): Date;
 export declare function getFullRetirementMonths(commonLawBirthDate: Date): number;

package/lib/index.js

@@ -1,173 +1,205 @@
 import { wageIndex } from './wage-index';
-const EARLY_RETIREMENT_AGE = 62;
+import { EARLY_RETIREMENT_AGE, WAGE_INDEX_CUTOFF, MAX_RETIREMENT_AGE, LOOKBACK_YEARS, BEND_POINT_DIVISOR, FIRST_BEND_POINT_MULTIPLIER, SECOND_BEND_POINT_MULTIPLIER, PIA_PERCENTAGES, EARLY_RETIREMENT_REDUCTION_RATES } from './constants';
+// Main calculation function
 export function calc(birthday, retirementDate, earnings) {
-    const AIME = calculateAIME(earnings);
-    const results = calcRetirementBenefit(birthday, retirementDate, AIME);
+    // Validation
+    if (!birthday || !retirementDate) {
+        throw new Error('Birthday and retirement date are required');
+    }
+    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');
+    }
+    const lastYearEarnings = earnings
+        .filter(wage => wage.earnings > 0)
+        .reduce((max, wage) => Math.max(max, wage.year), 0);
+    const yearAge60 = birthday.getFullYear() + 60;
+    const averageIndexedMonthlyEarnings = calculateAIME(earnings, yearAge60);
+    const results = calcRetirementBenefit(birthday, lastYearEarnings, retirementDate, averageIndexedMonthlyEarnings);
     return results;
 }
-export function calcRetirementBenefit(birthday, retirementDate, AIME) {
-    const eclBirthDate = getEnglishCommonLawDate(birthday);
-    const fraMonths = getFullRetirementMonths(eclBirthDate);
-    const fullRetirementDate = new Date(eclBirthDate.getFullYear(), eclBirthDate.getMonth() + fraMonths, eclBirthDate.getDate());
-    const earliestRetirementDate = new Date(eclBirthDate.getFullYear() + EARLY_RETIREMENT_AGE, eclBirthDate.getMonth(), eclBirthDate.getDate());
-    const age60Year = eclBirthDate.getFullYear() + 60;
-    const PIA = calculatePIA(AIME, age60Year);
-    const earlyRetireMonths = monthsDifference(retirementDate, fullRetirementDate);
-    let adjustedBenefits = PIA;
-    if (retirementDate < earliestRetirementDate) {
+export function calcRetirementBenefit(birthday, lastYearEarnings, retirementDate, AIME) {
+    const dates = calculateRetirementDates(birthday, retirementDate);
+    const age60Year = dates.eclBirthDate.getFullYear() + 60;
+    const primaryInsuranceAmount = calculatePIA(AIME, age60Year);
+    // Calculate COLA adjustments
+    const colaAdjustedPIA = calculateCOLAAdjustments(primaryInsuranceAmount, age60Year + 2);
+    // Calculate early/delayed retirement adjustments
+    const earlyRetireMonths = monthsDifference(dates.adjusted, dates.fullRetirement);
+    let adjustedBenefits = colaAdjustedPIA;
+    if (retirementDate < dates.earliestRetirement) {
         adjustedBenefits = 0;
     }
     else if (earlyRetireMonths < 0) {
-        adjustedBenefits = calculateSocialSecurityReduction(PIA, earlyRetireMonths * -1);
+        adjustedBenefits = calculateEarlyRetirementReduction(colaAdjustedPIA, Math.abs(earlyRetireMonths));
     }
     else if (earlyRetireMonths > 0) {
-        adjustedBenefits = calculateSocialSecurityIncrease(eclBirthDate, PIA, earlyRetireMonths);
+        adjustedBenefits = calculateDelayedRetirementIncrease(dates.eclBirthDate, colaAdjustedPIA, earlyRetireMonths);
     }
     const monthlyBenefit = Math.floor(adjustedBenefits);
-    const results = {
-        "AIME": AIME,
-        "NormalMonthlyBenefit": monthlyBenefit,
+    return {
+        AIME: AIME,
+        NormalMonthlyBenefit: monthlyBenefit,
     };
-    return results;
+}
+function calculateRetirementDates(birthday, retirementDate) {
+    const eclBirthDate = getEnglishCommonLawDate(birthday);
+    const fraMonths = getFullRetirementMonths(eclBirthDate);
+    const earliestRetirement = new Date(eclBirthDate.getFullYear() + EARLY_RETIREMENT_AGE, eclBirthDate.getMonth(), eclBirthDate.getDate());
+    const fullRetirement = new Date(eclBirthDate.getFullYear(), eclBirthDate.getMonth() + fraMonths, eclBirthDate.getDate());
+    const maxRetirement = new Date(eclBirthDate.getFullYear() + MAX_RETIREMENT_AGE, eclBirthDate.getMonth(), eclBirthDate.getDate());
+    const adjusted = retirementDate > maxRetirement ? maxRetirement : retirementDate;
+    return {
+        earliestRetirement,
+        fullRetirement,
+        maxRetirement,
+        adjusted,
+        eclBirthDate
+    };
+}
+function calculateCOLAAdjustments(PIA, startYear) {
+    const currentYear = new Date().getFullYear();
+    const colaRates = wageIndex
+        .filter(wage => wage.year >= startYear && wage.year < currentYear)
+        .map(wage => wage.cola);
+    return colaRates.reduce((adjustedAmount, rate) => {
+        const multiplier = 1 + (rate / 100);
+        return roundToFloorTenCents(adjustedAmount * multiplier);
+    }, PIA);
 }
 export function calculatePIA(AIME, baseYear) {
-    var _a;
-    const mostRecentWageIndex = Math.max(...wageIndex.map(val => val.year));
-    if (baseYear) {
-        baseYear = Math.min(baseYear, mostRecentWageIndex);
-    }
-    const averageWageLastYear = baseYear || mostRecentWageIndex;
-    const wageIndexLastYear = ((_a = wageIndex.find(val => val.year === averageWageLastYear)) === null || _a === void 0 ? void 0 : _a.earnings) || 0;
-    const bendPointDivisor = 9779.44;
-    const firstBendPointMultiplier = 180;
-    const secondBendPointMultiplier = 1085;
-    // https://www.ssa.gov/oact/COLA/piaformula.html
-    // Per examples, bend points are rounded to the nearest dollar
-    const firstBendPoint = Math.round(firstBendPointMultiplier * wageIndexLastYear / bendPointDivisor);
-    const secondBendPoint = Math.round(secondBendPointMultiplier * wageIndexLastYear / bendPointDivisor);
-    // https://www.ssa.gov/OP_Home/handbook/handbook.07/handbook-0738.html
-    // Calculations that are not a multiple of 10 cents are rounded to the next lower multiple of 10 cents. For example, $100.18 is rounded down to $100.10.
-    const PIA = (() => {
-        let monthlyBenefit = 0;
-        if (AIME <= firstBendPoint) {
-            monthlyBenefit = 0.9 * AIME;
-        }
-        else {
-            if (AIME > firstBendPoint && AIME <= secondBendPoint) {
-                monthlyBenefit = (0.9 * firstBendPoint) + (0.32 * (AIME - firstBendPoint));
-            }
-            else {
-                monthlyBenefit = (0.9 * firstBendPoint) + (0.32 * (secondBendPoint - firstBendPoint)) + (0.15 * (AIME - secondBendPoint));
-            }
-        }
-        return roundToFloorTenCents(monthlyBenefit);
-    })();
-    return PIA;
+    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 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);
+    const secondBendPoint = Math.round(SECOND_BEND_POINT_MULTIPLIER * wageIndexLastYear / BEND_POINT_DIVISOR);
+    let monthlyBenefit;
+    if (AIME <= firstBendPoint) {
+        monthlyBenefit = PIA_PERCENTAGES.FIRST_BRACKET * AIME;
+    }
+    else if (AIME <= secondBendPoint) {
+        monthlyBenefit =
+            PIA_PERCENTAGES.FIRST_BRACKET * firstBendPoint +
+                PIA_PERCENTAGES.SECOND_BRACKET * (AIME - firstBendPoint);
+    }
+    else {
+        monthlyBenefit =
+            PIA_PERCENTAGES.FIRST_BRACKET * firstBendPoint +
+                PIA_PERCENTAGES.SECOND_BRACKET * (secondBendPoint - firstBendPoint) +
+                PIA_PERCENTAGES.THIRD_BRACKET * (AIME - secondBendPoint);
+    }
+    return roundToFloorTenCents(monthlyBenefit);
 }
 export function calculateAIME(earnings, baseYear) {
-    var _a;
-    const lookbackYears = 35;
-    const mostRecentWageIndex = Math.max(...wageIndex.map(wag => wag.year));
-    if (baseYear) {
-        baseYear = Math.min(baseYear, mostRecentWageIndex);
-    }
-    const averageWageLastYear = baseYear || mostRecentWageIndex;
-    const wageIndexLastYear = ((_a = wageIndex.find(val => val.year === averageWageLastYear)) === null || _a === void 0 ? void 0 : _a.earnings) || 0;
+    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 wageIndexLastYear = wageIndexEntry.awi;
     const futureYearsFactor = 1;
-    // calculate the wage index factors
-    const wageIndexFactors = wageIndex.reduce((acc, { year, earnings }) => (acc[year] = 1 + (Math.max(0, wageIndexLastYear - earnings)) / earnings, acc), {});
-    // adjust the earnings according to the wage index factor
+    // Calculate wage index factors
+    const wageIndexFactors = wageIndex.reduce((acc, { year, awi }) => {
+        acc[year] = 1 + (Math.max(0, wageIndexLastYear - awi)) / awi;
+        return acc;
+    }, {});
+    // Adjust earnings according to wage index factor
     const adjustedEarnings = earnings.reduce((acc, { year, earnings }) => {
         acc[year] = earnings * (wageIndexFactors[year] || futureYearsFactor);
         return acc;
     }, {});
+    // Get top 35 years of earnings
     const top35YearsEarningsArr = Object.values(adjustedEarnings)
-        .sort((a, b) => b - a) // sort the earnings from highest to lowest amount
-        .slice(0, lookbackYears); // grab the highest 35 earnings years
-    const top35YearsEarnings = top35YearsEarningsArr.reduce((partialSum, a) => partialSum + a, 0); // and finally sum them
-    // https://www.ssa.gov/oact/cola/Benefits.html
-    // "We then round the resulting average amount down to the next lower dollar amount"
-    const AIME = Math.floor(top35YearsEarnings / (12 * lookbackYears));
-    return AIME;
+        .sort((a, b) => b - a)
+        .slice(0, LOOKBACK_YEARS);
+    const totalEarnings = top35YearsEarningsArr.reduce((sum, earnings) => sum + earnings, 0);
+    // Calculate AIME (rounded down to next lower dollar)
+    const averageIndexedMonthlyEarnings = Math.floor(totalEarnings / (12 * LOOKBACK_YEARS));
+    return averageIndexedMonthlyEarnings;
 }
-function calculateSocialSecurityReduction(amount, months) {
-    const first36Rate = 5 / 9 * 0.01; // 5/9 of 1%
-    const additionalRate = 5 / 12 * 0.01; // 5/12 of 1%
-    let reduction = 0;
+function calculateEarlyRetirementReduction(amount, months) {
+    if (months <= 0)
+        return amount;
+    let reduction;
     if (months <= 36) {
-        reduction = months * first36Rate;
+        reduction = months * EARLY_RETIREMENT_REDUCTION_RATES.FIRST_36_MONTHS;
     }
     else {
-        // 36 months times 5/9 of 1 percent plus 24 months times 5/12 of 1 percent.
-        reduction = 36 * first36Rate + (months - 36) * additionalRate;
+        reduction =
+            36 * EARLY_RETIREMENT_REDUCTION_RATES.FIRST_36_MONTHS +
+                (months - 36) * EARLY_RETIREMENT_REDUCTION_RATES.ADDITIONAL_MONTHS;
     }
-    return amount - amount * reduction;
+    return amount * (1 - reduction);
 }
-function calculateSocialSecurityIncrease(birthday, initialAmount, numberOfMonths) {
+function calculateDelayedRetirementIncrease(birthday, initialAmount, numberOfMonths) {
+    if (numberOfMonths <= 0)
+        return initialAmount;
     const birthYear = birthday.getFullYear();
-    let monthlyRate;
-    // Determine the monthly rate based on the year of birth
+    const monthlyRate = getDelayedRetirementRate(birthYear);
+    const totalIncrease = monthlyRate * numberOfMonths;
+    return initialAmount * (1 + totalIncrease);
+}
+function getDelayedRetirementRate(birthYear) {
     if (birthYear < 1933) {
         throw new Error(`Invalid birth year for delayed retirement: ${birthYear}`);
     }
-    else if (birthYear <= 1934) {
-        monthlyRate = 11 / 24 / 100; // 11/24 of 1%
-    }
-    else if (birthYear <= 1936) {
-        monthlyRate = 0.005; // 1/2 of 1%
-    }
-    else if (birthYear <= 1938) {
-        monthlyRate = 13 / 24 / 100; // 13/24 of 1%
-    }
-    else if (birthYear <= 1940) {
-        monthlyRate = 7 / 12 / 100; // 7/12 of 1%
-    }
-    else if (birthYear <= 1942) {
-        monthlyRate = 5 / 8 / 100; // 5/8 of 1%
-    }
-    else {
-        monthlyRate = 2 / 3 / 100; // 2/3 of 1%
-    }
-    // Calculate the new amount
-    let totalAdjustment = 0;
-    for (let i = 0; i < numberOfMonths; i++) {
-        totalAdjustment += monthlyRate;
-    }
-    return initialAmount * (1 + totalAdjustment);
+    // Rates based on SSA rules
+    if (birthYear <= 1934)
+        return 11 / 24 / 100; // 11/24 of 1%
+    if (birthYear <= 1936)
+        return 0.005; // 1/2 of 1%
+    if (birthYear <= 1938)
+        return 13 / 24 / 100; // 13/24 of 1%
+    if (birthYear <= 1940)
+        return 7 / 12 / 100; // 7/12 of 1%
+    if (birthYear <= 1942)
+        return 5 / 8 / 100; // 5/8 of 1%
+    return 2 / 3 / 100; // 2/3 of 1%
 }
 function roundToFloorTenCents(amount) {
-    // Convert the amount to fractional dimes
-    let dimes = amount * 10;
-    // floor to only whole dimes
-    dimes = Math.floor(dimes);
-    // Convert back to dollars and return
-    return (dimes / 10);
+    // Convert to dimes, floor, then convert back to dollars
+    return Math.floor(amount * 10) / 10;
 }
-function getEnglishCommonLawDate(date) {
-    const year = date.getFullYear();
-    const month = date.getMonth();
-    const day = date.getDate();
-    const englishCommonLawDate = new Date(year, month, day - 1);
-    return englishCommonLawDate;
+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;
 }
 export function getFullRetirementMonths(commonLawBirthDate) {
     const year = commonLawBirthDate.getFullYear();
-    switch (true) {
-        case (year >= 1943 && year <= 1954):
-            return 66 * 12;
-        case (year >= 1955 && year <= 1959):
-            const fra = ((year - 1954) * 2) + (66 * 12);
-            return fra;
-        case (year >= 1960):
-            return 67 * 12;
-        default:
-            throw new Error('Invalid birth year');
+    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) {
+        return 67 * 12;
+    }
+    else {
+        throw new Error(`Invalid birth year: ${year}`);
     }
 }
 function monthsDifference(date1, date2) {
-    // Calculate the total number of months for each date
     const months1 = date1.getFullYear() * 12 + date1.getMonth();
     const months2 = date2.getFullYear() * 12 + date2.getMonth();
-    // Return the difference in months
     return months1 - months2;
 }

package/lib/model.d.ts

@@ -1,4 +1,24 @@
-export type Wages = {
+export type Earnings = {
     year: number;
     earnings: number;
 }[];
+export type Wage = {
+    year: number;
+    retirement: number;
+    disability: number;
+    survivors: number;
+    taxMax: number;
+    cola: number;
+    awi: number;
+};
+export type Wages = Wage[];
+export interface BenefitCalculationResult {
+    AIME: number;
+    NormalMonthlyBenefit: number;
+}
+export interface RetirementDates {
+    earliestRetirement: Date;
+    fullRetirement: Date;
+    maxRetirement: Date;
+    adjusted: Date;
+}

package/lib/parseStatement/index.d.ts

@@ -1,3 +1,3 @@
-import { Wages } from '../model';
-declare function getWages(fileName: string): Promise<Wages>;
+import { Earnings } from '../model';
+declare function getWages(fileName: string): Promise<Earnings>;
 export default getWages;

package/lib/wage-index.d.ts

@@ -1,4 +1,3 @@
-import { Wages } from './model';
+import { Wage, Wages } from './model';
 export declare const wageIndex: Wages;
-export declare const wageIndexFuture: Wages;
-export declare const taxableMaximum: Wages;
+export declare const wageIndexFuture: Partial<Wage>[];