any vs unknown in TypeScript: differenze e quando usarli

any e unknown accettano entrambi qualsiasi valore. La differenza sta in cosa puoi fare con il valore dopo: any ti lascia fare tutto e non controlla nulla, mentre unknown non ti lascia fare quasi nulla finché non dimostri cos'è il valore.

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

Senza la riga @ts-expect-error, u.toUpperCase() è l'errore di compilazione TS18046. Il controllo typeof restringe u a string, e dentro quel blocco tutti i metodi delle stringhe sono disponibili.

any vs unknown in breve

In termini di teoria dei tipi, unknown è il top type: ogni tipo gli è assegnabile, e lui è assegnabile solo a unknown e any. any è una via di fuga assegnabile in entrambe le direzioni, a tutto tranne che a never.

any disattiva il controllo dei tipi

Un valore tipizzato any riceve fiducia cieca. Il compilatore accetta errori di battitura, tipi sbagliati e proprietà mancanti, e gli errori saltano fuori a runtime.

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

L'output mostra il problema: una variabile annotata number contiene una stringa, e l'ultima riga lancia Cannot read properties of undefined (reading 'city'). Inoltre any si propaga. user.name è any, quindi ogni valore calcolato da lì è any, e un solo valore non tipizzato può disattivare i controlli lontano dal punto in cui è entrato.

unknown ti obbliga a controllare prima

Con unknown, il compilatore rifiuta ogni operazione finché il codice non restringe il valore. Per restringere si usano normali controlli JavaScript, e dentro ogni ramo il valore ha il tipo verificato.

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

Il controllo value === null deve venire prima di quello sull'oggetto perché typeof null è "object". Dopo "id" in value, TypeScript sa che l'oggetto ha una proprietà id, tipizzata unknown, perché nulla dice cosa contiene. String() la trasforma esplicitamente in testo; per usarla come numero la controlleresti prima con typeof.

Puoi anche saltare il controllo con un'asserzione, value as string, e il compilatore la accetta. È una promessa senza alcun controllo a runtime dietro, quindi preferisci un controllo vero; vedi le type assertion.

Validare JSON con unknown

JSON.parse è dichiarato con ritorno any, quindi il suo risultato disattiva i controlli in silenzio. Annota il risultato come unknown e scrivi una type guard che verifichi la forma prima che il resto del codice se ne fidi.

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

Il primo input stampa dark at 14px, il secondo viene rifiutato perché manca fontSize. Con any, il secondo input sarebbe passato come Settings con fontSize undefined. Per schemi grandi, una libreria di validazione fa lo stesso lavoro e ricava il tipo al posto tuo.

noImplicitAny

any non arriva solo da chi lo scrive. Anche un parametro senza annotazione e senza contesto da cui dedurre il tipo sarebbe any. L'opzione noImplicitAny, attivata da strict, lo segnala come errore:

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

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

La soluzione è un'annotazione, function double(x: number). Anche scrivere esplicitamente x: any compila, ed è proprio questo il punto: any resta visibile nel codice e si può cercare e revisionare.

Dove any si infila ancora

Anche con strict, queste fonti producono any senza che la parola compaia nel tuo codice:

La variabile del catch è unknown con strict perché si può lanciare qualsiasi cosa, non solo oggetti Error. Restringila con e instanceof Error prima di leggere e.message.

Quando any è accettabile

any non è vietato, ma ognuno è un punto che il compilatore non protegge più. Usi ragionevoli:

• Migrare un codebase JavaScript, dove any segna ciò che non è ancora tipizzato.
• Codice che il sistema di tipi non esprime bene, tenuto piccolo e dietro la firma di una funzione tipizzata.
• Codice di test che passa di proposito dati sbagliati.

Per tutto il resto, unknown copre lo stesso caso "non conosco questo tipo" mantenendo i controlli. Molti team lo impongono con la regola di lint @typescript-eslint/no-explicit-any. Un tipo correlato, Record<string, unknown>, è la scelta abituale per "un oggetto qualsiasi con valori sconosciuti".