as en TypeScript : assertions de type et « cast » expliqués

value as Type est une assertion de type : elle demande à TypeScript de traiter value comme un Type. On parle souvent de cast, mais ce n'est qu'une instruction donnée au compilateur. Elle est effacée de la sortie JavaScript, ne convertit rien et ne vérifie rien à l'exécution.

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

C'est l'usage typique : vous en savez plus sur une valeur que le compilateur (ici, la forme d'un JSON), et vous le lui dites. Si vous vous trompez, rien ne vous avertit. Les sections suivantes montrent ce que cela implique et quand une vérification à l'exécution est un meilleur choix.

as et la syntaxe à chevrons

La même assertion s'écrit de deux façons :

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

La forme à chevrons n'est pas autorisée dans les fichiers .tsx, où <string> se lirait comme une balise JSX. Utilisez as partout et la question ne se pose jamais. Les assertions ont une priorité faible : entourez-les de parenthèses quand l'expression continue, (value as string).length.

Les assertions ne convertissent pas les valeurs

C'est ce point qui cause de vrais bugs. Une assertion change ce que le compilateur croit d'une valeur, pas la valeur elle-même :

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

Le compilateur croit que asserted est un number, donc asserted + 1 passe la vérification comme une opération arithmétique. À l'exécution, c'est toujours la chaîne "42", et JavaScript concatène. Pour changer le type d'une valeur, convertissez-la : Number(x), String(x), Boolean(x), BigInt(x), new Date(x). La page convertir une chaîne en nombre compare les fonctions de conversion.

Ce qu'autorise le compilateur

as n'est pas illimité. TypeScript autorise x as T quand l'un des types est assignable à l'autre : élargir ("a" as string, dog as Animal) comme affiner (animal as Dog, unknown as User) est accepté. Quand les types ne se recouvrent pas du tout, il refuse :

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

console.log(n);

Le compilateur signale 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. Le message nomme lui-même l'échappatoire : input as unknown as number. Cette double assertion compile, et elle est exactement aussi fausse à l'exécution que l'exemple précédent. Quand vous en ressentez le besoin, la bonne correction est en général une conversion (Number(input)) ou un autre type.

La règle de recouvrement est souple pour les objets. Un littéral objet qui possède une partie des propriétés est accepté, et c'est ainsi que as laisse discrètement passer des objets incomplets :

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

Une annotation (const draft: User = { name: "Ada" }) ou satisfies User signalerait l'email manquant (TS2741). N'utilisez as sur un littéral objet que si vous comptez vraiment le compléter plus tard, et préférez construire l'objet complet.

as const, c'est autre chose

as const ressemble à une assertion mais fait l'inverse d'un assouplissement : il rend un littéral aussi étroit que possible. Les chaînes restent des types littéraux, les tableaux deviennent des tuples readonly et les propriétés d'objet deviennent 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

C'est sûr, car cela décrit exactement le littéral au lieu d'affirmer quelque chose que le compilateur ne peut pas voir. (Le sizes as readonly string[] dans isSize est une assertion d'élargissement, sûre elle aussi : elle permet à includes d'accepter n'importe quelle chaîne.) Voir types littéraux pour en savoir plus.

Quand un type guard est le meilleur outil

as est une affirmation ; un type guard est une vérification. À une frontière où les données viennent de l'extérieur de votre code (JSON, fetch, localStorage, saisie utilisateur, message), l'affirmation peut être fausse, et une assertion transforme une erreur claire à la frontière en une erreur déroutante ailleurs.

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

Un guide sommaire des outils qui se ressemblent :

Il reste deux bons usages de as : affiner quelque chose que le compilateur ne peut pas suivre (une entrée de Map que vous avez définie deux lignes plus haut, une valeur d'une bibliothèque non typée), et le code de test qui construit des fixtures partielles. Gardez-les petits et proches de l'endroit où vous savez que l'affirmation est vraie.