@novha/calc-engines 4.0.0 → 5.0.0

package/test/canada-capital-gains.test.ts

@@ -0,0 +1,71 @@
+import { CanadaCapitalGainsServiceImpl } from '../src/capital-gains/canada/CanadaCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/canada/domain/types';
+
+// Canada 2024 federal tax brackets with 50% inclusion rate
+const canadaCapitalGainsRules: Rules = {
+    inclusionRate: 0.50,
+    taxBrackets: [
+        { from: 0, to: 55867, rate: 0.15 },
+        { from: 55867, to: 111733, rate: 0.205 },
+        { from: 111733, to: 154906, rate: 0.26 },
+        { from: 154906, to: 220000, rate: 0.29 },
+        { from: 220000, to: null, rate: 0.33 },
+    ],
+};
+
+describe('CanadaCapitalGainsServiceImpl', () => {
+    it('applies 50% inclusion rate', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 100000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(50000);
+    });
+
+    it('taxes included gain at marginal rate for low income', () => {
+        const input: Input = { capitalGain: 40000, totalTaxableIncome: 40000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 20000, all in first bracket (15%)
+        expect(result.taxableGain).toBe(20000);
+        expect(result.capitalGainsTax).toBe(20000 * 0.15);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0, totalTaxableIncome: 50000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+        expect(result.taxableGain).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -10000, totalTaxableIncome: 50000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('calculates effective rate based on full gain', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 100000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBe((result.capitalGainsTax / 100000) * 100);
+    });
+
+    it('stacks gain on top of other income', () => {
+        const input: Input = { capitalGain: 20000, totalTaxableIncome: 70000 };
+        const service = new CanadaCapitalGainsServiceImpl(input, canadaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Other income = 50000, taxable gain = 10000
+        // 10000 falls in first bracket (50000-55867 = 5867 at 15%, rest at 20.5%)
+        expect(result.taxableGain).toBe(10000);
+        expect(result.capitalGainsTax).toBeGreaterThan(0);
+    });
+});

package/test/france-capital-gains.test.ts

@@ -0,0 +1,66 @@
+import { FranceCapitalGainsServiceImpl } from '../src/capital-gains/france/FranceCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/france/domain/types';
+
+// France PFU (Prélèvement Forfaitaire Unique) 2024
+const franceCapitalGainsRules: Rules = {
+    flatTaxRate: 0.128,
+    socialContributionsRate: 0.172,
+};
+
+describe('FranceCapitalGainsServiceImpl', () => {
+    it('applies flat tax rate and social contributions', () => {
+        const input: Input = { capitalGain: 100000 };
+        const service = new FranceCapitalGainsServiceImpl(input, franceCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.incomeTax).toBe(12800);
+        expect(result.socialContributions).toBe(17200);
+        expect(result.totalTax).toBe(30000);
+    });
+
+    it('effective rate is 30% (12.8% + 17.2%)', () => {
+        const input: Input = { capitalGain: 50000 };
+        const service = new FranceCapitalGainsServiceImpl(input, franceCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBeCloseTo(30, 1);
+    });
+
+    it('returns two breakdowns (income tax + social)', () => {
+        const input: Input = { capitalGain: 100000 };
+        const service = new FranceCapitalGainsServiceImpl(input, franceCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.breakdowns).toHaveLength(2);
+        expect(result.breakdowns[0].rate).toBe(0.128);
+        expect(result.breakdowns[1].rate).toBe(0.172);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0 };
+        const service = new FranceCapitalGainsServiceImpl(input, franceCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+        expect(result.effectiveRate).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -10000 };
+        const service = new FranceCapitalGainsServiceImpl(input, franceCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+    });
+
+    it('scales linearly with gain amount', () => {
+        const input1: Input = { capitalGain: 100000 };
+        const input2: Input = { capitalGain: 200000 };
+
+        const result1 = new FranceCapitalGainsServiceImpl(input1, franceCapitalGainsRules).calculate();
+        const result2 = new FranceCapitalGainsServiceImpl(input2, franceCapitalGainsRules).calculate();
+
+        expect(result2.totalTax).toBe(result1.totalTax * 2);
+    });
+});

package/test/germany-capital-gains.test.ts

@@ -0,0 +1,85 @@
+import { GermanyCapitalGainsServiceImpl } from '../src/capital-gains/germany/GermanyCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/germany/domain/types';
+
+// Germany 2024 Abgeltungsteuer rules
+const germanyCapitalGainsRules: Rules = {
+    flatTaxRate: 0.25,
+    solidaritySurchargeRate: 0.055,
+    annualExemption: 1000,
+};
+
+describe('GermanyCapitalGainsServiceImpl', () => {
+    it('applies annual exemption of €1,000', () => {
+        const input: Input = { capitalGain: 800 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(0);
+        expect(result.totalTax).toBe(0);
+    });
+
+    it('taxes gains above exemption at 25% + solidarity', () => {
+        const input: Input = { capitalGain: 11000 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable = 11000 - 1000 = 10000
+        // Tax = 10000 * 25% = 2500
+        // Solidarity = 2500 * 5.5% = 137.5
+        // Total = 2637.5
+        expect(result.taxableGain).toBe(10000);
+        expect(result.capitalGainsTax).toBe(2500);
+        expect(result.solidaritySurcharge).toBe(137.5);
+        expect(result.totalTax).toBe(2637.5);
+    });
+
+    it('effective rate accounts for exemption', () => {
+        const input: Input = { capitalGain: 11000 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        // Effective rate = 2637.5 / 11000 * 100
+        expect(result.effectiveRate).toBeCloseTo((2637.5 / 11000) * 100, 2);
+    });
+
+    it('returns two breakdowns for taxable gains', () => {
+        const input: Input = { capitalGain: 5000 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.breakdowns).toHaveLength(2);
+        expect(result.breakdowns[0].rate).toBe(0.25);
+        expect(result.breakdowns[1].rate).toBe(0.055);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -5000 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+    });
+
+    it('calculates correctly for large gains', () => {
+        const input: Input = { capitalGain: 100000 };
+        const service = new GermanyCapitalGainsServiceImpl(input, germanyCapitalGainsRules);
+        const result = service.calculate();
+
+        const taxable = 99000;
+        const cgt = taxable * 0.25;
+        const soli = cgt * 0.055;
+        expect(result.taxableGain).toBe(taxable);
+        expect(result.capitalGainsTax).toBe(cgt);
+        expect(result.solidaritySurcharge).toBeCloseTo(soli, 2);
+        expect(result.totalTax).toBeCloseTo(cgt + soli, 2);
+    });
+});

package/test/south-africa-capital-gains.test.ts

@@ -0,0 +1,84 @@
+import { SouthAfricaCapitalGainsServiceImpl } from '../src/capital-gains/south-africa/SouthAfricaCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/south-africa/domain/types';
+
+// South Africa 2024-25 CGT rules (individuals)
+const southAfricaCapitalGainsRules: Rules = {
+    inclusionRate: 0.40,
+    annualExclusion: 40000,
+    taxBrackets: [
+        { from: 0, to: 237100, rate: 0.18 },
+        { from: 237100, to: 370500, rate: 0.26 },
+        { from: 370500, to: 512800, rate: 0.31 },
+        { from: 512800, to: 673000, rate: 0.36 },
+        { from: 673000, to: 857900, rate: 0.39 },
+        { from: 857900, to: 1817000, rate: 0.41 },
+        { from: 1817000, to: null, rate: 0.45 },
+    ],
+};
+
+describe('SouthAfricaCapitalGainsServiceImpl', () => {
+    it('applies annual exclusion of R40,000', () => {
+        const input: Input = { capitalGain: 30000, totalTaxableIncome: 30000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(0);
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('applies 40% inclusion rate after exclusion', () => {
+        const input: Input = { capitalGain: 140000, totalTaxableIncome: 140000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Net gain = 140000 - 40000 = 100000
+        // Taxable gain = 100000 * 0.40 = 40000
+        expect(result.taxableGain).toBe(40000);
+    });
+
+    it('taxes included gain at marginal rates', () => {
+        const input: Input = { capitalGain: 140000, totalTaxableIncome: 140000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 40000, first bracket rate 18%
+        expect(result.capitalGainsTax).toBe(40000 * 0.18);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0, totalTaxableIncome: 300000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -50000, totalTaxableIncome: 300000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('calculates effective rate based on full gain', () => {
+        const input: Input = { capitalGain: 140000, totalTaxableIncome: 140000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBe((result.capitalGainsTax / 140000) * 100);
+    });
+
+    it('stacks included gain on other income', () => {
+        const input: Input = { capitalGain: 540000, totalTaxableIncome: 840000 };
+        const service = new SouthAfricaCapitalGainsServiceImpl(input, southAfricaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Net gain = 540000 - 40000 = 500000
+        // Taxable gain = 500000 * 0.40 = 200000
+        // Other income = 300000
+        expect(result.taxableGain).toBe(200000);
+        expect(result.capitalGainsTax).toBeGreaterThan(0);
+    });
+});

package/test/uk-capital-gains.test.ts

@@ -0,0 +1,79 @@
+import { UKCapitalGainsServiceImpl } from '../src/capital-gains/uk/UKCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/uk/domain/types';
+
+// UK 2024-25 CGT rules (non-residential assets)
+const ukCapitalGainsRules: Rules = {
+    annualExemption: 3000,
+    basicRate: 0.10,
+    higherRate: 0.20,
+    basicRateLimit: 37700,
+};
+
+describe('UKCapitalGainsServiceImpl', () => {
+    it('applies annual exemption', () => {
+        const input: Input = { capitalGain: 2000, totalTaxableIncome: 20000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(0);
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('applies basic rate for basic-rate taxpayer', () => {
+        const input: Input = { capitalGain: 13000, totalTaxableIncome: 20000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 13000 - 3000 = 10000
+        // Basic rate remaining = 37700 - 20000 = 17700 (enough for all)
+        expect(result.taxableGain).toBe(10000);
+        expect(result.capitalGainsTax).toBe(10000 * 0.10);
+    });
+
+    it('applies higher rate for higher-rate taxpayer', () => {
+        const input: Input = { capitalGain: 53000, totalTaxableIncome: 50000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 53000 - 3000 = 50000, all at higher rate (income > basic rate limit)
+        expect(result.taxableGain).toBe(50000);
+        expect(result.capitalGainsTax).toBe(50000 * 0.20);
+    });
+
+    it('splits between basic and higher rate', () => {
+        const input: Input = { capitalGain: 23000, totalTaxableIncome: 30000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 23000 - 3000 = 20000
+        // Basic rate remaining = 37700 - 30000 = 7700
+        // 7700 at 10% = 770, 12300 at 20% = 2460
+        expect(result.taxableGain).toBe(20000);
+        expect(result.capitalGainsTax).toBe(7700 * 0.10 + 12300 * 0.20);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0, totalTaxableIncome: 50000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -5000, totalTaxableIncome: 50000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('calculates effective rate based on full gain', () => {
+        const input: Input = { capitalGain: 53000, totalTaxableIncome: 50000 };
+        const service = new UKCapitalGainsServiceImpl(input, ukCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBe((result.capitalGainsTax / 53000) * 100);
+    });
+});

package/test/usa-capital-gains.test.ts

@@ -0,0 +1,88 @@
+import { USACapitalGainsServiceImpl } from '../src/capital-gains/usa/USACapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/usa/domain/types';
+
+// USA 2024 long-term capital gains brackets (single filer)
+const usaCapitalGainsRules: Rules = {
+    longTermBrackets: [
+        { from: 0, to: 47025, rate: 0.00 },
+        { from: 47025, to: 518900, rate: 0.15 },
+        { from: 518900, to: null, rate: 0.20 },
+    ],
+    shortTermBrackets: [
+        { from: 0, to: 11600, rate: 0.10 },
+        { from: 11600, to: 47150, rate: 0.12 },
+        { from: 47150, to: 100525, rate: 0.22 },
+        { from: 100525, to: 191950, rate: 0.24 },
+        { from: 191950, to: 243725, rate: 0.32 },
+        { from: 243725, to: 609350, rate: 0.35 },
+        { from: 609350, to: null, rate: 0.37 },
+    ],
+    netInvestmentIncomeTax: { rate: 0.038, threshold: 200000 },
+};
+
+describe('USACapitalGainsServiceImpl', () => {
+    it('applies 0% long-term rate for low income', () => {
+        const input: Input = { capitalGain: 30000, totalTaxableIncome: 30000, holdingPeriodMonths: 24 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+        expect(result.netInvestmentIncomeTax).toBe(0);
+        expect(result.totalTax).toBe(0);
+    });
+
+    it('applies 15% long-term rate for mid income', () => {
+        const input: Input = { capitalGain: 50000, totalTaxableIncome: 100000, holdingPeriodMonths: 13 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Other income = 50000, gain falls in 50000-100000 range, all at 15%
+        expect(result.capitalGainsTax).toBe(50000 * 0.15);
+        expect(result.netInvestmentIncomeTax).toBe(0);
+    });
+
+    it('applies NIIT for high-income earners', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 300000, holdingPeriodMonths: 24 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.netInvestmentIncomeTax).toBe(100000 * 0.038);
+        expect(result.totalTax).toBe(result.capitalGainsTax + result.netInvestmentIncomeTax);
+    });
+
+    it('applies short-term rates for gains held <= 12 months', () => {
+        const input: Input = { capitalGain: 50000, totalTaxableIncome: 50000, holdingPeriodMonths: 6 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Short-term gain taxed as ordinary income from 0-50000
+        expect(result.capitalGainsTax).toBeGreaterThan(0);
+        expect(result.breakdowns.length).toBeGreaterThan(0);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0, totalTaxableIncome: 50000, holdingPeriodMonths: 24 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+        expect(result.effectiveRate).toBe(0);
+        expect(result.breakdowns).toHaveLength(0);
+    });
+
+    it('returns zero for negative gain', () => {
+        const input: Input = { capitalGain: -5000, totalTaxableIncome: 50000, holdingPeriodMonths: 24 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.totalTax).toBe(0);
+    });
+
+    it('calculates effective rate correctly', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 100000, holdingPeriodMonths: 24 };
+        const service = new USACapitalGainsServiceImpl(input, usaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBe((result.totalTax / 100000) * 100);
+    });
+});