Clarify documentation on national insurance function

[tboby]

calculateEmployeeNationalInsurance is documented as requiring taxableAnnualIncome, which isn't quite right. I'm not quite sure what to call it, and HMRC seem to careful avoid giving it a name, but it's more like the gross, cash, employment income?

I understand why SavingTool makes the salary sacrifice assumption to simplify things!

Thank you so much for this library; I've been using it for a personal finance tool that's slightly more tailored to me and it's really helpful :)

[sgb-io]

Hey, thanks for your interest in the library!

Hopefully the readme makes it clear that the scope of the library is (currently) limited to PAYE employees that pay Class 1 Category A NICs.

With this in mind (and avoiding lots of potential complexities like self employed, company director or non-Category A individuals), NICs are calculated using someone's annual (taxable) salary. The actual NICs rates are quoted weekly/monthly but this library simply calculates it on a 12 month basis.

Taxable income here essentially means PAYE employment income. Other forms of income are ignored. Open to suggestions if you think there is an obvious clarification or improvement to be made 🙂

Sources:

• https://www.gov.uk/national-insurance/how-much-you-pay
• https://www.gov.uk/national-insurance-rates-letters/category-letters

[tboby]

Oh, I absolutely understand limiting it to PAYE Class 1 Category A.

But for the simple case of:
£60k salary, 3% pension contributions (without sacrifice), student loan plan 1.
Which would be £58200 taxable income for income tax (and personal allowance?), but £60k employment income for student loan and NIC.

Perhaps the clearest example is just to show my usage, where I only get the "right" numbers if I pass the gross PAYE salary to a parameter called "taxableAnnualIncome". All four functions ask for taxableAnnualIncome, but they need to be given two different values in the simplest case.

let private calculateNetIncome grossCashEmploymentIncome taxableIncome studentLoanPlan =
    let personalAllowance =
        calculatePersonalAllowance {|
            taxableAnnualIncome = taxableIncome
            taxYear = None
        |}

    let incomeTax =
        calculateIncomeTax {|
            taxYear = None
            taxableAnnualIncome = taxableIncome
            personalAllowance = personalAllowance
        |}

    let nationalInsurance =
        calculateEmployeeNationalInsurance {|
            taxYear = None
            taxableAnnualIncome = grossCashEmploymentIncome
        |}

    let studentLoan =
        match studentLoanPlan with
        | 1 | 2 | 4 | 5 ->
            calculateStudentLoanRepayments {|
                taxYear = None
                taxableAnnualIncome = grossCashEmploymentIncome
                studentLoanPlanNo = studentLoanPlan
            |}
        | _ -> 0.0

    let totalDeductions =
        incomeTax.basicRateTax
        + incomeTax.higherRateTax
        + incomeTax.additionalRateTax
        + nationalInsurance
        + studentLoan

    let netIncome = taxableIncome - totalDeductions
    netIncome

So my tiny suggestion is just to rename the calculateEmployeeNationalInsurance and calculateStudentLoanRepayments parameters to make it clear it isn't the taxable income, it's the PAYE income.