I built a small thing that estimates what a US pay raise actually lands in your pocket after federal tax, FICA, state tax, and inflation. The arithmetic is the boring part. The part that took three rewrites was deciding how to represent fifty states plus DC when you don't actually have clean data for all of them on day one.

This is a writeup of that one decision, because it generalizes well beyond taxes.

The problem isn't the math, it's the gaps

Federal brackets are easy. There's one set of numbers, the IRS publishes them, and progressive tax is a five-line loop:

function taxFromBrackets(taxable: number, brackets: Bracket[]): number {
  if (taxable <= 0) return 0;
  let tax = 0;
  let prevCap = 0;
  for (const { upTo, rate } of brackets) {
    const band = Math.min(taxable, upTo) - prevCap;
    if (band <= 0) break;
    tax += band * rate;
    prevCap = upTo;
  }
  return tax;
}

State tax is the same loop with different numbers. The trouble is that "different numbers" hides a lot. Nine states don't tax wage income at all. A couple (New Hampshire, Tennessee) don't tax wages but have historically taxed other things, so you can't just lump them with Texas without a footnote. Some states publish 2026 figures early; others inflation-index their brackets and won't publish the new thresholds until mid-year. And when I started, I had verified numbers for about ten states and unverified-but-plausible numbers for the rest.

That last category is the dangerous one. The easy move is to ship the plausible numbers and fix them later. The problem is that a wrong tax estimate doesn't look wrong. It looks like a number. Someone in Oregon types in their salary, sees a confident dollar figure, and has no way to know it was a placeholder I never got around to checking.

Two variants felt like enough. It wasn't.

My first model was the obvious one:

type StateTax =
  | { kind: "none"; code: string; name: string; note: string }
  | { kind: "taxed"; code: string; name: string; brackets: ...; standardDeduction: ... };

This is clean and it compiles and it's a lie. It forces every state to be either "no tax" or "here are the exact brackets," which means the moment I add a state to the union, I'm implicitly claiming I've verified it. There's no way for the type to say this state taxes income, but I haven't confirmed the numbers yet. So either I block the entire feature until all 51 are done, or I quietly promote guesses to facts.

The fix was a third variant whose only job is to represent honesty about the gap:

/** Taxing state not yet data-verified — selectable, but calc returns 0 with a UI caveat. */
type PendingState = { kind: "pending"; code: string; name: string };

type StateTax = NoneState | PendingState | TaxedState;

pending means: yes, this state taxes wages, no, I will not pretend to know how much. The calculator returns 0 for it, and the UI renders a visible caveat instead of a clean dollar amount. It's selectable so the dropdown still lists every state, but it can't masquerade as a verified result.

The calculation function gets to stay honest because the type makes the gap unrepresentable as a real value:

function calcStateTax(gross: number, status: FilingStatus, code: string | null): number {
  if (gross <= 0 || !code) return 0;
  const st = STATES_2026[code];
  if (!st || st.kind !== "taxed") return 0; // none AND pending both fall through here
  const taxable = Math.max(0, gross - st.standardDeduction[status]);
  return taxFromBrackets(taxable, st.brackets[status]);
}

The single line st.kind !== "taxed" is the whole point. There is exactly one branch that produces a state-tax number, and it's only reachable when the data has been verified. A pending state and a no-tax state both return 0, but they mean completely different things, and the UI is allowed to treat them differently because the variant carries that distinction.

"Verified" needed a definition I could check later

Once pending existed, I had to define what it took for a state to leave pending. Hand-wavy "I looked it up" doesn't survive contact with a tax year that changes under you. So every taxed state carries its own provenance:

type TaxedState = {
  kind: "taxed";
  brackets: Record<Filing, Bracket[]>;
  standardDeduction: Record<Filing, number>;
  provenance: Provenance; // where each number came from + a dated note
};

The rule I held myself to: a state's numbers only graduate to taxed when they're cross-checked against two independent sources — the state's own Department of Revenue, and an outside table (I used the Tax Foundation's bracket data). Both agree, or it stays pending. The provenance.note records the date and any caveat, like "state inflation-indexes brackets and hasn't published 2026 thresholds, so rates are exact and thresholds are the latest complete schedule."

That sounds like bureaucracy for a side project. But it's the difference between a number I can defend and a number I'm hoping is right. Six months from now when a state changes its top rate, the provenance tells me which states to recheck instead of re-auditing all of them.

The inflation formula people get wrong

Separate gotcha, same theme of "the obvious version is subtly false." A "real" raise — what your raise is worth after inflation eats some of it — is not nominal minus inflation. A 5% raise in 4% inflation is not a 1% real raise.

It's multiplicative, because you're dividing two ratios of purchasing power:

function calcRealRaise(nominalPct: number, inflationPct: number): number {
  const n = nominalPct / 100;
  const i = inflationPct / 100;
  return ((1 + n) / (1 + i) - 1) * 100; // ≈ 0.96%, not 1%
}

The gap is small at low inflation and embarrassing at high inflation. Subtraction says a 10% raise in 9% inflation keeps 1% of growth; the real figure is about 0.92%. At the inflation levels of the last few years that error is big enough to flip "you beat inflation" into "you didn't." I shipped the subtraction version first. A spreadsheet caught me.

What I'd take to the next project

The reusable lesson has nothing to do with taxes:

• Model the absence of data as a first-class state, not a falsy placeholder. 0, null, and undefined all collapse "no value" and "value I haven't verified" into the same shape. A named variant keeps them apart and lets the UI tell the user which one they're looking at.
• If a number is going to be presented as authoritative, make "unverified" unrepresentable as that number. The type system can enforce that the only code path producing a real figure runs on real data.
• Attach provenance to data that decays. Tax tables, prices, anything time-sensitive — a dated source note turns "is this still right?" from a re-audit into a lookup.

The calculator is at raise-calculator.com if you want to poke at the output (the take-home page is where all of this surfaces). But honestly the interesting artifact was the tagged union, not the website. I've started reaching for a pending-style variant in unrelated code now — anywhere I'm tempted to ship a guess that looks like a fact.

If you've got a cleaner way to model "taxing state, unknown brackets" than a third variant, I'd genuinely like to hear it.