@casomoltd/nhs-pay 0.15.1 → 0.16.0

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 (102) hide show
  1. package/README.md +66 -16
  2. package/dist/afc-band.d.ts +33 -0
  3. package/dist/afc-band.js +33 -0
  4. package/dist/afc-band.js.map +1 -0
  5. package/dist/afc-scales.d.ts +67 -0
  6. package/dist/afc-scales.js +238 -0
  7. package/dist/afc-scales.js.map +1 -0
  8. package/dist/allowances.d.ts +91 -0
  9. package/dist/allowances.js +180 -0
  10. package/dist/allowances.js.map +1 -0
  11. package/dist/award.d.ts +175 -36
  12. package/dist/award.js +370 -47
  13. package/dist/award.js.map +1 -1
  14. package/dist/bands.d.ts +34 -12
  15. package/dist/bands.js +26 -9
  16. package/dist/bands.js.map +1 -1
  17. package/dist/circulars/afc-shapes.d.ts +101 -0
  18. package/dist/circulars/afc-shapes.js +18 -0
  19. package/dist/circulars/afc-shapes.js.map +1 -0
  20. package/dist/circulars/{england-md-1-2026r.d.ts → england-md-1-2026-r2.d.ts} +198 -32
  21. package/dist/circulars/{england-md-1-2026r.js → england-md-1-2026-r2.js} +142 -76
  22. package/dist/circulars/england-md-1-2026-r2.js.map +1 -0
  23. package/dist/circulars/ni-hsc-afc-06-2025.d.ts +63 -0
  24. package/dist/circulars/ni-hsc-afc-06-2025.js +100 -0
  25. package/dist/circulars/ni-hsc-afc-06-2025.js.map +1 -0
  26. package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +1 -1
  27. package/dist/circulars/ni-hsc-tc8-05-2025.js +1 -1
  28. package/dist/circulars/scotland-pcs-afc-2026-01.d.ts +82 -0
  29. package/dist/circulars/scotland-pcs-afc-2026-01.js +208 -0
  30. package/dist/circulars/scotland-pcs-afc-2026-01.js.map +1 -0
  31. package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +1 -1
  32. package/dist/circulars/scotland-pcs-dd-2025-01.js +12 -4
  33. package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
  34. package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
  35. package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
  36. package/dist/circulars/scotland-pcs-dd-2026-02.d.ts +79 -0
  37. package/dist/circulars/scotland-pcs-dd-2026-02.js +185 -0
  38. package/dist/circulars/scotland-pcs-dd-2026-02.js.map +1 -0
  39. package/dist/circulars/wales-afc-w-02-2025.d.ts +53 -0
  40. package/dist/circulars/wales-afc-w-02-2025.js +85 -0
  41. package/dist/circulars/wales-afc-w-02-2025.js.map +1 -0
  42. package/dist/circulars/wales-afc-w-02-2026.d.ts +48 -0
  43. package/dist/circulars/wales-afc-w-02-2026.js +91 -0
  44. package/dist/circulars/wales-afc-w-02-2026.js.map +1 -0
  45. package/dist/circulars/wales-mdw-01-2025.d.ts +1 -1
  46. package/dist/circulars/wales-mdw-01-2025.js +1 -1
  47. package/dist/circulars/wales-mdw-01-2026.d.ts +1 -1
  48. package/dist/circulars/wales-mdw-01-2026.js +1 -1
  49. package/dist/dental-scales.d.ts +4 -4
  50. package/dist/dental-scales.js +30 -20
  51. package/dist/dental-scales.js.map +1 -1
  52. package/dist/document-source.d.ts +141 -0
  53. package/dist/document-source.js +80 -0
  54. package/dist/document-source.js.map +1 -0
  55. package/dist/errors.d.ts +31 -5
  56. package/dist/errors.js +32 -2
  57. package/dist/errors.js.map +1 -1
  58. package/dist/format.d.ts +2 -2
  59. package/dist/format.js.map +1 -1
  60. package/dist/gad/erf-2023-06-30.d.ts +1 -1
  61. package/dist/gad/erf-2023-06-30.js +2 -1
  62. package/dist/gad/erf-2023-06-30.js.map +1 -1
  63. package/dist/gad/factor-table.d.ts +2 -1
  64. package/dist/gad/factor-table.js.map +1 -1
  65. package/dist/gad/lrf-2023-06-30.d.ts +1 -1
  66. package/dist/gad/lrf-2023-06-30.js +2 -1
  67. package/dist/gad/lrf-2023-06-30.js.map +1 -1
  68. package/dist/hcas.d.ts +10 -14
  69. package/dist/hcas.js +13 -20
  70. package/dist/hcas.js.map +1 -1
  71. package/dist/index.d.ts +17 -9
  72. package/dist/index.js +17 -8
  73. package/dist/index.js.map +1 -1
  74. package/dist/iso-date.d.ts +87 -0
  75. package/dist/iso-date.js +97 -0
  76. package/dist/iso-date.js.map +1 -0
  77. package/dist/medical-scales.d.ts +19 -4
  78. package/dist/medical-scales.js +77 -20
  79. package/dist/medical-scales.js.map +1 -1
  80. package/dist/pension.d.ts +30 -0
  81. package/dist/pension.js +128 -8
  82. package/dist/pension.js.map +1 -1
  83. package/dist/post.d.ts +87 -2
  84. package/dist/post.js +112 -2
  85. package/dist/post.js.map +1 -1
  86. package/dist/regions.d.ts +1 -1
  87. package/dist/regions.js +1 -1
  88. package/dist/resolver.d.ts +57 -7
  89. package/dist/resolver.js +77 -25
  90. package/dist/resolver.js.map +1 -1
  91. package/dist/scale-point.d.ts +13 -4
  92. package/dist/scale-tables.d.ts +57 -10
  93. package/dist/scale-tables.js +58 -9
  94. package/dist/scale-tables.js.map +1 -1
  95. package/dist/scales.d.ts +169 -44
  96. package/dist/scales.js +462 -226
  97. package/dist/scales.js.map +1 -1
  98. package/dist/sources.d.ts +183 -0
  99. package/dist/sources.js +375 -0
  100. package/dist/sources.js.map +1 -0
  101. package/package.json +24 -6
  102. package/dist/circulars/england-md-1-2026r.js.map +0 -1
