New series: what assistive tech really hears on your checkout page. Start with part one →
Shipwright
Home
TypeScript Sep 17, 2026 2 min read 290 views

Narrowing Unions Without a Single Type Assertion

June Park

June Park

@junepark

Share
Cover illustration for the article Narrowing Unions Without a Single Type Assertion

Discriminants, type guards, and the satisfies operator doing the work for you. TypeScript is at its best when you barely notice it. The goal of this post is fewer annotations, not more, while catching the bugs that actually reach production.

Let inference do the work

Inference covers most local code. Annotate function parameters and public return types, and let the compiler fill in everything else. If you find yourself writing as, stop and ask which check is missing.

result.ts
type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: string };

function parsePort(input: string): Result<number> {
  const port = Number(input);
  if (!Number.isInteger(port) || port < 1 || port > 65535) {
    return { ok: false, error: `Invalid port: ${input}` };
  }
  return { ok: true, value: port };
}

const result = parsePort(process.env.PORT ?? '3000');
if (result.ok) {
  console.log(result.value.toFixed(0));
}

Types at the boundary

Data that crosses a boundary, whether a network response, a form, or a query string, is untrusted until something validates it at runtime. Types alone cannot do that job, but they can make sure validation happens once.

  • Annotate parameters and exported return types.
  • Validate external data once, at the edge.
  • Prefer discriminated unions over optional flags.
  • Treat every as cast as a code smell to review.

When to reach for generics

Generics look intimidating in library code, yet in application code they usually solve one problem: keeping the input and output of a helper connected. Start with a single type parameter and add more only when a test demands it.

As always, the examples are simplified to fit on a page. The production version has more error handling and logging, but the shape of the code is the same.

Questions, corrections, and war stories are welcome in the comments. Several of our best follow-up posts started as a reader pointing out something we had missed.

We will revisit this in six months with fresh numbers. If the results change, we will update the post and note what changed at the end.

If you try this on your own project, start with one page or one service rather than the whole codebase. A small experiment gives you real numbers to argue with, and it is easy to roll back if the idea does not fit.

Before you ship this

Strict mode catches most of these bugs for free. If your tsconfig does not have strict enabled, turn it on in a branch and count the errors before planning the migration.

Simplicity is prerequisite for reliability.

Edsger W. Dijkstra, EWD498, 1975

Wrapping up

If you try this on your own project, start with one page or one service rather than the whole codebase. A small experiment gives you real numbers to argue with, and it is easy to roll back if the idea does not fit.

June Park

June Park

Author

Frontend engineer working across React and TypeScript. June writes the posts she wishes she had found while debugging.

Related Posts

Comments 10

Fatima Zahra

The part about naming things made me laugh, then made me go rename three functions.

June Park Author

Good question. We measured on a mid-range Android phone and took the median of five runs.

Priya Raman Member

Any thoughts on how this interacts with server-side rendering?

June Park Author

The renaming spree is a rite of passage.

Alex Moreno

Bookmarked. The code sample alone saved me an afternoon.

Oskar Nilsson

Solid write-up. The warning about caching bit us hard last year.

Kofi Mensah

Solid write-up. The warning about caching bit us hard last year.

Liam O’Brien

Would love a follow-up on how you test this in CI.

Elias Lindqvist Member

Shared this with my team. The list near the end is going straight into our pull request template.

Kofi Mensah

Clear, practical, no fluff. More of this, please.

Leave a comment

Your email will not be published. Sign in for a faster experience.

Supports **bold**, *italic*, and `code`.