merge

Author: iliakan

1-js/11-async/02-promise-basics/article.md

@@ -276,7 +276,7 @@ promise.then(alert); // done! (выведется сразу)
 
 Теперь, рассмотрим несколько практических примеров того, как промисы могут облегчить нам написание асинхронного кода.
 
-## Пример: loadScript
+## Пример: loadScript [#loadscript]
 
 У нас есть функция `loadScript` для загрузки скрипта из предыдущей главы.
 

1-js/11-async/03-promise-chaining/article.md

@@ -146,7 +146,7 @@ Returning promises allows us to build chains of asynchronous actions.
 
 ## Example: loadScript
 
-Let's use this feature with `loadScript` to load scripts one by one, in sequence:
+Let's use this feature with the promisified `loadScript`, defined in the [previous chapter](/promise-basics#loadscript), to load scripts one by one, in sequence:
 
 ```js run
 loadScript("/article/promise-chaining/one.js")
@@ -305,7 +305,7 @@ fetch('/article/promise-chaining/user.json')
   });
 ```
 
-The code works, see comments about the details, but it should be quite self-descriptive. Although, there's a potential problem in it, a typical error of those who begin to use promises.
+The code works, see comments about the details. Although, there's a potential problem in it, a typical error of those who begin to use promises.
 
 Look at the line `(*)`: how can we do something *after* the avatar has finished showing and gets removed? For instance, we'd like to show a form for editing that user or something else. As of now, there's no way.
 

1-js/12-generators-iterators/2-async-iterators-generators/article.md

@@ -3,13 +3,13 @@
 
 Asynchronous iterators allow to iterate over data that comes asynchronously, on-demand.
 
-For instance, when we download something chunk-by-chunk, or just expect events to come asynchronously and would like to iterate over them -- async iterators and generators may come in handy. Let's see a simple example first, to grasp the syntax, and then review a real-life use case.
+For instance, when we download something chunk-by-chunk, and expect data fragments to come asynchronously and would like to iterate over them -- async iterators and generators may come in handy. Let's see a simple example first, to grasp the syntax, and then review a real-life use case.
 
 ## Async iterators
 
-Asynchronous iterators are totally similar to regular iterators, with a few syntactic differences.
+Asynchronous iterators are similar to regular iterators, with a few syntactic differences.
 
-"Regular" iterable object from the chapter <info:iterable> look like this:
+"Regular" iterable object, as described in the chapter <info:iterable>, look like this:
 
 ```js run
 let range = {
@@ -101,7 +101,7 @@ let range = {
 })()
 ```
 
-As we can see, the components are similar to regular iterators:
+As we can see, the structure is similar to regular iterators:
 
 1. To make an object asynchronously iterable, it must have a method `Symbol.asyncIterator` `(1)`.
 2. It must return the object with `next()` method returning a promise `(2)`.
@@ -117,22 +117,22 @@ Here's a small cheatsheet:
 | to loop, use                          | `for..of`         | `for await..of` |
 
 
-````warn header="The spread operator doesn't work asynchronously"
+````warn header="The spread operator ...  doesn't work asynchronously"
 Features that require regular, synchronous iterators, don't work with asynchronous ones.
 
 For instance, a spread operator won't work:
 ```js
 alert( [...range] ); // Error, no Symbol.iterator
 ```
 
-That's natural, as it expects to find `Symbol.iterator`, same as `for..of` without `await`.
+That's natural, as it expects to find `Symbol.iterator`, same as `for..of` without `await`. Not `Symbol.asyncIterator`.
 ````
 
 ## Async generators
 
-JavaScript also provides generators, that are also iterable.
+As we already know, JavaScript also supprots generators, and they are iterable.
 
-Let's recall a sequence generator from the chapter [](info:generators). It generates a sequence of values from `start` to `end` (could be anything else):
+Let's recall a sequence generator from the chapter [](info:generators). It generates a sequence of values from `start` to `end`:
 
 ```js run
 function* generateSequence(start, end) {
@@ -147,7 +147,7 @@ for(let value of generateSequence(1, 5)) {
 ```
 
 
-Normally, we can't use `await` in generators. All values must come synchronously: there's no place for delay in `for..of`.
+Normally, we can't use `await` in generators. All values must come synchronously: there's no place for delay in `for..of`, it's a synchronous construct.
 
 But what if we need to use `await` in the generator body? To perform network requests, for instance.
 
