payroll.net-to-gross Unreviewed

export function netToGross(targetNet: Money, input: PayslipInput): Payslip

import { netToGross } from "#fune/payroll.net-to-gross@^1";

import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { grossToNet } from "./payroll_gross_to_net.ts";  ← from payroll.gross-to-net ^1.0.0 · built alongside by fune
import { type Payslip, type PayslipInput } from "./payroll_gross_to_net_types.ts";

/** The search refuses to look above £10,000,000 of gross pay for one period. */
const CEILING = 1_000_000_000;

/**
 * Gross up a net payment: the gross pay whose payslip nets at least the target.
 *
 * Net pay is not a smooth function of gross: tax is on whole pounds, student
 * loans are rounded down to whole pounds, and pension and NI thresholds switch
 * on. So there is no formula to invert, and a search is the honest method. It
 * is a bisection on whole pence, with fixed bounds and midpoints, so it takes
 * the same steps and finds the same answer in every language: a gross G whose
 * net is at least the target while the net at G - 1p is below it.
 */
export function netToGross(targetNet: Money, input: PayslipInput): Payslip {
  if (targetNet.currency !== "GBP") {
    throw new RangeError(`payroll amounts must be in GBP, received ${targetNet.currency} for targetNet`);
  }
  if (targetNet.minor <= 0) {
    throw new RangeError(`targetNet must be more than zero, received ${targetNet.minor}`);
  }
  const slip = (gross: number): Payslip => grossToNet({ ...input, gross: money(gross, "GBP") });

  // A refund can make net exceed gross, so zero gross may already be enough.
  const atZero = slip(0);
  if (atZero.net.minor >= targetNet.minor) return atZero;

  let low = 0;
  let high = targetNet.minor;
  while (slip(high).net.minor < targetNet.minor) {
    low = high;
    high = high * 2;
    if (high > CEILING) {
      throw new RangeError(`no gross pay up to ${CEILING} pence gives a net of ${targetNet.minor} pence`);
    }
  }
  while (high - low > 1) {
    const middle = Math.floor((low + high) / 2);
    if (slip(middle).net.minor >= targetNet.minor) high = middle;
    else low = middle;
  }
  return slip(high);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add payroll.net-to-gross

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./payroll.net-to-gross-1.0.2-typescript.fune, or fetch it from a terminal with fune pull payroll.net-to-gross@1.0.2:typescript.

The whole function, every language, is one file too: payroll.net-to-gross-1.0.2.fune, 28,658 bytes, sha256 6d4d7589fc87a348906f02e669c8a9c62ad3d58e752a098cb284865d169b75fd. It installs into a project of any language.

// fune: before payroll.net-to-gross

// fune: after payroll.net-to-gross

// fune: replace money.amount in payroll.net-to-gross
// fune: replace payroll.gross-to-net in payroll.net-to-gross

// fune: step payroll.net-to-gross after <n|label>

More from the author

## Why a search

Net pay has no clean inverse. Tax is charged on whole pounds, student loans are rounded down to whole pounds, pension and National Insurance thresholds switch on and off, and the income tax band a penny falls in depends on the year to date. Algebra that inverts the rates works for the middle of a band and is a penny or a pound out at every edge. So this runs `grossToNet` itself and searches.

The search is a plain bisection on whole pence: start at 0 and at the target, double the upper bound until its net reaches the target, then halve the gap until it is one penny. Every step is integer arithmetic with fixed midpoints, so the three languages take identical steps and return identical answers.

## What "the" answer is

The result is a gross `G` whose net is at least the target and where `G - 1p` nets less than the target. Net pay does not only ever rise with gross: tax is charged on whole pounds of taxable pay, so the penny that takes taxable pay into the next pound adds 20p or more of tax and net pay dips; one more penny can also cost a whole pound of student loan. Where the target sits clear of those dips (the usual case, and every vector here) `G` is the smallest gross that reaches it. Where it falls inside one, the bisection still returns a penny-exact boundary, but a smaller gross elsewhere could also reach the target, and the net may exceed the target by up to about £1. Check `net` on the returned payslip rather than assuming it equals the target.

If a tax refund makes the net at zero gross already reach the target, the payslip for zero gross is returned. The search refuses to look above £10,000,000 for one period.

Sources: as `payroll.gross-to-net`.

1.0.1 adds tests; behaviour unchanged.

## Before you rely on this

**Not professional advice.** This capability calculates payroll figures from published rules. It is a software component for developers, not tax or legal advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a payroll professional review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified payroll professional has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.2 marks it unreviewed. The code and the tests are unchanged.

Files