Merge pull request #503 from joaquinelio/promi

actualizacion promisify cierra #442

Author: joaquinelio

1-js/11-async/06-promisify/article.md

@@ -1,20 +1,20 @@
-# Promisification
+# Promisificación
 
-Promisification (Promisificación) -- es una palabra larga para una simple transformación. Es una conversión: de una función que acepta un callback a una función que retorna una promesa.
+"Promisificación" es una simple transformación. Es la conversión de una función que acepta un callback a una función que devuelve una promesa.
 
-En otras palabras, creamos una función de envoltura que realiza lo mismo, llamando a la original internamente, pero retornando una promesa.
+A menudo estas transformaciones son necesarias en la vida real ya que muchas funciones y librerías están basadas en callbacks, pero las promesas son más convenientes así que tiene sentido promisificarlas.
 
-Estas transformaciones son usualmente necesarias en la vida real, ya que muchas funciones y librerías están basadas en callbacks. Pero las promesas son mas convenientes, así que tiene sentido promisificar.
+Veamos un ejemplo.
 
-Por ejemplo, tenemos `loadScript(src, callback)` del capítulo <info:callbacks>.
+Aquí tenemos `loadScript(src, callback)` del artículo <info:callbacks>.
 
 ```js run
 function loadScript(src, callback) {
   let script = document.createElement('script');
   script.src = src;
 
   script.onload = () => callback(null, script);
-  script.onerror = () => callback(new Error(`Error de carga de script para ${src}`));
+  script.onerror = () => callback(new Error(`Error de carga de script ${src}`));
 
   document.head.append(script);
 }
@@ -23,9 +23,15 @@ function loadScript(src, callback) {
 // loadScript('path/script.js', (err, script) => {...})
 ```
 
-Vamos a promisificarla. La función nueva `loadScriptPromise(src)` va a hacer lo mismo, pero solo acepta `src` (sin callback) y retorna una promesa.
+La función carga un script con el `src` dado, y llama a `callback(err)` en caso de error o `callback(null, script)` en caso de carga exitosa. Esto está ampliamente acordado en el uso de callbacks, lo hemos visto antes.
 
-Aquí:
+Vamos a promisificarla. 
+
+Haremos una función nueva `loadScriptPromise(src)` que va a hacer lo mismo (carga el script), pero devuelve una promesa en vez de usar callbacks.
+
+Es decir: pasamos solamente `src` (sin `callback`) y obtenemos una promesa de vuelta, que resuelve con `script` cuando la carga fue exitosa y rechaza con error en caso contrario.
+
+Aquí está:
 ```js
 let loadScriptPromise = function(src) {
   return new Promise((resolve, reject) => {
@@ -40,21 +46,19 @@ let loadScriptPromise = function(src) {
 // loadScriptPromise('path/script.js').then(...)
 ```
 
-Ahora `loadScriptPromise` se ajusta bien a nuestro código basado en promesas.
+Como podemos ver, la nueva función es un "wrapper" (una función contenedora) que envuelve la función `loadScript` original. La llama proveyendo su propio callback y la traduce a una promesa `resolve/reject`.
 
-Como podemos ver, le delega todo el trabajo a la función `loadScript` original, proveyendo su propio callback que es traducido a promise `resolve/reject`.
+Ahora `loadScriptPromise` se adapta bien a un código basado en promesas. Si nos gustan más las promesas que los callbacks (y pronto veremos más motivos para ello), la usaremos en su lugar.
 
-Como vamos a tener que promisificar muchas funciones, tiene sentido usar un ayudante.
+En la práctica podemos necesitar promisificar más de una función, así que tiene sentido usar un ayudante.
 
