Сужение типов в TypeScript

Содержание туториала по TypeScript Предположим, что у нас есть функция padLeft.

function padLeft(padding: number | string, input: string): string {
  throw new Error('Not implemented yet!');
}

Если padding является числом, оно будет рассматриваться как количество пробелов, которые мы хотим добавить перед input. Если padding является строкой, он должен просто добавлять padding перед input. Давайте попробуем реализовать логику, когда в padLeft передается padding как число.

function padLeft(padding: number | string, input: string) {
  return ' '.repeat(padding) + input;

  // Argument of type 'string | number' is not assignable to parameter of type 'number'.
  // Type 'string' is not assignable to type 'number'.

  // Аргумент типа 'string | number' не может быть присвоен параметру типа 'number'.
  // Тип 'string' не может быть присвоен типу 'number'.
}

TypeScript предупреждает нас, что добавление string | number в number может не дать нам того, что мы хотим, и это правильно. Другими словами, мы не проверяли явно, является ли padding числом, и не обрабатываем случай, когда это строка, так что давайте сделаем это.

function padLeft(padding: number | string, input: string) {
  if (typeof padding === 'number') {
    return ' '.repeat(padding) + input;
  }
  return padding + input;
}

Если не считать добавленных нами аннотаций типов, этот TypeScript код выглядит как JavaScript. Идея состоит в том, что система типов TypeScript направлена на то, чтобы максимально упростить написание JavaScript кода, без необходимости лезть вон из кожи, чтобы обеспечить безопасность типов. Хотя это может показаться не таким уж большим делом, на самом деле в этом коде скрывается много работы со стороны TypeScript. Подобно тому, как TypeScript анализирует значения во время выполнения с использованием статических типов, он накладывает анализ типов на конструкции потока управления во время выполнения JavaScript, такие как if/else, тернарные условия, циклы, проверки на истинность и т.д., которые могут влиять на эти типы. В нашей проверке if TypeScript видит typeof padding === 'number' и понимает это как особую форму кода, называемую защитой типа (type guard). TypeScript следует возможным путям выполнения, которые наши программы могут использовать для анализа наиболее конкретного возможного типа значения в данной позиции. Он рассматривает эти специальные проверки (называемые защитой типов) и присвоения, а процесс уточнения типов до более конкретных, чем объявленные, называется сужением (narrowing). Во многих IDE мы можем наблюдать за изменением этих типов, и мы даже будем делать это в наших примерах.

function padLeft(padding: number | string, input: string) {
  if (typeof padding === 'number') {
    return ' '.repeat(padding) + input;
    // при наведении курсора на padding => (parameter) padding: number
  }
  return padding + input;
  // в этом случае при наведении курсора на padding => (parameter) padding: string
}

Существует несколько различных конструкций, которые применяются в TypeScript для сужения.

Защитник типов typeof

Как мы видели, JavaScript поддерживает оператор typeof, который может дать очень базовую информацию о типе значений, во время выполнения. TypeScript ожидает, что это вернет определенный набор строк:

• "string"
• "number"
• "bigint"
• "boolean"
• "symbol"
• "undefined"
• "object"
• "function"

Как мы видели в случае с padLeft, этот оператор довольно часто встречается в ряде библиотек JavaScript, и TypeScript может понимать его для сужения типов в разных ветках кода. В TypeScript проверка значения, возвращаемого typeof, является защитой типа. Поскольку TypeScript понимает как typeof работает с разными значениями, он знает о некоторых причудах в JavaScript. Например, обратите внимание, что в приведенном выше списке typeof не возвращает строку null. Рассмторим следующий пример:

function printAll(strs: string | string[] | null) {
  if (typeof strs === 'object') {
    for (const s of strs) {
      // Object is possibly 'null'.
      // Возможно, объект 'null'.
      console.log(s);
    }
  } else if (typeof strs === 'string') {
    console.log(strs);
  } else {
    // ничего не делать
  }
}

В функции printAll мы пытаемся проверить, является ли strs объектом, чтобы узнать, является ли он типом массива (сейчас самое время подчеркнуть, что массивы являются объектными типами в JavaScript). Но оказывается, что в JavaScript typeof null на самом деле вернет "object"! Это одна из тех досадных исторических случайностей. Пользователи с достаточным опытом могут не удивиться, но не все сталкивались с этим в JavaScript. К счастью, TypeScript сообщает нам, что strs был сужен только до string[] | null вместо просто string[].

Проверка на истинность (Truthiness narrowing)

В JavaScript мы можем использовать любое выражение в условных выражениях, операторах &&, ||, операторах if, логических отрицаниях (!) и т.д. Например, операторы if не ожидают, что их условие всегда будет иметь логический тип.

function getUsersOnlineMessage(numUsersOnline: number) {
  if (numUsersOnline) {
    return `There are ${numUsersOnline} online now!`;
  }
  return "Nobody's here. :(";
}

В JavaScript такие конструкции, как if, сначала "приводят" свои условия к булевым значениям, а затем выбирают свои ответвления в зависимости от того, является ли результат истинным или ложным. Такие значения, как

• 0
• NaN
• "" (пустая строка)
• 0n (bigint версия нуля)
• null
• undefined

приводятся к false, а другие значения приводятся к true. Вы всегда можете привести значения к логическим значениям, применив к ним функцию Boolean или используя более короткое двойное логическое отрицание. (Последний имеет преимущество - TypeScript выводит узкий литеральный логический тип true, в то время как в первом варианте выводится логический тип boolean.)

