Вывод типов в TypeScript: когда писать аннотации

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

let count = 0;            // number
let language = "TypeScript"; // string
let tags = ["ts", "js"];  // string[]
let user = { name: "Ada", age: 36 }; // { name: string; age: number }

function area(w: number, h: number) {
    return w * h;          // return type inferred as number
}

const size = area(3, 4);  // number
console.log(count, language, tags, user, size);

// The inferred types are enforced like written ones:
// @ts-expect-error: Type 'string' is not assignable to type 'number'.
count = "one";

Комментарии показывают, что отображает редактор при наведении на каждое имя. Последняя строка это ошибка компиляции (TS2322), хотя count никогда не аннотировалась; // @ts-expect-error помечает её как ожидаемую, чтобы остальной блок запустился.

let и const: расширение литералов

const никогда не меняется, поэтому TypeScript даёт ей самый узкий тип: само литеральное значение. let получает более широкий тип, потому что её могут переприсвоить позже.

let a = "left";    // string
const b = "left";  // "left"
let c = 42;        // number
const d = 42;      // 42
const e = true;    // true

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

// This does not compile: `let` widened "left" to string.
function move(direction: "left" | "right") {
    console.log("moving", direction);
}

let dir = "left";
move(dir);

const fixed = "left";
move(fixed); // fine: fixed has type "left"

index.ts(7,6): error TS2345: Argument of type 'string' is not assignable to parameter of type '"left" | "right"'.

Исправить можно через const или аннотацию переменной: let dir: "left" | "right" = "left". Литеральным типам посвящена отдельная страница, литеральные типы.

Объекты и массивы расширяют свои элементы

Свойства объектного литерала изменяемы, поэтому они расширяются так же, как let, даже если сам объект объявлен через const. С элементами массива то же самое. as const делает всё readonly и сохраняет литеральные типы.

const config = { mode: "dark", retries: 3 };
// config: { mode: string; retries: number }
config.mode = "light"; // allowed: mode is string

const frozen = { mode: "dark", retries: 3 } as const;
// frozen: { readonly mode: "dark"; readonly retries: 3 }

const sizes = ["s", "m", "l"];            // string[]
const fixedSizes = ["s", "m", "l"] as const; // readonly ["s", "m", "l"]

console.log(config.mode, frozen.mode, sizes.length, fixedSizes[0]);

Вывод возвращаемого типа

Возвращаемый тип функции выводится из её операторов return. Если их несколько, результат это объединение их типов.

function parsePort(text: string) {
    if (text === "") return null;
    return Number(text);
}
// parsePort returns number | null

const port = parsePort("8080");
if (port !== null) {
    console.log(port + 1); // 8081: port is number inside the check
}

function log(message: string) {
    console.log(message);
}
// log returns void: there is no return value

log("done");

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

Контекстная типизация: колбэки получают типы

Параметры не выводятся из того, как функция вызывается. Есть два исключения. Параметр со значением по умолчанию получает тип этого значения (function retry(times = 3) делает times типом number). И функция, написанная там, где уже ожидается функциональный тип, получает типы параметров из этого контекста, поэтому параметрам колбэков аннотация не нужна.

const names = ["ada", "grace", "alan"];

// s is string: map on a string[] passes strings
const upper = names.map((s) => s.toUpperCase());

// a and b are strings, the result must be a number
const sorted = [...names].sort((a, b) => a.length - b.length);

// The variable's type gives the arrow its parameter and return types
const greet: (name: string) => string = (n) => `Hello, ${n}`;

console.log(upper, sorted, greet("Ada"));

То же работает для forEach, filter, reduce, колбэков Promise, обработчиков событий и любой функции, которую вы передаёте в параметр с объявленным функциональным типом.

Параметрам нужны аннотации

Без значения по умолчанию или такого контекста TypeScript не смотрит, как вызывается функция, чтобы угадать типы её параметров. При включённом strict параметр без аннотации даёт ошибку TS7006:

// This does not compile: a parameter with no type and no context.
function double(x) {
    return x * 2;
}
console.log(double(21));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

Напишите function double(x: number), и блок напечатает 42, а возвращаемый тип number выведется из x * 2.

Наилучший общий тип

Для литерала массива со значениями разных видов TypeScript выводит массив из объединения их типов. Общий базовый тип, который вы не упомянули, он не ищет.

const mixed = [1, "two", null]; // (string | number | null)[]
const nums = [1, 2.5, -3];      // number[]

class Animal { name = "animal"; }
class Dog extends Animal { bark() { return "woof"; } }
class Cat extends Animal { meow() { return "meow"; } }

const pets = [new Dog(), new Cat()];            // (Cat | Dog)[]
const animals: Animal[] = [new Dog(), new Cat()]; // annotate to get Animal[]

console.log(mixed.length, nums, pets.length, animals[0].name);

Единственный случай, за которым стоит следить, это пустой массив. const list = [] начинается как «эволюционирующий» массив, тип которого растёт с каждым push; аннотация const list: string[] = [] сразу обозначает намерение и читается яснее.

Когда писать аннотацию

Быстрее всего увидеть выведенный тип, наведя курсор на имя в редакторе. Без редактора присвойте значение переменной неверного типа, например const probe: boolean = mixed;, и сообщение компилятора об ошибке назовёт выведенный тип.