Promise

Un objeto Promise  representa un valor que puede no estar disponible aún.

Una referencia a un Promise existente puede ser recibida por diferentes medios, por ejemplo como el valor de retorno de una llamada a una API asíncrona. Una vez que tenga una referencia al objeto Promise, puede llamar a su método then() para ejecutar una acción cuando el valor esté disponible o cuando ocurra un error.

Los objetos Promise también pueden ser creados usando el constructor new Promise(). No necesita importar el módulo Promise.jsm para usar un objeto Promise del que ya se tiene una referencia.

Internamente, Promise puede encontrarse en uno de tres estados:

  • Pending, cuando el valor final no está disponible aún. Este es el único estado que puede cambiar a uno de los otros dos estados.
  • Fulfilled, cuando y si el valor final esté disponible. Un valor fulfillment viene asociado permanentemente con Promise. Este puede ser cualquiera, incluyendo undefined.
  • Rejected, si un error impidió que el valor final se determine. Una valor rejection viene asociado permanentemente con Promise. Este puede ser cualquier valor, incluyendo undefined, aunque por lo general es un objeto Error, como en el manejo de excepciones.

Nota: siempre debería controlar, enviar o reportar errores (rejection reasons). Si ve el mensaje "A promise chain failed to handle a rejection", es posible que haya algo que corregir en el código. Vea manejo de errores y problemas comunes a continuación.

Convenciones de la documentación

En la documentación, el tipo de valor fulfillment es especificado normalmente entre corchetes angulados. Por ejemplo, la función OS.File.exists retorna un objeto Promise que eventualmente cumpla con un boolean:

Promise<boolean> exists(string path);

El motivo de rechazo (rejection reason) podrá especificarse por separado en la documentación de la función, y se considera que es un objeto Error a menos que se especifique lo contrario.

Resumen del método

