Sync with upstream @ d6e88647

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

@@ -1,6 +1,6 @@
 # An Introduction to JavaScript
 
-Let's see what's so special about JavaScript, what we can achieve with it, and which other technologies play well with it.
+Let's see what's so special about JavaScript, what we can achieve with it, and what other technologies play well with it.
 
 ## What is JavaScript?
 
@@ -116,6 +116,6 @@ There are more. Of course, even if we use one of transpiled languages, we should
 
 ## Summary
 
-- JavaScript was initially created as a browser-only language, but is now used in many other environments as well.
-- Today, JavaScript has a unique position as the most widely-adopted browser language with full integration with HTML/CSS.
+- JavaScript was initially created as a browser-only language, but it is now used in many other environments as well.
+- Today, JavaScript has a unique position as the most widely-adopted browser language with full integration in HTML/CSS.
 - There are many languages that get "transpiled" to JavaScript and provide certain features. It is recommended to take a look at them, at least briefly, after mastering JavaScript.

1-js/02-first-steps/18-javascript-specials/article.md

@@ -144,7 +144,7 @@ Assignments
 : There is a simple assignment: `a = b` and combined ones like `a *= 2`.
 
 Bitwise
-: Bitwise operators work with 32-bit integers at the lowest, bit-level: see the [docs](mdn:/JavaScript/Reference/Operators/Bitwise_Operators) when they are needed.
+: Bitwise operators work with 32-bit integers at the lowest, bit-level: see the [docs](mdn:/JavaScript/Guide/Expressions_and_Operators#Bitwise) when they are needed.
 
 Conditional
 : The only operator with three parameters: `cond ? resultA : resultB`. If `cond` is truthy, returns `resultA`, otherwise `resultB`.

1-js/04-object-basics/01-object/8-multiply-numeric/task.md

@@ -2,9 +2,9 @@ importance: 3
 
 ---
 
-# Multiply numeric properties by 2
+# Multiply numeric property values by 2
 
-Create a function `multiplyNumeric(obj)` that multiplies all numeric properties of `obj` by `2`.
+Create a function `multiplyNumeric(obj)` that multiplies all numeric property values of `obj` by `2`.
 
 For instance:
 

1-js/04-object-basics/02-object-copy/article.md

@@ -1,10 +1,12 @@
-# Object copying, references
+# Object references and copying
 
-One of the fundamental differences of objects vs primitives is that they are stored and copied "by reference".
+One of the fundamental differences of objects versus primitives is that objects are stored and copied "by reference", as opposed to primitive values: strings, numbers, booleans, etc -- that are always copied "as a whole value".
 
-Primitive values: strings, numbers, booleans -- are assigned/copied "as a whole value".
+That's easy to understand if we look a bit "under a cover" of what happens when we copy a value.
 
-For instance:
+Let's start with a primitive, such as a string.
+
+Here we put a copy of `message` into `phrase`:
 
 ```js
 let message = "Hello!";
@@ -15,21 +17,31 @@ As a result we have two independent variables, each one is storing the string `"
 
 ![](variable-copy-value.svg)
 
+Quite an obvious result, right?
+
 Objects are not like that.
 
-**A variable stores not the object itself, but its "address in memory", in other words "a reference" to it.**
+**A variable assigned to an object stores not the object itself, but its "address in memory", in other words "a reference" to it.**
 
-Here's the picture for the object:
+Let's look at an example of such variable:
 
 ```js
 let user = {
   name: "John"
 };
 ```
 
+And here's how it's actually stored in memory:
+
 ![](variable-contains-reference.svg)
 
-Here, the object is stored somewhere in memory. And the variable `user` has a "reference" to it.
+The object is stored somewhere in memory (at the right of the picture), while the `user` variable (at the left) has a "reference" to it.
+
+We may think of an object variable, such as `user`, as of a sheet of paper with the address.
+
+When we perform actions with the object, e.g. take a property `user.name`, JavaScript engine looks into that address and performs the operation on the actual object.
+
+Now here's why it's important.
 
 **When an object variable is copied -- the reference is copied, the object is not duplicated.**
 
@@ -45,6 +57,8 @@ Now we have two variables, each one with the reference to the same object:
 
 ![](variable-copy-reference.svg)
 
+As you can see, there's still one object, now with two variables that reference it.
+
 We can use any variable to access the object and modify its contents:
 
 ```js run
@@ -59,15 +73,14 @@ admin.name = 'Pete'; // changed by the "admin" reference
 alert(*!*user.name*/!*); // 'Pete', changes are seen from the "user" reference
 ```
 
-The example above demonstrates that there is only one object. As if we had a cabinet with two keys and used one of them (`admin`) to get into it. Then, if we later use another key (`user`) we can see changes.
 
-## Comparison by reference
+It's just as if we had a cabinet with two keys and used one of them (`admin`) to get into it. Then, if we later use another key (`user`) we can see changes.
 
-The equality `==` and strict equality `===` operators for objects work exactly the same.
+## Comparison by reference
 
-**Two objects are equal only if they are the same object.**
+Two objects are equal only if they are the same object.
 
-Here two variables reference the same object, thus they are equal:
+For instance, here `a` and `b` reference the same object, thus they are equal:
 
 ```js run
 let a = {};
@@ -77,7 +90,7 @@ alert( a == b ); // true, both variables reference the same object
 alert( a === b ); // true
 ```
 
-And here two independent objects are not equal, even though both are empty:
+And here two independent objects are not equal, even though they look alike (both are empty):
 
 ```js run
 let a = {};
@@ -86,7 +99,7 @@ let b = {}; // two independent objects
 alert( a == b ); // false
 ```
 
-For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons occur very rarely, usually as a result of a coding mistake.
+For comparisons like `obj1 > obj2` or for a comparison against a primitive `obj == 5`, objects are converted to primitives. We'll study how object conversions work very soon, but to tell the truth, such comparisons are needed very rarely, usually they appear as a result of a programming mistake.
 
 ## Cloning and merging, Object.assign
 

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

@@ -32,11 +32,11 @@ user.sayHi = function() {
 user.sayHi(); // Hello!
 ```
 
-Here we've just used a Function Expression to create the function and assign it to the property `user.sayHi` of the object.
+Here we've just used a Function Expression to create a function and assign it to the property `user.sayHi` of the object.
 
-Then we can call it. The user can now speak!
+Then we can call it as `user.sayHi()`. The user can now speak!
 
-A function that is the property of an object is called its *method*.
+A function that is a property of an object is called its *method*.
 
 So, here we've got a method `sayHi` of the object `user`.
 
@@ -160,14 +160,16 @@ let user = {
 let admin = user;
 user = null; // overwrite to make things obvious
 
-admin.sayHi(); // Whoops! inside sayHi(), the old name is used! error!
+*!*
+admin.sayHi(); // TypeError: Cannot read property 'name' of null
+*/!*
 ```
 
 If we used `this.name` instead of `user.name` inside the `alert`, then the code would work.
 
 ## "this" is not bound
 
-In JavaScript, keyword `this` behaves unlike most other programming languages. It can be used in any function.
+In JavaScript, keyword `this` behaves unlike most other programming languages. It can be used in any function, even if it's not a method of an object.
 
 There's no syntax error in the following example:
 

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

@@ -3,53 +3,87 @@
 
 [recent browser="new"]
 
-The optional chaining `?.` is an error-proof way to access nested object properties, even if an intermediate property doesn't exist.
+The optional chaining `?.` is a safe way to access nested object properties, even if an intermediate property doesn't exist.
 
-## The problem
+## The "non-existing property" problem
 
 If you've just started to read the tutorial and learn JavaScript, maybe the problem hasn't touched you yet, but it's quite common.
 
-For example, some of our users have addresses, but few did not provide them. Then we can't safely read `user.address.street`:
+As an example, consider objects for user data. Most of our users have addresses in `user.address` property, with the street `user.address.street`, but some did not provide them.
+
+In such case, when we attempt to get `user.address.street`, we may get an error:
 
 ```js run
-let user = {}; // the user happens to be without address
+let user = {}; // a user without "address" property
 
 alert(user.address.street); // Error!
 ```
 
-Or, in the web development, we'd like to get an information about an element on the page, but it may not exist:
+That's the expected result, JavaScript works like this. As `user.address` is `undefined`, the attempt to get `user.address.street` fails with an error. Although, in many practical cases we'd prefer to get `undefined` instead of an error here (meaning "no street").
+
+...And another example. In the web development, we may need the information about an element on the page. The element is returned by `document.querySelector('.elem')`, and the catch is again - that it sometimes doesn't exist:
 
 ```js run
-// Error if the result of querySelector(...) is null
-let html = document.querySelector('.my-element').innerHTML;
+// the result of the call document.querySelector('.elem') may be an object or null
+let html = document.querySelector('.elem').innerHTML; // error if it's null
 ```
 
-Before `?.` appeared in the language, the `&&` operator was used to work around that.
+Once again, we may want to avoid the error in such case.
 
-For example:
+How can we do this?
+
+The obvious solution would be to check the value using `if` or the conditional operator `?`, before accessing it, like this:
+
+```js
+let user = {};
+
+alert(user.address ? user.address.street : undefined);
+```
+
+...But that's quite inelegant. As you can see, the `user.address` is duplicated in the code. For more deeply nested properties, that becomes a problem.
+
+E.g. let's try getting `user.address.street.name`.
+
+We need to check both `user.address` and `user.address.street`:
+
+```js
+let user = {}; // user has no address
+
+alert(user.address ? user.address.street ? user.address.street.name : null : null);
+```
+
+That looks awful.
+
+Before the optional chaining `?.` was added to the language, people used the `&&` operator for such cases:
 
 ```js run
 let user = {}; // user has no address
 
-alert( user && user.address && user.address.street ); // undefined (no error)
+alert( user.address && user.address.street && user.address.street.name ); // undefined (no error)
 ```
 
-AND'ing the whole path to the property ensures that all components exist, but is cumbersome to write.
+AND'ing the whole path to the property ensures that all components exist (if not, the evaluation stops), but also isn't ideal.
+
+As you can see, the property names are still duplicated in the code. E.g. in the code above, `user.address` appears three times.
+
+And now, finally, the optional chaining comes to the rescue!
 
 ## Optional chaining
 
 The optional chaining `?.` stops the evaluation and returns `undefined` if the part before `?.` is `undefined` or `null`.
 
 **Further in this article, for brevity, we'll be saying that something "exists" if it's not `null` and not `undefined`.**
 
-Here's the safe way to access `user.address.street`:
+Here's the safe way to access `user.address.street` using `?.`:
 
 ```js run
 let user = {}; // user has no address
 
 alert( user?.address?.street ); // undefined (no error)
 ```
 
+The code is short and clean, there's no duplication at all.
+
 Reading the address with `user?.address` works even if `user` object doesn't exist:
 
 ```js run
@@ -61,16 +95,16 @@ alert( user?.address.street ); // undefined
 
 Please note: the `?.` syntax makes optional the value before it, but not any further.
 
-In the example above, `user?.` allows only `user` to be `null/undefined`.
+In the example above, `user?.address.street` allows only `user` to be `null/undefined`.
 
 On the other hand, if `user` does exist, then it must have `user.address` property, otherwise `user?.address.street` gives an error at the second dot.
 
 ```warn header="Don't overuse the optional chaining"
 We should use `?.` only where it's ok that something doesn't exist.
 
-For example, if according to our coding logic `user` object must be there, but `address` is optional, then `user.address?.street` would be better.
+For example, if according to our coding logic `user` object must exist, but `address` is optional, then we should write `user.address?.street`, but not `user?.address?.street`.
 
-So, if `user` happens to be undefined due to a mistake, we'll know about it and fix it. Otherwise, coding errors can be silenced where not appropriate, and become more difficult to debug.
+So, if `user` happens to be undefined due to a mistake, we'll see a programming error about it and fix it. Otherwise, coding errors can be silenced where not appropriate, and become more difficult to debug.
 ```
 
 ````warn header="The variable before `?.` must be declared"
@@ -80,25 +114,27 @@ If there's no variable `user` at all, then `user?.anything` triggers an error:
 // ReferenceError: user is not defined
 user?.address;
 ```
-There must be `let/const/var user`. The optional chaining works only for declared variables.
+The variable must be declared (e.g. `let/const/var user` or as a function parameter). The optional chaining works only for declared variables.
 ````
 
 ## Short-circuiting
 
 As it was said before, the `?.` immediately stops ("short-circuits") the evaluation if the left part doesn't exist.
 
-So, if there are any further function calls or side effects, they don't occur:
+So, if there are any further function calls or side effects, they don't occur.
+
+For instance:
 
 ```js run
 let user = null;
 let x = 0;
 
-user?.sayHi(x++); // nothing happens
+user?.sayHi(x++); // no "sayHi", so the execution doesn't reach x++
 
 alert(x); // 0, value not incremented
 ```
 
-## Other cases: ?.(), ?.[]
+## Other variants: ?.(), ?.[]
 
 The optional chaining `?.` is not an operator, but a special syntax construct, that also works with functions and square brackets.
 
@@ -121,9 +157,9 @@ user2.admin?.();
 */!*
 ```
 
-Here, in both lines we first use the dot `.` to get `admin` property, because the user object must exist, so it's safe read from it.
+Here, in both lines we first use the dot (`user1.admin`) to get `admin` property, because the user object must exist, so it's safe read from it.
 
-Then `?.()` checks the left part: if the admin function exists, then it runs (for `user1`). Otherwise (for `user2`) the evaluation stops without errors.
+Then `?.()` checks the left part: if the admin function exists, then it runs (that's so for `user1`). Otherwise (for `user2`) the evaluation stops without errors.
 
 The `?.[]` syntax also works, if we'd like to use brackets `[]` to access properties instead of dot `.`. Similar to previous cases, it allows to safely read a property from an object that may not exist.
 
@@ -148,28 +184,30 @@ Also we can use `?.` with `delete`:
 delete user?.name; // delete user.name if user exists
 ```
 
-```warn header="We can use `?.` for safe reading and deleting, but not writing"
-The optional chaining `?.` has no use at the left side of an assignment:
+````warn header="We can use `?.` for safe reading and deleting, but not writing"
+The optional chaining `?.` has no use at the left side of an assignment.
 
+For example:
 ```js run
-// the idea of the code below is to write user.name, if user exists
+let user = null;
 
 user?.name = "John"; // Error, doesn't work
 // because it evaluates to undefined = "John"
 ```
 
+It's just not that smart.
+````
+
 ## Summary
 
-The `?.` syntax has three forms:
+The optional chaining `?.` syntax has three forms:
 
 1. `obj?.prop` -- returns `obj.prop` if `obj` exists, otherwise `undefined`.
 2. `obj?.[prop]` -- returns `obj[prop]` if `obj` exists, otherwise `undefined`.
-3. `obj?.method()` -- calls `obj.method()` if `obj` exists, otherwise returns `undefined`.
+3. `obj.method?.()` -- calls `obj.method()` if `obj.method` exists, otherwise returns `undefined`.
 
 As we can see, all of them are straightforward and simple to use. The `?.` checks the left part for `null/undefined` and allows the evaluation to proceed if it's not so.
 
 A chain of `?.` allows to safely access nested properties.
 
-Still, we should apply `?.` carefully, only where it's ok 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 to exist. So that it won't hide programming errors from us, if they occur.