La lección anterior terminó con un diagnóstico preciso: los callbacks funcionan, pero no devuelven nada. Como el resultado futuro no es un valor, no se puede guardar en una variable, ni pasar a una función, ni combinar, ni encadenar sin anidar, y los errores dejan de propagarse solos en cuanto se cruza la frontera asíncrona. La solución del lenguaje fue hacer que ese resultado futuro sí sea un valor: un objeto llamado promesa que representa «algo que todavía no está, pero estará». En esta lección aprenderás a crearlas, consumirlas y encadenarlas; verás cómo la pirámide del 05-05 se aplana en una lista de pasos; conocerás los cuatro combinadores que resuelven en una línea lo que antes exigía contadores manuales; y llegarás a async/await, la sintaxis que hace que el código asíncrono se lea exactamente igual que el síncrono, con su try/catch funcionando por fin.

1. Qué es una promesa: los tres estados
2. Crear una promesa con new Promise
3. Prometificar leerBacklogSimulado
4. Consumir: .then, .catch, .finally
5. Encadenar: cómo se aplana la pirámide
6. Cómo se propagan los errores por la cadena
7. Promise.resolve y Promise.reject
8. Los cuatro combinadores
9. async y await
10. try/catch que por fin funciona
11. await en bucles frente a Promise.all
12. for await...of y await a nivel de módulo
13. Las trampas de async/await
14. Ejemplo integrador: cargarTablero()
15. La tabla comparativa de los tres estilos
16. Errores Comunes y Consejos
17. Ejercicios
18. Conclusión

Una promesa (Promise) es un objeto que representa el resultado de una operación asíncrona. Existe desde el instante en que la operación comienza, mucho antes de que haya resultado, y por eso se puede guardar, pasar y combinar como cualquier otro valor.

En cada momento está en uno de tres estados:

Dos propiedades que definen todo su comportamiento:

• La transición es única e irreversible. Una promesa pasa de pendiente a cumplida o a rechazada, una sola vez, y ahí se queda. Una vez decidida, se dice que está saldada (settled). Esto elimina de un plumazo el problema de la doble llamada del 05-05: por mucho que el código llame a resolve cinco veces, solo cuenta la primera.
• El resultado se conserva. Si te suscribes a una promesa que ya está cumplida, recibes el valor igualmente. No hay que «llegar a tiempo», al contrario que con un evento.

Una diferencia de vocabulario que evita confusiones: una promesa rechazada es un resultado normal y previsto (el servidor devolvió un 503), mientras que un error no manejado es un fallo del programa. Las dos cosas usan objetos Error, pero conceptualmente son distintas.

El constructor recibe una función —llamada ejecutor— con dos parámetros: resolve y reject.

Puntos clave del ejecutor:

• Se ejecuta de inmediato, en el momento de crear la promesa. Lo asíncrono es cuándo se llama a resolve/reject, no cuándo empieza el trabajo.
• resolve y reject son funciones normales; sus nombres son convención, no obligación.
• Solo cuenta la primera llamada. Las siguientes se ignoran en silencio.
• reject debe recibir un Error, no un string. Solo así conservas el mensaje, el nombre y la traza de 03-05.
• Una excepción lanzada dentro del ejecutor rechaza la promesa automáticamente. Es la primera señal de que la propagación de errores vuelve a funcionar.

Regla práctica: new Promise solo se usa para envolver algo que todavía no habla en promesas —un setTimeout, una API antigua de callbacks—. Si ya tienes una promesa, no la envuelvas en otra: es un antipatrón tan común que tiene nombre, el constructor promesa explícito.

Convertir una función de callbacks en una que devuelva una promesa se llama prometificar, y es la operación bisagra entre los dos mundos.

Compárala con la versión de callbacks del 05-05. La diferencia esencial está en la primera línea del cuerpo: hay un return. La función devuelve algo, y ese algo es un valor de primera clase:

Ninguna de esas tres líneas era posible con callbacks. Y también existe una receta genérica, útil cuando prometificas muchas funciones error-first:

