@novha/calc-engines 2.0.2 → 3.0.0

package/src/corporate/uk/UKCorporateTaxServiceImpl.ts

@@ -0,0 +1,82 @@
+import { Breakdown } from "../domain/types";
+import { UKCorporateTaxService } from "./UKCorporateTaxService";
+import { Input, MarginalReliefRule, Result, Rules } from "./domain/types";
+
+export class UKCorporateTaxServiceImpl implements UKCorporateTaxService {
+    private _input: Input;
+    private _rules: Rules;
+
+    constructor(input: Input, rules: Rules) {
+        this._input = input;
+        this._rules = rules;
+    }
+
+    calculate(): Result {
+        const income = this._input.taxableIncome;
+        const { smallProfits, main, marginalRelief } = this._rules.regimes;
+
+        let tax = 0;
+        let breakdowns: Breakdown[] = [];
+
+        if (income <= 0) {
+            return { corporateTax: 0, effectiveTaxRate: 0, breakdowns: [] };
+        }
+
+        if (income <= marginalRelief.lowerLimit) {
+            tax = income * smallProfits.rate;
+            breakdowns = [{
+                from: '0',
+                to: `${marginalRelief.lowerLimit}`,
+                rate: smallProfits.rate,
+                amount: tax,
+            }];
+        } else if (income >= marginalRelief.upperLimit) {
+            tax = income * main.rate;
+            breakdowns = [{
+                from: '0',
+                to: 'Above',
+                rate: main.rate,
+                amount: tax,
+            }];
+        } else {
+            tax = this.applyMarginalRelief(income, marginalRelief);
+            breakdowns = this.buildMarginalReliefBreakdowns(income, tax, marginalRelief);
+        }
+
+        return {
+            corporateTax: tax,
+            effectiveTaxRate: income > 0 ? (tax / income) * 100 : 0,
+            breakdowns,
+        };
+    }
+
+    private applyMarginalRelief(income: number, rules: MarginalReliefRule): number {
+        const grossTax = income * rules.mainRate;
+        const relief = rules.standardFraction * (rules.upperLimit - income);
+        return grossTax - relief;
+    }
+
+    private buildMarginalReliefBreakdowns(
+        income: number,
+        tax: number,
+        rules: MarginalReliefRule,
+    ): Breakdown[] {
+        const grossTax = income * rules.mainRate;
+        const relief = rules.standardFraction * (rules.upperLimit - income);
+
+        return [
+            {
+                from: '0',
+                to: 'Above',
+                rate: rules.mainRate,
+                amount: grossTax,
+            },
+            {
+                from: `${rules.lowerLimit}`,
+                to: `${rules.upperLimit}`,
+                rate: -(rules.standardFraction),
+                amount: -relief,
+            },
+        ];
+    }
+}

package/src/corporate/uk/domain/types.ts

@@ -0,0 +1,38 @@
+import { Breakdown } from "../../domain/types";
+
+export interface FlatTaxRule {
+    type: 'flat';
+    rate: number;
+    conditions?: {
+        maxIncome?: number;
+    };
+}
+
+export interface MarginalReliefRule {
+    type: 'marginal_relief';
+    mainRate: number;
+    smallProfitsRate: number;
+    upperLimit: number;
+    lowerLimit: number;
+    standardFraction: number;
+}
+
+export type TaxRule = FlatTaxRule | MarginalReliefRule;
+
+export interface Rules {
+    regimes: {
+        smallProfits: FlatTaxRule;
+        main: FlatTaxRule;
+        marginalRelief: MarginalReliefRule;
+    };
+}
+
+export interface Input {
+    taxableIncome: number;
+}
+
+export interface Result {
+    corporateTax: number;
+    effectiveTaxRate: number;
+    breakdowns: Breakdown[];
+}

package/src/income-tax/uk/UKIncomeTaxService.ts

@@ -0,0 +1,5 @@
+import { ComputedIncomeTaxValues } from "./domain/types";
+
+export interface UKIncomeTaxService {
+    calculateNetIncome(): ComputedIncomeTaxValues;
+}

package/src/income-tax/uk/UKIncomeTaxServiceImpl.ts

