Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-db3b3f8e

Author: iliakan

1-js/02-first-steps/14-function-basics/article.md

@@ -266,7 +266,7 @@ There may be many occurrences of `return` in a single function. For instance:
 
 ```js run
 function checkAge(age) {
-  if (age > 18) {
+  if (age >= 18) {
 *!*
     return true;
 */!*

1-js/03-code-quality/01-debugging-chrome/article.md

@@ -4,7 +4,7 @@ Before writing more complex code, let's talk about debugging.
 
 [Debugging](https://en.wikipedia.org/wiki/Debugging) is the process of finding and fixing errors within a script. All modern browsers and most other environments support debugging tools -- a special UI in developer tools that makes debugging much easier. It also allows to trace the code step by step to see what exactly is going on.
 
-We'll be using Chrome here, because it has enough features, most other browsers have a similar process`.
+We'll be using Chrome here, because it has enough features, most other browsers have a similar process.
 
 ## The "Sources" panel
 
@@ -24,11 +24,11 @@ Let's click it and select `hello.js` in the tree view. Here's what should show u
 
 ![](chrome-tabs.svg)
 
-Here we can see three zones:
+The Sources panel has 3 parts:
 
-1. The **Resources zone** lists HTML, JavaScript, CSS and other files, including images that are attached to the page. Chrome extensions may appear here too.
-2. The **Source zone** shows the source code.
-3. The **Information and control zone** is for debugging, we'll explore it soon.
+1. The **File Navigator** pane lists HTML, JavaScript, CSS and other files, including images that are attached to the page. Chrome extensions may appear here too.
+2. The **Code Editor** pane shows the source code.
+3. The **JavaScript Debugging** pane is for debugging, we'll explore it soon.
 
 Now you could click the same toggler <span class="devtools" style="background-position:-172px -122px"></span> again to hide the resources list and give the code some space.
 

1-js/05-data-types/07-map-set/article.md

@@ -41,6 +41,12 @@ alert( map.size ); // 3
 
 As we can see, unlike objects, keys are not converted to strings. Any type of key is possible.
 
+```smart header="`map[key]` isn't the right way to use a `Map`"
+Although `map[key]` also works, e.g. we can set `map[key] = 2`, this is treating `map` as a plain JavaScript object, so it implies all corresponding limitations (no object keys and so on).
+
+So we should use `map` methods: `set`, `get` and so on.
+```
+
 **Map can also use objects as keys.**
 
 For instance:

1-js/07-object-properties/02-property-accessors/article.md

