WPM Calculator Library

A TypeScript library for financial calculations, specifically designed for mortgage simulations in the Portuguese market.

Features

• 🏠 Mortgage payment calculations with three rate types:
  • Fixed Rate
  • Variable Rate (Euribor-based)
  • Mixed Rate (Fixed + Variable periods)
• 📊 Detailed amortization schedules
• 💶 Support for multiple Euribor periods (3M, 6M, 12M)
• 📈 Comprehensive payment breakdowns
• 🔢 Formatted currency and percentage outputs

Installation

npm install wpm-calc-lib

📚 Complete Documentation

Comprehensive documentation is available in the /docs folder:

• Getting Started - Introduction and quick examples
• Fixed Rate Loans - Detailed guide with real scenarios
• Variable Rate Loans - EURIBOR-based mortgages explained
• Mixed Rate Loans - Hybrid mortgages (most popular in Portugal)
• API Reference - Complete type definitions and function signatures
• FAQ - Frequently asked questions and troubleshooting

👉 Start with the Documentation Index for the best learning experience!

Usage

Fixed Rate Mortgage

import { FixedRateLoan, LoanParams } from 'wpm-calc-lib';

const loanParams: LoanParams = {
  propertyValue: 200000,  // Property value in euros
  downPayment: 40000,     // Down payment in euros
  years: 30,              // Loan term in years
  euribor: 2.958,         // Euribor rate (%)
  spread: 1.5             // Bank spread (%)
};

const result = FixedRateLoan.calculate(loanParams);
console.log(`Monthly Payment: ${result.summary.monthlyPayment}€`);

Variable Rate Mortgage (Euribor-based)

import { VariableRateLoan, VariableRateLoanParams } from 'wpm-calc-lib';

const loanParams: VariableRateLoanParams = {
  propertyValue: 200000,
  downPayment: 40000,
  years: 35,
  spread: 1.0,
  euriborPeriod: '6M',    // '3M', '6M', or '12M'
  euriborRates: {
    '3M': 2.000,
    '6M': 2.958,
    '12M': 4.000
  }
};

const result = VariableRateLoan.calculate(loanParams);
console.log(`Monthly Payment: ${result.summary.monthlyPayment}€`);

Mixed Rate Mortgage

import { MixedRateLoan, MixedRateLoanParams } from 'wpm-calc-lib';

const loanParams: MixedRateLoanParams = {
  propertyValue: 200000,
  downPayment: 40000,
  totalYears: 30,         // Total loan term
  fixedRateYears: 10,     // Initial fixed rate period
  spread: 1.5,
  fixedRate: 3.258,       // Fixed rate for initial period
  euriborPeriod: '6M',
  euriborRates: {
    '3M': 2.000,
    '6M': 2.958,
    '12M': 4.000
  }
};

const result = MixedRateLoan.calculate(loanParams);
console.log(`Fixed Period Payment: ${result.fixedPeriod.monthlyPayment}€`);
console.log(`Variable Period Payment: ${result.variablePeriod.monthlyPayment}€`);

API Reference

Common Types

EuriborPeriod

type EuriborPeriod = '3M' | '6M' | '12M';

Fixed Rate Mortgage

LoanParams

interface LoanParams {
  propertyValue: number;  // Value of the property in euros
  downPayment: number;    // Initial down payment in euros
  years: number;          // Loan term in years
  euribor: number;        // Euribor rate in percentage
  spread: number;         // Bank spread in percentage
}

Variable Rate Mortgage

VariableRateLoanParams

interface VariableRateLoanParams {
  propertyValue: number;
  downPayment: number;
  years: number;
  spread: number;
  euriborPeriod: EuriborPeriod;
  euriborRates: Record<EuriborPeriod, number>;
}

Mixed Rate Mortgage

MixedRateLoanParams

interface MixedRateLoanParams {
  propertyValue: number;
  downPayment: number;
  totalYears: number;
  fixedRateYears: number;
  spread: number;
  fixedRate: number;
  euriborPeriod: EuriborPeriod;
  euriborRates: Record<EuriborPeriod, number>;
}

Development

Prerequisites

• Node.js >= 14
• npm >= 6

Setup

1. Clone the repository

git clone https://github.com/wappme/wpm-calc-lib.git
cd wpm-calc-lib

2. Install dependencies

npm install

3. Build the project

npm run build

Testing

The library includes test cases for all mortgage types:

# Run all tests
npm test

# Test specific mortgage types
npm run test:home.loans.fixed
npm run test:home.loans.variable
npm run test:home.loans.mixed

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC License - see the LICENSE file for details