Merge pull request #221 from javascript-tutorial/sync-bc08fd1b

Sync with upstream @ bc08fd1

Author: odsantos

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

@@ -24,7 +24,7 @@ Agora, podemos colocar alguns dados usando o operador de atribuição `=`:
 let message;
 
 *!*
-message = 'Olá'; // armazenar a string
+message = 'Olá'; // armazene a string 'Olá' na variável chamada message
 */!*
 ```
 

1-js/02-first-steps/13-while-for/article.md

@@ -377,7 +377,7 @@ label: {
 }
 ```
 
-...Although, 99.9% of the time `break` used is inside loops, as we've seen in the examples above.
+...Although, 99.9% of the time `break` is used inside loops, as we've seen in the examples above.
 
 A `continue` is only possible from inside a loop.
 ````

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 @@ Here, in this chapter, our purpose is to get the gist of how they work, and thei
 
 ## Transpilers
 
-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

@@ -9,7 +9,7 @@ In case of such operations, objects are auto-converted to primitives, and then t
 
 That's an important limitation, as the result of `obj1 + obj2` can't be another object!
 
-E.g. we can't make objects representing vectors or matrices (or archievements or whatever), add them and expect a "summed" object as the result. Such architectural feats are automatically "off the board".
+E.g. we can't make objects representing vectors or matrices (or achievements or whatever), add them and expect a "summed" object as the result. Such architectural feats are automatically "off the board".
 
 So, because we can't do much here, there's no maths with objects in real projects. When it happens, it's usually because of a coding mistake.
 
@@ -135,7 +135,7 @@ As we can see from the code, `user` becomes a self-descriptive string or a money
 
 If there's no `Symbol.toPrimitive` then JavaScript tries to find methods `toString` and `valueOf`:
 
-- For the "string" hint: `toString`, and if it doesn't exist, then `valueOf` (so `toString` has the priority for stirng conversions).
+- For the "string" hint: `toString`, and if it doesn't exist, then `valueOf` (so `toString` has the priority for string conversions).
 - For other hints: `valueOf`, and if it doesn't exist, then `toString` (so `valueOf` has the priority for maths).
 
 Methods `toString` and `valueOf` come from ancient times. They are not symbols (symbols did not exist that long ago), but rather "regular" string-named methods. They provide an alternative "old-style" way to implement the conversion.
@@ -279,4 +279,4 @@ The conversion algorithm is:
 
 In practice, it's often enough to implement only `obj.toString()` as a "catch-all" method for string conversions that should return a "human-readable" representation of an object, for logging or debugging purposes.  
 
-As for math operations, JavaScript doesn't provide a way to "override" them using methods, so real life projects rarely use them on objects.
+As for math operations, JavaScript doesn't provide a way to "override" them using methods, so real life projects rarely use them on objects.

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

@@ -37,8 +37,8 @@ alert( 7.3e9 );  // 7.3 billions (same as 7300000000 or 7_300_000_000)
 In other words, `e` multiplies the number by `1` with the given zeroes count.
 
 ```js
-1e3 = 1 * 1000 // e3 means *1000
-1.23e6 = 1.23 * 1000000 // e6 means *1000000
+1e3 === 1 * 1000; // e3 means *1000
+1.23e6 === 1.23 * 1000000; // e6 means *1000000
 ```
 
 Now let's write something very small. Say, 1 microsecond (one millionth of a second):
@@ -59,10 +59,10 @@ In other words, a negative number after `"e"` means a division by 1 with the giv
 
 ```js
 // -3 divides by 1 with 3 zeroes
-1e-3 = 1 / 1000 (=0.001)
+1e-3 === 1 / 1000; // 0.001
 
 // -6 divides by 1 with 6 zeroes
-1.23e-6 = 1.23 / 1000000 (=0.00000123)
+1.23e-6 === 1.23 / 1000000; // 0.00000123
 ```
 
 ### Hex, binary and octal numbers
@@ -118,6 +118,7 @@ Please note that two dots in `123456..toString(36)` is not a typo. If we want to
 If we placed a single dot: `123456.toString(36)`, then there would be an error, because JavaScript syntax implies the decimal part after the first dot. And if we place one more dot, then JavaScript knows that the decimal part is empty and now goes the method.
 
 Also could write `(123456).toString(36)`.
+
 ```
 
 ## Rounding

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 @@ Objects lack many methods that exist for arrays, e.g. `map`, `filter` and others
 If we'd like to apply them, then we can use `Object.entries` followed by `Object.fromEntries`:
 
 1. Use `Object.entries(obj)` to get an array of key/value pairs from `obj`.
-2. Use array methods on that array, e.g. `map`.
+2. Use array methods on that array, e.g. `map`, to transform these key/value pairs.
 3. Use `Object.fromEntries(array)` on the resulting array to turn it back into an object.
 
 For example, we have an object with prices, and would like to double them:
@@ -91,12 +91,13 @@ let prices = {
 
 *!*
 let doublePrices = Object.fromEntries(
-  // convert to array, map, and then fromEntries gives back the object
-  Object.entries(prices).map(([key, value]) => [key, value * 2])
+  // convert prices to array, map each key/value pair into another pair
+  // and then fromEntries gives back the object
+  Object.entries(prices).map(entry => [entry[0], entry[1] * 2])
 );
 */!*
 
 alert(doublePrices.meat); // 8
-```   
+```
 
-It may look difficult at first sight, but becomes easy to understand after you use it once or twice. We can make powerful chains of transforms this way. 
+It may look difficult at first sight, but becomes easy to understand after you use it once or twice. We can make powerful chains of transforms this way.

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

@@ -195,7 +195,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:
 
@@ -215,20 +215,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):
 
@@ -245,7 +248,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 = {
@@ -264,6 +267,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