As в TypeScript: утверждения типа и приведение типов

value as Type это утверждение типа: оно велит TypeScript считать value типом Type. Его называют приведением, но это лишь указание компилятору. Из JavaScript на выходе оно стирается, ничего не преобразует и ничего не проверяет во время выполнения.

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

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

as и синтаксис угловых скобок

У одного и того же утверждения две записи:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

Форма с угловыми скобками не разрешена в файлах .tsx, где <string> читалось бы как тег JSX. Пишите as везде, и вопрос не возникнет. Утверждения связываются слабо, поэтому оборачивайте их в скобки, если продолжаете выражение: (value as string).length.

Утверждения не преобразуют значения

Именно это вызывает реальные ошибки. Утверждение меняет то, что компилятор думает о значении, а не само значение:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

Компилятор считает, что asserted это number, поэтому asserted + 1 проходит проверку как арифметика. Во время выполнения это по-прежнему строка "42", и JavaScript склеивает строки. Чтобы изменить тип значения, преобразуйте его: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). Функции преобразования сравниваются на странице строка в число.

Что разрешает компилятор

as не безграничен. TypeScript разрешает x as T, когда один тип можно присвоить другому: и расширение ("a" as string, dog as Animal), и сужение (animal as Dog, unknown as User) допустимы. Когда типы совсем не пересекаются, он отказывается:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

Компилятор сообщает index.ts(3,11): error TS2352: 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. Само сообщение называет лазейку: input as unknown as number. Это двойное утверждение компилируется и во время выполнения ровно так же неверно, как пример выше. Когда вам кажется, что оно нужно, правильное исправление обычно это преобразование (Number(input)) или другой тип.

Для объектов правило пересечения мягкое. Объектный литерал, у которого есть некоторые из свойств, принимается, и так as незаметно пропускает неполные объекты:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

Аннотация (const draft: User = { name: "Ada" }) или satisfies User сообщили бы об отсутствующем email (TS2741). Используйте as для объектного литерала, только если действительно собираетесь дозаполнить его позже, а лучше сразу собирайте полный объект.

as const устроен иначе

as const похоже на утверждение, но делает противоположное ослаблению: максимально сужает литерал. Строки остаются литеральными типами, массивы становятся readonly-кортежами, а свойства объектов становятся readonly.

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

Это безопасно, потому что точно описывает литерал, а не утверждает то, чего компилятор не видит. (sizes as readonly string[] внутри isSize это расширяющее утверждение, тоже безопасное: оно позволяет includes принимать любую строку.) Подробнее на странице литеральные типы.

Когда защитник типа подходит лучше

as это утверждение, а защитник типа это проверка. На границе, где данные приходят извне вашего кода (JSON, fetch, localStorage, пользовательский ввод, сообщение), утверждение может оказаться ложным, и as превращает понятную ошибку на границе в запутанную ошибку где-то в другом месте.

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

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

Краткий путеводитель по похожим инструментам:

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