DEV Community

Samuel Ochaba
Samuel Ochaba

Posted on

Stop Hitting Yourself: The Quiet Lie in Function Signatures

#webdev #typescript #beginners #discuss

Every codebase has a function like this:

function getUser(id: string): User {
  // ... fetch from DB ...
  return user;
}
Enter fullscreen mode Exit fullscreen mode

It looks innocent. It is not. That signature makes a promise: give me an ID, I will hand you back a User. Except it will not. Sometimes there is no user. Sometimes the database is on fire. Sometimes the caller passed an ID that was never valid. The signature does not tell you which, and that silence is one of the most expensive bugs in software.

This post is about the difference between code that runs and code that is honest, and the three failure modes that separate them. It is short, it has working TypeScript, and by the end you will know exactly what to put in your type signatures the next time you are tempted to write return null or throw new Error(...) and move on.

The Lie Hiding in Plain Sight

A type signature is a contract. When you write getUser(id: string): User, you are telling every caller, every reviewer, and the compiler itself: this returns a User.

Then you do this:

function getUser(id: string): User {
  const user = db.findUser(id);
  if (!user) return null; // 🤥
  return user;
}
Enter fullscreen mode Exit fullscreen mode

The signature still says User. The body returns null. The caller has no way to know without reading the implementation, and once you are reading the implementation, the type system has stopped doing its job. This is the family of bug Tony Hoare famously called his billion-dollar mistake: letting types promise a value they might not deliver.

So how do you fix it? First you have to realize there is not one kind of "something went wrong." There are three.

Exceptions, Errors, and Panics: Know the Difference

Most codebases treat every failure as an exception, and that is the root of the confusion. Let me untangle them.

Exceptions: for things you cannot handle

An exception is for exceptional conditions, things outside this function's control or knowledge:

  • the database is unreachable
  • a required config file is missing
  • a network call timed out mid-request
  • a programming bug, like calling a method on the wrong shape of object

The defining property: the current function does not know what to do, so it unwinds the stack and asks someone above it to figure it out. If nobody can, the request dies. That is the correct outcome. You genuinely did not know.

Errors: for things the caller must handle

An error is an expected, recoverable failure that belongs to the normal operation of the program:

  • the record was not found
  • the input failed validation
  • the user lacks permission
  • a file already exists

These are not exceptional. They are Tuesday. The function knows they are possible, and the right move is to return the failure so the caller is forced to deal with it, not throw it and hope.

Panics: for the impossible

A panic is for an unrecoverable invariant violation, a state the author believed could not happen:

  • a switch statement hits a case that should be unreachable
  • an array that was just checked is somehow empty
  • an internal counter is negative

You do not catch a panic. It means the program is in a state nobody designed for, and continuing would be worse than stopping. Crash loudly, with a stack trace, so somebody fixes it.

Make the Possibility Visible in the Type

Now the fix writes itself. "Record not found" is an error, not an exception. So do not throw, and do not sneakily return null. Make the absence part of the type:

function getUser(id: string): User | null {
  const user = db.findUser(id);
  return user ?? null;
}
Enter fullscreen mode Exit fullscreen mode

Now the signature tells the truth: a User, or nothing. And TypeScript will not let the caller pretend otherwise:

const user = getUser(id);
console.log(user.email); // ❌ Error: 'user' is possibly 'null'

if (user !== null) {
  console.log(user.email); // ✅ narrowed to User
}
Enter fullscreen mode Exit fullscreen mode

The compiler became your ally instead of your adversary. The bug that would have shipped at runtime now fails at tsc.

Want to carry a reason along with the absence? Reach for the richer version of the same idea:

type FindResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: "not_found" | "forbidden" };

function getUser(id: string): FindResult<User> { /* ... */ }
Enter fullscreen mode Exit fullscreen mode

Same principle, more information. Either way, the signature stops lying.

Three Rules to Take With You

  1. Throw for the exceptional. Return for the expected. Crash for the impossible.
  2. If the caller needs to handle it, it goes in the type. null, a discriminated union, a Result. Never a silent lie.
  3. Every signature is a promise. Make ones you can keep, and let the compiler enforce them.

Over to You

The next time you reach for throw new Error("not found") or return null on a typed User, ask the question that matters: what is my signature actually promising, and is it true?

I am genuinely curious how other teams draw the exception/error/panic line. Do you throw on "not found" and catch it later, return an optional, or use a full Result type? Tell me in the comments, I read all of them.

If this was useful, I write about TypeScript, system design, and the small decisions that compound in a codebase. Follow for the next one, and check out my earlier post on the same idea applied to optional fields.

Top comments (0)