Merge branch 'master' into patch-1

Author: iliakan

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/05-data-types/04-array/10-maximal-subarray/solution.md

@@ -57,7 +57,7 @@ alert( getMaxSubSum([1, 2, 3]) ); // 6
 alert( getMaxSubSum([100, -9, 2, -3, 5]) ); // 100
 ```
 
-The solution has a time complexety of [O(n<sup>2</sup>)](https://en.wikipedia.org/wiki/Big_O_notation). In other words, if we increase the array size 2 times, the algorithm will work 4 times longer.
+The solution has a time complexity of [O(n<sup>2</sup>)](https://en.wikipedia.org/wiki/Big_O_notation). In other words, if we increase the array size 2 times, the algorithm will work 4 times longer.
 
 For big arrays (1000, 10000 or more items) such algorithms can lead to a serious sluggishness.
 

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

@@ -209,7 +209,7 @@ arr.push("Pear"); // modify the array by reference
 alert( fruits ); // Banana, Pear - 2 items now
 ```
 
-...But what makes arrays really  special is their internal representation. The engine tries to store its elements in the contiguous memory area, one after another, just as depicted on the illustrations in this chapter, and there are other optimizations as well, to make arrays work really fast.
+...But what makes arrays really special is their internal representation. The engine tries to store its elements in the contiguous memory area, one after another, just as depicted on the illustrations in this chapter, and there are other optimizations as well, to make arrays work really fast.
 
 But they all break if we quit working with an array as with an "ordered collection" and start working with it as if it were a regular object.
 

1-js/05-data-types/08-weakmap-weakset/article.md

@@ -207,7 +207,7 @@ alert(cache.size); // 1 (Ouch! The object is still in cache, taking memory!)
 
 For multiple calls of `process(obj)` with the same object, it only calculates the result the first time, and then just takes it from `cache`. The downside is that we need to clean `cache` when the object is not needed any more.
 
-If we replace `Map` with `WeakMap`, then this problem disappears. The cached result will be removed from memory automatically after the object gets garbage collected .
+If we replace `Map` with `WeakMap`, then this problem disappears. The cached result will be removed from memory automatically after the object gets garbage collected.
 
 ```js run
 // 📁 cache.js
@@ -284,7 +284,8 @@ The most notable limitation of `WeakMap` and `WeakSet` is the absence of iterati
 
 `WeakSet` is `Set`-like collection that stores only objects and removes them once they become inaccessible by other means.
 
-It's main advantages are that they have weak reference to objects, so they can easily be removed by garbage collector. 
-That comes at the cost of not having support for `clear`, `size`, `keys`, `values` ...
+Their main advantages are that they have weak reference to objects, so they can easily be removed by garbage colector.
+
+That comes at the cost of not having support for `clear`, `size`, `keys`, `values`...
 
 `WeakMap` and `WeakSet` are used as "secondary" data structures in addition to the "primary" object storage. Once the object is removed from the primary storage, if it is only found as the key of `WeakMap` or in a `WeakSet`, it will be cleaned up automatically.

1-js/11-async/05-promise-api/article.md

@@ -219,7 +219,7 @@ The first promise here was fastest, so it became the result. After the first set
 
 ## Promise.any
 
-Similar to `Promise.race`, but waits only for the first fulfilled promise and gets its result. If all of the given promises are rejected, then the returned promise is rejected.
+Similar to `Promise.race`, but waits only for the first fulfilled promise and gets its result. If all of the given promises are rejected, then the returned promise is rejected with [`AggregateError`](mdn:js/AggregateError) - a special error object that stores all promise errors in its `errors` property.
 
 The syntax is:
 
@@ -239,6 +239,20 @@ Promise.any([
 
 The first promise here was fastest, but it was rejected, so the second promise became the result. After the first fulfilled promise "wins the race", all further results are ignored.
 
+Here's an example when all promises fail:
+
+```js run
+Promise.any([
+  new Promise((resolve, reject) => setTimeout(() => reject(new Error("Ouch!")), 1000)),
+  new Promise((resolve, reject) => setTimeout(() => reject(new Error("Error!")), 2000))
+]).catch(error => {
+  console.log(error.constructor.name); // AggregateError
+  console.log(error.errors[0]); // Error: Ouch!
+  console.log(error.errors[1]); // Error: Error
+});
+```
+
+As you can see, error objects for failed promises are available in the `errors` property of the `AggregateError` object.
 
 ## Promise.resolve/reject
 
@@ -302,7 +316,7 @@ There are 5 static methods of `Promise` class:
     - `status`: `"fulfilled"` or `"rejected"`
     - `value` (if fulfilled) or `reason` (if rejected).
 3. `Promise.race(promises)` -- waits for the first promise to settle, and its result/error becomes the outcome.
-4. `Promise.any(promises)` -- waits for the first promise to fulfill, and its result becomes the outcome. If all of the given promises rejects, it becomes the error of `Promise.any`.
+4. `Promise.any(promises)` -- waits for the first promise to fulfill, and its result becomes the outcome. If all of the given promises are rejected, [`AggregateError`](mdn:js/AggregateError) becomes the error of `Promise.any`.
 5. `Promise.resolve(value)` -- makes a resolved promise with the given value.
 6. `Promise.reject(error)` -- makes a rejected promise with the given error.
 

1-js/99-js-misc/01-proxy/article.md

@@ -969,7 +969,7 @@ Initially, `revoke` is separate from `proxy`, so that we can pass `proxy` around
 
 We can also bind `revoke` method to proxy by setting `proxy.revoke = revoke`.
 
-Another option is to create a `WeakMap` that has `proxy` as the key the corresponding `revoke` as the value, that allows to easily find `revoke` for a proxy:
+Another option is to create a `WeakMap` that has `proxy` as the key and the corresponding `revoke` as the value, that allows to easily find `revoke` for a proxy:
 
 ```js run
 *!*

