@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.
- package/README.md +66 -16
- package/dist/afc-band.d.ts +33 -0
- package/dist/afc-band.js +33 -0
- package/dist/afc-band.js.map +1 -0
- package/dist/afc-scales.d.ts +67 -0
- package/dist/afc-scales.js +238 -0
- package/dist/afc-scales.js.map +1 -0
- package/dist/allowances.d.ts +91 -0
- package/dist/allowances.js +180 -0
- package/dist/allowances.js.map +1 -0
- package/dist/award.d.ts +175 -36
- package/dist/award.js +370 -47
- package/dist/award.js.map +1 -1
- package/dist/bands.d.ts +34 -12
- package/dist/bands.js +26 -9
- package/dist/bands.js.map +1 -1
- package/dist/circulars/afc-shapes.d.ts +101 -0
- package/dist/circulars/afc-shapes.js +18 -0
- package/dist/circulars/afc-shapes.js.map +1 -0
- package/dist/circulars/{england-md-1-2026r.d.ts → england-md-1-2026-r2.d.ts} +198 -32
- package/dist/circulars/{england-md-1-2026r.js → england-md-1-2026-r2.js} +142 -76
- package/dist/circulars/england-md-1-2026-r2.js.map +1 -0
- package/dist/circulars/ni-hsc-afc-06-2025.d.ts +63 -0
- package/dist/circulars/ni-hsc-afc-06-2025.js +100 -0
- package/dist/circulars/ni-hsc-afc-06-2025.js.map +1 -0
- package/dist/circulars/ni-hsc-tc8-05-2025.d.ts +1 -1
- package/dist/circulars/ni-hsc-tc8-05-2025.js +1 -1
- package/dist/circulars/scotland-pcs-afc-2026-01.d.ts +82 -0
- package/dist/circulars/scotland-pcs-afc-2026-01.js +208 -0
- package/dist/circulars/scotland-pcs-afc-2026-01.js.map +1 -0
- package/dist/circulars/scotland-pcs-dd-2025-01.d.ts +1 -1
- package/dist/circulars/scotland-pcs-dd-2025-01.js +12 -4
- package/dist/circulars/scotland-pcs-dd-2025-01.js.map +1 -1
- package/dist/circulars/scotland-pcs-dd-2026-01.d.ts +2 -2
- package/dist/circulars/scotland-pcs-dd-2026-01.js +2 -2
- package/dist/circulars/scotland-pcs-dd-2026-02.d.ts +79 -0
- package/dist/circulars/scotland-pcs-dd-2026-02.js +185 -0
- package/dist/circulars/scotland-pcs-dd-2026-02.js.map +1 -0
- package/dist/circulars/wales-afc-w-02-2025.d.ts +53 -0
- package/dist/circulars/wales-afc-w-02-2025.js +85 -0
- package/dist/circulars/wales-afc-w-02-2025.js.map +1 -0
- package/dist/circulars/wales-afc-w-02-2026.d.ts +48 -0
- package/dist/circulars/wales-afc-w-02-2026.js +91 -0
- package/dist/circulars/wales-afc-w-02-2026.js.map +1 -0
- package/dist/circulars/wales-mdw-01-2025.d.ts +1 -1
- package/dist/circulars/wales-mdw-01-2025.js +1 -1
- package/dist/circulars/wales-mdw-01-2026.d.ts +1 -1
- package/dist/circulars/wales-mdw-01-2026.js +1 -1
- package/dist/dental-scales.d.ts +4 -4
- package/dist/dental-scales.js +30 -20
- package/dist/dental-scales.js.map +1 -1
- package/dist/document-source.d.ts +141 -0
- package/dist/document-source.js +80 -0
- package/dist/document-source.js.map +1 -0
- package/dist/errors.d.ts +31 -5
- package/dist/errors.js +32 -2
- package/dist/errors.js.map +1 -1
- package/dist/format.d.ts +2 -2
- package/dist/format.js.map +1 -1
- package/dist/gad/erf-2023-06-30.d.ts +1 -1
- package/dist/gad/erf-2023-06-30.js +2 -1
- package/dist/gad/erf-2023-06-30.js.map +1 -1
- package/dist/gad/factor-table.d.ts +2 -1
- package/dist/gad/factor-table.js.map +1 -1
- package/dist/gad/lrf-2023-06-30.d.ts +1 -1
- package/dist/gad/lrf-2023-06-30.js +2 -1
- package/dist/gad/lrf-2023-06-30.js.map +1 -1
- package/dist/hcas.d.ts +10 -14
- package/dist/hcas.js +13 -20
- package/dist/hcas.js.map +1 -1
- package/dist/index.d.ts +17 -9
- package/dist/index.js +17 -8
- package/dist/index.js.map +1 -1
- package/dist/iso-date.d.ts +87 -0
- package/dist/iso-date.js +97 -0
- package/dist/iso-date.js.map +1 -0
- package/dist/medical-scales.d.ts +19 -4
- package/dist/medical-scales.js +77 -20
- package/dist/medical-scales.js.map +1 -1
- package/dist/pension.d.ts +30 -0
- package/dist/pension.js +128 -8
- package/dist/pension.js.map +1 -1
- package/dist/post.d.ts +87 -2
- package/dist/post.js +112 -2
- package/dist/post.js.map +1 -1
- package/dist/regions.d.ts +1 -1
- package/dist/regions.js +1 -1
- package/dist/resolver.d.ts +57 -7
- package/dist/resolver.js +77 -25
- package/dist/resolver.js.map +1 -1
- package/dist/scale-point.d.ts +13 -4
- package/dist/scale-tables.d.ts +57 -10
- package/dist/scale-tables.js +58 -9
- package/dist/scale-tables.js.map +1 -1
- package/dist/scales.d.ts +169 -44
- package/dist/scales.js +462 -226
- package/dist/scales.js.map +1 -1
- package/dist/sources.d.ts +183 -0
- package/dist/sources.js +375 -0
- package/dist/sources.js.map +1 -0
- package/package.json +24 -6
- 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
|
|
5
|
+
* descriptions); presentation copy is a consumer concern.
|
|
6
6
|
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
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,
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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<
|
|
76
|
+
export declare const NLW_HOURLY: Partial<Record<YearLabel, number>>;
|
|
58
77
|
/**
|
|
59
|
-
* Standard AfC working hours per year (37.5 ×
|
|
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
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
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
|
|
73
|
-
export declare
|
|
74
|
-
/**
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
* year
|
|
82
|
-
*
|
|
83
|
-
|
|
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;
|