@novha/calc-engines 4.0.0 → 5.0.0

package/src/capital-gains/france/FranceCapitalGainsServiceImpl.ts

@@ -0,0 +1,48 @@
+import { Breakdown } from "../domain/types";
+import { FranceCapitalGainsService } from "./FranceCapitalGainsService";
+import { Input, Result, Rules } from "./domain/types";
+
+export class FranceCapitalGainsServiceImpl implements FranceCapitalGainsService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const gain = this._input.capitalGain;
+
+        if (gain <= 0) {
+            return { incomeTax: 0, socialContributions: 0, totalTax: 0, effectiveRate: 0, breakdowns: [] };
+        }
+
+        const incomeTax = gain * this._rules.flatTaxRate;
+        const socialContributions = gain * this._rules.socialContributionsRate;
+        const totalTax = incomeTax + socialContributions;
+
+        const breakdowns: Breakdown[] = [
+            {
+                from: '0',
+                to: 'All',
+                rate: this._rules.flatTaxRate,
+                amount: incomeTax,
+            },
+            {
+                from: '0',
+                to: 'Social',
+                rate: this._rules.socialContributionsRate,
+                amount: socialContributions,
+            },
+        ];
+
+        return {
+            incomeTax,
+            socialContributions,
+            totalTax,
+            effectiveRate: (totalTax / gain) * 100,
+            breakdowns,
+        };
+    }
+}

package/src/capital-gains/france/domain/types.ts

@@ -0,0 +1,18 @@
+import { Breakdown } from "../../domain/types";
+
+export interface Rules {
+    flatTaxRate: number;
+    socialContributionsRate: number;
+}
+
+export interface Input {
+    capitalGain: number;
+}
+
+export interface Result {
+    incomeTax: number;
+    socialContributions: number;
+    totalTax: number;
+    effectiveRate: number;
+    breakdowns: Breakdown[];
+}

package/src/capital-gains/germany/GermanyCapitalGainsService.ts

@@ -0,0 +1,5 @@
+import { Result } from "./domain/types";
+
+export interface GermanyCapitalGainsService {
+    calculate(): Result;
+}

package/src/capital-gains/germany/GermanyCapitalGainsServiceImpl.ts

@@ -0,0 +1,74 @@
+import { Breakdown } from "../domain/types";
+import { GermanyCapitalGainsService } from "./GermanyCapitalGainsService";
+import { Input, Result, Rules } from "./domain/types";
+
+export class GermanyCapitalGainsServiceImpl implements GermanyCapitalGainsService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const gain = this._input.capitalGain;
+
+        if (gain <= 0) {
+            return {
+                taxableGain: 0,
+                capitalGainsTax: 0,
+                solidaritySurcharge: 0,
+                totalTax: 0,
+                effectiveRate: 0,
+                breakdowns: [],
+            };
+        }
+
+        const taxableGain = Math.max(0, gain - this._rules.annualExemption);
+
+        if (taxableGain <= 0) {
+            return {
+                taxableGain: 0,
+                capitalGainsTax: 0,
+                solidaritySurcharge: 0,
+                totalTax: 0,
+                effectiveRate: 0,
+                breakdowns: [{
+                    from: '0',
+                    to: `${this._rules.annualExemption}`,
+                    rate: 0,
+                    amount: 0,
+                }],
+            };
+        }
+
+        const capitalGainsTax = taxableGain * this._rules.flatTaxRate;
+        const solidaritySurcharge = capitalGainsTax * this._rules.solidaritySurchargeRate;
+        const totalTax = capitalGainsTax + solidaritySurcharge;
+
+        const breakdowns: Breakdown[] = [
+            {
+                from: '0',
+                to: 'All',
+                rate: this._rules.flatTaxRate,
+                amount: capitalGainsTax,
+            },
+            {
+                from: 'CGT',
+                to: 'Solidarity',
+                rate: this._rules.solidaritySurchargeRate,
+                amount: solidaritySurcharge,
+            },
+        ];
+
+        return {
+            taxableGain,
+            capitalGainsTax,
+            solidaritySurcharge,
+            totalTax,
+            effectiveRate: gain > 0 ? (totalTax / gain) * 100 : 0,
+            breakdowns,
+        };
+    }
+}

package/src/capital-gains/germany/domain/types.ts

