*Function Type overloading (next—function overloading, overloads). TypeScript is a compile-time type checking. At runtime, there is regular JavaScript. Therefore, there is function type overloading, but there is no function overloading. I’ve used generics and union types in TypeScript before but I’ve never heard about function overloading. So this article is about taking a closer look at function overloading and comparing it with generics and union types. Function overloading and union types Function overloading – some of JavaScript functions can be called in a variety of argument counts and types. In TypeScript, we can specify a function that can be called in different ways by writing overload signatures. Let’s have a look at the example from the : documentation function getLength(str: string): number;
function getLength(arr: number[]): number;
function getLength(x: any) {  
  return x.length;
} Here we have a function to return a of a (one argument) or an (one argument). To get , we should write two function signatures: one accepting an argument with a string type, and another accepting argument with an array of numbers type. length str arr overload signatures Then, we have to write something called a - a function implementation with a compatible signature. The previous two functions already have implementation signatures, but that signature can’t be called directly. compatible signature You can say: “But this can be written in a much easier way by using union types” and you would be totally right: function getLength(x: number[] | string): number {
  return x.length;
} Even says so: documentation Always prefer parameters with union types instead of overloads when possible. And there is a good reason for this. Let’s get back to the example with overload signatures and try to call that function next way: getLength(Math.random() > 0.5 ? "hello" : [0]);
No overload matches this call.
  Overload 1 of 2, '(s: string): number', gave the following error.
    Argument of type 'number[] | "hello"' is not assignable to parameter of type 'string'.
      Type 'number[]' is not assignable to type 'string'.
  Overload 2 of 2, '(arr: number[]): number', gave the following error.
    Argument of type 'number[] | "hello"' is not assignable to parameter of type 'number[]'.
      Type 'string' is not assignable to type 'number[]'. If you decided to use function overloading you have to be very careful with all the ways of calling that function. In this case, because both overloads have the and it is a good practice to use union types instead of function overloading to keep code clean and simple. same argument count same return type Summing up here are the conditions when using union types is better than using function overloading: You at the moment of the function declaration; know all the argument types depending on the argument's types. You can even leave it out of the signature since it is assumed that it will be immutable; The return type doesn't change Our example satisfied all the conditions: we defined that argument as a string or an array of numbers at the moment of the function's declaration; we know that return type always would be a number since it is a value of length property; So what do we need this function overloading for? Please, take a look at this example. It’s a bit more complicated but it would help you to understand when using overloads is more profitable than union types: type FullOrderInfo = {
  orderStatus: string;
  deliveryDate: string;
  orderNumber: string
}

type PartialOrderInfo = {
  orderNumber: string;
}

function getOrderInfo(email: string): PartialOrderInfo;
function getOrderInfo(fullname: string, trackingNumber: string;, phoneNumber: string): FullOrderInfo;
function getOrderInfo(fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo {
  if (trackingNumber !== undefined && phoneNumber !== undefined) {
  // there might be a request to backend which accepts strictly 3 args: fullname, trackingNumber and phoneNumber. Otherwise an error would be throught.
    return  {
      orderStatus: 'inProgress';
      deliveryDate: '20/10/2022';
      orderNumber: '372956743728'
    };
  } else {
    return {
      orderNumber: '372956743728';
    };
  }
} Here we have a function to return some that takes either an (one argument) or a , a , a (three arguments). So this function works only with 1 or 3 arguments (2 arguments are not acceptable). We’ve made two and the final one is . Now let’s see what we get after calling this function with different counts of arguments: orderInfo email fullname trackingNumber phoneNumber overload signatures compatible signatures const info1 = getOrderInfo('olgakiba@gmail.com'); // everithing is fine (one arg satisfies the condition) const info2 = getOrderInfo('olgakiba', 'dh546kwL, '796677334'); // still fine (three args satisfy the condition) const info3 = getOrderInfo('olgakiba', '796677334'); // No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments. That’s the exact result we wanted. Our function expects only 1 or 3 arguments as it is defined in overload signatures. Also as you can see overload signatures return different types, so it would not be correct to use union types here. Note, if your function is supposed to return different types you need to use not a union type sign (“|”), but an intersection type sign (“&“) in the implementation signature: function getOrderInfo(fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo {
  // function body
} Summing up it is a good practice to use union types or function overloading when at the moment of the function declaration. Use union types when and function overloading when depending on the argument's types. you know all the argument types the return type doesn't change the return type does change We saw the example of using function overloading with functions created by using function declaration but you can also apply it with functions created by using function expression, arrow functions, and classes methods: Function expression: type FullOrderInfo = {
  orderStatus: string;
  deliveryDate: string;
  orderNumber: string
}

