Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-ec21af8a

Author: iliakan

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

@@ -212,7 +212,7 @@ But we can force the exit at any time using the special `break` directive.
 
 For example, the loop below asks the user for a series of numbers, "breaking" when no number is entered:
 
-```js
+```js run
 let sum = 0;
 
 while (true) {

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

@@ -350,7 +350,7 @@ welcome(); // ok now
 ```smart header="When to choose Function Declaration versus Function Expression?"
 As a rule of thumb, when we need to declare a function, the first to consider is Function Declaration syntax. It gives more freedom in how to organize our code, because we can call such functions before they are declared.
 
-That's also better for readability, as it's easier to look up `function f(…) {…}` in the code than `let f = function(…) {…}`. Function Declarations are more "eye-catching".
+That's also better for readability, as it's easier to look up `function f(…) {…}` in the code than `let f = function(…) {…};`. Function Declarations are more "eye-catching".
 
 ...But if a Function Declaration does not suit us for some reason, or we need a conditional declaration (we've just seen an example), then Function Expression should be used.
 ```

1-js/03-code-quality/01-debugging-chrome/article.md

@@ -139,7 +139,7 @@ There are buttons for it at the top of the right panel. Let's engage them.
 <span class="devtools" style="background-position:-62px -192px"></span> -- "Step over": run the next command, but *don't go into a function*, hotkey `key:F10`.
 : Similar to the previous the "Step" command, but behaves differently if the next statement is a function call. That is: not a built-in, like `alert`, but a function of our own.
 
-    The "Step" command goes into it and and pauses the execution at its first line, while "Step over" executes the nested function call invisibly, skipping the function internals.
+    The "Step" command goes into it and pauses the execution at its first line, while "Step over" executes the nested function call invisibly, skipping the function internals.
 
     The execution is then paused immediately after that function.
 >>>>>>> a0bfa924a17cad8e7fee213904b27dbf57c2dbac

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

@@ -46,21 +46,27 @@ There are three variants of type conversion, so-called "hints", described in the
 `"default"`
 : Occurs in rare cases when the operator is "not sure" what type to expect.
 
-    For instance, binary plus `+` can work both with strings (concatenates them) and numbers (adds them), so both strings and numbers would do. Or when an object is compared using `==` with a string, number or a symbol, it's also unclear which conversion should be done.
+    For instance, binary plus `+` can work both with strings (concatenates them) and numbers (adds them), so both strings and numbers would do. So if the a binary plus gets an object as an argument, it uses the `"default"` hint to convert it.
+
+    Also, if an object is compared using `==` with a string, number or a symbol, it's also unclear which conversion should be done, so the `"default"` hint is used.
 
     ```js
-    // binary plus
-    let total = car1 + car2;
+    // binary plus uses the "default" hint
+    let total = obj1 + obj2;
 
-    // obj == string/number/symbol
+    // obj == number uses the "default" hint
     if (user == 1) { ... };
     ```
 
-    The greater/less operator `<>` can work with both strings and numbers too. Still, it uses "number" hint, not "default". That's for historical reasons.
+    The greater and less comparison operators, such as `<` `>`, can work with both strings and numbers too. Still, they use the `"number"` hint, not `"default"`. That's for historical reasons.
+
+    In practice though, we don't need to remember these peculiar details, because all built-in objects except for one case (`Date` object, we'll learn it later) implement `"default"` conversion the same way as `"number"`. And we can do the same.
 
