Merge branch 'master' into patch-1

Author: iliakan

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

@@ -68,7 +68,7 @@ Examples of such restrictions include:
     Modern browsers allow it to work with files, but the access is limited and only provided if the user does certain actions, like "dropping" a file into a browser window or selecting it via an `<input>` tag.
 
     There are ways to interact with camera/microphone and other devices, but they require a user's explicit permission. So a JavaScript-enabled page may not sneakily enable a web-camera, observe the surroundings and send the information to the [NSA](https://en.wikipedia.org/wiki/National_Security_Agency).
-- Different tabs/windows generally do not know about each other. Sometimes they do; for example when one window uses JavaScript to open the other one. But even in this case, JavaScript from one page may not access the other if they come from different sites (from a different domain, protocol or port).
+- Different tabs/windows generally do not know about each other. Sometimes they do, for example when one window uses JavaScript to open the other one. But even in this case, JavaScript from one page may not access the other if they come from different sites (from a different domain, protocol or port).
 
     This is called the "Same Origin Policy". To work around that, *both pages* must agree for data exchange and contain a special JavaScript code that handles it. We'll cover that in the tutorial.
 

1-js/01-getting-started/4-devtools/article.md

@@ -8,7 +8,7 @@ To see errors and get a lot of other useful information about scripts, "develope
 
 Most developers lean towards Chrome or Firefox for development because those browsers have the best developer tools. Other browsers also provide developer tools, sometimes with special features, but are usually playing "catch-up" to Chrome or Firefox. So most developers have a "favorite" browser and switch to others if a problem is browser-specific.
 
-Developer tools are potent; they have many features. To start, we'll learn how to open them, look at errors, and run JavaScript commands.
+Developer tools are potent, they have many features. To start, we'll learn how to open them, look at errors, and run JavaScript commands.
 
 ## Google Chrome
 

1-js/02-first-steps/01-hello-world/article.md

@@ -9,7 +9,7 @@ So first, let's see how we attach a script to a webpage. For server-side environ
 
 ## The "script" tag
 
-JavaScript programs can be inserted into any part of an HTML document with the help of the `<script>` tag.
+JavaScript programs can be inserted almost anywhere into an HTML document using the `<script>` tag.
 
 For instance:
 

1-js/03-code-quality/02-coding-style/article.md

@@ -328,7 +328,7 @@ Here's an example of an `.eslintrc` file:
   },
   "rules": {
     "no-console": 0,
-    "indent": ["warning", 2]
+    "indent": 2
   }
 }
 ```

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

@@ -23,7 +23,7 @@ Actually, there are two parts in Babel:
 
 2. Second, the polyfill.
 
-    New language features may include new built-in functions and syntax constructs.
+    New language features may include not only syntax constructs, but also built-in functions.
     The transpiler rewrites the code, transforming syntax constructs into older ones. But as for new built-in functions, we need to implement them. JavaScript is a highly dynamic language, scripts may add/modify any functions, so that they behave according to the modern standard.
 
     A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.

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

@@ -92,30 +92,6 @@ let user = {
 ```
 That is called a "trailing" or "hanging" comma. Makes it easier to add/remove/move around properties, because all lines become alike.
 
-````smart header="Object with const can be changed"
-Please note: an object declared as `const` *can* be modified.
-
-For instance:
-
-```js run
-const user = {
-  name: "John"
-};
-
-*!*
-user.name = "Pete"; // (*)
-*/!*
-
-alert(user.name); // Pete
-```
-
-It might seem that the line `(*)` would cause an error, but no. The `const` fixes the value of `user`, but not its contents.
-
-The `const` would give an error only if we try to set `user=...` as a whole.
-
-There's another way to make constant object properties, we'll cover it later in the chapter <info:property-descriptors>.
-````
-
 ## Square brackets
 
 For multiword properties, the dot access doesn't work:

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

@@ -1,8 +1,8 @@
 # Object references and copying
 
-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".
+One of the fundamental differences of objects versus primitives is that objects are stored and copied "by reference", whereas primitive values: strings, numbers, booleans, etc -- are always 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.
+That's easy to understand if we look a bit under the hood of what happens when we copy a value.
 
 Let's start with a primitive, such as a string.
 
