Сужение типов в 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 В этой главе мы рассмотрим некоторые из наиболее распространенных типов, которые вы найдете в JavaScript коде, и объясним соответствующие способы описания этих типов в TypeScript. Это не исчерпывающий список, и в следующих главах будут описаны другие способы именования и использования других типов. Кроме того, типы могут появляться не только в аннотациях, но и во многих других местах. Когда мы узнаем о самих типах, мы также узнаем о местах, где мы можем ссылаться на эти типы для формирования новых конструкций. Мы начнем с обзора самых основных и распространенных типов, с которыми вы можете столкнуться при написании кода JavaScript или TypeScript. Позже они сформируют основные строительные блоки для более сложных типов.

Примитивы: string, number, boolean

В JavaScript есть три очень часто используемых примитива: string, number и boolean. У каждого есть соответствующий тип в TypeScript. Как и следовало ожидать, это те же самые имена, которые вы увидели бы, если бы использовали оператор JavaScript typeof для значений этих типов:

• string представляет строковые значения, такие как "Hello, world"
• number для чисел вроде 42. В JavaScript нет различий между целочисленными значениями и значениями с плавающей точкой, поэтому нет эквивалента int или float — все просто number
• boolean для двух значений true и false

Типы String, Number и Boolean (начинающиеся с заглавных букв) допустимы, но относятся к некоторым специальным встроенным типам, которые очень редко встречаются в коде. Всегда используйте типы string, number или boolean.

Массивы

Чтобы указать тип массива, например [1, 2, 3], вы можете использовать синтаксис number[]; этот синтаксис работает для любого типа (например, string[] — это массив строк и т.д.). Вы также можете встретить синтаксис Array<number>, что означает то же самое. Мы узнаем больше о синтаксисе T<U>, когда будем рассматривать дженерики (generics). Обратите внимание, что [number] — означает другой тип, а именно кортеж (tuple).

any

TypeScript также имеет специальный тип any, который вы можете использовать всякий раз, когда вы не хотите, чтобы определенное значение вызывало ошибки проверки типов. Когда значение имеет тип any, вы можете получить доступ к любым его свойствам (которые, в свою очередь, будут иметь тип any), вызвать его как функцию, присвоить ему значения любого типа или почти все что угодно. Это валидный синтаксис:

let obj: any = { x: 0 };
// Ни одна из следующих строк кода не вызовет ошибок компилятора.
// Использование any отключает все дальнейшие проверки типов и предполагается, что
// вы знаете эти сценарии лучше, чем TypeScript.
obj.foo();
obj();
obj.bar = 100;
obj = 'hello';
const n: number = obj;

Тип any полезен, когда вы не хотите записывать длинный тип только для того, чтобы убедить TypeScript в том, что конкретная строка кода в порядке.

noImplicitAny

Когда вы не указываете тип и TypeScript не может вывести его из контекста, компилятор обычно по умолчанию использует тип any. Обычно этого следует избегать, потому что тип any не проверяется. Используйте флаг компилятора noImplicitAny, чтобы пометить любое неявное значение any как ошибку.

Аннотации типов переменных

Когда вы объявляете переменную с помощью const, var или let, вы можете дополнительно добавить аннотацию типа, чтобы явно указать тип переменной:

let myName: string = 'Alice';

TypeScript не использует объявления в стиле «типы слева», такие как int x = 0; Аннотации типа всегда будут находится после. Однако в большинстве случаев в этом нет необходимости. Везде, где это возможно, TypeScript пытается автоматически определить типы в вашем коде. Например, тип переменной выводится на основе типа ее инициализатора:

// Аннотации типа не требуются — тип 'myName' выводится как 'string'
let myName = 'Alice';

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

Функции

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

Аннотации типов параметров

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

// Аннотация типа параметра
function greet(name: string) {
  console.log('Hello, ' + name.toUpperCase() + '!!');
}

Когда параметр имеет аннотацию типа, будут проверены аргументы этой функции:

// При вызове возникнет ошибка времени выполнения
greet(42);

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

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

Аннотации типа возвращаемого значения

Вы также можете добавить аннотации типа возвращаемого значения. Аннотации типа возвращаемого значения добавляется после списка параметров:

function getFavoriteNumber(): number {
  return 26;
}

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

Анонимные функции

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

// Здесь нет аннотаций типов, но TypeScript может обнаружить ошибку
const names = ['Alice', 'Bob', 'Eve'];

// Определение типа на основе контекста
names.forEach(function (s) {
  console.log(s.toUppercase());

  // Property 'toUppercase' does not exist on type 'string'. Did you mean 'toUpperCase'?
});