@@ -0,0 +1,20 @@
+import { Breakdown } from "../../domain/types";
+
+export interface Rules {
+    flatTaxRate: number;
+    solidaritySurchargeRate: number;
+    annualExemption: number;
+}
+
+export interface Input {
+    capitalGain: number;
+}
+
+export interface Result {
+    taxableGain: number;
+    capitalGainsTax: number;
+    solidaritySurcharge: number;
+    totalTax: number;
+    effectiveRate: number;
+    breakdowns: Breakdown[];
+}

package/src/capital-gains/south-africa/SouthAfricaCapitalGainsService.ts

@@ -0,0 +1,5 @@
+import { Result } from "./domain/types";
+
+export interface SouthAfricaCapitalGainsService {
+    calculate(): Result;
+}

package/src/capital-gains/south-africa/SouthAfricaCapitalGainsServiceImpl.ts

@@ -0,0 +1,87 @@
+import { Breakdown } from "../domain/types";
+import { SouthAfricaCapitalGainsService } from "./SouthAfricaCapitalGainsService";
+import { Input, Result, Rules, TaxBracket } from "./domain/types";
+
+export class SouthAfricaCapitalGainsServiceImpl implements SouthAfricaCapitalGainsService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const gain = this._input.capitalGain;
+
+        if (gain <= 0) {
+            return { taxableGain: 0, capitalGainsTax: 0, effectiveRate: 0, breakdowns: [] };
+        }
+
+        const netGain = Math.max(0, gain - this._rules.annualExclusion);
+        const taxableGain = netGain * this._rules.inclusionRate;
+
+        if (taxableGain <= 0) {
+            return {
+                taxableGain: 0,
+                capitalGainsTax: 0,
+                effectiveRate: 0,
+                breakdowns: [{
+                    from: '0',
+                    to: `${this._rules.annualExclusion}`,
+                    rate: 0,
+                    amount: 0,
+                }],
+            };
+        }
+
+        const otherIncome = this._input.totalTaxableIncome - gain;
+        const { tax, breakdowns } = this.applyBrackets(taxableGain, otherIncome, this._rules.taxBrackets);
+
+        return {
+            taxableGain,
+            capitalGainsTax: tax,
+            effectiveRate: gain > 0 ? (tax / gain) * 100 : 0,
+            breakdowns,
+        };
+    }
+
+    private applyBrackets(
+        taxableGain: number,
+        otherIncome: number,
+        brackets: TaxBracket[],
+    ): { tax: number; breakdowns: Breakdown[] } {
+        let tax = 0;
+        const breakdowns: Breakdown[] = [];
+        let remaining = taxableGain;
+        let incomeUsed = otherIncome;
+
+        for (const bracket of brackets) {
+            if (remaining <= 0) break;
+
+            const upper = bracket.to ?? Infinity;
+
+            if (incomeUsed >= upper) continue;
+
+            const bracketStart = Math.max(bracket.from, incomeUsed);
+            const bracketSpace = upper - bracketStart;
+            const taxable = Math.min(bracketSpace, remaining);
+
+            if (taxable > 0) {
+                const bracketTax = taxable * bracket.rate;
+                tax += bracketTax;
+                remaining -= taxable;
+                incomeUsed += taxable;
+
+                breakdowns.push({
+                    from: `${bracket.from}`,
+                    to: `${bracket.to ?? 'Above'}`,
+                    rate: bracket.rate,
+                    amount: bracketTax,
+                });
+            }
+        }
+
+        return { tax, breakdowns };
+    }
+}

package/src/capital-gains/south-africa/domain/types.ts

@@ -0,0 +1,25 @@
+import { Breakdown } from "../../domain/types";
+
+export interface TaxBracket {
+    from: number;
+    to: number | null;
+    rate: number;
+}
+
+export interface Rules {
+    inclusionRate: number;
+    annualExclusion: number;
+    taxBrackets: TaxBracket[];
+}
+
+export interface Input {
+    capitalGain: number;
+    totalTaxableIncome: number;
+}
+
+export interface Result {
+    taxableGain: number;
+    capitalGainsTax: number;
+    effectiveRate: number;
+    breakdowns: Breakdown[];
+}

package/src/capital-gains/uk/UKCapitalGainsService.ts

@@ -0,0 +1,5 @@
+import { Result } from "./domain/types";
+
+export interface UKCapitalGainsService {
+    calculate(): Result;
+}

package/src/capital-gains/uk/UKCapitalGainsServiceImpl.ts