// оба варианта имеют значение 'true'
Boolean('hello'); // type: boolean, value: true
!!'world'; // type: true, value: true

Довольно популярно использовать такое поведение, особенно для защиты от таких значений, как null или undefined. В качестве примера попробуем использовать его для нашей функции printAll.

function printAll(strs: string | string[] | null) {
  if (strs && typeof strs === 'object') {
    for (const s of strs) {
      console.log(s);
    }
  } else if (typeof strs === 'string') {
    console.log(strs);
  }
}

Обратите внимание, что мы избавились от приведенной выше ошибки, проверив, является ли strs истинным. Это, по крайней мере, защищает нас от ужасных ошибок при запуске нашего кода, например:

TypeError: null is not iterable

// TypeError: null не перечисляемый

Имейте в виду, однако, что проверка истинности примитивов часто может быть подвержена ошибкам. В качестве примера рассмотрим другой вариант printAll.

function printAll(strs: string | string[] | null) {
  // !!!!!!!!!!!!!!!!
  //  Не делайте так!
  //  Продолжайте чтение
  // !!!!!!!!!!!!!!!!
  if (strs) {
    if (typeof strs === 'object') {
      for (const s of strs) {
        console.log(s);
      }
    } else if (typeof strs === 'string') {
      console.log(strs);
    }
  }
}

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

function multiplyAll(
  values: number[] | undefined,
  factor: number
): number[] | undefined {
  if (!values) {
    return values;
  } else {
    return values.map((x) => x * factor);
  }
}

Сужение при проверке на равенство (Equality narrowing)

TypeScript также использует операторы switch и проверки на равенство, такие как ===, !==, == и != для сужения типов. Например:

function example(x: string | number, y: string | boolean) {
  if (x === y) {
    // Мы можем вызвать любой строковый метод у 'x' или 'y'.
    x.toUpperCase();
    // (method) String.toUpperCase(): string

    y.toLowerCase();
    // (method) String.toLowerCase(): string
  } else {
    console.log(x);
    // (parameter) x: string | number

    console.log(y);
    // (parameter) y: string | boolean
  }
}

Когда мы проверили, что x и y равны в приведенном выше примере, TypeScript узнал, что их типы также должны быть равны. Поскольку string — это единственный общий тип, который могут принимать как x, так и y, TypeScript знает, что x и y должны быть строкой в первой ветви. Также работает проверка конкретных литеральных значений (в отличие от переменных). В разделе Проверка на истинность мы написали функцию printAll, которая была подвержена ошибкам, потому что случайно неправильно обрабатывала пустые строки. Вместо этого мы могли бы сделать специальную проверку, чтобы заблокировать значения null, и TypeScript по-прежнему корректно удалял бы null из типа strs.

function printAll(strs: string | string[] | null) {
  if (strs !== null) {
    if (typeof strs === 'object') {
      for (const s of strs) {
        // (parameter) strs: string[]
        console.log(s);
      }
    } else if (typeof strs === 'string') {
      console.log(strs);
      // (parameter) strs: string
    }
  }
}

Cлабые проверки равенства в JavaScript с помощью == и != также корректно сужаются. Если вы не знакомы, проверка того, действительно ли что-то == null, не только проверяет, является ли это именно значением null, но также проверяет, является ли оно потенциально undefined. То же самое относится и к == undefined: он проверяет, является ли значение null или undefined.

interface Container {
  value: number | null | undefined;
}

function multiplyValue(container: Container, factor: number) {
  // Удаляем 'null' и 'undefined' из типа.
  if (container.value != null) {
    console.log(container.value);
    // (property) Container.value: number

    // Теперь можно безопасно умножить 'container.value'.
    container.value *= factor;
  }
}

Сужение типов с оператором in

В JavaScript есть оператор для определения наличия у объекта свойства с указанным именем: оператор in. TypeScript учитывает это как способ сузить число возможных типов. Например, кодом: "value" in x, где "value" — строковый литерал, а x — тип объединения. Ветвь с true сужает типы x, которые имеют либо необязательное, либо обязательное свойство value, а ветвь false сужает типы, которые имеют необязательное или отсутствующее свойство value.

type Fish = { swim: () => void };
type Bird = { fly: () => void };

function move(animal: Fish | Bird) {
  if ('swim' in animal) {
    return animal.swim();
  }

  return animal.fly();
}

Повторим, что необязательные свойства будут существовать в обеих ветках, например, человек может и плавать (swim), и летать (fly) (с соответствующим снаряжением):

type Fish = { swim: () => void };
type Bird = { fly: () => void };
type Human = { swim?: () => void; fly?: () => void };

function move(animal: Fish | Bird | Human) {
  if ('swim' in animal) {
    animal;
    // (parameter) animal: Fish | Human
  } else {
    animal;
    // (parameter) animal: Bird | Human
  }
}

Сужение типов с instanceof

В JavaScript есть оператор для проверки того, является ли значение «экземпляром» другого значения. В JavaScript x instanceof Foo проверяет, содержится ли Foo.prototype в цепочке прототипов x. Более подробно вернемся к этой теме, когда перейдем к классам. Как вы могли догадаться, instanceof также является защитой типов, а TypeScript сужает типы в ветках, защищенных instanceof.

function logValue(x: Date | string) {
  if (x instanceof Date) {
    console.log(x.toUTCString());
    //(parameter) x: Date
  } else {
    console.log(x.toUpperCase());
    // (parameter) x: string
  }
}