// Определение типа на основе контекста вызова функции также работает и для стрелочных функций
names.forEach((s) => {
  console.log(s.toUppercase());

  // Property 'toUppercase' does not exist on type 'string'. Did you mean 'toUpperCase'?
});

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

Типы объектов

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

// Аннотация типа параметра является типом объекта
function printCoord(pt: { x: number; y: number }) {
  console.log("The coordinate's x value is " + pt.x);
  console.log("The coordinate's y value is " + pt.y);
}
printCoord({ x: 3, y: 7 });

Здесь мы типизировали параметр двумя свойствами — x и y — оба типа number. Вы можете использовать , или ; для разделения свойств, а последний разделитель необязателен. Указание типа каждого свойства также необязательно. Если вы не укажете тип, он будет считаться any.

Необязательные свойства

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

function printName(obj: { first: string; last?: string }) {
  // ...
}
// Следующие вызовы не вызовут ошибок
printName({ first: 'Bob' });
printName({ first: 'Alice', last: 'Alisson' });

В JavaScript, если вы обращаетесь к несуществующему свойству, вы получите значение undefined, а не ошибку времени выполнения. Из-за этого, когда вы читаете из необязательного свойства, вам придется проверять его на undefined перед его использованием.

function printName(obj: { first: string; last?: string }) {
  // Ошибка, если obj.last не предоставлен:
  console.log(obj.last.toUpperCase());
Object is possibly 'undefined'.
  if (obj.last !== undefined) {
    // OK
    console.log(obj.last.toUpperCase());
  }

  // Безопасная альтернатива с использованием современного синтаксиса JavaScript:
  console.log(obj.last?.toUpperCase());
}

Объединение типов (Unions)

Система типов TypeScript позволяет вам создавать новые типы из существующих, используя большое количество операторов. Теперь, когда мы знаем, как писать несколько типов, пора начать комбинировать их интересными способами.

Определение объединенного типа

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

function printId(id: number | string) {
  console.log('Your ID is: ' + id);
}
// OK
printId(101);
// OK
printId('202');
// Ошибка
printId({ myID: 22342 });

// Argument of type '{ myID: number; }' is not assignable to parameter of type 'string | number'.

Работа с объединенными типами

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

function printId(id: number | string) {
  console.log(id.toUpperCase());

  // Property 'toUpperCase' does not exist on type 'string | number'.
  // Property 'toUpperCase' does not exist on type 'number'.
}

Решение состоит в том, чтобы сузить объединение с помощью кода, как в JavaScript без аннотаций типов. Сужение происходит, когда TypeScript может определить более конкретный тип для значения на основе структуры кода. Например, TypeScript знает, что только строковое значение будет иметь значение "string" при применении оператора typeof:

function printId(id: number | string) {
  if (typeof id === 'string') {
    // Здесь id имеет тип 'string'
    console.log(id.toUpperCase());
  } else {
    // Здесь id имеет тип 'number'
    console.log(id);
  }
}

Другой пример — использование такой функции, как Array.isArray:

function welcomePeople(x: string[] | string) {
  if (Array.isArray(x)) {
    // Здесь: 'x' это 'string[]'
    console.log('Hello, ' + x.join(' and '));
  } else {
    // Здесь: 'x' это 'string'
    console.log('Welcome lone traveler ' + x);
  }
}

Обратите внимание, что в ветке else нам не нужно делать ничего особенного — если x не является string[], то это должна быть строка. Иногда у вас будет объединение, в котором все члены имеют что-то общее. Например, и массивы, и строки имеют метод slice. Если у каждого члена объединения есть общее свойство, вы можете использовать это свойство без сужения:

// Возвращаемый тип определяется из number[] | string
function getFirstThree(x: number[] | string) {
  return x.slice(0, 3);
}

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

Псевдонимы типов (алиасы, aliases)

Мы использовали типы объектов и типы объединения, записывая их непосредственно в аннотациях типов. Это удобно, но часто хочется использовать один и тот же тип более одного раза и ссылаться на него по одному имени. Псевдоним типа — это именно то, что является именем для любого типа. Синтаксис псевдонима типа:

type Point = {
  x: number;
  y: number;
};

// Тоже самое как и в прошлом примере
function printCoord(pt: Point) {
  console.log("The coordinate's x value is " + pt.x);
  console.log("The coordinate's y value is " + pt.y);
}

printCoord({ x: 100, y: 100 });

Вы можете использовать псевдоним типа, чтобы дать имя любому типу, а не только объектному типу. Например, псевдоним типа может включать тип объединения:

type ID = number | string;

Обратите внимание, что псевдонимы — это всего лишь псевдонимы — вы не можете использовать псевдонимы типов для создания разных/отличных «версий» одного и того же типа. Другими словами, этот код может выглядеть недопустимым, но в соответствии с TypeScript это нормально, потому что оба типа являются псевдонимами для одного и того же типа:

