@casomoltd/nhs-pay 0.29.0 → 0.31.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 (80) hide show
  1. package/README.md +78 -249
  2. package/dist/bands.d.ts +9 -1
  3. package/dist/bands.js +20 -0
  4. package/dist/bands.js.map +1 -1
  5. package/dist/dates.d.ts +3 -0
  6. package/dist/dates.js +7 -2
  7. package/dist/dates.js.map +1 -1
  8. package/dist/document-source.d.ts +16 -0
  9. package/dist/document-source.js +3 -1
  10. package/dist/document-source.js.map +1 -1
  11. package/dist/errors.d.ts +46 -11
  12. package/dist/errors.js +68 -28
  13. package/dist/errors.js.map +1 -1
  14. package/dist/factor-basis.d.ts +14 -0
  15. package/dist/factor-basis.js.map +1 -1
  16. package/dist/index.d.ts +13 -11
  17. package/dist/index.js +6 -5
  18. package/dist/index.js.map +1 -1
  19. package/dist/member/benefits.js +41 -39
  20. package/dist/member/benefits.js.map +1 -1
  21. package/dist/member/index.d.ts +1 -1
  22. package/dist/member/input-period.d.ts +41 -0
  23. package/dist/member/input-period.js +168 -0
  24. package/dist/member/input-period.js.map +1 -0
  25. package/dist/member/service.d.ts +8 -1
  26. package/dist/member/service.js +18 -1
  27. package/dist/member/service.js.map +1 -1
  28. package/dist/member/types.d.ts +101 -44
  29. package/dist/member/types.js.map +1 -1
  30. package/dist/member/valuation.d.ts +72 -14
  31. package/dist/member/valuation.js +115 -34
  32. package/dist/member/valuation.js.map +1 -1
  33. package/dist/pay-path.d.ts +21 -25
  34. package/dist/pay-path.js +85 -67
  35. package/dist/pay-path.js.map +1 -1
  36. package/dist/pension/ages.d.ts +6 -4
  37. package/dist/pension/ages.js +6 -4
  38. package/dist/pension/ages.js.map +1 -1
  39. package/dist/pension/curve.d.ts +2 -1
  40. package/dist/pension/curve.js +15 -7
  41. package/dist/pension/curve.js.map +1 -1
  42. package/dist/pension/history.d.ts +18 -3
  43. package/dist/pension/history.js +12 -5
  44. package/dist/pension/history.js.map +1 -1
  45. package/dist/pension/ledger.d.ts +15 -9
  46. package/dist/pension/ledger.js +91 -56
  47. package/dist/pension/ledger.js.map +1 -1
  48. package/dist/pension/prices.d.ts +11 -2
  49. package/dist/pension/prices.js +35 -14
  50. package/dist/pension/prices.js.map +1 -1
  51. package/dist/pension/scheme-year.d.ts +59 -0
  52. package/dist/pension/scheme-year.js +80 -0
  53. package/dist/pension/scheme-year.js.map +1 -0
  54. package/dist/pension/seed.d.ts +66 -50
  55. package/dist/pension/seed.js +111 -65
  56. package/dist/pension/seed.js.map +1 -1
  57. package/dist/pension/uplift.d.ts +13 -33
  58. package/dist/pension/uplift.js +11 -56
  59. package/dist/pension/uplift.js.map +1 -1
  60. package/dist/pension-projection.js +30 -22
  61. package/dist/pension-projection.js.map +1 -1
  62. package/dist/post.d.ts +1 -10
  63. package/dist/post.js +1 -12
  64. package/dist/post.js.map +1 -1
  65. package/dist/revaluation.d.ts +34 -35
  66. package/dist/revaluation.js +41 -41
  67. package/dist/revaluation.js.map +1 -1
  68. package/dist/scale-point.d.ts +6 -0
  69. package/dist/sections/final-salary.d.ts +64 -52
  70. package/dist/sections/final-salary.js +131 -69
  71. package/dist/sections/final-salary.js.map +1 -1
  72. package/dist/sections/section-2015.d.ts +2 -1
  73. package/dist/sections/section-2015.js.map +1 -1
  74. package/dist/sources.d.ts +10 -0
  75. package/dist/sources.js +20 -0
  76. package/dist/sources.js.map +1 -1
  77. package/dist/take-home.d.ts +4 -20
  78. package/dist/take-home.js +3 -23
  79. package/dist/take-home.js.map +1 -1
  80. package/package.json +3 -3
package/README.md CHANGED
@@ -1,27 +1,12 @@
1
1
  # @casomoltd/nhs-pay
2
2
 
3
- NHS pay scales — Agenda for Change plus medical & dental —
4
- with pension tiers, regions, HCAS supplements, and a take-home
5
- calculator built on top of `@casomoltd/paye-calc`. And a member's
6
- NHS pension across the 1995, 2008 and 2015 Sections: final salary
7
- and career average, the McCloud remedy window valued on either
8
- basis, early and late retirement factors, and tax-free cash across
9
- the whole drawing.
10
-
11
- See [`docs/pay-frameworks.md`](docs/pay-frameworks.md) for the domain
12
- model — the pay frameworks (AfC, medical, dental, VSM), the shared
13
- scale-resolver core, and where the consumer boundary sits.
3
+ NHS pay scales — Agenda for Change plus medical & dental — with pension tiers, regions, HCAS supplements, and a take-home calculator built on top of `@casomoltd/paye-calc`. And a member's NHS pension across the 1995, 2008 and 2015 Sections: final salary and career average, the McCloud remedy window valued on either basis, early and late retirement factors, and tax-free cash across the whole drawing.
4
+
5
+ See [`docs/pay-frameworks.md`](docs/pay-frameworks.md) for the domain model — the pay frameworks (AfC, medical, dental, VSM), the shared scale-resolver core, and where the consumer boundary sits.
14
6
 
15
7
  ## About Casomo
16
8
 
17
- Casomo is a [registered UK limited company][companies-house]
18
- founded and directed by
19
- [David Mohamad](https://github.com/dkmohamad). It builds focused
20
- software tools and offers engineering consulting. This library
21
- powers the NHS pay calculators and explainers on
22
- [casomo.co.uk](https://casomo.co.uk) — where the differentiator is
23
- showing **take-home** pay (after tax, NI and pension), not just the
24
- gross figures most published sources stop at.
9
+ Casomo is a [registered UK limited company][companies-house] founded and directed by [David Mohamad](https://github.com/dkmohamad). It builds focused software tools and offers engineering consulting. This library powers the NHS pay calculators and explainers on [casomo.co.uk](https://casomo.co.uk) — where the differentiator is showing **take-home** pay (after tax, NI and pension), not just the gross figures most published sources stop at.
25
10
 
26
11
  - **Portfolio** — [casomo.co.uk](https://casomo.co.uk)
27
12
  - **Consulting** — [casomoltd.com](https://casomoltd.com)
@@ -36,8 +21,7 @@ npm install @casomoltd/nhs-pay
36
21
 
37
22
  Public on the npm registry — no auth or `.npmrc` config needed.
38
23
 
39
- Requires `@casomoltd/paye-calc` (>=0.5.0) as a peer
40
- dependency.
24
+ Requires `@casomoltd/paye-calc` as a peer dependency; the range it accepts is `peerDependencies` in [`package.json`](package.json).
41
25
 
42
26
  ## Usage
43
27
 
@@ -114,10 +98,7 @@ fmtPct(8.3); // '8.3%'
114
98
 
115
99
  ### Take-home for a doctor or dentist
116
100
 
117
- Medical and dental grades resolve the same way as AfC, via a
118
- per-family resolver. `getMedicalScales(year, nation)` lists the
119
- grades published for a nation and year; `fromPoint` builds a
120
- `Post` (gross, pension tier, tax, NI, take-home) from one point.
101
+ Medical and dental grades resolve the same way as AfC, via a per-family resolver. `getMedicalScales(year, nation)` lists the grades published for a nation and year; `fromPoint` builds a `Post` (gross, pension tier, tax, NI, take-home) from one point.
121
102
 
122
103
  ```ts
123
104
  import {getMedicalScales, medicalResolver} from '@casomoltd/nhs-pay';
@@ -135,16 +116,9 @@ console.log(post.takeHome.net); // annual net after tax + NI + pension
135
116
  console.log(consultant.source.reference); // the circular it came from
136
117
  ```
137
118
 
138
- `fromPoint` takes the point itself. There is also
139
- `fromScalePoint(grade, label, …)` for a caller holding only a label,
140
- but a label does not identify a point on every scale — England's
141
- consultant scale is 20 payroll steps over 5 threshold labels, so
142
- `'Threshold 4'` names six of them and that call throws
143
- `AmbiguousScalePoint` rather than picking one.
119
+ `fromPoint` takes the point itself. There is also `fromScalePoint(grade, label, …)` for a caller holding only a label, but a label does not identify a point on every scale — England's consultant scale is 20 payroll steps over 5 threshold labels, so `'Threshold 4'` names six of them and that call throws `AmbiguousScalePoint` rather than picking one.
144
120
 
145
- `getDentalScales` / `dentalResolver` mirror this for salaried
146
- dental grades. Both fail loud (`ScaleUnavailable`) for an
147
- unpublished nation/year or grade rather than defaulting.
121
+ `getDentalScales` / `dentalResolver` mirror this for salaried dental grades. Both fail loud (`ScaleUnavailable`) for an unpublished nation/year or grade rather than defaulting.
148
122
 
149
123
  ### Value a member's pension across sections
150
124
 
@@ -152,6 +126,7 @@ unpublished nation/year or grade rather than defaulting.
152
126
  import {
153
127
  PAST_YEARS, SECTIONS, isoDate, memberBenefits,
154
128
  } from '@casomoltd/nhs-pay';
129
+ import {definedBenefitInput, taxYearEnd} from '@casomoltd/paye-calc';
155
130
 
156
131
  // Built once from the member; `today` pins the date the figures
157
132
  // are as at, so they reproduce.
@@ -180,8 +155,9 @@ const benefits = memberBenefits(
180
155
  benefits.remedy; // true: in service by 31 March 2012 and after 2015
181
156
  benefits.now(); // held today, the remedy window on the legacy basis
182
157
 
183
- // Asked once per option. Every section is drawn on one date.
184
- for (const kind of ['legacy-basis', 'section-2015-basis'] as const) {
158
+ // Asked once per election the member is compared on: both bases here,
159
+ // because they have a remedy window. Every section is drawn on one date.
160
+ for (const kind of benefits.elections) {
185
161
  const position = benefits.at({
186
162
  leaving: isoDate('2039-09-30'),
187
163
  drawing: isoDate('2039-09-30'),
@@ -189,25 +165,25 @@ for (const kind of ['legacy-basis', 'section-2015-basis'] as const) {
189
165
  cash: {kind: 'maximum'},
190
166
  });
191
167
  position.awards; // one per section and basis, each factored
168
+ position.section2015; // the 2015 Section's ledgers, estimated history, curve
192
169
  position.crystallised; // the pension and automatic lump sum, summed
193
170
  position.cash; // the cash taken across the whole
194
171
  }
172
+
173
+ // One tax year's pension input, for the annual allowance: 2027 is
174
+ // 2026-27 (paye-calc's `taxYearEnd`), for the same leaving and election,
175
+ // valued in that year's cash at 2% CPI.
176
+ const period = benefits.pensionInputPeriod(taxYearEnd(2027), {
177
+ leaving: isoDate('2039-09-30'), remedy: {kind: 'legacy-basis'},
178
+ }, 0.02);
179
+ const input = definedBenefitInput(period); // the year's input amount
195
180
  ```
196
181
 
197
- Each section keeps its own rules — denominator, pay measure,
198
- pension age, lump sum, factors — so no caller can combine them
199
- into one the scheme lacks. Pay comes from the member's pay path
200
- (`promotionalIndex` is GAD's curve behind it). Service the library
201
- does not model, such as a break, is refused with
202
- `BenefitNotModelled` and a `code` to branch on; `NOT_MODELLED`
203
- links each code to the issue tracking it. See
204
- [*A member's benefits across sections*](docs/how-it-works.md#a-members-benefits-across-sections).
182
+ Each section keeps its own rules — denominator, pay measure, pension age, lump sum, factors — so no caller can combine them into one the scheme lacks. Pay comes from the member's pay path (`promotionalIndex` is GAD's curve behind it). Service the library does not model, such as a break, is refused with `BenefitNotModelled` and a `code` to branch on; `NOT_MODELLED` links each code to the issue tracking it. See [*A member's benefits across sections*](docs/how-it-works.md#a-members-benefits-across-sections) for the model. How each arrangement's pension input is valued is [*A year's pension input*](docs/how-it-works.md#a-years-pension-input).
205
183
 
206
184
  ### Project a 2015 Section pension on flat pay
207
185
 
208
- **Deprecated.** `projectPension` is kept for this flat-pay question
209
- until [#21](https://github.com/casomoltd/nhs-pay/issues/21); for a
210
- member across sections, use `memberBenefits` above.
186
+ **Deprecated.** `projectPension` is kept for this flat-pay question until [#21](https://github.com/casomoltd/nhs-pay/issues/21); for a member across sections, use `memberBenefits` above.
211
187
 
212
188
  ```ts
213
189
  import {
@@ -257,47 +233,21 @@ console.log(limit.real.amount, limit.real.binding);
257
233
  console.log(limit.nominal.amount, limit.nominal.binding);
258
234
  ```
259
235
 
260
- The maximum is the **lower** of two caps, and **both are
261
- statutory**: 25% of the capital value of the benefits, and the
262
- Lump Sum Allowance. The scheme's own contribution to the swap is
263
- the 12:1 rate and nothing else, so a consumer must not attribute
264
- the 25% to the scheme — `LUMP_SUM_CAPS.Scheme` names the
265
- discriminant, not the rule's author. `binding` says which cap
266
- stopped it, so a consumer can explain the figure rather than
267
- restate the rule.
268
-
269
- Why that name is left as it is, and what moves where when it
270
- changes: [*The two caps on tax-free
271
- cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
272
-
273
- There is **one limit per ruler, and no single flag**, because the
274
- two can genuinely disagree: `real` is the model run at zero CPI
275
- while the allowance is carried forward at CPI, so around the
276
- crossover the allowance binds in today's money while the scheme
277
- limb still binds in cash. Show the limit belonging to the ruler
278
- on screen. See
279
- [*The two caps on tax-free cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
280
-
281
- Without a statement figure, `kind: 'estimation'` accrues from a
282
- `joinDate` instead. ERF/LRF factors are transcribed verbatim from
283
- the GAD consolidated factor workbook (30 June 2023 issue) with
284
- GAD's own rounding rules; a retirement date beyond the printed
285
- tables throws `RetirementFactorOutOfRange`.
236
+ The maximum is the **lower** of two caps, and **both are statutory**: 25% of the capital value of the benefits, and the Lump Sum Allowance. The scheme's own contribution to the swap is the 12:1 rate and nothing else, so a consumer must not attribute the 25% to the scheme — `LUMP_SUM_CAPS.Scheme` names the discriminant, not the rule's author. `binding` says which cap stopped it, so a consumer can explain the figure rather than restate the rule.
237
+
238
+ Why that name is left as it is, and what moves where when it changes: [*The two caps on tax-free cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
239
+
240
+ There is **one limit per ruler, and no single flag**, because the two can genuinely disagree: `real` is the model run at zero CPI while the allowance is carried forward at CPI, so around the crossover the allowance binds in today's money while the scheme limb still binds in cash. Show the limit belonging to the ruler on screen. See [*The two caps on tax-free cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
241
+
242
+ Without a statement figure, `kind: 'estimation'` accrues from a `joinDate` instead. ERF/LRF factors are transcribed verbatim from the GAD consolidated factor workbook (30 June 2023 issue) with GAD's own rounding rules; a retirement date beyond the printed tables throws `RetirementFactorOutOfRange`.
286
243
 
287
244
  ## How it works
288
245
 
289
- [`docs/how-it-works.md`](docs/how-it-works.md) — the model this
290
- library implements: the recurrence it walks, what a scheme year
291
- and an exit date mean to it, why cash and today's money are two
292
- runs rather than one and a deflator, and every assumption it
293
- makes, declared. Read it before trusting a figure.
246
+ [`docs/how-it-works.md`](docs/how-it-works.md) — the model this library implements: the recurrence it walks, what a scheme year and an exit date mean to it, why cash and today's money are two runs rather than one and a deflator, and every assumption it makes, declared. Read it before trusting a figure.
294
247
 
295
248
  ## API reference
296
249
 
297
- [`docs/api.md`](docs/api.md) — every export, organised by
298
- domain, with typed signatures and short notes. Kept in sync with
299
- the code by a check-time drift gate. Agents may prefer the
300
- shipped `dist/*.d.ts`, which carry the full JSDoc per module.
250
+ [`docs/api.md`](docs/api.md) — every export, organised by domain, with typed signatures and short notes. Kept in sync with the code by a check-time drift gate. Agents may prefer the shipped `dist/*.d.ts`, which carry the full JSDoc per module.
301
251
 
302
252
  ## Data sources
303
253
 
@@ -308,8 +258,7 @@ shipped `dist/*.d.ts`, which carry the full JSDoc per module.
308
258
  | 2025-26 | England, NI, Wales | [NHS Employers pay scales 2025/26][scales-2526] |
309
259
  | 2026-27 | England, NI | [NHS Employers pay scales 2026/27][scales-2627] |
310
260
 
311
- Cross-checked against [NHSPRB 39th Report (2026)][nhsprb-39],
312
- Table A25 (AfC 2025/26 data for England, NI, Wales).
261
+ Cross-checked against [NHSPRB 39th Report (2026)][nhsprb-39], Table A25 (AfC 2025/26 data for England, NI, Wales).
313
262
 
314
263
  [scales-2526]: https://www.nhsemployers.org/articles/pay-scales-202526
315
264
  [scales-2627]: https://www.nhsemployers.org/articles/pay-scales-202627
@@ -337,99 +286,37 @@ Table A25 (AfC 2025/26 data for England, NI, Wales).
337
286
  [s276]: https://www.legislation.gov.uk/ukpga/2004/12/section/276
338
287
  [s637p]: https://www.legislation.gov.uk/ukpga/2003/1/part/9/chapter/15A
339
288
 
340
- Reconciled line by line against a real **Annual Benefit
341
- Statement** (2015 Section, updated to 31/03/2025, name and
342
- membership number redacted), and against a ten-year projection
343
- built by hand from it.
344
-
345
- Both are archived and inventoried in
346
- [`docs/source-archive.md`](docs/source-archive.md), with the
347
- links themselves in the header of
348
- [`tests/golden-abs.test.ts`](tests/golden-abs.test.ts) — beside
349
- the assertions they justify, which is where a citation belongs
350
- and where it cannot drift from what it is citing.
351
-
352
- The statement is the source of truth and the library never
353
- restates it: enter its figure and ask for its own date, and you
354
- are handed back exactly what it says. See
355
- [*Two rulers, one model*](docs/how-it-works.md#two-rulers-one-model)
356
- for how cash and today's money are produced, and
357
- [*Which series applies a published Order*](docs/how-it-works.md#which-series-applies-a-published-order)
358
- for when a legislated rate is applied and why today's money
359
- never takes one.
360
-
361
- That promise is exact for a statement handed over **with its
362
- date**. Passing the figure undated instead asks a different
363
- question — "this is my balance today" — and the library must
364
- then work backwards to the year end, at its own revaluation rule
365
- rather than the scheme's. For a member who left at a year end
366
- the two differ; see
367
- [*Reading a statement back applies the SAME rule*](docs/how-it-works.md#reading-a-statement-back-applies-the-same-rule)
368
- for the size of it and why passing the date avoids it.
289
+ Reconciled line by line against a real **Annual Benefit Statement** (2015 Section, updated to 31/03/2025, name and membership number redacted), and against a ten-year projection built by hand from it.
290
+
291
+ Both are archived and inventoried in [`docs/source-archive.md`](docs/source-archive.md), with the links themselves in the header of [`tests/golden-abs.test.ts`](tests/golden-abs.test.ts) — beside the assertions they justify, which is where a citation belongs and where it cannot drift from what it is citing.
292
+
293
+ The statement is the source of truth and the library never restates it: enter its figure and ask for its own date, and you are handed back exactly what it says. See [*Two rulers, one model*](docs/how-it-works.md#two-rulers-one-model) for how cash and today's money are produced, and [*Which series applies a published Order*](docs/how-it-works.md#which-series-applies-a-published-order) for when a legislated rate is applied and why today's money never takes one.
294
+
295
+ That promise is exact for a statement handed over **with its date**. Passing the figure undated instead asks a different question — "this is my balance today" — and the library must then work backwards to the year end, at its own revaluation rule rather than the scheme's. For a member who left at a year end the two differ; see [*Reading a statement back applies the SAME rule*](docs/how-it-works.md#reading-a-statement-back-applies-the-same-rule) for the size of it and why passing the date avoids it.
369
296
 
370
297
  ### Scotland
371
298
 
372
- Scotland negotiates its own AfC award independently and
373
- has completely different base salaries from England.
374
- Separate scale tables are stored for each tax year —
375
- `getAfcScales(year, 'scotland')` returns Scotland figures
376
- directly. Scotland also has structural differences: Band 2
377
- has 2 points (vs 1 in England) and Bands 8a–9 have 2
378
- points each (vs 3).
379
-
380
- Source: [PCS(AFC)2026/1][scot-circular] — Scottish Health
381
- Workforce Directorate circular (23 Jan 2026). Annex B holds
382
- both years' rate tables; Annex C sets them out increment by
383
- increment and corroborates Annex B point for point.
384
-
385
- Scotland's 2025-26 settlement was 4.25%, but carried an
386
- inflation guarantee — at least one percentage point above
387
- average CPI for the calendar year of the uplift. 2025 CPI
388
- confirmed at 3.4%, so the guarantee triggered and the rate
389
- was revised to 4.4%, backdated to 1 April 2025 with arrears.
390
- 2026-27's 3.75% then applies to the revised base, so both
391
- years moved. Take both from Annex B rather than the MSG
392
- consolidated table, which still prints the original 4.25%
393
- rates.
299
+ Scotland negotiates its own AfC award independently and has completely different base salaries from England. Separate scale tables are stored for each tax year — `getAfcScales(year, 'scotland')` returns Scotland figures directly. Scotland also has structural differences: Band 2 has 2 points (vs 1 in England) and Bands 8a–9 have 2 points each (vs 3).
300
+
301
+ Source: [PCS(AFC)2026/1][scot-circular] — Scottish Health Workforce Directorate circular (23 Jan 2026). Annex B holds both years' rate tables; Annex C sets them out increment by increment and corroborates Annex B point for point.
302
+
303
+ Scotland's 2025-26 settlement was 4.25%, but carried an inflation guarantee — at least one percentage point above average CPI for the calendar year of the uplift. 2025 CPI confirmed at 3.4%, so the guarantee triggered and the rate was revised to 4.4%, backdated to 1 April 2025 with arrears. 2026-27's 3.75% then applies to the revised base, so both years moved. Take both from Annex B rather than the MSG consolidated table, which still prints the original 4.25% rates.
394
304
 
395
305
  [scot-circular]: https://www.publications.scot.nhs.uk/files/pcs2026-afc-01.pdf
396
306
 
397
307
  ### Wales
398
308
 
399
- Wales runs its own pay ladder and both years are transcribed
400
- from it: [AfC(W) 02/2025][wales-2025] (29 May 2025) and
401
- [AfC(W) 02/2026][wales-2026] (12 Feb 2026), Annex 1 of each.
402
-
403
- Wales is **not** England's table with a floor applied. The two
404
- ladders differ at every band from 4 upward, where no floor
405
- reaches: Band 9 tops out at £131,732 in Wales against £129,783
406
- in England. A floor lifts the bottom of a ladder and cannot
407
- raise its top. Wales also carries two Band 2 points where
408
- England has one.
409
-
410
- Point labels come from each circular's own "years until
411
- eligible for pay progression" column, so they are stated by
412
- the Welsh source rather than borrowed from England's table,
413
- and they do not always agree with England's for the same band.
414
-
415
- The living-wage floor is real but separate: it is an advance
416
- payment that lifts the lowest points, which is why the 2026/27
417
- uplift explicitly does not apply to them. `WALES_LIVING_WAGE`
418
- carries both published figures — the annual floor and the hourly
419
- rate it is set against — for reference; nothing derives a scale
420
- from it, and neither figure derives from the other.
421
- Source: [AfC(W) 01/2026][wales-lw] (6 Jan 2026).
422
-
423
- Band 1 is published in both years (£24,833, then £26,300) and
424
- closed to new entrants. It is absent from `AFC_BANDS`, the same
425
- gap Scotland has.
426
-
427
- Both Welsh years were transcribed during an outage of the NHS Wales
428
- web estate (2 September 2026), so the circulars were read from NHS
429
- Wales Employers' copy rather than the publisher's own. Each file was
430
- checked byte-for-byte against a copy downloaded from `www.nhs.wales`
431
- the previous day, before the outage, and both matched. The links
432
- above are the publisher's, which is where these documents live.
309
+ Wales runs its own pay ladder and both years are transcribed from it: [AfC(W) 02/2025][wales-2025] (29 May 2025) and [AfC(W) 02/2026][wales-2026] (12 Feb 2026), Annex 1 of each.
310
+
311
+ Wales is **not** England's table with a floor applied. The two ladders differ at every band from 4 upward, where no floor reaches: Band 9 tops out at £131,732 in Wales against £129,783 in England. A floor lifts the bottom of a ladder and cannot raise its top. Wales also carries two Band 2 points where England has one.
312
+
313
+ Point labels come from each circular's own "years until eligible for pay progression" column, so they are stated by the Welsh source rather than borrowed from England's table, and they do not always agree with England's for the same band.
314
+
315
+ The living-wage floor is real but separate: it is an advance payment that lifts the lowest points, which is why the 2026/27 uplift explicitly does not apply to them. `WALES_LIVING_WAGE` carries both published figures — the annual floor and the hourly rate it is set against — for reference; nothing derives a scale from it, and neither figure derives from the other. Source: [AfC(W) 01/2026][wales-lw] (6 Jan 2026).
316
+
317
+ Band 1 is published in both years (£24,833, then £26,300) and closed to new entrants. It is absent from `AFC_BANDS`, the same gap Scotland has.
318
+
319
+ Both Welsh years were transcribed during an outage of the NHS Wales web estate (2 September 2026), so the circulars were read from NHS Wales Employers' copy rather than the publisher's own. Each file was checked byte-for-byte against a copy downloaded from `www.nhs.wales` the previous day, before the outage, and both matched. The links above are the publisher's, which is where these documents live.
433
320
 
434
321
  [wales-2025]: https://www.nhs.wales/files/pc-resources/afc-w-02-2025-pdf-2-pdf/
435
322
  [wales-2026]: https://www.nhs.wales/files/pc-resources/afc-w-02-2026-pdf-pdf/
@@ -449,10 +336,7 @@ above are the publisher's, which is where these documents live.
449
336
 
450
337
  ## Medical & dental pay scales
451
338
 
452
- Doctors and dentists are paid on a separate set of pay circulars —
453
- one per nation — from Agenda for Change. This library encodes them
454
- so it can render **take-home** (not just gross) for medical and
455
- dental grades, which is what most published sources omit.
339
+ Doctors and dentists are paid on a separate set of pay circulars — one per nation — from Agenda for Change. This library encodes them so it can render **take-home** (not just gross) for medical and dental grades, which is what most published sources omit.
456
340
 
457
341
  | Nation | Circular | Year | Source |
458
342
  | ------ | -------- | ---- | ------ |
@@ -469,78 +353,33 @@ dental grades, which is what most published sources omit.
469
353
  [md-wal]: https://www.nhs.wales/hpb/nhs-pay-and-conditions/
470
354
  [md-ni]: https://www.health-ni.gov.uk/publications/hsc-tc8-052025
471
355
 
472
- Wales's 2026/27 round is a 3.5% uplift (3.75% for salaried
473
- dentists) and removes the closed Associate Specialist (MC01)
474
- code, so that grade resolves only at 2025/26.
356
+ Wales's 2026/27 round is a 3.5% uplift (3.75% for salaried dentists) and removes the closed Associate Specialist (MC01) code, so that grade resolves only at 2025/26.
475
357
 
476
- NI 2025/26 pension member tiers (HSC — distinct thresholds *and*
477
- rates from NHSBSA) are sourced from [HSC Pensions][hsc-pension].
358
+ NI 2025/26 pension member tiers (HSC — distinct thresholds *and* rates from NHSBSA) are sourced from [HSC Pensions][hsc-pension].
478
359
 
479
360
  [hsc-pension]: https://hscpensions.hscni.net/
480
361
 
481
362
  ### How the data is modelled
482
363
 
483
- The circulars vary widely in structure (nodal training points,
484
- consultant thresholds, SAS experience bands, GP ranges, dental
485
- spines), so the data is built in three layers that decouple
486
- transcription fidelity from the uniform domain model:
487
-
488
- 1. **Verbatim circular** (`src/circulars/*.ts`) — one file per PDF,
489
- each table transcribed 1:1 in source order with a row shape that
490
- mirrors that table's own columns, under a comment citing the
491
- Annex / section / page. Every table in the circular is either
492
- transcribed or **recorded with a reason** for skipping it, so
493
- nothing is silently dropped and each file diffs against the PDF
494
- top-to-bottom.
495
- 2. **Translation layer** (`src/medical-scales.ts`,
496
- `src/dental-scales.ts`) — selects which scales feed the
497
- calculator and maps each verbatim row to a canonical scale point.
498
- Inclusive by default: closed-to-new-entrant grades, devolved
499
- training variants, GP registrars and the Community Dental Service
500
- are all wired.
501
- 3. **Canonical domain** (`getMedicalScales` / `getDentalScales` +
502
- `medicalResolver` / `dentalResolver`) — a uniform
503
- `(grade, nation, year) → scale points` view, identical in shape
504
- to the AfC resolver.
505
-
506
- **Scope.** *(a)* every basic-pay salary scale, including
507
- closed-to-new-entrant grades still paid to incumbents, plus *(b)*
508
- earnings-affecting supplements expressed as an annual £ (Clinical
509
- Impact / Excellence awards, DPH and intensity supplements). Pure
510
- expense tables (mileage, fees) and self-employed GDS/UDA dentist
511
- contract income are out of scope.
512
-
513
- **Unpublished data fails loud.** England and Wales publish complete
514
- 2026/27 rounds. Scotland's 2026/27 circular uplifts training grades
515
- only, so its consultant / SAS / GP / dental scales resolve to the
516
- complete 2025/26 round (PCS(DD)2025/01) until the Scottish
517
- Government publishes the non-training uplift; Northern Ireland's
518
- latest circular is 2025/26 throughout. Each grade resolves at its
519
- own cited year and `latestYearFor(grade, nation)` reports it —
520
- figures are never silently carried forward, and a query for an
521
- unpublished (year, nation) throws rather than defaulting to another
522
- nation's or year's figures.
364
+ The circulars vary widely in structure (nodal training points, consultant thresholds, SAS experience bands, GP ranges, dental spines), so the data is built in three layers that decouple transcription fidelity from the uniform domain model:
365
+
366
+ 1. **Verbatim circular** (`src/circulars/*.ts`) — one file per PDF, each table transcribed 1:1 in source order with a row shape that mirrors that table's own columns, under a comment citing the Annex / section / page. Every table in the circular is either transcribed or **recorded with a reason** for skipping it, so nothing is silently dropped and each file diffs against the PDF top-to-bottom.
367
+ 2. **Translation layer** (`src/medical-scales.ts`, `src/dental-scales.ts`) — selects which scales feed the calculator and maps each verbatim row to a canonical scale point. Inclusive by default: closed-to-new-entrant grades, devolved training variants, GP registrars and the Community Dental Service are all wired.
368
+ 3. **Canonical domain** (`getMedicalScales` / `getDentalScales` + `medicalResolver` / `dentalResolver`) — a uniform `(grade, nation, year) → scale points` view, identical in shape to the AfC resolver.
369
+
370
+ **Scope.** *(a)* every basic-pay salary scale, including closed-to-new-entrant grades still paid to incumbents, plus *(b)* earnings-affecting supplements expressed as an annual £ (Clinical Impact / Excellence awards, DPH and intensity supplements). Pure expense tables (mileage, fees) and self-employed GDS/UDA dentist contract income are out of scope.
371
+
372
+ **Unpublished data fails loud.** England and Wales publish complete 2026/27 rounds. Scotland's 2026/27 circular uplifts training grades only, so its consultant / SAS / GP / dental scales resolve to the complete 2025/26 round (PCS(DD)2025/01) until the Scottish Government publishes the non-training uplift; Northern Ireland's latest circular is 2025/26 throughout. Each grade resolves at its own cited year and `latestYearFor(grade, nation)` reports it — figures are never silently carried forward, and a query for an unpublished (year, nation) throws rather than defaulting to another nation's or year's figures.
523
373
 
524
374
  ## Test fixtures
525
375
 
526
- `tests/working-week.test.ts` pins the AfC week and its 365/7 year
527
- against every hourly rate Scotland's circular prints beside a salary, and
528
- the Welsh living-wage pair.
529
-
530
- `tests/fixtures/band-take-home.csv` — golden-value rows
531
- covering bands 5, 7, 8a across all 4 nations (England,
532
- Scotland, Wales, NI), both tax years, 3 HCAS zones, and
533
- part-time (0.6 FTE). Gross figures are derived from
534
- `getAfcScales(year, nation)` using the sources above.
535
- Pension, tax, NI and net values are computed by
536
- `nhsTakeHome` and should be cross-checked against:
537
-
538
- - [NHS Employers pay scales 2025/26][scales-2526] and
539
- [2026/27][scales-2627] for England/NI gross
540
- - [PCS(AFC)2026/1][scot-circular] Annex B for Scotland
541
- gross
542
- - [NHSBSA pension contribution rates 2025/26][pension-2526]
543
- for pension tier rates
376
+ `tests/working-week.test.ts` pins the AfC week and its 365/7 year against every hourly rate Scotland's circular prints beside a salary, and the Welsh living-wage pair.
377
+
378
+ `tests/fixtures/band-take-home.csv` — golden-value rows covering bands 5, 7, 8a across all 4 nations (England, Scotland, Wales, NI), both tax years, 3 HCAS zones, and part-time (0.6 FTE). Gross figures are derived from `getAfcScales(year, nation)` using the sources above. Pension, tax, NI and net values are computed by `nhsTakeHome` and should be cross-checked against:
379
+
380
+ - [NHS Employers pay scales 2025/26][scales-2526] and [2026/27][scales-2627] for England/NI gross
381
+ - [PCS(AFC)2026/1][scot-circular] Annex B for Scotland gross
382
+ - [NHSBSA pension contribution rates 2025/26][pension-2526] for pension tier rates
544
383
 
545
384
  ## Tax years
546
385
 
@@ -553,10 +392,7 @@ AfC scale + pension coverage (all four nations):
553
392
  | 2025-26 | Yes | Yes |
554
393
  | 2026-27 | Yes | Yes |
555
394
 
556
- Medical & dental coverage is per-nation (England/Wales 2026/27;
557
- Scotland 2026/27 for training grades and 2025/26 for the rest;
558
- NI 2025/26) — see
559
- [Medical & dental pay scales](#medical--dental-pay-scales).
395
+ Medical & dental coverage is per-nation (England/Wales 2026/27; Scotland 2026/27 for training grades and 2025/26 for the rest; NI 2025/26) — see [Medical & dental pay scales](#medical--dental-pay-scales).
560
396
 
561
397
  ## Development
562
398
 
@@ -570,13 +406,6 @@ npm run test:watch # vitest watch mode
570
406
 
571
407
  ## License
572
408
 
573
- AGPL-3.0-only — see [LICENSE](LICENSE).
574
- Copyright © 2026 Casomo Ltd.
409
+ AGPL-3.0-only — see [LICENSE](LICENSE). Copyright © 2026 Casomo Ltd.
575
410
 
576
- There is no linking exception: combine this library with your
577
- own code and the combined work is AGPL too, and letting people
578
- use that work over a network obliges you to offer them its
579
- source. Charging money is not what triggers this, and not
580
- charging is no exemption. A commercial licence is available for
581
- use that needs to stay closed — enquire via
582
- [casomoltd.com](https://casomoltd.com).
411
+ There is no linking exception: combine this library with your own code and the combined work is AGPL too, and letting people use that work over a network obliges you to offer them its source. Charging money is not what triggers this, and not charging is no exemption. A commercial licence is available for use that needs to stay closed — enquire via [casomoltd.com](https://casomoltd.com).
package/dist/bands.d.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import type { PayYear, Nation } from '@casomoltd/paye-calc';
11
11
  import type { AfcBandId, HcasZones } from './scales.js';
12
- import type { SteppedPoint } from './scale-point.js';
12
+ import type { PayLadder, SteppedPoint } from './scale-point.js';
13
13
  import type { DocumentSource } from './document-source.js';
14
14
  import type { SalaryRange } from './values.js';
15
15
  export interface AfcBandMeta {
@@ -53,3 +53,11 @@ export declare const AFC_PREVIOUS_YEAR: PayYear;
53
53
  * silently return England figures for every region (the exact bug
54
54
  * this signature prevents). */
55
55
  export declare function getAfcScales(year: PayYear, nation: Nation): AfcScaleData;
56
+ /**
57
+ * The point labelled `label` on an AfC band, with the band's points, for
58
+ * a pay year and nation, read from {@link getAfcScales}. Throws
59
+ * `ScaleUnavailable` where the year and nation publish no scale or the
60
+ * band has no such point, and `AmbiguousScalePoint` where the label names
61
+ * more than one, so a caller never prices a point it did not ask for.
62
+ */
63
+ export declare function afcPointOf(year: PayYear, nation: Nation, band: AfcBandId, label: string): PayLadder;
package/dist/bands.js CHANGED
@@ -9,6 +9,7 @@
9
9
  */
10
10
  import { TAX_YEARS } from '@casomoltd/paye-calc';
11
11
  import { AFC_BAND_IDS, afcScaleSource, getScalesForYear, } from './scales.js';
12
+ import { AmbiguousScalePoint, ScaleUnavailable } from './errors.js';
12
13
  /**
13
14
  * The AfC PAY year England, Scotland and Wales are currently on.
14
15
  *
@@ -55,4 +56,23 @@ export function getAfcScales(year, nation) {
55
56
  hcas: scaleYear.hcas,
56
57
  };
57
58
  }
59
+ /**
60
+ * The point labelled `label` on an AfC band, with the band's points, for
61
+ * a pay year and nation, read from {@link getAfcScales}. Throws
62
+ * `ScaleUnavailable` where the year and nation publish no scale or the
63
+ * band has no such point, and `AmbiguousScalePoint` where the label names
64
+ * more than one, so a caller never prices a point it did not ask for.
65
+ */
66
+ export function afcPointOf(year, nation, band, label) {
67
+ const found = getAfcScales(year, nation).bands.find((b) => b.band === band);
68
+ const matches = found?.points.filter((p) => p.label === label) ?? [];
69
+ const current = matches.at(0);
70
+ if (found === undefined || current === undefined) {
71
+ throw new ScaleUnavailable(nation, year, band, label);
72
+ }
73
+ if (matches.length > 1) {
74
+ throw new AmbiguousScalePoint(band, label, matches.length);
75
+ }
76
+ return { points: found.points, current };
77
+ }
58
78
  //# sourceMappingURL=bands.js.map
package/dist/bands.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"bands.js","sourceRoot":"","sources":["../src/bands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAM/C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAC;AA2BrB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE5D,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE7D;;;;;;;gCAOgC;AAChC,MAAM,UAAU,YAAY,CAC1B,IAAa,EACb,MAAc;IAEd,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAChB,CAAC;QACF,OAAO;YACL,IAAI;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;gBAC1B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;aAC3B;YACD,MAAM;SACP,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK;QACL,IAAI,EAAE,SAAS,CAAC,IAAI;KACrB,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"bands.js","sourceRoot":"","sources":["../src/bands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAC,SAAS,EAAC,MAAM,sBAAsB,CAAC;AAM/C,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAC,mBAAmB,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAC;AA0BlE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE5D,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAY,SAAS,CAAC,QAAQ,CAAC;AAE7D;;;;;;;gCAOgC;AAChC,MAAM,UAAU,YAAY,CAC1B,IAAa,EACb,MAAc;IAEd,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAChB,CAAC;QACF,OAAO;YACL,IAAI;YACJ,MAAM;YACN,MAAM,EAAE;gBACN,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;gBAC1B,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;aAC3B;YACD,MAAM;SACP,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK;QACL,IAAI,EAAE,SAAS,CAAC,IAAI;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,IAAa,EACb,MAAc,EACd,IAAe,EACf,KAAa;IAEb,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;IACrE,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAC,CAAC;AACzC,CAAC"}
package/dist/dates.d.ts CHANGED
@@ -64,3 +64,6 @@ export declare function yearsBetween(from: Date, to: Date): number;
64
64
  export declare function npaDate(dateOfBirth: Date, npa: number): Date;
65
65
  /** The earliest of some dates. */
66
66
  export declare function earliest(...dates: readonly Date[]): Date;
67
+ /** Whole days from `from` to `to`, rounded to absorb the hour a clock
68
+ * change shifts local midnight by. */
69
+ export declare function daysBetween(from: Date, to: Date): number;
package/dist/dates.js CHANGED
@@ -29,6 +29,7 @@ const HOURS_PER_DAY = 24;
29
29
  const MINUTES_PER_HOUR = 60;
30
30
  const SECONDS_PER_MINUTE = 60;
31
31
  const MS_PER_SECOND = 1000;
32
+ /** Milliseconds in a calendar day, for counting days between two dates. */
32
33
  const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
33
34
  /** The Julian year: the mean year over a leap cycle, so compounding over a
34
35
  * span crossing 29 February neither gains nor loses a day. */
@@ -72,8 +73,7 @@ export function periodInYearsMonths(from, to) {
72
73
  totalMonths -= 1;
73
74
  }
74
75
  const anniversary = addMonthsClamped(from, totalMonths);
75
- // Round absorbs the ±1h a DST boundary shifts local midnight.
76
- const days = Math.round((to.getTime() - anniversary.getTime()) / MS_PER_DAY);
76
+ const days = daysBetween(anniversary, to);
77
77
  const years = Math.floor(totalMonths / MONTHS_PER_YEAR);
78
78
  const months = totalMonths % MONTHS_PER_YEAR;
79
79
  invariant(years >= 0 && months >= 0 && months < MONTHS_PER_YEAR
@@ -123,6 +123,11 @@ export function npaDate(dateOfBirth, npa) {
123
123
  export function earliest(...dates) {
124
124
  return new Date(Math.min(...dates.map((d) => d.getTime())));
125
125
  }
126
+ /** Whole days from `from` to `to`, rounded to absorb the hour a clock
127
+ * change shifts local midnight by. */
128
+ export function daysBetween(from, to) {
129
+ return Math.round((to.getTime() - from.getTime()) / MS_PER_DAY);
130
+ }
126
131
  /** `date` plus `n` months, day-of-month clamped to the target
127
132
  * month's length (31 Jan + 1mo = 28 Feb). */
128
133
  function addMonthsClamped(date, n) {
package/dist/dates.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"dates.js","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"dates.js","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"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"}
@@ -139,3 +139,19 @@ export declare class DocumentSource {
139
139
  * identical to a fresh one.
140
140
  */
141
141
  export type SourceCurrency = 'current' | 'lapsed' | 'unknown';
142
+ /**
143
+ * A publisher's web page that prints no issue date: what it is, and the
144
+ * day it was read. Its own type rather than a {@link DocumentSource},
145
+ * whose `issued` a consumer prints as the date of publication, so an
146
+ * undated page cannot be shown as published on the day it was read.
147
+ */
148
+ export interface PageSource {
149
+ /** Who publishes it — 'NHSBSA'. */
150
+ readonly issuer: string;
151
+ /** The page's own title, as printed. */
152
+ readonly reference: string;
153
+ /** The page itself, for a consumer to link. */
154
+ readonly url: string;
155
+ /** ISO date the page was read; it prints no date of its own. */
156
+ readonly retrieved: IsoDate;
157
+ }
@@ -18,6 +18,8 @@
18
18
  * scale carries one too, and `award.ts` imports every scale module —
19
19
  * so defining it there would make a scale citing its source a cycle.
20
20
  */
21
+ /** The characters of an ISO timestamp that are its date, `YYYY-MM-DD`. */
22
+ const ISO_DATE_LENGTH = 10;
21
23
  /**
22
24
  * A document this library cites — not commentary about it. Held on the
23
25
  * record so a consumer cites the document rather than keeping its own
@@ -72,7 +74,7 @@ export class DocumentSource {
72
74
  if (!this.nextExpected) {
73
75
  return 'unknown';
74
76
  }
75
- return this.nextExpected >= now.toISOString().slice(0, 10)
77
+ return this.nextExpected >= now.toISOString().slice(0, ISO_DATE_LENGTH)
76
78
  ? 'current'
77
79
  : 'lapsed';
78
80
  }
@@ -1 +1 @@
1
- {"version":3,"file":"document-source.js","sourceRoot":"","sources":["../src/document-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,cAAc;IACzB,8DAA8D;IACrD,MAAM,CAAS;IACxB,mEAAmE;IAC1D,SAAS,CAAS;IAC3B,+CAA+C;IACtC,GAAG,CAAS;IACrB,wCAAwC;IAC/B,MAAM,CAAU;IACzB,sDAAsD;IAC7C,YAAY,CAAW;IAChC;iCAC6B;IACpB,kBAAkB,CAAU;IAErC,YAAY,MAA4B;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,kBAAkB,CAAC;IACtD,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAS;QAClB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACxD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,QAAQ,CAAC;IACf,CAAC;CACF"}
1
+ {"version":3,"file":"document-source.js","sourceRoot":"","sources":["../src/document-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,0EAA0E;AAC1E,MAAM,eAAe,GAAG,EAAE,CAAC;AA8D3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,cAAc;IACzB,8DAA8D;IACrD,MAAM,CAAS;IACxB,mEAAmE;IAC1D,SAAS,CAAS;IAC3B,+CAA+C;IACtC,GAAG,CAAS;IACrB,wCAAwC;IAC/B,MAAM,CAAU;IACzB,sDAAsD;IAC7C,YAAY,CAAW;IAChC;iCAC6B;IACpB,kBAAkB,CAAU;IAErC,YAAY,MAA4B;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,kBAAkB,CAAC;IACtD,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAS;QAClB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;YACrE,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,QAAQ,CAAC;IACf,CAAC;CACF"}