Merge pull request #202 from javascript-tutorial/sync-039716de

Sync with upstream @ 039716d

Author: odsantos

1-js/01-getting-started/1-intro/article.md

@@ -109,8 +109,9 @@ Exemplos de tais linguagens:
 - [CoffeeScript](http://coffeescript.org/) é um "açúcar sintático" para JavaScript. Ele introduz uma sintaxe mais curta, permitindo-nos escrever um código mais claro e preciso. Normalmente, Ruby devs gostam dele.
 - [TypeScript](http://www.typescriptlang.org/) está concentrado em adicionar "estritos tipos de dados" para simplificar o desenvolvimento e suporte de sistemas complexos. É desenvolvido pela Microsoft.
 - [Flow](http://flow.org/) também adiciona tipos de dados, mas de uma forma diferente. Desenvolvido pela Facebook.
-- [Dart](https://www.dartlang.org/) é uma linguagem autônoma que tem seu próprio interpretador que roda em ambientes fora do navegador (como aplicativos móveis), mas também pode ser transpilada para JavaScript. Desenvolvido pela Google.
+- [Dart](https://www.dartlang.org/) é uma linguagem autônoma que tem seu próprio interpretador que roda em ambientes fora do navegador (como aplicativos móveis), mas também pode ser transpilada para JavaScript. Desenvolvida pela Google.
 - [Brython](https://brython.info/) é um transpilador de Python para JavaScript que permite escrever aplicativos em puro Python, sem JavaScript.
+- [Kotlin](https://kotlinlang.org/docs/js-overview.html) é uma linguagem de programação moderna, concisa e segura, que pode ser usada no navegador ou no Node.
 
 Há mais. Claro que, mesmo que usemos uma dessas linguagens transpiladas, também devemos saber JavaScript para entender o que estamos fazendo.
 

1-js/04-object-basics/07-optional-chaining/article.md

@@ -219,4 +219,4 @@ As we can see, all of them are straightforward and simple to use. The `?.` check
 
 A chain of `?.` allows to safely access nested properties.
 
-Still, we should apply `?.` carefully, only where it's acceptable that the left part doesn't to exist. So that it won't hide programming errors from us, if they occur.
+Still, we should apply `?.` carefully, only where it's acceptable that the left part doesn't exist. So that it won't hide programming errors from us, if they occur.

1-js/05-data-types/02-number/article.md

@@ -16,7 +16,7 @@ Imagine we need to write 1 billion. The obvious way is:
 let billion = 1000000000;
 ```
 
-But in real life we usually avoid writing a long string of zeroes as it's easy to mistype. Also, we are lazy. We will usually write something like `"1bn"` for a billion or `"7.3bn"` for 7 billion 300 million. The same is true for most large numbers.
+But in real life, we usually avoid writing a long string of zeroes as it's easy to mistype. Also, we are lazy. We will usually write something like `"1bn"` for a billion or `"7.3bn"` for 7 billion 300 million. The same is true for most large numbers.
 
 In JavaScript, we shorten a number by appending the letter `"e"` to the number and specifying the zeroes count:
 
@@ -180,7 +180,7 @@ There are two ways to do so:
 
 ## Imprecise calculations
 
-Internally, a number is represented in 64-bit format [IEEE-754](http://en.wikipedia.org/wiki/IEEE_754-1985), so there are exactly 64 bits to store a number: 52 of them are used to store the digits, 11 of them store the position of the decimal point (they are zero for integer numbers), and 1 bit is for the sign.
+Internally, a number is represented in 64-bit format [IEEE-754](https://en.wikipedia.org/wiki/IEEE_754-2008_revision), so there are exactly 64 bits to store a number: 52 of them are used to store the digits, 11 of them store the position of the decimal point (they are zero for integer numbers), and 1 bit is for the sign.
 
 If a number is too big, it would overflow the 64-bit storage, potentially giving an infinity:
 
@@ -208,15 +208,15 @@ Ouch! There are more consequences than an incorrect comparison here. Imagine you
 
 But why does this happen?
 
-A number is stored in memory in its binary form, a sequence of ones and zeroes. But fractions like `0.1`, `0.2` that look simple in the decimal numeric system are actually unending fractions in their binary form.
+A number is stored in memory in its binary form, a sequence of bits - ones and zeroes. But fractions like `0.1`, `0.2` that look simple in the decimal numeric system are actually unending fractions in their binary form.
 
 In other words, what is `0.1`? It is one divided by ten `1/10`, one-tenth. In decimal numeral system such numbers are easily representable. Compare it to one-third: `1/3`. It becomes an endless fraction `0.33333(3)`.
 
 So, division by powers `10` is guaranteed to work well in the decimal system, but division by `3` is not. For the same reason, in the binary numeral system, the division by powers of `2` is guaranteed to work, but `1/10` becomes an endless binary fraction.
 
 There's just no way to store *exactly 0.1* or *exactly 0.2* using the binary system, just like there is no way to store one-third as a decimal fraction.
 
-The numeric format IEEE-754 solves this by rounding to the nearest possible number. These rounding rules normally don't allow us to see that "tiny precision loss", so the number shows up as `0.3`. But beware, the loss still exists.
+The numeric format IEEE-754 solves this by rounding to the nearest possible number. These rounding rules normally don't allow us to see that "tiny precision loss", but it exists.
 
 We can see this in action:
 ```js run
@@ -327,7 +327,7 @@ Please note that an empty or a space-only string is treated as `0` in all numeri
 There is a special built-in method [`Object.is`](mdn:js/Object/is) that compares values like `===`, but is more reliable for two edge cases:
 
 1. It works with `NaN`: `Object.is(NaN, NaN) === true`, that's a good thing.
-2. Values `0` and `-0` are different: `Object.is(0, -0) === false`, it rarely matters, but these values technically are different.
+2. Values `0` and `-0` are different: `Object.is(0, -0) === false`, technically that's true, because internally the number has a sign bit that may be different even if all other bits are zeroes.
 
 In all other cases, `Object.is(a, b)` is the same as `a === b`.
 
@@ -383,7 +383,7 @@ JavaScript has a built-in [Math](https://developer.mozilla.org/en/docs/Web/JavaS
 A few examples:
 
 `Math.random()`
-: Returns a random number from 0 to 1 (not including 1)
+: Returns a random number from 0 to 1 (not including 1).
 
     ```js run
     alert( Math.random() ); // 0.1234567894322
@@ -400,7 +400,7 @@ A few examples:
     ```
 
 `Math.pow(n, power)`
-: Returns `n` raised the given power
+: Returns `n` raised to the given power.
 
     ```js run
     alert( Math.pow(2, 10) ); // 2 in power 10 = 1024

1-js/05-data-types/06-iterable/article.md

@@ -3,9 +3,9 @@
 
 *Iterable* objects are a generalization of arrays. That's a concept that allows us to make any object useable in a `for..of` loop.
 
-Of course, Arrays are iterable. But there are many other built-in objects, that are iterable as well. For instance, Strings are iterable also. As we'll see, many built-in operators and methods rely on them.
+Of course, Arrays are iterable. But there are many other built-in objects, that are iterable as well. For instance, strings are also iterable.
 
-If an object represents a collection (list, set) of something, then `for..of` is a great syntax to loop over it, so let's see how to make it work.
+If an object isn't technically an array, but represents a collection (list, set) of something, then `for..of` is a great syntax to loop over it, so let's see how to make it work.
 
 
 ## Symbol.iterator
@@ -31,9 +31,9 @@ To make the `range` object iterable (and thus let `for..of` work) we need to add
 1. When `for..of` starts, it calls that method once (or errors if not found). The method must return an *iterator* -- an object with the method `next`.
 2. Onward, `for..of` works *only with that returned object*.
 3. When `for..of` wants the next value, it calls `next()` on that object.
-4. The result of `next()` must have the form `{done: Boolean, value: any}`, where `done=true`  means that the iteration is finished, otherwise `value` must be the new value.
+4. The result of `next()` must have the form `{done: Boolean, value: any}`, where `done=true`  means that the iteration is finished, otherwise `value` is the next value.
 
-Here's the full implementation for `range`:
+Here's the full implementation for `range` with remarks:
 
 ```js run
 let range = {
@@ -68,10 +68,10 @@ for (let num of range) {
 }
 ```
 
-Please note the core feature of iterables: an important separation of concerns:
+Please note the core feature of iterables: separation of concerns.
 
 - The `range` itself does not have the `next()` method.
-- Instead, another object, a so-called "iterator" is created by the call to `range[Symbol.iterator]()`, and it handles the whole iteration.
+- Instead, another object, a so-called "iterator" is created by the call to `range[Symbol.iterator]()`, and its `next()` generates values for the iteration.
 
 So, the iterator object is separate from the object it iterates over.
 
@@ -105,7 +105,7 @@ for (let num of range) {
 
 Now `range[Symbol.iterator]()` returns the `range` object itself:  it has the necessary `next()` method and remembers the current iteration progress in `this.current`. Shorter? Yes. And sometimes that's fine too.
 
-The downside is that now it's impossible to have two `for..of` loops running over the object simultaneously: they'll share the iteration state, because there's only one iterator -- the object itself. But two parallel for-ofs is a rare thing, doable with some async scenarios.
+The downside is that now it's impossible to have two `for..of` loops running over the object simultaneously: they'll share the iteration state, because there's only one iterator -- the object itself. But two parallel for-ofs is a rare thing, even in async scenarios.
 
 ```smart header="Infinite iterators"
 Infinite iterators are also possible. For instance, the `range` becomes infinite for `range.to = Infinity`. Or we can make an iterable object that generates an infinite sequence of pseudorandom numbers. Also can be useful.
@@ -174,7 +174,7 @@ When we use JavaScript for practical tasks in a browser or any other environment
 
 For instance, strings are both iterable (`for..of` works on them) and array-like (they have numeric indexes and `length`).
 
-But an iterable may not be array-like. And vice versa an array-like may not be iterable.
+But an iterable may be not array-like. And vice versa an array-like may be not iterable.
 
 For example, the `range` in the example above is iterable, but not array-like, because it does not have indexed properties and `length`.
 
@@ -193,11 +193,11 @@ for (let item of arrayLike) {}
 */!*
 ```
 
-What do they have in common? Both iterables and array-likes are usually *not arrays*, they don't have `push`, `pop` etc. That's rather inconvenient if we have such an object and want to work with it as with an array.
+Both iterables and array-likes are usually *not arrays*, they don't have `push`, `pop` etc. That's rather inconvenient if we have such an object and want to work with it as with an array. E.g. we would like to work with `range` using array methods. How to achieve that?
 
 ## Array.from
 
-There's a universal method [Array.from](mdn:js/Array/from) that brings them together. It takes an iterable or array-like value and makes a "real" `Array` from it. Then we can call array methods on it.
+There's a universal method [Array.from](mdn:js/Array/from) that takes an iterable or array-like value and makes a "real" `Array` from it. Then we can call array methods on it.
 
 For instance:
 
@@ -283,7 +283,7 @@ let str = '𝒳😂𩷶';
 
 alert( slice(str, 1, 3) ); // 😂𩷶
 
-// native method does not support surrogate pairs
+// the native method does not support surrogate pairs
 alert( str.slice(1, 3) ); // garbage (two pieces from different surrogate pairs)
 ```
 

1-js/06-advanced-functions/04-var/article.md

@@ -42,7 +42,19 @@ alert(test); // true, the variable lives after if
 */!*
 ```
 
-If we used `let test` on the 2nd line, then it wouldn't be visible to `alert`. But `var` ignores code blocks, so we've got a global `test`.
+As `var` ignores code blocks, we've got a global variable `test`.
+
+If we used `let test` instead of `var test`, then the variable would only be visible inside `if`:
+
+```js run
+if (true) {
+  let test = true; // use "let"
+}
+
+*!*
+alert(test); // ReferenceError: test is not defined
+*/!*
+```
 
 The same thing for loops: `var` cannot be block- or loop-local:
 
@@ -70,7 +82,7 @@ function sayHi() {
 }
 
 sayHi();
-alert(phrase); // Error: phrase is not defined
+alert(phrase); // ReferenceError: phrase is not defined
 ```
 
 As we can see, `var` pierces through `if`, `for` or other code blocks. That's because a long time ago in JavaScript, blocks had no Lexical Environments, and `var` is a remnant of that.
@@ -216,7 +228,7 @@ The Function Expression is wrapped with parenthesis `(function {...})`, because
 
 ```js run
 // Tries to declare and immediately call a function
-function() { // <-- Error: Function statements require a function name
+function() { // <-- SyntaxError: Function statements require a function name
 
   var message = "Hello";
 

1-js/11-async/07-microtask-queue/article.md

@@ -1,5 +1,5 @@
 
-# Microtasks and event loop
+# Microtasks
 
 Promise handlers `.then`/`.catch`/`.finally` are always asynchronous.
 
@@ -10,20 +10,20 @@ Here's a demo:
 ```js run
 let promise = Promise.resolve();
 
-promise.then(() => alert("promise done"));
+promise.then(() => alert("promise done!"));
 
 alert("code finished"); // this alert shows first
 ```
 
-If you run it, you see `code finished` first, and then `promise done`.
+If you run it, you see `code finished` first, and then `promise done!`.
 
 That's strange, because the promise is definitely done from the beginning.
 
 Why did the `.then` trigger afterwards? What's going on?
 
-# Microtasks
+## Microtasks queue
 
-Asynchronous tasks need proper management. For that, the ECMA standard specifies an internal queue `PromiseJobs`, more often referred to as the "microtask queue" (ES8 term).
+Asynchronous tasks need proper management. For that, the ECMA standard specifies an internal queue `PromiseJobs`, more often referred to as the "microtask queue" (V8 term).
 
 As stated in the [specification](https://tc39.github.io/ecma262/#sec-jobs-and-job-queues):
 
@@ -52,77 +52,6 @@ Promise.resolve()
 
 Now the order is as intended.
 
-## Event loop
-
-In-browser JavaScript, as well as Node.js, is based on an *event loop*.
-
-"Event loop" is a process when the engine sleeps and waits for events, then reacts on those and sleeps again.
-
-Examples of events:
-- `mousemove`, a user moved their mouse.
-- `setTimeout` handler is to be called.
-- an external `<script src="...">` is loaded, ready to be executed.
-- a network operation, e.g. `fetch` is complete.
-- ...etc.
-
-Things happen -- the engine handles them -- and waits for more to happen (while sleeping and consuming close to zero CPU).
-
-![](eventLoop.svg)
-
-As you can see, there's also a queue here. A so-called "macrotask queue" (v8 term).
-
-When an event happens, while the engine is busy, its handling is enqueued.
-
-For instance, while the engine is busy processing a network `fetch`, a user may move their mouse causing `mousemove`, and `setTimeout` may be due and so on, just as painted on the picture above.
-
-Events from the macrotask queue are processed on "first come – first served" basis. When the engine browser finishes with `fetch`, it handles `mousemove` event, then `setTimeout` handler, and so on.
-
-So far, quite simple, right? The engine is busy, so other tasks queue up.
-
-Now the important stuff.
-
-**Microtask queue has a higher priority than the macrotask queue.**
-
-In other words, the engine first executes all microtasks, and then takes a macrotask. Promise handling always has the priority.
-
-For instance, take a look:
-
-```js run
-setTimeout(() => alert("timeout"));
-
-Promise.resolve()
-  .then(() => alert("promise"));
-
-alert("code");
-```
-
-What's the order?
-
-1. `code` shows first, because it's a regular synchronous call.
-2. `promise` shows second, because `.then` passes through the microtask queue, and runs after the current code.
-3. `timeout` shows last, because it's a macrotask.
-
-It may happen that while handling a macrotask, new promises are created.
-
-Or, vice-versa, a microtask schedules a macrotask (e.g. `setTimeout`).
-
-For instance, here `.then` schedules a `setTimeout`:
-
-```js run
-Promise.resolve()
-  .then(() => {
-    setTimeout(() => alert("timeout"), 0);
-  })
-  .then(() => {
-    alert("promise");
-  });
-```
-
-Naturally, `promise` shows up first, because `setTimeout` macrotask awaits in the less-priority macrotask queue.
-
-As a logical consequence, macrotasks are handled only when promises give the engine a "free time". So if we have a promise chain that doesn't wait for anything, then things like `setTimeout` or event handlers can never get in the middle.
-
-
 ## Unhandled rejection
 
 Remember the `unhandledrejection` event from the article <info:promise-error-handling>?
@@ -131,34 +60,33 @@ Now we can see exactly how JavaScript finds out that there was an unhandled reje
 
 **An "unhandled rejection" occurs when a promise error is not handled at the end of the microtask queue.**
 
-For instance, consider this code:
+Normally, if we expect an error, we add `.catch` to the promise chain to handle it:
 
 ```js run
 let promise = Promise.reject(new Error("Promise Failed!"));
+*!*
+promise.catch(err => alert('caught'));
+*/!*
 
-window.addEventListener('unhandledrejection', event => {
-  alert(event.reason); // Promise Failed!
-});
+// doesn't run: error handled
+window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
 But if we forget to add `.catch`, then, after the microtask queue is empty, the engine triggers the event:
 
 ```js run
 let promise = Promise.reject(new Error("Promise Failed!"));
-*!*
-promise.catch(err => alert('caught'));
-*/!*
 
-// no error, all quiet
+// Promise Failed!
 window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
-Now let's say, we'll be catching the error, but after `setTimeout`:
+What if we handle the error later? Like this:
 
 ```js run
 let promise = Promise.reject(new Error("Promise Failed!"));
 *!*
-setTimeout(() => promise.catch(err => alert('caught')));
+setTimeout(() => promise.catch(err => alert('caught')), 1000);
 */!*
 
 // Error: Promise Failed!
@@ -173,16 +101,12 @@ But now we understand that `unhandledrejection` is generated when the microtask
 
 In the example above, `.catch` added by `setTimeout` also triggers. But it does so later, after `unhandledrejection` has already occurred, so it doesn't change anything.
 
-    **So, `.then/catch/finally` are called after the current code is finished.**
-
-    If we need to guarantee that a piece of code is executed after `.then/catch/finally`, it's best to add it into a chained `.then` call.
-
-- There's also a "macrotask queue" that keeps various events, network operation results, `setTimeout`-scheduled calls, and so on. These are also called "macrotasks" (v8 term).
+## Summary
 
-Promise handling is always asynchronous, as all promise actions pass through the internal "promise jobs" queue, also called "microtask queue" (ES8 term).
+Promise handling is always asynchronous, as all promise actions pass through the internal "promise jobs" queue, also called "microtask queue" (V8 term).
 
 So `.then/catch/finally` handlers are always called after the current code is finished.
 
-    In other words, they have lower priority.
+If we need to guarantee that a piece of code is executed after `.then/catch/finally`, we can add it into a chained `.then` call.
 
 In most Javascript engines, including browsers and Node.js, the concept of microtasks is closely tied with the "event loop" and "macrotasks". As these have no direct relation to promises, they are covered in another part of the tutorial, in the article <info:event-loop>.