type UserInputSanitizedString = string;

function sanitizeInput(str: string): UserInputSanitizedString {
  return sanitize(str);
}

// Значение типа UserInputSanitizedString
let userInput = sanitizeInput(getInput());

// может также присваивать строку
userInput = 'new input';

Интерфейсы

Объявление интерфейса — это еще один способ объявить тип объекта:

interface Point {
  x: number;
  y: number;
}

function printCoord(pt: Point) {
  console.log("The coordinate's x value is " + pt.x);
  console.log("The coordinate's y value is " + pt.y);
}

printCoord({ x: 100, y: 100 });

Точно так же, как когда мы использовали псевдоним типа выше, пример работает так же, как если бы мы использовали анонимный тип объекта. TypeScript заботится только о структуре значения, которое мы передали в printCoord, — то, что оно имеет ожидаемые свойства. Занимаясь только структурой и возможностями типов, мы называем TypeScript структурно типизированной (structurally typed) системой типов.

Различия между псевдонимами и интерфейсами

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

interface Animal {
  name: string;
}

interface Bear extends Animal {
  honey: boolean;
}

const bear = getBear();
bear.name;
bear.honey;

Расширение типа через пересечения:

type Animal = {
  name: string;
};

type Bear = Animal & {
  honey: boolean;
};

const bear = getBear();
bear.name;
bear.honey;

Добавление новых полей в существующий интерфейс:

interface Window {
  title: string;
}

interface Window {
  ts: TypeScriptAPI;
}

const src = 'const a = "Hello World"';
window.ts.transpileModule(src, {});

Тип нельзя изменить после создания:

type Window = {
  title: string;
};

type Window = {
  ts: TypeScriptAPI;
};

// Error: Duplicate identifier 'Window'

Вы узнаете больше об этих понятиях в следующих главах, так что не беспокойтесь, если вы не сразу все поймете.

• До TypeScript версии 4.2 имена псевдонимов могут появляться в сообщениях об ошибках, иногда вместо эквивалентного анонимного типа. Интерфейсы всегда будут иметь имена в сообщениях об ошибках.
• Псевдонимы типов не могут участвовать в слиянии объявлений, но интерфейсы могут.
• Интерфейсы могут использоваться только для объявления форм объектов, а не для переименования примитивов.
• Имена интерфейсов всегда будут отображаться в исходном виде в сообщениях об ошибках, но только тогда, когда они используются по имени.

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

Утверждения типа (Type Assertions)

Иногда у вас будет информация о типе значения, о котором TypeScript не может узнать. Например, если вы используете document.getElementById, TypeScript знает только, что это вернет какой-то HTMLElement, но вы можете знать, что на вашей странице всегда будет HTMLCanvasElement с заданным идентификатором. В этой ситуации вы можете использовать утверждение типа, чтобы указать более конкретный тип:

const myCanvas = document.getElementById('main_canvas') as HTMLCanvasElement;

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

const myCanvas = <HTMLCanvasElement>document.getElementById('main_canvas');

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

const x = 'hello' as number;

// Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.

Иногда это правило может быть слишком консервативным и запрещать более сложные приведения, которые могут быть действительными. Если это произойдет, вы можете использовать два утверждения, сначала для any (или unknown, о котором мы расскажем позже), затем для нужного типа:

const a = expr as any as T;

Литеральные типы (Literal Types)

В дополнение к общим типам string и number мы можем ссылаться на определенные строки и числа в позициях типа. Один из способов подумать об этом — рассмотреть, как в JavaScript существуют различные способы объявления переменных. И var, и let позволяют изменять содержимое переменной, а const — нет. Это отражено в том, как TypeScript создает типы для литералов.

let changingString = 'Hello World';
changingString = 'Olá Mundo';
// Поскольку `changingString` может представлять любую возможную строку, именно так TypeScript описывает ее в системе типов

const constantString = 'Hello World';
// Поскольку `constantString` может представлять только 1 возможную строку, она имеет буквальное представление типа.

Сами по себе литеральные типы не очень ценны:

let x: 'hello' = 'hello';
// OK
x = 'hello';
// ...
x = 'howdy';
// Type '"howdy"' is not assignable to type '"hello"'.

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

function printText(s: string, alignment: 'left' | 'right' | 'center') {
  // ...
}
printText('Hello, world', 'left');
printText("G'day, mate", 'centre');

// Argument of type '"centre"' is not assignable to parameter of type '"left" | "right" | "center"'.

Типы числовых литералов работают так же:

function compare(a: string, b: string): -1 | 0 | 1 {
  return a === b ? 0 : a > b ? 1 : -1;
}

