Sync with upstream @ ef8d5768

1-js/02-first-steps/04-variables/article.md

@@ -24,7 +24,7 @@ let message;
 let message;
 
 *!*
-message = 'Привіт'; // збереження рядка
+message = 'Привіт'; // збереження рядка 'Привіт' у змінній `message`
 */!*
 ```
 

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

@@ -181,7 +181,7 @@ In other words, to put these terms straight:
 
 We declare functions listing their parameters, then call them passing arguments.
 
-In the example above, one might say: "the function `sayMessage` is declared with two parameters, then called with two arguments: `from` and `"Hello"`".
+In the example above, one might say: "the function `showMessage` is declared with two parameters, then called with two arguments: `from` and `"Hello"`".
 
 
 ## Default values
@@ -247,7 +247,7 @@ function showMessage(text) {
 showMessage(); // empty message
 ```
 
-...Or we could use the `??` operator:
+...Or we could use the `||` operator:
 
 ```js
 function showMessage(text) {

1-js/03-code-quality/06-polyfills/article.md

@@ -22,7 +22,7 @@
 
 ## Транспілятори
 
-A [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler) is a special piece of software that can parse ("read and understand") modern code, and rewrite it using older syntax constructs, so that the result would be the same.
+A [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler) is a special piece of software that translates source code to another source code. It can parse ("read and understand") modern code and rewrite it using older syntax constructs, so that it'll also work in outdated engines.
 
 E.g. JavaScript before year 2020 didn't have the "nullish coalescing operator" `??`. So, if a visitor uses an outdated browser, it may fail to understand the code like `height = height ?? 100`.
 

1-js/04-object-basics/06-constructor-new/1-two-functions-one-object/task.md

@@ -4,7 +4,7 @@ importance: 2
 
 # Two functions – one object
 
-Is it possible to create functions `A` and `B` such as `new A()==new B()`?
+Is it possible to create functions `A` and `B` so that `new A() == new B()`?
 
 ```js no-beautify
 function A() { ... }

1-js/04-object-basics/09-object-toprimitive/article.md

@@ -133,7 +133,7 @@ alert(user + 500); // hint: default -> 1500
 
 Якщо немає `Symbol.toPrimitive` тоді JavaScript намагається знайти методи `toString` і `valueOf`:
 
-- Для "string" підказки: `tostring`, і якщо цей метод не існує, то `valueOf` (таким чином `toString` має пріоритет при перетворенні в рядок).
+- Для "string" підказки: `toString`, і якщо цей метод не існує, то `valueOf` (таким чином `toString` має пріоритет при перетворенні в рядок).
 - Для інших підказок: `valueOf`, і якщо це не існує, то `toString` (таким чином `valueOf` має пріоритет для математики).
 
 Методи `toString` і `valueOf` походять з давніх часів. Вони не є символами (багато часу назад символи не існували), а скоріше є "звичними" методами, що названі за допомогою рядків. Вони забезпечують альтернативний шлях "старого стилю" для реалізації перетворення.

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

@@ -37,8 +37,8 @@ alert( 7.3e9 );  // 7.3 мільярдів (таке ж саме що 7300000000
 Іншими словами, `"e"` помножує число на `1` із заданим числом нулів.
 
 ```js
-1e3 = 1 * 1000 // e3 означає *1000
-1.23e6 = 1.23 * 1000000 // e6 означає *1000000
+1e3 === 1 * 1000; // e3 означає *1000
+1.23e6 === 1.23 * 1000000; // e6 означає *1000000
 ```
 
 Тепер напишемо щось дуже маленьке. Наприклад, 1 мікросекунда (одна мільйонна частина секунди):
@@ -59,10 +59,10 @@ let ms = 1e-6; // шість нулів зліва від 1
 
 ```js
 // -3 ділиться на 1 з 3 нулями
-1e-3 = 1 / 1000 (=0.001)
+1e-3 === 1 / 1000; // 0.001
 
 // -6 ділиться на 1 з 6 нулями
-1.23e-6 = 1.23 / 1000000 (=0.00000123)
+1.23e-6 === 1.23 / 1000000; // 0.00000123
 ```
 
 ### Двійкові, вісімкові та шістнадцяткові числа
@@ -118,6 +118,7 @@ alert( num.toString(2) );   // 11111111
 Якби ми помістили одну крапку: `123456.toString(36)`, тоді виникла б помилка, оскільки синтаксис JavaScript передбачає десяткову частину після першої точки. І якщо ми розмістимо ще одну крапку, то JavaScript розпізнає, що десяткова частина порожня, і далі йде метод.
 
 Також можна написати `(123456).toString(36)`.
