Servicio de traducción

El objeto Promise representa la finalización (o el fallo) eventual de una operación asíncrona y su valor resultante.

Ciclo de vida de una promesa

Una Promise tiene tres estados:

1. pendiente
2. resuelta
3. rechazada

Cuando se crea, una promesa está pendiente. En algún momento futuro puede resolverse o rechazarse. Una vez que una promesa se resuelve o se rechaza, no puede volver a resolverse ni rechazarse, y su estado tampoco puede cambiar.

En otras palabras:

1. Mientras está pendiente, una promesa:
   • puede pasar al estado resuelta o rechazada.
2. Cuando está resuelta, una promesa:
   • no debe pasar a ningún otro estado.
   • debe tener un valor, que no debe cambiar.
3. Cuando está rechazada, una promesa:
   • no debe pasar a ningún otro estado.
   • debe tener una razón, que no debe cambiar.

Cómo resolver una promesa

Una promesa puede resolverse de varias formas:

// Creates a promise that is immediately resolved
Promise.resolve(value);

// Creates a promise that is immediately resolved
new Promise((resolve) => {
  resolve(value);
});

// Chaining a promise leads to a resolved promise
somePromise.then(() => {
  // ...
  return value;
});

En los ejemplos anteriores, value puede ser cualquier cosa, incluido un error, undefined, null u otra promesa. Por lo general, querrás resolver con un valor que no sea un error.

Cómo rechazar una promesa

Una promesa puede rechazarse de varias formas:

// Creates a promise that is immediately rejected
Promise.reject(reason)

// Creates a promise that is immediately rejected
new Promise((_, reject) {
  reject(reason)
})

// Chaining a promise with an error leads to a rejected promise
somePromise.then(() => {
  // ...
  throw reason
})

En los ejemplos anteriores, reason puede ser cualquier cosa, incluido un error, undefined o null. Por lo general, querrás rechazar con un error.

Cómo encadenar una promesa

Una promesa puede continuarse con una acción futura una vez que se resuelve o se rechaza.

• Se llama a promise.then() una vez que promise se resuelve
• Se llama a promise.catch() una vez que promise se rechaza
• Se llama a promise.finally() una vez que promise se resuelve o se rechaza

then

Toda promesa es «thenable». Eso significa que hay una función then disponible que se ejecutará una vez que la promesa original se resuelva. Dado promise.then(onResolved), el callback onResolved recibe el valor con el que se resolvió la promesa original. Esto siempre devolverá una nueva promesa «encadenada».

Devolver un value desde then resuelve la promesa «encadenada». Lanzar un reason en then rechaza la promesa «encadenada».

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);
});

const promise2 = promise1.then(function (value) {
  console.log(value);
  // expected output: "Success!"

  return true;
});

Esto imprimirá "Success!" en la consola después de aproximadamente 1000 ms. El estado y el valor de promise1 serán resolved y "Success!". El estado y el valor de promise2 serán resolved y true.

Hay un segundo argumento disponible que se ejecuta cuando la promesa original se rechaza. Dado promise.then(onResolved, onRejected), el callback onResolved recibe el valor con el que se resolvió la promesa original, o el callback onRejected recibe la razón por la que se rechazó la promesa.

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return true;
}

function shout(reason) {
  console.error(reason.toUpperCase());
  return false;
}

const promise2 = promise1.then(log, shout);

• En aproximadamente la mitad de los casos, esto imprimirá "Success!" en la consola después de aproximadamente 1000 ms.
  • El estado y el valor de promise1 serán resolved y "Success!".
  • El estado y el valor de promise2 serán resolved y true.
• En aproximadamente la mitad de los casos, esto imprimirá inmediatamente "NOPE!" en la consola.
  • El estado y el valor de promise1 serán rejected y Nope!.
  • El estado y el valor de promise2 serán resolved y false.

