Day20: Learning TypeScript: Function Overloads Not Present in JavaScript

Finally, it's day 20! I feel a bit happy that it's almost over, but I'm worried about the next 10 articles, feeling both excited and afraid I won't finish XDD

Alright, enough chit-chat. Today, we will talk about Function Overloads. I find this feature cool; JavaScript definitely cannot do this due to hoisting issues. Let's take a look!

If there are any errors, please feel free to leave comments. Thank you!

Function Overloads

Function overloads refer to extending the forms in which a function can be executed. In simple terms, it provides multiple type definitions for the same function. You can use the same function name to create multiple methods with different parameter counts or types.

Function overloads consist of two parts:

• Overload signatures: This is the type definition part, usually defining two or more types.
• Function implementation: The actual function that executes, which must satisfy all overload signatures.

Example 1:

In the following example, the padding function (which sets CSS padding) can take one, two, or four parameters. We can use Function Overloads to enforce this. If three parameters are accidentally passed, it will remind you with No overload expects 3 arguments.

// Overload signatures definition
function padding(all: number): object;
function padding(topAndBottom: number, leftAndRight: number): object;
function padding(top: number, right: number, bottom: number, left: number): object;

// Function implementation
function padding(a: number, b?: number, c?: number, d?: number) {
  if (b === undefined && c === undefined && d === undefined) {
    b = c = d = a;
  } else if (c === undefined && d === undefined) {
    c = a;
    d = b;
  }
  return {
    top: a,
    right: b,
    bottom: c,
    left: d
  };
}

padding(1); // ok: all
padding(1, 1); // ok: topAndBottom, leftAndRight
padding(1, 1, 1, 1); // ok: top, right, bottom, left
padding(1, 1, 1); // Error: No overload expects 3 arguments, but overloads do exist that expect either 2 or 4

In this example, we can see that the compiler marks +2 overloads, and it automatically detects that you are using function overloads, which is quite cool.

Example 2:

// Overload signatures
function makeDate(timestamp: number): Date;
function makeDate(m: number, d: number, y: number): Date;

// Function implementation
function makeDate(mOrTimestamp: number, d?: number, y?: number): Date {
  if (d !== undefined && y !== undefined) {
    return new Date(y, mOrTimestamp, d);
  } else {
    return new Date(mOrTimestamp);
  }
}
const d1 = makeDate(12345678); // ok
const d2 = makeDate(5, 5, 5); // ok
const d3 = makeDate(1, 3); // error: No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.

Important Notes on Usage

1. At least 2 or more overload signatures are required

❌ In the following example, it is expected that calling fn(); without parameters will print "hello", but it results in an error because it is only defined to take x: string, which requires one parameter, so calling it without parameters results in an error.

function fn(x: string): void;
function fn() {
   console.log("hello");
}
fn(); // error: Expected 1 arguments, but got 0.

✅ Just add an overload signature for no parameters.

function fn(x: string): void;
function fn(): void;
function fn() {
  console.log("hello");
}
fn();

2. The parameter types passed to the actual function must be compatible with the overload signatures

❌ In the actual function, if the parameter type is only boolean, and the second overload signature's parameter type is string, then it is incompatible with the implementation.

// Overload signatures
function fn(x: boolean): void;

function fn(x: string): void; // error: This overload signature is not compatible with its implementation signature.

// Function implementation
function fn(x: boolean) {
    console.log("hello");
}

✅ To make it compatible, use a union type.

function fn(x: boolean): void;
function fn(x: string): void;

function fn(x: boolean | string) {
  console.log("hello");
}

fn(""); //"hello"

In the next article, I will take notes on Generics. See you tomorrow!

References

https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads

https://pjchender.dev/typescript/ts-functions/#function-overload%E5%87%BD%E5%BC%8F%E8%B6%85%E8%BC%89

https://basarat.gitbook.io/typescript/type-system/functions#overloading