Sync with upstream @ c56e6a57

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?
 
@@ -110,12 +110,12 @@ Examples of such languages:
 - [TypeScript](http://www.typescriptlang.org/) is concentrated on adding "strict data typing" to simplify the development and support of complex systems. It is developed by Microsoft.
 - [Flow](http://flow.org/) also adds data typing, but in a different way. Developed by Facebook.
 - [Dart](https://www.dartlang.org/) is a standalone language that has its own engine that runs in non-browser environments (like mobile apps), but also can be transpiled to JavaScript. Developed by Google.
-- [Brython](https://brython.info/) is a Python transpiler to JavaScript that allow to write application in pure Python without JavaScript.
+- [Brython](https://brython.info/) is a Python transpiler to JavaScript that enables the writing of applications in pure Python without JavaScript.
 
 There are more. Of course, even if we use one of transpiled languages, we should also know JavaScript to really understand what we're doing.
 
 ## 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/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/02-first-steps/04-variables/2-declare-variables/solution.md

@@ -6,7 +6,7 @@ That's simple:
 let ourPlanetName = "Earth";
 ```
 
-Note, we could use a shorter name `planet`, but it might be not obvious what planet it refers to. It's nice to be more verbose. At least until the variable isNotTooLong.
+Note, we could use a shorter name `planet`, but it might not be obvious what planet it refers to. It's nice to be more verbose. At least until the variable isNotTooLong.
 
 ## The name of the current visitor
 

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/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

@@ -1,5 +1,5 @@
 
-# Polyfills
+# Polyfills and transpilers
 
 The JavaScript language steadily evolves. New proposals to the language appear regularly, they are analyzed and, if considered worthy, are appended to the list at <https://tc39.github.io/ecma262/> and then progress to the [specification](http://www.ecma-international.org/publications/standards/Ecma-262.htm).
 
@@ -9,46 +9,84 @@ So it's quite common for an engine to implement only the part of the standard.
 
 A good page to see the current state of support for language features is <https://kangax.github.io/compat-table/es6/> (it's big, we have a lot to study yet).
 
-## Babel
+As programmers, we'd like to use most recent features. The more good stuff - the better!
 
-When we use modern features of the language, some engines may fail to support such code. Just as said, not all features are implemented everywhere.
+From the other hand, how to make out modern code work on older engines that don't understand recent features yet?
 
-Here Babel comes to the rescue.
+There are two tools for that:
 
-[Babel](https://babeljs.io) is a [transpiler](https://en.wikipedia.org/wiki/Source-to-source_compiler). It rewrites modern JavaScript code into the previous standard.
+1. Transpilers.
+2. Polyfills.
 
-Actually, there are two parts in Babel:
+Here, in this chapter, our purpose is to get the gist of how they work, and their place in web development.
 
-1. First, the transpiler program, which rewrites the code. The developer runs it on their own computer. It rewrites the code into the older standard. And then the code is delivered to the website for users. Modern project build systems like [webpack](http://webpack.github.io/) provide means to run transpiler automatically on every code change, so that it's very easy to integrate into development process.
+## Transpilers
 
-2. Second, the polyfill.
+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.
 
-    New language features may include new built-in functions and syntax constructs.
-    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.
+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`.
 
-    A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.
+A transpiler would analyze our code and rewrite `height ?? 100` into `(height !== undefined && height !== null) ? height : 100`.
 
-    Two interesting polyfills are:
-    - [core js](https://github.com/zloirock/core-js) that supports a lot, allows to include only needed features.
-    - [polyfill.io](http://polyfill.io) service that provides a script with polyfills, depending on the features and user's browser.
+```js
+// before running the transpiler
+height = height ?? 100;
 
-So, if we're going to use modern language features, a transpiler and a polyfill are necessary.
+// after running the transpiler
+height = (height !== undefined && height !== null) ? height : 100;
+```
 
-## Examples in the tutorial
+Now the rewritten code is suitable for older JavaScript engines.
 
+Usually, a developer runs the transpiler on their own computer, and then deploys the transpiled code to the server.
 
-````online
-Most examples are runnable at-place, like this:
+Speaking of names, [Babel](https://babeljs.io) is one of the most prominent transpilers out there. 
 
-```js run
-alert('Press the "Play" button in the upper-right corner to run');
-```
+Modern project build systems, such as [webpack](http://webpack.github.io/), provide means to run transpiler automatically on every code change, so it's very easy to integrate into development process.
+
+## Polyfills
+
+New language features may include not only syntax constructs and operators, but also built-in functions.
+
+For example, `Math.trunc(n)` is a function that "cuts off" the decimal part of a number, e.g `Math.trunc(1.23) = 1`.
 
-Examples that use modern JS will work only if your browser supports it.
-````
+In some (very outdated) JavaScript engines, there's no `Math.trunc`, so such code will fail.
 
-```offline
-As you're reading the offline version, in PDF examples are not runnable. In EPUB some of them can run.
+As we're talking about new functions, not syntax changes, there's no need to transpile anything here. We just need to declare the missing function.
+
+A script that updates/adds new functions is called "polyfill". It "fills in" the gap and adds missing implementations.
+
+For this particular case, the polyfill for `Math.trunc` is a script that implements it, like this:
+
+```js
+if (!Math.trunc) { // if no such function
+  // implement it
+  Math.trunc = function(number) {
+    // Math.ceil and Math.floor exist even in ancient JavaScript engines
+    // they are covered later in the tutorial
+    return number < 0 ? Math.ceil(number) : Math.floor(number);
+  };
+}
 ```
 
-Google Chrome is usually the most up-to-date with language features, good to run bleeding-edge demos without any transpilers, but other modern browsers also work fine.
+JavaScript is a highly dynamic language, scripts may add/modify any functions, even including built-in ones. 
+
+Two interesting libraries of polyfills are:
+- [core js](https://github.com/zloirock/core-js) that supports a lot, allows to include only needed features.
+- [polyfill.io](http://polyfill.io) service that provides a script with polyfills, depending on the features and user's browser.
+
+
+## Summary
+
+In this chapter we'd like to motivate you to study modern and even "bleeding-edge" langauge features, even if they aren't yet well-supported by JavaScript engines.
+
+Just don't forget to use transpiler (if using modern syntax or operators) and polyfills (to add functions that may be missing). And they'll ensure that the code works.
+
+For example, later when you're familiar with JavaScript, you can setup a code build system based on [webpack](http://webpack.github.io/) with [babel-loader](https://github.com/babel/babel-loader) plugin.
+
+Good resources that show the current state of support for various features:
+- <https://kangax.github.io/compat-table/es6/> - for pure JavaScript.
+- <https://caniuse.com/> - for browser-related functions.
+
+P.S. Google Chrome is usually the most up-to-date with language features, try it if a tutorial demo fails. Most tutorial demos work with any modern browser though.
+

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/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,37 +1,49 @@
-# 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", whereas primitive values: strings, numbers, booleans, etc -- 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 the hood 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!";
 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 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 a 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 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`, the JavaScript engine looks at what's at that address and performs the operation on the actual object.
 
-**When an object variable is copied -- the reference is copied, the object is not duplicated.**
+Now here's why it's important.
+
+**When an object variable is copied, the reference is copied, but the object itself is not duplicated.**
 
 For instance:
 
@@ -41,11 +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)
 
-We can use any variable to access the object and modify its contents:
+As you can see, there's still one object, but now with two variables that reference it.
+
+We can use either variable to access the object and modify its contents:
 
 ```js run
 let user = { name: 'John' };
@@ -59,15 +73,13 @@ 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.
+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
 
-The equality `==` and strict equality `===` operators for objects work exactly the same.
-
-**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 +89,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,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 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
 
 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.
 
@@ -213,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.