Excess property checks, ou la fraîcheur d'un littéral Excess property checks, or a literal's freshness

Le structurel avalerait la faute de frappe. Un contrôle l'arrête.Structural typing would swallow the typo. One check stops it.

Vol 1.1 l'a posé : un objet avec des champs en trop passe, du moment qu'il a la bonne forme. Mais alors un isAdmin mal tapé — au lieu de admin — devrait passer aussi, et la propriété attendue resterait silencieusement vide. TypeScript fait ici une exception : sur un littéral écrit à l'endroit même, il refuse les champs inconnus.Vol 1.1 established it: an object with extra fields passes, as long as it has the right shape. But then a mistyped isAdmin — instead of admin — should pass too, and the expected property would stay silently empty. TypeScript makes an exception here: on a literal written at the very spot, it rejects unknown fields.

type Options = { name: string; admin?: boolean };

function createUser(o: Options) { /* ... */ }

createUser({ name: "Ada", isAdmin: true });
//                        ^^^^^^^
// error: Object literal may only specify known properties,
//        but 'isAdmin' does not exist in type 'Options'.
//        Did you mean to write 'admin'?

Le contrôle porte sur comment c'est écrit, pas sur ce que c'est.The check is about how it's written, not what it is.

La même valeur, exactement la même, est refusée écrite en littéral et acceptée passée par une variable. Déroutant — jusqu'à ce qu'on comprenne que la « fraîcheur » est un drapeau attaché au littéral lui-même, à l'endroit où on l'écrit. Dès qu'il transite par une variable, le drapeau tombe, et le structurel pur reprend la main ; et ce qu'un spread fait entrer dans le littéral n'est jamais contrôlé.The same value, exactly the same, is rejected as a literal and accepted through a variable. Baffling — until you grasp that 'freshness' is a flag attached to the literal itself, at the spot you write it. The moment it passes through a variable, the flag drops, and pure structural typing takes over; and whatever a spread brings into the literal is never checked.

createUser({ name: "Ada", isAdmin: true });
//                        ^^^^^^^ ✗ refusé
// le littéral est « frais » : écrit directement à l'endroit de l'appel

Un littéral d'objet écrit directement comme argument (ou en partie droite d'une affectation typée) est frais. Sur lui seul, TypeScript ajoute le contrôle des champs en trop. C'est le moment — et le seul — où une faute de frappe se fait attraper.An object literal written directly as an argument (or on the right of a typed assignment) is fresh. On it alone, TypeScript adds the excess property check. That's the moment — and the only one — where a typo gets caught.

Deux conditions, et le contrôle s'arme. Une seule manque, il dort.Two conditions, and the check arms. One missing, it sleeps.

Le contrôle des champs en trop se déclenche quand — et seulement quand — deux choses sont réunies : un littéral frais, et un type cible connu pour le confronter (le « type contextuel »). Annotation, argument, retour, élément de tableau, objet imbriqué : partout où ces deux conditions tiennent, il s'arme, récursivement.The excess property check fires when — and only when — two things meet: a fresh literal, and a known target type to compare it against (the 'contextual type'). Annotation, argument, return, array element, nested object: wherever both conditions hold, it arms, recursively.

type T = { id: number };

const a: T = { id: 1, x: 0 };           // ✗ annotation directe
function f(t: T) {} ; f({ id: 1, x: 0 });// ✗ argument
function g(): T { return { id: 1, x: 0 }; } // ✗ valeur de retour
const arr: T[] = [{ id: 1, x: 0 }];     // ✗ éléments de tableau littéral

const o = { id: 1, x: 0 }; const b: T = o; // ✓ passé par variable
type Bag = { id: number; [k: string]: unknown };
const c: Bag = { id: 1, x: 0 };         // ✓ la cible accepte l'inconnu

Faire taire l'alarme, ou déclarer que l'extra est prévu.To silence the alarm, or declare the extra is expected.

Le réflexe paresseux face à « Object literal may only specify known properties » : sortir l'objet dans une variable jusqu'à ce que ça compile. Ça marche — et ça désarme la seule protection contre les fautes de frappe, pour de bon. Quand les champs en plus sont vraiment attendus, il y a un geste honnête : le dire dans le type.The lazy reflex to 'Object literal may only specify known properties': pull the object into a variable until it compiles. It works — and it disarms the only protection against typos, for good. When the extra fields are genuinely expected, there's an honest move: say so in the type.

// On voulait juste « que ça compile »
const o = { name: "Ada", isAdmin: true };
createUser(o);
// ✓ compile — mais isAdmin survit, admin reste undefined.
// On a éteint l'alarme, pas le bug. Et partout où o passera,
// plus aucune faute de frappe ne sera attrapée.

La variable n'a rien corrigé : elle a juste retiré la fraîcheur, donc le contrôle. Le isAdmin mal tapé est toujours là, admin est toujours undefined, et l'utilisateur ne sera jamais admin. Faire compiler n'est pas faire marcher.The variable fixed nothing: it just stripped freshness, hence the check. The mistyped isAdmin is still there, admin is still undefined, and the user will never be admin. Making it compile isn't making it work.