PHPackages                             bherila/usa-retirement-account-parameters - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. bherila/usa-retirement-account-parameters

ActiveLibrary

bherila/usa-retirement-account-parameters
=========================================

Historical and current U.S. retirement-account contribution limits, phase-outs, shared-limit allocation, and Roth-conversion tax effects.

v0.1.0(yesterday)01↑2900%[2 PRs](https://github.com/bherila/usa-retirement-account-parameters/pulls)MITPHPPHP >=8.2CI passing

Since Aug 28Pushed yesterdayCompare

[ Source](https://github.com/bherila/usa-retirement-account-parameters)[ Packagist](https://packagist.org/packages/bherila/usa-retirement-account-parameters)[ RSS](/packages/bherila-usa-retirement-account-parameters/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (2)Used By (0)

usa-retirement-account-parameters
=================================

[](#usa-retirement-account-parameters)

[![CI](https://github.com/bherila/usa-retirement-account-parameters/actions/workflows/ci.yml/badge.svg)](https://github.com/bherila/usa-retirement-account-parameters/actions/workflows/ci.yml)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

`usa-retirement-account-parameters` is a dependency-free calculation engine for historical and current U.S. retirement-account contribution parameters. It calculates account-level and household-level contribution capacity, IRA phase-outs, shared statutory limits, federal income effects, and Roth-conversion taxability.

The repository contains two native implementations with the same behavior:

- **TypeScript** for npm, exported as `USARetirementAccountParameters`.
- **PHP 8.2+** for Packagist, in the `USARetirementAccountParameters` namespace.

Annual legal parameters are maintained once in `data/retirement-parameters.json` and generated into each single-file runtime. Shared conformance vectors and a full-output parity check keep the TypeScript and PHP engines synchronized.

> **Tax-software scope, not tax advice.** This package calculates statutory parameters from caller-supplied facts. It does not determine whether a plan document permits a contribution, perform ERISA nondiscrimination testing, calculate self-employment tax, replace Form 8606, provide an actuarial valuation, or prepare a tax return. Review material results against the governing plan document and current primary authority.

Supported tax years
-------------------

[](#supported-tax-years)

The encoded range is **1975 through 2026**. The package does not extrapolate a future year. Calling a year outside the range throws `UnsupportedTaxYearError` in TypeScript or `UnsupportedTaxYearException` in PHP.

The 1975 starting point corresponds to the first generally available IRA contribution year. Some early employer-plan years cannot be reduced to a universal modern dollar ceiling from tax year alone. In those cases the engine returns an explicit `indeterminate` status and diagnostic rather than inventing a value.

```
USARetirementAccountParameters.supportedTaxYears();
// { minimum: 1975, maximum: 2026 }
```

Installation
------------

[](#installation)

### npm

[](#npm)

```
npm install usa-retirement-account-parameters
```

The npm package provides ESM, CommonJS, and TypeScript declarations and supports Node.js 20 or later.

```
// ESM
import USARetirementAccountParameters from "usa-retirement-account-parameters";

// CommonJS — the class is the module's default export
const USARetirementAccountParameters = require("usa-retirement-account-parameters").default;
```

### Composer / Packagist

[](#composer--packagist)

```
composer require bherila/usa-retirement-account-parameters
```

The PHP package requires PHP 8.2 or later and loads the native single-file implementation through Composer.

TypeScript builder example
--------------------------

[](#typescript-builder-example)

```
import USARetirementAccountParameters, {
  AccountType,
  ConversionType,
  FilingStatus,
} from "usa-retirement-account-parameters";

const result = USARetirementAccountParameters.forTaxYear(2026)
  .filingStatus(FilingStatus.MARRIED_FILING_JOINTLY)
  .taxpayer("taxpayer", (person) => {
    person
      .bornIn(1963)
      .iraCompensation(180_000)
      .w2Compensation(180_000)
      .rothIraMagi(240_000)
      .traditionalIraDeductionMagi(240_000)
      .coveredByEmployerPlan(true)
      .priorYearFicaWages("employer-a", 180_000)
      .aggregateTraditionalSepSimpleIraBasis(20_000)
      .yearEndTraditionalSepSimpleIraValue(80_000);
  })
  .spouse("spouse", (person) => {
    person
      .bornIn(1970)
      .iraCompensation(0)
      .rothIraMagi(240_000)
      .traditionalIraDeductionMagi(240_000)
      .coveredByEmployerPlan(false);
  })
  .account(
    "taxpayer-401k",
    "taxpayer",
    AccountType.TRADITIONAL_401K,
    (account) => {
      account
        .employer("employer-a")
        .annualAdditionsGroup("employer-a")
        .planCompensation(180_000)
        .permitsRothContributions()
        .permitsRothCatchUp()
        .permitsAfterTaxContributions()
        .expectedEmployerContribution(9_000)
        .priority(10);
    },
  )
  .account("taxpayer-roth-ira", "taxpayer", AccountType.ROTH_IRA, (account) => {
    account.priority(20);
  })
  .account("spouse-traditional-ira", "spouse", AccountType.TRADITIONAL_IRA, (account) => {
    account.priority(30);
  })
  .conversion(
    "ira-conversion",
    "taxpayer",
    ConversionType.IRA_TO_ROTH_IRA,
    10_000,
  )
  .calculate();

console.log(result.accounts[0].maximumAnnualContributionBasedOnInputs);
console.log(result.totals.federalAgiReduction);
console.log(result.conversions[0].taxableAmount);
```

A built scenario can be inspected and calculated repeatedly:

```
const scenario = USARetirementAccountParameters.forTaxYear(2026)
  .filingStatus("MFJ")
  .taxpayer("taxpayer", (person) => person.bornIn(1980).w2Compensation(200_000))
  .build();

const input = scenario.toInput();
const result = scenario.calculate();
```

PHP builder example
-------------------

[](#php-builder-example)

```