@casomoltd/nhs-pay 0.5.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +134 -3
  2. package/dist/award.d.ts +32 -0
  3. package/dist/award.js +59 -0
  4. package/dist/award.js.map +1 -0
  5. package/dist/bands.d.ts +8 -8
  6. package/dist/bands.js +6 -8
  7. package/dist/bands.js.map +1 -1
  8. package/dist/circulars/england-md-1-2026r.d.ts +257 -0
  9. package/dist/circulars/england-md-1-2026r.js +302 -0
  10. package/dist/circulars/england-md-1-2026r.js.map +1 -0
  11. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +166 -0
  12. package/dist/circulars/ni-hsc-tc8-05-2025.js +249 -0
  13. package/dist/circulars/ni-hsc-tc8-05-2025.js.map +1 -0
  14. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +34 -0
  15. package/dist/circulars/scotland-pcs-dd-2026-01.js +96 -0
  16. package/dist/circulars/scotland-pcs-dd-2026-01.js.map +1 -0
  17. package/dist/circulars/wales-mdw-01-2025.d.ts +130 -0
  18. package/dist/circulars/wales-mdw-01-2025.js +221 -0
  19. package/dist/circulars/wales-mdw-01-2025.js.map +1 -0
  20. package/dist/dental-scales.d.ts +44 -0
  21. package/dist/dental-scales.js +103 -0
  22. package/dist/dental-scales.js.map +1 -0
  23. package/dist/errors.d.ts +33 -5
  24. package/dist/errors.js +44 -6
  25. package/dist/errors.js.map +1 -1
  26. package/dist/index.d.ts +14 -7
  27. package/dist/index.js +8 -3
  28. package/dist/index.js.map +1 -1
  29. package/dist/medical-scales.d.ts +64 -0
  30. package/dist/medical-scales.js +153 -0
  31. package/dist/medical-scales.js.map +1 -0
  32. package/dist/pension.d.ts +18 -15
  33. package/dist/pension.js +99 -25
  34. package/dist/pension.js.map +1 -1
  35. package/dist/post.d.ts +78 -3
  36. package/dist/post.js +59 -6
  37. package/dist/post.js.map +1 -1
  38. package/dist/resolver.d.ts +17 -0
  39. package/dist/resolver.js +61 -0
  40. package/dist/resolver.js.map +1 -1
  41. package/dist/role.d.ts +25 -4
  42. package/dist/role.js +1 -2
  43. package/dist/role.js.map +1 -1
  44. package/dist/scale-point.d.ts +21 -0
  45. package/dist/scale-point.js +2 -0
  46. package/dist/scale-point.js.map +1 -0
  47. package/dist/scale-tables.d.ts +69 -0
  48. package/dist/scale-tables.js +98 -0
  49. package/dist/scale-tables.js.map +1 -0
  50. package/dist/scales.d.ts +2 -5
  51. package/dist/scales.js +1 -1
  52. package/dist/scales.js.map +1 -1
  53. package/dist/take-home.d.ts +36 -7
  54. package/dist/take-home.js +59 -13
  55. package/dist/take-home.js.map +1 -1
  56. package/package.json +2 -2
package/dist/take-home.js CHANGED
@@ -1,26 +1,72 @@
1
1
  /**
2
- * Pre-configured TakeHomePay for NHS AfC staff.
3
- * Uses NET pay arrangement (pension deducted before
4
- * tax) which matches the NHS Pension Scheme.
2
+ * Pre-configured TakeHomePay for NHS staff.
3
+ *
4
+ * The NHS Pension Scheme uses a NET PAY ARRANGEMENT: the member
5
+ * contribution is deducted from pay BEFORE income tax is calculated
6
+ * (so tax relief is automatic at the member's marginal rate), but is
7
+ * NOT deducted before National Insurance — NI is assessed on the full
8
+ * gross, including the pension contribution. Getting this wrong (also
9
+ * reducing NI by the pension) overstates take-home; the invariant in
10
+ * {@link nhsTakeHome} guards against it.
11
+ *
12
+ * Sources:
13
+ * - Net pay arrangement — HMRC PTM044230:
14
+ * https://www.gov.uk/hmrc-internal-manuals/pensions-tax-manual/ptm044230
15
+ * - Deducted before tax, not before NI — LITRG:
16
+ * https://www.litrg.org.uk/pensions/paying-pensions/tax-relief-pension-contributions/how-tax-relief-given-pension-contributions
5
17
  */