package/dist/scales.d.ts CHANGED
@@ -2,10 +2,26 @@
2
2
  * NHS Agenda for Change pay scales by tax year.
3
3
  *
4
4
  * Pure salary data — no metadata (labels, slugs, role
5
- * descriptions); presentation copy is a hub-site concern.
5
+ * descriptions); presentation copy is a consumer concern.
6
6
  *
7
- * Sources, by the names they carry in docs/source-archive.md,
8
- * which holds every publisher URL and archived copy:
7
+ * ── Two layers, and which nation is in which ──
8
+ *
9
+ * Scotland, Wales and Northern Ireland each publish an AfC pay
10
+ * CIRCULAR, so each is transcribed verbatim in `src/circulars/*` and
11
+ * translated to canonical points by `afc-scales.ts`. This module holds
12
+ * the result, not the transcription.
13
+ *
14
+ * **England is the exception, and a documented one.** It publishes no
15
+ * AfC circular — its scales are an NHS Employers web page plus a
16
+ * poster — so there is nothing to transcribe and its tables are
17
+ * authored here directly. The rule: *where the publisher issues a
18
+ * circular, transcribe it verbatim; where it publishes a web table,
19
+ * cite it and pin it with fixtures.* Do NOT invent a pseudo-circular
20
+ * file for England to make the shapes match.
21
+ *
22
+ * Sources for what is authored HERE, by the names they carry in
23
+ * docs/source-archive.md, which holds every publisher URL and
24
+ * archived copy:
9
25
  * - "NHS Employers — AfC pay scales 2025/26"