Es la misma idea de las funciones de orden superior de 03-06: una función que recibe una función y devuelve otra función.

Una promesa se consume registrando qué hacer cuando se salde.

.finally es el equivalente del finally de 02-05 y sirve para lo mismo: la limpieza que hay que hacer pase lo que pase —ocultar un indicador de carga, cerrar una conexión, reactivar un botón—. No recibe argumentos precisamente porque no debe depender del resultado, y no consume el valor: lo deja pasar a los .then siguientes.

Aunque .then(alCumplir, alFallar) existe, la forma recomendada es .then(...).catch(...), y hay un motivo técnico: con dos argumentos, el manejador de error no captura los fallos del propio alCumplir, porque ambos se registran sobre la misma promesa.

Aquí está la propiedad que lo cambia todo:

.then() devuelve una promesa nueva, cumplida con lo que devuelva su callback.

Eso permite poner un .then detrás de otro en lugar de anidarlos. Y hay una regla adicional que hace la magia completa: si el callback devuelve una promesa, la cadena espera a que esa se salde y continúa con su valor, en lugar de pasar la promesa misma.

Con esa herramienta, la pirámide del apartado 9 de 05-05 se convierte en una lista. Primero prometificamos los otros dos módulos simulados:

Y ahora el informe semanal de Marta, el mismo del 05-05, sin una sola anidación:

Tres mejoras respecto a la versión con callbacks, y ninguna es cosmética:

1. La indentación es plana. Los pasos se leen de arriba abajo, en el orden en que ocurren.
2. Hay un único .catch. Si falla la carga, la consulta del equipo o el guardado, el error acaba en la misma línea. Los tres bloques if (error) { … return; } repetidos han desaparecido.
3. El flujo es explícito. Cada return dice qué se le pasa al paso siguiente.

Queda un defecto honesto: esa variable carga fuera de la cadena, necesaria porque el tercer .then necesita un dato que se calculó en el primero. Es exactamente el mismo problema de estado compartido que ya apareció al «aplanar con funciones nombradas» en 05-05, y las promesas por sí solas no lo resuelven del todo. Guarda la incomodidad: async/await la hace desaparecer, porque allí las variables son simplemente variables locales.

Cuando un paso falla, la cadena salta todos los .then siguientes hasta el primer .catch. Es el comportamiento de la pila síncrona de 02-05, recuperado.

Un error dentro de un .then provoca lo mismo, aunque no sea una operación asíncrona:

Y —esto es clave— la cadena se puede recuperar después de un .catch, porque .catch también devuelve una promesa:

De ahí una regla de colocación importante: el .catch captura lo que ocurre por encima de él en la cadena, no por debajo. Si lo pones en medio y quieres que también proteja los pasos siguientes, necesitas otro al final. Lo habitual es un solo .catch al final de todo.

Con errores propios, el patrón se combina con la jerarquía de 05-02:

Dos atajos para crear promesas ya saldadas.

Su uso más valioso es normalizar: hacer que una función devuelva siempre una promesa, tenga o no que trabajar de verdad.

Sin ese Promise.resolve, la función devolvería un array unas veces y una promesa otras, y quien la usara tendría que comprobarlo. Es la memoización de 03-06, ahora aplicada a operaciones asíncronas.

Promise.resolve tiene además una propiedad muy práctica: si le pasas una promesa, la devuelve tal cual, sin envolverla otra vez.

Aquí está la respuesta al «problema 4» del 05-05: combinar operaciones asíncronas. Cuatro métodos estáticos, cada uno con una semántica distinta.

Promise.all — espera a que todas se cumplan. Si una falla, falla el conjunto de inmediato.

Dos cosas que hay que interiorizar. El orden del array de resultados es el de entrada, no el de llegada: aunque Lucía responda primero, su resultado sigue en la tercera posición. Y las tres peticiones corren a la vez: el total tarda 500 ms —lo que la más lenta—, no 1000 ms.