Es importante entender que, debido a las reglas del ciclo de vida, cuando se llama a reject, el resolve que llega unos 1000 ms más tarde se ignora en silencio, ya que el estado interno no puede cambiar una vez que se ha rechazado o resuelto. Es importante entender que devolver un valor desde una promesa la resuelve, y lanzar un valor la rechaza. Cuando promise1 se resuelve y hay un onResolved encadenado: then(onResolved), esa continuación es una nueva promesa que puede resolverse o rechazarse. Cuando promise1 se rechaza pero hay un onRejected encadenado: then(, onRejected), esa continuación es una nueva promesa que puede resolverse o rechazarse.

catch

A veces quieres capturar errores y solo continuar cuando la promesa original se rechaza. Dado promise.catch(onCatch), el callback onCatch recibe la razón por la que se rechazó la promesa original. Esto siempre devolverá una nueva promesa «encadenada».

Devolver un value desde catch resuelve la promesa «encadenada». Lanzar un reason en catch rechaza la promesa «encadenada».

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return 'done';
}

function recover(reason) {
  console.error(reason.toUpperCase());
  return 42;
}

const promise2 = promise1.catch(recover).then(log);

En aproximadamente la mitad de los casos, esto imprimirá "Success!" en la consola después de aproximadamente 1000 ms. En la otra mitad de los casos, esto imprimirá inmediatamente 42 en la consola.

• Si promise1 se resuelve, se omite catch y se llega a then, que imprime el valor.
  • El estado y el valor de promise1 serán resolved y "Success!".
  • El estado y el valor de promise2 serán resolved y "done";
• Si promise1 se rechaza, se ejecuta catch, que devuelve un valor, y por lo tanto la cadena ahora está resolved, y se llega a then, que imprime el valor.
  • El estado y el valor de promise1 serán rejected y "Nope!".
  • El estado y el valor de promise2 serán resolved y "done";

finally

A veces quieres ejecutar código después de que una promesa finalice, sin importar si se resuelve o se rechaza. Dado promise.finally(onSettled), el callback onSettled no recibe nada. Esto siempre devolverá una nueva promesa «encadenada».

Devolver un value desde finally copia el estado y el valor de la promesa original, ignorando el value. Lanzar un reason en finally rechaza la promesa «encadenada», sobrescribiendo cualquier estado y valor o razón de la promesa original.

Ejemplo

Varios de los métodos juntos:

const myPromise = new Promise(function (resolve, reject) {
  const sampleData = [2, 4, 6, 8];
  const randomNumber = Math.round(Math.random() * 5);

  if (sampleData[randomNumber]) {
    resolve(sampleData[randomNumber]);
  } else {
    reject('Sampling did not result in a sample');
  }
});

const finalPromise = myPromise
  .then(function (sampled) {
    // If the random number was 0, 1, 2, or 3, this will be
    // reached and the number 2, 4, 6, or 8 will be logged.
    console.log(`Sampled data: ${sampled}`);
    return 'yay';
  })
  .catch(function (reason) {
    // If the random number was 4 or 5, this will be reached and
    // reason will be "An error occurred". The entire chain will
    // then reject with an Error with the reason as message.
    throw new Error(reason);
  })
  .finally(function () {
    // This will always log after either the sampled data is
    // logged or the error is raised.
    console.log('Promise completed');
  });

• En los casos en que randomNumber es 0-3:
  • myPromise se resolverá con el valor 2, 4, 6, or 8
  • finalPromise se resolverá con el valor 'yay'
  • Habrá dos mensajes en la consola:
    • Sampled data: ...
    • Promise completed
• En los casos en que randomNumber es 4-5:
  • myPromise se rechazará con la razón 'Sampling did not result in a sample'
  • finalPromise se rechazará con la razón Error('Sampling did not result in a sample')
  • Habrá un mensaje en la consola:
    • Promise completed
    • en algunos entornos esto producirá un registro "uncaught rejected promise: Error('Sampling did not result in a sample')"

Como se muestra arriba, reject funciona con un string, y una promesa también puede rechazarse con un Error.