@@ -0,0 +1,133 @@
+import { BracketAllocation } from "../domain/types";
+import { UKIncomeTaxService } from "./UKIncomeTaxService";
+import {
+    ComputedIncomeTaxValues,
+    IncomeTaxRules,
+    NationalInsuranceRules,
+    PersonalAllowanceRules,
+} from "./domain/types";
+
+export class UKIncomeTaxServiceImpl implements UKIncomeTaxService {
+    private _income: number;
+    private _rules: IncomeTaxRules;
+
+    constructor(income: number, rules: IncomeTaxRules) {
+        this._income = income;
+        this._rules = rules;
+    }
+
+    public calculateNetIncome(): ComputedIncomeTaxValues {
+        const effectivePA = this.computePersonalAllowance(
+            this._income,
+            this._rules.personalAllowance,
+        );
+        const taxableIncome = Math.max(0, this._income - effectivePA);
+
+        const { grossTax, bracketBreakdown } = this.computeTaxBrackets(taxableIncome);
+
+        const ni = this.computeNationalInsurance(
+            this._income,
+            this._rules.nationalInsurance,
+        );
+
+        const totalDeductions = grossTax + ni;
+        const netIncome = this._income - totalDeductions;
+
+        return {
+            grossIncome: this._income,
+            incomeTax: this.round(grossTax),
+            nationalInsurance: this.round(ni),
+            personalAllowance: effectivePA,
+            totalDeductions: this.round(totalDeductions),
+            netIncome: this.round(netIncome),
+            effectiveTaxRate: this._income > 0 ? this.round(grossTax / this._income, 4) : 0,
+            taxBracketBreakdown: bracketBreakdown,
+        };
+    }
+
+    private computePersonalAllowance(
+        income: number,
+        rules: PersonalAllowanceRules,
+    ): number {
+        if (income <= rules.taperThreshold) {
+            return rules.amount;
+        }
+
+        const reduction = Math.floor((income - rules.taperThreshold) * rules.taperRate);
+        return Math.max(0, rules.amount - reduction);
+    }
+
+    private computeTaxBrackets(
+        taxableIncome: number,
+    ): { grossTax: number; bracketBreakdown: BracketAllocation[] } {
+        let tax = 0;
+        const bracketBreakdown: BracketAllocation[] = [];
+
+        for (let index = 0; index < this._rules.taxBrackets.length; index++) {
+            const bracket = this._rules.taxBrackets[index];
+
+            if (taxableIncome <= bracket.from) {
+                bracketBreakdown.push({
+                    bracketIndex: index,
+                    bracketName: `Bracket ${index + 1}`,
+                    from: bracket.from,
+                    to: bracket.to ?? null,
+                    rate: bracket.rate,
+                    amountInBracket: 0,
+                    taxOnAmount: 0,
+                });
+                break;
+            }
+
+            const upper = bracket.to ?? taxableIncome;
+            const taxableAmount = Math.min(upper, taxableIncome) - bracket.from;
+
+            if (taxableAmount > 0) {
+                const taxOnAmount = taxableAmount * bracket.rate;
+                tax += taxOnAmount;
+                bracketBreakdown.push({
+                    bracketIndex: index,
+                    bracketName: `Bracket ${index + 1}`,
+                    from: bracket.from,
+                    to: bracket.to ?? null,
+                    rate: bracket.rate,
+                    amountInBracket: taxableAmount,
+                    taxOnAmount,
+                });
+            } else {
+                bracketBreakdown.push({
+                    bracketIndex: index,
+                    bracketName: `Bracket ${index + 1}`,
+                    from: bracket.from,
+                    to: bracket.to ?? null,
+                    rate: bracket.rate,
+                    amountInBracket: 0,
+                    taxOnAmount: 0,
+                });
+            }
+        }
+
+        return { grossTax: tax, bracketBreakdown };
+    }
+
+    private computeNationalInsurance(
+        income: number,
+        rules: NationalInsuranceRules,
+    ): number {
+        if (income <= rules.primaryThreshold) {
+            return 0;
+        }
+
+        if (income <= rules.upperEarningsLimit) {
+            return (income - rules.primaryThreshold) * rules.mainRate;
+        }
+
+        const mainBand = (rules.upperEarningsLimit - rules.primaryThreshold) * rules.mainRate;
+        const upperBand = (income - rules.upperEarningsLimit) * rules.upperRate;
+        return mainBand + upperBand;
+    }
+
+    private round(value: number, decimals = 2): number {
+        return Number(value.toFixed(decimals));
+    }
+}