Присваивания (Assignments)

Как мы упоминали ранее, когда мы присваиваем значение любой переменной, TypeScript смотрит на правую часть присваивания и соответствующим образом сужает тип левой стороны.

let x = Math.random() < 0.5 ? 10 : 'hello world!';

let x: string | number;
x = 1;

console.log(x);
// let x: number

x = 'goodbye!';

console.log(x);
// let x: string

Обратите внимание, что каждое из этих присвоений допустимо. Несмотря на то, что наблюдаемый тип x изменился на number после нашего первого присваивания, мы по-прежнему могли присвоить x строку. Это связано с тем, что объявленный тип x — тип, с которого начинается x — это string | number, а присваиваемость всегда проверяется по объявленному типу. Если бы мы присвоили x значение boolean, мы бы увидели ошибку, поскольку это не было частью объявленного типа.

let x = Math.random() < 0.5 ? 10 : 'hello world!';

let x: string | number;
x = 1;

console.log(x);
// let x: number

x = true;
// Type 'boolean' is not assignable to type 'string | number'.
// Тип 'boolean' нельзя присвоить к типу 'string | number'.

console.log(x);
// let x: string | number

Анализ потока управления

До этого момента мы рассмотрели несколько основных примеров того, как TypeScript сужает типы ветках. Но на самом деле происходит нечто большее, чем просто обход каждой переменной и поиск защитников типов в if, while, условных выражениях и т.д. Например.

function padLeft(padding: number | string, input: string) {
  if (typeof padding === 'number') {
    return ' '.repeat(padding) + input;
  }
  return padding + input;
}

padLeft возвращает значение из своего первого блока if. TypeScript смог проанализировать этот код и увидеть, что остальная часть тела (return padding + input;) недостижима в случае, когда padding является числом. В результате удалось удалить number из типа padding (сужение от string | number до string) для остальной части функции. Этот анализ кода, основанный на достижимости, называется анализом потока управления (control flow analysis), и TypeScript использует этот анализ потока для сужения типов по мере того, как он сталкивается с защитой типов и присваиваниями. Когда переменная анализируется, поток управления может разделяться и объединяться снова и снова, и можно наблюдать, что эта переменная имеет разный тип в каждой точке.

function example() {
  let x: string | number | boolean;

  x = Math.random() < 0.5;

  console.log(x);
  // let x: boolean

  if (Math.random() < 0.5) {
    x = 'hello';
    console.log(x);
    // let x: string
  } else {
    x = 100;
    console.log(x);
    // let x: number
  }

  return x;
  // let x: string | number
}

Использование предикатов типа (type predicates)

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

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

pet is Fish — наш предикат типа в этом примере. Предикат принимает форму parameterName is Type, где parameterName должно быть именем параметра из текущей сигнатуры функции. Каждый раз, когда isFish вызывается с некоторой переменной, TypeScript сужает эту переменную до этого конкретного типа, если исходный тип совместим.

// Теперь вызовы 'swim' и 'fly' - ок.
let pet = getSmallPet();

if (isFish(pet)) {
  pet.swim();
} else {
  pet.fly();
}

Обратите внимание, что TypeScript не только знает, что pet — это Fish в ветке if; он также знает, что в другой ветке у вас нет Fish, поэтому у вас должна быть Bird. Вы можете использовать защиту типа isFish для фильтрации массива Fish | Bird и получить массив состоящий из Fish:

const zoo: (Fish | Bird)[] = [getSmallPet(), getSmallPet(), getSmallPet()];
const underWater1: Fish[] = zoo.filter(isFish);
// или, тоже самое
const underWater2: Fish[] = zoo.filter(isFish) as Fish[];

// Предикат может нуждаться в повторении для более сложных примеров.
const underWater3: Fish[] = zoo.filter((pet): pet is Fish => {
  if (pet.name === 'sharkey') return false;
  return isFish(pet);
});

Исключающие объединения (discriminated unions)

Большинство примеров, которые мы рассмотрели ранее, были сосредоточены на сужении одиночных переменных с помощью простых типов, таких как string, boolean и number. Однако, большую часть времени в JavaScript мы будем иметь дело с немного более сложными структурами. Представим, что мы пытаемся описать такие фигуры, как круги и квадраты. Круги отслеживают свои радиусы, а квадраты отслеживают длины своих сторон. Мы будем использовать поле под названием kind, чтобы указать, с какой формой мы имеем дело. Вот первая реализация Shape.

interface Shape {
  kind: 'circle' | 'square';
  radius?: number;
  sideLength?: number;
}

Обратите внимание, что мы используем объединение типов строковых литералов: "circle" и "square". Используя "circle" | "square" вместо string, мы можем избежать проблем с орфографическими ошибками.

function handleShape(shape: Shape) {
  // "rect" не входит в "circle"` или `"square"
  if (shape.kind === 'rect') {
    // This condition will always return 'false' since the types '"circle" | "square"' and '"rect"' have no overlap.
    // Это условие всегда будет возвращать 'false', так как типы '"circle" | "square"' и '"rect"' не пересекаются.
    // ...
  }
}

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

function getArea(shape: Shape) {
  return Math.PI * shape.radius ** 2;
  // Object is possibly 'undefined'.
  // Объект, возможно, 'undefined'.
}

В strictNullChecks это выдает ошибку, что уместно, поскольку радиус может быть не определен. Но что, если мы выполним соответствующие проверки свойства kind?