@@ -0,0 +1,84 @@
+import { Breakdown } from "../domain/types";
+import { UKCapitalGainsService } from "./UKCapitalGainsService";
+import { Input, Result, Rules } from "./domain/types";
+
+export class UKCapitalGainsServiceImpl implements UKCapitalGainsService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const gain = this._input.capitalGain;
+
+        if (gain <= 0) {
+            return { taxableGain: 0, capitalGainsTax: 0, effectiveRate: 0, breakdowns: [] };
+        }
+
+        const taxableGain = Math.max(0, gain - this._rules.annualExemption);
+
+        if (taxableGain <= 0) {
+            return {
+                taxableGain: 0,
+                capitalGainsTax: 0,
+                effectiveRate: 0,
+                breakdowns: [{
+                    from: '0',
+                    to: `${this._rules.annualExemption}`,
+                    rate: 0,
+                    amount: 0,
+                }],
+            };
+        }
+
+        const basicRateRemaining = Math.max(0, this._rules.basicRateLimit - this._input.totalTaxableIncome);
+        const breakdowns: Breakdown[] = [];
+        let tax = 0;
+
+        if (basicRateRemaining > 0) {
+            const basicRateGain = Math.min(taxableGain, basicRateRemaining);
+            const basicTax = basicRateGain * this._rules.basicRate;
+            tax += basicTax;
+
+            breakdowns.push({
+                from: '0',
+                to: `${basicRateRemaining}`,
+                rate: this._rules.basicRate,
+                amount: basicTax,
+            });
+
+            const higherRateGain = taxableGain - basicRateGain;
+            if (higherRateGain > 0) {
+                const higherTax = higherRateGain * this._rules.higherRate;
+                tax += higherTax;
+
+                breakdowns.push({
+                    from: `${basicRateRemaining}`,
+                    to: 'Above',
+                    rate: this._rules.higherRate,
+                    amount: higherTax,
+                });
+            }
+        } else {
+            const higherTax = taxableGain * this._rules.higherRate;
+            tax += higherTax;
+
+            breakdowns.push({
+                from: '0',
+                to: 'Above',
+                rate: this._rules.higherRate,
+                amount: higherTax,
+            });
+        }
+
+        return {
+            taxableGain,
+            capitalGainsTax: tax,
+            effectiveRate: gain > 0 ? (tax / gain) * 100 : 0,
+            breakdowns,
+        };
+    }
+}

package/src/capital-gains/uk/domain/types.ts

@@ -0,0 +1,20 @@
+import { Breakdown } from "../../domain/types";
+
+export interface Rules {
+    annualExemption: number;
+    basicRate: number;
+    higherRate: number;
+    basicRateLimit: number;
+}
+
+export interface Input {
+    capitalGain: number;
+    totalTaxableIncome: number;
+}
+
+export interface Result {
+    taxableGain: number;
+    capitalGainsTax: number;
+    effectiveRate: number;
+    breakdowns: Breakdown[];
+}

package/src/capital-gains/usa/USACapitalGainsService.ts

@@ -0,0 +1,5 @@
+import { Result } from "./domain/types";
+
+export interface USACapitalGainsService {
+    calculate(): Result;
+}

package/src/capital-gains/usa/USACapitalGainsServiceImpl.ts

