El top-level await es una característica de ECMAScript 6 que te permite usar await directamente en un módulo, sin envolverlo en una función async. Si trabajas con APIs en JavaScript, esta función simplifica el flujo de tus peticiones y hace tu código más legible.

Para practicarlo, vamos a usar la Fake API de Platzi, un recurso que simula una e-commerce real con productos, usuarios, autenticación y upload de archivos. La encuentras en fakeapi.platzi.com y es ideal para ejercicios y retos.

Qué es top-level await y por qué importa

El top-level await te permite usar await fuera de una función async, directamente en el nivel superior de un módulo. Esto cambia la forma en que estructuras peticiones asíncronas y módulos en JavaScript [01:55].

¿Qué es top-level await? Es la capacidad de usar la palabra reservada await en el nivel principal de un módulo de JavaScript, sin necesidad de envolver el código en una función async. Funciona solo dentro de módulos ES.

Antes de esta característica, tenías que crear una función async específica, ejecutar la lógica adentro, retornar el resultado y exportar esa función para llamarla donde la necesitaras. Ahora puedes saltarte ese paso.

Cómo configurar el proyecto con node-fetch

Para hacer peticiones desde Node.js, necesitas una utilidad que te permita usar fetch. Aunque versiones recientes de Node ya lo incorporan de forma nativa, para garantizar compatibilidad usaremos la librería node-fetch [02:49].

Desde tu terminal, instala la dependencia:

bash npm install node-fetch

Esto agrega el recurso al proyecto y habilita peticiones HTTP desde el lado del servidor. Si los conceptos de npm, imports y módulos todavía te generan dudas, conviene reforzar con el curso de npm para sacarle provecho a tus proyectos.

Cómo creo el módulo de productos

Crea un archivo llamado products.js. Este será el módulo encargado de consumir la API y exponer los datos. Dentro de él, importa fetch y arma la petición:

javascript import fetch from 'node-fetch';

const response = await fetch('https://api.escuelajs.co/api/v1/products'); const products = await response.json();

export { products };

Fíjate en el detalle: usamos await dos veces sin envolver nada en una función async. Primero esperamos la respuesta de la API, luego la transformamos en un objeto JSON con el método .json() [04:32].

Cómo se compara con el enfoque tradicional con async

Antes del top-level await, tendrías que escribir algo así:

• Crear una función async llamada getProducts.
• Ejecutar la petición y la transformación adentro.
• Retornar los productos al final.
• Exportar la función para invocarla en otro archivo.

Con top-level await eliminas toda esa envoltura. El módulo se vuelve más directo y el flujo de datos más claro [05:18].

¿Cuándo debo usar top-level await? Úsalo cuando trabajes con módulos ES y necesites resolver promesas antes de exportar valores, como peticiones a APIs o lectura de archivos durante la inicialización del módulo.

Cómo importo y uso el módulo

Crea otro archivo, por ejemplo 01_topLevelAwait.js, e importa los productos:

javascript import { products } from './products.js';

console.log(products); console.log('hey');

Al ejecutarlo con Code Runner, verás primero el objeto enorme con los productos y después el hey. Eso confirma que el await está bloqueando la ejecución hasta que la API responde, sin necesidad de async explícito [06:30].

Qué pasa si quito await de la ecuación

Si eliminas los await del módulo products.js, el código intenta procesar la respuesta antes de que el servidor la devuelva. El resultado: la información no llega a tiempo y el console.log muestra una promesa pendiente o un error.

Por eso await es la pieza clave. Espera la respuesta del servidor, transforma los datos en un objeto utilizable y los expone listos para consumir [07:12]. Sin él, el flujo asíncrono se rompe.

Esta característica encaja perfecto cuando inicializas configuraciones, cargas datos remotos antes de exponer un módulo o trabajas con recursos que dependen de promesas. ¿Ya tienes en mente un proyecto donde aplicarla? Cuéntame en los comentarios cómo piensas usarla.