function getArea(shape: Shape) {
  if (shape.kind === 'circle') {
    return Math.PI * shape.radius ** 2;
    // Object is possibly 'undefined'.
    // Объект, возможно, 'undefined'.
  }
}

И здесь TypeScript не знает, что делать. Мы достигли точки, когда знаем о наших значениях больше, чем средство проверки типов. Мы могли бы попытаться использовать ненулевое утверждение (! после shape.radius), чтобы сказать, что радиус определенно присутствует.

function getArea(shape: Shape) {
  if (shape.kind === 'circle') {
    return Math.PI * shape.radius! ** 2;
  }
}

Но это выглядит не очень. Нам пришлось немного покричать на средство проверки типов с этими ненулевыми утверждениями (!), чтобы убедить его, что shape.radius был определен, но эти утверждения подвержены ошибкам, если мы начнем менять код. Кроме того, за пределами strictNullChecks мы все равно можем случайно получить доступ к любому из этих полей (поскольку предполагается, что необязательные свойства всегда присутствуют при их чтении). Мы определенно можем сделать лучше.

Проблема с этой реализацией Shape заключается в том, что средство проверки типов не может узнать, присутствуют ли radius или sideLength на основе свойства kind. Нам нужно сообщить то, что мы знаем, системе проверки типов. Имея это в виду, давайте еще раз обратимся к определению Shape.

interface Circle {
  kind: 'circle';
  radius: number;
}

interface Square {
  kind: 'square';
  sideLength: number;
}

type Shape = Circle | Square;

Здесь мы правильно разделили Shape на два типа с разными значениями свойства kind, но radius и sideLength объявлены как обязательные свойства в соответствующих типах. Давайте посмотрим, что здесь происходит, когда мы пытаемся получить доступ к радиусу Shape.

function getArea(shape: Shape) {
  return Math.PI * shape.radius ** 2;
  // Property 'radius' does not exist on type 'Shape'.
  // Свойство 'radius' не существует в типе 'Square'.
}

Как и в случае с нашим первой реализацией Shape, это все еще ошибка. Когда радиус был необязательным, мы получили ошибку (с включенной strictNullChecks), потому что TypeScript не мог определить, присутствует ли свойство. Теперь, когда Shape является объединением, TypeScript сообщает нам, что Shape может быть квадратом, а у квадратов не определен радиус! Обе интерпретации верны, но только объединенный тип Shape вызовет ошибку независимо от того, как настроен strictNullChecks. Но что, если мы попытаемся снова проверить свойство kind?

function getArea(shape: Shape) {
  if (shape.kind === 'circle') {
    return Math.PI * shape.radius ** 2;
    // (parameter) shape: Circle
  }
}

Мы избавилась от ошибки. Когда каждый тип в объединении содержит общее свойство с литеральными типами, TypeScript считает это исключающим объединением (discriminated union) и может сузить круг членов объединения. В данном случае это общее свойство было kind (это то, что считается дискриминантным свойством Shape). Проверка того, является ли свойство kind = "circle", избавляет от всех типов в Shape, которые не имеют свойства kind с типом "circle". Эта суженный shape до типа Circle. Та же проверка работает и с операторами switch. Теперь мы можем попытаться написать полную реализацию getArea без каких-либо ! ненулевых утверждений.

function getArea(shape: Shape) {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    // (parameter) shape: Circle

    case 'square':
      return shape.sideLength ** 2;
    // (parameter) shape: Square
  }
}

Передача правильной информации в TypeScript — что Circle и Square на самом деле были двумя отдельными типами с определенными полями kind — была крайне важна. Это позволяет нам писать типобезопасный код TypeScript. Кроме того, попробуйте поиграть с приведенным выше примером и удалить некоторые из возвращаемых ключевых слов. Вы увидите, что проверка типов может помочь избежать ошибок при случайном переходе через разные ветки в операторе switch. Исключающие объединения полезны не только для разделения кругов и квадратов. Они хороши для представления любой схемы обмена сообщениями в JavaScript, например, при отправке сообщений по сети (связь клиент-сервер) или для определения мутаций в библиотеках управления состоянием.

Тип never

При сужении можно уменьшить варианты объединения до такой степени, что можно убрать все возможные варианты и ничего не останется. В таких случаях TypeScript будет использовать тип never для представления состояния, которого не должно быть.

Исчерпывающие проверки (Exhaustiveness checking)

Тип never присваивается каждому типу; однако никакому типу нельзя присвоить значение never (кроме самого never). Это означает, что вы можете использовать сужение и полагаться на never для выполнения исчерпывающих проверок в операторе switch. Например, добавление значения по умолчанию к нашей функции getArea, которая пытается присвоить форме значение never, будет выполняться, если все возможные случаи не были обработаны.

type Shape = Circle | Square;

function getArea(shape: Shape) {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'square':
      return shape.sideLength ** 2;
    default:
      const _exhaustiveCheck: never = shape;
      return _exhaustiveCheck;
  }
}

Добавление нового члена в объединение Shape вызовет ошибку TypeScript:

interface Triangle {
  kind: 'triangle';
  sideLength: number;
}

type Shape = Circle | Square | Triangle;

function getArea(shape: Shape) {
  switch (shape.kind) {
    case 'circle':
      return Math.PI * shape.radius ** 2;
    case 'square':
      return shape.sideLength ** 2;
    default:
      const _exhaustiveCheck: never = shape;
      // Type 'Triangle' is not assignable to type 'never'.
      // Тип 'Triangle' нельзя присвоить типу 'never'.
      return _exhaustiveCheck;
  }
}