2-ui/1-document/07-modifying-document/10-clock-setinterval/solution.md

@@ -39,15 +39,19 @@ The clock-managing functions:
 ```js
 let timerId;
 
-function clockStart() { // run the clock
-  timerId = setInterval(update, 1000);
+function clockStart() { // run the clock  
+  if (!timerId) { // only set a new interval if the clock is not running
+    timerId = setInterval(update, 1000);
+  }
   update(); // (*)
 }
 
 function clockStop() {
   clearInterval(timerId);
-  timerId = null;
+  timerId = null; // (**)
 }
 ```
 
 Please note that the call to `update()` is not only scheduled in `clockStart()`, but immediately run in the line `(*)`. Otherwise the visitor would have to wait till the first execution of `setInterval`. And the clock would be empty till then.
+
+Also it is important to set a new interval in `clockStart()` only when the clock is not running. Otherways clicking the start button several times would set multiple concurrent intervals. Even worse - we would only keep the `timerID` of the last interval, losing references to all others. Then we wouldn't be able to stop the clock ever again! Note that we need to clear the `timerID` when the clock is stopped in the line `(**)`, so that it can be started again by running `clockStart()`.

2-ui/1-document/07-modifying-document/10-clock-setinterval/solution.view/index.html

@@ -43,12 +43,17 @@
     }
 
     function clockStart() {
-      timerId = setInterval(update, 1000);
+      // set a new interval only if the clock is stopped
+      // otherwise we would rewrite the timerID reference to the running interval and wouldn't be able to stop the clock ever again
+      if (!timerId) { 
+        timerId = setInterval(update, 1000);
+      }
       update(); // <--  start right now, don't wait 1 second till the first setInterval works
     }
 
     function clockStop() {
       clearInterval(timerId);
+      timerId = null; // <-- clear timerID to indicate that the clock has been stopped, so that it is possible to start it again in clockStart()
     }
 
     clockStart();

2-ui/99-ui-misc/02-selection-range/article.md

@@ -8,33 +8,36 @@ libs:
 
 In this chapter we'll cover selection in the document, as well as selection in form fields, such as `<input>`.
 
-JavaScript can get the existing selection, select/deselect both as a whole or partially, remove the selected part from the document, wrap it into a tag, and so on.
+JavaScript can access an existing selection, select/deselect DOM nodes as a whole or partially, remove the selected content from the document, wrap it into a tag, and so on.
 
-You can get ready to use recipes at the end, in "Summary" section. But you'll get much more if you read the whole chapter. The underlying `Range` and `Selection` objects are easy to grasp, and then you'll need no recipes to make them do what you want.
+You can find some recipes for common tasks at the end of the chapter, in "Summary" section. Maybe that covers your current needs, but you'll get much more if you read the whole text.
 
