Top-level Await JavaScript : Révolutionner le chargement de modules et l'initialisation asynchrone

Pendant des années, les développeurs JavaScript ont dû naviguer dans les complexités de l'asynchronisme. Bien que la syntaxe async/await ait apporté une clarté remarquable à l'écriture de la logique asynchrone au sein des fonctions, une limitation importante persistait : le niveau supérieur d'un module ES était strictement synchrone. Cela obligeait les développeurs à utiliser des motifs maladroits comme les Expressions de Fonction Asynchrone Immédiatement Invoquées (IIAFE) ou à exporter des promesses simplement pour effectuer une tâche asynchrone simple lors de la configuration du module. Le résultat était souvent un code passe-partout difficile à lire et encore plus difficile à raisonner.

C'est là qu'intervient le Top-level Await (TLA), une fonctionnalité finalisée dans ECMAScript 2022 qui change fondamentalement la façon dont nous pensons et structurons nos modules. Il vous permet d'utiliser le mot-clé await au niveau supérieur de vos modules ES, transformant de fait la phase d'initialisation de votre module en une fonction async. Ce changement en apparence mineur a des implications profondes pour le chargement des modules, la gestion des dépendances et l'écriture d'un code asynchrone plus propre et plus intuitif.

Dans ce guide complet, nous allons plonger en profondeur dans le monde du Top-level Await. Nous explorerons les problèmes qu'il résout, son fonctionnement interne, ses cas d'utilisation les plus puissants et les meilleures pratiques à suivre pour l'exploiter efficacement sans compromettre les performances.

Le défi : l'asynchronisme au niveau du module

Pour apprécier pleinement le Top-level Await, nous devons d'abord comprendre le problème qu'il résout. L'objectif principal d'un module ES est de déclarer ses dépendances (import) et d'exposer son API publique (export). Le code au niveau supérieur d'un module n'est exécuté qu'une seule fois, lors de la première importation du module. La contrainte était que cette exécution devait être synchrone.

Mais que se passe-t-il si votre module doit récupérer des données de configuration, se connecter à une base de données ou initialiser un module WebAssembly avant de pouvoir exporter ses valeurs ? Avant le TLA, il fallait recourir à des solutions de contournement.

La solution de contournement IIAFE (Immediately Invoked Async Function Expression)

Un motif courant consistait à envelopper la logique asynchrone dans une IIAFE async. Cela permettait d'utiliser await, mais créait un nouvel ensemble de problèmes. Considérez cet exemple où un module doit récupérer des paramètres de configuration :

config.js (L'ancienne méthode avec IIAFE)

            
export const settings = {};

(async () => {
  try {
    const response = await fetch('https://api.example.com/config');
    const configData = await response.json();
    Object.assign(settings, configData);
  } catch (error) {
    console.error("Failed to load configuration:", error);
    // Assign default settings on failure
    Object.assign(settings, { default: true });
  }
})();

            

              
                Copy
              
            
          

Le problème principal ici est une condition de concurrence (race condition). Le module config.js s'exécute et exporte immédiatement un objet settings vide. Les autres modules qui importent config obtiennent cet objet vide tout de suite, tandis que l'opération fetch se déroule en arrière-plan. Ces modules n'ont aucun moyen de savoir quand l'objet settings sera réellement peuplé, ce qui conduit à une gestion d'état complexe, à des émetteurs d'événements ou à des mécanismes de polling pour attendre les données.

Le motif "Exporter une promesse"

Une autre approche consistait à exporter une promesse qui se résout avec les exportations prévues du module. C'est plus robuste car cela force le consommateur à gérer l'asynchronisme, mais cela déplace la charge.

config.js (Export d'une promesse)

            
const setupPromise = (async () => {
  const response = await fetch('https://api.example.com/config');
  return response.json();
})();

export { setupPromise };

            

              
                Copy
              
            
          

main.js (Consommation de la promesse)

            
import { setupPromise } from './config.js';

setupPromise.then(config => {
  console.log('API Key:', config.apiKey);
  // ... start the application
});

            

              
                Copy
              
            
          

Chaque module qui a besoin de la configuration doit maintenant importer la promesse et utiliser .then() ou await dessus avant de pouvoir accéder aux données réelles. C'est verbeux, répétitif et facile à oublier, ce qui entraîne des erreurs d'exécution.

L'arrivée du Top-level Await : un changement de paradigme

Le Top-level Await résout élégamment ces problèmes en permettant l'utilisation de await directement dans la portée du module. Voici à quoi ressemble l'exemple précédent avec le TLA :

config.js (La nouvelle méthode avec TLA)

            
const response = await fetch('https://api.example.com/config');
const config = await response.json();

export default config;

            

              
                Copy
              
            
          

main.js (Propre et simple)

            
import config from './config.js';

// Ce code ne s'exécute qu'une fois config.js entièrement chargé.
console.log('API Key:', config.apiKey);

            

              
                Copy
              
            
          

Ce code est propre, intuitif et fait exactement ce à quoi on s'attend. Le mot-clé await met en pause l'exécution du module config.js jusqu'à ce que les promesses fetch et .json() se résolvent. Fait crucial, tout autre module qui importe config.js mettra également son exécution en pause jusqu'à ce que config.js soit entièrement initialisé. Le graphe de modules "attend" de fait que la dépendance asynchrone soit prête.

Important : Cette fonctionnalité n'est disponible que dans les Modules ES. Dans le contexte d'un navigateur, cela signifie que votre balise de script doit inclure type="module". Dans Node.js, vous devez soit utiliser l'extension de fichier .mjs, soit définir "type": "module" dans votre package.json.

Comment le Top-level Await transforme le chargement de modules

Le TLA ne se contente pas d'offrir du sucre syntaxique ; il s'intègre fondamentalement à la spécification de chargement des modules ES. Lorsqu'un moteur JavaScript rencontre un module avec TLA, il modifie son flux d'exécution.

Voici une description simplifiée du processus :

• Analyse et construction du graphe : Le moteur analyse d'abord tous les modules, en partant du point d'entrée, pour identifier les dépendances via les instructions import. Il construit un graphe de dépendances sans exécuter aucun code.
• Exécution : Le moteur commence à exécuter les modules en suivant un parcours post-ordre (les dépendances sont exécutées avant les modules qui en dépendent).
• Mise en pause sur Await : Lorsque le moteur exécute un module contenant un await de haut niveau, il met en pause l'exécution de ce module et de tous ses modules parents dans le graphe.
• Boucle d'événements non bloquée : Cette pause est non bloquante. Le moteur est libre de continuer à exécuter d'autres tâches dans la boucle d'événements, comme répondre aux entrées de l'utilisateur ou gérer d'autres requêtes réseau. C'est le chargement du module qui est bloqué, pas l'application entière.
• Reprise de l'exécution : Une fois que la promesse attendue est réglée (résolue ou rejetée), le moteur reprend l'exécution du module et, par la suite, des modules parents qui l'attendaient.

Cette orchestration garantit qu'au moment où le code d'un module s'exécute, toutes ses dépendances importées—même les asynchrones—ont été entièrement initialisées et sont prêtes à être utilisées.

Cas d'utilisation pratiques et exemples concrets

Le Top-level Await ouvre la voie à des solutions plus propres pour une variété de scénarios de développement courants.

1. Chargement dynamique de modules et dépendances de secours

Parfois, vous devez charger un module depuis une source externe, comme un CDN, mais vous voulez une solution de secours locale en cas d'échec du réseau. Le TLA rend cela trivial.

            
// utils/date-library.js
let moment;

try {
  // Tente d'importer depuis un CDN
  moment = await import('https://cdn.skypack.dev/moment');
} catch (error) {
  console.warn('Échec du CDN, chargement de la version locale de secours pour moment.js');
  // En cas d'échec, charge une copie locale
  moment = await import('./vendor/moment.js');
}

export default moment.default;

            

              
                Copy
              
            
          

Ici, nous tentons de charger une bibliothèque depuis un CDN. Si la promesse de l'import() dynamique est rejetée (en raison d'une erreur réseau, d'un problème CORS, etc.), le bloc catch charge gracieusement une version locale à la place. Le module exporté n'est disponible qu'après qu'une de ces voies se soit terminée avec succès.

2. Initialisation asynchrone des ressources

C'est l'un des cas d'utilisation les plus courants et les plus puissants. Un module peut désormais encapsuler entièrement sa propre configuration asynchrone, masquant la complexité à ses consommateurs. Imaginez un module responsable d'une connexion à la base de données :

            
// services/database.js
import { createPool } from 'mysql2/promise';

const connectionPool = await createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  database: 'my_app_db',
  waitForConnections: true,
  connectionLimit: 10,
});

// Le reste de l'application peut utiliser cette fonction
// sans se soucier de l'état de la connexion.
export async function query(sql, params) {
  const [results] = await connectionPool.execute(sql, params);
  return results;
}

            

              
                Copy
              
            
          

N'importe quel autre module peut maintenant simplement faire import { query } from './database.js' et utiliser la fonction, confiant que la connexion à la base de données a déjà été établie.

3. Chargement conditionnel de modules et internationalisation (i18n)

Vous pouvez utiliser le TLA pour charger des modules de manière conditionnelle en fonction de l'environnement ou des préférences de l'utilisateur, qui pourraient devoir être récupérés de manière asynchrone. Un excellent exemple est le chargement du fichier de langue correct pour l'internationalisation.

            
// i18n/translator.js
async function getUserLanguage() {
  // Dans une vraie application, cela pourrait être un appel API ou provenir du stockage local
  return new Promise(resolve => resolve('es')); // Exemple : Espagnol
}