Содержание туториала по TypeScript Функции — это основной строительный блок любого приложения, будь то локальные функции, импортированные из другого модуля или методы класса. Они также являются значениями, и, как и другие значения, в TypeScript есть много способов описать, как можно вызывать функции.

Типизация функций

Самый простой способ типизировать функцию — использовать выражение функционального типа. Эти типы синтаксически похожи на стрелочные функции:

function greeter(fn: (a: string) => void) {
  fn('Hello, World');
}

function printToConsole(s: string) {
  console.log(s);
}

greeter(printToConsole);

Синтаксис (a:string) => void означает "функция с одним параметром a, типа string, который не имеет возвращаемого значения". Как и в случае с определением функции, если тип параметра не указан, он будет иметь тип any. Обратите внимание, что имя параметра является обязательным. Тип функции (string) => void означает "функция с параметром, названным string типа any"! Конечно, мы можем использовать псевдоним типа для обозначения типа функции:

type GreetFunction = (a: string) => void;
function greeter(fn: GreetFunction) {
  // ...
}

Сигнатура вызова (Call Signature)

В JavaScript функции могут не только вызываться, но и иметь свойства. Однако синтаксис выражения функционального типа не позволяет объявлять свойства. Если мы хотим описать что-то вызываемое с помощью свойств, мы можем написать сигнатуру вызова в объектном типе:

type DescribableFunction = {
  description: string;
  (someArg: number): boolean;
};
function doSomething(fn: DescribableFunction) {
  console.log(fn.description + ' returned ' + fn(6));
}

Обратите внимание, что синтаксис немного отличается от выражения функционального типа — используется : между списком параметров и возвращаемым типом, а не =>.

Сигнатура конструктора (Construct Signature)

Функции JavaScript также можно вызывать с помощью оператора new. В TypeScript они считаются конструкторами, потому что они обычно создают новый объект. Вы можете написать сигнатуру конструктора, добавив ключевое слово new перед сигнатурой вызова:

type SomeConstructor = {
  new (s: string): SomeObject;
};
function fn(ctor: SomeConstructor) {
  return new ctor('hello');
}

Некоторые объекты, такие как объект Date в JavaScript, можно вызывать как с оператором new, так и без него. Вы можете произвольно комбинировать сигнатуры вызова и конструктора в одном и том же типе:

interface CallOrConstruct {
  new (s: string): Date;
  (n?: number): number;
}

Функции-дженерики (Generic Functions)

Обычно пишут функцию, в которой типы входных данных связаны с типом выходных данных или где типы двух входных данных каким-то образом связаны. Давайте рассмотрим функцию, которая возвращает первый элемент массива:

function firstElement(arr: any[]) {
  return arr[0];
}

Эта функция выполняет свою работу, но, к сожалению, имеет возвращаемый тип any. Лучше бы функция возвращала тип элемента массива. В TypeScript дженерики используются, когда мы хотим описать соответствие между двумя значениями. Мы делаем это, объявляя параметр типа в сигнатуре функции:

function firstElement<Type>(arr: Type[]): Type | undefined {
  return arr[0];
}

Добавив к этой функции параметр Type и используя его в двух местах, мы создали связь между входными данными функции (массивом) и выходными (возвращаемым значением). Теперь, когда мы ее вызываем, получается более конкретный тип:

// s имеет тип 'string'
const s = firstElement(['a', 'b', 'c']);
// n имеет тип 'number'
const n = firstElement([1, 2, 3]);
// u имеет тип undefined
const u = firstElement([]);

Предположение типа (Inference)

Мы можем использовать несколько параметров типа. Например, самописная версия функции map может выглядеть так:

function map<Input, Output>(
  arr: Input[],
  func: (arg: Input) => Output
): Output[] {
  return arr.map(func);
}

// Параметр 'n' имеет тип 'string'
// 'parsed' имеет тип 'number[]'
const parsed = map(['1', '2', '3'], (n) => parseInt(n));

Обратите внимание, что в приведенном примере TypeScript может сделать вывод относительно типа Input на основе переданного string[], а относительно типа Output на основе возвращаемого number.

Ограничения (constraints)

Ограничение используется для того, чтобы ограничивать типы, которые принимаются параметром типа. Реализуем функцию, возвращающую самое длинное из двух значений. Для этого нам потребуется свойство length, которое будет числом. Мы ограничим параметр типа типом number с помощью ключевого слова extends:

function longest<Type extends { length: number }>(a: Type, b: Type) {
  if (a.length >= b.length) {
    return a;
  } else {
    return b;
  }
}

// longerArray имеет тип 'number[]'
const longerArray = longest([1, 2], [1, 2, 3]);
// longerString имеет тип 'alice' | 'bob'
const longerString = longest('alice', 'bob');
// Ошибка! У чисел нет свойства 'length'
const notOK = longest(10, 100);

// Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
// Аргумент типа 'number' не может быть присвоен аргументу типа '{ length: number; }'.

В этом примере есть несколько интересных моментов. Мы позволили TypeScript определять возвращаемый тип самого длинного значения. Вывод типа возвращаемого значения также работает с функциями-дженериками. Поскольку мы ограничили Type значением {length: number}, мы смогли получить доступ к свойству .length параметров a и b. Без ограничения типа мы не смогли бы получить доступ к этим свойствам, потому что значения могли быть какого-то другого типа без свойства length. Типы longerArray и longerString были выведены на основе аргументов. Помните, что дженерики — это связывание двух или более значений с одним и тем же типом. Наконец, как мы и хотели, вызов longest(10, 100) ,был отклонен, потому что тип number не имеет свойства .length.

