as in TypeScript: type assertion e casting spiegati

value as Type è una type assertion: dice a TypeScript di trattare value come Type. Molti la chiamano cast, ma è solo un'istruzione per il compilatore. Viene eliminata dall'output JavaScript, non converte nulla e a runtime non controlla nulla.

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

Questo è l'uso tipico: sai di un valore più di quanto possa sapere il compilatore (qui, la forma di un JSON) e lo dichiari. Se sbagli, niente ti avvisa. Le sezioni seguenti mostrano cosa significa e quando un controllo a runtime è la scelta migliore.

as e la sintassi con le parentesi angolari

La stessa asserzione si può scrivere in due modi:

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

La forma con le parentesi angolari non è ammessa nei file .tsx, dove <string> verrebbe letto come un tag JSX. Usa as ovunque e il problema non si pone. Le asserzioni hanno una precedenza bassa, quindi racchiudile tra parentesi quando prosegui l'espressione: (value as string).length.

Le asserzioni non convertono i valori

Questa è la parte che causa bug veri. Un'asserzione cambia ciò che il compilatore crede di un valore, non il valore stesso:

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

Il compilatore crede che asserted sia un number, quindi asserted + 1 supera il controllo come operazione aritmetica. A runtime è ancora la stringa "42" e JavaScript concatena. Per cambiare il tipo di un valore, convertilo: Number(x), String(x), Boolean(x), BigInt(x), new Date(x). La pagina da stringa a numero confronta le funzioni di conversione.

Cosa permette il compilatore

as non è illimitato. TypeScript permette x as T quando uno dei due tipi è assegnabile all'altro: allargare ("a" as string, dog as Animal) e restringere (animal as Dog, unknown as User) vanno bene entrambi. Quando i tipi non si sovrappongono affatto, lo rifiuta:

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

console.log(n);

Il compilatore segnala 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. Il messaggio stesso indica la scappatoia: input as unknown as number. Quella doppia asserzione compila, ed è sbagliata a runtime esattamente come l'esempio qui sopra. Quando senti il bisogno di usarla, di solito la soluzione giusta è una conversione (Number(input)) o un tipo diverso.

La regola della sovrapposizione è permissiva con gli oggetti. Un oggetto letterale che ha alcune delle proprietà viene accettato, ed è così che as fa passare in silenzio oggetti incompleti:

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

Un'annotazione (const draft: User = { name: "Ada" }) o satisfies User segnalerebbe l'email mancante (TS2741). Usa as su un oggetto letterale solo quando intendi davvero completarlo più avanti, e preferisci costruire l'oggetto completo.

as const è diverso

as const sembra un'asserzione ma fa il contrario di allentare i controlli: rende un letterale il più stretto possibile. Le stringhe restano tipi letterali, gli array diventano tuple readonly e le proprietà degli oggetti diventano 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

È sicuro, perché descrive esattamente il letterale invece di affermare qualcosa che il compilatore non può vedere. (Il sizes as readonly string[] dentro isSize è un'asserzione che allarga il tipo, anch'essa sicura: permette a includes di accettare qualsiasi stringa.) Approfondisci nei literal types.

Quando un type guard è lo strumento migliore

as è un'affermazione; un type guard è un controllo. Al confine in cui i dati arrivano da fuori dal tuo codice (JSON, fetch, localStorage, input dell'utente, un messaggio), l'affermazione può essere falsa, e un'asserzione trasforma un errore chiaro al confine in uno confuso da qualche altra parte.

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

Una guida di massima agli strumenti che si somigliano:

Restano due buoni usi di as: restringere qualcosa che il compilatore non riesce a seguire (una voce di una Map impostata due righe prima, un valore da una libreria senza tipi) e il codice di test che costruisce fixture parziali. Tienili piccoli e vicini al punto in cui sai che l'affermazione è vera.