Saldo

TypeScript library for Portuguese tax calculations.

Covers dependent worker payslips and independent worker (category B) income, with full TypeScript support.

Quick Start

Pick your path:

• Dependent workers - Payroll with retention tables. Get started.
• Independent workers - Simplified regime / RNH for self-employed. Get started.

Features

• Dependent workers: 2025 retention tables for continent, Azores, and Madeira
• Independent workers: Simplified regime, expense caps, 248 business-day calendar
• Family situations: single, married, dependents, disabilities
• Lunch allowances: meal vouchers and cash
• Holiday bonuses: 13th and 14th month distribution
• Detailed tax breakdown: brackets, tables, and rates
• TypeScript native: full type safety and IntelliSense
• Zero dependencies (except for commander in the CLI wrapper)
• Comes fully featured as a CLI: simulate directly from the terminal

Installation

npm install saldo
# or
pnpm add saldo
# or
yarn add saldo

Core Concepts

Tax Situations

The library picks the right tax table based on:

• Marital status: single or married
• Number of income holders: 1 or 2 (for married couples)
• Dependents: children or other qualifying relatives
• Disability status: worker or partner

Locations

• continent: Mainland Portugal
• azores: Azores
• madeira: Madeira

Each region has different tax rates and rules.

Time Periods

Tax tables change over time. The library includes historical data so calculations are accurate across different periods.

Use Cases

• Payroll systems
• HR salary simulations
• Net salary projections
• Tax scenario comparisons