@casomoltd/nhs-pay 0.13.2 → 0.15.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/LICENSE +656 -160
- package/README.md +70 -6
- package/dist/commutation.d.ts +331 -0
- package/dist/commutation.js +324 -0
- package/dist/commutation.js.map +1 -0
- package/dist/index.d.ts +5 -2
- package/dist/index.js +6 -1
- package/dist/index.js.map +1 -1
- package/dist/pension/money.d.ts +34 -0
- package/dist/pension/money.js +2 -0
- package/dist/pension/money.js.map +1 -0
- package/dist/pension/prices.d.ts +25 -3
- package/dist/pension/prices.js +6 -1
- package/dist/pension/prices.js.map +1 -1
- package/dist/pension-projection.d.ts +14 -80
- package/dist/pension-projection.js +8 -58
- package/dist/pension-projection.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -124,7 +124,12 @@ unpublished nation/year or grade rather than defaulting.
|
|
|
124
124
|
### Project a 2015-scheme pension
|
|
125
125
|
|
|
126
126
|
```ts
|
|
127
|
-
import {
|
|
127
|
+
import {
|
|
128
|
+
COMMUTATION_FACTOR,
|
|
129
|
+
LUMP_SUM_ALLOWANCE,
|
|
130
|
+
commute,
|
|
131
|
+
projectPension,
|
|
132
|
+
} from '@casomoltd/nhs-pay';
|
|
128
133
|
|
|
129
134
|
const projection = projectPension({
|
|
130
135
|
kind: 'statement',
|
|
@@ -141,11 +146,52 @@ console.log(projection.annualPension); // after ERF/LRF
|
|
|
141
146
|
console.log(projection.factorType); // 'erf'
|
|
142
147
|
console.log(projection.curve); // chart-ready points
|
|
143
148
|
|
|
144
|
-
|
|
145
|
-
|
|
149
|
+
// Commutation takes the whole {nominal, real, asAt} figure, not
|
|
150
|
+
// one side of it: the lump sum allowance is a cash amount tested
|
|
151
|
+
// on a date, so a dateless number could not say which ruler it
|
|
152
|
+
// was in. Every limit is required for the same reason — a
|
|
153
|
+
// default would answer a question the caller did not ask.
|
|
154
|
+
const {lumpSum, residualPension, limit} = commute(
|
|
155
|
+
projection.annualPension,
|
|
156
|
+
1, // take the permitted maximum
|
|
157
|
+
{
|
|
158
|
+
commutationFactor: COMMUTATION_FACTOR,
|
|
159
|
+
allowance: {
|
|
160
|
+
amount: LUMP_SUM_ALLOWANCE,
|
|
161
|
+
asAt: new Date(2026, 2, 31),
|
|
162
|
+
},
|
|
163
|
+
// The run's OWN price series, so the allowance is carried
|
|
164
|
+
// forward at the rate the pension was projected at.
|
|
165
|
+
prices: projection.prices,
|
|
166
|
+
},
|
|
146
167
|
);
|
|
168
|
+
console.log(lumpSum.real, lumpSum.nominal); // both rulers
|
|
169
|
+
// The maximum, and which cap stopped it — PER RULER.
|
|
170
|
+
console.log(limit.real.amount, limit.real.binding);
|
|
171
|
+
console.log(limit.nominal.amount, limit.nominal.binding);
|
|
147
172
|
```
|
|
148
173
|
|
|
174
|
+
The maximum is the **lower** of two caps, and **both are
|
|
175
|
+
statutory**: 25% of the capital value of the benefits, and the
|
|
176
|
+
Lump Sum Allowance. The scheme's own contribution to the swap is
|
|
177
|
+
the 12:1 rate and nothing else, so a consumer must not attribute
|
|
178
|
+
the 25% to the scheme — `LUMP_SUM_CAPS.Scheme` names the
|
|
179
|
+
discriminant, not the rule's author. `binding` says which cap
|
|
180
|
+
stopped it, so a consumer can explain the figure rather than
|
|
181
|
+
restate the rule.
|
|
182
|
+
|
|
183
|
+
Why that name is left as it is, and what moves where when it
|
|
184
|
+
changes: [*The two caps on tax-free
|
|
185
|
+
cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
|
|
186
|
+
|
|
187
|
+
There is **one limit per ruler, and no single flag**, because the
|
|
188
|
+
two can genuinely disagree: `real` is the model run at zero CPI
|
|
189
|
+
while the allowance is carried forward at CPI, so around the
|
|
190
|
+
crossover the allowance binds in today's money while the scheme
|
|
191
|
+
limb still binds in cash. Show the limit belonging to the ruler
|
|
192
|
+
on screen. See
|
|
193
|
+
[*The two caps on tax-free cash*](docs/how-it-works.md#the-two-caps-on-tax-free-cash).
|
|
194
|
+
|
|
149
195
|
Without a statement figure, `kind: 'estimation'` accrues from a
|
|
150
196
|
`joinDate` instead. ERF/LRF factors are transcribed verbatim from
|
|
151
197
|
the GAD consolidated factor workbook (30 June 2023 issue) with
|
|
@@ -190,9 +236,17 @@ Table A25 (AfC 2025/26 data for England, NI, Wales).
|
|
|
190
236
|
| September CPI + in-service rate | [HM Treasury Revaluation Orders][sis], one SI per year |
|
|
191
237
|
| Accrual rate, NPA | NHSBSA 2015 Members' Guide (V13) |
|
|
192
238
|
| ERF / LRF factors | GAD NHS EW consolidated factor workbook |
|
|
193
|
-
| Commutation | NHSBSA Key Notes — 2015 Scheme Estimates (V2) |
|
|
239
|
+
| Commutation rate (£12 : £1) | NHSBSA Key Notes — 2015 Scheme Estimates (V2) |
|
|
240
|
+
| Permitted maximum (lowest of three limbs) | [Sch 29 Finance Act 2004 para 2][sch29] |
|
|
241
|
+
| Applicable amount, defined benefits, `(A + (B × C)) / 4` | [Sch 29 Finance Act 2004 para 2C][sch29p2c] |
|
|
242
|
+
| Relevant valuation factor (20) | [Finance Act 2004 s.276][s276] |
|
|
243
|
+
| Lump Sum Allowance (£268,275, frozen) | [ITEPA 2003 s.637P][s637p] |
|
|
194
244
|
|
|
195
245
|
[sis]: https://www.legislation.gov.uk/secondary/public+service+pensions
|
|
246
|
+
[sch29]: https://www.legislation.gov.uk/ukpga/2004/12/schedule/29
|
|
247
|
+
[sch29p2c]: https://www.legislation.gov.uk/ukpga/2004/12/schedule/29/paragraph/2C
|
|
248
|
+
[s276]: https://www.legislation.gov.uk/ukpga/2004/12/section/276
|
|
249
|
+
[s637p]: https://www.legislation.gov.uk/ukpga/2003/1/part/9/chapter/15A
|
|
196
250
|
|
|
197
251
|
Reconciled line by line against a real **Annual Benefit
|
|
198
252
|
Statement** (2015 Section, updated to 31/03/2025, name and
|
|
@@ -371,7 +425,8 @@ NI 2025/26) — see
|
|
|
371
425
|
## Development
|
|
372
426
|
|
|
373
427
|
```bash
|
|
374
|
-
npm run check # lint + typecheck + knip + jscpd
|
|
428
|
+
npm run check # lint + typecheck + knip + jscpd
|
|
429
|
+
# + api-docs drift gate + test
|
|
375
430
|
npm run build # compile to dist/
|
|
376
431
|
npm test # vitest
|
|
377
432
|
npm run test:watch # vitest watch mode
|
|
@@ -379,4 +434,13 @@ npm run test:watch # vitest watch mode
|
|
|
379
434
|
|
|
380
435
|
## License
|
|
381
436
|
|
|
382
|
-
|
|
437
|
+
AGPL-3.0-only — see [LICENSE](LICENSE).
|
|
438
|
+
Copyright © 2026 Casomo Ltd.
|
|
439
|
+
|
|
440
|
+
There is no linking exception: combine this library with your
|
|
441
|
+
own code and the combined work is AGPL too, and letting people
|
|
442
|
+
use that work over a network obliges you to offer them its
|
|
443
|
+
source. Charging money is not what triggers this, and not
|
|
444
|
+
charging is no exemption. A commercial licence is available for
|
|
445
|
+
use that needs to stay closed — enquire via
|
|
446
|
+
[casomoltd.com](https://casomoltd.com).
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Commutation — exchanging annual pension for a tax-free lump
|
|
3
|
+
* sum, and the caps on how much of it may be taken.
|
|
4
|
+
*
|
|
5
|
+
* Separate from the projection because it IS separate: nothing
|
|
6
|
+
* in `pension-projection.ts` calls into here and the ledger
|
|
7
|
+
* applies no commutation. It is a choice taken AT retirement, on
|
|
8
|
+
* a pension the projection has already finished producing. It
|
|
9
|
+
* borrows one thing, by type only: the `Prices` the projection
|
|
10
|
+
* ran with, so the allowance is carried forward at the SAME
|
|
11
|
+
* assumption the pension was projected at and cannot silently
|
|
12
|
+
* use another.
|
|
13
|
+
*
|
|
14
|
+
* ── Only one figure here is an NHS rule ─────────────
|
|
15
|
+
*
|
|
16
|
+
* The commutation RATE — £12 of cash per £1 of pension — is the
|
|
17
|
+
* scheme's own. The three caps are statutory and bind every
|
|
18
|
+
* registered pension scheme in the UK: the 25% of capital value,
|
|
19
|
+
* the 20:1 factor that capital value is measured with, and the
|
|
20
|
+
* Lump Sum Allowance. They are grouped apart below, and the
|
|
21
|
+
* scheme's rate is passed to the solver as a parameter rather
|
|
22
|
+
* than read from the module, so the statutory half can move to a
|
|
23
|
+
* scheme-neutral home without a redesign.
|
|
24
|
+
*/
|
|
25
|
+
import type { ProjectionMoney } from './pension/money.js';
|
|
26
|
+
import type { Prices } from './pension/prices.js';
|
|
27
|
+
/**
|
|
28
|
+
* Commutation: £12 lump sum per £1 of annual pension given up.
|
|
29
|
+
*
|
|
30
|
+
* The NHS scheme's rate. Other schemes commute at other rates,
|
|
31
|
+
* which is why {@link lumpSumLimit} takes it as an argument
|
|
32
|
+
* instead of reading it here.
|
|
33
|
+
*
|
|
34
|
+
* Source: NHSBSA Key Notes, 2015 Scheme Estimates (V2) —
|
|
35
|
+
* **not archived**; see docs/how-it-works.md's source table.
|
|
36
|
+
* NHSBSA states the same terms to members, publicly, at
|
|
37
|
+
* <https://www.nhsbsa.nhs.uk/employee-section/
|
|
38
|
+
* understanding-your-statement/maximum-lump-sum> ("reducing your
|
|
39
|
+
* pension by £1 for every £12"). Named here as well as in the
|
|
40
|
+
* table because the Key Notes document has no public URL, so
|
|
41
|
+
* without it this constant is the one figure in the module a
|
|
42
|
+
* reader cannot go and check.
|
|
43
|
+
*/
|
|
44
|
+
export declare const COMMUTATION_FACTOR = 12;
|
|
45
|
+
/**
|
|
46
|
+
* The most of a member's benefits HMRC lets them take as a
|
|
47
|
+
* tax-free lump sum, as a percentage.
|
|
48
|
+
*
|
|
49
|
+
* Exported because it is the only part of the commutation rule
|
|
50
|
+
* a member can be told directly — {@link lumpSumLimit} is the
|
|
51
|
+
* cap in pounds, which answers "how much" but never "why that
|
|
52
|
+
* much". A consumer explaining the swap needs this figure, and
|
|
53
|
+
* a consumer that writes its own copy of it is one that can
|
|
54
|
+
* drift from the library that applies it.
|
|
55
|
+
*
|
|
56
|
+
* THIS IS THE FORM THE STATUTE USES. Schedule 29 FA 2004
|
|
57
|
+
* paragraph 2C gives the defined-benefits applicable amount as
|
|
58
|
+
* `(A + (B × C)) / 4`, where A is the amount of the lump sum, B
|
|
59
|
+
* is the relevant valuation factor ({@link VALUATION_FACTOR})
|
|
60
|
+
* and C is the pension payable in the 12 months beginning with
|
|
61
|
+
* the day the member becomes entitled to it. `A + (B × C)` IS
|
|
62
|
+
* the capital value, so a quarter of it is this constant.
|
|
63
|
+
*
|
|
64
|
+
* Two things follow, and both are load-bearing. C is the pension
|
|
65
|
+
* AFTER commutation, which is what makes the cap a fixed point
|
|
66
|
+
* rather than a percentage of anything the caller already holds.
|
|
67
|
+
* And the one-third-of-the-remaining-pension form that guidance
|
|
68
|
+
* often quotes is this same rule solved for A: 4A = A + (B × C)
|
|
69
|
+
* gives A = B × C / 3. Both reach 30P/7 at a 12:1 rate, verified
|
|
70
|
+
* numerically either way. Do NOT "correct" this constant to a
|
|
71
|
+
* third — it would be the same number and the wrong citation.
|
|
72
|
+
*
|
|
73
|
+
* Source: Schedule 29 Finance Act 2004, paragraphs 2 (the
|
|
74
|
+
* permitted maximum is the LOWEST of three amounts) and 2C (the
|
|
75
|
+
* defined-benefits applicable amount, which invokes B by
|
|
76
|
+
* reference to s.276 rather than restating 20). Verified against
|
|
77
|
+
* the Act on 27 August 2026. Paragraph 2C's formula is published
|
|
78
|
+
* as an image, so its shape is corroborated by the variable
|
|
79
|
+
* definitions in the surrounding text and by HMRC's own
|
|
80
|
+
* 20P / (3 + 20/CF), which agrees to the penny.
|
|
81
|
+
*/
|
|
82
|
+
export declare const HMRC_LUMP_SUM_CAP_PCT = 25;
|
|
83
|
+
/**
|
|
84
|
+
* The statutory factor turning an annual defined-benefit pension
|
|
85
|
+
* into a capital value: capital value is 20 × annual pension.
|
|
86
|
+
*
|
|
87
|
+
* Named because it is a RULE, not arithmetic. A statutory
|
|
88
|
+
* factor written as a bare `20` inside an expression is
|
|
89
|
+
* invisible to a search, to a citation and to a test, and reads
|
|
90
|
+
* as a coefficient someone chose.
|
|
91
|
+
*
|
|
92
|
+
* Reached by reference, not by repetition: Schedule 29 paragraph
|
|
93
|
+
* 2C names "the relevant valuation factor" as its B rather than
|
|
94
|
+
* writing 20 into the lump sum rule, so the factor and the cap
|
|
95
|
+
* are one rule in two provisions and a change to s.276 would
|
|
96
|
+
* move the cap without touching Schedule 29.
|
|
97
|
+
*
|
|
98
|
+
* Source: Finance Act 2004 s.276, "Relevant valuation factor":
|
|
99
|
+
* "the relevant valuation factor in relation to any registered
|
|
100
|
+
* pension scheme, or any arrangement under a registered pension
|
|
101
|
+
* scheme, is 20", unless a higher one is agreed with HMRC.
|
|
102
|
+
* Verified against the Act on 27 August 2026.
|
|
103
|
+
*/
|
|
104
|
+
export declare const VALUATION_FACTOR = 20;
|
|
105
|
+
/**
|
|
106
|
+
* The Lump Sum Allowance: the absolute cap on tax-free pension
|
|
107
|
+
* cash, in pounds.
|
|
108
|
+
*
|
|
109
|
+
* £268,275 since 6 April 2024, when it replaced the Lifetime
|
|
110
|
+
* Allowance. FROZEN IN LAW — it is not indexed, so its real
|
|
111
|
+
* value erodes every year it stands.
|
|
112
|
+
*
|
|
113
|
+
* "Frozen" states the LAW, not how a projection should treat it.
|
|
114
|
+
* Whether to carry this figure forward in real terms is the
|
|
115
|
+
* CALLER's assumption, declared through
|
|
116
|
+
* {@link CommutationLimits.allowance}. Do not read this comment
|
|
117
|
+
* as an instruction to hold the figure fixed in cash.
|
|
118
|
+
*
|
|
119
|
+
* This is the STANDARD allowance. A member holding a Lifetime
|
|
120
|
+
* Allowance protection has a higher one — HMRC PTM174700 puts
|
|
121
|
+
* fixed protection 2016 at £312,500, 2014 at £375,000 and 2012
|
|
122
|
+
* at £450,000, with the other classes worked out per member.
|
|
123
|
+
* None of them is modelled here and none is detectable from
|
|
124
|
+
* what this library is given.
|
|
125
|
+
*
|
|
126
|
+
* Source: ITEPA 2003 s.637P, verified against the Act on
|
|
127
|
+
* 27 August 2026 — <https://www.legislation.gov.uk/ukpga/2003/1/
|
|
128
|
+
* part/9/chapter/15A>. Cited to the instrument rather than to
|
|
129
|
+
* HMRC's Pensions Tax Manual, which is written for
|
|
130
|
+
* administrators and gave the wrong section number when this
|
|
131
|
+
* figure was first transcribed. Its source-archive row is in
|
|
132
|
+
* docs/how-it-works.md.
|
|
133
|
+
*/
|
|
134
|
+
export declare const LUMP_SUM_ALLOWANCE = 268275;
|
|
135
|
+
/**
|
|
136
|
+
* The two limbs of the permitted maximum, as a const object so
|
|
137
|
+
* the keys are reachable at a call site instead of a bare
|
|
138
|
+
* literal repeated across modules.
|
|
139
|
+
*
|
|
140
|
+
* `Scheme` IS A MISLEADING NAME AND IS KNOWN TO BE. Both limbs
|
|
141
|
+
* are statutory and bind every registered pension scheme in the
|
|
142
|
+
* UK; the scheme's only contribution to this swap is
|
|
143
|
+
* {@link COMMUTATION_FACTOR}. The name has already leaked into
|
|
144
|
+
* prose that told members "the scheme stops the swap at 25%",
|
|
145
|
+
* which was wrong wherever it appeared.
|
|
146
|
+
*
|
|
147
|
+
* It is not renamed in place on purpose. The whole statutory
|
|
148
|
+
* half of this module moves to the UK-tax library
|
|
149
|
+
* (casomoltd/nhs-pay#15, casomoltd/paye-calc#30), and renaming
|
|
150
|
+
* here as well would spend two breaking changes on one defect.
|
|
151
|
+
* When the rule lands in its new home the key should be named
|
|
152
|
+
* for the statute — `Applicable`, after the applicable amount
|
|
153
|
+
* in Schedule 29 paragraph 2C.
|
|
154
|
+
*
|
|
155
|
+
* Until then: read `Scheme` as the name of a discriminant, not
|
|
156
|
+
* as an attribution, and never render it to a member.
|
|
157
|
+
*/
|
|
158
|
+
export declare const LUMP_SUM_CAPS: {
|
|
159
|
+
readonly Scheme: "scheme";
|
|
160
|
+
readonly Allowance: "allowance";
|
|
161
|
+
};
|
|
162
|
+
/** Which limb of the permitted maximum bound. */
|
|
163
|
+
export type LumpSumCap = (typeof LUMP_SUM_CAPS)[keyof typeof LUMP_SUM_CAPS];
|
|
164
|
+
/**
|
|
165
|
+
* A cash amount and the date it is stated in.
|
|
166
|
+
*
|
|
167
|
+
* The pairing is the point. An amount without its date cannot be
|
|
168
|
+
* moved into another ruler, and it cannot say which ruler it is
|
|
169
|
+
* already in — cash at retirement and today's money are the same
|
|
170
|
+
* number in different units. A function handed a bare number has
|
|
171
|
+
* to assume one, and its assumption is unwritten.
|
|
172
|
+
*/
|
|
173
|
+
export interface DatedAmount {
|
|
174
|
+
readonly amount: number;
|
|
175
|
+
readonly asAt: Date;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Everything the permitted maximum depends on besides the
|
|
179
|
+
* pension itself.
|
|
180
|
+
*
|
|
181
|
+
* EVERY FIELD IS REQUIRED. Each selects WHICH answer you get,
|
|
182
|
+
* not how it is computed, so a default would hand a
|
|
183
|
+
* plausible-but-wrong figure to a caller who forgot it — with no
|
|
184
|
+
* error, no type failure and no failing test. A cap is exactly
|
|
185
|
+
* the kind of figure that looks right at every value except the
|
|
186
|
+
* ones it exists to catch.
|
|
187
|
+
*/
|
|
188
|
+
export interface CommutationLimits {
|
|
189
|
+
/**
|
|
190
|
+
* The SCHEME's commutation rate — £ of lump sum per £1 of
|
|
191
|
+
* pension. {@link COMMUTATION_FACTOR} for the NHS. The only
|
|
192
|
+
* non-statutory input here.
|
|
193
|
+
*/
|
|
194
|
+
readonly commutationFactor: number;
|
|
195
|
+
/**
|
|
196
|
+
* The lump sum allowance, and the date it is stated in.
|
|
197
|
+
*
|
|
198
|
+
* Modelled as a REAL-TERMS constant: the today's-money run
|
|
199
|
+
* tests `amount` as given, and the cash run tests the same cap
|
|
200
|
+
* carried forward to the pension's own date. That is an
|
|
201
|
+
* assumption — the allowance is frozen in law — and a consumer
|
|
202
|
+
* showing these figures should say so.
|
|
203
|
+
*/
|
|
204
|
+
readonly allowance: DatedAmount;
|
|
205
|
+
/**
|
|
206
|
+
* The price series the pension was PROJECTED with, used to
|
|
207
|
+
* carry the allowance to the pension's own date.
|
|
208
|
+
*
|
|
209
|
+
* PASS THE ONE FROM `projectPension`'s RESULT. Taking the
|
|
210
|
+
* object rather than a bare rate removes the need to restate
|
|
211
|
+
* the assumption, and gives the conversion the run's own
|
|
212
|
+
* anchor — but it does not make a mismatch impossible:
|
|
213
|
+
* `createPrices` is exported, so a caller can still build a
|
|
214
|
+
* series the pension was never projected with. That is a
|
|
215
|
+
* caller error this library cannot detect.
|
|
216
|
+
*/
|
|
217
|
+
readonly prices: Prices;
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* The NHS binding of {@link CommutationLimits}.
|
|
221
|
+
*
|
|
222
|
+
* Every field of that interface is required so a non-NHS caller
|
|
223
|
+
* cannot inherit an NHS default by omitting one. That stops a
|
|
224
|
+
* field being LEFT OUT; it does nothing to stop several call
|
|
225
|
+
* sites each assembling the same NHS combination by hand and one
|
|
226
|
+
* of them getting it subtly wrong — a different `asAt`, a
|
|
227
|
+
* `createPrices` of its own, a literal `12`. Two consumers
|
|
228
|
+
* already spelled the date two ways.
|
|
229
|
+
*
|
|
230
|
+
* So the combination is published once, here, beside the
|
|
231
|
+
* constants it pairs. Pass the `prices` your own projection
|
|
232
|
+
* returned; the allowance is stated at that run's anchor,
|
|
233
|
+
* because these are the prices that will convert it and
|
|
234
|
+
* anchoring it anywhere else converts it across a gap the
|
|
235
|
+
* projection never travelled.
|
|
236
|
+
*/
|
|
237
|
+
export declare function nhsCommutationLimits(prices: Prices): CommutationLimits;
|
|
238
|
+
/**
|
|
239
|
+
* The permitted maximum tax-free lump sum, and the working
|
|
240
|
+
* behind it.
|
|
241
|
+
*
|
|
242
|
+
* A value object rather than a number because a consumer that
|
|
243
|
+
* stops a control at this figure has to be able to say WHY it
|
|
244
|
+
* stopped, and a UI that re-derives "was it the allowance?" from
|
|
245
|
+
* a comparison keeps a second copy of the rule in the layer
|
|
246
|
+
* least able to test it.
|
|
247
|
+
*/
|
|
248
|
+
export interface LumpSumLimit {
|
|
249
|
+
/** The permitted maximum: the lower of the two limbs. */
|
|
250
|
+
readonly amount: number;
|
|
251
|
+
/**
|
|
252
|
+
* Which limb set `amount`. Equal limbs report `Allowance` — at
|
|
253
|
+
* the crossover the allowance is what stops it moving.
|
|
254
|
+
*/
|
|
255
|
+
readonly binding: LumpSumCap;
|
|
256
|
+
/** The applicable-amount limb, before the allowance. */
|
|
257
|
+
readonly schemeMax: number;
|
|
258
|
+
/**
|
|
259
|
+
* The allowance actually tested against, in this ruler — so a
|
|
260
|
+
* consumer cites the figure that was applied rather than the
|
|
261
|
+
* statutory one it assumes was applied.
|
|
262
|
+
*/
|
|
263
|
+
readonly allowance: number;
|
|
264
|
+
/**
|
|
265
|
+
* `amount` as a share of the capital value of the benefits,
|
|
266
|
+
* in percentage points.
|
|
267
|
+
*
|
|
268
|
+
* The unit the statute states the rule in, and the one a
|
|
269
|
+
* member can check the rule against — so it is reported here
|
|
270
|
+
* rather than left to a consumer to re-derive from the capital
|
|
271
|
+
* value, which is not a figure this library otherwise hands
|
|
272
|
+
* out. It is HMRC_LUMP_SUM_CAP_PCT exactly when the scheme
|
|
273
|
+
* limb binds, and LESS when the allowance does: a flat cash
|
|
274
|
+
* cap is a smaller share of a larger pension. A control whose
|
|
275
|
+
* ceiling is labelled 25% while the allowance binds is telling
|
|
276
|
+
* the member a share they are not taking.
|
|
277
|
+
*/
|
|
278
|
+
readonly sharePct: number;
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* One reading per ruler.
|
|
282
|
+
*
|
|
283
|
+
* Named rather than left inline because it is public API: a
|
|
284
|
+
* consumer writing a caption helper should not have to spell
|
|
285
|
+
* `CommutationResult['limit']` to type its argument.
|
|
286
|
+
*/
|
|
287
|
+
export interface LumpSumLimits {
|
|
288
|
+
readonly real: LumpSumLimit;
|
|
289
|
+
readonly nominal: LumpSumLimit;
|
|
290
|
+
}
|
|
291
|
+
/** Commutation, in both rulers, from one call. */
|
|
292
|
+
export interface CommutationResult {
|
|
293
|
+
readonly pensionGivenUp: ProjectionMoney;
|
|
294
|
+
readonly residualPension: ProjectionMoney;
|
|
295
|
+
readonly lumpSum: ProjectionMoney;
|
|
296
|
+
/**
|
|
297
|
+
* The full working behind each ruler's maximum — which limb
|
|
298
|
+
* bound it, and both limbs' figures.
|
|
299
|
+
*
|
|
300
|
+
* TWO limits, not one flag, because the rulers can genuinely
|
|
301
|
+
* disagree about which limb stopped the lump sum. They are not
|
|
302
|
+
* one walk in different units: `real` is the model run at zero
|
|
303
|
+
* CPI, growing 1.5% a year, while the allowance is carried
|
|
304
|
+
* forward at CPI — so the pension's real-to-cash ratio and the
|
|
305
|
+
* allowance's are different numbers. Around the crossover
|
|
306
|
+
* there is a band where the allowance binds in today's money
|
|
307
|
+
* and the scheme limb still binds in cash. A consumer shows
|
|
308
|
+
* the limit for the ruler it is displaying; one flag for both
|
|
309
|
+
* would caption one column with the other's reason.
|
|
310
|
+
*
|
|
311
|
+
* The maximum itself is `limit.<ruler>.amount`. It is not also
|
|
312
|
+
* reported as a pair: two shapes for one number is two places
|
|
313
|
+
* an edit can change it.
|
|
314
|
+
*/
|
|
315
|
+
readonly limit: LumpSumLimits;
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Commutation at a fraction of the permitted maximum, reported
|
|
319
|
+
* in both rulers.
|
|
320
|
+
*
|
|
321
|
+
* Takes the pension as a {@link ProjectionMoney} rather than a
|
|
322
|
+
* bare number so the ruler travels with the money. A dateless
|
|
323
|
+
* figure cannot say which ruler it is in, and the allowance is a
|
|
324
|
+
* cash amount tested on a date — so the two could only be
|
|
325
|
+
* compared by assuming, which is the defect this signature
|
|
326
|
+
* removes.
|
|
327
|
+
*
|
|
328
|
+
* ERF/LRF is applied BEFORE commutation (§1.18), so `pension` is
|
|
329
|
+
* the pension at retirement after any factor.
|
|
330
|
+
*/
|
|
331
|
+
export declare function commute(pension: ProjectionMoney, fraction: number, limits: CommutationLimits): CommutationResult;
|