@@ -134,7 +134,7 @@ alert(user.fullName); // John Smith
 for(let key in user) alert(key); // name, surname
 ```
 
-Please note once again that a property can be either an accessor (has `get/set` methods) or a data property (has a `value`), not both.
+Please note that a property can be either an accessor (has `get/set` methods) or a data property (has a `value`), not both.
 
 If we try to supply both `get` and `value` in the same descriptor, there will be an error:
 

1-js/11-async/01-callbacks/article.md

@@ -109,7 +109,7 @@ loadScript('https://cdnjs.cloudflare.com/ajax/libs/lodash.js/3.2.0/lodash.js', s
 
 That's called a "callback-based" style of asynchronous programming. A function that does something asynchronously should provide a `callback` argument where we put the function to run after it's complete.
 
-Here we did it in `loadScript`, but of course, it's a general approach.
+Here we did it in `loadScript`, but of course it's a general approach.
 
 ## Callback in callback
 

1-js/11-async/02-promise-basics/article.md

@@ -31,9 +31,9 @@ When the executor obtains the result, be it soon or late - doesn't matter, it sh
 - `resolve(value)` — if the job finished successfully, with result `value`.
 - `reject(error)` — if an error occurred, `error` is the error object.
 
-So to summarize: the executor runs automatically, it should do a job, and then call either `resolve` or `reject`.
+So to summarize: the executor runs automatically and performs a job. Then it should call `resolve` if it was succssful or `reject` if there was an error.
 
-The `promise` object returned by `new Promise` constructor has internal properties:
+The `promise` object returned by the `new Promise` constructor has internal properties:
 
 - `state` — initially `"pending"`, then changes to either `"fulfilled"` when `resolve` is called or `"rejected"` when `reject` is called.
 - `result` — initially `undefined`, then changes to `value` when `resolve(value)` called or `error` when `reject(error)` is called.
@@ -58,7 +58,7 @@ let promise = new Promise(function(resolve, reject) {
 We can see two things by running the code above:
 
 1. The executor is called automatically and immediately (by `new Promise`).
-2. The executor receives two arguments: `resolve` and `reject` — these functions are pre-defined by the JavaScript engine. So we don't need to create them. We should only call one of them when ready.
+2. The executor receives two arguments: `resolve` and `reject`. These functions are pre-defined by the JavaScript engine, so we don't need to create them. We should only call one of them when ready.
 
     After one second of "processing" the executor calls `resolve("done")` to produce the result. This changes the state of the `promise` object:
 
@@ -79,7 +79,7 @@ The call to `reject(...)` moves the promise object to `"rejected"` state:
 
 ![](promise-reject-1.svg)
 
-To summarize, the executor should do a job (something that takes time usually) and then call `resolve` or `reject` to change the state of the corresponding promise object.
+To summarize, the executor should perform a job (usually something that takes time) and then call `resolve` or `reject` to change the state of the corresponding promise object.
 
 A promise that is either resolved or rejected is called "settled", as opposed to an initially "pending" promise.
 
@@ -166,7 +166,7 @@ promise.then(
 
 The first function was executed.
 
-And in the case of a rejection -- the second one:
+And in the case of a rejection, the second one:
 
 ```js run
 let promise = new Promise(function(resolve, reject) {
@@ -205,7 +205,7 @@ let promise = new Promise((resolve, reject) => {
 });
 
 *!*
-// .catch(f) is the same as .then(null, f)
+// .catch(f) is the same as promise.then(null, f)
 promise.catch(alert); // shows "Error: Whoops!" after 1 second
 */!*
 ```
@@ -255,7 +255,7 @@ It's not exactly an alias of `then(f,f)` though. There are several important dif
     })
       .finally(() => alert("Promise ready"))
       .catch(err => alert(err));  // <-- .catch handles the error object
-    ```  
+    ```
 
     That's very convenient, because `finally` is not meant to process a promise result. So it passes it through.
 
@@ -303,7 +303,7 @@ Let's rewrite it using Promises.
 The new function `loadScript` will not require a callback. Instead, it will create and return a Promise object that resolves when the loading is complete. The outer code can add handlers (subscribing functions) to it using `.then`:
 
 ```js run
-function loadScript(src) {  
+function loadScript(src) {
   return new Promise(function(resolve, reject) {
     let script = document.createElement('script');
     script.src = src;

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

@@ -3,9 +3,9 @@
 
 Promise handlers `.then`/`.catch`/`.finally` are always asynchronous.
 
-Even when a Promise is immediately resolved, the code on the lines *below* `.then`/`.catch`/`.finally` will still execute before these handlers .
+Even when a Promise is immediately resolved, the code on the lines *below* `.then`/`.catch`/`.finally` will still execute before these handlers.
 
-Here's the demo:
+Here's a demo:
 
 ```js run
 let promise = Promise.resolve();
@@ -23,22 +23,22 @@ Why did the `.then` trigger afterwards? What's going on?
 
 ## Microtasks queue
 
-Asynchronous tasks need proper management. For that, the standard specifies an internal queue `PromiseJobs`, more often referred to as "microtask queue" (v8 term).
+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).
 
-As said in the [specification](https://tc39.github.io/ecma262/#sec-jobs-and-job-queues):
+As stated in the [specification](https://tc39.github.io/ecma262/#sec-jobs-and-job-queues):
 
 - The queue is first-in-first-out: tasks enqueued first are run first.
 - Execution of a task is initiated only when nothing else is running.
 
-Or, to say that simply, when a promise is ready, its `.then/catch/finally` handlers are put into the queue. They are not executed yet. When the JavaScript engine becomes free from the current code, it takes a task from the queue and executes it.
+Or, to say more simply, when a promise is ready, its `.then/catch/finally` handlers are put into the queue; they are not executed yet. When the JavaScript engine becomes free from the current code, it takes a task from the queue and executes it.
 
 That's why "code finished" in the example above shows first.
 
 ![](promiseQueue.svg)
 
 Promise handlers always go through this internal queue.
 
-If there's a chain with multiple `.then/catch/finally`, then every one of them is executed asynchronously. That is, it first gets queued, and executed when the current code is complete and previously queued handlers are finished.
+If there's a chain with multiple `.then/catch/finally`, then every one of them is executed asynchronously. That is, it first gets queued, then executed when the current code is complete and previously queued handlers are finished.
 
 **What if the order matters for us? How can we make `code finished` run after `promise done`?**
 
@@ -58,7 +58,7 @@ Remember the `unhandledrejection` event from the chapter <info:promise-error-han
 
 Now we can see exactly how JavaScript finds out that there was an unhandled rejection.
 
-**"Unhandled rejection" occurs when a promise error is not handled at the end of the microtask queue.**
+**An "unhandled rejection" occurs when a promise error is not handled at the end of the microtask queue.**
 
 Normally, if we expect an error, we add `.catch` to the promise chain to handle it:
 
@@ -72,7 +72,7 @@ promise.catch(err => alert('caught'));
 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:
+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!"));
@@ -93,20 +93,20 @@ setTimeout(() => promise.catch(err => alert('caught')), 1000);
 window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
-Now, if you run it, we'll see `Promise Failed!` first and then `caught`. 
+Now, if we run it, we'll see `Promise Failed!` first and then `caught`.
 
-If we didn't know about the microtasks queue, we could wonder: "Why did `unhandledrejection` handler run? We did catch the error!".
+If we didn't know about the microtasks queue, we could wonder: "Why did `unhandledrejection` handler run? We did catch and handle the error!"
 
-But now we understand that `unhandledrejection` is generated when the microtask queue is complete: the engine examines promises and, if any of them is in "rejected" state, then the event triggers.
+But now we understand that `unhandledrejection` is generated when the microtask queue is complete: the engine examines promises and, if any of them is in the "rejected" state, then the event triggers.
 
-In the example above, `.catch` added by `setTimeout` also triggers, but later, after `unhandledrejection` has already occurred, so that doesn't change anything.
+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.
 
 ## Summary
 
-Promise handling is always asynchronous, as all promise actions pass through the internal "promise jobs" queue, also called "microtask queue" (v8 term).
+Promise handling is always asynchronous, as all promise actions pass through the internal "promise jobs" queue, also called "microtask queue" (ES8 term).
 
-So, `.then/catch/finally` handlers are always called after the current code is finished.
+So `.then/catch/finally` handlers are always called after the current code is finished.
 
 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 "event loop" and "macrotasks". As these have no direct relation to promises, they are covered in another part of the tutorial, in the chapter <info:event-loop>.
+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 chapter <info:event-loop>.

1-js/99-js-misc/05-bigint/article.md

@@ -45,7 +45,7 @@ alert(bigint + BigInt(number)); // 3
 alert(Number(bigint) + number); // 3
 ```
 
-The conversion of bigint to number is always silent, but if the bigint is too huge and won't fit the number type, then extra bits will be cut off, causing a precision loss.
+The conversion operations are always silent, never give errors, but if the bigint is too huge and won't fit the number type, then extra bits will be cut off, so we should be careful doing such conversion.
 
 ````smart header="The unary plus is not supported on bigints"
 The unary plus operator `+value` is a well-known way to convert `value` to a number.
@@ -69,7 +69,7 @@ alert( 2n > 1n ); // true
 alert( 2n > 1 ); // true
 ```
 
-As numbers and bigints belong to different types, they can be equal `==`, but not strictly equal `===`:
+Please note though, as numbers and bigints belong to different types, they can be equal `==`, but not strictly equal `===`:
 
 ```js run
 alert( 1 == 1n ); // true
@@ -101,15 +101,15 @@ alert( 0n || 2 ); // 2 (0n is considered falsy)
 
 Polyfilling bigints is tricky. The reason is that many JavaScript operators, such as `+`, `-` and so on behave differently with bigints compared to regular numbers.
 
-For example, division of bigints always returns an integer.
+For example, division of bigints always returns a bigint (rounded if necessary).
 
-To emulate such behavior, a polyfill would need to replace all such operators with its functions. But doing so is cumbersome and would cost a lot of performance.
+To emulate such behavior, a polyfill would need to analyze the code and replace all such operators with its functions. But doing so is cumbersome and would cost a lot of performance.
 
 So, there's no well-known good polyfill.
 
 Although, the other way around is proposed by the developers of [https://github.com/GoogleChromeLabs/jsbi](JSBI) library.
 
-They suggest to use JSBI library calls instead of native bigints:
+This library implements big numbers using its own methods. We can use them instead of native bigints:
 
 | Operation | native `BigInt` | JSBI |
 |-----------|-----------------|------|
@@ -120,7 +120,9 @@ They suggest to use JSBI library calls instead of native bigints:
 
 ...And then use the polyfill (Babel plugin) to convert JSBI calls to native bigints for those browsers that support them.
 
-In other words, this approach suggests that we write code in JSBI instead of native bigints. But JSBI works with numbers as with bigints internally, closely following the specification, so the code will be "bigint-ready".
+In other words, this approach suggests that we write code in JSBI instead of native bigints. But JSBI works with numbers as with bigints internally, emulates them closely following the specification, so the code will be "bigint-ready".
+
+We can use such JSBI code "as is" for engines that don't support bigints and for those that do support - the polyfill will convert the calls to native bigints.
 
 ## References
 

2-ui/5-loading/03-onload-onerror/article.md

@@ -107,7 +107,7 @@ That's for historical reasons.
 
 There's a rule: scripts from one site can't access contents of the other site. So, e.g. a script at `https://facebook.com` can't read the user's mailbox at `https://gmail.com`.
 
-Or, to be more precise, one origin (domain/port/protocol triplet) can't access the content from another one. So even if we have a subdomain, or just another port, these are different origins, no access to each other.
+Or, to be more precise, one origin (domain/port/protocol triplet) can't access the content from another one. So even if we have a subdomain, or just another port, these are different origins with no access to each other.
 
 This rule also affects resources from other domains.
 
@@ -159,7 +159,7 @@ Details may vary depending on the browser, but the idea is the same: any informa
 
 Why do we need error details?
 
-There are many services (and we can build our own) that listen for global errors using `window.onerror`, save errors and provide an interface to access and analyze them. That's great, as we can see real errors, triggered by our users. But if a script comes from another origin, then there's no much information about errors in it, as we've just seen.
+There are many services (and we can build our own) that listen for global errors using `window.onerror`, save errors and provide an interface to access and analyze them. That's great, as we can see real errors, triggered by our users. But if a script comes from another origin, then there's not much information about errors in it, as we've just seen.
 
 Similar cross-origin policy (CORS) is enforced for other types of resources as well.