@finanzfluss/calculators

A selection of financial calculators used on the Finanzfluss Website: https://www.finanzfluss.de/rechner/

🎯 Type-safe: built with TypeScript and Zod validation

🔍 Real-world tested: used by millions of Finanzfluss users

🏛️ German tax system support: Correct tax and insurance calculation

Installation

# pnpm
pnpm add -D @finanzfluss/calculators

# npm
npm install -D @finanzfluss/calculators

# yarn
yarn add -D @finanzfluss/calculators

Calculators

Compound Interest Calculator

The Zinseszinsrechner (https://finanzfluss.de/rechner/zinseszinsrechner) demonstrates the power of compound interest for long-term wealth building. It calculates how investments grow over time when returns are reinvested, helping users visualize the compound effect on their savings.

Key Features:

• Flexible starting capital support for both lump-sum investments and zero initial capital scenarios
• Regular savings plans with configurable monthly payment amounts to model systematic investing
• Multiple compounding intervals supporting monthly, quarterly, and yearly compounding periods
• Long-term projections with duration support from short-term to multi-decade investment horizons
• Interest rate sensitivity analysis showing how small changes in returns dramatically impact final wealth
• Visual data output providing detailed breakdowns of capital growth vs. compound interest accumulation
• Realistic return modeling with validation for reasonable interest rate ranges (-10000% to 10000%)

import { compoundInterest } from '@finanzfluss/calculators'

const input = {
  startCapital: 5000,
  monthlyPayment: 100,
  durationYears: 10,
  yearlyInterest: 7,
  type: 'monthly', // 'monthly', 'quarterly', or 'yearly'
}

// Validate input and calculate compound interest result
const result = compoundInterest.validateAndCalculate(input)

console.log(result.finalCapital) // Total capital after compound growth
console.log(result.totalPayments) // Sum of all payments made
console.log(result.totalInterest) // Total interest earned through compounding
console.log(result.diagramData) // Detailed growth data for visualization

Savings Calculator

The Sparrechner (https://finanzfluss.de/rechner/sparrechner) is a versatile financial planning tool that calculates any unknown variable in a savings plan when all other variables are provided. It helps users plan their savings goals by solving for end value, starting capital, interest rate, duration, or payment amount.

Key Features:

• Flexible calculation modes solving for any of five variables: end value, start capital, interest rate, duration, or payment amount
• Tax-optimized calculations supporting both distributing and accumulating investment types with capital gains tax considerations
• Partial tax exemption modeling the German partial exemption (Teilfreistellung) for funds
• Multiple saving intervals supporting both monthly and yearly payment schedules
• Visual growth tracking providing detailed capital and interest accumulation data for charts

import { savings } from '@finanzfluss/calculators'

const input = {
  output: 'endValue', // What to calculate: 'endValue', 'startValue', 'yearlyInterest', 'monthlyDuration', or 'savingRate'
  startValue: 10000,
  savingRate: 200,
  saveIntervalType: 'monthly', // 'monthly' or 'yearly'
  savingType: 'inAdvance', // 'inAdvance' or 'inArrear'
  yearlyInterest: 7,
  interestIntervalType: 'monthly', // 'monthly', 'quarterly', or 'yearly'
  yearlyDuration: 20,
  considerCapitalGainsTax: true,
  capitalGainsTax: 26.375,
  distributionType: 'accumulating', // 'accumulating' or 'distributing'
  partialExemption: 30,
  useCompoundInterest: true,
}

// Validate input and calculate savings result
const result = savings.validateAndCalculate(input)

console.log(result.endValue) // Final portfolio value
console.log(result.deposits) // Total amount deposited
console.log(result.interestAfterTax) // Net interest earned after tax
console.log(result.yearlyDuration) // Duration in years
console.log(result.monthlyDuration) // Duration in months
console.log(result.diagramData) // Detailed capital and interest growth data

Gross-to-Net Calculator

The Brutto-Netto-Rechner (https://finanzfluss.de/rechner/brutto-netto-rechner) calculates a net salary from gross income, accounting for all German tax and social insurance deductions. It is based on the official pseudo code for tax calculation provided by the German ministry of finance: https://www.bmf-steuerrechner.de/interface/pseudocodes.xhtml.

Key Features:

• All 6 German tax classes (I-VI) with specific calculations for single, married, and divorced individuals
• State-specific calculations for all 16 German states including varying church tax rates (8% in Bavaria/Baden-Württemberg, 9% elsewhere)
• Age-based adjustments including senior citizen tax relief (Altersentlastungsbetrag) for 64+ years
• Child allowances with support for partial children (e.g., 0.5 children for blended families)
• Flexible insurance options supporting both public (GKV) and private (PKV) health insurance
• Comprehensive social insurance including pension, unemployment, and care insurance calculations

import { grossToNet } from '@finanzfluss/calculators'

const input = {
  inputAccountingYear: '2025',
  inputTaxClass: 1,
  inputTaxAllowance: 0,
  inputChurchTax: 0,
  inputState: 'Hamburg',
  inputYearOfBirth: 1990,
  inputChildren: 0,
  inputChildTaxAllowance: 0,
  inputPkvContribution: 0,
  inputPpvContribution: 0,
  inputEmployerSubsidy: 0,
  inputPensionInsurance: 0,
  inputLevyOne: 0,
  inputLevyTwo: 0,
  inputActivateLevy: 0,
  inputHealthInsurance: 0,
  inputAdditionalContribution: 1.7,
  inputGrossWage: 5000,
  inputPeriod: 2, // 2 = monthly, 1 = yearly
}

// Validate input and calculate gross to net result
const result = grossToNet.validateAndCalculate(input)

console.log(result.outputResNetWageMonth) // Net monthly wage
console.log(result.outputResNetWageYear) // Net yearly wage

Net Policy Calculator

The Rentenversicherung-Rechner (https://finanzfluss.de/rechner/rentenversicherung) compares ETF-based pension insurance policies (Nettopolice) with traditional ETF savings plans for retirement planning.

Key Features:

• ETF pension insurance analysis comparing net policies vs. direct ETF investments
• Tax optimization calculations including different taxation rules for insurance vs. investment gains
• Cost structure analysis factoring in management fees, placement commissions, and ongoing charges
• Long-term projections with realistic return assumptions (typically 7% for diversified equity portfolios)
• Flexible withdrawal scenarios supporting both lump-sum and gradual withdrawal strategies
• Real-world cost modeling using actual insurance product data and fee structures

import { netPolicy } from '@finanzfluss/calculators'

const input = {
  // General inputs
  savingRate: 250,
  duration: 35, // in years
  taxAllowance: 1000,
  additionalIncome: 0,
  capitalGainsTax: 26.375,

  // Policy inputs
  placementCommission: 299,
  savingRateCosts: 4,
  balanceCosts: 0.22,
  fixedCosts: 10,
  minimumCosts: 30,

  // ETF inputs
  ter: 0.2,
  expectedInterest: 7,
  partialExemption: 30,

  // Reallocation inputs
  reallocationOccurrence: 10,
  reallocationRate: 40,
}

// Validate input and calculate net policy result
const result = netPolicy.validateAndCalculate(input)

console.log(result.tableData.netWorth) // Projected net worth over time

Disability Insurance Calculator

The Berufsunfähigkeitsversicherung-Rechner (https://finanzfluss.de/rechner/berufsunfaehigkeitsversicherung) helps users determine how much disability insurance coverage they need. It compares three standard coverage levels against their current income and models the income gap during different stages of disability.

Key Features:

• Three DIN 77230 coverage levels based on the German standard for private household financial analysis: securing basic existence (avoiding social welfare), maintaining your current standard of living, and enabling an improved standard of living that covers additional goals like property, family, or wealth building
• Income timeline modeling showing actual take-home at each stage: working, short-term sick leave, prolonged illness (Krankengeld), and full disability (Erwerbsminderungsrente)
• Custom coverage input supporting a user-defined target pension amount alongside the three standard levels
• Visual data output providing both tabular level comparisons and interval-based coverage data for charts

import { disabilityInsurance } from '@finanzfluss/calculators'

const input = {
  grossIncome: 4000,
  netIncome: 2600,
  useCustomHalfDisabilityPension: false, // set to true to override the estimated value
  customHalfDisabilityPension: 0,
  numberOfChildren: 1, // affects care insurance contribution rate (0–4)
  useCustomPensionAmount: false,
  customPensionAmount: 0,
}

// Validate input and calculate disability insurance result
const result = disabilityInsurance.validateAndCalculate(input)

result.tableData.level1 // Level 1: basic existence security (DIN 77230 Stufe 1)
result.tableData.level2 // Level 2: maintaining current standard of living (DIN 77230 Stufe 2)
result.tableData.level3 // Level 3: improved standard of living (DIN 77230 Stufe 3)

AV-Depot Calculator

The Altersvorsorgedepot-Rechner (https://finanzfluss.de/rechner/altersvorsorgedepot) compares saving into a subsidized AV-Depot (Altersvorsorgedepot) against a regular ETF brokerage depot for retirement. It models the full savings and payout phases for both accounts, accounting for state subsidies (Grundzulage, Kinderzulage, Berufseinsteigerbonus), Vorabpauschale taxation, and the tax treatment of withdrawals (Günstigerprüfung, Halbeinkünfteverfahren).

Key Features:

• Side-by-side depot comparison projecting year-by-year capital growth for both an AV-Depot and a normal depot under the same contributions and returns
• State subsidies including Grundzulage, Kinderzulage per eligible child, and the Berufseinsteigerbonus for savers under 25
• Configurable tax-savings handling letting the income-tax refund from AV contributions flow back into the AV-Depot, into a separate secondary depot, or be consumed
• Payout-phase modeling covering the optional one-time lump-sum payout and the taxation of subsequent annual withdrawals for both depots

import { avDepot } from '@finanzfluss/calculators'

const input = {
  age: 35,
  retirementAge: 67,
  zveSavingsPhase: 50_000,
  zveRetirement: 20_000,
  savingsRate: 1_800,
  etfReturnRate: 6, // percent
  avDepotCosts: 0.2, // percent, annual AV-Depot cost drag
  exemptionOrder: 1_000,
  taxSavingsMode: 'avDepot', // 'avDepot' | 'secondaryDepot' | 'consume'
  baseRate: 0, // percent, Basiszins for Vorabpauschale
  oneTimePayout: 0, // percent taken as a lump sum at retirement
  payoutReturnRate: 3, // percent
  payoutUntilAge: 85,
  childBirthYears: [], // enables Kinderzulage while children are under 18
}

// Validate input and calculate AV-Depot result
const result = avDepot.validateAndCalculate(input)

result.finalCapital.avDepot // Capital in the AV-Depot at retirement
result.finalCapital.normalDepot // Capital in a comparable normal depot at retirement
result.payoutTotal.net.avDepot // Total net payout from the AV-Depot

AV-Depot Simulator

The AV-Depot calculation on its own, without the comparison to a normal depot. It is the core of the AV-Depot Calculator. It returns raw numbers instead of formatted strings.

Key Features:

• Same inputs as the AV-Depot Calculator, plus two optional fields for transfers into an AV-Depot
• Start capital (startCapital) treated as subsidized capital: it grows from the first year, is taxed like subsidized capital on payout, earns no Zulagen and doesn't count as own contribution
• Optional Berufseinsteigerbonus (includeStarterBonus) to exclude the bonus when it was already received, e.g. in a transferred Riester contract
• Subsidy and tax-saving totals for Grundzulage, Kinderzulage, Berufseinsteigerbonus and the income-tax saving

import { avDepotSimulator } from '@finanzfluss/calculators'

const result = avDepotSimulator.validateAndCalculate({
  ...input, // same input as for the AV-Depot Calculator
  startCapital: 25_000, // optional, defaults to 0
  includeStarterBonus: false, // optional, defaults to true
})

result.savings.finalCapital // Capital in the AV-Depot (incl. secondary depot) at retirement
result.savings.totalGrundzulage // Sum of all Grundzulagen
result.payout.totalNet // Total net payout

Riester or AV-Depot Calculator

Compares keeping an existing Riester contract with transferring its capital into an AV-Depot and continuing the contributions there. Both scenarios are projected through the savings and payout phases. The result includes a verdict on which option leads.

Key Features:

• Contract transfer moving the current Riester contract value into the AV-Depot, minus switching costs if the contract is younger than five years
• Riester return rate entered manually or derived from the contract's value, total contributions and allowances (falls back to a default rate if the contract is too young or inputs are missing)
• Riester payout as a lifelong annuity based on the contract's annuity factor (Rentenfaktor per 10,000 €)
• Verdict with the capital difference, the subsidy difference, the monthly net payout of both options and the survival probability to the end of the payout phase (Destatis Periodensterbetafel)

import { riesterOrAvDepot } from '@finanzfluss/calculators'

const input = {
  age: 42,
  retirementAge: 67,
  zveSavingsPhase: 30_000,
  zveRetirement: 20_000,
  riesterAnnualContribution: 1_200, // own contribution per year
  riesterContractValue: 18_500, // current value of the Riester contract
  riesterContractStart: 2012,
  riesterTotalContributions: 9_000, // optional, used to derive the return rate
  riesterTotalAllowances: 2_500, // optional, used to derive the return rate
  // riesterReturnRate: 2, // optional, percent, overrides the derived rate
  riesterAnnuityFactor: 32.5, // monthly annuity per 10,000 € capital
  riesterSwitchingCosts: 150,
  etfReturnRate: 6, // percent
  avDepotCosts: 0.2, // percent, annual AV-Depot cost drag
  oneTimePayout: 0, // percent taken as a lump sum at retirement
  payoutReturnRate: 3, // percent
  payoutUntilAge: 85,
  childBirthYears: [],
}

const result = riesterOrAvDepot.validateAndCalculate(input)

result.finalCapital.avDepot // Capital in the AV-Depot at retirement
result.finalCapital.riester // Capital in the Riester contract at retirement
result.riesterReturnRate.case // 'manual' | 'derived' | 'missingInputs' | 'tooShort' | 'tooHigh' | 'tooLow'
result.verdict.case // 'avDepotWins' | 'riesterWins' | 'mixed'

Testing

Run the test suite:

pnpm test

Run type checking:

pnpm test:types

Run tests with coverage report:

pnpm test:coverage

License

AGPL-3.0 License © 2025-PRESENT Finflow GmbH