const lang = await getUserLanguage();
const translations = await import(`./locales/${lang}.json`);

export function t(key) {
  return translations[key] || key;
}

            

              
                Copy
              
            
          

Ce module récupère les paramètres de l'utilisateur, détermine la langue préférée, puis importe dynamiquement le fichier de traduction correspondant. La fonction t exportée est garantie d'être prête avec la bonne langue dès son importation.

Bonnes pratiques et pièges potentiels

Bien que puissant, le Top-level Await doit être utilisé judicieusement. Voici quelques lignes directrices à suivre.

À faire : l'utiliser pour une initialisation essentielle et bloquante

Le TLA est parfait pour les ressources critiques sans lesquelles votre application ou module ne peut pas fonctionner, comme la configuration, les connexions à la base de données ou les polyfills essentiels. Si le reste du code de votre module dépend du résultat d'une opération asynchrone, le TLA est le bon outil.

À ne pas faire : en abuser pour des tâches non critiques

Utiliser le TLA pour chaque tâche asynchrone peut créer des goulots d'étranglement de performance. Parce qu'il bloque l'exécution des modules dépendants, il peut augmenter le temps de démarrage de votre application. Pour du contenu non critique comme le chargement d'un widget de réseau social ou la récupération de données secondaires, il est préférable d'exporter une fonction qui renvoie une promesse, permettant à l'application principale de se charger en premier et de gérer ces tâches de manière différée (lazily).

À faire : gérer les erreurs avec élégance

Une promesse rejetée non gérée dans un module avec TLA empêchera ce module de se charger correctement. L'erreur se propagera à l'instruction import, qui sera également rejetée. Cela peut interrompre le démarrage de votre application. Utilisez des blocs try...catch pour les opérations qui pourraient échouer (comme les requêtes réseau) afin d'implémenter des solutions de secours ou des états par défaut.

Soyez attentif aux performances et à la parallélisation

Si votre module doit effectuer plusieurs opérations asynchrones indépendantes, ne les attendez pas séquentiellement. Cela crée une cascade inutile. Utilisez plutôt Promise.all() pour les exécuter en parallèle et attendez le résultat.

            
// services/initial-data.js

// MAUVAIS : requêtes séquentielles
// const user = await fetch('/api/user').then(res => res.json());
// const permissions = await fetch('/api/permissions').then(res => res.json());

// BON : requêtes parallèles
const [user, permissions] = await Promise.all([
  fetch('/api/user').then(res => res.json()),
  fetch('/api/permissions').then(res => res.json()),
]);

export { user, permissions };

            

              
                Copy
              
            
          

Cette approche garantit que vous n'attendez que la plus longue des deux requêtes, et non la somme des deux, améliorant considérablement la vitesse d'initialisation.

Évitez le TLA dans les dépendances circulaires

Les dépendances circulaires (où le module `A` importe `B`, et `B` importe `A`) sont déjà un code qui sent mauvais (code smell), mais elles peuvent provoquer un interblocage (deadlock) avec le TLA. Si `A` et `B` utilisent tous deux le TLA, le système de chargement de modules peut se bloquer, chacun attendant que l'autre termine son opération asynchrone. La meilleure solution est de remanier votre code pour supprimer la dépendance circulaire.

Support des environnements et des outils

Le Top-level Await est maintenant largement pris en charge dans l'écosystème JavaScript moderne.

• Node.js : Entièrement pris en charge depuis la version 14.8.0. Vous devez être en mode module ES (utilisez des fichiers .mjs ou ajoutez "type": "module" à votre package.json).
• Navigateurs : Pris en charge dans tous les principaux navigateurs modernes : Chrome (depuis la v89), Firefox (depuis la v89) et Safari (depuis la v15). Vous devez utiliser <script type="module">.
• Bundlers : Les bundlers modernes comme Vite, Webpack 5+ et Rollup ont un excellent support pour le TLA. Ils peuvent correctement empaqueter les modules qui utilisent cette fonctionnalité, garantissant qu'elle fonctionne même en ciblant des environnements plus anciens.

Conclusion : un avenir plus propre pour le JavaScript asynchrone

Le Top-level Await est plus qu'une simple commodité ; c'est une amélioration fondamentale du système de modules JavaScript. Il comble une lacune de longue date dans les capacités asynchrones du langage, permettant une initialisation de module plus propre, plus lisible et plus robuste.

En permettant aux modules d'être véritablement autonomes, de gérer leur propre configuration asynchrone sans fuir les détails d'implémentation ou forcer les consommateurs à utiliser du code passe-partout, le TLA favorise une meilleure architecture et un code plus maintenable. Il simplifie tout, de la récupération des configurations et de la connexion aux bases de données au chargement dynamique de code et à l'internationalisation. Lors de la création de votre prochaine application JavaScript moderne, demandez-vous où le Top-level Await peut vous aider à écrire un code plus élégant et efficace.