+
 ```
 
 ## Округлення

1-js/05-data-types/05-array-methods/12-reduce-object/task.md

@@ -4,7 +4,7 @@ importance: 4
 
 # Create keyed object from array
 
-Let's say we received an array of users in the form `{id:..., name:..., age... }`.
+Let's say we received an array of users in the form `{id:..., name:..., age:... }`.
 
 Create a function `groupById(arr)` that creates an object from it, with `id` as the key, and array items as values.
 

1-js/05-data-types/09-keys-values-entries/article.md

@@ -77,7 +77,7 @@ for (let value of Object.values(user)) {
 Якщо б ми хотіли їх застосувати, тоді б ми використовували `Object.entries` з подальшим викликом `Object.fromEntries`:
 
 1. Викликаємо `Object.entries(obj)`, щоб отримати масив пар ключ/значення з `obj`.
-2. На ньому використовуємо методи масиву, наприклад `map`.
+2. На ньому використовуємо методи масиву, наприклад `map`, щоб перетворити ці пари ключів/значень.
 3. Використаємо `Object.fromEntries(array)` на отриманому масиві, щоб перетворити його знову на об’єкт.
 
 Наприклад, у нас є об’єкт з цінами, і ми б хотіли їх подвоїти:
@@ -91,12 +91,13 @@ let prices = {
 
 *!*
 let doublePrices = Object.fromEntries(
-  // перетворити на масив, потім застосувати map, а потім fromEntries повертає об’єкт
-  Object.entries(prices).map(([key, value]) => [key, value * 2])
+  // перетворити ціни на масив, потім застосувати map, щоб перетворити на пари ключ/значення
+  // а потім fromEntries повертає об’єкт
+  Object.entries(prices).map(entry => [entry[0], entry[1] * 2])
 );
 */!*
 
 alert(doublePrices.meat); // 8
-```   
+```
 
-З першого погляду це може здатися важким, але стане зрозумілим після того, як ви використаєте це декілька разів. Таким чином ми можемо створювати потужні ланцюги перетворень.
+З першого погляду це може здатися важким, але стане зрозумілим після того, як ви використаєте це декілька разів. Таким чином ми можемо створювати потужні ланцюги перетворень.

1-js/07-object-properties/01-property-descriptors/article.md

@@ -194,7 +194,7 @@ alert(Object.keys(user)); // name
 
 The non-configurable flag (`configurable:false`) is sometimes preset for built-in objects and properties.
 
-A non-configurable property can not be deleted.
+A non-configurable property can't be deleted, its attributes can't be modified.
 
 For instance, `Math.PI` is non-writable, non-enumerable and non-configurable:
 
@@ -214,20 +214,23 @@ alert( JSON.stringify(descriptor, null, 2 ) );
 So, a programmer is unable to change the value of `Math.PI` or overwrite it.
 
 ```js run
-Math.PI = 3; // Error
+Math.PI = 3; // Error, because it has writable: false
 
 // delete Math.PI won't work either
 ```
 
-Making a property non-configurable is a one-way road. We cannot change it back with `defineProperty`.
+We also can't change `Math.PI` to be `writable` again:
+
+```js run
+// Error, because of configurable: false
+Object.defineProperty(Math, "PI", { writable: true });
+```
 
-To be precise, non-configurability imposes several restrictions on `defineProperty`:
-1. Can't change `configurable` flag.
-2. Can't change `enumerable` flag.
-3. Can't change `writable: false` to `true` (the other way round works).
-4. Can't change `get/set` for an accessor property (but can assign them if absent).
+There's absolutely nothing we can do with `Math.PI`.
 
-**The idea of "configurable: false" is to prevent changes of property flags and its deletion, while allowing to change its value.**
+Making a property non-configurable is a one-way road. We cannot change it back with `defineProperty`.
+
+**Please note: `configurable: false` prevents changes of property flags and its deletion, while allowing to change its value.**
 
 Here `user.name` is non-configurable, but we can still change it (as it's writable):
 
@@ -244,7 +247,7 @@ user.name = "Pete"; // works fine
 delete user.name; // Error
 ```
 
