Getting Started

Dependent worker payroll calculations. For self-employed, see independent worker docs.

Installation


npm install saldo
# or
pnpm add saldo

Quick Start (CLI)

You can run calculations directly from the terminal if you install the package globally:


saldo dependent --year 2025 --income 1500 --twelfths 2

Quick Start (Library)

Interactive Example

const result = simulateDependentWorker({
year: 2025,
income: 1500, // Monthly gross income in euros
location: 'continent',
married: false
});

// Access the January breakdown
const jan = result.monthlyBreakdown[0];
console.log(`Gross Income (Jan): €${jan.grossIncome.baseSalaryAmount.toFixed(2)}`);
console.log(`IRS Withheld (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`Social Security (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Net Income (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

// Yearly totals
console.log(`Annual Net: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);
const result = simulateDependentWorker({
year: 2025,
income: 1500, // Monthly gross income in euros
location: 'continent',
married: false
});

// Access the January breakdown
const jan = result.monthlyBreakdown[0];
console.log(`Gross Income (Jan): €${jan.grossIncome.baseSalaryAmount.toFixed(2)}`);
console.log(`IRS Withheld (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`Social Security (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Net Income (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

// Yearly totals
console.log(`Annual Net: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);

Understanding the Result


interface DependentWorkerResult {
  yearly: {
    totalGrossIncomeAmount: number;         // Annual gross income
    totalNetIncomeAmount: number;           // Annual net income
    totalLunchAllowanceGrossAmount: number; // Annual lunch allowance
  };
  socialSecurityContributionRate: number;   // SS rate applied
  monthlyBreakdown: MonthlyBreakdownResult[]; // 12 entries, one per month
}
 
interface MonthlyBreakdownResult {
  month: MonthName;   // e.g. "january"
  period: PeriodT;    // e.g. "2025-01-01_2025-07-31"
  grossIncome: {
    baseSalaryAmount: number;
    baseSalaryAndLunchAllowanceAmount: number;
    totalWithLunchAllowanceAndSubsidyTwelfthsAmount: number;
  };
  irsWithholdingTax: {
    totalAmount: number;
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  socialSecurityContribution: {
    totalAmount: number;
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  netIncome: {
    totalAmount: number;       // Monthly net salary (the main figure)
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  lunchAllowance: LunchAllowanceAmountBreakdown;
  subsidyTwelfths: SubsidyTwelfthsAmountBreakdown;
  bracket: BracketResult;
  taxRetentionTable: TaxRetentionTableResult;
}

Key Parameters

year: Tax year — required (e.g. 2025)
income: Monthly gross income in euros
married / numberOfHolders: Required together for married workers (1 or 2)
disabled, partnerDisabled, numberOfDependents, numberOfDependentsDisabled
location: 'continent' | 'azores' | 'madeira' (default 'continent')
socialSecurityContributionRate: Default 0.11
twelfths: Twelfths.NONE | ONE_HALF_MONTH | ONE_MONTH | TWO_MONTHS (default TWO_MONTHS)
lunchAllowanceDailyValue, lunchAllowanceMode ("cupon" or "salary"), lunchAllowanceDaysCount
includeLunchAllowanceInJune: Whether June gets lunch allowance (default false)
oneHalfMonthTwelfthsLumpSumMonth: "june" or "december" (default "december")
isencaoHorarioMonthly: Monthly “isenção de horário” supplement (Art. 218.º–219.º + 265.º CT). Default 0
benefitsOfYouthIrs + yearOfYouthIrs: IRS Jovem partial monthly retention exemption (Art. 2.º-C CIRS). See the IRS Jovem section in the API reference

Common Scenarios

Single Person

Interactive Example

const single = simulateDependentWorker({
year: 2025,
income: 1000,
location: 'continent'
});

console.log('=== Single Person ===');
// Monthly net in january
const jan = single.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Annual Net: €${single.yearly.totalNetIncomeAmount.toFixed(2)}`);const single = simulateDependentWorker({
year: 2025,
income: 1000,
location: 'continent'
});

console.log('=== Single Person ===');
// Monthly net in january
const jan = single.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Annual Net: €${single.yearly.totalNetIncomeAmount.toFixed(2)}`);

Married with Children

Interactive Example

const marriedWithKids = simulateDependentWorker({
year: 2025,
income: 1800,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent'
});

console.log('=== Married with Children ===');
const jan = marriedWithKids.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Tax Bracket Deduction: €${jan.bracket.deduction.toFixed(2)}`);const marriedWithKids = simulateDependentWorker({
year: 2025,
income: 1800,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent'
});

console.log('=== Married with Children ===');
const jan = marriedWithKids.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Tax Bracket Deduction: €${jan.bracket.deduction.toFixed(2)}`);

Disabled Worker

Interactive Example

const disabledWorker = simulateDependentWorker({
year: 2025,
income: 1200,
disabled: true,
location: 'continent'
});

console.log('=== Disabled Worker ===');
const jan = disabledWorker.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Additional Deduction: €${jan.bracket.var1_deduction.toFixed(2)}`);const disabledWorker = simulateDependentWorker({
year: 2025,
income: 1200,
disabled: true,
location: 'continent'
});

console.log('=== Disabled Worker ===');
const jan = disabledWorker.monthlyBreakdown[0];
console.log(`Monthly Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Additional Deduction: €${jan.bracket.var1_deduction.toFixed(2)}`);

With Lunch Allowance

Interactive Example

const withLunch = simulateDependentWorker({
year: 2025,
income: 1400,
lunchAllowanceDailyValue: 7.5,
lunchAllowanceMode: "cupon",
lunchAllowanceDaysCount: 22,
location: 'continent'
});

console.log('=== With Lunch Allowance ===');
const jan = withLunch.monthlyBreakdown[0];
console.log(`Base Net Income: €${jan.netIncome.fromBaseSalaryAmount.toFixed(2)}`);
console.log(`Lunch Allowance Gross: €${jan.lunchAllowance.grossAmount.toFixed(2)}`);
console.log(`Total Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);const withLunch = simulateDependentWorker({
year: 2025,
income: 1400,
lunchAllowanceDailyValue: 7.5,
lunchAllowanceMode: "cupon",
lunchAllowanceDaysCount: 22,
location: 'continent'
});

console.log('=== With Lunch Allowance ===');
const jan = withLunch.monthlyBreakdown[0];
console.log(`Base Net Income: €${jan.netIncome.fromBaseSalaryAmount.toFixed(2)}`);
console.log(`Lunch Allowance Gross: €${jan.lunchAllowance.grossAmount.toFixed(2)}`);
console.log(`Total Net (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

Using Twelfths Enum

Interactive Example

const withoutHolidayAllowance = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.NONE, // No holiday allowance distribution
location: 'continent'
});

const withBothHolidayAllowances = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.TWO_MONTHS, // Both Christmas AND holiday allowance
location: 'continent'
});

console.log('=== Twelfths Comparison ===');
const janNoTwelfths = withoutHolidayAllowance.monthlyBreakdown[0];
const janBothTwelfths = withBothHolidayAllowances.monthlyBreakdown[0];
console.log(`No Distribution - Monthly Net (Jan): €${janNoTwelfths.netIncome.totalAmount.toFixed(2)}`);
console.log(`Two Months - Monthly Net (Jan): €${janBothTwelfths.netIncome.totalAmount.toFixed(2)}`);
console.log(`Two Months - Annual Net: €${withBothHolidayAllowances.yearly.totalNetIncomeAmount.toFixed(2)}`);
const withoutHolidayAllowance = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.NONE, // No holiday allowance distribution
location: 'continent'
});

const withBothHolidayAllowances = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.TWO_MONTHS, // Both Christmas AND holiday allowance
location: 'continent'
});

console.log('=== Twelfths Comparison ===');
const janNoTwelfths = withoutHolidayAllowance.monthlyBreakdown[0];
const janBothTwelfths = withBothHolidayAllowances.monthlyBreakdown[0];
console.log(`No Distribution - Monthly Net (Jan): €${janNoTwelfths.netIncome.totalAmount.toFixed(2)}`);
console.log(`Two Months - Monthly Net (Jan): €${janBothTwelfths.netIncome.totalAmount.toFixed(2)}`);
console.log(`Two Months - Annual Net: €${withBothHolidayAllowances.yearly.totalNetIncomeAmount.toFixed(2)}`);

Working with Types


import { 
  simulateDependentWorker, 
  LocationT, 
  Twelfths, 
  DependentWorkerResult,
  SimulateDependentWorkerOptions
} from 'saldo';
 
// Type-safe dependent worker calculation
const dependentOpts: SimulateDependentWorkerOptions = {
  year: 2025,
  income: 1500,
  location: 'continent',
};
const dependentResult: DependentWorkerResult = simulateDependentWorker(dependentOpts);

Regional Differences

Each Portuguese region has different tax rates:

Interactive Example

// Mainland Portugal
const continent = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'continent'
});

// Azores
const azores = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'azores'
});

// Madeira
const madeira = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'madeira'
});

console.log('=== Regional Comparison (€1500 income, January) ===');
console.log(`Continent - Net: €${continent.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Azores - Net: €${azores.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Madeira - Net: €${madeira.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);// Mainland Portugal
const continent = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'continent'
});

// Azores
const azores = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'azores'
});

// Madeira
const madeira = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'madeira'
});

console.log('=== Regional Comparison (€1500 income, January) ===');
console.log(`Continent - Net: €${continent.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Azores - Net: €${azores.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Madeira - Net: €${madeira.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);

Error Handling

The library provides clear error messages for invalid configurations:

Interactive Example

try {
const result = simulateDependentWorker({
  year: 2025,
  income: 1500,
  married: true,
  // Missing numberOfHolders - required for married
});
} catch (error) {
console.error('Error:', error.message); // "'numberOfHolders' is required for married workers"
}try {
const result = simulateDependentWorker({
  year: 2025,
  income: 1500,
  married: true,
  // Missing numberOfHolders - required for married
});
} catch (error) {
console.error('Error:', error.message); // "'numberOfHolders' is required for married workers"
}

Next Steps

Learn about tax situations and scenarios
Explore the tax tables explorer
Understand lunch allowances
Review the dependent worker API
Browse dependent worker examples
Working with self-employed? Jump to the independent worker docs.