-Esto es en realidad muy simple -- La función `promisify(f)` debajo toma una función `f` que sera promisificada y retorna una función de envoltura (wrapper function).
-
-Esa envoltura realiza lo mismo que el código de arriba: retorna una promesa y pasa el llamado a la `f` original, rastreando el resultado en un callback personalizado.
+Lo llamamos `promisify(f)`: esta acepta la función a promisificar `f` y devuelve una función contenedora (wrapper).
 
 ```js
 function promisify(f) {
-  return function (...args) { // retorna una función de envoltura
+  return function (...args) { // devuelve una función contenedora (*)
     return new Promise((resolve, reject) => {
-      function callback(err, result) { // nuestro callback personalizado para f
+      function callback(err, result) { // nuestro callback personalizado para f (**)
         if (err) {
           reject(err);
         } else {
@@ -74,11 +78,18 @@ let loadScriptPromise = promisify(loadScript);
 loadScriptPromise(...).then(...);
 ```
 
-Aquí asumimos que la función original espera un callback con dos argumentos `(err, result)`. Eso es lo que usualmente encontramos. Entonces nuestro callback personalizado está exactamente en el formato correcto, y `promisify` funciona muy bien para tal caso.
+El código puede verse complicado, pero es esencialmente lo mismo que escribimos arriba al promisificar la función `loadScript`.
+
+Una llamada a `promisify(f)` devuelve una función contenedora que envuelve a `f` `(*)`. Este contenedor devuelve una promesa y redirige el llamado a la `f` original, siguiendo el resultado en el callback personalizado `(**)`.
+
+Aquí `promisify` asume que la función original espera un callback con dos argumentos `(err, result)`. Eso es lo que usualmente encontramos. Entonces nuestro callback personalizado está exactamente en el formato correcto, y `promisify` funciona muy bien para tal caso.
 
 ¿Y si la `f` original espera un callback con más argumentos `callback(err, res1, res2)`?
 
-Aquí hay una modificación de `promisify` que retorna un array de los múltiples resultados del callback:
+Podemos mejorar el ayudante. Hagamos una versión de `promisify` más avanzada.
+
+- Cuando la llamamos como `promisify(f)`, debe funcionar igual que en la versión previa.
+- Cuando la llamamos como `promisify(f, true)`, debe devolver una promesa que resuelve con el array de resultados del callback. Esto es para callbacks con muchos argumentos.
 
 ```js
 // promisify(f, true) para conseguir array de resultados
@@ -89,7 +100,7 @@ function promisify(f, manyArgs = false) {
         if (err) {
           reject(err);
         } else {
-          // Retornar todos los resultados del callback si manyArgs es especificado
+          // Devolver todos los resultados del callback si "manyArgs" es especificado
           *!*resolve(manyArgs ? results : results[0]);*/!*
         }
       }
@@ -105,12 +116,15 @@ function promisify(f, manyArgs = false) {
 f = promisify(f, true);
 f(...).then(arrayOfResults => ..., err => ...);
 ```
-En algunos casos, puede que `err` esté ausente: `callback(result)`, o que haya algo que no es habitual en el formato del callback, por lo que tendremos que promisificar tales funciones manualmente.
+
+Como puedes ver es esencialmente lo mismo de antes, pero `resolve` es llamado con solo uno o con todos los argumentos dependiendo del valor de `manyArgs`. 
+
+Para formatos más exóticos de callback, como aquellos sin `err` en absoluto: `callback(result)`, podemos promisificarlos manualmente sin usar el ayudante.
 
 También hay módulos con funciones de promisificación un poco más flexibles, ej. [es6-promisify](https://github.com/digitaldesignlabs/es6-promisify). En Node.js, hay una función integrada `util.promisify` para ello.
 
 ```smart
-La promisificación es un excelente enfoque, especialmente cuando usas `async/await` (revisa el siguiente capítulo), pero no es totalmente un substituto para los callbacks.
+La promisificación es un excelente enfoque, especialmente cuando usas `async/await` (revisa el siguiente artículo), pero no es un substituto completo para los callbacks.
 
 Recuerda, una promesa puede tener sólo un resultado, pero un callback puede ser técnicamente llamado muchas veces.