Promise.allSettled — espera a que todas se salden, cumplidas o rechazadas, y nunca falla.

Cada elemento es un objeto { status: 'fulfilled', value } o { status: 'rejected', reason }. Es lo que quieres cuando un fallo parcial es aceptable: prefieres el informe de dos personas a ningún informe.

Promise.race — se salda con la primera que termine, sea cumplida o rechazada. Su uso canónico es imponer un tiempo máximo:

Un aviso honesto: el setTimeout interno no cancela la operación lenta, que sigue corriendo aunque su resultado se ignore. La cancelación de verdad necesita AbortController, que llega en 07-03.

Promise.any — se cumple con la primera que se cumpla, ignorando los rechazos. Solo falla si fallan todas, con un AggregateError.

La tabla de decisión:

Los cuatro aceptan cualquier iterable y devuelven una promesa. Compara mentalmente estas cuatro líneas con las veinte de contadores y banderas del apartado 10 de 05-05: eso es lo que significa que el resultado futuro sea un valor.

Las promesas arreglaron el flujo, pero el código sigue lleno de .then((x) => …). Desde ES2017 existe una sintaxis que elimina hasta eso.

async delante de una función hace que devuelva siempre una promesa.

await delante de una promesa espera su resultado y lo devuelve como si fuera un valor normal. Solo puede usarse dentro de una función async (o en el nivel superior de un módulo, apartado 12).

Que ese await no bloquea nada es lo esencial y lo que más cuesta creer al principio. Lo que hace es suspender esta función en ese punto y devolver el control al programa; cuando la promesa se salda, la función se reanuda justo donde se quedó. El hilo, entretanto, está libre para todo lo demás. El mecanismo exacto que lo permite es el tema de 05-07.

La misma cadena del apartado 5, reescrita:

Compáralo con la pirámide original de 05-05. Es el mismo programa: tres operaciones asíncronas encadenadas, cada una dependiente de la anterior. Y se lee exactamente como se leería si todo fuera síncrono. La variable carga ha vuelto a ser una variable local, sin necesidad de sacarla fuera. No hay callbacks, no hay .then, no hay indentación.

Un apunte de sintaxis: async funciona con cualquier forma de función, incluidas las flecha de 03-02 y los métodos de clase de 05-02.

En 02-05 aprendiste try/catch, y en 05-05 descubriste que no servía para lo asíncrono. Con await, vuelve a servir.

El motivo por el que ahora sí funciona es preciso: await convierte un rechazo en una excepción lanzada en esa misma línea. Como el throw ocurre dentro del try, en la misma pila, el catch lo captura igual que capturaría un TypeError. Toda la maquinaria de 02-05 vuelve a estar disponible: finally, instanceof para distinguir tipos, relanzar lo que no sabes manejar, la jerarquía ErrorDeValidacion/ErrorDeDatos de 05-02.

Y hay una simetría que conviene tener presente:

Son la misma puerta en los dos sentidos, y por eso los errores atraviesan sin problema la frontera entre funciones async y cadenas de promesas.

También puedes mezclar estilos cuando convenga. Un patrón útil es capturar solo un await concreto sin envolver media función:

Este es el error de rendimiento más común de todo async/await, y merece un apartado propio.

Novecientos milisegundos frente a trescientos, con tres elementos. Con treinta responsables serían nueve segundos frente a trescientos milisegundos. La causa es que await dentro de un bucle detiene el bucle: la segunda petición ni siquiera se envía hasta que llega la primera.

La clave del arreglo está en un detalle que conviene subrayar: una promesa empieza a trabajar en el momento en que se crea, no cuando se le hace await. El .map() crea las tres promesas de golpe —y las tres peticiones salen a la vez—; el await Promise.all(...) solo espera a que todas terminen.

Ahora bien: secuencial no siempre está mal. Es lo correcto cuando cada paso necesita el resultado del anterior, o cuando quieres limitar deliberadamente la carga sobre el servidor.

Y una advertencia sobre forEach, que es una trampa clásica:

