any vs unknown en TypeScript : différences et cas d'usage

any et unknown acceptent toutes les valeurs. La différence tient à ce que vous pouvez faire ensuite avec la valeur : any vous laisse tout faire et ne vérifie rien, alors que unknown ne vous laisse presque rien faire tant que vous n'avez pas prouvé ce qu'est la valeur.

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
}

Sans la ligne @ts-expect-error, u.toUpperCase() provoque l'erreur de compilation TS18046. La vérification typeof affine u en string, et dans ce bloc toutes les méthodes de chaîne sont disponibles.

any ou unknown en un coup d'œil

En termes de théorie des types, unknown est le type supérieur (top type) : tout type lui est assignable, et il n'est assignable qu'à unknown et à any. any est une échappatoire assignable dans les deux sens, à tout sauf never.

any désactive la vérification des types

Une valeur typée any bénéficie d'une confiance aveugle. Le compilateur accepte les fautes de frappe, les mauvais types et les propriétés manquantes, et les erreurs apparaissent à l'exécution à la place.

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

La sortie montre le problème : une variable annotée number contient une chaîne, et la dernière ligne lève Cannot read properties of undefined (reading 'city'). any se propage aussi. user.name est any, donc toute valeur calculée à partir de lui est any, et une seule valeur non typée peut désactiver la vérification loin de l'endroit où elle est entrée.

unknown vous oblige à vérifier d'abord

Avec unknown, le compilateur refuse toute opération tant que le code n'a pas affiné la valeur. L'affinage utilise des vérifications JavaScript ordinaires, et dans chaque branche la valeur a le type vérifié.

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

La vérification value === null doit précéder celle de l'objet, car typeof null vaut "object". Après "id" in value, TypeScript sait que l'objet possède une propriété id, typée unknown, puisque rien n'indique ce qu'elle contient. String() la convertit explicitement en texte ; pour l'utiliser comme un nombre, il faudrait d'abord la vérifier avec typeof.

Vous pouvez aussi sauter la vérification avec une assertion, value as string, et le compilateur l'accepte. C'est une promesse sans aucune vérification à l'exécution derrière elle : préférez une vraie vérification ; voir assertions de type.

Valider du JSON avec unknown

JSON.parse est déclaré comme renvoyant any, son résultat désactive donc la vérification en silence. Annotez le résultat en unknown et écrivez un type guard qui vérifie la forme avant que le reste du code ne lui fasse confiance.

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

La première entrée affiche dark at 14px, la seconde est refusée car fontSize manque. Avec any, la seconde entrée aurait circulé comme un Settings avec un fontSize indéfini. Pour les gros schémas, une bibliothèque de validation fait le même travail et dérive le type pour vous.

noImplicitAny

any ne vient pas seulement de ceux qui l'écrivent. Un paramètre sans annotation et sans contexte d'inférence serait any lui aussi. L'option noImplicitAny, activée par strict, signale cela comme une erreur :

// 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 correction est une annotation, function double(x: number). Écrire explicitement x: any compile aussi, et c'est justement le but : any reste visible dans le code, on peut le rechercher et le relire.

Par où any se glisse encore

Même avec strict, ces cas produisent any sans que le mot n'apparaisse dans votre code :

La variable de catch est unknown avec strict, car on peut lever n'importe quoi, pas seulement des objets Error. Affinez-la avec e instanceof Error avant de lire e.message.

Quand any est acceptable

any n'est pas interdit, mais chaque occurrence est un endroit que le compilateur ne protège plus. Usages raisonnables :

• La migration d'une base de code JavaScript, où any marque ce qui n'est pas encore typé.
• Du code que le système de types exprime mal, gardé petit et derrière une signature de fonction typée.
• Du code de test qui passe volontairement de mauvaises données.

Pour tout le reste, unknown couvre le même cas « je ne connais pas ce type » tout en gardant les vérifications. Beaucoup d'équipes l'imposent avec la règle de lint @typescript-eslint/no-explicit-any. Un type voisin, Record<string, unknown>, est le choix habituel pour « un objet aux valeurs inconnues ».