@@ -184,15 +184,15 @@ It's indeed very simple. We add the `async` keyword, and the generator now can u
 
 Technically, another the difference of an async generator is that its `generator.next()` method is now asynchronous also, it returns promises.
 
-Instead of `result = generator.next()` for a regular, non-async generator, values can be obtained like this:
+In a regular generator we'd use `result = generator.next()` to get values. In an async generator, we should add `await`, like this:
 
 ```js
 result = await generator.next(); // result = {value: ..., done: true/false}
 ```
 
 ## Iterables via async generators
 
-When we'd like to make an object iterable, we should add `Symbol.iterator` to it.
+As we already know, to make an object iterable, we should add `Symbol.iterator` to it.
 
 ```js
 let range = {
@@ -270,7 +270,7 @@ The pattern is very common, it's not about users, but just about anything. For i
 - It responds with a JSON of 30 commits, and also provides a link to the next page in the `Link` header.
 - Then we can use that link for the next request, to get more commits, and so on.
 
-What we'd like to have is an iterable source of commits, so that we could use it like this:
+What we'd like to have is a simpler API: an iterable object with commits, so that we could go over them like this:
 
 ```js
 let repo = 'javascript-tutorial/en.javascript.info'; // GitHub repository to get commits from
@@ -332,7 +332,7 @@ An example of use (shows commit authors in console):
 })();
 ```
 
-That's just what we wanted. The internal pagination mechanics is invisible from the outside. For us it's just an async generator that returns commits.
+That's just what we wanted. The internal mechanics of paginated requests is invisible from the outside. For us it's just an async generator that returns commits.
 
 ## Summary
 
@@ -356,6 +356,6 @@ Syntax differences between async and regular generators:
 
 In web-development we often meet streams of data, when it flows chunk-by-chunk. For instance, downloading or uploading a big file.
 
-We could use async generators to process such data, but there's also another API called Streams, that may be more convenient, as it provides special interfaces to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere). But they are also more complex.
+We can use async generators to process such data, but it's worth to mention that there's also another API called Streams, that provides special interfaces to transform the data and to pass it from one stream to another (e.g. download from one place and immediately send elsewhere). 
 
 Streams API not a part of JavaScript language standard. Streams and async generators complement each other, both are great ways to handle async data flows.

6-data-storage/02-localstorage/article.md

@@ -42,9 +42,9 @@ localStorage.setItem('test', 1);
 alert( localStorage.getItem('test') ); // 1
 ```
 
-We only have to be on the same domain/port/protocol, the url path can be different.
+We only have to be on the same origin (domain/port/protocol), the url path can be different.
 
-The `localStorage` is shared, so if we set the data in one window, the change becomes visible in the other one.
+The `localStorage` is shared between all windows with the same origin, so if we set the data in one window, the change becomes visible in another one.
 
 ## Object-like access
 
@@ -73,7 +73,7 @@ That's allowed for historical reasons, and mostly works, but generally not recom
 
 ## Looping over keys
 
-As we've seen, the methods provide get/set/remove functionality. But how to get all saved values or keys?
+As we've seen, the methods provide "get/set/remove by key" functionality. But how to get all saved values or keys?
 
 Unfortunately, storage objects are not iterable.
 
@@ -198,7 +198,7 @@ Imagine, you have two windows with the same site in each. So `localStorage` is s
 You might want to open this page in two browser windows to test the code below.
 ```
 
-Now if both windows are listening for `window.onstorage`, then each one will react on updates that happened in the other one.
+If both windows are listening for `window.onstorage`, then each one will react on updates that happened in the other one.
 
 ```js run
 // triggers on updates made to the same storage from other documents
@@ -229,18 +229,18 @@ Web storage objects `localStorage` and `sessionStorage` allow to store key/value
 | `localStorage` | `sessionStorage` |
 |----------------|------------------|
 | Shared between all tabs and windows with the same origin | Visible within a browser tab, including iframes from the same origin |
-| Survives browser restart | Dies on tab close |
+| Survives browser restart | Survives page refresh (but not tab close) |
 
 API:
 
 - `setItem(key, value)` -- store key/value pair.
 - `getItem(key)` -- get the value by key.
 - `removeItem(key)` -- remove the key with its value.
 - `clear()` -- delete everything.
-- `key(index)` -- get the key on a given position.
+- `key(index)` -- get the key number `index`.
 - `length` -- the number of stored items.
 - Use `Object.keys` to get all keys.
-- Can use the keys as object properties, in that case `storage` event isn't triggered.
+- We access keys as object properties, in that case `storage` event isn't triggered.
 
 Storage event: