Function Overloading in TypeScript

What is Function Overloading?

Function Overloading is a TypeScript feature where you can define multiple signatures for same function name. We define how the function should behave and handle in different cases. This is useful in cases where we need the function to accept different kind of arguments and return the type accordingly.

Simple Example

Imagine you went to a coffee shop and asked for A BLACK COFFEE, and you got ONE black coffee. Next time you asked for A BLACK COFFEE with SUGAR, and you got it. Here you asked different things from same shop and you got what you asked, no conflicts, right?

It’s same thing in TypeScript, you give different kind of arguments and you get based on the input. You have full type-safety, no need mess with union types.

Real-World Example

Here is a real case where I used this feature. I had a function which gives a random character, but it returns only ONE char, I also wanted to return an array of characters if I provide the count/length arg. Here is the code which overloads the function:

function getRandomChar(): string;
function getRandomChar(length: number): string[];
function getRandomChar(length?: number): string | string[] {
  const randomChar = () =>
    CHARACTERS[Math.floor(Math.random() * CHARACTERS.length)];
  return length !== undefined
    ? Array.from({ length }, randomChar)
    : randomChar();
}

Here this getRandomChar function returns one string if I dont give any argument(length). But if I do give an argument(length), it’ll return an array of string (string[]).

What actually happens?

When we call an overloaded function, TypeScript checks all the overloads and determine which signature should be used based on the argument.

First we define all possible cases with the type of arguments and return type as well, then we define the last function which handles all the possible cases which we’ve defined before, this is where we will do the logic based on the arguments.

function getRandomChar(): string;
function getRandomChar(length: number): string[];
function getRandomChar(length?: number): string | string[] {
  const randomChar = () =>
    CHARACTERS[Math.floor(Math.random() * CHARACTERS.length)];
  return length !== undefined
    ? Array.from({ length }, randomChar)
    : randomChar();
}

// usage
const char = getRandomChar(); // char is just ONE random character (string)
const chars = getRandomChar(5); // chars is now a list of 5 random characters (string[])
const err = getRandomChar("abc"); // shows ts error, because there is no handle for this case.

When to use and avoid

Use function overloading when:

• Your function can clearly behave in different ways.
• Each usage needs different argument types and/or return types.
• You want better DX with strict types.

Avoid overloading when:

• The arguments are dynamic and not predictable.
• You’re tempted to overload just to avoid writing seperate functions.

TL;DR

Function Overloading in TypeScript is about letting one function server multiple purposes- safely and predictably. It’s not about showing off TypeScript’s power. It’s about writing APIs that are easy to use, hard to misuse and joy to work with.