Конечно, вы можете комбинировать их с нелитеральными типами:

interface Options {
  width: number;
}
function configure(x: Options | 'auto') {
  // ...
}
configure({ width: 100 });
configure('auto');
configure('automatic');

// Argument of type '"automatic"' is not assignable to parameter of type 'Options | "auto"'.

Есть еще один вид литералов: boolean литералы. Есть только два типа логических литералов, и, как вы могли догадаться, это true и false. Сам тип boolean на самом деле является просто псевдонимом объединения true | false.

Вывод литералов

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

const obj = { counter: 0 };
if (someCondition) {
  obj.counter = 1;
}

TypeScript не считает, что присвоение 1 полю, которое ранее имело 0, является ошибкой. Другой способ выразить тоже самое это то, что obj.counter должен иметь тип number, а не 0, потому что типы используются для определения поведения как при чтении, так и при записи. То же самое относится и к строкам:

const req = { url: 'https://example.com', method: 'GET' };
handleRequest(req.url, req.method);

// Argument of type 'string' is not assignable to parameter of type '"GET" | "POST"'.

В приведенном выше примере req.method подразумевается как строка, а не как "GET". Поскольку код можно обработать между созданием req и вызовом handleRequest, который может назначить новую строку, например "GUESS", для req.method, TypeScript считает, что этот код содержит ошибку. Есть два способа решить это.

• Вы можете изменить вывод, добавив утверждение типа в любом месте:

// Изменение 1:
const req = { url: 'https://example.com', method: 'GET' as 'GET' };
// Изменение 2:
handleRequest(req.url, req.method as 'GET');

Изменение 1 означает: "Я говорю, что req.method всегда имеет литеральный тип "GET"", предотвращая возможное назначение "GUESS" этому полю после этого. Изменение 2 означает "Я знаю, что req.method имеет значение "GET"". Вы можете использовать as const для преобразования всего объекта в литералы типов:

const req = { url: 'https://example.com', method: 'GET' } as const;
handleRequest(req.url, req.method);

Суффикс as const действует как const, но для системы типов, гарантируя, что всем свойствам будет присвоен литеральный тип, а не более общая версия, такая как string или number.

null и undefined

В JavaScript есть два примитивных значения, которые используются для обозначения отсутствия или неинициализации значения: null и undefined. TypeScript имеет два соответствующих типа с соответствующими именами. Поведение этих типов зависит от того, включена ли у вас опция strictNullChecks.

strictNullChecks выключен

Если strictNullChecks выключен, значения, которые могут быть null или undefined, по-прежнему могут быть доступны в обычном режиме, а значения null или undefined могут быть присвоены свойству любого типа. Это похоже на то, как ведут себя языки без проверок на null (например, C#, Java). Отсутствие проверки этих значений, как правило, является основным источником ошибок; мы всегда рекомендуем включать strictNullChecks, если это целесообразно в кодовой базе.

strictNullChecks включен

При включении strictNullChecks, когда значение равно null или undefined, вам нужно будет проверить эти значения, прежде чем использовать методы или свойства для этого значения. Точно так же, как проверка на undefined перед использованием необязательного свойства, мы можем использовать сужение для проверки значений, которые могут быть null:

function doSomething(x: string | null) {
  if (x === null) {
    // do nothing
  } else {
    console.log('Hello, ' + x.toUpperCase());
  }
}

Оператор ненулевого утверждения (Non-null Assertion Operator, постфикс !)

TypeScript также имеет специальный синтаксис для удаления null и undefined из типа без какой-либо явной проверки. Добавление ! после выражения фактически является утверждением того, что значение не является null или undefined:

function liveDangerously(x?: number | null) {
  // No error
  console.log(x!.toFixed());
}

Как и другие утверждения типа, это не меняет поведение вашего кода во время выполнения, поэтому важно использовать только ! когда вы знаете, что значение не может быть null или undefined.

Перечисления (Enums)

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

Менее распространенные примитивы

Стоит упомянуть остальные примитивы в JavaScript, представленные в системе типов.

bigint

Начиная с ES2020, в JavaScript есть примитив, используемый для очень больших целых чисел, BigInt:

// Создание значения bigint через функцию BigInt
const oneHundred: bigint = BigInt(100);

// Создание значения BigInt через литеральный синтаксис
const anotherHundred: bigint = 100n;

symbol

В JavaScript есть примитив, используемый для создания глобальной уникальной ссылки с помощью функции Symbol():

const firstName = Symbol('name');
const secondName = Symbol('name');

if (firstName === secondName) {
  /// This condition will always return 'false' since the types 'typeof firstName' and 'typeof secondName' have no overlap.
  // Can't ever happen
}