Promise

El objeto Promise (Promesa) es usado para computaciones as铆ncronas. Una promesa representa un valor que puede estar disponible ahora, en el futuro, o nunca.

Sintaxis

new Promise( /* ejecutor */ function(resolver, rechazar) { ... } );

Par谩metros

ejecutor
Una funci贸n con los argumentos resolver y rechazar. La funci贸n ejecutor es ejecutada inmediatamente por la implementaci贸n de la Promesa, pas谩ndole las funciones resolver y rechazar (el ejecutor es llamado incluso antes de que el constructor de la Promesa devuelva el objeto creado). Las funciones resolver y rechazar, al ser llamadas, resuelven o rechazan la promesa, respectivamente. Normalmente el ejecutor inicia un trabajo as铆ncrono, y luego, una vez que es completado, llama a la funci贸n resolver para resolver la promesa o la rechaza si ha ocurrido un error.
Si un error es lanzado en la funci贸n ejecutor, la promesa es rechazada y el valor de retorno del ejecutor es rechazado.

Descripci贸n

Una Promesa es un proxy para un valor no necesariamente conocido en el momento que es creada la promesa. Permite asociar manejadores que actuar谩n asincr贸nicamente sobre un eventual valor en caso de 茅xito, o la raz贸n de falla en caso de una falla. Esto permite que m茅todos as铆ncronos devuelvan valores como si fueran s铆ncronos: en vez de inmediatamente retornar el valor final, el m茅todo as铆ncrono devuelve una promesa de suministrar el valor en alg煤n momento en el futuro.

Una Promesa se encuentra en uno de los siguientes estados:

  • pendiente (pending): estado inicial, no cumplida o rechazada.
  • cumplida (fulfilled): significa que la operaci贸n se complet贸 satisfactoriamente.
  • rechazada (rejected): significa que la operaci贸n fall贸.

Una promesa pendiente puede ser cumplida con un valor, o rechazada con una raz贸n (error). Cuando cualquiera de estas dos opciones sucede, los m茅todos asociados, encolados por el m茅todo then de la promesa, son llamados. (Si la promesa ya ha sido cumplida o rechazada en el momento que es anexado su correspondiente manejador, el manejador ser谩 llamado, de tal manera que no exista una condici贸n de carrera entre la operaci贸n as铆ncrona siendo completada y los manejadores siendo anexados)

Como los m茅todos Promise.prototype.then() y Promise.prototype.catch() retornan promesas, 茅stas pueden ser encadenadas.

No confundir con: Varios lenguajes tienen mecanismos para evaluar perezosamente y postergar una computaci贸n, a los que tambi茅n les llaman "promesas" - p.ej.: Scheme. Las promesas en JavaScript representan procesos que ya est谩n sucediendo, y pueden ser encadenados con funciones callback. Si lo que se busca es evaluar perezosamente una expresi贸n, se debe considerar la funci贸n flecha (arrow function) sin argumentos: f = () => expresi贸n para crear la expresi贸n evaluada perezosamente, y f() para evaluar.

Nota: Una promesa se dice que est谩 determinada (settled) si se ha cumplido o si se ha rechazado, pero no est谩 pendiente. Con promesas tambi茅n se usa el t茅rmino resuelta 鈥 esto significa que la promesa est谩 determinada, o que se encuentra bloqueada dentro de una cadena de promesas. States and fates de Domenic Denicola contiene mas detalles sobre la terminolog铆a de las promesas.

Propiedades

Promise.length
Propiedad longitud cuyo valor es siempre 1 (numero de argumentos del constructor).
Promise.prototype (en-US)
Representa el prototipo del constructor Promise.

M茅todos

Promise.all(iterable)
Devuelve una de dos promesas: una que se cumple cuando todas las promesas en el argumento iterable han sido cumplidas, o una que se rechaza tan pronto como una de las promesas del argumento iterable es rechazada. Si la promesa retornada es cumplida, lo hace con un arreglo de los valores de las promesas cumplidas en el mismo orden definido en el iterable. Si la promesa retornada es rechazada, es rechazada con la raz贸n de la primera promesa rechazada en el iterable. Este m茅todo puede ser 煤til para agregar resultados de m煤ltiples promesas
Promise.race(iterable)
Devuelve una promesa que se cumple o rechaza tan pronto como una de las promesas del iterable se cumple o rechaza, con el valor o raz贸n de esa promesa.
Promise.reject(reason)
Devuelve un objeto Promise que es rechazado con la raz贸n dada.
Promise.resolve(value)
Devuelve un objeto Promise que es resuelto con el valor dado. Si el valor es un thenable (p.ej. tiene un m茅todo then), la promesa devuelta "seguir谩" este thenable, adoptando su eventual estado; de lo contrario la promesa devuelta ser谩 cumplida con el valor. Generalmente, si se quiere saber si un valor es una promesa o no, se podr铆a usar - Promise.resolve(value) y trabajar con el valor devuelto como una promesa.