Работа со значениями с ограничениями

Вот распространенная ошибка при работе с ограничениями-дженериками:

function minimumLength<Type extends { length: number }>(
  obj: Type,
  minimum: number
): Type {
  if (obj.length >= minimum) {
    return obj;
  } else {
    return { length: minimum };

    // Type '{ length: number; }' is not assignable to type 'Type'.
    // '{ length: number; }' is assignable to the constraint of type 'Type', but 'Type' could be instantiated with a different subtype of constraint '{ length: number; }'.
  }
}

Может показаться, что с этой функцией все в порядке — Type ограничен до { length: number }, и функция либо возвращает Type, либо значение, соответствующее этому ограничению. Проблема в том, что функция обещает вернуть тот же тип объекта, который был передан, а не просто какой-то объект, соответствующий ограничению. Если бы этот код был работающим, вы могли бы написать код, который не работал бы:

// 'arr' получает значение { length: 6 }
const arr = minimumLength([1, 2, 3], 6);
// и падает, т.к. массив имеет метод 'slice'
// но не возвращаемый объект!
console.log(arr.slice(0));

Определение типа аргументов

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

function combine<Type>(arr1: Type[], arr2: Type[]): Type[] {
  return arr1.concat(arr2);
}

Обычно было бы ошибкой вызывать эту функцию с несовпадающими массивами:

const arr = combine([1, 2, 3], ['hello']);

// Type 'string' is not assignable to type 'number'.
// Нельзя присвоить тип 'string' типу 'number'.

Однако, если вы намеревались сделать это, вы можете вручную указать Type:

const arr = combine<string | number>([1, 2, 3], ['hello']);

Как написать хорошую функцию-дженерик?

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

Используйте параметры типа без ограничений

Вот два способа написания функции, которые кажутся похожими:

function firstElement1<Type>(arr: Type[]) {
  return arr[0];
}

function firstElement2<Type extends any[]>(arr: Type) {
  return arr[0];
}

// a: number (хорошо)
const a = firstElement1([1, 2, 3]);
// b: any (плохо)
const b = firstElement2([1, 2, 3]);

На первый взгляд они могут показаться идентичными, но firstElement1 — гораздо лучший способ написать эту функцию. Предполагаемый тип возвращаемого значения — Type, но предполагаемый возвращаемый тип firstElement2 — any, поскольку TypeScript должен разрешать выражение arr[0] с использованием типа ограничения, а не «ждать» элемент во время вызова. Правило: по возможности используйте сам параметр типа, а не ограничивайте его.

Используйте меньше параметров типа

Вот еще пара похожих функций:

function filter1<Type>(arr: Type[], func: (arg: Type) => boolean): Type[] {
  return arr.filter(func);
}

function filter2<Type, Func extends (arg: Type) => boolean>(
  arr: Type[],
  func: Func
): Type[] {
  return arr.filter(func);
}

Мы создали параметр типа Func, который не связывает два значения. Это всегда красный флаг, потому что это означает, что вызывающие программы, желающие указать аргументы типа, должны вручную указать дополнительный аргумент типа без всякой причины. Func ничего не делает, но затрудняет чтение и осмысление функции! Правило: всегда используйте как можно меньше параметров типа

Параметры типа должны появляться дважды

Иногда мы забываем, что функции не обязательно быть дженериком:

function greet<Str extends string>(s: Str) {
  console.log('Hello, ' + s);
}

greet('world');

Мы могли бы написать более простую версию:

function greet(s: string) {
  console.log('Hello, ' + s);
}

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

Необязательные параметры

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

function f(n: number) {
  console.log(n.toFixed()); // 0 аргументов
  console.log(n.toFixed(3)); // 1 аргумент
}

Мы можем смоделировать это в TypeScript, пометив параметр как необязательный с помощью ?:

function f(x?: number) {
  // ...
}
f(); // OK
f(10); // OK

Хотя параметр указан как типа number, параметр x на самом деле будет иметь тип number | undefined, потому что неуказанные параметры в JavaScript получают значение undefined. Вы также можете указать параметр по умолчанию:

function f(x = 10) {
  // ...
}

Теперь в теле f, x будет иметь тип number, потому что любой неопределенный аргумент будет заменен на 10. Обратите внимание, что, когда параметр является необязательным, вызывающая сторона всегда может передать значение undefined, так как это просто имитирует «отсутствующий» аргумент:

declare function f(x?: number): void;

// все вызовы допустимы
f();
f(10);
f(undefined);

Необязательные параметры в функциях обратного вызова

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

function myForEach(arr: any[], callback: (arg: any, index?: number) => void) {
  for (let i = 0; i < arr.length; i++) {
    callback(arr[i], i);
  }
}

Обычно при написании index? в качестве необязательного параметр разработчики хотят, чтобы оба этих вызова валидными:

myForEach([1, 2, 3], (a) => console.log(a));
myForEach([1, 2, 3], (a, i) => console.log(a, i));

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

function myForEach(arr: any[], callback: (arg: any, index?: number) => void) {
  for (let i = 0; i < arr.length; i++) {
    callback(arr[i]);
  }
}

В свою очередь, TypeScript будет применять это значение и выдавать ошибки:

myForEach([1, 2, 3], (a, i) => {
  console.log(i.toFixed());
  // Object is possibly 'undefined'.
  // Объект, возможно, 'undefined'.
});