package/src/income-tax/uk/domain/types.ts

@@ -0,0 +1,31 @@
+import { BracketAllocation, TaxBracket } from "../../domain/types";
+
+export interface IncomeTaxRules {
+    taxBrackets: TaxBracket[];
+    personalAllowance: PersonalAllowanceRules;
+    nationalInsurance: NationalInsuranceRules;
+}
+
+export interface PersonalAllowanceRules {
+    amount: number;
+    taperThreshold: number;
+    taperRate: number;
+}
+
+export interface NationalInsuranceRules {
+    primaryThreshold: number;
+    upperEarningsLimit: number;
+    mainRate: number;
+    upperRate: number;
+}
+
+export interface ComputedIncomeTaxValues {
+    grossIncome: number;
+    incomeTax: number;
+    nationalInsurance: number;
+    personalAllowance: number;
+    totalDeductions: number;
+    netIncome: number;
+    effectiveTaxRate: number;
+    taxBracketBreakdown: BracketAllocation[];
+}

package/src/index.ts

@@ -81,5 +81,26 @@ export {
     Result as AustraliaCorporateTaxResult,
 } from './corporate/australia/domain/types';
 
+// United Kingdom
+export { UKIncomeTaxServiceImpl as UKIncomeTaxService } from './income-tax/uk/UKIncomeTaxServiceImpl';
+export {
+    ComputedIncomeTaxValues as UKComputedIncomeTaxValues,
+    IncomeTaxRules as UKIncomeTaxRules,
+} from './income-tax/uk/domain/types';
+
+export { UKCorporateTaxServiceImpl as UKCorporateTaxService } from './corporate/uk/UKCorporateTaxServiceImpl';
+export {
+    Input as UKCorporateTaxInput,
+    Rules as UKCorporateTaxRules,
+    Result as UKCorporateTaxResult,
+} from './corporate/uk/domain/types';
+
+export { UKMortgageServiceImpl as UKMortgageService } from './mortgage/uk/UKMortgageServiceImpl';
+export {
+    MortgageRules as UKMortgageRules,
+    MortgageInput as UKMortgageInput,
+    MortgageOutput as UKMortgageOutput,
+} from './mortgage/uk/domain/types';
+
 export { IncomeTaxCalculatorSchema } from './income-tax/domain/types';
 export * from './income-tax/domain/types';

package/src/mortgage/uk/UKMortgageService.ts

@@ -0,0 +1,5 @@
+import { MortgageInput, MortgageOutput, MortgageRules } from "./domain/types";
+
+export interface UKMortgageService {
+    calculate(input: MortgageInput, rules: MortgageRules): MortgageOutput;
+}

package/src/mortgage/uk/UKMortgageServiceImpl.ts

@@ -0,0 +1,140 @@
+import { UKMortgageService } from "./UKMortgageService";
+import {
+    AmortizationScheduleItem,
+    MortgageInput,
+    MortgageOutput,
+    MortgageRules,
+    StampDutyBracket,
+} from "./domain/types";
+
+export class UKMortgageServiceImpl implements UKMortgageService {
+
+    public calculate(input: MortgageInput, rules: MortgageRules): MortgageOutput {
+        const loanAmount = input.propertyPrice - input.downPayment;
+
+        if (loanAmount <= 0) {
+            throw new Error('Invalid loan amount: down payment must be less than property price');
+        }
+
+        const totalPayments = input.amortizationYears * 12;
+        const monthlyRate = (input.annualInterestRate / 100) / 12;
+
+        const monthlyPayment = this.calculatePayment(loanAmount, monthlyRate, totalPayments);
+        const totalPaid = monthlyPayment * totalPayments;
+        const totalInterestPaid = totalPaid - loanAmount;
+
+        const stampDuty = this.calculateStampDuty(input, rules);
+
+        const amortizationSchedule = this.calculateAmortizationSchedule(
+            loanAmount,
+            monthlyRate,
+            monthlyPayment,
+            totalPayments,
+            input.amortizationYears,
+        );
+
+        return {
+            loanAmount,
+            totalMortgage: loanAmount,
+            monthlyPayment,
+            totalInterestPaid,
+            totalPaid,
+            stampDuty,
+            amortizationSchedule,
+            otherFees: {
+                notaryFees: {
+                    value: stampDuty,
+                    label: 'STAMP_DUTY',
+                },
+                bankFees: {
+                    value: 0,
+                    label: 'BANK_FEES',
+                },
+                monthlyInsuranceFees: {
+                    value: 0,
+                    label: 'MONTHLY_INSURANCE_FEES',
+                },
+            },
+        };
+    }
+
+    private calculateStampDuty(input: MortgageInput, rules: MortgageRules): number {
+        const { propertyPrice, isFirstTimeBuyer } = input;
+        const { firstTimeBuyer, standardBrackets } = rules.stampDuty;
+
+        const useFirstTimeBuyerRules =
+            isFirstTimeBuyer && propertyPrice <= firstTimeBuyer.maxEligiblePropertyPrice;
+
+        const brackets = useFirstTimeBuyerRules ? firstTimeBuyer.brackets : standardBrackets;
+
+        return this.applyStampDutyBrackets(propertyPrice, brackets);
+    }
+
+    private applyStampDutyBrackets(propertyPrice: number, brackets: StampDutyBracket[]): number {
+        let duty = 0;
+        let previousLimit = 0;
+
+        for (const bracket of brackets) {
+            if (bracket.upTo !== undefined && propertyPrice > previousLimit) {
+                const taxable = Math.min(propertyPrice, bracket.upTo) - previousLimit;
+                duty += taxable * bracket.rate;
+                previousLimit = bracket.upTo;
+            }
+
+            if (bracket.above !== undefined && propertyPrice > bracket.above) {
+                duty += (propertyPrice - bracket.above) * bracket.rate;
+                break;
+            }
+        }
+
+        return duty;
+    }
+
+    private calculateAmortizationSchedule(
+        principal: number,
+        monthlyRate: number,
+        monthlyPayment: number,
+        totalPayments: number,
+        amortizationYears: number,
+    ): AmortizationScheduleItem[] {
+        const schedule: AmortizationScheduleItem[] = [];
+        let balance = principal;
+
+        for (let year = 1; year <= amortizationYears; year++) {
+            let yearlyPrincipal = 0;
+            let yearlyInterest = 0;
+
+            const paymentsInYear = Math.min(12, totalPayments - (year - 1) * 12);
+
+            for (let payment = 1; payment <= paymentsInYear; payment++) {
+                const interestPayment = balance * monthlyRate;
+                const principalPayment = monthlyPayment - interestPayment;
+
+                yearlyInterest += interestPayment;
+                yearlyPrincipal += principalPayment;
+                balance -= principalPayment;
+            }
+
+            schedule.push({
+                year,
+                principal: yearlyPrincipal,
+                interest: yearlyInterest,
+                balance: Math.max(0, balance),
+            });
+
+            if (balance <= 0) break;
+        }
+
+        return schedule;
+    }
+
+    private calculatePayment(principal: number, rate: number, periods: number): number {
+        if (rate === 0) {
+            return principal / periods;
+        }
+
+        return principal *
+            (rate * Math.pow(1 + rate, periods)) /
+            (Math.pow(1 + rate, periods) - 1);
+    }
+}

package/src/mortgage/uk/domain/types.ts

@@ -0,0 +1,58 @@
+import { OtherFees } from "../../domain/types";
+
+export interface MortgageRules {
+    loanConstraints: LoanConstraints;
+    interest: InterestRules;
+    stampDuty: StampDutyRules;
+}
+
+export interface LoanConstraints {
+    maxLtvPercent: number;
+    maxAmortizationYears: number;
+}
+
+export interface InterestRules {
+    compounding: 'MONTHLY';
+}
+
+export interface StampDutyBracket {
+    upTo?: number;
+    above?: number;
+    rate: number;
+}
+
+export interface StampDutyRules {
+    standardBrackets: StampDutyBracket[];
+    firstTimeBuyer: FirstTimeBuyerStampDuty;
+}
+
+export interface FirstTimeBuyerStampDuty {
+    brackets: StampDutyBracket[];
+    maxEligiblePropertyPrice: number;
+}
+
+export interface AmortizationScheduleItem {
+    year: number;
+    principal: number;
+    interest: number;
+    balance: number;
+}
+
+export interface MortgageInput {
+    propertyPrice: number;
+    downPayment: number;
+    annualInterestRate: number;
+    amortizationYears: number;
+    isFirstTimeBuyer: boolean;
+}
+
+export interface MortgageOutput {
+    loanAmount: number;
+    totalMortgage: number;
+    monthlyPayment: number;
+    totalInterestPaid: number;
+    totalPaid: number;
+    stampDuty: number;
+    amortizationSchedule: AmortizationScheduleItem[];
+    otherFees: OtherFees;
+}

package/test/australia-income-tax.test.ts

@@ -31,7 +31,7 @@ const australiaRules: IncomeTaxRules = {
 
 describe('AustraliaIncomeTaxServiceImpl', () => {
     it('returns zero tax for income below the tax-free threshold', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(18200, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(18200, australiaRules, true, false);
         const result = service.calculateNetIncome();
 
         expect(result.incomeTax).toBe(0);
@@ -40,7 +40,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('correctly calculates income tax for $60,000 income', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(60000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(60000, australiaRules, true, false);
         const result = service.calculateNetIncome();
 
         // Bracket 1: 0 → 18200 @ 0% = 0
@@ -54,7 +54,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('applies the Low Income Tax Offset for low incomes', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(30000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(30000, australiaRules, true, false);
         const result = service.calculateNetIncome();
 
         // Bracket 2: 18200 → 30000 @ 19% = 2242
@@ -65,7 +65,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('partially phases out LITO between $37,500 and $45,000', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(40000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(40000, australiaRules, true, false);
         const result = service.calculateNetIncome();
 
         // Gross tax: 18200→40000 @ 19% = 3382
@@ -74,7 +74,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('applies Medicare Levy correctly', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(60000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(60000, australiaRules, true, true);
         const result = service.calculateNetIncome();
 
         // Medicare Levy: 60000 * 2% = 1200
@@ -83,7 +83,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
 
     it('applies shading-in Medicare Levy for income in the shading-in range', () => {
         const income = 28000;
-        const service = new AustraliaIncomeTaxServiceImpl(income, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(income, australiaRules, true, true);
         const result = service.calculateNetIncome();
 
         // income (28000) > shadingInThreshold (26000), < fullLevyThreshold (32500)
@@ -92,14 +92,14 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('returns zero Medicare Levy below shading-in threshold', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(25000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(25000, australiaRules, true, true);
         const result = service.calculateNetIncome();
 
         expect(result.medicareLevy).toBe(0);
     });
 
     it('calculates high income tax correctly', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(200000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(200000, australiaRules, true, true);
         const result = service.calculateNetIncome();
 
         // Bracket 1: 0→18200 @ 0% = 0
@@ -115,7 +115,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('net income equals gross income minus total deductions', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(80000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(80000, australiaRules, true, true);
         const result = service.calculateNetIncome();
 
         expect(result.netIncome).toBeCloseTo(
@@ -125,7 +125,7 @@ describe('AustraliaIncomeTaxServiceImpl', () => {
     });
 
     it('effective tax rate is income tax divided by gross income', () => {
-        const service = new AustraliaIncomeTaxServiceImpl(100000, australiaRules);
+        const service = new AustraliaIncomeTaxServiceImpl(100000, australiaRules, true, false);
         const result = service.calculateNetIncome();
 
         expect(result.effectiveTaxRate).toBeCloseTo(result.incomeTax / result.grossIncome, 4);