-## Range
-
-The basic concept of selection is [Range](https://dom.spec.whatwg.org/#ranges): basically, a pair of "boundary points": range start and range end.
+The underlying `Range` and `Selection` objects are easy to grasp, and then you'll need no recipes to make them do what you want.
 
-Each point represented as a parent DOM node with the relative offset from its start. If the parent node is an element node, then the offset is a child number, for a text node it's the position in the text. Examples to follow.
+## Range
 
-Let's select something.
+The basic concept of selection is [Range](https://dom.spec.whatwg.org/#ranges), that is essentially a pair of "boundary points": range start and range end.
 
-First, we can create a range (the constructor has no parameters):
+A `Range` object is created without parameters:
 
 ```js
 let range = new Range();
 ```
 
 Then we can set the selection boundaries using `range.setStart(node, offset)` and `range.setEnd(node, offset)`.
 
-For example, consider this fragment of HTML:
+The first argument `node` can be either a text node or an element node. The meaning of the second argument depends on that:
+
+- If `node` is a text node, then `offset` must be the position in the text.
+- If `node` is an element node, then `offset` must be the child number.
+
+For example, let's create a range in this fragment:
 
-```html
+```html autorun
 <p id="p">Example: <i>italic</i> and <b>bold</b></p>
 ```
 
-Here's its DOM structure, note that here text nodes are important for us:
+Here's its DOM structure:
 
 <div class="select-p-domtree"></div>
 
@@ -72,10 +75,17 @@ let selectPDomtree = {
 drawHtmlTree(selectPDomtree, 'div.select-p-domtree', 690, 320);
 </script>
 
-Let's select `"Example: <i>italic</i>"`. That's two first children of `<p>` (counting text nodes):
+Let's make a range for `"Example: <i>italic</i>"`.
+
+As we can see, this phrase consists of exactly the first and the second children of `<p>`:
 
 ![](range-example-p-0-1.svg)
 
+- The starting point has `<p>` as the parent `node`, and `0` as the offset.
+- The ending point also has `<p>` as the parent `node`, but `2` as the offset (it specifies the range up to, but not including `offset`).
+
+Here's the demo, if you run it, you can see that the text gets selected:
+
 ```html run
 <p id="p">Example: <i>italic</i> and <b>bold</b></p>
 
@@ -87,17 +97,14 @@ Let's select `"Example: <i>italic</i>"`. That's two first children of `<p>` (cou
   range.setEnd(p, 2);
 */!*
 
-  // toString of a range returns its content as text (without tags)
-  alert(range); // Example: italic
+  // toString of a range returns its content as text, without tags
+  console.log(range); // Example: italic
 
-  // apply this range for document selection (explained later)
+  // let's apply this range for document selection (explained later)
   document.getSelection().addRange(range);
 </script>
 ```
 
-- `range.setStart(p, 0)` -- sets the start at the 0th child of `<p>` (that's the text node `"Example: "`).
-- `range.setEnd(p, 2)` -- spans the range up to (but not including) 2nd child of `<p>` (that's the text node `" and "`, but as the end is not included, so the last selected node is `<i>`).
-
 Here's a more flexible test stand where you try more variants:
 
 ```html run autorun
@@ -121,7 +128,7 @@ From <input id="start" type="number" value=1> – To <input id="end" type="numbe
 </script>
 ```
 
-E.g. selecting from `1` to `4` gives range `<i>italic</i> and <b>bold</b>`.
+E.g. selecting in the same `<p>` from offset `1` to `4` gives range `<i>italic</i> and <b>bold</b>`:
 
 ![](range-example-p-1-3.svg)
 
@@ -264,11 +271,9 @@ There also exist methods to compare ranges, but these are rarely used. When you
 
 ## Selection
 
-`Range` is a generic object for managing selection ranges. We may create such objects, pass them around -- they do not visually select anything on their own.
-
-The document selection is represented by `Selection` object, that can be obtained as `window.getSelection()` or `document.getSelection()`.
+`Range` is a generic object for managing selection ranges. We may create `Range` objects, pass them around -- they do not visually select anything on their own.
 
-A selection may include zero or more ranges. At least, the [Selection API specification](https://www.w3.org/TR/selection-api/) says so. In practice though, only Firefox allows to select multiple ranges in the document by using `key:Ctrl+click` (`key:Cmd+click` for Mac).
+The document selection is represented by `Selection` object, that can be obtained as `window.getSelection()` or `document.getSelection()`. A selection may include zero or more ranges. At least, the [Selection API specification](https://www.w3.org/TR/selection-api/) says so. In practice though, only Firefox allows to select multiple ranges in the document by using `key:Ctrl+click` (`key:Cmd+click` for Mac).
 
 Here's a screenshot of a selection with 3 ranges, made in Firefox:
 
@@ -289,7 +294,7 @@ The main selection properties are:
 - `isCollapsed` -- `true` if selection selects nothing (empty range), or doesn't exist.
 - `rangeCount` -- count of ranges in the selection, maximum `1` in all browsers except Firefox.
 
-````smart header="Selection end may be in the document before start"
+````smart header="Usually, the selection end `focusNode` is after its start `anchorNode`, but it's not always the case"
 There are many ways to select the content, depending on the user agent: mouse, hotkeys, taps on a mobile etc.
 
 Some of them, such as a mouse, allow the same selection can be created in two directions: "left-to-right" and "right-to-left".