TypeScript as: asercje typów i rzutowanie

value as Type to asercja typu: mówi TypeScriptowi, żeby traktował value jako Type. Często nazywa się to rzutowaniem, ale to tylko instrukcja dla kompilatora. Znika z wyjściowego JavaScriptu, niczego nie konwertuje i niczego nie sprawdza w czasie wykonania.

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

To typowe użycie: wiesz o wartości więcej, niż może wiedzieć kompilator (tutaj znasz kształt jakiegoś JSON-a), i to mówisz. Jeśli się mylisz, nic cię nie ostrzeże. Kolejne sekcje pokazują, co to oznacza i kiedy lepszym wyborem jest sprawdzenie w czasie wykonania.

as i składnia z nawiasami ostrymi

Tę samą asercję można zapisać na dwa sposoby:

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

Forma z nawiasami ostrymi jest niedozwolona w plikach .tsx, gdzie <string> zostałoby odczytane jako tag JSX. Używaj wszędzie as, a ten problem nigdy się nie pojawi. Asercje wiążą słabo, więc gdy kontynuujesz wyrażenie, otocz je nawiasami: (value as string).length.

Asercje nie konwertują wartości

To ta część, która powoduje prawdziwe błędy. Asercja zmienia to, co kompilator myśli o wartości, a nie samą wartość:

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

Kompilator uważa, że asserted to number, więc asserted + 1 przechodzi sprawdzanie typów jako działanie arytmetyczne. W czasie wykonania to nadal string "42" i JavaScript łączy stringi. Żeby zmienić typ wartości, przekonwertuj ją: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). Strona string na number porównuje funkcje konwersji.

Na co pozwala kompilator

as nie jest nieograniczone. TypeScript pozwala na x as T, gdy jeden typ da się przypisać do drugiego: poszerzanie ("a" as string, dog as Animal) i zawężanie (animal as Dog, unknown as User) są w porządku. Gdy typy w ogóle się nie pokrywają, kompilator odmawia:

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

console.log(n);

Kompilator zgłasza 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. Sam komunikat wskazuje furtkę: input as unknown as number. Ta podwójna asercja się kompiluje i w czasie wykonania jest dokładnie tak samo błędna jak powyższy przykład. Gdy czujesz, że jej potrzebujesz, właściwą poprawką jest zwykle konwersja (Number(input)) albo inny typ.

Reguła pokrywania się typów jest luźna dla obiektów. Literał obiektu, który ma część właściwości, jest akceptowany i w ten sposób as po cichu przepuszcza niekompletne obiekty:

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

Adnotacja (const draft: User = { name: "Ada" }) albo satisfies User zgłosiłyby brakujące email (TS2741). Używaj as na literale obiektu tylko wtedy, gdy naprawdę zamierzasz uzupełnić go później, a najlepiej od razu buduj kompletny obiekt.

as const to coś innego

as const wygląda jak asercja, ale robi coś przeciwnego do luzowania: sprawia, że literał jest tak wąski, jak to możliwe. Stringi pozostają typami literałów, tablice stają się krotkami readonly, a właściwości obiektów stają się 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

To jest bezpieczne, bo dokładnie opisuje literał, zamiast twierdzić coś, czego kompilator nie widzi. (sizes as readonly string[] w isSize to asercja poszerzająca, też bezpieczna: pozwala includes przyjąć dowolny string.) Więcej na stronie o typach literałów.

Kiedy lepszym narzędziem jest type guard

as to twierdzenie, a type guard to sprawdzenie. Na granicy, gdzie dane przychodzą spoza twojego kodu (JSON, fetch, localStorage, dane od użytkownika, wiadomość), twierdzenie może być fałszywe, a asercja zamienia czytelny błąd na granicy w mylący błąd gdzieś indziej.

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");

Z grubsza, jak dobrać narzędzia, które wyglądają podobnie:

Zostają dwa dobre zastosowania as: zawężenie czegoś, czego kompilator nie potrafi prześledzić (wpis w Map ustawiony dwie linie wcześniej, wartość z nieotypowanej biblioteki), i kod testów, który buduje częściowe dane testowe. Trzymaj je w małej skali i blisko miejsca, w którym wiesz, że twierdzenie jest prawdziwe.