Promise then([opcional] Function onFulfill, [opcionalFunction onReject);
Promise catch([opcionalFunction onReject);

Constructor

Crea un nuevo objeto Promise, inicialmente con estado pendiente (pending) y proporciona referencias a las funciones de resolución que se puedan utilizar para cambiar su estado.

new Promise(executor);

Parámetros

executor

Esta función se invoca inmediatamente con la resolución de funciones como sus dos argumentos:

executor(resolve, reject);

El constructor no retornará valor hasta que el executor haya terminado. Las funciones de resolución pueden ser usadas en cualquier momento, antes o despues que executor haya terminado, para controlar el estado final de Promise. Si executor lanza una excepción, su valor será pasado a la función de resolución reject .

Funciones de resolución

resolve()

Cumple con el Promise asociado con el valor especificado, o propaga el estado de un objeto Promise existente. Si el Promise asociado ya ha sido resuelto, ya sea a un valor, un rechazo, o de otro Promise, este método no hace nada.

Nota: llamar a este método con un Promise pendiente con el argumento aValue, y luego llamándolo con otro valor antes de que Promise se haya cumplido (fulfilled) o rechazado (rejected), no tendrá efecto la segunda vez, ya que el objeto Promise asociado ya está resuelto al objeto Promise pendiente.
void resolve(
  aValue
);
Parameters
aValue Opcional
Si este valor no es un Promise, incluyendo undefined, se convierte en el valor de cumplimiento del Promise asociado. Si este valor es un objeto Promise, el Promise asociado será resuelto con el promise pasado, y seguirá el estado como la promesa proporcionada (incluyendo cualquier transición futura).

reject()

Rechaza el Promise asociada con la razón especificada. Si el Promise ya se ha resuelto, ya sea a un valor, un rechazo, o de otro Promise, este método no hace nada.

void reject(
  aReason
);
Parameters
aReason Opcional

El motivo de rechazo de la promesa asociada. Aunque la razón puede ser undefined, por lo general es un objeto de Error, como en el manejo de excepciones.

Nota: este argumento no debería ser un Promise. Especificar un Promise rechazado haría el motivo de rechazo igual al Promise rechazado en sí, y no a su razón de rechazo.

Métodos

then()

Llama a una de las funciones previstas tan pronto como esta Promise se haya, bien cumplido, o bien rechazado.  Se retorna un nuevo promise, cuyo estado evoluciona dependiendo del promise y la funcion de devolución de llamada (callbacks) proporcionados.

La devolución de llamada apropiada siempre se invoca después de devolver este método, incluso si esta Promise se ha cumplido o rechazado. Pude lamar al método then() muchas veces para el mismo Promise, y las funciones de devolución de llamada (callbacks) serán invocadas en el mismo orden en el cual fueron registradas.

Advertencia: si la funcion de llamada onFulfill lanza una axcepción, onReject no se invocará y la excepción no será capturada, se muestra en la consola (verá una error de cadena promesa fallida). Puede registrar una función de llamada de rechazo en el promise retornado en su lugar (usando catch() o then()), para procesar cualquier excepción ocurrida en cualquiera de las devoluciones de llamada registradas para este promise.

Nota: cuando llama al método then() multiples veces para el mismo promise, las funciones de devolución de llamada (callbacks) son siempre ejecutadas inmediatamente. Por ejemplo, si una acepción ocurre en un callback, no afecta al callback posterior. El comportamiento del callback sólo afecta al promise retornado por el método then() con el cual el callback fue registrado, esto es en realidad un promise diferente para cada invocación del método.
Promise then(
  Function onFulfill,
  Function onReject
);
Parámetros
onFulfill Optional
Si el promise está cumplido (fulfilled), esta funciń es invokada con el valor de cumplimiento del promise como su único argumento, y elo resultado de la función determina el estado del nuevo promise retornado por el método then(). En caso este parámetro (usualmente null), el nuevo promise retornado por el método then() es cumplido (fulfilled) con el mismo valor del promise original.
onReject Optional

Si el promise es rechazado (rejected), esta función es invocada con con el motivo de rechazo del promise como su único argumento, y el resultado del la función determina el nuevo estado del promise retornado por el método then(). En caso este parametro no es un función (Por lo general undefined), el nuevo promise retornado por el método then() es rechazado (rejected) con la misma razón que el promise original.

Valor de retorno

Un nuevo promise que es initialmente pendiente, luego asume un estado que depende del resultado de la función de devolución de llamada (callback):

  • Si el callback retorna un valor que nos es un promise, incluyendo undefined, el nuevo promise es cumplido (fulfilled) con este valor de cumplimiento, incluso si el promise original fue rechazado (rejected).
  • Si el callback lanza una excepción, el nuevo promise es rechazado (rejected) con la excepción como motivo de rechazo, incluso si el promise original fue cumplida (fulfilled).
  • Si el callback retorna un promise, el nuevo promise eventualmente asumirá el mismo estado del promise retornado.

catch()

Equivalente a then() con un valor undefined para el parámetro onFulfill. Si encadena then( onFulfill ).catch( onReject ), las excepciones lanzadas en onFulfill serán capturadas y pasadas a onReject, que no es el caso cuando pasa onReject a then().

Promise catch(
  Function onReject
);

Las siguientes llamadas son por lo tanto idénticas:

p.then(undefined, logError);
p.catch(logError);

Depuración

Por diseño, el estado instantáneo y el valor de un Promise no pueden ser inspeccionados de forma sincrónica, sin llamar al método then().

PAra ayudar con la depuración,  sólo cuando inspeccione un objeto Promise manualmente,  puede ver información con propiedades especialesque son accesibles desde código (esto, actualmente, está implementado se implementa mediante la aleatorización del nombre de la propiedad, por la falta de un lenguaje más sofisticado o soporte depurador).

Estas propiedades inspeccionables de código inaccesible son:

  • {{privado:status}}: 0 para pendiente, 1 para cumplido, o 2 para rechazado.
  • {{privado:value}}: Valor de cumplimiento o razon de rechazo, sólo para Promises cumplidos o rechazados.
  • {{privado:handlers}}: Array de objetos de las referencias a funciones registradas por el método then(), sólo para Promises pendientes.

Promise properties are visible in the debugger.Promise handlers can be watched from the Console.

Ejemplos

Ver la página de ejemplos.

Gestión de errores y problemas comunes

Debe reportar errores no controlados, a menos que de el relevo de Promise a una función de llamada u otra ruta de código que controlará el error.

// ###### ERROR: Silenciando cualquier rechazo notificado por "OS.File.Exists".
OS.File.exists(path).then(exists => { if (exists) myRead(path); });

// ###### ERROR: Silenciando cualquier excepción planteado por "myRead".
OS.File.exists(path).then(exists => { if (exists) myRead(path); }, Components.utils.reportError);

// CORRECTO (por ejemplo, podria reportar la excepción "myRead ino está definido")
OS.File.exists(path).then(exists => { if (exists) myRead(path); })
                    .catch(Components.utils.reportError);

// CORRECTO (La función retorna un Promise, y el caller se encargará del rechazo)
function myReadIfExists(path)
{
  return OS.File.exists(path).then(exists => { if (exists) myRead(path); });
}

Ver también

Etiquetas y colaboradores del documento

 Colaboradores en esta página: RickieES, joseluisq
 Última actualización por: RickieES,