-And here we make `user.name` a "forever sealed" constant:
+And here we make `user.name` a "forever sealed" constant, just like the built-in `Math.PI`:
 
 ```js run
 let user = {
@@ -263,6 +266,11 @@ delete user.name;
 Object.defineProperty(user, "name", { value: "Pete" });
 ```
 
+```smart header="The only attribute change possible: writable true -> false"
+There's a minor exception about changing flags.
+
+We can change `writable: true` to `false` for a non-configurable property, thus preventing its value modification (to add another layer of protection). Not the other way around though.
+```
 
 ## Object.defineProperties
 

1-js/09-classes/04-private-protected-properties-methods/article.md

@@ -116,7 +116,7 @@ class CoffeeMachine {
 let coffeeMachine = new CoffeeMachine(100);
 
 // add water
-coffeeMachine.waterAmount = -10; // Error: Negative water
+coffeeMachine.waterAmount = -10; // _waterAmount will become 0, not -10
 ```
 
 Now the access is under control, so setting the water amount below zero becomes impossible.

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

@@ -21,9 +21,9 @@ Internally, we'll use `JSON.parse`. If it receives malformed `json`, then it thr
 
 Our function `readUser(json)` will not only read JSON, but check ("validate") the data. If there are no required fields, or the format is wrong, then that's an error. And that's not a `SyntaxError`, because the data is syntactically correct, but another kind of error. We'll call it `ValidationError` and create a class for it. An error of that kind should also carry the information about the offending field.
 
-Our `ValidationError` class should inherit from the built-in `Error` class.
+Our `ValidationError` class should inherit from the `Error` class.
 
-That class is built-in, but here's its approximate code so we can understand what we're extending:
+The `Error` class is built-in, but here's its approximate code so we can understand what we're extending:
 
 ```js
 // The "pseudocode" for the built-in Error class defined by JavaScript itself
@@ -117,15 +117,15 @@ We could also look at `err.name`, like this:
 // instead of (err instanceof SyntaxError)
 } else if (err.name == "SyntaxError") { // (*)
 // ...
-```  
+```
 
 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` 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.
+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 (caused by a typo in the code or other unknown reasons) should fall through.
 
 ## Further inheritance
 
-The `ValidationError` class is very generic. Many things may go wrong. The property may be absent or it may be in a wrong format (like a string value for `age`). Let's make a more concrete class `PropertyRequiredError`, exactly for absent properties. It will carry additional information about the property that's missing.
+The `ValidationError` class is very generic. Many things may go wrong. The property may be absent or it may be in a wrong format (like a string value for `age` instead of a number). Let's make a more concrete class `PropertyRequiredError`, exactly for absent properties. It will carry additional information about the property that's missing.
 
 ```js run
 class ValidationError extends Error {

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

@@ -28,7 +28,7 @@ function loadScript(src) {
 }
 ```
 
-It appends to the document the new, dynamically created, tag `<script src="…">` with given `src`. The browser automatically starts loading it and executes when complete.
+It inserts into the document a new, dynamically created, tag `<script src="…">` with the given `src`. The browser automatically starts loading it and executes when complete.
 
 We can use this function like this:
 

1-js/11-async/05-promise-api/article.md

@@ -18,7 +18,7 @@ let promise = Promise.all([...promises...]);
 
 `Promise.all` takes an array of promises (it technically can be any iterable, but is usually an array) and returns a new promise.
 
-The new promise resolves when all listed promises are settled, and the array of their results becomes its result.
+The new promise resolves when all listed promises are resolved, and the array of their results becomes its result.
 
 For instance, the `Promise.all` below settles after 3 seconds, and then its result is an array `[1, 2, 3]`:
 

1-js/12-generators-iterators/1-generators/article.md

@@ -448,6 +448,28 @@ try {
 
 If we don't catch the error there, then, as usual, it falls through to the outer calling code (if any) and, if uncaught, kills the script.
 
+## generator.return
+
+`generator.return(value)` finishes the generator execution and return the given `value`.
+
+```js
+function* gen() {
+  yield 1;
+  yield 2;
+  yield 3;
+}
+
+const g = gen();
+
+g.next();        // { value: 1, done: false }
+g.return('foo'); // { value: "foo", done: true }
+g.next();        // { value: undefined, done: true }
+```
+
+If we again use `generator.return()` in a completed generator, it will return that value again ([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/return)).
+
+Often we don't use it, as most of time we want to get all returning values, but it can be useful when we want to stop generator in a specific condition.
+
 ## Summary
 
 - Generators are created by generator functions `function* f(…) {…}`.