Function overloading in TypeScript

Preface:

Most functions accept a fixed set of parameters. But some functions can accept a variable number of arguments, arguments of different types, or even return different types depending on how you call the function. To annotate such functions, TypeScript provides function overloading.

1. Function signature

Let's first consider a function that returns a greeting message to a specific person.

function greet(person: string): string {
  return `Hello, ${person}!`;
}

The function above accepts one argument of type character: the person's name. Calling the function is very simple:

greet('World'); // 'Hello, World!'

What if you want to make greet() function more flexible? For example, have it additionally accept a list of people to greet.

Such a function will accept a string or an array of strings as an argument and return a string or an array of strings.

How to annotate a function like this? There are 2 methods.

The first approach is straightforward and involves directly modifying the function signature by updating the parameters and return types.

Here’s how greet() looks like after refactoring:

function greet(person: string | string[]): string | string[] {
  if (typeof person === 'string') {
    return `Hello, ${person}!`;
  } else if (Array.isArray(person)) {
    return person.map(name => `Hello, ${name}!`);
  }
  throw new Error('Unable to greet');
}

Now we can call greet() in two ways:

greet('World'); // 'Hello, World!'
greet(['Xiaozhi', 'Daye']); // ['Hello, Xiaozhi!', 'Hello, Daye!']

It is a common and good approach to directly update the function signature to support multiple calling methods.

However, in some cases, we may need to take a different approach and separately define all the ways your function can be called. This approach is called function overloading.

2. Function Overloading

The second method is to use function overloading. I recommend this approach when the function signature is relatively complex and involves multiple types.

Defining a function overload requires defining an overload signature and an implementation signature.

An overloaded signature defines the function's parameters and return type, without a function body. A function can have multiple overloaded signatures: corresponding to different ways of calling the function.

On the other hand, an implementation signature also has parameter types and a return type, as well as the body of the implementation function, and there can be only one implementation signature.

// Overload signature function greet(person: string): string;
function greet(persons: string[]): string[];
 
// Implement signature function greet(person: unknown): unknown {
  if (typeof person === 'string') {
    return `Hello, ${person}!`;
  } else if (Array.isArray(person)) {
    return person.map(name => `Hello, ${name}!`);
  }
  throw new Error('Unable to greet');
}

greet() function has two overload signatures and one implementation signature.

Each overload signature describes one way that the function can be called. As far as the greet() function is concerned, we can call it in two ways: with a string argument, or with an array of strings.

The implementation signature function greet(person: unknown): unknown { ... } contains the appropriate logic for how this function works.

Now, as above, greet() can be called with a string or array of strings.

greet('World'); // 'Hello, World!'
greet(['Xiaozhi', 'Daye']); // ['Hello, Xiaozhi!', 'Hello, Daye!']

2.1 Overloaded signatures are callable

Although the implementation signature implements the function behavior, it cannot be called directly. Only overloaded signatures are callable.

greet('World'); // Overloaded signature callable greet(['Xiaozhi', 'Daye']); // Overloaded signature callable const someValue: unknown = 'Unknown';
greet(someValue); // Implementation signature NOT callable

// Report an error. No overload matches this call.
  Overload 1 of 2, '(person: string): string', gave the following error.
    Argument of type 'unknown' is not assignable to parameter of type 'string'.
  Overload 2 of 2, '(persons: string[]): string[]', gave the following error.
    Argument of type 'unknown' is not assignable to parameter of type 'string[]'.

In the above example, you cannot call greet() function with an argument of type unknown (greet(someValue)) even though the implementation signature accepts an unknown argument.

2.1 Implementation signatures must be universal

// Overload signature function greet(person: string): string;
function greet(persons: string[]): string[]; 
// This overload signature is incompatible with its implementation signature.

 
// Implement signature function greet(person: unknown): string {
  // ...
  throw new Error('Unable to greet');
}

The overloaded signature function greet(person: string[]): string[] is marked as incompatible with greet(person: unknown): string .

string return type of the implementing signature is not generic enough to be compatible with string[] return type of the overloaded signature.

3. Method Overloading

Although in the previous example, function overloading was applied to a normal function. But we can also overload a method

In the method overloading section, both the overload signature and the implementation signature are part of the class.

For example, we implement a Greeter class with an overloaded method greet() .

class Greeter {
  message: string;
 
  constructor(message: string) {
    this.message = message;
  }
 
  // Overload signature greet(person: string): string;
  greet(persons: string[]): string[];
 
  // Implement signature greet(person: unknown): unknown {
    if (typeof person === 'string') {
      return `${this.message}, ${person}!`;
    } else if (Array.isArray(person)) {
      return person.map(name => `${this.message}, ${name}!`);
    }
    throw new Error('Unable to greet');
  }

The Greeter class contains the greet() overloaded method: 2 overload signatures describing how to call the method, and an implementation signature containing the correct implementation

Thanks to method overloading, we can call hi.greet() in two ways: with a string or with an array of strings as an argument.

const hi = new Greeter('Hi');
 
hi.greet('Xiaozhi'); // 'Hi, Xiaozhi!'
hi.greet(['Wang Daye', 'Daye']); // ['Hi, Wang Daye!', 'Hi, Daye!']

4. When to use function overloading

Function overloading, if used properly, can greatly increase the usability of functions that may be called in multiple ways. This is especially useful when doing autocompletion: we'll list all possible overloads in the autocompletion.

However, in some cases it is recommended not to use function overloading, but to use function signatures instead.

For example, do not use function overloading with optional parameters:

// Not recommended function myFunc(): string;
function myFunc(param1: string): string;
function myFunc(param1: string, param2: string): string;
function myFunc(...args: string[]): string {
  // implementation...
}

It is sufficient to use optional parameters in the function signature:

// Recommended practice function myFunc(param1?: string, param2: string): string {
  // implementation...
}

5. Summary

Function overloading in TypeScript lets us define functions that can be called in multiple ways.

Using function overloading requires defining an overload signature: a set of functions with parameters and return types, but no body. These signatures indicate how the function should be called.

Additionally, you must write the correct implementation of the function (implementation signature): parameter and return types, and the function body**. Note that the implementation signature is not callable. **

In addition to regular functions, methods within a class can also be overloaded.

This is the end of this article about function overloading in TypeScript . For more information about TypeScript function overloading, please search previous articles on 123WORDPRESS.COM or continue to browse the following related articles. I hope you will support 123WORDPRESS.COM in the future!