forEach (04-04) descarta el valor de retorno del callback, así que las tres promesas quedan sueltas y nadie las espera. Si necesitas esperar, usa for...of con await (secuencial) o map + Promise.all (paralelo). Nunca forEach.

Cuando lo que tienes es un array de promesas y quieres procesarlas conforme llegan, existe una variante del bucle:

Las tres peticiones arrancan a la vez (el map ya las creó), y el bucle las va desenvolviendo en orden de array. Su verdadero potencial es recorrer fuentes de datos asíncronas de longitud desconocida —páginas de resultados, ficheros que se leen por trozos—, y para eso hacen falta los iteradores asíncronos, que se estudian en 05-08. Por ahora basta con reconocer la sintaxis.

El otro añadido es el await a nivel de módulo, que ya apareció de pasada en 05-04:

Todo módulo que importe este esperará a que ese await termine antes de ejecutarse. Es cómodo para configuración imprescindible, pero retrasa el arranque de toda la aplicación, así que conviene usarlo con moderación y solo en la capa de datos.

Cuatro fallos que cometerás alguna vez. Conviene reconocerlos por su síntoma.

Trampa 1: olvidar el await. El síntoma es un Promise { <pending> } donde esperabas un dato.

Trampa 2: olvidar el return. La función async se cumple con undefined y nadie se entera.

Un caso especialmente insidioso es olvidar el await dentro de un try:

Sin await, la función devuelve la promesa antes de que se rechace, y el catch no ve nada. La regla es return await cuando el return está dentro de un try; fuera de un try, return promesa es equivalente y algo más eficiente.

Trampa 3: rechazos sin manejar. Una promesa que se rechaza y no tiene ningún .catch ni try/catch produce un UnhandledPromiseRejection. En el navegador aparece como un error en consola; en Node moderno, termina el proceso.

Especialmente traicioneras son las promesas «huérfanas» que se lanzan sin esperar (fire and forget). Si de verdad no te interesa el resultado, ponle un .catch de todos modos, aunque solo registre el fallo.

Trampa 4: async en un constructor. No existe: un constructor no puede ser async porque tiene que devolver el objeto, no una promesa. El patrón correcto es una fábrica estática de las que aprendiste en 05-02:

Reunamos todo en la función que a partir de ahora será el arranque de Nómada Tareas: cargar el backlog, validarlo, construir el tablero y producir el resumen, con reserva local si el servidor falla y tiempo máximo de espera.

Y el punto de entrada, que queda notablemente corto:

Fíjate en el .catch de la última línea: iniciar() es una función async, devuelve una promesa, y si algo se escapa de todos los manejadores internos ese .catch es la red de seguridad que evita un rechazo sin manejar. Toda función async que se invoca desde el nivel superior necesita ese cierre.

La conclusión operativa: escribe async/await por defecto, usa .then/.catch cuando encaje mejor —una transformación suelta, un .catch de reserva en una línea—, recurre a los combinadores para todo lo que sea paralelo, y reserva new Promise para envolver APIs antiguas de callbacks. Y no olvides que los tres estilos son el mismo mecanismo: async/await es sintaxis sobre promesas, y una promesa se salda gracias a callbacks registrados por dentro.

• Olvidar await. El síntoma es Promise { <pending> }, undefined en una propiedad o un TypeError diciendo que un método no es una función. Es la primera hipótesis cuando algo asíncrono da resultados raros.
• Olvidar await dentro de un try. El rechazo escapa del bloque y el catch no se entera. Usa return await cuando el return esté dentro de un try.
• await dentro de un bucle sobre operaciones independientes. Multiplica el tiempo total por el número de elementos. Usa map + Promise.all.
• forEach con un callback async. No espera nada. Usa for...of o map + Promise.all.
• Promesas sin .catch. Un rechazo sin manejar es un error en el navegador y puede tumbar el proceso en Node. Toda cadena termina en .catch, y toda función async llamada desde el nivel superior también.
• Envolver una promesa en new Promise. Si ya tienes una promesa, encadénala. new Promise es solo para envolver lo que aún no lo es.
• reject('texto') con un string. Pierdes nombre y traza. Rechaza siempre con un Error o una subclase de las de 05-02.
• Promise.all cuando toleras fallos parciales. Un solo rechazo tira todo el conjunto. Si prefieres resultados parciales, allSettled.
• Creer que Promise.race cancela. No cancela nada: la operación perdedora sigue corriendo. La cancelación real es AbortController (07-03).
• Constructores async. No existen. Usa una fábrica estática (static async cargar()).
• Consejo: nombra las variables que contienen promesas de forma que se note (promesaBacklog, pendientes). Una variable llamada tareas que en realidad es una promesa es una fuente inagotable de despistes.