В JavaScript, если вы вызываете функцию с бОльшим количеством аргументов, лишние аргументы просто игнорируются. TypeScript ведет себя точно так же. Функции с меньшим количеством параметров (одного и того же типа) всегда могут заменить функции с бОльшим количеством параметров. При типизации функции для колбека никогда делайте параметр необязательным, если вы не собираетесь вызывать функцию без передачи этого аргумента.

Перегрузка функций (Function Overloads)

Некоторые функции JavaScript можно вызывать с различным числом аргументов и типами. Например, вы можете написать функцию для создания даты Date, которая принимает отметку времени (один аргумент) или спецификацию месяц/день/год (три аргумента). В TypeScript мы можем указать функцию, которую можно вызывать по-разному, написав сигнатуры перегрузки. Для этого нужно написать несколько сигнатур функции (обычно две или более), а затем тело функции:

function makeDate(timestamp: number): Date;
function makeDate(m: number, d: number, y: number): Date;
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);
const d2 = makeDate(5, 5, 5);
const d3 = makeDate(1, 3);

// No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
// Нет перегрузки, ожидающей 2 аргумента, но есть перегрузки, которые ожидают либо 1, либо 3 аргумента.

В этом примере мы написали две перегрузки: одну, принимающую один аргумент, и другую, принимающую три аргумента. Эти первые две сигнатуры называются сигнатурами перегрузки. Затем мы написали реализацию функции с совместимой сигнатурой. Функции имеют сигнатуру реализации, но эту сигнатуру нельзя вызвать напрямую. Несмотря на то, что мы написали функцию с двумя необязательными параметрами после обязательного, ее нельзя вызвать с двумя параметрами!

Сигнатуры перегрузки и сигнатура реализации

Это распространенный источник путаницы. Часто люди пишут такой код и не понимают, почему возникает ошибка:

function fn(x: string): void;
function fn() {
  // ...
}
// Expected to be able to call with zero arguments
// Ожидается, что можно вызвать без аргументов
fn();
// Expected 1 arguments, but got 0.
// Ожидается 1 аргумент, но получено 0.

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

function fn(x: boolean): void;
// Неправильный аргумент функции
function fn(x: string): void;
// This overload signature is not compatible with its implementation signature.
// Эта перегрузка сигнатуры не совместима с сигнатурой реализации.
function fn(x: boolean) {}

function fn(x: string): string;
// Неверный возвращаемый тип
function fn(x: number): boolean;
// This overload signature is not compatible with its implementation signature.
// Cигнатура перегрузки не совместима с сигнатурой реализации.
function fn(x: string | number) {
  return 'oops';
}

Как написать хорошую перегрузку

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

function len(s: string): number;
function len(arr: any[]): number;
function len(x: any) {
  return x.length;
}

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

len(''); // OK
len([0]); // OK
len(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: any[]): number', gave the following error.
//    Argument of type 'number[] | "hello"' is not assignable to parameter of type 'any[]'.
//     Type 'string' is not assignable to type 'any[]'.

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

function len(x: any[] | string) {
  return x.length;
}

Так гораздо лучше! Ее можно вызывать со значением любого типа, и в качестве дополнительного бонуса нам не нужно вычислять правильную сигнатуру реализации. Всегда предпочитайте параметры с объединением вместо перегрузок, когда это возможно.

Определение this в функциях

С помощью анализа потока кода TypeScript сделает вывод о том, чем является this:

const user = {
  id: 123,

  admin: false,
  becomeAdmin: function () {
    this.admin = true;
  },
};

TypeScript понимает, что функция user.becomeAdmin имеет соответствующий this, который является объектом user извне. В спецификации JavaScript указано, что у вас не может быть параметра с именем this, TypeScript использует это, чтобы можно было объявить тип для this в теле функции.

interface DB {
  filterUsers(filter: (this: User) => boolean): User[];
}

const db = getDB();
const admins = db.filterUsers(function (this: User) {
  return this.admin;
});

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

interface DB {
  filterUsers(filter: (this: User) => boolean): User[];
}

const db = getDB();
const admins = db.filterUsers(() => this.admin);
// The containing arrow function captures the global value of 'this'.
// Стрелочная функция захватывает глобальный `this`.

// Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature.
// Элемент неявно имеет тип 'any' т.к. тип 'typeof globalThis' не имеет сигнатуры.

Другие типы, о которых следует знать

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

void

void представляет возвращаемое значение функций, которые не возвращают значения. Этот тип выведется из функции, когда функция не имеет операторов return или не возвращает никакого явного значения из этих операторов return:

// Выведенный тип возвращаемого результата void
function noop() {
  return;
}

В JavaScript функция, которая не возвращает никакого значения, неявно вернет значение undefined. Однако void и undefined — это не одно и то же в TypeScript. Дополнительные подробности приведены в конце этой главы.

object

Специальный тип object относится к любому значению, не являющемуся примитивом (string, number, bigint, boolean, symbol, null или undefined). Это отличается от типа пустого объекта { }, а также отличается от глобального типа Object. Очень вероятно, что вы никогда не будете использовать Object. object не является Object. Всегда используйте object! Обратите внимание, что в JavaScript функции являются объектами: у них есть свойства, есть Object.prototype в своей цепочке прототипов, являются instanceof Object, вы можете вызывать для них Object.keys и т.д. По этой причине типы функций считаются object в TypeScript.

unknown

