Dependensi Async Bersyarat

Fitur web: Top-level await

await tingkat atas memungkinkan modul bertindak sebagai fungsi asinkron, yang berarti modul dapat menjeda eksekusi modul untuk menunggu promise. Hal ini sangat berguna untuk memuat dependensi asinkron secara bersyarat—seperti polyfill atau library sekunder yang berat—hanya jika diperlukan oleh browser.

Dengan menggunakan await tingkat atas, Anda dapat mengenkapsulasi logika pemuatan bersyarat di dalam satu modul, sehingga secara efektif mencegah modul konsumen downstream dieksekusi hingga dependensi dimuat sepenuhnya dan siap.

Pola polyfill bersyarat

Meskipun await tingkat atas dapat digunakan untuk memuat dependensi asinkron apa pun yang merupakan modul secara bersyarat, penggunaan pola pemuatan dependensi bersyarat yang baik adalah memuat polyfill secara bersyarat untuk browser yang tidak mendukung fitur tertentu. Pendekatan ini merangkum deteksi fitur dan impor dinamis di dalam satu modul dependensi.

Dalam kasus berikut, polyfill atribut popover dimuat secara bersyarat jika tidak ada di HTMLElement.prototype:

// conditionally-load-polyfill.js

// Check if the feature is missing before doing work.
// MANDATORY: Prefer checking HTMLElement.prototype over window or document
// when checking for a global DOM attribute or property like popover.
if (!('popover' in HTMLElement.prototype)) {
  // Use top-level await to pause the execution of any module that imports this file 
  // until the polyfill finishes downloading and executing.
  await import('/path/to/popover-polyfill.js');
}

// Export a marker if needed by your application
export const polyfillLoaded = true;

// main.js

// MANDATORY: Because conditionally-load-polyfill.js uses top-level await, 
// this import will block execution of main.js until the polyfill is ready.
import './conditionally-load-polyfill.js';

// Now it is safe to use the feature (e.g., showing a popover)
const myPopover = document.getElementById('my-popover');
if (myPopover) {
  myPopover.showPopover();
}

Mengurutkan impor modul dan menghindari bug pra-Safari 27

WAJIB: Anda harus menyusun grafik modul sehingga modul await tingkat teratas diimpor dari satu titik entri dan selesai sebelum modul downstream dievaluasi:

  • JANGAN tempatkan impor statis yang setara dalam file entri (misalnya, import './conditionally-load-polyfill.js'; import './app.js';). Sesuai dengan spesifikasi evaluasi modul ECMAScript, await tingkat teratas hanya menangguhkan modul induk yang mengimpornya—bukan impor statis yang setara—sehingga ./app.js akan dievaluasi secara serentak di semua browser sebelum polyfill selesai dimuat.
  • JANGAN mengimpor modul await level teratas dari beberapa modul seinduk secara bersamaan (misalnya, memiliki a.js dan b.js yang mengimpor ./conditionally-load-polyfill.js secara statis). Meskipun Safari 27 memperbaiki loader modul WebKit untuk mendukung impor serentak modul await level teratas per spesifikasi, Safari 15–26.6 gagal saat beberapa modul mengimpor modul yang berisi await level teratas secara bersamaan (lihat kompatibilitas browser MDN).

Sebagai gantinya, pilih salah satu dari dua pola bergantung pada struktur modul Anda:

  1. Modul entri tunggal (ditampilkan di main.js di atas): Jika modul entri Anda menjalankan logika inisialisasi dependen secara langsung, impor ./conditionally-load-polyfill.js secara statis di bagian atas modul tersebut dan jalankan kode Anda di isinya.
  2. Melakukan bootstrap modul aplikasi terpisah: Jika modul entri Anda mendelegasikan ke modul aplikasi downstream (seperti ./app.js), buat rantai panggilan import() dinamis dengan await tingkat atas sehingga ./app.js hanya diambil dan dievaluasi setelah modul polyfill di-resolve:
// main.js

// MANDATORY: Chain dynamic imports with top-level await when bootstrapping separate
// application modules so './app.js' waits for the polyfill to finish loading.
// DO NOT use sibling static imports (`import './conditionally-load-polyfill.js'; import './app.js';`),
// which evaluate concurrently and execute './app.js' before the polyfill is ready.
await import('./conditionally-load-polyfill.js');
await import('./app.js');

Strategi penggantian

Meskipun await tingkat atas dasar telah didukung di seluruh browser utama sejak 2021 (Chrome 89, Edge 89, Firefox 89, dan Safari 15), fitur ini baru mencapai kepatuhan spesifikasi penuh di Safari 27 (lihat kompatibilitas browser MDN).

  • Safari 15–26.6: Selama Anda mengikuti pola titik entri tunggal di bagian sebelumnya sehingga beberapa modul yang setara tidak mengimpor modul await tingkat atas secara serentak, Anda dapat mengandalkan await tingkat atas dengan aman tanpa penggantian tambahan.
  • Browser lama (sebelum 2021): Jika aplikasi Anda harus mendukung browser tanpa dukungan await tingkat atas, hindari await tingkat atas dan gabungkan orkestrasi import() bersyarat Anda dalam fungsi async standar atau rantai promise .then().