Enum TypeScript : numérique, string, const et alternatives | We.Inc
Générez des enums numériques, string et const à partir de vos propres noms de membres, voyez le JavaScript exact que chacun émet, et comparez-les aux objets as const et aux unions de littéraux.
Un enum donne un type unique à un ensemble de constantes nommées. Les enums numériques comptent à partir de 0 et associent aussi les nombres aux noms ; les enums string exigent un littéral par membre et n'ont pas de reverse mapping ; les const enums sont insérés en ligne et disparaissent. Contrairement à la plupart du TypeScript, les enums classiques émettent du vrai JavaScript, c'est pourquoi beaucoup d'équipes préfèrent les objets as const.
Cinq façons de modéliser un ensemble fixe de valeurs
Style
Émet du JavaScript ?
Reverse mapping
Accepte un littéral brut ?
Enum numérique
Oui, un objet
Oui, du nombre vers le nom
Les nombres qui correspondent à un membre
Enum string
Oui, un objet
Non
Non, il faut utiliser Enum.Member
const enum
Non, valeurs insérées en ligne
Non
Selon son type d'enum
Objet as const
Oui, un objet simple
Non (écrivez-en un si besoin)
Oui
Union de littéraux
Non, effacée
Non
Oui
Saisissez des noms de membres dans le générateur et passez d'un style à l'autre. Il écrit la déclaration TypeScript et le JavaScript que le compilateur produirait, pour que vous voyiez le coût de chaque choix avant qu'il n'arrive dans votre bundle.
Saisissez des noms de membres séparés par des virgules, par exemple Draft, Review, Live.
Pour les enums numériques, définissez le nombre de départ ; les membres suivants comptent à partir de celui-ci.
Choisissez un style pour voir sa déclaration, le JavaScript émis et la façon de l'utiliser.
Copiez la version qui convient à votre projet.
Choisissez des enums string ou des objets as const pour les valeurs qui sortent de votre programme, comme les champs d'API ou les colonnes de base de données. Une ligne de log qui dit live est plus lisible que 2.
Ne réordonnez jamais et n'insérez jamais de membres au milieu d'un enum numérique stocké quelque part. Tous les nombres suivants se décalent et les anciennes données enregistrées signifient désormais autre chose.
Évitez const enum dans les bibliothèques publiées. Les consommateurs compilés avec isolatedModules ou un outil de suppression des types ne peuvent pas insérer en ligne des valeurs provenant d'un autre fichier.
Activez erasableSyntaxOnly si vous exécutez des fichiers .ts avec le type stripping de Node ; l'option signale les enums avant qu'ils n'échouent à l'exécution.
Questions fréquentes
Qu'est-ce qu'un reverse mapping ?
Pour les enums numériques, tsc stocke les deux sens sur l'objet : Direction.Up vaut 0 et Direction[0] vaut la chaîne Up. Les membres string n'ont pas d'entrée inverse, car la valeur pourrait entrer en conflit avec le nom d'un autre membre.
Pourquoi ne puis-je pas passer une simple chaîne à une fonction qui attend un enum string ?
Les membres d'un enum string sont des types distincts. Le compilateur signale que le littéral n'est pas assignable à l'enum, les appelants doivent donc écrire Status.Draft. Si vous voulez que les appelants passent le littéral, utilisez plutôt une union de littéraux string.
Comment parcourir les valeurs d'un enum ?
Pour un enum string, Object.values(MyEnum) renvoie les valeurs. Pour un enum numérique, l'objet contient aussi les clés inverses, il faut donc filtrer : Object.values(MyEnum).filter((v) => typeof v === 'number').
Les enums sont-ils dépréciés ?
Non. Ils font toujours partie de TypeScript. L'option plus récente erasableSyntaxOnly, ajoutée dans TypeScript 5.8, permet simplement aux projets qui reposent sur le type stripping de les interdire, car un enum ne peut pas être retiré en supprimant les annotations.
Node.js exécute-t-il directement les fichiers contenant des enums ?
Pas avec le type stripping par défaut. La documentation de Node range les déclarations d'enum parmi les fonctionnalités qui nécessitent une génération de code et ne sont pas prises en charge dans ce mode : compilez-les donc avec tsc ou un autre transformateur, ou passez à un objet as const.
Enums numériques : compacts mais fragiles
Sans initialiseur, les membres sont numérotés 0, 1, 2 dans l'ordre. Donnez une valeur au premier, comme Low = 1, et les suivants continuent à partir de là. L'objet émis contient à la fois nom vers nombre et nombre vers nom.
Cette compacité est aussi le risque. Les nombres ne signifient rien en dehors de votre code, et ajouter un membre au milieu renumérote silencieusement tout ce qui suit.
Enums string : lisibles et stricts
Chaque membre a besoin d'un littéral string, ce qui rend les valeurs explicites dans les logs, les URL et le JSON. La rigueur a deux faces : une valeur lue depuis une API est une chaîne, pas l'enum, il faut donc toujours une vérification avant de la traiter comme tel.
Le motif as const
Un objet littéral marqué as const conserve ses valeurs string exactes comme types. Associez-le à type Role = (typeof Role)[keyof typeof Role] et vous obtenez un objet à l'exécution pour l'itération, plus un type union qui accepte à la fois Role.Admin et le littéral admin.
C'est du JavaScript simple avec des annotations : tous les outils de type stripping le gèrent, et rien d'autre n'est généré en dehors de l'objet que vous avez écrit.
Les trois types d'enum et ce qu'ils émettent
Enum numérique avec une valeur de départ
Mid et High continuent de compter à partir de Low. L'objet produit fait la correspondance dans les deux sens.
Enum string
Chaque membre est assigné une seule fois, sans entrée inverse.
const enum
La déclaration disparaît et chaque utilisation devient sa valeur.
Alternatives effaçables
Objet as const plus une union dérivée
Fonctionne avec le type stripping, s'itère avec Object.values et accepte la chaîne brute.
Union simple quand aucune liste à l'exécution n'est nécessaire
Entièrement effacée ; le compilateur rejette quand même toute autre chaîne.
Interdire les enums dans un projet en type stripping
Avec cette option, une déclaration d'enum est une erreur de compilation.
Enum numérique
Enum string
const enum
Objet as const
Type union
Générateur d'enum
Nom du type
Membres (séparés par des virgules)
Premier nombre
Style d'enum
TypeScript
JavaScript émis
Copier le TypeScript
Copier le JavaScript
Utilisez des noms qui commencent par une lettre, $ ou _, et ne contiennent que des lettres, chiffres, $ ou _, sans nom en double.