diff options
Diffstat (limited to 'files/es/web/javascript/reference/global_objects/promise')
8 files changed, 1267 insertions, 0 deletions
diff --git a/files/es/web/javascript/reference/global_objects/promise/all/index.html b/files/es/web/javascript/reference/global_objects/promise/all/index.html new file mode 100644 index 0000000000..79a16aadc6 --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/all/index.html @@ -0,0 +1,123 @@ +--- +title: Promise.all() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/all +tags: + - ECMAScript6 + - JavaScript + - Método(2) + - Promesa + - Promise +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/all +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>Promise.all(iterable)</strong></code> devuelve una promesa que termina correctamente cuando todas las promesas en el argumento iterable han sido concluídas con éxito, o bien rechaza la petición con el motivo pasado por la primera promesa que es rechazada.</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox"><var>Promise.all(iterable)</var>;</pre> + +<dl> + <dt>iterable</dt> + <dd>Un objeto iterable, por ejemplo un {{jsxref("Array")}}. Vea <a href="/en-US/docs/Web/JavaScript/Guide/iterable">iterable</a>.</dd> +</dl> + +<h3 id="Valor_devuelto">Valor devuelto</h3> + +<p>Una {{jsxref("Promise")}} que se cumplirá cuando todas las promesas del argumento iterable hayan sido cumplidas, o bien se rechazará cuando alguna de ellas se rechace.</p> + +<h2 id="Descripción">Descripción</h2> + +<p><strong><code>Promise.all</code> </strong> se cumple cuando todas las promesas del iterable dado se han cumplido, o es rechazada si alguna promesa no se cumple. {{jsxref("Promise.resolve")}}.</p> + +<p>Si alguna de las promesas pasadas en el argumento iterable falla, la promesa <code>all</code> es rechazada inmediatamente con el valor de la promesa que fué rechazada, descartando todas las demás promesas hayan sido o no cumplidas. Si se pasa un array vacío a <code>all</code> , la promesa se cumple inmediatamente.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Uso_de_Promise.all">Uso de <code>Promise.all</code></h3> + +<p><code>Promise.all</code> espera a que todo se cumpla (o bien al primer rechazo).</p> + +<pre class="brush: js">var p1 = Promise.resolve(3); +var p2 = 1337; +var p3 = new Promise((resolve, reject) => { + setTimeout(resolve, 100, "foo"); +}); + +Promise.all([p1, p2, p3]).then(values => { + console.log(values); // [3, 1337, "foo"] +});</pre> + +<h3 id="Promise.all_comportamiento_de_fallo-rápido"><code>Promise.all</code> comportamiento de fallo-rápido</h3> + +<p><code>Promise.all</code> se rechaza si uno de los elementos ha sido rechazado y <code>Promise.all</code> falla rápido: Si tienes cuatro promesas que se resuelven después de un timeout y una de ellas falla inmediatamente, entonces <code>Promise.all</code> se rechaza inmediatamente.</p> + +<pre class="brush: js">var p1 = new Promise((resolve, reject) => { + setTimeout(resolve, 1000, "one"); +}); +var p2 = new Promise((resolve, reject) => { + setTimeout(resolve, 2000, "two"); +}); +var p3 = new Promise((resolve, reject) => { + setTimeout(resolve, 3000, "three"); +}); +var p4 = new Promise((resolve, reject) => { + setTimeout(resolve, 4000, "four"); +}); +var p5 = new Promise((resolve, reject) => { + reject("reject"); +}); + +Promise.all([p1, p2, p3, p4, p5]).then(values => { + console.log(values); +}, reason => { + console.log(reason) +}); + +//From console: +//"reject" + +// Evenly, it's possible to use .catch +Promise.all([p1, p2, p3, p4, p5]).then(values => { + console.log(values); +}).catch(reason => { + console.log(reason) +}); + +//From console: +//"reject" + +</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Status</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-promise.all', 'Promise.all')}}</td> + <td>{{Spec2('ES6')}}</td> + <td>Initial definition in an ECMA standard.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.all', 'Promise.all')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_entre_navegadores">Compatibilidad entre navegadores</h2> + +<p>{{Compat("javascript/promise","Promise.all")}}</p> + +<h2 id="Vea_también">Vea también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li>{{jsxref("Promise.race()")}}</li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/catch/index.html b/files/es/web/javascript/reference/global_objects/promise/catch/index.html new file mode 100644 index 0000000000..a99a071979 --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/catch/index.html @@ -0,0 +1,183 @@ +--- +title: Promise.prototype.catch() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/catch +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/catch +--- +<div>{{JSRef}}</div> + +<p>El método <strong>catch()</strong> retorna una <code>Promise</code> y solo se ejecuta en los casos en los que la promesa se marca como <code>Reject</code>. Se comporta igual que al llamar {{jsxref("Promise.then", "Promise.prototype.then(undefined, onRejected)")}} (de hecho, al llamar <code>obj.catch(onRejected)</code> internamente llama a <code>obj.then(undefined, onRejected)</code>).</p> + +<h2 id="Síntaxis">Síntaxis</h2> + +<pre class="syntaxbox"><var>p.catch(onRejected)</var>; + +p.catch(function(reason) { + // rejection +}); +</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt>onRejected</dt> + <dd>Una {{jsxref("Function")}} llamada cuando la <code>Promise</code> es rechazada. Esta función tiene un argumento: + <dl> + <dt><code>reason</code></dt> + <dd>La razón del rechazo.</dd> + </dl> + La promesa devuelta por <code>catch()</code> es rechazada si <code>onRejected</code> lanza un error o retorna una <code>Promise</code> que a su vez se rechaza, de cualquier otra manera la <code>Promise</code> es resuelta.</dd> +</dl> + +<h3 id="Valor_de_Retorno_(Return)">Valor de Retorno (Return)</h3> + +<p>Internamente llama a <code>Promise.prototype.then</code> en el objeto sobre el que se llama, pasándole el parámetro <code>undefined</code> y el manejador <code>onRejected</code> recibido; luego devuelve un valor de esa llamada (que es una {{jsxref("Promise")}}).</p> + +<p><strong>Demostración de la llamada interna:</strong></p> + +<pre class="brush: js">// overriding original Promise.prototype.then/catch just to add some logs +(function(Promise){ + var originalThen = Promise.prototype.then; + var originalCatch = Promise.prototype.catch; + + Promise.prototype.then = function(){ + console.log('> > > > > > called .then on %o with arguments: %o', this, arguments); + return originalThen.apply(this, arguments); + }; + Promise.prototype.catch = function(){ + console.log('> > > > > > called .catch on %o with arguments: %o', this, arguments); + return originalCatch.apply(this, arguments); + }; + +})(this.Promise); + + + +// calling catch on an already resolved promise +Promise.resolve().catch(function XXX(){}); + +// logs: +// > > > > > > called .catch on Promise{} with arguments: Arguments{1} [0: function XXX()] +// > > > > > > called .then on Promise{} with arguments: Arguments{2} [0: undefined, 1: function XXX()] +</pre> + +<h2 id="Descripción">Descripción</h2> + +<p>El método <code>catch</code> puede ser muy útil para el manejo de errores en tu código con promesas.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Usando_y_encadenando_el_método_catch">Usando y encadenando el método <code>catch</code></h3> + +<pre class="brush: js">var p1 = new Promise(function(resolve, reject) { + resolve('Success'); +}); + +p1.then(function(value) { + console.log(value); // "Success!" + throw 'oh, no!'; +}).catch(function(e) { + console.log(e); // "oh, no!" +}).then(function(){ + console.log('after a catch the chain is restored'); +}, function () { + console.log('Not fired due to the catch'); +}); + +// The following behaves the same as above +p1.then(function(value) { + console.log(value); // "Success!" + return Promise.reject('oh, no!'); +}).catch(function(e) { + console.log(e); // "oh, no!" +}).then(function(){ + console.log('after a catch the chain is restored'); +}, function () { + console.log('Not fired due to the catch'); +}); +</pre> + +<h3 id="Trucos_cuando_lanzamos_errores">Trucos cuando lanzamos errores</h3> + +<pre class="brush: js">// Hacer un throw llamará al método catch +var p1 = new Promise(function(resolve, reject) { + throw 'Uh-oh!'; +}); + +p1.catch(function(e) { + console.log(e); // "Uh-oh!" +}); + +// Los errores que se lancen dentro de funciones asíncronas actuarán como errores no capturados +var p2 = new Promise(function(resolve, reject) { + setTimeout(function() { + throw 'Uncaught Exception!'; + }, 1000); +}); + +p2.catch(function(e) { + console.log(e); // Nunca será llamado +}); + +// Errores lanzados después de resolve() serán omitidos +var p3 = new Promise(function(resolve, reject) { + resolve(); + throw 'Silenced Exception!'; +}); + +p3.catch(function(e) { + console.log(e); // Nunca será llamado +});</pre> + +<h3 id="Si_se_resuelve_la_promesa">Si se resuelve la promesa</h3> + +<pre class="brush: js">// Crea una promesa que no llamará a <code>onReject</code> +var p1 = Promise.resolve("calling next"); + +var p2 = p1.catch(function (reason) { + // Nunca será llamado + console.log("catch p1!"); + console.log(reason); +}); + +p2.then(function (value) { + console.log("next promise's onFulfilled"); /* next promise's onFulfilled */ + console.log(value); /* calling next */ +}, function (reason) { + console.log("next promise's onRejected"); + console.log(reason); +});</pre> + +<h2 id="Especificación">Especificación</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Definición inicial en el standar ECMA.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_de_navegadores">Compatibilidad de navegadores</h2> + +<p class="hidden">To contribute to this compatibility data, please write a pull request against this repository: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</p> + +<p>{{Compat("javascript.builtins.promise.catch")}}</p> + +<h2 id="Vea_también">Vea también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li>{{jsxref("Promise.prototype.then()")}}</li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/finally/index.html b/files/es/web/javascript/reference/global_objects/promise/finally/index.html new file mode 100644 index 0000000000..8d21aa785a --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/finally/index.html @@ -0,0 +1,95 @@ +--- +title: Promise.prototype.finally() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/finally +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/finally +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>finally()</strong></code> devuelve una {{jsxref("Promise")}}. Cuando la promesa se resuelve, sea exitosa o rechazada, la función de callback específicada será ejecutada. Esto ofrece una forma de ejecutar código sin importar como se haya resuelto la promesa.</p> + +<p>Esto ayuda a evitar tener código duplicado tanto en el {{jsxref("Promise.then", "then()")}} como en el {{jsxref("Promise.catch", "catch()")}}.</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox"><var>p.finally(alFinalizar)</var>; + +p.finally(function() { + // finalizada (exitosa o rechazada) +}); +</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt><code>alFinalizar</code></dt> + <dd>Una {{jsxref("Function")}} llamada cuando la <code>Promise</code> se resuelve con éxito o falla.</dd> +</dl> + +<h3 id="Valor_de_retorno">Valor de retorno</h3> + +<p>Devuelve una {{jsxref("Promise")}} cuyo <code>finally</code> fue fijado a la función específicada en <code>alFinalizar</code>.</p> + +<h2 id="Descripción">Descripción</h2> + +<p>El método <code>finally()</code> puede ser de utilidad si quieres hacer algún proceso o limpieza una vez que la promesa termina, sin importar su resultado.</p> + +<p>Utilizar <code>finally()</code> es muy similar a llamar <code>.then(onFinally, onFinally)</code>, sin embargo tiene algunas diferencias:</p> + +<ul> + <li>Cuando usamos una función <code>inline</code>, se la puede pasar una sola vez, en vez de estar forzado a declararla dos veces, o guardarla en una variable.</li> + <li>Un callback <code>finally</code> no recibe ningún argumento, ya que no hay una manera fehaciente de determinar si la promesa fue exitosa o fallida. Este caso de uso es precisamente para cuando <em>no nos importa</em> la razón por la que falló o el valor al que resuelve, y no hay necesidad de proveerlos.</li> + <li>A diferencia de <code>Promise.resolve(2).then(() => {}, () => {})</code> (que va a resolver a <code>undefined</code>), <code>Promise.resolve(2).finally(() => {})</code> resolverá con un <code>2</code>.</li> + <li>Del mismo modo, a diferencia de <code>Promise.reject(3).then(() => {}, () => {})</code> (que resolverá con <code>undefined</code>), <code>Promise.reject(3).finally(() => {})</code> será rechazada con un <code>3</code>.</li> +</ul> + +<div class="note"> +<p><strong>Nota:</strong> Un <code>throw</code> (o retornar una promesa rechazada) en el callback <code>finally</code> va a rechazar la nueva promesa con la razón de rechazo especificada al llamar <code>throw()</code>.</p> +</div> + +<h2 id="Ejemplos">Ejemplos</h2> + +<pre class="brush: js">let isLoading = true; + +fetch(myRequest).then(function(response) { + var contentType = response.headers.get("content-type"); + if(contentType && contentType.includes("application/json")) { + return response.json(); + } + throw new TypeError("Oops, no hemos obtenido un JSON!"); + }) + .then(function(json) { /* procesar el JSON */ }) + .catch(function(error) { console.log(error); /* esta línea podría arrojar error, e.g. cuando console = {} */ }) + .finally(function() { isLoading = false; }); + +</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.prototype.finally', 'Promise.prototype.finally')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_en_navegador">Compatibilidad en navegador</h2> + +<p class="hidden">To contribute to this compatibility data, please write a pull request against this repository: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</p> + +<p>{{Compat("javascript.builtins.Promise.finally")}}</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li>{{jsxref("Promise.prototype.then()")}}</li> + <li>{{jsxref("Promise.prototype.catch()")}}</li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/index.html b/files/es/web/javascript/reference/global_objects/promise/index.html new file mode 100644 index 0000000000..58a2319c2f --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/index.html @@ -0,0 +1,222 @@ +--- +title: Promise +slug: Web/JavaScript/Referencia/Objetos_globales/Promise +tags: + - ECMAScript6 + - JavaScript + - Promesa + - Promise +translation_of: Web/JavaScript/Reference/Global_Objects/Promise +--- +<div>{{JSRef}}</div> + +<p>El objeto <strong><code>Promise</code></strong> (Promesa) es usado para computaciones asíncronas. Una promesa representa un valor que puede estar disponible ahora, en el futuro, o nunca.</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox notranslate">new Promise( /* ejecutor */ function(resolver, rechazar) { ... } );</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt>ejecutor</dt> + <dd>Una función con los argumentos <code>resolver</code> y <code>rechazar</code>. La función <code>ejecutor</code> es ejecutada inmediatamente por la implementación de la Promesa, pasándole las funciones <code>resolver</code> y <code>rechazar</code> (el ejecutor es llamado incluso antes de que el constructor de la <code>Promesa</code> devuelva el objeto creado). Las funciones <code>resolver</code> y <code>rechazar</code>, 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 <code>resolver</code> para resolver la promesa o la rechaza si ha ocurrido un error.<br> + Si un error es lanzado en la función ejecutor, la promesa es rechazada y el valor de retorno del ejecutor es rechazado.</dd> +</dl> + +<h2 id="Descripción">Descripción</h2> + +<p>Una <strong>Promesa</strong> 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 <em>promesa</em> de suministrar el valor en algún momento en el futuro.</p> + +<p>Una <code>Promesa</code> se encuentra en uno de los siguientes estados:</p> + +<ul> + <li><em>pendiente (pending)</em>: estado inicial, no cumplida o rechazada.</li> + <li><em>cumplida (fulfilled)</em>: significa que la operación se completó satisfactoriamente.</li> + <li><em>rechazada (rejected)</em>: significa que la operación falló.</li> +</ul> + +<p>Una promesa pendiente puede ser <em>cumplida</em> con un valor, o <em>rechazada</em> con una razón (error). Cuando cualquiera de estas dos opciones sucede, los métodos asociados, encolados por el método <em>then</em> 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)</p> + +<p>Como los métodos <code>{{jsxref("Promise.then", "Promise.prototype.then()")}}</code> y <code>{{jsxref("Promise.catch", "Promise.prototype.catch()")}}</code> retornan promesas, éstas pueden ser encadenadas.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/8633/promises.png"></p> + +<div class="note"> +<p><strong>No confundir con:</strong> 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 <a href="/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">flecha </a> (arrow function) sin argumentos: <code>f = () => <em>expresión</em></code> para crear la expresión evaluada perezosamente, y <code>f()</code> para evaluar.</p> +</div> + +<div class="note" id="settledNote"> +<p><strong>Nota</strong>: Una promesa se dice que está <em>determinada (settled)</em> si se ha cumplido o si se ha rechazado, pero no está pendiente. Con promesas también se usa el término <em>resuelta</em> — esto significa que la promesa está determinada, o que se encuentra bloqueada dentro de una cadena de promesas. <a href="https://github.com/domenic/promises-unwrapping/blob/master/docs/states-and-fates.md">States and fates</a> de Domenic Denicola contiene mas detalles sobre la terminología de las promesas.</p> +</div> + +<h2 id="Propiedades">Propiedades</h2> + +<dl> + <dt><code>Promise.length</code></dt> + <dd>Propiedad longitud cuyo valor es siempre 1 (numero de argumentos del constructor).</dd> + <dt>{{jsxref("Promise.prototype")}}</dt> + <dd>Representa el prototipo del constructor <code>Promise</code>.</dd> +</dl> + +<h2 id="Métodos">Métodos</h2> + +<dl> + <dt>{{jsxref("Promise.all", "Promise.all(iterable)")}}</dt> + <dd>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</dd> + <dt>{{jsxref("Promise.race", "Promise.race(iterable)")}}</dt> + <dd>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.</dd> +</dl> + +<dl> + <dt>{{jsxref("Promise.reject", "Promise.reject(reason)")}}</dt> + <dd>Devuelve un objeto <code>Promise</code> que es rechazado con la razón dada.</dd> +</dl> + +<dl> + <dt>{{jsxref("Promise.resolve", "Promise.resolve(value)")}}</dt> + <dd>Devuelve un objeto <code>Promise</code> que es resuelto con el valor dado. Si el valor es un <em>thenable</em> (p.ej. tiene un método <code>then</code>), 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 - {{jsxref("Promise.resolve", "Promise.resolve(value)")}} y trabajar con el valor devuelto como una promesa.</dd> +</dl> + +<h2 id="Prototipo_Promise">Prototipo <code>Promise</code></h2> + +<h3 id="Propiedades_2">Propiedades</h3> + +<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Properties')}}</p> + +<h3 id="Métodos_2">Métodos</h3> + +<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Methods')}}</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Súper_simple_¡10_líneas!">Súper simple (¡10 líneas!)</h3> + +<pre class="brush: js notranslate"><code>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); +});</code></pre> + +<h3 id="Creando_una_Promise">Creando una Promise</h3> + +<p>Este pequeño ejemplo muestra el mecanismo de una <code>Promise</code>. El método <code>testPromise()</code> se llama cada vez que se pulsa el {{HTMLElement("button")}}. Esto crea una promesa que se cumplirá, aplicando {{domxref("window.setTimeout()")}}, al contador de la promesa (partiendo desde 1) aleatoriamente cada 1-3 segundos. El constructor de la Promise() es usado para crear dicha promesa.</p> + +<p>El cumplimiento de la promesa simplemente se registra, a través de una llamada de retorno al cumplirse utilizando {{jsxref("Promise.prototype.then()","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.</p> + +<pre class="brush: js notranslate">'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/>'); +} +</pre> + +<pre class="brush:js hidden notranslate">if ("Promise" in window) { + var btn = document.getElementById("btn"); + btn.addEventListener("click",testPromise); +} else { + log = document.getElementById('log'); + log.innerHTML = "El ejemplo en vivo no está disponible ya que tu navegador no soporta la interfaz <code>Promise<code>."; +} +</pre> + +<p>Este ejemplo es ejecutado cuando pulsas el botón. Necesitas un navegador que soporte <code>Promise</code>. Al pulsar el botón varias veces en un período corto de tiempo, verás las diferentes promesas siendo cumplidas una tras otra.</p> + +<p>{{EmbedLiveSample("Creando_una_Promise", "500", "200")}}</p> + +<h2 id="Cargando_una_imagen_con_XHR">Cargando una imagen con XHR</h2> + +<p>Otro ejemplo sencillo utilizando <code>Promise</code> y <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> para cargar una imagen está disponible en el repositorio <a href="https://github.com/mdn/js-examples/tree/master/promises-test">js-examples</a> de MDN en GitHub. También puedes <a href="https://mdn.github.io/js-examples/promises-test/">verlo en acción</a>. Cada paso está comentado y te permite seguir de cerca la arquitectura detrás de las Promesas y XHR.</p> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise-objects', 'Promise')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Initial definition in an ECMA standard.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise-objects', 'Promise')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_de_navegadores">Compatibilidad de navegadores</h2> + +<p class="hidden">To contribute to this compatibility data, please write a pull request against this file: <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/promise.json">https://github.com/mdn/browser-compat-data/blob/master/javascript/promise.json</a>.</p> + +<p>{{Compat("javascript/promise")}}</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li><a href="http://promisesaplus.com/">Promises/A+ specification</a></li> + <li><a href="https://medium.com/@ramsunvtech/promises-of-promise-part-1-53f769245a53">Venkatraman.R - JS Promise (Part 1, Basics)</a></li> + <li><a href="https://medium.com/@ramsunvtech/js-promise-part-2-q-js-when-js-and-rsvp-js-af596232525c#.dzlqh6ski">Venkatraman.R - JS Promise (Part 2 - Using Q.js, When.js and RSVP.js)</a></li> + <li><a href="http://www.html5rocks.com/en/tutorials/es6/promises/">Jake Archibald: JavaScript Promises: There and Back Again</a></li> + <li><a href="http://de.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript">Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Patterns in JavaScript</a></li> + <li><a href="http://www.mattgreer.org/articles/promises-in-wicked-detail/">Matt Greer: JavaScript Promises ... In Wicked Detail</a></li> + <li><a href="https://www.promisejs.org/">Forbes Lindesay: promisejs.org</a></li> + <li><a href="http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html">Nolan Lawson: We have a problem with promises — Common mistakes with promises</a></li> + <li><a href="https://github.com/jakearchibald/es6-promise/">Promise polyfill</a></li> + <li><a href="https://www.udacity.com/course/javascript-promises--ud898">Udacity: JavaScript Promises</a></li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/race/index.html b/files/es/web/javascript/reference/global_objects/promise/race/index.html new file mode 100644 index 0000000000..f24be82a9c --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/race/index.html @@ -0,0 +1,112 @@ +--- +title: Promise.race() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/race +tags: + - ECMAScript2015 + - ECMAScript6 + - JavaScript + - Promesa + - metodo +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/race +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>Promise.race(iterable)</strong></code> retorna una promesa que se cumplirá o no tan pronto como una de las promesas del argumento iterable se cumpla o se rechace, con el valor o razón de rechazo de ésta.</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox"><var>Promise.race(iterable)</var>;</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt>iterable</dt> + <dd>Un objeto iterable , como por ejemplo un {{jsxref("Array")}}. Vea <a href="/en-US/docs/Web/JavaScript/Guide/iterable">iterable</a>.</dd> +</dl> + +<h3 id="Retorna">Retorna</h3> + +<p>Una {{jsxref("Promise")}} que se cumple o se rechaza tan pronto como una de las promesas dadas en el argumento iterable se cumple o se rechaza.</p> + +<h2 id="Descripción">Descripción</h2> + +<p>La función <code>race</code> retorna una <code>Promise</code> que se comporta como tal. Se cumple o se rechaza, lo que suceda antes en alguno de sus argumentos (iterable).</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Usando_Promise.race_–_ejemplos_con_setTimeout">Usando <code>Promise.race</code> – ejemplos con <code>setTimeout</code></h3> + +<pre class="brush: js">var p1 = new Promise( (resolve, reject) => { + setTimeout(resolve, 500, "uno"); +}); +var p2 = new Promise( (resolve, reject) => { + setTimeout(resolve, 100, "dos"); +}); + +Promise.race([p1, p2]).then( value => { + console.log(value); // "dos" + // Ambas se resuelven, pero la p2 antes. +}); + + // Ejemplo con un resolve y un reject en el mismo método race. +var p3 = new Promise( (resolve, reject) => { + setTimeout(resolve, 100, "tres"); +}); +var p4 = new Promise( (resolve, reject) => { + setTimeout(reject, 500, "cuatro"); +}); + +Promise.race([p3, p4]).then( value => { + console.log(value); // "tres" + // p3 es mas rápida, así que se resuelve el race +}, reason => { + // No es llamado +}); + +var p5 = new Promise( (resolve, reject) => { + setTimeout(resolve, 500, "cinoc"); +}); +var p6 = new Promise( (resolve, reject) => { + setTimeout(reject, 100, "seis"); +}); + +Promise.race([p5, p6]).then( value => { + // No es llamado +}, reason => { + console.log(reason); // "seis" + // p6 es mas rápida, así que se rechaza +}); +</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Status</th> + <th scope="col">Comentar</th> + </tr> + <tr> + <td>{{SpecName('ES6', '#sec-promise.race', 'Promise.race')}}</td> + <td>{{Spec2('ES6')}}</td> + <td>Initial definition in an ECMA standard.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.race', 'Promise.race')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_entre_navegadores">Compatibilidad entre navegadores</h2> + +<p>{{Compat}}</p> + +<h2 id="Vea_también">Vea también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li>{{jsxref("Promise.all()")}}</li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/reject/index.html b/files/es/web/javascript/reference/global_objects/promise/reject/index.html new file mode 100644 index 0000000000..70505d7471 --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/reject/index.html @@ -0,0 +1,80 @@ +--- +title: Promise.reject() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/reject +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/reject +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>Promise.reject(reason)</strong></code> retorna un objeto <code>Promise</code> que es rechazado por la razón específicada.</p> + +<div>{{EmbedInteractiveExample("pages/js/promise-reject.html")}}</div> + +<p class="hidden"><span class="tlid-translation translation" lang="es"><span title="">La fuente de este ejemplo interactivo se almacena en un repositorio de GitHub.</span> <span title="">Si desea contribuir al proyecto de ejemplos interactivos, clone https://github.com/mdn/interactive-examples y envíenos una solicitud de extracción.</span></span></p> + +<p class="hidden"><span class="tlid-translation translation" lang="es"><span title="">La fuente de este ejemplo interactivo se almacena en un repositorio de GitHub.</span> <span title="">Si desea contribuir al proyecto de ejemplos interactivos, clone https://github.com/mdn/interactive-examples y envíenos una solicitud de extracción.</span></span></p> + +<p class="hidden"><span class="tlid-translation translation" lang="es"><span title="">La fuente de este ejemplo interactivo se almacena en un repositorio de GitHub.</span> <span title="">Si desea contribuir al proyecto de ejemplos interactivos, clone https://github.com/mdn/interactive-examples y envíenos una solicitud de extracción.</span></span></p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox"><var>Promise.reject(reason)</var>;</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt>reason</dt> + <dd>Razón por la cual esta {jsxref("Promise")}} fue rechazada.</dd> +</dl> + +<h3 id="Return_value">Return value</h3> + +<p>Un objeto {{jsxref("Promise")}} que es rechazado por la razón específicada.</p> + +<h2 id="Descripción">Descripción</h2> + +<p>La función estática <code>Promise.reject</code> retorna un objecto {{jsxref("Promise")}} que es rechazado. Para fines de depuración y captura selectiva de error, se suele pasar por el parámetro <code>reason</code> un <code>instanceof</code> {{jsxref("Error")}}.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Usando_el_método_estático_Promise.reject">Usando el método estático Promise.reject()</h3> + +<pre class="brush: js">Promise.reject(new Error('fail')).then(function() { + // no entra en esta función +}, function(error) { + console.log(error); // Stacktrace +});</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Specification</th> + <th scope="col">Status</th> + <th scope="col">Comment</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise.reject', 'Promise.reject')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Initial definition in an ECMA standard.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.reject', 'Promise.reject')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">To contribute to this compatibility data, please write a pull request against this repository: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</p> + +<p>{{Compat("javascript.builtins.Promise.reject")}}</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li><a href="https://github.com/petkaantonov/bluebird#error-handling">Selective error catching using the BlueBird Promise library</a></li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/resolve/index.html b/files/es/web/javascript/reference/global_objects/promise/resolve/index.html new file mode 100644 index 0000000000..e91dc7b80d --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/resolve/index.html @@ -0,0 +1,150 @@ +--- +title: Promise.resolve() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/resolve +tags: + - ECMAScript 2015 + - JavaScript + - Promise + - metodo +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/resolve +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>Promise.resolve(value)</strong></code> retorna un objeto {{jsxref("Promise")}} que es resuelto con el valor dado. Si el valor es una <em>promise</em>, esa <em>promise </em>es devuelta; si el valor es un <em>thenable </em>(si tiene un {{jsxref("Promise.then", "método \"then\"")}}), el valor devuelto le seguirá a ese <em>thenable</em>, adoptando su estado; de otro modo la <em>promise</em> devuelta estará completada con el valor.</p> + +<div>{{EmbedInteractiveExample("pages/js/promise-resolve.html")}}</div> + +<p class="hidden">La fuente para esta demostración interactiva se encuentra en un repositorio de GitHub. Si te gustaría contribuir al proyecto de la demostración interactiva, por favor clona <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> y envíanos una <em>pull request</em>.</p> + +<h2 id="Sintáxis">Sintáxis</h2> + +<pre class="brush: js">Promise.resolve(value); +Promise.resolve(promise); +Promise.resolve(thenable); +</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<dl> + <dt>value</dt> + <dd>Argumento por resolver por esta <code>Promise</code>. También puede ser una <code>Promise</code> o un <em>thenable</em> por resolver.</dd> +</dl> + +<h3 id="Valor_retornado">Valor retornado</h3> + +<p>Una {{jsxref("Promise")}} que es resuelta con el valor dado, o con la <em>promise </em>pasada como valor, si el valor era un objeto <em>promise</em>.</p> + +<h2 id="Descripción">Descripción</h2> + +<p>La función estática <code>Promise.resolve</code> retorna una <code>Promise</code> que es resuelta.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Utilizando_el_método_estático_Promise.resolve">Utilizando el método estático <code>Promise.resolve</code></h3> + +<pre class="brush: js">Promise.resolve('Éxito').then(function(value) { + console.log(value); // "Éxito" +}, function(value) { + // no es llamada +}); +</pre> + +<h3 id="Resolviendo_un_arreglo">Resolviendo un arreglo</h3> + +<pre class="brush: js">var p = Promise.resolve([1,2,3]); +p.then(function(v) { + console.log(v[0]); // 1 +});</pre> + +<h3 id="Resolviendo_otra_Promise">Resolviendo otra <code>Promise</code></h3> + +<pre class="brush: js">var original = Promise.resolve(33); +var cast = Promise.resolve(original); +cast.then(function(value) { + console.log('valor: ' + value); +}); +console.log('original === cast ? ' + (original === cast)); + +// registros, en orden: +// original === cast ? true +// valor: 33 +</pre> + +<p>El orden invertido de los registros se debe al hecho de que los <em>handler </em><code>then</code> sean llamados asíncronamente. Vea cómo funciona <code>then</code> <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then#Return_value">aquí</a>.</p> + +<h3 id="Resolviendo_thenables_y_arrojando_Errores">Resolviendo thenables y arrojando Errores</h3> + +<pre class="brush: js">// Resolviendo un objeto thenable +var p1 = Promise.resolve({ + then: function(onFulfill, onReject) { onFulfill('¡Completada!'); } +}); +console.log(p1 instanceof Promise) // true, objeto convertido en una Promise +j +p1.then(function(v) { + console.log(v); // "¡Completada!" + }, function(e) { + // no es llamada +}); + +// Thenable arroja antes del callback +// Rechaza la Promise +var thenable = { then: function(resolve) { + throw new TypeError('Arrojando'); + resolve('Resolviendo'); +}}; + +var p2 = Promise.resolve(thenable); +p2.then(function(v) { + // no es llamada +}, function(e) { + console.log(e); // TypeError: Arrojando +}); + +// Thenable arroja después del callback +// Resuelve la Promise +var thenable = { then: function(resolve) { + resolve('Resolviendo'); + throw new TypeError('Arrojando'); +}}; + +var p3 = Promise.resolve(thenable); +p3.then(function(v) { + console.log(v); // "Resolviendo" +}, function(e) { + // no es llamada +}); +</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise.resolve', 'Promise.resolve')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Definición inicial en un estándar de ECMA.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.resolve', 'Promise.resolve')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td> </td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_con_navegadores">Compatibilidad con navegadores</h2> + +<p class="hidden">Para contribuir a esta información de compatibilidad, porfavor haz una <em>pull request</em> contra este repositorio: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</p> + +<p>{{Compat("javascript.builtins.Promise.resolve")}}</p> + +<h2 id="Véase_también">Véase también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> +</ul> diff --git a/files/es/web/javascript/reference/global_objects/promise/then/index.html b/files/es/web/javascript/reference/global_objects/promise/then/index.html new file mode 100644 index 0000000000..8998f3b180 --- /dev/null +++ b/files/es/web/javascript/reference/global_objects/promise/then/index.html @@ -0,0 +1,302 @@ +--- +title: Promise.prototype.then() +slug: Web/JavaScript/Referencia/Objetos_globales/Promise/then +tags: + - ECMAScript 2015 + - JavaScript + - Method + - Promise + - Prototype +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/then +--- +<div>{{JSRef}}</div> + +<p>El método <code><strong>then()</strong></code> retorna una {{domxref("Promesa")}}. Recibe dos argumentos: funciones callback para los casos de éxito y fallo de <code><a href="/es/docs/Web/JavaScript/Referencia/Objetos_globales/Promise">Promise</a></code>.</p> + +<p>Nota: Si ambos argumentos son omitidos, o se proveen métodos que no sean funciones, se creará una nueva <code>Promesa</code> sin handlers adicionales, que simplemente adoptan el estado final de la <code>Promesa</code> que entonces es llamado. Si el primer argumento es omitido o se provee una no-función, el nuevo <code>Promise</code> que es creado simplemente adopta el estado cumplido del <code>Promise</code> que entonces es llamado (si se convierte en fulfilled). Si el segundo argument es omitido o se provee una no-función, el nuevo <code>Promise</code> que es creado simplemente adopta el estado de rechazo del <code>Promesa</code> que entonces es llamado (si se convierte en rechazado).</p> + +<h2 id="Sintaxis">Sintaxis</h2> + +<pre class="syntaxbox notranslate"><var>p.then(alCumplir[, enRechazo])</var>; + +p.then(function(value) { + // cumplimiento + }, function(reason) { + // rechazo +}); +</pre> + +<h3 id="Parámetros">Parámetros</h3> + +<p>Retorna un <code>Promise</code> el cual es determinado por las funciones input:</p> + +<ul> + <li>Si <font face="consolas, Liberation Mono, courier, monospace">alCumplir</font> o <code>enRechazo</code> arroja un error, o retorna un <code><a href="/es/docs/Web/JavaScript/Referencia/Objetos_globales/Promise">Promise</a></code> rechazado, <code>then</code> retorna un <code>Promise</code> rechazado.</li> + <li>Si <font face="consolas, Liberation Mono, courier, monospace">alCumplir</font> o <code>enRechazo</code> retorna un <code>Promise</code> que resuelve, o retorna cualquier otro valor, <code>then</code> retorna un <code>Promise </code>resuelto.</li> +</ul> + +<dl> + <dt><font face="consolas, Liberation Mono, courier, monospace">alCumplir </font>{{optional_inline}}</dt> + <dd>Una <a href="es/docs/Web/JavaScript/Referencia/Objetos_globales/Function">Función</a> es llamada si la <code>Promesa</code> se cumple. Esta función tiene un argumento, el <code>valor de</code> cumplimiento. Si no es una función, se reemplaza internamente con una función de "Identidad" (devuelve el argumento recibido).</dd> + <dt><code>enRechazo</code> {{optional_inline}}</dt> + <dd>Una <a href="es/docs/Web/JavaScript/Referencia/Objetos_globales/Function">Función</a> es llamada si la <code>Promesa </code>es rechazada. Esta función tiene un argumento, la <code>razón</code> de rechazo. Si no es una función, se reemplaza internamente con una función "Lanzador" (lanza un error que recibió como argumento).</dd> +</dl> + +<h3 id="Valor_de_retorno">Valor de retorno</h3> + +<p>Un <code><a href="/es/docs/Web/JavaScript/Referencia/Objetos_globales/Promise">Promise</a></code> en estado <strong>pendiente.</strong> La función de control (<code>alCumplir o enRechazo)</code> es llamada de forma <strong>asíncrona</strong> (tan pronto como el stack se vacíe). Después de la invocación de la función de control pueden darse diferentes casos:</p> + +<ul> + <li>Si se recibe un valor, la Promesa devuelta por el método <code>then</code> queda resuelta adoptando el valor de retorno.</li> + <li>Si se produce un error, la Promesa devuelta por el método <code>then</code> es rechazada, adoptando el error como su valor.</li> + <li>Si se devuelve una Promesa ya resuelta, la Promesa devuelta por el método <code>then</code> queda resuelta adoptando el valor de la promesa anterior.</li> + <li>Si se devuelve una Promesa con un objeto <strong>pendiente</strong> de resolver, la resolución o rechazo devueltos por <code>then</code> quedará a esperas de que la Promesa establecida para la función de control quede resuelta. Además, el valor de la Promesa en estado pendiente será el mismo que el valor devuelto por el controlador.</li> +</ul> + +<p>Veamos un ejemplo para demostrar la asincronía del método <code>then</code>.</p> + +<pre class="notranslate"><code>// al usar una promesa revuelta, el bloque 'then' se lanzará automáticamente, +// pero sus funciones controladoras se lanzarán asíncronamente, +// como demuestran los console.logs +var promResuelta = Promise.resolve(33); + +var thenProm = promResuelta.then(función(valor){ + console.log("ésto será invocado cuando acabe el stack principal. El valor recibido y devuelto es: " + valor); + return valor; +}); +// imprimimos al momento el valor de thenProm() +console.log(thenProm); + +// usando setTimeout podemos posponer la ejecución de una función al momento en el que el stack quede vacío. +setTimeout(función(){ + console.log(thenProm); +}); + + +// logs, en orden: +// Promise {[[EstadoPromise¡]]: "pendiente", [[ValorPromise]]: undefined} +// "ésto será invocado cuando acabe el stack principal. El valor recibido y devuelto es: "33" +// Promise {[[EstadoPromise]]: "resuelta", [[ValorPromise]]: 33}</code></pre> + +<h2 id="Descripción">Descripción</h2> + +<p>Ya que los métodos <code>then</code> y {{jsxref("Promise.prototype.catch()")}} devuelven promesas, pueden ser encadenados — una operación llamada <em>composición</em>.</p> + +<h2 id="Ejemplos">Ejemplos</h2> + +<h3 id="Usando_el_metodo_then">Usando el metodo <code>then</code></h3> + +<pre class="brush: js notranslate">var p1 = new Promise(function(resolve, reject) { + resolve('Success!'); + // or + // reject ("Error!"); +}); + +p1.then(function(value) { + console.log(value); // Success! +}, function(reason) { + console.log(reason); // Error! +}); +</pre> + +<h3 id="Encadenamiento">Encadenamiento</h3> + +<p>El método <code>then</code> devuelve una <code>Promise</code> que permite encadenar métodos.</p> + +<p>Puedes pasar una lambda a <code>then</code> y si devuelve una promesa, una <code>Promise</code> equivalente será expuesta al <code>then</code> subsecuente en la cadena de métodos. El fragmento incluido debajo simula un código asíncrono mediante la función <code>setTimeout</code>. </p> + +<pre class="brush: js notranslate">Promise.resolve('foo') + // 1. Recibe "foo", concatena "bar" con él, y resuelve la cadena con el siguiente 'then' + .then(función(hilo) { + return new Promise(function(resolve, reject) { + setTimeout(función() { + hilo += 'bar'; + resolve(hilo); + }, 1); + }); + }) + // 2. recibe "foobar", registra una función de llamada para opear sobre ese hilo + // e imprimirlo en la consola, pero no antes de devolver el hilo sin modificar + // en la resolución del siguiente 'then' + .then(función(hilo) { + setTimeout(función() { + hilo += 'baz'; + console.log(hilo); + }, 1) + return hilo; + }) + // 3. imprime mensajes útiles sobre cómo funcionará el código en esta sección + // antes de que el hilo se procese por el código de prueba + // antes del bloque 'then'. + .then(función(hilo) { + console.log("Último Then: oops... no me he molestado en instanciar y devolver " + + "una promesa en el then anterior, así que la secuencia puede ser un poco " + + "sorprendente"); + + // Observemos que `string` no incluye el trozo 'baz' en éste punto. Ésto ocurre + // porque lo hemos contruido para que ocurra asíncronamente con una función setTimeout + console.log(hilo); +});</pre> + +<p>Cuando un valor sencillamente se devuelve desde un lambda <code>then</code> , devolverá un <code>Promise.resolve(<valor devuelto por el controlador que haya sido invocado>)</code>.</p> + +<pre class="brush: js notranslate">var p2 = nueva Promise(function(resolver, rechazar) { + resolver(1); +}); + +p2.then(función(valor) { + console.log(valor); // 1 + return valor + 1; +}).then(function(value) { + console.log(valor + '- Este uso síncrono es prácticamente inútil'); // 2- Este uso síncrono es prácticamente inútil +}); + +p2.then(función(valor) { + console.log(valor); // 1 +}); +</pre> + +<p>Una llamada a <code>then</code> devolverá una promesa rechazada si la función lanza un error o devuelve una Promise rechazada.</p> + +<pre class="brush: js notranslate">Promise.resolve() + .then( () => { + // Hace que .then() devuelva una promera rechazada + throw new Error('Oh no!'); + }) + .then( () => { + console.log( 'No invocada.' ); + }, error => { + console.error( 'Función de rechazo llamada: ', error ); +});</pre> + +<p>En cualquier otro caso, una Promise en resolución será devuelta. El el siguiente ejemplo, el primer <code>then()</code> devolverá un <code>42</code> dentro de una Promise en resolución, aunque la Promise de la cadena fue rechazada.</p> + +<pre class="brush: js notranslate">Promise.reject() + .then( () => 99, () => 42 ) // enRechazo devuelve 42, que está dentro de una Promise en resolución + .then( respuesta => console.log( 'Resuelta con ' + respuesta ) ); // Resuelta con 42</pre> + +<p>En la práctica, suele ser preferible capturar promesas rechazadas en lugar de utilizar la sintaxis de dos casos de <code>then,</code> como demostramos abajo.</p> + +<pre class="brush: js notranslate">Promise.resolve() + .then( () => { + // Hace que .then() devuelva una promesa rechazada + throw new Error('Oh no!'); + }) + .catch( error => { + console.error( 'función enRechazo invocada: ', error ); + }) + .then( () => { + console.log( "Siempre soy invocada, incluso si la promesa del then previo es rechazada" ); + });</pre> + +<p><br> + También puedes usar encadenamiento para implementar una función con una API basada en promesas, sobre una función del mismo tipo.</p> + +<pre class="brush: js notranslate">function traer_datos_actuales() { + // La función <a href="/en-US/docs/Web/API/GlobalFetch/fetch">fetch</a>() de la API devuelve una Promesa. Esta función + // expone una API similar, pero el valor de cumplimiento + // de la Promesa de esta función tiene más tareas + // implementadas sobre ella. + return fetch('datos_actuales.json').then((response) => { + if (response.headers.get('content-type') != 'application/json') { + throw new TypeError(); + } + var j = response.json(); + // podríamos hacer algo con j + return j; // valor de cumplimiento asignado al usuario de + // fetch_datos_actuales().then() + }); +} +</pre> + +<p>Si <code>alCumplir</code> devuelve una promesa, el valor de retorno de <code>then</code> será resuelto o rechazado por la promesa.</p> + +<pre class="brush: js notranslate">function resolverDespues(resolver, reject) { + setTimeout(función () { + resolver(10); + }, 1000); +} +function rechazarDespues(resolver, reject) { + setTimeout(function () { + resolver(new Error('Error')); + }, 1000); +} + +var p1 = Promise.resolve('foo'); +var p2 = p1.then(función() { + // Devuelve la promesa aquí, que será resuelta igualada a 10 tras 1 segundo + return new Promise(resolverDespues); +}); +p2.then(función(v) { + console.log('resuelta', v); // "resuelta", 10 +}, función(e) { + // no invocada + console.log('rechazada', e); +}); + +var p3 = p1.then(funcion() { + // Devuelve la promesa aquí, que será rechazada con 'Error' despues de 1 segundo + return new Promise(rechazarDespues); +}); +p3.then(funcion(v) { + // no invocada + console.log('resuelta', v); +}, funcion(e) { + console.log('rechazada', e); // "rechazada", 'Error' +}); +</pre> + +<h3 id="window.setImmediate_estilo_polyfill_basado_en_promesas"><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate" title="This method is used to break up long running operations and run a callback function immediately after the browser has completed other operations such as events and display updates."><code>window.setImmediate</code></a> estilo polyfill basado en promesas</h3> + +<p>Usar un método {{jsxref("Function.prototype.bind()")}}<code>Reflect.apply</code> ({{jsxref("Reflect.apply()")}}) para crear un (non-cancellable) setImmediate-style function.</p> + +<pre class="notranslate">const nextTick = (() => { + const noop = () => {}; // literally + const nextTickPromise = () => Promise.resolve().then(noop); + + const rfab = Reflect.apply.bind; // (thisArg, fn, thisArg, [...args]) + const nextTick = (fn, ...args) => ( + fn !== undefined + ? Promise.resolve(args).then(rfab(null, fn, null)) + : nextTickPromise(), + undefined + ); + nextTick.ntp = nextTickPromise; + + return nextTick; +})();</pre> + +<h2 id="Especificaciones">Especificaciones</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificación</th> + <th scope="col">Estado</th> + <th scope="col">Comentario</th> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise.prototype.then', 'Promise.prototype.then')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Definición inicial en el estándar ECMA.</td> + </tr> + <tr> + <td>{{SpecName('ESDraft', '#sec-promise.prototype.then', 'Promise.prototype.then')}}</td> + <td>{{Spec2('ESDraft')}}</td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidad_en_navegador">Compatibilidad en navegador</h2> + +<p class="hidden">Para contribuir a la compatibilidad de estos datos, realiza una pull request sobre éste archivo: <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/promise.json">https://github.com/mdn/browser-compat-data/blob/master/javascript/promise.json</a>.</p> + +<p>{{Compat("javascript/promise","Promise.prototype.then")}}</p> + +<h2 id="Ver_también">Ver también</h2> + +<ul> + <li>{{jsxref("Promise")}}</li> + <li>{{jsxref("Promise.prototype.catch()")}}</li> +</ul> |