social-security-calculator 1.0.2 → 1.0.3

package/README.md

@@ -1,14 +1,139 @@
-# SocialSecurityCalculator
-TypeScript to calculate estimated Social Security Benefits
+# Social Security Benefits Calculator
 
+A TypeScript library for calculating Social Security retirement benefits based on official SSA formulas. This calculator handles Average Indexed Monthly Earnings (AIME), Primary Insurance Amount (PIA), and adjustments for early or delayed retirement.
 
- This module will calculate your expected retirement benefits
- from Social Security given your annual earnings
+## Credits
 
- Input:
+This project is forked from [Ryan Antkowiak's SocialSecurityCalculator](https://github.com/antkowiak/SocialSecurityCalculator) python implementation. The original implementation has been refactored with COLA adjustments to bring it into alignment with SSA's Quick Calculator.
 
- Dictionary mapping a year to the amount of Social
- Security eligible earnings in that particular year
+## Features
 
+- Calculate Average Indexed Monthly Earnings (AIME) based on earnings history
+- Determine Primary Insurance Amount (PIA) using current bend points
+- Apply Cost of Living Adjustments (COLA)
+- Handle early retirement reductions
+- Calculate delayed retirement credits
+- Full TypeScript support with comprehensive type definitions
 
-Adapted from python originally written by Ryan Antkowiak
+## Installation
+
+```bash
+npm install social-security-calculator
+```
+
+## Usage
+
+### Quick Start
+
+```typescript
+import { calc } from 'social-security-calculator';
+
+const result = calc(
+  new Date(1960, 0, 15),     // Birthday: January 15, 1960
+  new Date(2027, 0, 15),     // Retirement: January 15, 2027
+  [
+    { year: 1982, earnings: 12000 },
+    { year: 1983, earnings: 15000 },
+    // ... add more years of earnings
+    { year: 2025, earnings: 87000 }
+  ]
+);
+
+console.log(`Monthly benefit: ${result.NormalMonthlyBenefit}`);
+```
+
+### Early Retirement Example
+
+```typescript
+const birthDate = new Date(1965, 5, 1); // June 1, 1965
+const earlyRetirement = new Date(2027, 5, 1); // June 1, 2027 (at age 62)
+
+const result = calc(birthDate, earlyRetirement, earnings);
+// Benefits will be reduced for early retirement
+```
+
+### Delayed Retirement Example
+
+```typescript
+const birthDate = new Date(1955, 2, 15); // March 15, 1955
+const delayedRetirement = new Date(2025, 2, 15); // March 15, 2025 (at age 70)
+
+const result = calc(birthDate, delayedRetirement, earnings);
+// Benefits will include delayed retirement credits
+```
+
+## API Reference
+
+### Main Functions
+
+#### `calc(birthday: Date, retirementDate: Date, earnings: Earnings): BenefitCalculationResult`
+
+Calculates Social Security retirement benefits.
+
+**Parameters:**
+- `birthday`: Date of birth
+- `retirementDate`: Planned retirement date
+- `earnings`: Array of yearly earnings records
+
+**Returns:**
+- `BenefitCalculationResult` object containing:
+  - `AIME`: Average Indexed Monthly Earnings
+  - `NormalMonthlyBenefit`: Monthly benefit amount (in dollars)
+
+#### `calculatePIA(AIME: number, baseYear?: number): number`
+
+Calculates the Primary Insurance Amount based on AIME.
+
+**Parameters:**
+- `AIME`: Average Indexed Monthly Earnings
+- `baseYear`: Optional base year for calculations (defaults to 2023)
+
+#### `calculateAIME(earnings: Earnings, baseYear?: number): number`
+
+Calculates Average Indexed Monthly Earnings from earnings history.
+
+**Parameters:**
+- `earnings`: Array of yearly earnings
+- `baseYear`: Optional base year for wage indexing
+
+### Type Definitions
+
+```typescript
+interface Wage {
+  year: number;
+  earnings: number;
+}
+
+type Earnings = Wage[];
+
+interface BenefitCalculationResult {
+  AIME: number;
+  NormalMonthlyBenefit: number;
+}
+```
+
+## How It Works
+
+1. **AIME Calculation**: The calculator indexes historical earnings to account for wage inflation, selects the highest 35 years of indexed earnings, and computes the monthly average.
+
+2. **PIA Calculation**: Applies SSA bend points to determine the Primary Insurance Amount from the AIME.
+
+3. **Retirement Age Adjustments**:
+   - Early retirement (age 62-66): Benefits are reduced by 5/9 of 1% for each of the first 36 months and 5/12 of 1% for additional months
+   - Delayed retirement (age 67-70): Benefits increase by 2/3 of 1% per month (8% per year) for those born after 1943
+
+4. **COLA Adjustments**: Annual Cost of Living Adjustments are applied starting at age 62.
+
+## Important Notes
+
+- The calculator uses the most recent wage indexes as published by the SSA as of 2025
+- It is designed and tested to exactly align with the [SSA Quick Calculator](https://www.ssa.gov/OACT/quickcalc/index.html)
+- It always uses current dollar value, and does not predict future inflation amounts
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## License
+
+This project maintains the same license as the original repository. Please refer to the LICENSE file for details.

package/lib/constants.d.ts

@@ -10,7 +10,8 @@ export declare const PIA_PERCENTAGES: {
     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;
+export declare const EARLY_RETIREMENT_REDUCTION: {
+    readonly FIRST_MONTHS: 36;
+    readonly FIRST_MONTHS_RATE: number;
+    readonly ADDITIONAL_MONTHS_RATE: number;
 };

package/lib/constants.js

@@ -11,7 +11,8 @@ export const PIA_PERCENTAGES = {
     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%
+export const EARLY_RETIREMENT_REDUCTION = {
+    FIRST_MONTHS: 36,
+    FIRST_MONTHS_RATE: 5 / 9 * 0.01,
+    ADDITIONAL_MONTHS_RATE: 5 / 12 * 0.01 // 5/12 of 1%
 };

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 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 calcRetirementBenefit(birthday: Date, retirementDate: Date, AIME: number): BenefitCalculationResult;
 export declare function calculatePIA(AIME: number, baseYear?: number): number;
 export declare function calculateAIME(earnings: Earnings, baseYear?: number): number;
 export declare function getEnglishCommonLawDate(date: Date): Date;

package/lib/index.js

@@ -1,5 +1,5 @@
 import { wageIndex } from './wage-index';
-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';
+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 } from './constants';
 // Main calculation function
 export function calc(birthday, retirementDate, earnings) {
     // Validation
@@ -12,15 +12,12 @@ export function calc(birthday, retirementDate, earnings) {
     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);
+    const results = calcRetirementBenefit(birthday, retirementDate, averageIndexedMonthlyEarnings);
     return results;
 }
-export function calcRetirementBenefit(birthday, lastYearEarnings, retirementDate, AIME) {
+export function calcRetirementBenefit(birthday, retirementDate, AIME) {
     const dates = calculateRetirementDates(birthday, retirementDate);
     const age60Year = dates.eclBirthDate.getFullYear() + 60;
     const primaryInsuranceAmount = calculatePIA(AIME, age60Year);
@@ -130,13 +127,13 @@ function calculateEarlyRetirementReduction(amount, months) {
     if (months <= 0)
         return amount;
     let reduction;
-    if (months <= 36) {
-        reduction = months * EARLY_RETIREMENT_REDUCTION_RATES.FIRST_36_MONTHS;
+    if (months <= EARLY_RETIREMENT_REDUCTION.FIRST_MONTHS) {
+        reduction = months * EARLY_RETIREMENT_REDUCTION.FIRST_MONTHS_RATE;
     }
     else {
         reduction =
-            36 * EARLY_RETIREMENT_REDUCTION_RATES.FIRST_36_MONTHS +
-                (months - 36) * EARLY_RETIREMENT_REDUCTION_RATES.ADDITIONAL_MONTHS;
+            EARLY_RETIREMENT_REDUCTION.FIRST_MONTHS * EARLY_RETIREMENT_REDUCTION.FIRST_MONTHS_RATE +
+                (months - EARLY_RETIREMENT_REDUCTION.FIRST_MONTHS) * EARLY_RETIREMENT_REDUCTION.ADDITIONAL_MONTHS_RATE;
     }
     return amount * (1 - reduction);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-security-calculator",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Calculate estimated Social Security Benefits",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",