Merge pull request #192 from javascript-tutorial/sync-dccca58f

odsantos · web-flow · commit 11d38138553c · 2020-11-02T17:08:50.000+01:00
Sync with upstream @ dccca58
diff --git a/1-js/03-code-quality/02-coding-style/article.md b/1-js/03-code-quality/02-coding-style/article.md
@@ -270,7 +270,7 @@ Se estiver a escrever várias funções "auxiliares" (*"helper" functions*) acom
     }
     ```
 
-3. Mista: uma função é declarada onde for empregue pela primeir vez.
+3. Mista: uma função é declarada onde for empregue pela primeira vez.
 
 A maior parte da vezes, a segunda variante é a preferida.
 
@@ -292,7 +292,7 @@ Algumas opções populares:
 - [StandardJS](https://standardjs.com/)
 - (e muitas mais)
 
-Se for um programador iniciante, começe pela cábula (*cheatsheet*) dísponivel no início deste capítulo. Depois, poderá procurar por outros guias de estilo afim de colher mais ideias e decidir qual prefere.
+Se for um programador iniciante, começe pela cábula (*cheatsheet*) disponível no início deste capítulo. Depois, poderá procurar por outros guias de estilo afim de colher mais ideias e decidir qual prefere.
 
 ## *Linters* Automatizados
 
@@ -329,8 +329,8 @@ Aqui está um exemplo de um ficheiro `.eslintrc`:
   },
   "rules": {
     "no-console": 0,
-  },
-  "indent": 2
+    "indent": 2
+  }
 }
 ```
 
diff --git a/1-js/03-code-quality/06-polyfills/article.md b/1-js/03-code-quality/06-polyfills/article.md
@@ -23,7 +23,8 @@ Actually, there are two parts in Babel:
 
 2. Second, the polyfill.
 
-    The transpiler rewrites the code, so syntax features are covered. But for new functions we need to write a special script that implements them. JavaScript is a highly dynamic language, scripts may not just add new functions, but also modify built-in ones, so that they behave according to the modern standard.
+    New language features may include not only syntax constructs, but also built-in functions.
+    The transpiler rewrites the code, transforming syntax constructs into older ones. But as for new built-in functions, we need to implement them. JavaScript is a highly dynamic language, scripts may add/modify any functions, so that they behave according to the modern standard.
 
     There's a term "polyfill" for scripts that "fill in" the gap and add missing implementations.
 
diff --git a/1-js/04-object-basics/03-garbage-collection/article.md b/1-js/04-object-basics/03-garbage-collection/article.md
@@ -23,7 +23,7 @@ Simply put, "reachable" values are those that are accessible or usable somehow.
 
 2. Any other value is considered reachable if it's reachable from a root by a reference or by a chain of references.
 
-    For instance, if there's an object in a global variable, and that object has a property referencing another object, that object is considered reachable. And those that it references are also reachable. Detailed examples to follow.
+    For instance, if there's an object in a global variable, and that object has a property referencing another object, *that* object is considered reachable. And those that it references are also reachable. Detailed examples to follow.
 
 There's a background process in the JavaScript engine that is called [garbage collector](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)). It monitors all objects and removes those that have become unreachable.
 
diff --git a/1-js/05-data-types/02-number/article.md b/1-js/05-data-types/02-number/article.md
@@ -406,7 +406,7 @@ A few examples:
     alert( Math.pow(2, 10) ); // 2 in power 10 = 1024
     ```
 
-There are more functions and constants in `Math` object, including trigonometry, which you can find in the [docs for the Math](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Math) object.
+There are more functions and constants in `Math` object, including trigonometry, which you can find in the [docs for the Math object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Math).
 
 ## Summary
 
diff --git a/1-js/05-data-types/08-weakmap-weakset/article.md b/1-js/05-data-types/08-weakmap-weakset/article.md
@@ -30,7 +30,8 @@ let array = [ john ];
 john = null; // overwrite the reference
 
 *!*
-// john is stored inside the array, so it won't be garbage-collected
+// the object previously referenced by john is stored inside the array 
+// therefore it won't be garbage-collected
 // we can get it as array[0]
 */!*
 ```