Тип unknown представляет любое значение. Это похоже на тип any, но безопаснее, потому что нельзя ничего делать с неизвестным значением:

function f1(a: any) {
  a.b(); // OK
}
function f2(a: unknown) {
  a.b();
  // Object is of type 'unknown'.
  // Объект типа 'unknown'.
}

Это полезно при описании типов функций, потому что вы можете описывать функции, которые принимают любое значение, не имея значений any в теле вашей функции. И наоборот, вы можете описать функцию, которая возвращает значение типа unknown:

function safeParse(s: string): unknown {
  return JSON.parse(s);
}

// Нужно быть осторожным с 'obj'!
const obj = safeParse(someRandomString);

never

Некоторые функции никогда не возвращают значение:

function fail(msg: string): never {
  throw new Error(msg);
}

Тип never представляет значения, которые никогда не возвращаются. В возвращаемом типе это означает, что функция выдает исключение или завершает выполнение программы. never появляется, когда TypeScript определяет, что в объединении ничего не осталось.

function fn(x: string | number) {
  if (typeof x === 'string') {
    // что-то делаем
  } else if (typeof x === 'number') {
    // что-то делаем еще
  } else {
    x; // имеет тип 'never'!
  }
}

Function

Глобальный тип Function описывает такие свойства, как bind, call, apply и другие, присутствующие во всех значениях функций в JavaScript. Он также имеет специальное свойство, позволяющее вызывать значения типа Function — такие вызовы возвращают any:

function doSomething(f: Function) {
  return f(1, 2, 3);
}

Это нетипизированный вызов функции, и его обычно лучше избегать из-за небезопасного возвращаемого типа any. Если вам нужно принять произвольную функцию без ее вызова, тип () => void, как правило, безопаснее.

Остальные параметры и аргументы (rest)

Остальные параметры

В дополнение к использованию необязательных параметров или перегрузок функций, которые могут принимать множество фиксированных аргументов, мы также можем определить функции, которые принимают неограниченное количество аргументов, используя синтаксис остальных параметров (rest parameters). Остальные параметры появляется после всех остальных параметров и используют синтаксис ...:

function multiply(n: number, ...m: number[]) {
  return m.map((x) => n * x);
}
// 'a' имеет значение [10, 20, 30, 40]
const a = multiply(10, 1, 2, 3, 4);

В TypeScript аннотация типа для этих параметров неявно является any[] вместо any, и любая указанная аннотация типа должна иметь форму Array<T> или T[] или тип кортежа (о котором мы узнаем позже).

Остальные аргументы

И наоборот, мы можем предоставить переменное количество аргументов из массива, используя синтаксис распыления (spread syntax). Например, метод массивов push принимает любое количество аргументов:

const arr1 = [1, 2, 3];
const arr2 = [4, 5, 6];
arr1.push(...arr2);

Обратите внимание, что в целом TypeScript не предполагает, что массивы иммутабельные. Это может привести к неожиданному поведению:

// Предполагаемый тип number[] - массив с двумя или более числами,
// не конкретно с двумя числами
const args = [8, 5];
const angle = Math.atan2(...args);
// A spread argument must either have a tuple type or be passed to a rest parameter.
// Распыленный аргумент должен быть типом кортежа или отправлен как остальные параметры (rest)

Лучшее решение для этой ситуации зависит от вашего кода, но в целом const является наиболее простым решением:

// Представлен как кортеж длины 2
const args = [8, 5] as const;
// OK
const angle = Math.atan2(...args);

Использование остальных аргументов может потребовать включения downlevelIteration если старые среды выполнения являются целевыми.

Деструктуризация параметров (Parameter Destructuring)

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

function sum({ a, b, c }) {
  console.log(a + b + c);
}
sum({ a: 10, b: 3, c: 9 });

Аннотация типа для объекта идет после синтаксиса деструктурирования:

function sum({ a, b, c }: { a: number; b: number; c: number }) {
  console.log(a + b + c);
}

Это может выглядеть немного многословно, но здесь вы также можете использовать именованный тип:

type ABC = { a: number; b: number; c: number };
function sum({ a, b, c }: ABC) {
  console.log(a + b + c);
}

Присваиваемость функций

Возвращаемый тип void

Возвращаемый тип void для функций может привести к необычному, но ожидаемому поведению. Контекстуальная типизация (contextual typing) с возвращаемым типом void не заставляет функции ничего не возвращать. Иными словами, По-другому можно сказать, что функция с возвращаемым типом void (type vf = () => void), при реализации может вернуть любое другое значение, но оно будет проигнорировано. Таким образом, допустимы следующие реализации () => void:

type voidFunc = () => void;

const f1: voidFunc = () => {
  return true;
};

const f2: voidFunc = () => true;

const f3: voidFunc = function () {
  return true;
};

И когда возвращаемое значение одной из этих функций будет присвоено другой переменной, оно сохранит тип void:

const v1 = f1();

const v2 = f2();

const v3 = f3();

Поэтому следующий код валидный, несмотря на то, что Array.prototype.push возвращает number, а метод Array.prototype.forEach ожидает функцию с возвращаемым типом void.

const src = [1, 2, 3];
const dst = [0];

src.forEach((el) => dist.push(el));

Есть еще один особый случай, о котором следует знать, когда литеральное определение функции имеет возвращаемый тип void, эта функция не должна ничего возвращать.

function f2(): void {
  // @ts-expect-error
  return true;
}

const f3 = function (): void {
  // @ts-expect-error
  return true;
};