6
- import { TakeHomePay, GrossAnnual, PensionBasis, PensionPercent, TAX_REGIONS, } from '@casomoltd/paye-calc';
7
- import { AFC_CURRENT_YEAR } from './bands.js';
18
+ import { TakeHomePay, GrossAnnual, PensionBasis, PensionPercent, } from '@casomoltd/paye-calc';
8
19
  import { yearlyAccrual } from './pension-projection.js';
20
+ import { invariant } from './errors.js';
9
21
  /**
10
- * @param salary Gross annual salary
11
- * @param pensionRate Decimal fraction (e.g. 0.098)
22
+ * @param salary Gross annual pay assessed for tax/NI (already
23
+ * FTE-adjusted and net of any salary sacrifice)
24
+ * @param pensionRate Decimal fraction (e.g. 0.098); 0 = opted out
25
+ * @param taxYear Which pay/tax year — required, no silent default
26
+ * @param taxRegion Which tax region — required; omitting it would
27
+ * silently tax a Scottish member at rUK rates
28
+ * @param options Student loans / tax-code override
12
29
  */
13
- export function nhsTakeHome(salary, pensionRate, taxYear = AFC_CURRENT_YEAR, taxRegion = TAX_REGIONS.rUK) {
30
+ export function nhsTakeHome(salary, pensionRate, taxYear, taxRegion, options = {}) {
14
31
  const thp = new TakeHomePay(taxYear, taxRegion);
15
32
  thp.setSalary(GrossAnnual(salary));
16
- thp.setPensionBasis(PensionBasis.Employer);
17
- thp.setPension(PensionPercent(pensionRate * 100));
18
- // DB pension input (16 × accrual) drives the annual-allowance
19
- // taper; without it adjusted income omits the scheme accrual and
20
- // the taper never bites for high earners. Skip when opted out.
33
+ // A positive rate is scheme membership (NET arrangement); zero is an
34
+ // opted-out member, so there's no pension basis at all — never a 0%
35
+ // Employer contribution.
21
36
  if (pensionRate > 0) {
37
+ thp.setPensionBasis(PensionBasis.Employer);
38
+ thp.setPension(PensionPercent(pensionRate * 100));
39
+ // The tapered annual allowance is driven by the DB pension INPUT
40
+ // amount (growth in CARE benefits ≈ 16 × annual accrual), not the
41
+ // contribution paid; without it, adjusted income omits the scheme
42
+ // accrual and the taper never bites for high earners.
43
+ // Source: HMRC PTM044230 (pension input amount for DB schemes).
22
44
  thp.setDbAnnualAccrual(yearlyAccrual(salary));
23
45
  }
46
+ else {
47
+ thp.setPensionBasis(PensionBasis.None);
48
+ }
49
+ // setStudentLoanPlans wants a mutable Set; the VO holds a
50
+ // ReadonlySet, so copy it at the boundary.
51
+ if (options.studentLoans && options.studentLoans.size > 0) {
52
+ thp.setStudentLoanPlans(new Set(options.studentLoans));
53
+ }
54
+ if (options.taxCode) {
55
+ thp.setTaxCode(options.taxCode);
56
+ }
57
+ // Net-pay invariant: the member contribution reduces the tax base
58
+ // but MUST NOT reduce NI-able pay (NI is on the full gross). If NI
59
+ // ever changes when the pension is applied, the pension basis is
60
+ // wrong or paye-calc's model changed — fail loud here (this runs in
61
+ // every test and page) rather than silently overstating take-home.
62
+ if (pensionRate > 0) {
63
+ const niNoPension = new TakeHomePay(taxYear, taxRegion);
64
+ niNoPension.setSalary(GrossAnnual(salary));
65
+ invariant(thp.nationalInsurance === niNoPension.nationalInsurance, 'NHS pension is a net-pay arrangement: it must reduce income '
66
+ + 'tax but not National Insurance (NI is assessed on full '
67
+ + 'gross). NI changed when the pension was applied. '
68
+ + 'See HMRC PTM044230.');
69
+ }
24
70
  return thp;
25
71
  }
26
72
  //# sourceMappingURL=take-home.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"take-home.js","sourceRoot":"","sources":["../src/take-home.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAC,gBAAgB,EAAC,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAC,MAAM,yBAAyB,CAAC;AAEtD;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,WAAmB,EACnB,UAAmB,gBAAgB,EACnC,YAAuB,WAAW,CAAC,GAAG;IAEtC,MAAM,GAAG,GAAG,IAAI,WAAW,CACzB,OAAO,EAAE,SAAS,CACnB,CAAC;IACF,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACnC,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,GAAG,CAAC,UAAU,CACZ,cAAc,CAAC,WAAW,GAAG,GAAG,CAAC,CAClC,CAAC;IACF,8DAA8D;IAC9D,iEAAiE;IACjE,+DAA+D;IAC/D,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,GAAG,CAAC,kBAAkB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
1
+ {"version":3,"file":"take-home.js","sourceRoot":"","sources":["../src/take-home.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAC,aAAa,EAAC,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAetC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,WAAmB,EACnB,OAAgB,EAChB,SAAoB,EACpB,UAA8B,EAAE;IAEhC,MAAM,GAAG,GAAG,IAAI,WAAW,CACzB,OAAO,EAAE,SAAS,CACnB,CAAC;IACF,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACnC,qEAAqE;IACrE,oEAAoE;IACpE,yBAAyB;IACzB,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC3C,GAAG,CAAC,UAAU,CACZ,cAAc,CAAC,WAAW,GAAG,GAAG,CAAC,CAClC,CAAC;QACF,iEAAiE;QACjE,kEAAkE;QAClE,kEAAkE;QAClE,sDAAsD;QACtD,gEAAgE;QAChE,GAAG,CAAC,kBAAkB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,0DAA0D;IAC1D,2CAA2C;IAC3C,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,mBAAmB,CACrB,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAC9B,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,iEAAiE;IACjE,oEAAoE;IACpE,mEAAmE;IACnE,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QACxD,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3C,SAAS,CACP,GAAG,CAAC,iBAAiB,KAAK,WAAW,CAAC,iBAAiB,EACvD,8DAA8D;cAC1D,yDAAyD;cACzD,mDAAmD;cACnD,qBAAqB,CAC1B,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@casomoltd/nhs-pay",
3
- "version": "0.5.0",
3
+ "version": "0.7.2",
4
4
  "description": "NHS Agenda for Change pay scales, pension tiers, regions, and take-home calculator",
5
5
  "homepage": "https://github.com/casomoltd/nhs-pay#readme",
6
6
  "bugs": "https://github.com/casomoltd/nhs-pay/issues",
@@ -56,7 +56,7 @@
56
56
  },
57
57
  "devDependencies": {
58
58
  "@casomoltd/paye-calc": "^0.5.11",
59
- "@casomoltd/tooling": "git+https://github.com/casomoltd/tooling.git#semver:^0.10.0",
59
+ "@casomoltd/tooling": "^0.20.0",
60
60
  "@commitlint/cli": "^20.0.0",
61
61
  "@types/node": "^25.5.0",
62
62
  "csv-parse": "^6.2.1",