Prototipo Promise

Propiedades

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Properties')}}

M茅todos

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Methods')}}

Ejemplos

S煤per simple (隆10 l铆neas!)

let miPrimeraPromise = new Promise((resolve, reject) => {
  // Llamamos a resolve(...) cuando lo que estabamos haciendo finaliza con 茅xito, y reject(...) cuando falla.
  // En este ejemplo, usamos setTimeout(...) para simular c贸digo as铆ncrono.
  // En la vida real, probablemente uses algo como XHR o una API HTML5.
  setTimeout(function(){
    resolve("隆脡xito!"); // 隆Todo sali贸 bien!
  }, 250);
});

miPrimeraPromise.then((successMessage) => {
  // succesMessage es lo que sea que pasamos en la funci贸n resolve(...) de arriba.
  // No tiene por qu茅 ser un string, pero si solo es un mensaje de 茅xito, probablemente lo sea.
  console.log("隆S铆! " + successMessage);
});

Creando una Promise

Este peque帽o ejemplo muestra el mecanismo de una Promise. El m茅todo testPromise() se llama cada vez que se pulsa el <button>. Esto crea una promesa que se cumplir谩, aplicando window.setTimeout() (en-US), al contador de la promesa (partiendo desde 1) aleatoriamente cada 1-3 segundos. El constructor de la Promise() es usado para crear dicha promesa.

El cumplimiento de la promesa simplemente se registra, a trav茅s de una llamada de retorno al cumplirse utilizando p1.then(). A los pocos registros muestra c贸mo la parte s铆ncrona del m茅todo se desacopla de la finalizaci贸n as铆ncrona de la promesa.

'use strict';
var promiseCount = 0;

function testPromise() {
  var thisPromiseCount = ++promiseCount;

  var log = document.getElementById('log');
  log.insertAdjacentHTML('beforeend', thisPromiseCount +
    ') Comenz贸 (<small>Comenz贸 el c贸digo sincr贸nico</small>)<br/>');

  // Hacemos una promesa: prometemos un contador num茅rico de esta promesa,
  // empezando por 1 (despu茅s de esperar 3s)
  var p1 = new Promise(
    // La funci贸n resolvedora es llamada con la
    // habilidad de resolver o rechazar la promesa
    function(resolve, reject) {
      log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Comenz贸 la promesa (<small>C贸digo as铆ncrono comenz贸</small>)<br/>');

      // Esto es solo un ejemplo para crear asincronismo
      window.setTimeout(
        function() {
          // 隆Cumplimos la promesa!
          resolve(thisPromiseCount);
        }, Math.random() * 2000 + 1000);
    }
  );

  // Definimos qu茅 hacer cuando la promesa es resuelta/cumplida con la llamada
  // al m茅todo then(). La llamada al m茅todo catch() define qu茅 hacer si
  // la promesa es rechazada
  p1.then(
    // Registrar el valor de la promesa cumplida
    function(val) {
      log.insertAdjacentHTML('beforeend', val +
        ') Promesa cumplida (<small>C贸digo as铆ncrono terminado.</small>)<br/>');
    })
  .catch(
    // Registrar la raz贸n del rechazo
    function(reason) {
      console.log('Manejar promesa rechazada ('+reason+') aqu铆.');
    });

  log.insertAdjacentHTML('beforeend', thisPromiseCount +
    ') Promesa hecha (<small>C贸digo s铆ncrono terminado. </small>)<br/>');
}

Este ejemplo es ejecutado cuando pulsas el bot贸n. Necesitas un navegador que soporte Promise. Al pulsar el bot贸n varias veces en un per铆odo corto de tiempo, ver谩s las diferentes promesas siendo cumplidas una tras otra.

Cargando una imagen con XHR

Otro ejemplo sencillo utilizando Promise y XMLHttpRequest para cargar una imagen est谩 disponible en el repositorio js-examples de MDN en GitHub. Tambi茅n puedes verlo en acci贸n. Cada paso est谩 comentado y te permite seguir de cerca la arquitectura detr谩s de las Promesas y XHR.

Especificaciones

Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
La definici贸n de 'Promise' en esta especificaci贸n.
Standard Initial definition in an ECMA standard.
ECMAScript (ECMA-262)
La definici贸n de 'Promise' en esta especificaci贸n.
Living Standard

Compatibilidad de navegadores

No compatibility data found for javascript/promise.
Check for problems with this page or contribute missing data to mdn/browser-compat-data.

Ver tambi茅n