Ejercicio 1 — De callbacks a async/await. Reescribe la función conReintentos del ejercicio 3 de 05-05 como conReintentos(operacion, intentos, esperaMs) donde operacion devuelve una promesa. Debe reintentar hasta agotar los intentos, esperar entre ellos y lanzar el último error si todos fallan. Cuenta las líneas y compáralas con la versión de callbacks.

Ejercicio 2 — Informe paralelo con tolerancia a fallos. Escribe informeDeCarga(nombres) que consulte las horas de varias personas en paralelo, incluya en el informe a quienes respondan y liste aparte a quienes fallen, sin que un fallo tumbe el conjunto. Pruébala con ['Iván', 'Marta', 'Nadie', 'Lucía'] y verifica que las 45 h abiertas siguen cuadrando entre los tres reales.

Ejercicio 3 — Predecir la salida. Sin ejecutarlo, indica qué imprime y en qué orden, y explica cada línea. (Nota: aquí solo se pide el resultado; el porqué exacto del orden entre lo síncrono y lo asíncrono es el tema de 05-07.)

Ejercicio 1

Doce líneas de función frente a las veinte de la versión con callbacks, y la comparación cualitativa es más elocuente que el recuento: aquí toda la lógica es lógica. Un for normal cuenta los intentos, un try/catch normal captura el fallo, un await normal espera entre reintentos. Ha desaparecido la función interna que existía solo para poder repetirse, han desaparecido los return de guarda tras cada llamada al callback, y ha desaparecido la fragilidad de la doble llamada: una promesa se salda una sola vez por construcción. Fíjate también en el return await operacion() dentro del try: aquí el await es imprescindible, porque sin él el rechazo escaparía del bloque y no habría reintento (trampa 2 del apartado 13).

Ejercicio 2

Las 45 h canónicas cuadran: 25 de Iván, 6 de Marta y 14 de Lucía. Tres decisiones que merecen comentario. La elección de allSettled en lugar de all es el corazón del ejercicio: con all, el fallo de 'Nadie' habría tirado el informe completo y no habrías visto ni una línea. El resultados.entries() es necesario porque allSettled no dice a qué entrada corresponde cada resultado; lo único garantizado es que el orden se conserva, y por eso el índice sirve para recuperar el nombre. Y las cuatro consultas se lanzan a la vez en el map, así que el informe tarda lo que la más lenta, no la suma de las cuatro.

Ejercicio 3

Línea por línea:

• A y B son síncronas dentro de principal. Entre ellas se crean p1 y p2: paso es async, y su cuerpo se ejecuta hasta el primer await, así que los dos temporizadores arrancan de inmediato y en paralelo. Ninguna imprime nada todavía.
• F sale después de B porque principal() se suspende en su primer await y devuelve el control al nivel superior, que aún tenía ese console.log pendiente.
• D dos falló: a los 100 ms p2 se rechaza. Promise.all se rechaza al instante con el primer fallo, sin esperar a p1. Por eso no se imprime C.
• Nunca aparece fin dos (lanzó antes de llegar al console.log), pero sí aparecería fin uno a los 200 ms: p1 sigue su curso aunque Promise.all ya la haya ignorado —recuerda que nada se cancela—. Su fin uno se cuela entre D y E.
• E [ 'fulfilled', 'rejected' ]: allSettled espera a las dos y nunca se rechaza; 'tres' imprime su fin tres y 'cuatro' falla sin imprimir.