@@ -13,17 +13,17 @@ let message = "Hello!";
 let phrase = message;
 ```
 
-As a result we have two independent variables, each one is storing the string `"Hello!"`.
+As a result we have two independent variables, each one storing the string `"Hello!"`.
 
 ![](variable-copy-value.svg)
 
 Quite an obvious result, right?
 
 Objects are not like that.
 
-**A variable assigned to an object 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.**
 
-Let's look at an example of such variable:
+Let's look at an example of such a variable:
 
 ```js
 let user = {
@@ -37,13 +37,13 @@ And here's how it's actually stored in memory:
 
 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.
+We may think of an object variable, such as `user`, as like a sheet of paper with the address of the object on it.
 
-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.
+When we perform actions with the object, e.g. take a property `user.name`, the JavaScript engine looks at what's at 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.**
+**When an object variable is copied, the reference is copied, but the object itself is not duplicated.**
 
 For instance:
 
@@ -53,13 +53,13 @@ let user = { name: "John" };
 let admin = user; // copy the reference
 ```
 
-Now we have two variables, each one with the reference to the same object:
+Now we have two variables, each storing a 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.
+As you can see, there's still one object, but now with two variables that reference it.
 
-We can use any variable to access the object and modify its contents:
+We can use either variable to access the object and modify its contents:
 
 ```js run
 let user = { name: 'John' };
@@ -73,8 +73,7 @@ admin.name = 'Pete'; // changed by the "admin" reference
 alert(*!*user.name*/!*); // 'Pete', changes are seen from the "user" 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.
+It's as if we had a cabinet with two keys and used one of them (`admin`) to get into it and make changes. Then, if we later use another key (`user`), we are still opening the same cabinet and can access the changed contents.
 
 ## Comparison by reference
 
@@ -99,15 +98,15 @@ 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 are needed very rarely, usually they appear as a result of a programming 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
 
 So, copying an object variable creates one more reference to the same object.
 
 But what if we need to duplicate an object? Create an independent copy, a clone?
 
-That's also doable, but a little bit more difficult, because there's no built-in method for that in JavaScript. Actually, that's rarely needed. Copying by reference is good most of the time.
+That's also doable, but a little bit more difficult, because there's no built-in method for that in JavaScript. But there is rarely a need -- copying by reference is good most of the time.
 
 But if we really want that, then we need to create a new object and replicate the structure of the existing one by iterating over its properties and copying them on the primitive level.
 
@@ -226,13 +225,37 @@ user.sizes.width++;       // change a property from one place
 alert(clone.sizes.width); // 51, see the result from the other one
 ```
 
-To fix that, we should use the cloning loop that examines each value of `user[key]` and, if it's an object, then replicate its structure as well. That is called a "deep cloning".
+To fix that, we should use a cloning loop that examines each value of `user[key]` and, if it's an object, then replicate its structure as well. That is called a "deep cloning".
+
+We can use recursion to implement it. Or, to not reinvent the wheel, take an existing implementation, for instance [_.cloneDeep(obj)](https://lodash.com/docs#cloneDeep) from the JavaScript library [lodash](https://lodash.com).
+
+````smart header="Const objects can be modified"
+An important side effect of storing objects as references is that an object declared as `const` *can* be modified.
+
+For instance:
+
+```js run
+const user = {
+  name: "John"
+};
+
+*!*
+user.name = "Pete"; // (*)
+*/!*
+
+alert(user.name); // Pete
+```
+
+It might seem that the line `(*)` would cause an error, but it does not. The value of `user` is constant, it must always reference the same object, but properties of that object are free to change.
+
+In other words, the `const user` gives an error only if we try to set `user=...` as a whole.
 
-We can use recursion to implement it. Or, not to reinvent the wheel, take an existing implementation, for instance [_.cloneDeep(obj)](https://lodash.com/docs#cloneDeep) from the JavaScript library [lodash](https://lodash.com).
+That said, if we really need to make constant object properties, it's also possible, but using totally different methods. We'll mention that in the chapter <info:property-descriptors>.
+````
 
 ## Summary
 
-Objects are assigned and copied by reference. In other words, a variable stores not the "object value", but a "reference" (address in memory) for the value. So copying such a variable or passing it as a function argument copies that reference, not the object.
+Objects are assigned and copied by reference. In other words, a variable stores not the "object value", but a "reference" (address in memory) for the value. So copying such a variable or passing it as a function argument copies that reference, not the object itself.
 
 All operations via copied references (like adding/removing properties) are performed on the same single object.
 

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

@@ -23,7 +23,7 @@ Simply put, "reachable" values are those that are accessible or usable somehow.
 
 2. Any other value is considered reachable if it's reachable from a root by a reference or by a chain of references.
 
-    For instance, if there's an object in a global variable, and that object has a property referencing another object, that object is considered reachable. And those that it references are also reachable. Detailed examples to follow.
+    For instance, if there's an object in a global variable, and that object has a property referencing another object, *that* object is considered reachable. And those that it references are also reachable. Detailed examples to follow.
 
 There's a background process in the JavaScript engine that is called [garbage collector](https://en.wikipedia.org/wiki/Garbage_collection_(computer_science)). It monitors all objects and removes those that have become unreachable.
 

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

@@ -9,51 +9,89 @@ The optional chaining `?.` is a safe way to access nested object properties, eve
 
 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.
 
-As an example, let's 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. 
+As an example, let's say we have `user` objects that hold the information about our users. 
 
-In such case, when we attempt to get `user.address.street`, we'll get an error:
+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`, and the user happens to be without an address, we get an error:
 
 ```js run
-let user = {}; // the user without "address" property
+let user = {}; // a user without "address" property
 
 alert(user.address.street); // Error!
 ```
 
-That's the expected result, JavaScript works like this, but many practical cases we'd prefer to get `undefined` instead of an error (meaning "no street").
+That's the expected result. JavaScript works like this. As `user.address` is `undefined`, an attempt to get `user.address.street` fails with an error. 
+
+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 to get an information about an element on the page, that sometimes doesn't exist:
+...And another example. In the web development, we can get an object that corresponds to a web page element using a special method call, such as `document.querySelector('.elem')`, and it returns `null` when there's no such element.
 
 ```js run
-// Error if the result of querySelector(...) is null
-let html = document.querySelector('.my-element').innerHTML;
+// document.querySelector('.elem') is null if there's no element
+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, if the element doesn't exist, we'll get an error accessing `.innerHTML` of `null`. And in some cases, when the absence of the element is normal, we'd like to avoid the error and just accept `html = null` as the result.
 
-For example:
+How can we do this?
+
+The obvious solution would be to check the value using `if` or the conditional operator `?`, before accessing its property, like this:
+
+```js
+let user = {};
+
+alert(user.address ? user.address.street : undefined);
+```
+
+It works, there's no error... But it's quite inelegant. As you can see, the `"user.address"` appears twice in the code. For more deeply nested properties, that becomes a problem as more repetitions are required.
+
+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's just awful, one may even have problems understanding such code. 
+
+Don't even care to, as there's a better way to write it, using the `&&` operator:
 
 ```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 (if not, the evaluation stops), 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, property names are still duplicated in the code. E.g. in the code above, `user.address` appears three times.
+
+That's why the optional chaining `?.` was added to the language. To solve this problem once and for all!
 
 ## Optional chaining
 
-The optional chaining `?.` stops the evaluation and returns `undefined` if the part before `?.` is `undefined` or `null`.
+The optional chaining `?.` stops the evaluation if the part before `?.` is `undefined` or `null` and returns that part.
 
 **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`:
+In other words, `value?.prop`:
+- is the same as `value.prop` if `value` exists,
+- otherwise (when `value` is `undefined/null`) it returns `undefined`.
+
+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
@@ -65,14 +103,12 @@ 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`.
-
-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.
+E.g. in `user?.address.street.name` the `?.` allows `user` to be `null/undefined`, but it's all it does. Further properties are accessed in a regular way. If we want some of them to be optional, then we'll need to replace more `.` with `?.`.
 
 ```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 see a programming error about it and fix it. Otherwise, coding errors can be silenced where not appropriate, and become more difficult to debug.
 ```
@@ -84,7 +120,7 @@ If there's no variable `user` at all, then `user?.anything` triggers an error:
 // ReferenceError: user is not defined
 user?.address;
 ```
-There must be a declaration (e.g. `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
@@ -113,17 +149,20 @@ For example, `?.()` is used to call a function that may not exist.
 In the code below, some of our users have `admin` method, and some don't:
 
 ```js run
-let user1 = {
+let userAdmin = {
   admin() {
     alert("I am admin");
   }
-}
+};
 
-let user2 = {};
+let userGuest = {};
+
+*!*
+userAdmin.admin?.(); // I am admin
+*/!*
 
 *!*
-user1.admin?.(); // I am admin
-user2.admin?.();
+userGuest.admin?.(); // nothing (no such method)
 */!*
 ```