-    In practice, all built-in objects except for one case (`Date` object, we'll learn it later) implement `"default"` conversion the same way as `"number"`. And probably we should do the same.
+```smart header="No `\"boolean\"` hint"
+Please note -- there are only three hints. It's that simple.
 
-Please note -- there are only three hints. It's that simple. There is no "boolean" hint (all objects are `true` in boolean context) or anything else. And if we treat `"default"` and `"number"` the same, like most built-ins do, then there are only two conversions.
+There is no "boolean" hint (all objects are `true` in boolean context) or anything else. And if we treat `"default"` and `"number"` the same, like most built-ins do, then there are only two conversions.
+```
 
 **To do the conversion, JavaScript tries to find and call three object methods:**
 
@@ -112,7 +118,29 @@ If there's no `Symbol.toPrimitive` then JavaScript tries to find them and try in
 - `toString -> valueOf` for "string" hint.
 - `valueOf -> toString` otherwise.
 
-For instance, here `user` does the same as above using a combination of `toString` and `valueOf`:
+These methods must return a primitive value. If `toString` or `valueOf` returns an object, then it's ignored (same as if there were no method).
+
+By default, a plain object has following `toString` and `valueOf` methods:
+
+- The `toString` method returns a string `"[object Object]"`.
+- The `valueOf` method returns an object itself.
+
+Here's the demo:
+
+```js run
+let user = {name: "John"};
+
+alert(user); // [object Object]
+alert(user.valueOf() === user); // true
+```
+
+So if we try to use an object as a string, like in an `alert` or so, then by default we see `[object Object]`.
+
+And the default `valueOf` is mentioned here only for the sake of completeness, to avoid any confusion. As you can see, it returns the object itself, and so is ignored. Don't ask me why, that's for historical reasons. So we can assume it doesn't exist.
+
+Let's implement these methods.
+
+For instance, here `user` does the same as above using a combination of `toString` and `valueOf` instead of `Symbol.toPrimitive`:
 
 ```js run
 let user = {
@@ -159,7 +187,7 @@ In the absence of `Symbol.toPrimitive` and `valueOf`, `toString` will handle all
 
 The important thing to know about all primitive-conversion methods is that they do not necessarily return the "hinted" primitive.
 
-There is no control whether `toString()` returns exactly a string, or whether `Symbol.toPrimitive` method returns a number for a hint "number".
+There is no control whether `toString` returns exactly a string, or whether `Symbol.toPrimitive` method returns a number for a hint `"number"`.
 
 The only mandatory thing: these methods must return a primitive, not an object.
 
@@ -169,35 +197,41 @@ For historical reasons, if `toString` or `valueOf` returns an object, there's no
 In contrast, `Symbol.toPrimitive` *must* return a primitive, otherwise there will be an error.
 ```
 
-## Further operations
+## Further conversions
 
-An operation that initiated the conversion gets the primitive, and then continues to work with it, applying further conversions if necessary.
+As we know already, many operators and functions perform type conversions, e.g. multiplication `*` converts operatnds to numbers.
+
+If we pass an object as an argument, then there are two stages:
+1. The object is converted to a primitive (using the rules described above).
+2. If the resulting primitive isn't of the right type, it's converted.
 
 For instance:
 
-- Mathematical operations, except binary plus, convert the primitive to a number:
+```js run
+let obj = {
+  // toString handles all conversions in the absence of other methods
+  toString() {
+    return "2";
+  }
+};
 
-    ```js run
-    let obj = {
-      // toString handles all conversions in the absence of other methods
-      toString() {
-        return "2";
-      }
-    };
+alert(obj * 2); // 4, object converted to primitive "2", then multiplication made it a number
+```
 
-    alert(obj * 2); // 4, object converted to primitive "2", then multiplication made it a number
-    ```
+1. The multiplication `obj * 2` first converts the object to primitive (that's a string `"2"`).
+2. Then `"2" * 2` becomes `2 * 2` (the string is converted to number).
 
-- Binary plus will concatenate strings in the same situation:
-    ```js run
-    let obj = {
-      toString() {
-        return "2";
-      }
-    };
+Binary plus will concatenate strings in the same situation, as it gladly accepts a string:
 
-    alert(obj + 2); // 22 (conversion to primitive returned a string => concatenation)
-    ```
+```js run
+let obj = {
+  toString() {
+    return "2";
+  }
+};
+
+alert(obj + 2); // 22 ("2" + 2), conversion to primitive returned a string => concatenation
+```
 
 ## Summary
 

1-js/05-data-types/03-string/article.md

@@ -394,7 +394,7 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
 
     ```js run
     let str = "st*!*ringify*/!*";
-    alert( str.slice(2) ); // ringify, from the 2nd position till the end
+    alert( str.slice(2) ); // 'ringify', from the 2nd position till the end
     ```
 
     Negative values for `start/end` are also possible. They mean the position is counted from the string end:
@@ -403,7 +403,7 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
     let str = "strin*!*gif*/!*y";
 
     // start at the 4th position from the right, end at the 1st from the right
-    alert( str.slice(-4, -1) ); // gif
+    alert( str.slice(-4, -1) ); // 'gif'
     ```
 
 `str.substring(start [, end])`
@@ -435,14 +435,14 @@ There are 3 methods in JavaScript to get a substring: `substring`, `substr` and
 
     ```js run
     let str = "st*!*ring*/!*ify";
-    alert( str.substr(2, 4) ); // ring, from the 2nd position get 4 characters
+    alert( str.substr(2, 4) ); // 'ring', from the 2nd position get 4 characters
     ```
 
     The first argument may be negative, to count from the end:
 
     ```js run
     let str = "strin*!*gi*/!*fy";
-    alert( str.substr(-4, 2) ); // gi, from the 4th position get 2 characters
+    alert( str.substr(-4, 2) ); // 'gi', from the 4th position get 2 characters
     ```
 
 Let's recap these methods to avoid any confusion:

1-js/05-data-types/05-array-methods/6-calculator-extendable/solution.md

@@ -1,5 +1,3 @@
 
 - Please note how methods are stored. They are simply added to `this.methods` property.
 - All tests and numeric conversions are done in the `calculate` method. In future it may be extended to support more complex expressions.
-
-[js src="_js/solution.js"]

1-js/05-data-types/05-array-methods/article.md

@@ -36,7 +36,7 @@ That's natural, because `delete obj.key` removes a value by the `key`. It's all
 
 So, special methods should be used.
 
-The [arr.splice(str)](mdn:js/Array/splice) method is a swiss army knife for arrays. It can do everything: insert, remove and replace elements.
+The [arr.splice(start)](mdn:js/Array/splice) method is a swiss army knife for arrays. It can do everything: insert, remove and replace elements.
 
 The syntax is:
 
@@ -268,7 +268,7 @@ alert( arr.includes(NaN) );// true (correct)
 
 Imagine we have an array of objects. How do we find an object with the specific condition?
 
-Here the [arr.find](mdn:js/Array/find) method comes in handy.
+Here the [arr.find(fn)](mdn:js/Array/find) method comes in handy.
 
 The syntax is:
 ```js
@@ -574,7 +574,7 @@ The calculation flow:
 
 Or in the form of a table, where each row represents a function call on the next array element:
 
-|   |`sum`|`current`|`result`|
+|   |`sum`|`current`|result|
 |---|-----|---------|---------|
 |the first call|`0`|`1`|`1`|
 |the second call|`1`|`2`|`3`|

1-js/05-data-types/06-iterable/article.md

@@ -142,15 +142,17 @@ for (let char of str) {
 
 For deeper understanding let's see how to use an iterator explicitly.
 
-We'll iterate over a string in exactlly the same way as `for..of`, but with direct calls. This code creates a string iterator and gets values from it "manually":
+We'll iterate over a string in exactly the same way as `for..of`, but with direct calls. This code creates a string iterator and gets values from it "manually":
 
 ```js run
 let str = "Hello";
 
 // does the same as
 // for (let char of str) alert(char);
 
+*!*
 let iterator = str[Symbol.iterator]();
+*/!*
 
 while (true) {
   let result = iterator.next();
@@ -268,7 +270,7 @@ for (let char of str) {
 alert(chars);
 ```
 
-...But is shorter.    
+...But it is shorter.    
 
 We can even build surrogate-aware `slice` on it:
 

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

@@ -11,7 +11,7 @@ They are supported for:
 
 - `Map`
 - `Set`
-- `Array` (except `arr.values()`)
+- `Array`
 
 Plain objects also support similar methods, but the syntax is a bit different.
 

1-js/05-data-types/10-destructuring-assignment/article.md

@@ -187,7 +187,7 @@ The destructuring assignment also works with objects.
 The basic syntax is:
 
 ```js
-let {var1, var2} = {var1:…, var2…}
+let {var1, var2} = {var1:…, var2:…}
 ```
 
 We have an existing object at the right side, that we want to split into variables. The left side contains a "pattern" for corresponding properties. In the simple case, that's a list of variable names in `{...}`.

1-js/05-data-types/12-json/article.md

@@ -425,9 +425,9 @@ alert( numbers[1] ); // 1
 Or for nested objects:
 
 ```js run
-let user = '{ "name": "John", "age": 35, "isAdmin": false, "friends": [0,1,2,3] }';
+let userData = '{ "name": "John", "age": 35, "isAdmin": false, "friends": [0,1,2,3] }';
 
-user = JSON.parse(user);
+let user = JSON.parse(userData);
 
 alert( user.friends[1] ); // 1
 ```

1-js/06-advanced-functions/01-recursion/article.md

@@ -459,6 +459,7 @@ let list = { value: 1 };
 list.next = { value: 2 };
 list.next.next = { value: 3 };
 list.next.next.next = { value: 4 };
+list.next.next.next.next = null;
 ```
 
 Here we can even more clearer see that there are multiple objects, each one has the `value` and `next` pointing to the neighbour. The `list` variable is the first object in the chain, so following `next` pointers from it we can reach any element.

1-js/06-advanced-functions/03-closure/article.md

@@ -351,7 +351,7 @@ Please note the additional `[[Environment]]` property is covered here. We didn't
 
     ![](lexenv-nested-makecounter-3.svg)
 
-    Please note that on this step the inner function was created, but not yet called. The code inside `function() { return count++; }` is not running.
+    Please note that on this step the inner function was created, but not yet called. The code inside `return count++;` is not running.
 
 4. As the execution goes on, the call to `makeCounter()` finishes, and the result (the tiny nested function) is assigned to the global variable `counter`:
 
@@ -576,7 +576,8 @@ function f() {
 */!*
 }
 
-let g = f(); // g is reachable, and keeps the outer lexical environment in memory
+let func = f(); // func gets a reference to g
+// so it stays and memory and its outer lexical environment stays as well
 ```
 
 Please note that if `f()` is called many times, and resulting functions are saved, then all corresponding Lexical Environment objects will also be retained in memory. All 3 of them in the code below:
@@ -606,10 +607,9 @@ function f() {
   return g;
 }
 
-let g = f(); // while g is alive
-// their corresponding Lexical Environment lives
+let func = f(); // while func has a reference to g, it stays in memory
 
-g = null; // ...and now the memory is cleaned up
+func = null; // ...and now the memory is cleaned up
 ```
 
 ### Real-life optimizations

1-js/06-advanced-functions/08-settimeout-setinterval/article.md

@@ -61,7 +61,7 @@ So, this will also work:
 setTimeout("alert('Hello')", 1000);
 ```
 
-But using strings is not recommended, use functions instead of them, like this:
+But using strings is not recommended, use arrow functions instead of them, like this:
 
 ```js run no-beautify
 setTimeout(() => alert('Hello'), 1000);
@@ -184,7 +184,7 @@ Let's compare two code fragments. The first one uses `setInterval`:
 ```js
 let i = 1;
 setInterval(function() {
-  func(i);
+  func(i++);
 }, 100);
 ```
 
@@ -193,12 +193,12 @@ The second one uses nested `setTimeout`:
 ```js
 let i = 1;
 setTimeout(function run() {
-  func(i);
+  func(i++);
   setTimeout(run, 100);
 }, 100);
 ```
 
-For `setInterval` the internal scheduler will run `func(i)` every 100ms:
+For `setInterval` the internal scheduler will run `func(i++)` every 100ms:
 
 ![](setinterval-interval.svg)
 

1-js/06-advanced-functions/09-call-apply-decorators/04-throttle/_js.view/test.js

@@ -44,4 +44,20 @@ describe("throttle(f, 1000)", function() {
     this.clock.restore();
   });
 
-});
+});
+
+describe('throttle', () => {
+
+  it('runs a forwarded call once', done => {
+    let log = '';
+    const f = str => log += str;
+    const f10 = throttle(f, 10);
+    f10('once');
+
+    setTimeout(() => {
+      assert.equal(log, 'once');
+      done();
+    }, 20);
+  });
+
+});