Fonctionnalités méconnues de TypeScript qui valent le détour
Explorez sept fonctionnalités TypeScript méconnues, de const et NoInfer aux fonctions d’assertion et à verbatimModuleSyntax, avec leurs versions et des exemples de code.
Sept fonctionnalités de TypeScript restent sous-utilisées, même par de nombreux développeurs expérimentés : les paramètres de type const (5.0), NoInfer (5.4), les fonctions d’assertion (3.7), les éléments de tuple nommés (4.0), les annotations de variance (4.7), le mot-clé accessor (4.9) et import type combiné à verbatimModuleSyntax (3.8 et 5.0).
Si vous avez appris TypeScript à l’époque de la 4.x et que vous livrez du code sans relâche depuis, vous écrivez sans doute encore as const aux points d’appel et vous ajoutez des paramètres de type supplémentaires pour empêcher l’inférence d’élargir les types. Les versions récentes offrent des moyens plus concis d’obtenir ces deux résultats.
Cet article passe en revue chacune de ces fonctionnalités : ce qu’elle fait, la version qui l’a introduite et un court exemple qui compile en mode strict.
Points clés à retenir
- Un paramètre de type
const(TypeScript 5.0) infère["/", "/users"]commereadonly ["/", "/users"]lorsque la contrainte est en lecture seule, par exemplereadonly string[]. NoInfer<T>(TypeScript 5.4) empêche un paramètre de servir de site d’inférence, de sorte qu’une valeur par défaut ne peut pas élargir le type établi par les autres arguments.- Une fonction d’assertion déclarée avec
asserts value is Taffine le type de son argument pour tout le reste de la portée après l’appel, et pas seulement à l’intérieur d’un blocif. - Avec
verbatimModuleSyntax, un import n’est supprimé que sitypes’applique à l’instruction entière.import { type X } from "./mod"produitimport {} from "./mod", si bien que le module est tout de même exécuté.
Fonctionnalités avancées de TypeScript par version
Le tableau ci-dessous recense les sept fonctionnalités méconnues de TypeScript, avec la version qui les a introduites et les développeurs pour qui elles comptent le plus.
| Fonctionnalité | Introduite dans | Public principal |
|---|---|---|
| Fonctions d’assertion | 3.7 | Code applicatif et de bibliothèque |
import type | 3.8 | Configuration de build |
| Éléments de tuple nommés | 4.0 | Auteurs de hooks et d’API |
Annotations de variance (in/out) | 4.7 | Auteurs de bibliothèques |
Mot-clé accessor | 4.9 | Utilisateurs de décorateurs |
Paramètres de type const | 5.0 | Auteurs d’API génériques |
verbatimModuleSyntax | 5.0 | Configuration de build |
NoInfer<T> | 5.4 | Auteurs d’API génériques |
Paramètres de type const (TypeScript 5.0)
TypeScript 5.0 a ajouté le modificateur const sur les paramètres de type. Il amène le compilateur à inférer les littéraux de tableau et d’objet comme si l’appelant avait écrit as const. Les appelants n’ont plus besoin de penser à ajouter l’assertion pour obtenir des types littéraux.
Associez le modificateur const à une contrainte en lecture seule si vous voulez des résultats readonly. Avec une contrainte mutable comme string[], TypeScript 5.0 à 5.2 se rabattait sur string[]. Depuis la 5.3, le compilateur infère à la place un tuple mutable. Par ailleurs, le modificateur const ne s’applique qu’aux littéraux écrits directement dans l’appel. Une variable déclarée en amont conserve le type élargi qu’elle avait déjà.
function defineRoutes<T extends readonly string[]>(paths: T): T { return paths; }
const a = defineRoutes(["/", "/users"]); // string[]
function defineRoutesExact<const T extends readonly string[]>(paths: T): T { return paths; }
const b = defineRoutesExact(["/", "/users"]); // readonly ["/", "/users"]
function defineRoutesMutable<const T extends string[]>(paths: T): T { return paths; }
const c = defineRoutesMutable(["/", "/users"]); // ["/", "/users"] (TS 5.3+; string[] in 5.0–5.2)
NoInfer pour maîtriser l’inférence (TypeScript 5.4)
NoInfer<T>, ajouté dans TypeScript 5.4, empêche le compilateur d’utiliser un argument donné comme source d’inférence. Cet argument est alors vérifié par rapport au type inféré à partir des autres paramètres, au lieu de l’élargir. Avant la 5.4, le contournement habituel consistait à ajouter un second paramètre de type contraint par le premier. Cela fonctionnait, mais au prix d’un paramètre de type qui n’apparaissait qu’une seule fois dans la signature.
function createSelect<T extends string>(options: T[], initial: NoInfer<T>) {
return { options, value: initial };
}
createSelect(["draft", "published"], "draft"); // OK
createSelect(["draft", "published"], "archived");
// Error: Argument of type '"archived"' is not assignable
// to parameter of type '"draft" | "published"'.
Sans NoInfer, T serait élargi en "draft" | "published" | "archived" et la faute de frappe compilerait. La référence des types utilitaires le documente aux côtés de Partial et Pick.
Fonctions d’assertion (TypeScript 3.7)
Une fonction d’assertion affine le type de son argument pour tout le reste de la portée englobante dès lors qu’elle retourne sans lever d’exception. Elle se prête donc bien aux clauses de garde de type fail-fast, qui n’ont pas besoin de branche conditionnelle. Un type guard (value is T) n’affine le type qu’à l’intérieur de la condition qui l’appelle. Une signature asserts value is T, introduite dans TypeScript 3.7, affine le type pour tout ce qui suit l’appel.
function assertIsDefined<T>(value: T, name = "value"): asserts value is NonNullable<T> {
if (value === undefined || value === null) {
throw new Error(`${name} is not defined`);
}
}
const root = document.getElementById("app"); // HTMLElement | null
assertIsDefined(root, "#app");
root.classList.add("ready"); // root: HTMLElement
Les fonctions d’assertion comportent un piège. Si vous écrivez l’utilitaire sous forme de fonction fléchée affectée à une const non annotée, l’appel échoue avec l’erreur « Assertions require every name in the call target to be declared with an explicit type annotation. » Utilisez plutôt une déclaration de fonction, ou donnez un type explicite à la const.
Éléments de tuple nommés (TypeScript 4.0)
Les éléments de tuple nommés, ajoutés dans TypeScript 4.0, permettent de nommer chaque position d’un type tuple. Les noms apparaissent dans les infobulles de l’éditeur, l’aide à la signature et les messages d’erreur. Ces libellés ne modifient que ce qu’affichent les éditeurs et les messages d’erreur. Ils ne changent pas le type du tuple, et les appelants peuvent déstructurer les éléments sous les noms de leur choix. Depuis TypeScript 5.2, un tuple peut également mélanger éléments nommés et non nommés.
Le type de retour d’un hook en est le cas d’usage typique :
type ToggleState = [isOn: boolean, toggle: () => void];
function useToggle(initial = false): ToggleState {
let isOn = initial;
return [isOn, () => { isOn = !isOn; }];
}
const [open, toggleOpen] = useToggle(); // any names work; labels show in hovers
Annotations de variance : in et out (TypeScript 4.7)
Les annotations de variance, introduites dans TypeScript 4.7, permettent de déclarer explicitement si un paramètre de type est covariant (out), contravariant (in) ou les deux. Elles s’adressent surtout aux auteurs de bibliothèques ; le code applicatif n’en a presque jamais besoin. Les notes de version de la 4.7 les présentent comme un moyen de documenter l’intention et, pour les types profondément récursifs, d’accélérer la vérification de types. TypeScript signale une erreur lorsqu’une annotation contredit l’usage réel du paramètre, mais il accepte les annotations plus strictes que nécessaire.
interface Producer<out T> { get: () => T }
interface Consumer<in T> { accept: (value: T) => void }
interface Bad<in T> { get: () => T }
// Error: Type 'Bad<super-T>' is not assignable to type 'Bad<sub-T>'
// as implied by variance annotation.
Le mot-clé accessor (TypeScript 4.9)
TypeScript 4.9 a ajouté les auto-accesseurs. On les déclare comme un champ de classe, mais précédés du mot-clé accessor. Le compilateur les transforme en une paire getter/setter adossée à un champ privé inaccessible. Un auto-accesseur offre donc à un décorateur un point unique pour intercepter à la fois les lectures et les écritures du champ.
L’exemple ci-dessous utilise la signature standard des décorateurs introduite dans TypeScript 5.0, avec les types fournis par le fichier intégré au compilateur decorators.d.ts. Il nécessite que experimentalDecorators soit désactivé, car les décorateurs historiques utilisent une signature différente.
function logged<This, V>(
target: ClassAccessorDecoratorTarget<This, V>,
context: ClassAccessorDecoratorContext<This, V>
): ClassAccessorDecoratorResult<This, V> {
return {
set(value) {
console.log(`set ${String(context.name)} =`, value);
target.set.call(this, value);
},
};
}
class Settings {
@logged accessor theme = "light";
}
import type avec verbatimModuleSyntax (TypeScript 3.8 et 5.0)
Avec verbatimModuleSyntax, TypeScript ne supprime un import que si type s’applique à l’instruction entière. Tous les autres imports sont émis tels qu’ils ont été écrits. La syntaxe import type remonte à TypeScript 3.8. L’option elle-même est arrivée avec la 5.0 et a remplacé importsNotUsedAsValues et preserveValueImports, dépréciées en 5.0 et supprimées dans TypeScript 7.
{ "compilerOptions": { "verbatimModuleSyntax": true } }
import type { User } from "./api"; // erased entirely
import { fetchUser, type Post } from "./api"; // emits: import { fetchUser } from "./api";
import { type Config } from "./config"; // emits: import {} from "./config";
C’est la troisième ligne, import { type Config }, qui piège les développeurs. Un modificateur type en ligne laisse tout de même derrière lui un import vide : le module est donc chargé et ses effets de bord s’exécutent. Une fois l’option activée, tout type importé sans modificateur type provoque une erreur de compilation. La migration consiste essentiellement à convertir les imports nommés qui ne concernent que des types en import type.
Sujets TypeScript avancés connexes
Plusieurs sujets ont été volontairement laissés de côté, car ils font l’objet d’articles dédiés :
- A Practical Guide to TypeScript’s satisfies Operator
- Understanding infer in TypeScript
- How JavaScript Finally Learned to Clean Up After Itself (le mot-clé
using) - TypeScript Best Practices for Large Projects (aborde les branded types)
- 5 Tips To Improve Your TypeScript Code
Conclusion
La plupart de ces fonctionnalités remplacent un contournement ou transfèrent une vérification d’une convention à l’exécution vers le système de types. Les paramètres de type const et NoInfer offrent aux API génériques une inférence précise sans imposer d’effort supplémentaire aux appelants. Les fonctions d’assertion et les tuples nommés renforcent le code applicatif au quotidien, et verbatimModuleSyntax rend les imports émis prévisibles. Une première étape pragmatique consiste à activer verbatimModuleSyntax dans un package, à corriger les imports de types signalés par le compilateur, puis à ajouter const à tout générique dont la documentation demande actuellement aux appelants d’ajouter as const.
FAQ
verbatimModuleSyntax fonctionne-t-il dans les projets qui émettent du CommonJS ?
Oui, mais les fichiers émis en CommonJS doivent utiliser la syntaxe de style CommonJS propre à TypeScript : import fs = require('fs') pour les imports et export = pour les exports. Écrire des instructions import ou export ESM dans ces fichiers provoque une erreur de compilation. Les versions actuelles la signalent sous le code TS1295, en suggérant de modifier le champ type du package.json ou d'ajuster vos paramètres de module. Les fichiers émis en ESM conservent la syntaxe import et export habituelle.
Ai-je encore besoin d'isolatedModules si j'active verbatimModuleSyntax ?
Non. Selon la référence TSConfig, isolatedModules vaut true par défaut dès que verbatimModuleSyntax est activé : ses vérifications liées à la transpilation fichier par fichier s'appliquent donc automatiquement et vous pouvez supprimer l'entrée explicite. Ces vérifications sont importantes pour des outils comme esbuild, SWC et Babel, qui compilent chaque fichier séparément et ne peuvent pas déterminer si un nom importé est un type ou une valeur.
Une fonction d'assertion peut-elle être asynchrone ?
Non. TypeScript ne propose pas de signature d'assertion asynchrone : un type de retour comme Promise<asserts value is T> n'est pas valide. Cette fonctionnalité a été demandée dans l'issue TypeScript 37681, mais elle ne fait pas partie du langage. Le contournement habituel consiste à attendre d'abord le traitement asynchrone avec await, puis à appeler une fonction d'assertion synchrone sur le résultat, ou bien à faire retourner par la fonction asynchrone la valeur validée avec un type affiné.
Complete picture for complete understanding
Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.
Star on GitHub12k