diff --git a/1-js/08-prototypes/01-prototype-inheritance/article.md b/1-js/08-prototypes/01-prototype-inheritance/article.md
@@ -12,7 +12,7 @@ In JavaScript, objects have a special hidden property `[[Prototype]]` (as named
 
 ![prototype](object-prototype-empty.svg)
 
-That `[[Prototype]]` has a "magical" meaning. When we want to read a property from `object`, and it's missing, JavaScript automatically takes it from the prototype. In programming, such thing is called "prototypal inheritance". Many cool language features and programming techniques are based on it.
+When we  read a property from `object`, and it's missing, JavaScript automatically takes it from the prototype. In programming, such thing is called "prototypal inheritance". And soon we'll study many examples of such inheritance, as well as cooler language features built upon it.
 
 The property `[[Prototype]]` is internal and hidden, but there are many ways to set it.
 
@@ -27,19 +27,11 @@ let rabbit = {
 };
 
 *!*
-rabbit.__proto__ = animal;
+rabbit.__proto__ = animal; // sets rabbit.[[Prototype]] = animal
 */!*
 ```
 
-```smart header="`__proto__` is a historical getter/setter for `[[Prototype]]`"
-Please note that `__proto__` is *not the same* as `[[Prototype]]`. It's a getter/setter for it.
-
-It exists for historical reasons. In modern language it is replaced with functions `Object.getPrototypeOf/Object.setPrototypeOf` that also get/set the prototype. We'll study the reasons for that and these functions later.
-
-By the specification, `__proto__` must only be supported by browsers, but in fact all environments including server-side support it. For now, as `__proto__` notation is a little bit more intuitively obvious, we'll use it in the examples.
-```
-
-If we look for a property in `rabbit`, and it's missing, JavaScript automatically takes it from `animal`.
+Now if we read a property from `rabbit`, and it's missing, JavaScript will automatically take it from `animal`.
 
 For instance:
 
@@ -131,13 +123,28 @@ alert(longEar.jumps); // true (from rabbit)
 
 ![](proto-animal-rabbit-chain.svg)
 
-There are actually only two limitations:
+Now if we read something from `longEar`, and it's missing, JavaScript will look for it in `rabbit`, and then in `animal`.
+
+There are only two limitations:
 
 1. The references can't go in circles. JavaScript will throw an error if we try to assign `__proto__` in a circle.
 2. The value of `__proto__` can be either an object or `null`, other types (like primitives) are ignored.
 
 Also it may be obvious, but still: there can be only one `[[Prototype]]`. An object may not inherit from two others.
 
+
+```smart header="`__proto__` is a historical getter/setter for `[[Prototype]]`"
+It's a common mistake of novice developers not to know the difference between these two. 
+
+Please note that `__proto__` is *not the same* as the internal `[[Prototype]]` property. It's a getter/setter for `[[Prototype]]`. Later we'll see situations where it matters,  for now let's just keep it in mind, as we build our understanding of JavaScript language.
+
+The `__proto__` property is a bit outdated. It exists for historical reasons, modern JavaScript suggests that we should use `Object.getPrototypeOf/Object.setPrototypeOf` functions instead that get/set the prototype. We'll also cover these functions later. 
+
+By the specification, `__proto__` must only be supported by browsers. In fact though, all environments including server-side support `__proto__`, so we're quite safe using it.
+
+As the `__proto__` notation is a bit more intuitively obvious, we use it in the examples.
+```
+
 ## Writing doesn't use prototype
 
 The prototype is only used for reading properties.
diff --git a/1-js/08-prototypes/04-prototype-methods/article.md b/1-js/08-prototypes/04-prototype-methods/article.md
@@ -175,8 +175,8 @@ alert(Object.keys(chineseDictionary)); // hello,bye
 Modern methods to set up and directly access the prototype are:
 
 - [Object.create(proto, [descriptors])](mdn:js/Object/create) -- creates an empty object with a given `proto` as `[[Prototype]]` (can be `null`) and optional property descriptors.
-- [Object.getPrototypeOf(obj)](mdn:js/Object.getPrototypeOf) -- returns the `[[Prototype]]` of `obj` (same as `__proto__` getter).
-- [Object.setPrototypeOf(obj, proto)](mdn:js/Object.setPrototypeOf) -- sets the `[[Prototype]]` of `obj` to `proto` (same as `__proto__` setter).
+- [Object.getPrototypeOf(obj)](mdn:js/Object/getPrototypeOf) -- returns the `[[Prototype]]` of `obj` (same as `__proto__` getter).
+- [Object.setPrototypeOf(obj, proto)](mdn:js/Object/setPrototypeOf) -- sets the `[[Prototype]]` of `obj` to `proto` (same as `__proto__` setter).
 
 The built-in `__proto__` getter/setter is unsafe if we'd want to put user-generated keys into an object. Just because a user may enter `"__proto__"` as the key, and there'll be an error, with hopefully light, but generally unpredictable consequences.
 
diff --git a/1-js/09-classes/01-class/1-rewrite-to-class/task.md b/1-js/09-classes/01-class/1-rewrite-to-class/task.md
@@ -4,6 +4,6 @@ importance: 5
 
 # Rewrite to class
 
-The `Clock` class is written in functional style. Rewrite it the "class" syntax.
+The `Clock` class (see the sandbox) is written in functional style. Rewrite it in the "class" syntax.
 
 P.S. The clock ticks in the console, open it to see.
diff --git a/1-js/09-classes/01-class/article.md b/1-js/09-classes/01-class/article.md
@@ -221,7 +221,7 @@ function makeClass(phrase) {
   return class {
     sayHi() {
       alert(phrase);
-    };
+    }
   };
 }
 
diff --git a/1-js/09-classes/02-class-inheritance/article.md b/1-js/09-classes/02-class-inheritance/article.md
@@ -76,8 +76,8 @@ For instance, a function call that generates the parent class:
 ```js run
 function f(phrase) {
   return class {
-    sayHi() { alert(phrase) }
-  }
+    sayHi() { alert(phrase); }
+  };
 }
 
 *!*