10
26
  * - "NHS Employers — AfC pay scales 2026/27" (note its hourly
11
27
  * table has printing errors; this file reads the ANNUAL
@@ -18,28 +34,31 @@
18
34
  * - Wales floor: "Wales, AFC(W) 01/2026 living wage"
19
35
  * - HCAS rates: "NHS Terms and Conditions of Service
20
36
  * Handbook, amendment 62" (#sa-41), Annex 9
21
- * - Scotland (both years): "NHS Scotland, AfC pay scales 2025-26
22
- * and 2026-27 (MSG)" — 2025-26 rates revised by
23
- * "Scotland, PCS(AFC)2026/01"; 2026-27 in its Annex B
37
+ *
38
+ * The other three nations' sources are cited in their own circular
39
+ * files, beside the data they justify — including the qualification
40
+ * that used to live in this header, that Scotland's MSG consolidated
41
+ * table prints superseded 4.25% rates and must not be read instead of
42
+ * the circular.
43
+ *
44
+ * POINT LABELS — one convention, all four nations. A point's label is
45
+ * the year of service in which a member first reaches it: increment 1
46
+ * is `Year 1`, and the top point takes a `+` because service continues
47
+ * past it. No publisher prints such a label; every one is our reading
48
+ * of an interval the publisher does print. For the three circular
49
+ * nations that reading is now DERIVED in `afc-scales.ts` from the
50
+ * transcribed interval, so a label and its interval cannot disagree.
51
+ * England's are authored here, from the same convention.
52
+ *
53
+ * Labels are lookup keys for `afcResolver.fromScalePoint`, so changing
54
+ * one is an API change, and the fixtures assert them.
24
55
  */
25
- import type { Nation, TaxYear } from '@casomoltd/paye-calc';
56
+ import type { Nation, PayYear, YearLabel } from '@casomoltd/paye-calc';
57
+ import type { DocumentSource } from './document-source.js';
26
58
  import type { ScalePoint } from './scale-point.js';
27
- export declare const AFC_BANDS: {
28
- readonly B2: "2";
29
- readonly B3: "3";
30
- readonly B4: "4";
31
- readonly B5: "5";
32
- readonly B6: "6";
33
- readonly B7: "7";
34
- readonly B8a: "8a";
35
- readonly B8b: "8b";
36
- readonly B8c: "8c";
37
- readonly B8d: "8d";
38
- readonly B9: "9";
39
- };
40
- export type AfcBandId = (typeof AFC_BANDS)[keyof typeof AFC_BANDS];
41
- /** Ordered band IDs — use for iteration. */
42
- export declare const AFC_BAND_IDS: AfcBandId[];
59
+ import type { AfcBandId } from './afc-band.js';
60
+ export { AFC_BANDS, AFC_BAND_IDS } from './afc-band.js';
61
+ export type { AfcBandId } from './afc-band.js';
43
62
  export interface HcasZone {
44
63
  rate: number;
45
64
  min: number;
@@ -54,9 +73,15 @@ interface AfcScaleYear {
54
73
  hcas: HcasZones;
55
74
  scales: Record<AfcBandId, ScalePoint[]>;
56
75
  }
57
- export declare const NLW_HOURLY: Partial<Record<TaxYear, number>>;
76
+ export declare const NLW_HOURLY: Partial<Record<YearLabel, number>>;
58
77
  /**
59
- * Standard AfC working hours per year (37.5 × 52).
78
+ * Standard AfC working hours per year (37.5 × 365/7 ≈ 1,955.4).
79
+ *
80
+ * The week-year is 365/7, not 52, matching every publisher that prints
81
+ * an hourly rate beside an annual salary, and matching NHS Employers'
82
+ * own ~1,955.4-hour year. A 52-week year gives 1,950, which no
83
+ * publisher prints.
84
+ *
60
85
  * @deprecated Use `hoursPerYear(config)` from
61
86
  * paye-calc for region-aware hours. This constant
62
87
  * assumes rUK 37.5h weeks and is wrong for Scotland
@@ -65,23 +90,123 @@ export declare const NLW_HOURLY: Partial<Record<TaxYear, number>>;
65
90
  export declare const AFC_HOURS_PER_YEAR: number;
66
91
  /**
67
92
  * Annualise an hourly rate at given weekly hours.
68
- * Defaults to 37.5 (rUK standard) for backward
69
- * compatibility. Pass config.standardWeeklyHours
70
- * for region-aware conversion.
93
+ *
94
+ * `weeklyHours` is required: the standard week is the
95
+ * axis that varies by nation (Scotland's AfC week is 37
96
+ * hours to 2025-26 and 36 from 2026-27, rUK's 37.5), so
97
+ * defaulting it would silently return an rUK answer for a
98
+ * Scottish rate. Pass `config.standardWeeklyHours`.
99
+ *
100
+ * The week-year is 365/7, the same basis `hoursPerYear`
101
+ * uses — the two are inverses of one another and a
102
+ * divisor that disagreed would round-trip a salary to a
103
+ * different number.
104
+ */
105
+ export declare function annualiseHourly(hourly: number, weeklyHours: number): number;
106
+ /** The Welsh living-wage floor for a year, as its pay
107
+ * letter states it. */
108
+ export interface WalesLivingWage {
109
+ /** The floor applied to low spine points. */
110
+ readonly annual: number;
111
+ /** The Living Wage Foundation rate the floor is set
112
+ * against — quotable, never a divisor. */
113
+ readonly hourly: number;
114
+ }
115
+ export declare const WALES_LIVING_WAGE: Partial<Record<YearLabel, WalesLivingWage>>;
116
+ /** The circular or page that publishes a nation's AfC scales for a
117
+ * year. Throws for a combination that has no published scale, in step
118
+ * with {@link getScalesForYear} — a scale we cannot cite is a scale we
119
+ * should not be serving. */
120
+ export declare function afcScaleSource(year: PayYear, nation: Nation): DocumentSource;
121
+ /** PAY years a given nation publishes AfC scales for, oldest
122
+ * first. Nations do not move in lockstep — a year one has
123
+ * published may be outstanding for another — so a caller
124
+ * resolving figures for a nation must ask for that nation's
125
+ * years rather than assuming England's.
126
+ *
127
+ * Pay years, not tax years: this answers "which scale can I ask
128
+ * for", never "which tax rules apply". Northern Ireland publishes
129
+ * one pay year while every nation shares the same tax year. */
130
+ export declare function afcPayYears(nation: Nation): PayYear[];
131
+ /**
132
+ * The most recent year a nation has actually published AfC scales for.
133
+ *
134
+ * Nations do not move together. Northern Ireland has issued no 2026-27
135
+ * pay circular — its 3.3% is announced, unfunded and undated — so its
136
+ * latest published year is 2025-26 while the other three are on
137
+ * 2026-27. A consumer that asks for a site-wide "current year" gets
138
+ * `ScaleUnavailable` there, which is correct but is not an answer; this
139
+ * is the answer.
140
+ *
141
+ * Lives here rather than in a consumer because it is a fact about what
142
+ * this library holds. A consumer deriving it would be re-computing,
143
+ * from the outside, something only these tables know.
144
+ */
145
+ /**
146
+ * How far a nation's newest published pay scales sit from the tax year
147
+ * in force. Positive means the pay scales are BEHIND.
148
+ *
149
+ * ## The domain rule this exists to state
150
+ *
151
+ * A person's salary comes from an Agenda for Change round; the tax, NI
152
+ * and pension tiers applied to it come from the tax year they are
153
+ * being paid IN. Those are different facts, and they normally name the
154
+ * same year — which is why one value was long used for both, and why
155
+ * the day they diverge nothing complains.
156
+ *
157
+ * They diverge in exactly one way. An AfC round is agreed and
158
+ * implemented by each nation separately, and a nation whose award is
159
+ * not yet funded keeps paying last year's scales into this tax year.
160
+ * Northern Ireland is doing that now. Tax never waits: the thresholds
161
+ * change on 6 April whatever the employer has settled.
162
+ *
163
+ * So the legitimate values are:
164
+ *
165
+ * | lag | meaning |
166
+ * |---|---|
167
+ * | `0` | the award is implemented; pay year and tax year agree |
168
+ * | `1` | the award for this year is not yet in payment |
169
+ * | `-1` | next year's circular is out but its tax year has not begun |
170
+ *
171
+ * Anything else is a defect in THIS library's data, not a fact about
172
+ * the world: a lag of 2 means a whole round was never transcribed.
173
+ * {@link assertPayYearLagIsSane} is where that is enforced.
174
+ *
175
+ * The one thing this CANNOT catch is the mistake it was written after:
176
+ * passing a pay year where a tax year was wanted. Both are `TaxYear`,
177
+ * so both type-check, and the values here would look perfectly legal.
178
+ * Only distinct types would stop that.
179
+ */
180
+ export declare function payYearLag(nation: Nation): number;
181
+ /**
182
+ * True while a nation is still paying an older round than the tax year
183
+ * in force — its award is announced or awaited, but not in payment.
184
+ *
185
+ * The domain question ("is this nation behind?") rather than a
186
+ * comparison against some particular year, so a consumer cannot get
187
+ * the comparison subtly wrong: testing against a fixed year answers
188
+ * "is it exactly 2025-26" and quietly says no for a nation two rounds
189
+ * behind, which is the case that most needs saying yes.
190
+ */
191
+ export declare function isAwaitingPayAward(nation: Nation): boolean;
192
+ /**
193
+ * Fail loudly if any nation's pay scales have drifted further from the
194
+ * tax year than the domain allows. See {@link payYearLag}.
195
+ *
196
+ * A function rather than a module-scope check: this library is
197
+ * published, and a throw at import time would take down every consumer
198
+ * over a data problem they cannot fix. It runs in this repo's tests,
199
+ * which is where a transcription gap should surface.
71
200
  */
72
- export declare function annualiseHourly(hourly: number, weeklyHours?: number): number;
73
- export declare const WALES_LW_FLOOR: Partial<Record<TaxYear, number>>;
74
- /** Apply the Wales living wage floor to a salary.
75
- * Returns the original salary if no floor exists
76
- * for the given tax year. */
77
- export declare function applyWalesFloor(salary: number, year: TaxYear): number;
78
- /** Tax years that have AFC scale data. */
79
- export declare const AFC_TAX_YEARS: TaxYear[];
80
- /** Resolve the published, nation-adjusted scale table for a
81
- * year — the single place a nation modifies the base scale:
82
- * Scotland swaps to its own family, Wales floors the
83
- * England/NI base, England/NI use the base as-is. Throws
84
- * {@link ScaleUnavailable} for an unpublished year rather
85
- * than silently substituting another year's figures. */
86
- export declare function getScalesForYear(year: TaxYear, nation: Nation): AfcScaleYear;
87
- export {};
201
+ export declare function assertPayYearLagIsSane(): void;
202
+ export declare function latestAfcYear(nation: Nation): PayYear;
203
+ /** Resolve a nation's published scale table for a year.
204
+ * Every figure returned is transcribed from that nation's
205
+ * own instrument. Where two nations' circulars print the
206
+ * same numbers the tables share an object literal for
207
+ * brevity, and each nation's fixture rows pin its values
208
+ * against its OWN document, so a divergence fails rather
209
+ * than propagating. Throws {@link ScaleUnavailable} for a
210
+ * year that nation has not published, rather than silently
211
+ * substituting another year's or nation's figures. */
212
+ export declare function getScalesForYear(year: PayYear, nation: Nation): AfcScaleYear;