Promise<T> & async/await, ou la moitié de l'histoire Promise<T> & async/await, or half the story

Promise<T> décrit la valeur de succès — et seulement elle.Promise<T> describes the success value — and only it.

async/await a l'air d'être la partie de TypeScript qui rend enfin l'asynchrone sûr et lisible comme du code synchrone. Pour le chemin du succès, c'est vrai : Promise<User> nomme exactement ce qu'on obtiendra si ça résout. Mais le type ne raconte que la moitié de l'histoire. Le T est la valeur résolue, rien d'autre — la branche du rejet est totalement absente du type. Lire Promise<User> comme « ça me donne un User » oublie le « ou ça lève quelque chose, qu'aucun type ne décrit ».async/await looks like the part of TypeScript that finally makes asynchrony safe and readable like synchronous code. For the success path, it's true: Promise<User> names exactly what you'll get if it resolves. But the type tells only half the story. The T is the resolved value, nothing else — the rejection branch is entirely absent from the type. Reading Promise<User> as 'it gives me a User' forgets the 'or it throws something, which no type describes'.

async function getUser(id: string): Promise<User> {
  const res = await fetch("/u/" + id);
  return res.json();          // le type dit Promise<User> : succès garanti, croit-on
}

const user = await getUser("42");   // user : User — MAIS si ça rejette, on saute ICI
user.name;                          // jamais atteint en cas d'erreur — et l'erreur n'est pas typée

async function getUser(id: string): Promise<User> { /* ... */ }
//                                   ^^^^^^^^^^^^^ décrit la valeur de SUCCÈS, uniquement

const user = await getUser("42");   // user : User — SI la promesse résout
// le rejet ? invisible dans le type. await le relance, et c'est un 'unknown' au catch (8.2)

async enveloppe toujours ; une Promise ne s'emboîte jamais dans une Promise.async always wraps; a Promise never nests inside a Promise.

Deux faits qui surprennent. Un : une fonction async qui rend 5 n'a pas le type number mais Promise<number> — on ne peut pas s'y soustraire, async enveloppe systématiquement le retour, et transforme un throw en rejet. Deux : rendre une Promise depuis une async ne donne pas Promise<Promise<T>> — les promesses s'aplatissent, toujours. await déballe exactement une couche, et Awaited<T> est l'aplatissement au niveau type. On ne jongle jamais avec des promesses imbriquées.Two facts that surprise. One: an async function returning 5 doesn't have type number but Promise<number> — you can't opt out, async systematically wraps the return, and turns a throw into a reject. Two: returning a Promise from an async doesn't give Promise<Promise<T>> — promises always flatten. await unwraps exactly one layer, and Awaited<T> is the type-level flatten. You never juggle nested promises.

async function f() { return 5; }     // f : () => Promise<number>, JAMAIS number
async function g() { return f(); }   // g : () => Promise<number>, PAS Promise<Promise<number>>
//   async enveloppe toujours le retour ; et les Promise ne s'imbriquent pas — elles s'aplatissent

Marquer une fonction async, c'est promettre un Promise<…> en sortie — impossible de rendre la valeur nue. Et comme g rend ce que rend f (déjà une promesse), TypeScript aplatit : pas de double emballage. La règle est mécanique, pas optionnelle.Marking a function async is promising a Promise<…> as output — you can't return the bare value. And since g returns what f returns (already a promise), TypeScript flattens: no double wrapping. The rule is mechanical, not optional.

Trois états, un seul typé. await déballe le succès, relance le reste.Three states, one typed. await unwraps success, rethrows the rest.

Une promesse représente un résultat futur, et passe par trois états : pending, puis fulfilled (avec une valeur de type T) ou rejected (avec une raison sans type). Le T de Promise<T> ne nomme que la branche fulfilled. await suspend l'exécution et rend la valeur si la promesse résout, ou relance la raison si elle rejette. async est du sucre : il enveloppe le retour dans une promesse et transforme tout throw en rejet. La preuve que l'erreur n'est pas typée est dans la signature même de .then.A promise represents a future result, passing through three states: pending, then fulfilled (with a value of type T) or rejected (with an untyped reason). The T in Promise<T> names only the fulfilled branch. await suspends execution and yields the value if the promise resolves, or rethrows the reason if it rejects. async is sugar: it wraps the return in a promise and turns any throw into a reject. The proof that the error isn't typed is in .then's very signature.

// Une promesse a trois états — le type n'en nomme qu'un :
//
//   pending  ──┬──▶ fulfilled(value: T)   ← T, le seul type décrit
//              └──▶ rejected(reason: ???)  ← aucun type : le trou du Vol 8.2
//
// await : suspend, rend T si fulfilled, RELANCE reason si rejected.
// async : enveloppe le retour en Promise, et transforme 'throw' en rejected.

promise.then(
  (value: T) => { /* succès : value est typé T */ },
  (reason: any) => { /* rejet : reason est 'any' — la preuve que l'erreur n'est pas typée */ }
);

La promesse flottante : un objet truthy qu'on prend pour sa valeur.The floating promise: a truthy object mistaken for its value.

Le piège quotidien de l'async : oublier await. Une promesse est un objet — donc truthy —, et tester if (!isReady()) au lieu de if (!(await isReady())) ne passe jamais, quelle que soit la valeur résolue — sans que tsc proteste. Pire, une promesse appelée sans await ni gestion « flotte » : si elle rejette, le rejet n'est capté nulle part et peut faire tomber le process. Le type Promise<boolean> ne force pas à déballer : c'est une valeur qu'on peut, par mégarde, utiliser à la place de son contenu.The everyday async trap: forgetting await. A promise is an object — hence truthy — and testing if (!isReady()) instead of if (!(await isReady())) never passes, whatever the resolved value — and tsc doesn't object. Worse, a promise called without await or handling 'floats': if it rejects, the rejection is caught nowhere and can take the process down. The type Promise<boolean> doesn't force you to unwrap: it's a value you can, by mistake, use in place of its content.

async function isReady(): Promise<boolean> { /* ... */ }

if (!isReady()) return;     // ✗ JAMAIS vrai : une Promise est truthy, !promise vaut false
//   ^ 'await' oublié — et tsc se tait (il n'attrape que if (isReady()), TS2801)

saveUser(data);   // ✗ flottante : si elle rejette, rejet non géré (peut crasher le process)

Sans await, isReady() est un objet Promise — toujours truthy : sa négation vaut toujours false, la garde ne teste rien. Et saveUser(data) flottante laisse son rejet sans filet. Le type ne t'oblige pas à déballer — il accepte qu'on traite la promesse comme une valeur ordinaire, et c'est là que ça casse.Without await, isReady() is a Promise object — always truthy: its negation is always false, the guard tests nothing. And the floating saveUser(data) leaves its rejection netless. The type doesn't force you to unwrap — it lets you treat the promise as an ordinary value, and that's where it breaks.