type PartialOrderInfo = {
  orderNumber: string;
}

type GetOrderInfo = {
 (email: string): PartialOrderInfo;
 (fullname: string, trackingNumber: string, phoneNumber: string): FullOrderInfo;
};

const getOrderInfo:GetOrderInfo = function (fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo  {
 if (trackingNumber !== undefined && phoneNumber !== undefined) {
   return  {
      orderStatus: 'inProgress';
      deliveryDate: '20/10/2022';
      orderNumber: '372956743728'
    };
  } else {
    return {
      orderNumber: '372956743728';
    };
  }
}; Arrow function: type FullOrderInfo = {
  orderStatus: string;
  deliveryDate: string;
  orderNumber: string
}

type PartialOrderInfo = {
  orderNumber: string;
}

type GetOrderInfo = {
 (email: string): PartialOrderInfo;
 (fullname: string, trackingNumber: string, phoneNumber: string): FullOrderInfo;
};

const getOrderInfo:GetOrderInfo = (fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo => {
 if (trackingNumber !== undefined && phoneNumber !== undefined) {
   return  {
      orderStatus: 'inProgress';
      deliveryDate: '20/10/2022';
      orderNumber: '733487232'
    };
  } else {
    return {
      orderNumber: '372956743728';
    }
}; Class method - here is the same logic as in the examples above so I combined and wrote it in a short way: type FullOrderInfo = {
  orderStatus: string;
  deliveryDate: string;
  orderNumber: string
}

type PartialOrderInfo = {
  orderNumber: string;
}

type GetOrderInfo = {
 (email: string): PartialOrderInfo;
 (fullname: string, trackingNumber: string, phoneNumber: string): FullOrderInfo;
};

class OrderInfoGetter {
  // Function declaration
  getOrderInfo(email: string): PartialOrderInfo;
  getOrderInfo(fullname: string, trackingNumber: string;, phoneNumber: string): FullOrderInfo;
  getOrderInfo(fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo {
    // function body
  };

  // Function expression
  getOrderInfo:GetOrderInfo = function (fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo  {
    // function body
  }

  // Arrow function
  getOrderInfo:GetOrderInfo = (fullnameOrEmail: string, trackingNumber?: string, phoneNumber?: string): PartialOrderInfo & FullOrderInfo => {
    // function body
  }
} Generics You might think: “Okay, now we know when to use union types and when — overloads, let’s go try it in practice”. But before you do this we have to define one problem between those solutions — having a possibility of adding type support when beforehand. This is also a quite common case and as you can see it doesn’t satisfy all the conditions of using union types or function overloading. we are not aware of all the possible types A great solution for that is using generics: function getFirstArrayElement<T>(array: T[]): T {
    return array[0];
}

const firstArrayElement1 = getFirstArrayElement([1, 2, 3]); // return type: number
const firstArrayElement2 = getFirstArrayElement(["first", "second", "third"]); // return type: string
const firstArrayElement3 = getFirstArrayElement([true, false, true]); // return type: boolean A good practice of using generics is when: at the moment of the function declaration; You don’t know the argument types depending on the argument's types. In other words, it is a direct mapping (or close to it) of the argument types; The return type changes Conclusion Of all the methods described above, function overloading was new to me. I think that overloads won't be an integral part of your code. It can be used mainly to continue and support previous work. Imagine you come to a huge old project that dozens and hundreds of developers have worked with and for sure it might have some problems and mistakes made by previous developers. So you have to write a function wrapper on a function that somehow has two signatures and different return types. The best way to implement this function wrapper would be by using function overloading. But you have to understand that this is a forced solution to support old code. In other words, if you are writing a project from scratch and you already have the usage of function overloading in the code it means that your architecture might have some holes and you might need to reconsider it. Because first SOLID principle says: in most cases Every class, module, or function in a program should have one responsibility/purpose in a program So in this case (if it is possible) it would be better to divide your function into several ones to keep the code clean and understandable for other people. But of course, there might be cases where overloads would be the only correct solution, e.x. working with chrome.tabs.query or complicated business conditions. Function overloading is an excellent tool. It would be good for every developer to know what it is and how it works. However, it must be used carefully and only where it’s necessary.

The code in this story is for educational purposes. The readers are solely responsible for whatever they build with it.

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

Understanding Function Overloading in TypeScript

Too Long; Didn't Read

Olga Kiba

STORY’S CREDIBILITY

Code License

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Understanding Function Overloading in TypeScript

Too Long; Didn't Read

Olga Kiba

STORY’S CREDIBILITY

Code License

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES