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

Author: root

1-js/04-object-basics/02-garbage-collection/article.md

@@ -207,6 +207,6 @@ A general book "The Garbage Collection Handbook: The Art of Automatic Memory Man
 
 If you are familiar with low-level programming, the more detailed information about V8 garbage collector is in the article [A tour of V8: Garbage Collection](http://jayconrod.com/posts/55/a-tour-of-v8-garbage-collection).
 
-[V8 blog](http://v8project.blogspot.com/) also publishes articles about changes in memory management from time to time. Naturally, to learn the garbage collection, you'd better prepare by learning about V8 internals in general and read the blog of [Vyacheslav Egorov](http://mrale.ph) who worked as one of V8 engineers. I'm saying: "V8", because it is best covered with articles in the internet. For other engines, many approaches are similar, but garbage collection differs in many aspects.
+[V8 blog](https://v8.dev/) also publishes articles about changes in memory management from time to time. Naturally, to learn the garbage collection, you'd better prepare by learning about V8 internals in general and read the blog of [Vyacheslav Egorov](http://mrale.ph) who worked as one of V8 engineers. I'm saying: "V8", because it is best covered with articles in the internet. For other engines, many approaches are similar, but garbage collection differs in many aspects.
 
 In-depth knowledge of engines is good when you need low-level optimizations. It would be wise to plan that as the next step after you're familiar with the language.  

1-js/04-object-basics/04-object-methods/article.md

@@ -63,7 +63,7 @@ user.sayHi(); // Hello!
 ```smart header="Object-oriented programming"
 When we write our code using objects to represent entities, that's called an [object-oriented programming](https://en.wikipedia.org/wiki/Object-oriented_programming), in short: "OOP".
 
-OOP is a big thing, an interesting science of its own. How to choose the right entities? How to organize the interaction between them? That's architecture, and there are great books on that topic, like "Design Patterns: Elements of Reusable Object-Oriented Software" by E.Gamma, R.Helm, R.Johnson, J.Vissides or "Object-Oriented Analysis and Design with Applications" by G.Booch, and more. 
+OOP is a big thing, an interesting science of its own. How to choose the right entities? How to organize the interaction between them? That's architecture, and there are great books on that topic, like "Design Patterns: Elements of Reusable Object-Oriented Software" by E.Gamma, R.Helm, R.Johnson, J.Vissides or "Object-Oriented Analysis and Design with Applications" by G.Booch, and more.
 ```
 ### Method shorthand
 
@@ -72,14 +72,14 @@ There exists a shorter syntax for methods in an object literal:
 ```js
 // these objects do the same
 
-let user = {
+user = {
   sayHi: function() {
     alert("Hello");
   }
 };
 
 // method shorthand looks better, right?
-let user = {
+user = {
 *!*
   sayHi() { // same as "sayHi: function()"
 */!*
@@ -166,7 +166,7 @@ If we used `this.name` instead of `user.name` inside the `alert`, then the code
 
 ## "this" is not bound
 
-In JavaScript, "this" keyword behaves unlike most other programming languages. First, it can be used in any function.
+In JavaScript, "this" keyword behaves unlike most other programming languages. It can be used in any function.
 
 There's no syntax error in the code like that:
 
@@ -176,9 +176,9 @@ function sayHi() {
 }
 ```
 
-The value of `this` is evaluated during the run-time. And it can be anything.
+The value of `this` is evaluated during the run-time, depending on the context. And it can be anything.
 
-For instance, the same function may have different "this" when called from different objects:
+For instance, here the same function is assigned to two different objects and has different "this" in the calls:
 
 ```js run
 let user = { name: "John" };
@@ -189,7 +189,7 @@ function sayHi() {
 }
 
 *!*
-// use the same functions in two objects
+// use the same function in two objects
 user.f = sayHi;
 admin.f = sayHi;
 */!*
@@ -202,7 +202,10 @@ admin.f(); // Admin  (this == admin)
 admin['f'](); // Admin (dot or square brackets access the method – doesn't matter)
 ```
 
-Actually, we can call the function without an object at all:
+The rule is simple: if `obj.f()` is called, then `this` is `obj` during the call of `f`. So it's either `user` or `admin` in the example above.
+
+````smart header="Calling without an object: `this == undefined`"
+We can even call the function without an object at all:
 
 ```js run
 function sayHi() {
@@ -216,7 +219,8 @@ In this case `this` is `undefined` in strict mode. If we try to access `this.nam
 
 In non-strict mode the value of `this` in such case will be the *global object* (`window` in a browser, we'll get to it later in the chapter [](info:global-object)). This is a historical behavior that `"use strict"` fixes.
 
-Please note that usually a call of a function that uses `this` without an object is not normal, but rather a programming mistake. If a function has `this`, then it is usually meant to be called in the context of an object.
+Usually such call is an programming error. If there's `this` inside a function, it expects to be called in an object context.
+````
 
 ```smart header="The consequences of unbound `this`"
 If you come from another programming language, then you are probably used to the idea of a "bound `this`", where methods defined in an object always have `this` referencing that object.

1-js/05-data-types/02-number/3-repeat-until-number/_js.view/test.js

@@ -18,7 +18,7 @@ describe("readNumber", function() {
     assert.strictEqual(readNumber(), 0);
   });
 
-  it("continues the loop unti meets a number", function() {
+  it("continues the loop until meets a number", function() {
     prompt.onCall(0).returns("not a number");
     prompt.onCall(1).returns("not a number again");
     prompt.onCall(2).returns("1");
@@ -35,4 +35,4 @@ describe("readNumber", function() {
     assert.isNull(readNumber());
   });
 
-});
+});

1-js/05-data-types/11-json/article.md

@@ -66,7 +66,7 @@ alert(json);
 
 The method `JSON.stringify(student)` takes the object and converts it into a string.
 
-The resulting `json` string is a called *JSON-encoded* or *serialized* or *stringified* or *marshalled* object. We are ready to send it over the wire or put into a plain data store.
+The resulting `json` string is called a *JSON-encoded* or *serialized* or *stringified* or *marshalled* object. We are ready to send it over the wire or put into a plain data store.
 
 
 Please note that a JSON-encoded object has several important differences from the object literal:

1-js/08-prototypes/02-function-prototype/article.md

@@ -162,7 +162,7 @@ Everything is quite simple, just few notes to make things clear:
 
 - The `F.prototype` property is not the same as `[[Prototype]]`. The only thing `F.prototype` does: it sets `[[Prototype]]` of new objects when `new F()` is called.
 - The value of `F.prototype` should be either an object or null: other values won't work.
--  The `"prototype"` property only has such a special effect when is set to a constructor function, and invoked with `new`.
+-  The `"prototype"` property only has such a special effect when set on a constructor function, and invoked with `new`.
 
 On regular objects the `prototype` is nothing special:
 ```js

1-js/09-classes/01-class/article.md

@@ -64,7 +64,7 @@ The notation here is not to be confused with object literals. Within the class,
 
 ## What is a class?
 
-So, what exactly is a `class`? That's not an entirely  new language-level entity, as one might think.
+So, what exactly is a `class`? That's not an entirely new language-level entity, as one might think.
 
 Let's unveil any magic and see what a class really is. That'll help in understanding many complex aspects.
 
@@ -91,7 +91,7 @@ What `class User {...}` construct really does is:
 
 Afterwards, for new objects, when we call a method, it's taken from the prototype, just as  described in the chapter <info:function-prototype>. So `new User` object has access to class methods.
 
-We can illustrate the result of `class User` as:
+We can illustrate the result of `class User` declaration as:
 
 ![](class-user.png)
 
@@ -198,7 +198,8 @@ Similar to Named Function Expressions, class expressions may or may not have a n
 If a class expression has a name, it's visible inside the class only:
 
 ```js run
-// "Named Class Expression" (alas, no such term, but that's what's going on)
+// "Named Class Expression"
+// (no such term in the spec, but that's similar to Named Function Expression)
 let User = class *!*MyClass*/!* {
   sayHi() {
     alert(MyClass); // MyClass is visible only inside the class
@@ -268,7 +269,7 @@ alert(user.name); // John
 user = new User(""); // Name too short.
 ```
 
-Internally, getters and setters are created on `User.prototype`, like this:
+The class declaration creates getters and setters in `User.prototype`, like this:
 
 ```js
 Object.defineProperties(User.prototype, {

1-js/10-error-handling/2-custom-errors/article.md

@@ -6,7 +6,7 @@ Our errors should support basic error properties like `message`, `name` and, pre
 
 JavaScript allows to use `throw` with any argument, so technically our custom error classes don't need to inherit from `Error`. But if we inherit, then it becomes possible to use `obj instanceof Error` to identify error objects. So it's better to inherit from it.
 
-As we build our application, our own errors naturally form a hierarchy, for instance `HttpTimeoutError` may inherit from `HttpError`, and so on.
+As the application grows, our own errors naturally form a hierarchy, for instance `HttpTimeoutError` may inherit from `HttpError`, and so on.
 
 ## Extending Error
 
@@ -126,7 +126,7 @@ We could also look at `err.name`, like this:
 
 The `instanceof` version is much better, because in the future we are going to extend `ValidationError`, make subtypes of it, like `PropertyRequiredError`. And `instanceof` check will continue to work for new inheriting classes. So that's future-proof.
 
-Also it's important that if `catch` meets an unknown error, then it rethrows it in the line `(**)`. The `catch`  only knows how to handle validation and syntax errors, other kinds (due to a typo in the code or such) should fall through.
+Also it's important that if `catch` meets an unknown error, then it rethrows it in the line `(**)`. The `catch` block only knows how to handle validation and syntax errors, other kinds (due to a typo in the code or other unknown ones) should fall through.
 
 ## Further inheritance
 
@@ -185,7 +185,7 @@ try {
 
 The new class `PropertyRequiredError` is easy to use: we only need to pass the property name: `new PropertyRequiredError(property)`. The human-readable `message` is generated by the constructor.
 
-Please note that `this.name` in `PropertyRequiredError` constructor is again assigned manually. That may become a bit tedious -- to assign `this.name = <class name>` when creating each custom error. But there's a way out. We can make our own "basic error" class that removes this burden from our shoulders by using `this.constructor.name` for `this.name` in the constructor. And then inherit from it.
+Please note that `this.name` in `PropertyRequiredError` constructor is again assigned manually. That may become a bit tedious -- to assign `this.name = <class name>` in every custom error class. But there's a way out. We can make our own "basic error" class that removes this burden from our shoulders by using `this.constructor.name` for `this.name` in its constructor. And then inherit all ours custom errors from it.
 
 Let's call it `MyError`.
 
@@ -218,7 +218,7 @@ Now custom errors are much shorter, especially `ValidationError`, as we got rid
 
 ## Wrapping exceptions
 
-The purpose of the function `readUser` in the code above is "to read the user data", right? There may occur different kinds of errors in the process. Right now we have `SyntaxError` and `ValidationError`, but in the future `readUser` function may grow: the new code will probably generate other kinds of errors.
+The purpose of the function `readUser` in the code above is "to read the user data", right? There may occur different kinds of errors in the process. Right now we have `SyntaxError` and `ValidationError`, but in the future `readUser` function may grow and probably generate other kinds of errors.
 
 The code which calls `readUser` should handle these errors. Right now it uses multiple `if` in the `catch` block to check for different error types and rethrow the unknown ones. But if `readUser` function generates several kinds of errors -- then we should ask ourselves: do we really want to check for all error types one-by-one in every code that calls `readUser`?
 
@@ -303,5 +303,5 @@ The approach is called "wrapping exceptions", because we take "low level excepti
 ## Summary
 
 - We can inherit from `Error` and other built-in error classes normally, just need to take care of `name` property and don't forget to call `super`.
-- Most of the time, we should use `instanceof` to check for particular errors. It also works with inheritance. But sometimes we have an error object coming from the 3rd-party library and there's no easy way to get the class. Then `name` property can be used for such checks.
-- Wrapping exceptions is a widespread technique when a function handles low-level exceptions and makes a higher-level object to report about the errors. Low-level exceptions sometimes become properties of that object like `err.cause` in the examples above, but that's not strictly required.
+- We can use `instanceof` to check for particular errors. It also works with inheritance. But sometimes we have an error object coming from the 3rd-party library and there's no easy way to get the class. Then `name` property can be used for such checks.
+- Wrapping exceptions is a widespread technique: a function handles low-level exceptions and creates higher-level errors instead of various low-level ones. Low-level exceptions sometimes become properties of that object like `err.cause` in the examples above, but that's not strictly required.

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* your `.then`/`.catch`/`.finally` will still execute first.
+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 code that demonstrates it:
+Here's the demo:
 
 ```js run
 let promise = Promise.resolve();
@@ -21,7 +21,7 @@ That's strange, because the promise is definitely done from the beginning.
 
 Why did the `.then` trigger afterwards? What's going on?
 
-# Microtasks
+## Microtasks
 
 Asynchronous tasks need proper management. For that, the standard specifies an internal queue `PromiseJobs`, more often referred to as "microtask queue" (v8 term).
 
@@ -54,9 +54,11 @@ Now the order is as intended.
 
 ## Event loop
 
-In-browser JavaScript, as well as Node.js, is based on an *event loop*.
+In-browser JavaScript execution flow, 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.
+"Event loop" is a process when the engine sleeps and waits for events. When they occur - handles them and sleeps again.
+
+Events may come either comes from external sources, like user actions, or just as the end signal of an internal task.
 
 Examples of events:
 - `mousemove`, a user moved their mouse.
@@ -120,14 +122,14 @@ Promise.resolve()
 
 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.
+As a logical consequence, macrotasks are handled only when promises give the engine a "free time". So if we have a chain of promise handlers that don't wait for anything, execute right one after another, then a `setTimeout` (or a user action handler) can never run in-between them.
 
 
 ## Unhandled rejection
 
 Remember "unhandled rejection" event from the chapter <info:promise-error-handling>?
 
-Now, with the understanding of microtasks, we can formalize it.
+Now we can describe how JavaScript finds out that a rejection was not handled.
 
 **"Unhandled rejection" is when a promise error is not handled at the end of the microtask queue.**
 
@@ -167,15 +169,15 @@ setTimeout(() => promise.catch(err => alert('caught')));
 window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
-Now the unhandled rejection appears again. Why? Because `unhandledrejection` triggers when the microtask queue is complete. The engine examines promises and, if any of them is in "rejected" state, then the event is generated.
+Now the unhandled rejection appears again. Why? Because `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.
 
 In the example, the `.catch` added by `setTimeout` triggers too, of course it does, but later, after `unhandledrejection` has already occurred.
 
 ## Summary
 
 - 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` are called after the current code is finished.**
+    **So, `.then/catch/finally` handlers 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.
 

1-js/13-modules/03-modules-dynamic-imports/article.md

@@ -1,7 +1,7 @@
 
 # Dynamic imports
 
-Export and import statements that we covered in previous chaters are called "static".
+Export and import statements that we covered in previous chapters are called "static".
 
 That's because they are indeed static. The syntax is very strict.
 

2-ui/1-document/05-basic-dom-node-properties/2-tree-info/solution.md

@@ -6,7 +6,9 @@ for (let li of document.querySelectorAll('li')) {
 }
 ```
 
-In the loop we need to get the text inside every `li`. We can read it directly from the first child node, that is the text node:
+In the loop we need to get the text inside every `li`.
+
+We can read the text from the first child node of `li`, that is the text node:
 
 ```js
 for (let li of document.querySelectorAll('li')) {
@@ -16,4 +18,4 @@ for (let li of document.querySelectorAll('li')) {
 }
 ```
 
-Then we can get the number of descendants `li.getElementsByTagName('li')`.
+Then we can get the number of descendants as `li.getElementsByTagName('li').length`.