Что такое Function Overload в TypeScript

Перегрузка функции в TypeScript состоит из двух частей: нескольких overload-сигнатур и одной реализации. Overload-сигнатуры описывают, как функцию можно вызвать снаружи. Реализация содержит реальный код и должна обработать все объявленные варианты.

Простой пример:

function parseValue(value: string): string[];
function parseValue(value: number): number;
function parseValue(value: string | number): string[] | number {
  if (typeof value === "string") {
    return value.split(",");
  }

  return value * 100;
}

const tags = parseValue("react,typescript"); // string[]
const percent = parseValue(0.42); // number

Здесь вызывающий код получает разные типы результата. Для строки это string[], для числа это number. В этом практическая ценность overload. Вы не просто разрешаете разные типы входа, а сохраняете точный контракт между входом и выходом.

Хороший короткий ответ может звучать так:

Function Overload это несколько сигнатур вызова для одной функции. TypeScript использует их, чтобы понять, какие аргументы разрешены и какой тип вернется для конкретного вызова. При этом реализация одна, и она должна сама проверить аргументы и обработать все варианты.

После этого добавьте практический критерий. Перегрузки нужны не всегда. Если возвращаемый тип не зависит от формы входа, union type часто проще. Если зависит, overload делает API удобнее и уменьшает лишние проверки в вызывающем коде.

На интервью важно не только знать синтаксис, но и показать, что вы умеете выбирать форму API. Перегрузки могут улучшить developer experience. Но если использовать их без необходимости, простая функция быстро превращается в длинный список сигнатур.

Пример, где overload не обязателен:

function formatValue(value: string | number): string {
  return String(value);
}

Результат всегда string, поэтому отдельные сигнатуры для string и number почти ничего не дают. А вот если разные входы дают разные выходы, перегрузки помогают избежать ручных проверок после вызова.

Внешний код может вызвать функцию только так, как описано в overload-сигнатурах. Сигнатура реализации нужна для тела функции и проверки совместимости.

Неверный вывод выглядит так: если в реализации написан широкий параметр, значит функцию можно вызвать с любым значением.

function loadUser(id: number): Promise<User>;
function loadUser(slug: string): Promise<User>;
function loadUser(value: number | string | boolean): Promise<User> {
  return fetch(`/api/users/${String(value)}`).then((response) => response.json());
}

loadUser(true); // ошибка типов, потому что такой overload не объявлен

В этом примере широкая реализация опасна не из-за самого overload, а из-за тела функции. Если значение придет из JavaScript-кода, формы или URL без проверки, можно отправить лишний запрос на /api/users/true, получить неверный error или показать в UI пустое состояние вместо понятной ошибки.

Безопаснее держать реализацию настолько широкой, насколько нужно для объявленных перегрузок, и явно проверять аргументы перед сетевым вызовом:

function loadUser(id: number): Promise<User>;
function loadUser(slug: string): Promise<User>;
function loadUser(value: number | string): Promise<User> {
  const path = typeof value === "number" ? `id/${value}` : `slug/${encodeURIComponent(value)}`;

  return fetch(`/api/users/${path}`).then(async (response) => {
    if (!response.ok) {
      throw new Error("User request failed");
    }

    const data: unknown = await response.json();
    return parseUser(data);
  });
}

Здесь parseUser означает вашу проверку формы ответа. Не доверяйте JSON только потому, что overload красиво описал вызов. Не превращайте реализацию в any без причины. И обязательно проверяйте аргументы в теле, потому что в runtime перегрузок уже нет.

TypeScript проверяет overload-сигнатуры сверху вниз. Поэтому сначала пишите более специфичные варианты, а потом более общие.

function getSetting(key: "theme"): "light" | "dark";
function getSetting(key: string): string;
function getSetting(key: string): string {
  return localStorage.getItem(key) ?? "";
}

const theme = getSetting("theme"); // "light" | "dark"

Если поставить общий вариант key: string выше, точный результат для "theme" может потеряться. На практике это бьет по автодополнению, условиям в UI и проверкам, которые зависят от конкретного режима.

Во frontend overload часто полезен для функций-оберток над API, парсеров, helpers для роутинга и функций с несколькими режимами. Например, один режим возвращает одиночную сущность, другой список.

type User = { id: string; name: string };

function selectUsers(users: User[], mode: "one"): User | undefined;
function selectUsers(users: User[], mode: "many"): User[];
function selectUsers(users: User[], mode: "one" | "many") {
  if (mode === "one") {
    return users[0];
  }

  return users;
}

const firstUser = selectUsers(users, "one");
const allUsers = selectUsers(users, "many");

Такой API помогает компоненту не угадывать тип результата. Для режима "one" UI сразу видит, что результата может не быть, и может показать empty state. Для режима "many" компонент получает массив и не пишет лишние проверки. Но если режимов становится много, лучше подумать об объекте настроек или разделить функцию. Длинный список перегрузок может быть признаком слишком сложного helper-а.

Сильный ответ не обязан быть длинным. Достаточно объяснить контракт, привести маленький пример и сказать, где перегрузки уместны. Если вы добавите отличие от union и упомянете, что реализация одна, ответ будет выглядеть уверенно.