@casomoltd/nhs-pay 0.10.0 → 0.10.1

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 (2) hide show
  1. package/README.md +4 -145
  2. package/package.json +3 -2
package/README.md CHANGED
@@ -153,151 +153,10 @@ tables throws `RetirementFactorOutOfRange`.
153
153
 
154
154
  ## API reference
155
155
 
156
- ### Scales (`scales.ts`)
157
-
158
- | Export | Description |
159
- | ---------------------- | ------------------------------------ |
160
- | `AFC_BANDS` | Band key-to-ID mapping |
161
- | `AFC_BAND_IDS` | Ordered array of all band IDs |
162
- | `AFC_TAX_YEARS` | Tax years with available scale data |
163
- | `AFC_HOURS_PER_YEAR` | Standard AfC hours (1950) |
164
- | `NLW_HOURLY` | National Living Wage by year |
165
- | `WALES_LW_FLOOR` | Welsh Government living wage floor |
166
- | `annualiseHourly` | Convert hourly rate to annual salary |
167
- | `applyWalesFloor` | Apply Wales living wage floor |
168
-
169
- **Types:** `AfcBandId`, `ScalePoint`, `HcasZone`,
170
- `HcasZones`
171
-
172
- ### Pension (`pension.ts`)
173
-
174
- | Export | Description |
175
- | ------------------- | ---------------------------------- |
176
- | `getPensionTiers` | Pension tiers for a tax year |
177
- | `pensionTierRate` | Contribution rate (%) for a salary |
178
- | `lookupPensionTier` | Full tier info for a salary |
179
-
180
- **Types:** `PensionTier`
181
-
182
- ### Pension projection (`pension-projection.ts`)
183
-
184
- | Export | Description |
185
- | -------------------- | ---------------------------------------------- |
186
- | `projectPension` | Full 2015-scheme projection with chart curve |
187
- | `retirementFactor` | ERF/LRF factor for retirement vs NPA date |
188
- | `commute` | Lump-sum commutation at a fraction of the max |
189
- | `maxLumpSum` | Maximum tax-free lump sum (HMRC 25% rule) |
190
- | `yearlyAccrual` | One year's pension accrual |
191
- | `ACCRUAL_RATE` | 1/54 CARE accrual rate |
192
- | `COMMUTATION_FACTOR` | £12 lump sum per £1 pension |
193
-
194
- `projectPension(input, today?)` takes an optional evaluation
195
- date (defaults to now) — inject a fixed date for reproducible
196
- output. Date plumbing, raw revaluation maths and the GAD factor
197
- tables are deliberately private: factors are reachable only
198
- through `retirementFactor` / `projectPension`, which own the
199
- GAD rounding rules.
200
-
201
- **Types:** `PensionProjectionInput` (`PensionStatementInput` |
202
- `PensionEstimationInput`), `PensionProjectionResult`,
203
- `ProjectionPoint`, `CommutationResult`, `FactorTableKind`
204
-
205
- ### HCAS (`hcas.ts`)
206
-
207
- | Export | Description |
208
- | ------------------------ | ------------------------------ |
209
- | `HCAS_ZONE_IDS` | Zone key-to-ID mapping |
210
- | `calculateHcasSupplement`| HCAS amount for base + zone |
211
- | `grossSalary` | Base + Wales floor + HCAS |
212
- | `isHcasZoneId` | Type guard for zone IDs |
213
-
214
- **Types:** `HcasZoneId`
215
-
216
- ### HCAS PCTs (`hcas-pcts.ts`)
217
-
218
- | Export | Description |
219
- | ------------------- | ------------------------------------ |
220
- | `getHcasZone` | PCT → HCAS zone lookup |
221
- | `getHcasPcts` | All PCTs with zone, in order |
222
-
223
- **Types:** `HcasPct`
224
-
225
- ### Regions (`regions.ts`)
226
-
227
- | Export | Description |
228
- | ------------------- | ------------------------------------ |
229
- | `AFC_REGIONS` | Region key-to-ID mapping |
230
- | `ZONE_TO_REGION` | HCAS zone → AFC region mapping |
231
- | `resolveRegion` | Resolve region to tax/HCAS/label |
232
- | `afcRegionToNation` | Map region to paye-calc Nation |
233
- | `isAfcRegionId` | Type guard for region IDs |
234
- | `isNation` | Type guard for Nation strings |
235
-
236
- **Types:** `AfcRegionId`, `ResolvedRegion`
237
-
238
- ### Bands (`bands.ts`)
239
-
240
- | Export | Description |
241
- | ------------------- | ------------------------------------ |
242
- | `getAfcScales` | Band + scale + pension, nation-aware |
243
- | `AFC_CURRENT_YEAR` | Current financial year |
244
- | `AFC_PREVIOUS_YEAR` | Previous financial year |
245
-
246
- **Types:** `AfcBandMeta`, `AfcScaleData`
247
-
248
- ### Take-home (`take-home.ts`)
249
-
250
- | Export | Description |
251
- | -------------- | ------------------------------------- |
252
- | `nhsTakeHome` | Pre-configured TakeHomePay for NHS |
253
-
254
- ### Medical & dental (`medical-scales.ts`, `dental-scales.ts`, `resolver.ts`)
255
-
256
- | Export | Description |
257
- | ------------------ | --------------------------------------------- |
258
- | `getMedicalScales` | Doctor grades for a nation/year, with points |
259
- | `getDentalScales` | Salaried dental grades for a nation/year |
260
- | `medicalResolver` | Build a `Post` from a doctor grade + point |
261
- | `dentalResolver` | Build a `Post` from a dental grade + point |
262
-
263
- Each resolver exposes `fromScalePoint(grade, pointLabel, nation,
264
- year)`, `fromSalary`, `availableGrades(nation, year)` and
265
- `latestYearFor(grade, nation)`. See
266
- [Medical & dental pay scales](#medical--dental-pay-scales) for how
267
- the data is sourced and modelled.
268
-
269
- **Types:** `MedicalGradeId`, `DentalGradeId`, `MedicalGradeMeta`,
270
- `DentalGradeMeta`, `MedicalRole`, `DentalRole`, `Role`, `Post`
271
-
272
- ### Format (`format.ts`)
273
-
274
- | Export | Description |
275
- | ----------------- | ----------------------------------- |
276
- | `fmtSalary` | Format exact salary (e.g. £31,049) |
277
- | `formatGBP` | Format GBP, no decimals |
278
- | `formatGBPPrecise` | Format GBP with pence |
279
- | `fmtMoney` | Format rounded money |
280
- | `fmtPct` | Format percentage (e.g. 8.3%) |
281
- | `formatPct` | Format percentage (Intl) |
282
- | `yearLabel` | Convert '2025-26' to '2025/26' |
283
-
284
- ### Errors (`errors.ts`)
285
-
286
- All data lookups fail loud rather than defaulting:
287
-
288
- | Export | Thrown when |
289
- | ---------------------------- | -------------------------------------- |
290
- | `ScaleUnavailable` | Unpublished nation/year/grade queried |
291
- | `PensionTiersUnavailable` | No pension tiers for a year/nation |
292
- | `AwardUnavailable` | No pay award for a year/nation |
293
- | `RetirementFactorOutOfRange` | Retirement period beyond the GAD table |
294
-
295
- ### Re-exports from paye-calc
296
-
297
- `TAX_REGIONS`, `TAX_YEARS`, `NATIONS`, `NATION_KEYS`,
298
- `TakeHomePay`, `GrossAnnual`, `PensionBasis`,
299
- `PensionPercent`, `StudentLoanPlan`, `nationToTaxRegion`,
300
- and types `Nation`, `TaxRegion`, `TaxYear`.
156
+ [`docs/api.md`](docs/api.md) — every export, organised by
157
+ domain, with typed signatures and short notes. Kept in sync with
158
+ the code by a check-time drift gate. Agents may prefer the
159
+ shipped `dist/*.d.ts`, which carry the full JSDoc per module.
301
160
 
302
161
  ## Data sources
303
162
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@casomoltd/nhs-pay",
3
- "version": "0.10.0",
3
+ "version": "0.10.1",
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",
@@ -25,7 +25,8 @@
25
25
  "test:watch": "vitest",
26
26
  "knip": "knip",
27
27
  "jscpd": "jscpd ./src",
28
- "check": "npm run lint && npm run typecheck && npm run knip && npm run jscpd && npm run test",
28
+ "check:docs": "node scripts/check-api-docs.mjs",
29
+ "check": "npm run lint && npm run typecheck && npm run knip && npm run jscpd && npm run check:docs && npm run test",
29
30
  "prepare": "husky"
30
31
  },
31
32
  "repository": {