@@ -0,0 +1,86 @@
+import { Breakdown } from "../domain/types";
+import { USACapitalGainsService } from "./USACapitalGainsService";
+import { Input, LongTermBracket, Result, Rules } from "./domain/types";
+
+export class USACapitalGainsServiceImpl implements USACapitalGainsService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const gain = this._input.capitalGain;
+
+        if (gain <= 0) {
+            return { capitalGainsTax: 0, netInvestmentIncomeTax: 0, totalTax: 0, effectiveRate: 0, breakdowns: [] };
+        }
+
+        const isLongTerm = this._input.holdingPeriodMonths > 12;
+        const brackets = isLongTerm ? this._rules.longTermBrackets : this._rules.shortTermBrackets;
+
+        const { tax, breakdowns } = this.applyBrackets(gain, this._input.totalTaxableIncome, brackets);
+
+        let niit = 0;
+        if (this._input.totalTaxableIncome > this._rules.netInvestmentIncomeTax.threshold) {
+            niit = gain * this._rules.netInvestmentIncomeTax.rate;
+            breakdowns.push({
+                from: 'NIIT',
+                to: 'All Gain',
+                rate: this._rules.netInvestmentIncomeTax.rate,
+                amount: niit,
+            });
+        }
+
+        const totalTax = tax + niit;
+
+        return {
+            capitalGainsTax: tax,
+            netInvestmentIncomeTax: niit,
+            totalTax,
+            effectiveRate: gain > 0 ? (totalTax / gain) * 100 : 0,
+            breakdowns,
+        };
+    }
+
+    private applyBrackets(
+        gain: number,
+        totalIncome: number,
+        brackets: LongTermBracket[],
+    ): { tax: number; breakdowns: Breakdown[] } {
+        let tax = 0;
+        const breakdowns: Breakdown[] = [];
+        let remaining = gain;
+        let incomeUsed = totalIncome - gain;
+
+        for (const bracket of brackets) {
+            if (remaining <= 0) break;
+
+            const upper = bracket.to ?? Infinity;
+
+            if (incomeUsed >= upper) continue;
+
+            const bracketStart = Math.max(bracket.from, incomeUsed);
+            const bracketSpace = upper - bracketStart;
+            const taxable = Math.min(bracketSpace, remaining);
+
+            if (taxable > 0) {
+                const bracketTax = taxable * bracket.rate;
+                tax += bracketTax;
+                remaining -= taxable;
+                incomeUsed += taxable;
+
+                breakdowns.push({
+                    from: `${bracket.from}`,
+                    to: `${bracket.to ?? 'Above'}`,
+                    rate: bracket.rate,
+                    amount: bracketTax,
+                });
+            }
+        }
+
+        return { tax, breakdowns };
+    }
+}

package/src/capital-gains/usa/domain/types.ts

@@ -0,0 +1,27 @@
+import { Breakdown } from "../../domain/types";
+
+export interface LongTermBracket {
+    from: number;
+    to: number | null;
+    rate: number;
+}
+
+export interface Rules {
+    longTermBrackets: LongTermBracket[];
+    shortTermBrackets: LongTermBracket[];
+    netInvestmentIncomeTax: { rate: number; threshold: number };
+}
+
+export interface Input {
+    capitalGain: number;
+    totalTaxableIncome: number;
+    holdingPeriodMonths: number;
+}
+
+export interface Result {
+    capitalGainsTax: number;
+    netInvestmentIncomeTax: number;
+    totalTax: number;
+    effectiveRate: number;
+    breakdowns: Breakdown[];
+}

package/src/index.ts

@@ -144,5 +144,61 @@ export {
     Result as GermanyCorporateTaxResult,
 } from './corporate/germany/domain/types';
 
+// Capital Gains - Canada
+export { CanadaCapitalGainsServiceImpl as CanadaCapitalGainsService } from './capital-gains/canada/CanadaCapitalGainsServiceImpl';
+export {
+    Input as CanadaCapitalGainsInput,
+    Rules as CanadaCapitalGainsRules,
+    Result as CanadaCapitalGainsResult,
+} from './capital-gains/canada/domain/types';
+
+// Capital Gains - France
+export { FranceCapitalGainsServiceImpl as FranceCapitalGainsService } from './capital-gains/france/FranceCapitalGainsServiceImpl';
+export {
+    Input as FranceCapitalGainsInput,
+    Rules as FranceCapitalGainsRules,
+    Result as FranceCapitalGainsResult,
+} from './capital-gains/france/domain/types';
+
+// Capital Gains - South Africa
+export { SouthAfricaCapitalGainsServiceImpl as SouthAfricaCapitalGainsService } from './capital-gains/south-africa/SouthAfricaCapitalGainsServiceImpl';
+export {
+    Input as SouthAfricaCapitalGainsInput,
+    Rules as SouthAfricaCapitalGainsRules,
+    Result as SouthAfricaCapitalGainsResult,
+} from './capital-gains/south-africa/domain/types';
+
+// Capital Gains - Australia
+export { AustraliaCapitalGainsServiceImpl as AustraliaCapitalGainsService } from './capital-gains/australia/AustraliaCapitalGainsServiceImpl';
+export {
+    Input as AustraliaCapitalGainsInput,
+    Rules as AustraliaCapitalGainsRules,
+    Result as AustraliaCapitalGainsResult,
+} from './capital-gains/australia/domain/types';
+
+// Capital Gains - UK
+export { UKCapitalGainsServiceImpl as UKCapitalGainsService } from './capital-gains/uk/UKCapitalGainsServiceImpl';
+export {
+    Input as UKCapitalGainsInput,
+    Rules as UKCapitalGainsRules,
+    Result as UKCapitalGainsResult,
+} from './capital-gains/uk/domain/types';
+
+// Capital Gains - USA
+export { USACapitalGainsServiceImpl as USACapitalGainsService } from './capital-gains/usa/USACapitalGainsServiceImpl';
+export {
+    Input as USACapitalGainsInput,
+    Rules as USACapitalGainsRules,
+    Result as USACapitalGainsResult,
+} from './capital-gains/usa/domain/types';
+
+// Capital Gains - Germany
+export { GermanyCapitalGainsServiceImpl as GermanyCapitalGainsService } from './capital-gains/germany/GermanyCapitalGainsServiceImpl';
+export {
+    Input as GermanyCapitalGainsInput,
+    Rules as GermanyCapitalGainsRules,
+    Result as GermanyCapitalGainsResult,
+} from './capital-gains/germany/domain/types';
+
 export { IncomeTaxCalculatorSchema } from './income-tax/domain/types';
 export * from './income-tax/domain/types';

package/src/shared/domain/types.ts

@@ -3,6 +3,7 @@ export enum CalculatorType {
     MORTGAGE = 'MORTGAGE',
     LOAN = 'LOAN',
     CORPORATE_TAX = 'CORPORATE_TAX',
+    CAPITAL_GAINS = 'CAPITAL_GAINS',
 }
 
 export interface RuleMeta {

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

@@ -0,0 +1,80 @@
+import { AustraliaCapitalGainsServiceImpl } from '../src/capital-gains/australia/AustraliaCapitalGainsServiceImpl';
+import { Input, Rules } from '../src/capital-gains/australia/domain/types';
+
+// Australia 2024-25 individual marginal tax rates + 50% CGT discount
+const australiaCapitalGainsRules: Rules = {
+    cgtDiscount: 0.50,
+    cgtDiscountMinMonths: 12,
+    taxBrackets: [
+        { from: 0, to: 18200, rate: 0.00 },
+        { from: 18200, to: 45000, rate: 0.16 },
+        { from: 45000, to: 135000, rate: 0.30 },
+        { from: 135000, to: 190000, rate: 0.37 },
+        { from: 190000, to: null, rate: 0.45 },
+    ],
+};
+
+describe('AustraliaCapitalGainsServiceImpl', () => {
+    it('applies 50% CGT discount for assets held >= 12 months', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 100000, holdingPeriodMonths: 24 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(50000);
+    });
+
+    it('no discount for assets held < 12 months', () => {
+        const input: Input = { capitalGain: 100000, totalTaxableIncome: 100000, holdingPeriodMonths: 6 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.taxableGain).toBe(100000);
+    });
+
+    it('taxes discounted gain at marginal rates', () => {
+        const input: Input = { capitalGain: 40000, totalTaxableIncome: 40000, holdingPeriodMonths: 18 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Taxable gain = 20000, no other income
+        // 18200 at 0% = 0, 1800 at 16% = 288
+        expect(result.taxableGain).toBe(20000);
+        expect(result.capitalGainsTax).toBeCloseTo(288, 2);
+    });
+
+    it('returns zero for zero gain', () => {
+        const input: Input = { capitalGain: 0, totalTaxableIncome: 50000, holdingPeriodMonths: 24 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        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, holdingPeriodMonths: 24 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.capitalGainsTax).toBe(0);
+    });
+
+    it('stacks gain on top of other income', () => {
+        const input: Input = { capitalGain: 20000, totalTaxableIncome: 70000, holdingPeriodMonths: 24 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        // Other income = 50000, taxable gain = 10000 (50% discount)
+        // Gain falls in 50000-60000 range, all at 30%
+        expect(result.taxableGain).toBe(10000);
+        expect(result.capitalGainsTax).toBe(10000 * 0.30);
+    });
+
+    it('calculates effective rate based on full gain', () => {
+        const input: Input = { capitalGain: 20000, totalTaxableIncome: 70000, holdingPeriodMonths: 24 };
+        const service = new AustraliaCapitalGainsServiceImpl(input, australiaCapitalGainsRules);
+        const result = service.calculate();
+
+        expect(result.effectiveRate).toBe((result.capitalGainsTax / 20000) * 100);
+    });
+});