working

Author: iliakan

8-async/01-callback-hell/article.md

@@ -9,40 +9,38 @@ The most obvious example is `setTimeout`, but there are others, like making netw
 
 ## Callbacks
 
-Consider a function `loadScript` that loads a script:
+Consider this function `loadScript(src)` that loads a script:
 
 ```js
 function loadScript(src) {
   let script = document.createElement('script');
   script.src = src;
+  document.head.append(script);
 }
 ```
 
-When the `<script>` tag is created and `src` is assigned, the browser loads the script and executes it. So, the function works. We can use it like this:
+When the script element is added to the document, the browser loads it and executes. So, the function works.
+
+We can use it like this:
 
 ```js
+// loads and executes the script
 loadScript('/my/script.js');
 ```
 
-The function is asynchronous: the script starts loading now, but finishes later, maybe after a few seconds. So, the question is: how can we track the load end? As of now, the function provides no such way.
-
-We'd like to invoke our code after the script is loaded. One of the easiest ways is to add a second argument to `loadScript`: the function that would run on load end.
-
+The function is asynchronous: the script starts loading now, but finishes later.
 
-How can hook on "load completion"?
+```smart header="Synchronous vs asynchronous"
+"Synchonous" and "asynchronous" are general programming terms, not specific to JavaScript.
 
+A *synchronous* action suspends the execution until it's completed. For instance, `alert` and `prompt` are synchronous: the program may not continue until they are finished.
 
-From ancient times, Javascript allowed to use callback functions for asynchronous
-Most asychronous
-In this chapter we cover how to write callback-based asynchronous code.
-Let's see a couple of examples, so that we can discover a problem, and then solve it using "promises".
-
-
-Remember resource load/error events? They are covered in the chapter <info:onload-onerror>.
+An *asynchronous* action allows the program to continue while it's in progress. For instance, `loadScript` in the example above initiates the script loading, but does not suspend the execution. Other commands may execute while the script is loading.
+```
 
-Let's say we want to create a function `loadScript` that loads a script and executes our code afterwards.
+As of now, `loadScript` provides no way to track the load end. How can we execute our own code after the script is loaded?
 
-It can look like this:
+Let's allow that by adding a custom function as a second argument to `loadScript`, that should execute at that moment:
 
 ```js
 function loadScript(src, callback) {
@@ -63,25 +61,24 @@ loadScript('/my/script.js', function(script) {
 });
 ```
 
-...And it works, shows `alert` after the script is loaded.
-
-That is called "a callback API". Our function `loadScript` performs an asynchronous task and we can hook on its completion using the callback function.
+...And it works, shows the `alert` after the script is loaded.
 
 ## Callback in callback
 
-What if we need to load two scripts: one more after the first one?
+What if we need to load two scripts sequentially: the first one, and then the second one after it?
 
-We can put another `loadScript` inside the callback, like this:
+We can put the second `loadScript` inside the callback, like this:
 
 ```js
 loadScript('/my/script.js', function(script) {
+
   alert(`Cool, the ${script.src} is loaded, let's load one more`);
 
+*!*
   loadScript('/my/script2.js', function(script) {
-
     alert(`Cool, the second script is loaded`);
-
   });
+*/!*
 
 });
 ```
@@ -96,11 +93,11 @@ loadScript('/my/script.js', function(script) {
   loadScript('/my/script2.js', function(script) {
 
     if (something) {
-      loadScript('/my/script3.js', function(script) {
 *!*
+      loadScript('/my/script3.js', function(script) {
         // ...continue after all scripts are loaded
-*/!*
       });
+*/!*
     }
 
   })
@@ -114,7 +111,7 @@ As you can see, a new asynchronous action means one more nesting level.
 
 In this example we didn't consider errors. What if a script loading failed with an error? Our callback should be able to react on that.
 
-Here's an improved version of `loadScript` that can handle errors:
+Here's an improved version of `loadScript` that tracks loading errors:
 
 ```js run
 function loadScript(src, callback) {
@@ -138,32 +135,34 @@ loadScript('/my/script.js', function(error, script) {
   if (error) {
     // handle error
   } else {
-    // script loaded, go on
+    // script loaded successfully
   }
 });
 ```
 
-The first argument of `callback` is reserved for errors and the second argument for the successful result. That allows to use a single function to pass both success and failure.
+The first argument of `callback` is reserved for errors, and the second argument is for the successful result.
 
 ## Pyramid of doom
 
-From the first look it's a viable code. And indeed it is. For one or maybe two nested calls it looks fine.
+What we've just seen is called a "callback-based" approach to asynchronous programming. We pass a function, and it should run after the process is complete: with an error or a successful result.
+
+From the first look it's a viable way of asynchronous coding. And indeed it is. For one or maybe two nested calls it looks fine.
 
-But for multiple asynchronous actions that follow one after another...
+But for multiple asynchronous actions that follow one after another we'll have a code like this:
 
 ```js
-loadScript('/my/script1.js', function(error, script) {
+loadScript('1.js', function(error, script) {
 
   if (error) {
     handleError(error);
   } else {
     // ...
-    loadScript('/my/script2.js', function(error, script) {
+    loadScript('2.js', function(error, script) {
       if (error) {
         handleError(error);
       } else {
         // ...
-        loadScript('/my/script3.js', function(error, script) {
+        loadScript('3.js', function(error, script) {
           if (error) {
             handleError(error);
           } else {
@@ -180,35 +179,16 @@ loadScript('/my/script1.js', function(error, script) {
 ```
 
 In the code above:
-1. we load `/my/script1.js`, then if there's no error
-2. we load `/my/script2.js`, then if there's no error
-3. we load `/my/script3.js`, then if there's no error -- do something else `(*)`.
+1. We load `1.js`, then if there's no error.
+2. We load `2.js`, then if there's no error.
+3. We load `3.js`, then if there's no error -- do something else `(*)`.
 
-The nested calls become increasingly more difficult to manage, especially if we add real code instead of `...`, that may include more loops, conditional statements and other usage of loaded scripts.
+As calls become more nested, the whole thing becomes increasingly more difficult to manage, especially if we add real code instead of `...`, that may include more loops, conditional statements and other usage of loaded scripts.
 
 That's sometimes called "callback hell" or "pyramid of doom".
 
 ![](callback-hell.png)
 
-See? It grows right with every asynchronous action.
-
-Compare that with a "regular" synchronous code.
-
-Just *if* `loadScript` were a regular synchronous function:
-
-```js
-try {
-  // assume we get the result in a synchronous manner, without callbacks
-  let script = loadScript('/my/script.js');
-  // ...
-  let script2 = loadScript('/my/script2.js');
-  // ...
-  let script3 = loadScript('/my/script3.js');
-} catch(err) {
-  handleError(err);
-}
-```
-
-How much cleaner and simpler it is!
+The pyramid grows to the right with every asynchronous action. Soon it spirales out of control.
 
-Promises allow to write asynchronous code in a similar way. They are really great at that. Let's study them in the next chapter.
+Fortunately, there are ways to evade such pyramids. One of them is using "promises", we'll study them in the next chapters.