@@ -300,7 +300,7 @@ Consider this example:
 
 ```js run
 class Animal {
-  name = 'animal'
+  name = 'animal';
 
   constructor() {
     alert(this.name); // (*)
diff --git a/1-js/09-classes/06-instanceof/article.md b/1-js/09-classes/06-instanceof/article.md
@@ -2,7 +2,7 @@
 
 The `instanceof` operator allows to check whether an object belongs to a certain class. It also takes inheritance into account.
 
-Such a check may be necessary in many cases. Here we'll use it for building a *polymorphic* function, the one that treats arguments differently depending on their type.
+Such a check may be necessary in many cases. For example, it can be used for building a *polymorphic* function, the one that treats arguments differently depending on their type.
 
 ## The instanceof operator [#ref-instanceof]
 
diff --git a/1-js/11-async/06-promisify/article.md b/1-js/11-async/06-promisify/article.md
@@ -4,6 +4,8 @@
 
 Such transformations are often required in real-life, as many functions and libraries are callback-based. But promises are more convenient, so it makes sense to promisify them.
 
+For better understanding, let's see an example.
+
 For instance, we have `loadScript(src, callback)` from the chapter <info:callbacks>.
 
 ```js run
@@ -21,8 +23,15 @@ function loadScript(src, callback) {
 // loadScript('path/script.js', (err, script) => {...})
 ```
 
-Let's promisify it. The new `loadScriptPromise(src)` function achieves the same result, but it accepts only `src` (no `callback`) and returns a promise.
+The function loads a script with the given `src`, and then calls `callback(err)` in case of an error, or `callback(null, script)` in case of successful loading. That's a widespread agreement for using callbacks, we saw it before.
+
+Let's promisify it. 
+
+We'll make a new function `loadScriptPromise(src)`, that does the same (loads the script), but returns a promise instead of using callbacks.
+
+In other words, we pass it only `src` (no `callback`) and get a promise in return, that resolves with `script` when the load is successful, and rejects with the error otherwise.
 
+Here it is:
 ```js
 let loadScriptPromise = function(src) {
   return new Promise((resolve, reject) => {
@@ -37,19 +46,19 @@ let loadScriptPromise = function(src) {
 // loadScriptPromise('path/script.js').then(...)
 ```
 
-Now `loadScriptPromise` fits well in our promise-based code.
+As we can see, the new function is a wrapper around the original `loadScript` function. It calls it providing its own callback that translates to promise `resolve/reject`.
 
-As we can see, it delegates all the work to the original `loadScript`, providing its own callback that translates to promise `resolve/reject`.
+Now `loadScriptPromise` fits well in promise-based code. If we like promises more than callbacks (and soon we'll see more reasons for that), then we will use it instead.
 
-In practice we'll probably need to promisify many functions, so it makes sense to use a helper. We'll call it `promisify(f)`: it accepts a to-promisify function `f` and returns a wrapper function.
+In practice we may need to promisify more than one function, so it makes sense to use a helper. 
 
-That wrapper does the same as in the code above: returns a promise and passes the call to the original `f`, tracking the result in a custom callback:
+We'll call it `promisify(f)`: it accepts a to-promisify function `f` and returns a wrapper function.
 
 ```js
 function promisify(f) {
-  return function (...args) { // return a wrapper-function
+  return function (...args) { // return a wrapper-function (*)
     return new Promise((resolve, reject) => {
-      function callback(err, result) { // our custom callback for f
+      function callback(err, result) { // our custom callback for f (**)
         if (err) {
           reject(err);
         } else {
@@ -69,11 +78,18 @@ let loadScriptPromise = promisify(loadScript);
 loadScriptPromise(...).then(...);
 ```
 
-Here we assume that the original function expects a callback with two arguments `(err, result)`. That's what we encounter most often. Then our custom callback is in exactly the right format, and `promisify` works great for such a case.
+The code may look a bit complex, but it's essentially the same that we wrote above, while promisifying `loadScript` function.
+
+A call to `promisify(f)` returns a wrapper around `f` `(*)`. That wrapper returns a promise and forwards the call to the original `f`, tracking the result in the custom callback `(**)`.
+
+Here, `promisiefy` assumes that the original function expects a callback with exactly two arguments `(err, result)`. That's what we encounter most often. Then our custom callback is in exactly the right format, and `promisify` works great for such a case.
 
 But what if the original `f` expects a callback with more arguments `callback(err, res1, res2)`?
 
-Here's a modification of `promisify` that returns an array of multiple callback results:
+We can improve our helper. Let's make a more advanced version of `promisify`.
+
+- When called as `promisify(f)` it should work similar to the version above.
+- When called as `promisify(f, true)`, it should return the promise that resolves with the array of callback results. That's exactly for callbacks with many arguments.
 
 ```js
 // promisify(f, true) to get array of results
@@ -101,6 +117,8 @@ f = promisify(f, true);
 f(...).then(arrayOfResults => ..., err => ...)
 ```
 
+As you can see it's essentially the same as above, but `resolve` is called with only one or all arguments depending on whether `manyArgs` is truthy.
+
 For more exotic callback formats, like those without `err` at all: `callback(result)`, we can promisify such functions manually without using the helper.
 
 There are also modules with a bit more flexible promisification functions, e.g. [es6-promisify](https://github.com/digitaldesignlabs/es6-promisify). In Node.js, there's a built-in `util.promisify` function for that.
diff --git a/1-js/11-async/08-async-await/03-async-from-regular/task.md b/1-js/11-async/08-async-await/03-async-from-regular/task.md
@@ -1,7 +1,7 @@
 
 # Call async from non-async
 
-We have a "regular" function. How to call `async` from it and use its result?
+We have a "regular" function called `f`. How can you call the `async` function `wait()` and use its result inside of `f`?
 
 ```js
 async function wait() {
@@ -11,7 +11,7 @@ async function wait() {
 }
 
 function f() {
-  // ...what to write here?
+  // ...what should you write here?
   // we need to call async wait() and wait to get 10
   // remember, we can't use "await"
 }
diff --git a/1-js/13-modules/02-import-export/article.md b/1-js/13-modules/02-import-export/article.md
@@ -321,7 +321,7 @@ export {default as User} from './user.js'; // reexporta o default
 
 Por que isso seria necessário? Vamos ver um caso de uso prático.
 
-Imagine que estamos escrevendo um "pacote": uma pasta com muitos módulos, com algumas funcionalidades exportadas (ferramentas como NPM permitem publicar e distribuir esses pacotes), e muitos módulos são apenas "auxiliares", para uso interno em outro pacote de módulos.
+Imagine, we're writing a "package": a folder with a lot of modules, with some of the functionality exported outside (tools like NPM allow us to publish and distribute such packages, but we don't have to use them), and many modules are just "helpers", for internal use in other package modules.
 
 A estrutura de arquivos pode ser assim:
 ```
@@ -378,7 +378,7 @@ export {default as User} from './user.js';
 
 O export default precisa de um tratamento separado ao reexportar.
 
-Vamos dizer que temos `user.js` com o `export default class User`, e gostaríamos de o reexportar:
+Let's say we have `user.js` with the `export default class User` and would like to re-export it:
 
 ```js
 // 📁 user.js
@@ -387,7 +387,7 @@ export default class User {
 }
 ```
 
-Podemos encontrar dois problemas:
+We can come across two problems with it:
 
 1. `export User from './user.js'` não funcionará. Isso levaria a um erro de sintaxe.
 
@@ -401,7 +401,7 @@ Podemos encontrar dois problemas:
     export {default} from './user.js'; // para reexportar o export default
     ```
 
-Essas esquisitices de reexportar o export default são um dos motivos pelos quais alguns desenvolvedores não gostam de default exports e preferem os nomeados.
+Essas esquisitices de reexportar um default export são um dos motivos pelos quais alguns desenvolvedores não gostam de default exports e preferem os nomeados.
 
 ## Resumo
 
diff --git a/2-ui/5-loading/02-script-async-defer/article.md b/2-ui/5-loading/02-script-async-defer/article.md
@@ -83,7 +83,7 @@ Let's say, we have two deferred scripts: the `long.js` and then `small.js`:
 
 Browsers scan the page for scripts and download them in parallel, to improve performance. So in the example above both scripts download in parallel. The `small.js` probably finishes first.
 
-...But the `defer` atribute, besides telling the browser "not to block", ensures that the relative order is kept. So even though `small.js` loads first, it still waits and runs after `long.js` executes.
+...But the `defer` attribute, besides telling the browser "not to block", ensures that the relative order is kept. So even though `small.js` loads first, it still waits and runs after `long.js` executes.
 
 That may be important for cases when we need to load a JavaScript library and then a script that depends on it.
 
diff --git a/9-regular-expressions/17-regexp-methods/article.md b/9-regular-expressions/17-regexp-methods/article.md
@@ -4,7 +4,7 @@ Neste artigo, abordaremos vários métodos que funcionam com regexps em profundi
 
 ## str.match(regexp)
 
-O método `str.macth(regexp)` pesquisa correspondências para `regexp` na string `str`.
+O método `str.match(regexp)` pesquisa correspondências para `regexp` na string `str`.
 
 Possui 3 modos:
 
@@ -20,7 +20,7 @@ Possui 3 modos:
     alert( result.length ); // 2
 
     // Informação adicional:
-    alert( result.index );  // 0 (posição da correspondÊncia)
+    alert( result.index );  // 0 (posição da correspondência)
     alert( result.input );  // Eu amo JavaScript (string original)
     ```
 

Original file line number	Diff line number	Diff line change
`@@ -221,7 +221,7 @@ function makeClass(phrase) {`
`221`	`221`	`return class {`
`222`	`222`	`sayHi() {`
`223`	`223`	`alert(phrase);`
`224`		`- };`
	`224`	`+ }`
`225`	`225`	`};`
`226`	`226`	`}`
`227`	`227`