Con fin uno incluido, la salida completa es: A, B, F, D dos falló, fin uno, fin tres, E [...]. La lección que hay que llevarse es doble: Promise.all falla rápido pero no cancela nada, y una función async cede el control en su primer await, que es exactamente el mecanismo que se disecciona en la lección siguiente.

Has resuelto los cuatro problemas que dejó la lección anterior, y todos con la misma idea: hacer que el resultado futuro sea un valor. Una promesa es un objeto con tres estados —pendiente, cumplida, rechazada—, con una transición única e irreversible que hace imposible la doble llamada, y con el resultado conservado para quien se suscriba más tarde. Sabes crearla con new Promise((resolve, reject) => …) —recordando que el ejecutor se ejecuta de inmediato, que solo cuenta la primera llamada y que hay que rechazar con Error—, y sabes prometificar una API de callbacks, que es la operación bisagra entre los dos mundos y la que convirtió leerBacklogSimulado en leerBacklog.

Dominas el consumo. .then para el valor, .catch para el fallo, .finally para la limpieza; y sobre todo el encadenamiento, porque cada .then devuelve una promesa nueva y, si su callback devuelve otra promesa, la cadena la espera. Eso aplanó la pirámide del informe semanal en una lista de pasos con un solo .catch al final, y restauró la propagación automática de errores que se había perdido al cruzar la frontera asíncrona: un fallo en cualquier eslabón salta hasta el primer manejador, y un .catch intermedio puede incluso recuperar la cadena devolviendo un valor de reserva. Con Promise.resolve normalizas funciones que a veces trabajan y a veces responden de caché, y con los cuatro combinadores resuelves en una línea lo que exigía contadores manuales: all cuando lo necesitas todo, allSettled cuando toleras fallos parciales, race para tiempos máximos y any para varias fuentes equivalentes.

Y has llegado a async/await, que es sintaxis sobre todo lo anterior. Una función async devuelve siempre una promesa —se cumple con el return, se rechaza con el throw—, y await suspende esa función sin bloquear el hilo hasta que la promesa se salda, entregando el valor como si fuera normal. Con eso, el try/catch vuelve a funcionar, porque await convierte un rechazo en una excepción lanzada en esa misma línea, y con él vuelven finally, el instanceof para distinguir ErrorDeValidacion de ErrorDeDatos, y el fail-fast de relanzar lo que no sabes manejar. Conoces el error de rendimiento clásico —await dentro de un bucle sobre operaciones independientes, 900 ms en lugar de 300— y su arreglo con map + Promise.all, apoyado en el detalle de que una promesa empieza a trabajar al crearse, no al esperarla; sabes que forEach con un callback async no espera nada; y reconoces for await...of y el await a nivel de módulo. Las cuatro trampas —olvidar el await, olvidar el return dentro de un try, dejar rechazos sin manejar, intentar un constructor async— están identificadas por su síntoma. Y cargarTablero() reúne todo: carga con tiempo máximo, valida los invariantes del backlog, cae a datos locales si el servidor falla y devuelve el resumen canónico de siempre —48 h, 45 abiertas, 1 vencida, esfuerzo 124— en una función que se lee de arriba abajo.

Queda una pregunta que hemos ido esquivando a propósito. Sabes qué hace await, pero no por qué el orden de la salida es el que es: por qué 'F' sale antes que el resultado de una promesa ya cumplida, por qué un setTimeout(f, 0) se ejecuta después de un .then registrado más tarde, y por qué un bucle pesado congela la interfaz aunque haya await de por medio. Todo eso lo decide una maquinaria con nombre propio —la pila de llamadas, las APIs del entorno, la cola de macrotareas, la cola de microtareas y el bucle que las coordina— y es el tema de El Bucle de Eventos y la Cola de Microtareas.