Las solicitudes de red, las lecturas de archivos y los temporizadores finalizan más tarde, pero JavaScript no puede simplemente detenerse y esperar, o la página se congelaría. Las promesas de JavaScript le brindan una manera ordenada de decir “cuando esto termine, haga aquello, y si falla, haga esto en su lugar”.

Incluso si escribe principalmente async y await, está utilizando promesas debajo, por lo que comprenderlas facilita mucho la depuración. Ejecutamos estos ejemplos en Node.js 24 y el resultado que se muestra proviene de esa ejecución. Se comportan de la misma manera en los navegadores modernos.

¿Qué es una promesa?

Una promesa es un marcador de posición para un valor futuro. Piensa en el timbre que te da un restaurante cuando haces un pedido. Aún no tienes tu comida, pero sostienes algo que te dirá cuando está lista, o que hay un problema, y ​​mientras tanto eres libre de hacer otras cosas.

En el código, una función asincrónica devuelve una promesa inmediatamente y usted adjunta lo que debería suceder a continuación:

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

Los tres estados de promesa

Una promesa que se cumple o se rechaza se llama cumplida. Una promesa sólo puede cumplirse una vez. Después de eso, su estado y valor se fijan y las llamadas posteriores a resolve o reject se ignoran.

Crea una promesa

Por lo general, consume promesas de API como fetch, pero crear una muestra cómo funcionan. El constructor recibe dos funciones, resolve y reject:

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

Registrar la promesa de inmediato muestra que aún está pendiente porque el temporizador no se ha activado. El valor solo se puede alcanzar a través de un controlador o await. Rechace siempre con un objeto Error en lugar de una cadena, ya que un Error lleva un seguimiento de la pila que ayuda con la depuración.

luego, atrapar y finalmente

Estos tres métodos adjuntan controladores a una promesa:

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then se ejecuta en caso de éxito, catch se ejecuta en caso de error y finally se ejecuta en cualquier sentido. Eso hace que finally sea el lugar adecuado para la limpieza, como ocultar un control giratorio de carga. No recibe argumentos, porque no debería importarle el resultado.

Encadenando promesas

La idea clave es que then siempre devuelve una nueva promesa. Lo que sea que devuelva su controlador se convierte en el valor de esa nueva promesa:

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

Si un controlador devuelve otra promesa, la cadena espera a que se establezca antes de continuar. Esto es lo que convierte las devoluciones de llamadas anidadas en una secuencia plana de pasos:

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

Cómo viajan los errores a través de una cadena

Una promesa rechazada se salta cada then hasta llegar a un catch. Lanzar dentro de un guía también cuenta como un rechazo. Y un catch que regresa normalmente vuelve a encarrilar la cadena:

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

Piense en esto como la versión asincrónica de try y catch. Un catch al final suele cubrir toda la cadena. Si solo desea registrar un error y aún así falla, tírelo nuevamente desde el interior del catch.

Promise.all, allSettled, raza y cualquiera

Estos métodos estáticos coordinan varias promesas a la vez. Todos ellos toman una matriz y devuelven una promesa.

Para probarlos, utilizamos dos pequeños ayudantes, uno que tiene éxito después de un retraso y otro que falla después de un retraso:

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

Dos detalles a destacar. Los resultados mantienen el orden de entrada, aunque b termine primero. Y el tiempo total fue de unos 300 ms, el tiempo de la tarea más lenta y no la suma de los 600 ms, porque ya estaban ejecutándose las tres a la vez. Si alguno de ellos rechaza, todo el conjunto rechaza inmediatamente:

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

Este espera todo e informa cada resultado, para que un fallo no pierda el resto. Se adapta a un panel donde cada widget se carga de forma independiente:

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promesa.race y Promesa.cualquiera

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

La diferencia es que race toma el primero en resolverse, incluso si falló, mientras que any ignora los fracasos siempre que algo tenga éxito. Un uso clásico de race es agregar un tiempo de espera a una solicitud lenta, aunque la tarea más lenta continúa ejecutándose en segundo plano a menos que la cancele.

Promesas y async/await

async y await son una forma más legible de trabajar con las mismas promesas. Una función async siempre devuelve una promesa y await pausa esa función hasta que se cumpla una promesa:

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

Los rechazos se convierten en errores, por lo que try y catch ordinarios funcionan. Aún necesitas Promise.all para el trabajo paralelo, porque esperar una llamada tras otra las ejecuta en secuencia. Nuestra guía de JavaScript async/await profundiza en esto.

Promesas y el bucle de eventos.

Los manejadores de promesas nunca son llamados inmediatamente, incluso cuando la promesa ya se ha cumplido. Se ejecutan después de que finaliza el código actual y antes de cualquier temporizador. Aquí está la prueba:

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

El código sincrónico se ejecuta primero. Luego viene la cola de microtareas, que contiene controladores de promesas. Sólo entonces el bucle de eventos selecciona la siguiente tarea, como un temporizador. Esta es una pregunta de entrevista popular y explica por qué un setTimeout de cero no es realmente inmediato.

Promesas versus devoluciones de llamada

Errores comunes

• Olvidarse de regresar al interior de then. Sin un return, el siguiente paso recibe undefined y no espera tu promesa interior.
• No catch en absoluto. Esto provoca un rechazo no controlado y, en Node.js, detiene el proceso de forma predeterminada.
• Anidar en lugar de encadenar. Poner then dentro de then recrea el infierno de las devoluciones de llamadas. Devuelve la promesa y continúa la cadena.
• Envolviendo una promesa en new Promise. Si una función ya devuelve una promesa, simplemente úsela.
• Usando forEach con devoluciones de llamada asíncronas. No espera. Utilice for...of o Promise.all con map, como se muestra en nuestra guía de métodos de matriz de JavaScript.
• Pensar que una promesa se puede cancelar. No puede por sí sola. Para solicitudes, utilice AbortController.

Conclusión

Las promesas se reducen a unas pocas reglas: una promesa se cumple una vez, then devuelve una nueva promesa y los errores viajan a lo largo de la cadena hasta que algo los detecta. Una vez que esas reglas se sientan naturales, async y await dejan de ser mágicas. Para practicar, reescriba una función basada en devolución de llamada usando promesas, luego busque dos puntos finales con Promise.all y maneje una falla adecuadamente.

Preguntas frecuentes

sigue aprendiendo