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.

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

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.

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.

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.

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

• Promise.jsm
• Deferred
• Examples
• JavaScript OS.File
• Promises, Promises: a useful simple explanation by Stuart Langridge
• WHATWG Living Standard