` (e.g., to make the DOM element visible once it has content). You probably wouldn't want to show the DOM element before it had content, so the coordination must ensure proper ordering interaction.\n\nSome concurrency scenarios are *always broken* (not just *sometimes*) without coordinated interaction. Consider:\n\n```js\nvar a, b;\n\nfunction foo(x) {\n\ta = x * 2;\n\tbaz();\n}\n\nfunction bar(y) {\n\tb = y * 2;\n\tbaz();\n}\n\nfunction baz() {\n\tconsole.log(a + b);\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nIn this example, whether `foo()` or `bar()` fires first, it will always cause `baz()` to run too early (either `a` or `b` will still be `undefined`), but the second invocation of `baz()` will work, as both `a` and `b` will be available.\n\nThere are different ways to address such a condition. Here's one simple way:\n\n```js\nvar a, b;\n\nfunction foo(x) {\n\ta = x * 2;\n\tif (a && b) {\n\t\tbaz();\n\t}\n}\n\nfunction bar(y) {\n\tb = y * 2;\n\tif (a && b) {\n\t\tbaz();\n\t}\n}\n\nfunction baz() {\n\tconsole.log( a + b );\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nThe `if (a && b)` conditional around the `baz()` call is traditionally called a \"gate,\" because we're not sure what order `a` and `b` will arrive, but we wait for both of them to get there before we proceed to open the gate (call `baz()`).\n\nAnother concurrency interaction condition you may run into is sometimes called a \"race,\" but more correctly called a \"latch.\" It's characterized by \"only the first one wins\" behavior. Here, nondeterminism is acceptable, in that you are explicitly saying it's OK for the \"race\" to the finish line to have only one winner.\n\nConsider this broken code:\n\n```js\nvar a;\n\nfunction foo(x) {\n\ta = x * 2;\n\tbaz();\n}\n\nfunction bar(x) {\n\ta = x / 2;\n\tbaz();\n}\n\nfunction baz() {\n\tconsole.log( a );\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nWhichever one (`foo()` or `bar()`) fires last will not only overwrite the assigned `a` value from the other, but it will also duplicate the call to `baz()` (likely undesired).\n\nSo, we can coordinate the interaction with a simple latch, to let only the first one through:\n\n```js\nvar a;\n\nfunction foo(x) {\n\tif (a == undefined) {\n\t\ta = x * 2;\n\t\tbaz();\n\t}\n}\n\nfunction bar(x) {\n\tif (a == undefined) {\n\t\ta = x / 2;\n\t\tbaz();\n\t}\n}\n\nfunction baz() {\n\tconsole.log( a );\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nThe `if (a == undefined)` conditional allows only the first of `foo()` or `bar()` through, and the second (and indeed any subsequent) calls would just be ignored. There's just no virtue in coming in second place!\n\n**Note:** In all these scenarios, we've been using global variables for simplistic illustration purposes, but there's nothing about our reasoning here that requires it. As long as the functions in question can access the variables (via scope), they'll work as intended. Relying on lexically scoped variables (see the *Scope & Closures* title of this book series), and in fact global variables as in these examples, is one obvious downside to these forms of concurrency coordination. As we go through the next few chapters, we'll see other ways of coordination that are much cleaner in that respect.\n\n### Cooperation\n\nAnother expression of concurrency coordination is called \"cooperative concurrency.\" Here, the focus isn't so much on interacting via value sharing in scopes (though that's obviously still allowed!). The goal is to take a long-running \"process\" and break it up into steps or batches so that other concurrent \"processes\" have a chance to interleave their operations into the event loop queue.\n\nFor example, consider an Ajax response handler that needs to run through a long list of results to transform the values. We'll use `Array#map(..)` to keep the code shorter:\n\n```js\nvar res = [];\n\n// `response(..)` receives array of results from the Ajax call\nfunction response(data) {\n\t// add onto existing `res` array\n\tres = res.concat(\n\t\t// make a new transformed array with all `data` values doubled\n\t\tdata.map( function(val){\n\t\t\treturn val * 2;\n\t\t} )\n\t);\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", response );\najax( \"http://some.url.2\", response );\n```\n\nIf `\"http://some.url.1\"` gets its results back first, the entire list will be mapped into `res` all at once. If it's a few thousand or less records, this is not generally a big deal. But if it's say 10 million records, that can take a while to run (several seconds on a powerful laptop, much longer on a mobile device, etc.).\n\nWhile such a \"process\" is running, nothing else in the page can happen, including no other `response(..)` calls, no UI updates, not even user events like scrolling, typing, button clicking, and the like. That's pretty painful.\n\nSo, to make a more cooperatively concurrent system, one that's friendlier and doesn't hog the event loop queue, you can process these results in asynchronous batches, after each one \"yielding\" back to the event loop to let other waiting events happen.\n\nHere's a very simple approach:\n\n```js\nvar res = [];\n\n// `response(..)` receives array of results from the Ajax call\nfunction response(data) {\n\t// let's just do 1000 at a time\n\tvar chunk = data.splice( 0, 1000 );\n\n\t// add onto existing `res` array\n\tres = res.concat(\n\t\t// make a new transformed array with all `chunk` values doubled\n\t\tchunk.map( function(val){\n\t\t\treturn val * 2;\n\t\t} )\n\t);\n\n\t// anything left to process?\n\tif (data.length > 0) {\n\t\t// async schedule next batch\n\t\tsetTimeout( function(){\n\t\t\tresponse( data );\n\t\t}, 0 );\n\t}\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", response );\najax( \"http://some.url.2\", response );\n```\n\nWe process the data set in maximum-sized chunks of 1,000 items. By doing so, we ensure a short-running \"process,\" even if that means many more subsequent \"processes,\" as the interleaving onto the event loop queue will give us a much more responsive (performant) site/app.\n\nOf course, we're not interaction-coordinating the ordering of any of these \"processes,\" so the order of results in `res` won't be predictable. If ordering was required, you'd need to use interaction techniques like those we discussed earlier, or ones we will cover in later chapters of this book.\n\nWe use the `setTimeout(..0)` (hack) for async scheduling, which basically just means \"stick this function at the end of the current event loop queue.\"\n\n**Note:** `setTimeout(..0)` is not technically inserting an item directly onto the event loop queue. The timer will insert the event at its next opportunity. For example, two subsequent `setTimeout(..0)` calls would not be strictly guaranteed to be processed in call order, so it *is* possible to see various conditions like timer drift where the ordering of such events isn't predictable. In Node.js, a similar approach is `process.nextTick(..)`. Despite how convenient (and usually more performant) it would be, there's not a single direct way (at least yet) across all environments to ensure async event ordering. We cover this topic in more detail in the next section.\n\n## Jobs\n\nAs of ES6, there's a new concept layered on top of the event loop queue, called the \"Job queue.\" The most likely exposure you'll have to it is with the asynchronous behavior of Promises (see Chapter 3).\n\nUnfortunately, at the moment it's a mechanism without an exposed API, and thus demonstrating it is a bit more convoluted. So we're going to have to just describe it conceptually, such that when we discuss async behavior with Promises in Chapter 3, you'll understand how those actions are being scheduled and processed.\n\nSo, the best way to think about this that I've found is that the \"Job queue\" is a queue hanging off the end of every tick in the event loop queue. Certain async-implied actions that may occur during a tick of the event loop will not cause a whole new event to be added to the event loop queue, but will instead add an item (aka Job) to the end of the current tick's Job queue.\n\nIt's kinda like saying, \"oh, here's this other thing I need to do *later*, but make sure it happens right away before anything else can happen.\"\n\nOr, to use a metaphor: the event loop queue is like an amusement park ride, where once you finish the ride, you have to go to the back of the line to ride again. But the Job queue is like finishing the ride, but then cutting in line and getting right back on.\n\nA Job can also cause more Jobs to be added to the end of the same queue. So, it's theoretically possible that a Job \"loop\" (a Job that keeps adding another Job, etc.) could spin indefinitely, thus starving the program of the ability to move on to the next event loop tick. This would conceptually be almost the same as just expressing a long-running or infinite loop (like `while (true) ..`) in your code.\n\nJobs are kind of like the spirit of the `setTimeout(..0)` hack, but implemented in such a way as to have a much more well-defined and guaranteed ordering: **later, but as soon as possible**.\n\nLet's imagine an API for scheduling Jobs (directly, without hacks), and call it `schedule(..)`. Consider:\n\n```js\nconsole.log( \"A\" );\n\nsetTimeout( function(){\n\tconsole.log( \"B\" );\n}, 0 );\n\n// theoretical \"Job API\"\nschedule( function(){\n\tconsole.log( \"C\" );\n\n\tschedule( function(){\n\t\tconsole.log( \"D\" );\n\t} );\n} );\n```\n\nYou might expect this to print out `A B C D`, but instead it would print out `A C D B`, because the Jobs happen at the end of the current event loop tick, and the timer fires to schedule for the *next* event loop tick (if available!).\n\nIn Chapter 3, we'll see that the asynchronous behavior of Promises is based on Jobs, so it's important to keep clear how that relates to event loop behavior.\n\n## Statement Ordering\n\nThe order in which we express statements in our code is not necessarily the same order as the JS engine will execute them. That may seem like quite a strange assertion to make, so we'll just briefly explore it.\n\nBut before we do, we should be crystal clear on something: the rules/grammar of the language (see the *Types & Grammar* title of this book series) dictate a very predictable and reliable behavior for statement ordering from the program point of view. So what we're about to discuss are **not things you should ever be able to observe** in your JS program.\n\n**Warning:** If you are ever able to *observe* compiler statement reordering like we're about to illustrate, that'd be a clear violation of the specification, and it would unquestionably be due to a bug in the JS engine in question -- one which should promptly be reported and fixed! But it's vastly more common that you *suspect* something crazy is happening in the JS engine, when in fact it's just a bug (probably a \"race condition\"!) in your own code -- so look there first, and again and again. The JS debugger, using breakpoints and stepping through code line by line, will be your most powerful tool for sniffing out such bugs in *your code*.\n\nConsider:\n\n```js\nvar a, b;\n\na = 10;\nb = 30;\n\na = a + 1;\nb = b + 1;\n\nconsole.log( a + b ); // 42\n```\n\nThis code has no expressed asynchrony to it (other than the rare `console` async I/O discussed earlier!), so the most likely assumption is that it would process line by line in top-down fashion.\n\nBut it's *possible* that the JS engine, after compiling this code (yes, JS is compiled -- see the *Scope & Closures* title of this book series!) might find opportunities to run your code faster by rearranging (safely) the order of these statements. Essentially, as long as you can't observe the reordering, anything's fair game.\n\nFor example, the engine might find it's faster to actually execute the code like this:\n\n```js\nvar a, b;\n\na = 10;\na++;\n\nb = 30;\nb++;\n\nconsole.log( a + b ); // 42\n```\n\nOr this:\n\n```js\nvar a, b;\n\na = 11;\nb = 31;\n\nconsole.log( a + b ); // 42\n```\n\nOr even:\n\n```js\n// because `a` and `b` aren't used anymore, we can\n// inline and don't even need them!\nconsole.log( 42 ); // 42\n```\n\nIn all these cases, the JS engine is performing safe optimizations during its compilation, as the end *observable* result will be the same.\n\nBut here's a scenario where these specific optimizations would be unsafe and thus couldn't be allowed (of course, not to say that it's not optimized at all):\n\n```js\nvar a, b;\n\na = 10;\nb = 30;\n\n// we need `a` and `b` in their preincremented state!\nconsole.log( a * b ); // 300\n\na = a + 1;\nb = b + 1;\n\nconsole.log( a + b ); // 42\n```\n\nOther examples where the compiler reordering could create observable side effects (and thus must be disallowed) would include things like any function call with side effects (even and especially getter functions), or ES6 Proxy objects (see the *ES6 & Beyond* title of this book series).\n\nConsider:\n\n```js\nfunction foo() {\n\tconsole.log( b );\n\treturn 1;\n}\n\nvar a, b, c;\n\n// ES5.1 getter literal syntax\nc = {\n\tget bar() {\n\t\tconsole.log( a );\n\t\treturn 1;\n\t}\n};\n\na = 10;\nb = 30;\n\na += foo();\t\t\t\t// 30\nb += c.bar;\t\t\t\t// 11\n\nconsole.log( a + b );\t// 42\n```\n\nIf it weren't for the `console.log(..)` statements in this snippet (just used as a convenient form of observable side effect for the illustration), the JS engine would likely have been free, if it wanted to (who knows if it would!?), to reorder the code to:\n\n```js\n// ...\n\na = 10 + foo();\nb = 30 + c.bar;\n\n// ...\n```\n\nWhile JS semantics thankfully protect us from the *observable* nightmares that compiler statement reordering would seem to be in danger of, it's still important to understand just how tenuous a link there is between the way source code is authored (in top-down fashion) and the way it runs after compilation.\n\nCompiler statement reordering is almost a micro-metaphor for concurrency and interaction. As a general concept, such awareness can help you understand async JS code flow issues better.\n\n## Review\n\nA JavaScript program is (practically) always broken up into two or more chunks, where the first chunk runs *now* and the next chunk runs *later*, in response to an event. Even though the program is executed chunk-by-chunk, all of them share the same access to the program scope and state, so each modification to state is made on top of the previous state.\n\nWhenever there are events to run, the *event loop* runs until the queue is empty. Each iteration of the event loop is a \"tick.\" User interaction, IO, and timers enqueue events on the event queue.\n\nAt any given moment, only one event can be processed from the queue at a time. While an event is executing, it can directly or indirectly cause one or more subsequent events.\n\nConcurrency is when two or more chains of events interleave over time, such that from a high-level perspective, they appear to be running *simultaneously* (even though at any given moment only one event is being processed).\n\nIt's often necessary to do some form of interaction coordination between these concurrent \"processes\" (as distinct from operating system processes), for instance to ensure ordering or to prevent \"race conditions.\" These \"processes\" can also *cooperate* by breaking themselves into smaller chunks and to allow other \"process\" interleaving.\n"
},
{
"path": "async & performance/ch2.md",
"content": "# You Don't Know JS: Async & Performance\n# Chapter 2: Callbacks\n\nIn Chapter 1, we explored the terminology and concepts around asynchronous programming in JavaScript. Our focus is on understanding the single-threaded (one-at-a-time) event loop queue that drives all \"events\" (async function invocations). We also explored various ways that concurrency patterns explain the relationships (if any!) between *simultaneously* running chains of events, or \"processes\" (tasks, function calls, etc.).\n\nAll our examples in Chapter 1 used the function as the individual, indivisible unit of operations, whereby inside the function, statements run in predictable order (above the compiler level!), but at the function-ordering level, events (aka async function invocations) can happen in a variety of orders.\n\nIn all these cases, the function is acting as a \"callback,\" because it serves as the target for the event loop to \"call back into\" the program, whenever that item in the queue is processed.\n\nAs you no doubt have observed, callbacks are by far the most common way that asynchrony in JS programs is expressed and managed. Indeed, the callback is the most fundamental async pattern in the language.\n\nCountless JS programs, even very sophisticated and complex ones, have been written upon no other async foundation than the callback (with of course the concurrency interaction patterns we explored in Chapter 1). The callback function is the async work horse for JavaScript, and it does its job respectably.\n\nExcept... callbacks are not without their shortcomings. Many developers are excited by the *promise* (pun intended!) of better async patterns. But it's impossible to effectively use any abstraction if you don't understand what it's abstracting, and why.\n\nIn this chapter, we will explore a couple of those in depth, as motivation for why more sophisticated async patterns (explored in subsequent chapters of this book) are necessary and desired.\n\n## Continuations\n\nLet's go back to the async callback example we started with in Chapter 1, but let me slightly modify it to illustrate a point:\n\n```js\n// A\najax( \"..\", function(..){\n\t// C\n} );\n// B\n```\n\n`// A` and `// B` represent the first half of the program (aka the *now*), and `// C` marks the second half of the program (aka the *later*). The first half executes right away, and then there's a \"pause\" of indeterminate length. At some future moment, if the Ajax call completes, then the program will pick up where it left off, and *continue* with the second half.\n\nIn other words, the callback function wraps or encapsulates the *continuation* of the program.\n\nLet's make the code even simpler:\n\n```js\n// A\nsetTimeout( function(){\n\t// C\n}, 1000 );\n// B\n```\n\nStop for a moment and ask yourself how you'd describe (to someone else less informed about how JS works) the way that program behaves. Go ahead, try it out loud. It's a good exercise that will help my next points make more sense.\n\nMost readers just now probably thought or said something to the effect of: \"Do A, then set up a timeout to wait 1,000 milliseconds, then once that fires, do C.\" How close was your rendition?\n\nYou might have caught yourself and self-edited to: \"Do A, setup the timeout for 1,000 milliseconds, then do B, then after the timeout fires, do C.\" That's more accurate than the first version. Can you spot the difference?\n\nEven though the second version is more accurate, both versions are deficient in explaining this code in a way that matches our brains to the code, and the code to the JS engine. The disconnect is both subtle and monumental, and is at the very heart of understanding the shortcomings of callbacks as async expression and management.\n\nAs soon as we introduce a single continuation (or several dozen as many programs do!) in the form of a callback function, we have allowed a divergence to form between how our brains work and the way the code will operate. Any time these two diverge (and this is by far not the only place that happens, as I'm sure you know!), we run into the inevitable fact that our code becomes harder to understand, reason about, debug, and maintain.\n\n## Sequential Brain\n\nI'm pretty sure most of you readers have heard someone say (even made the claim yourself), \"I'm a multitasker.\" The effects of trying to act as a multitasker range from humorous (e.g., the silly patting-head-rubbing-stomach kids' game) to mundane (chewing gum while walking) to downright dangerous (texting while driving).\n\nBut are we multitaskers? Can we really do two conscious, intentional actions at once and think/reason about both of them at exactly the same moment? Does our highest level of brain functionality have parallel multithreading going on?\n\nThe answer may surprise you: **probably not.**\n\nThat's just not really how our brains appear to be set up. We're much more single taskers than many of us (especially A-type personalities!) would like to admit. We can really only think about one thing at any given instant.\n\nI'm not talking about all our involuntary, subconscious, automatic brain functions, such as heart beating, breathing, and eyelid blinking. Those are all vital tasks to our sustained life, but we don't intentionally allocate any brain power to them. Thankfully, while we obsess about checking social network feeds for the 15th time in three minutes, our brain carries on in the background (threads!) with all those important tasks.\n\nWe're instead talking about whatever task is at the forefront of our minds at the moment. For me, it's writing the text in this book right now. Am I doing any other higher level brain function at exactly this same moment? Nope, not really. I get distracted quickly and easily -- a few dozen times in these last couple of paragraphs!\n\nWhen we *fake* multitasking, such as trying to type something at the same time we're talking to a friend or family member on the phone, what we're actually most likely doing is acting as fast context switchers. In other words, we switch back and forth between two or more tasks in rapid succession, *simultaneously* progressing on each task in tiny, fast little chunks. We do it so fast that to the outside world it appears as if we're doing these things *in parallel*.\n\nDoes that sound suspiciously like async evented concurrency (like the sort that happens in JS) to you?! If not, go back and read Chapter 1 again!\n\nIn fact, one way of simplifying (i.e., abusing) the massively complex world of neurology into something I can remotely hope to discuss here is that our brains work kinda like the event loop queue.\n\nIf you think about every single letter (or word) I type as a single async event, in just this sentence alone there are several dozen opportunities for my brain to be interrupted by some other event, such as from my senses, or even just my random thoughts.\n\nI don't get interrupted and pulled to another \"process\" at every opportunity that I could be (thankfully -- or this book would never be written!). But it happens often enough that I feel my own brain is nearly constantly switching to various different contexts (aka \"processes\"). And that's an awful lot like how the JS engine would probably feel.\n\n### Doing Versus Planning\n\nOK, so our brains can be thought of as operating in single-threaded event loop queue like ways, as can the JS engine. That sounds like a good match.\n\nBut we need to be more nuanced than that in our analysis. There's a big, observable difference between how we plan various tasks, and how our brains actually operate those tasks.\n\nAgain, back to the writing of this text as my metaphor. My rough mental outline plan here is to keep writing and writing, going sequentially through a set of points I have ordered in my thoughts. I don't plan to have any interruptions or nonlinear activity in this writing. But yet, my brain is nevertheless switching around all the time.\n\nEven though at an operational level our brains are async evented, we seem to plan out tasks in a sequential, synchronous way. \"I need to go to the store, then buy some milk, then drop off my dry cleaning.\"\n\nYou'll notice that this higher level thinking (planning) doesn't seem very async evented in its formulation. In fact, it's kind of rare for us to deliberately think solely in terms of events. Instead, we plan things out carefully, sequentially (A then B then C), and we assume to an extent a sort of temporal blocking that forces B to wait on A, and C to wait on B.\n\nWhen a developer writes code, they are planning out a set of actions to occur. If they're any good at being a developer, they're **carefully planning** it out. \"I need to set `z` to the value of `x`, and then `x` to the value of `y`,\" and so forth.\n\nWhen we write out synchronous code, statement by statement, it works a lot like our errands to-do list:\n\n```js\n// swap `x` and `y` (via temp variable `z`)\nz = x;\nx = y;\ny = z;\n```\n\nThese three assignment statements are synchronous, so `x = y` waits for `z = x` to finish, and `y = z` in turn waits for `x = y` to finish. Another way of saying it is that these three statements are temporally bound to execute in a certain order, one right after the other. Thankfully, we don't need to be bothered with any async evented details here. If we did, the code gets a lot more complex, quickly!\n\nSo if synchronous brain planning maps well to synchronous code statements, how well do our brains do at planning out asynchronous code?\n\nIt turns out that how we express asynchrony (with callbacks) in our code doesn't map very well at all to that synchronous brain planning behavior.\n\nCan you actually imagine having a line of thinking that plans out your to-do errands like this?\n\n> \"I need to go to the store, but on the way I'm sure I'll get a phone call, so 'Hi, Mom', and while she starts talking, I'll be looking up the store address on GPS, but that'll take a second to load, so I'll turn down the radio so I can hear Mom better, then I'll realize I forgot to put on a jacket and it's cold outside, but no matter, keep driving and talking to Mom, and then the seatbelt ding reminds me to buckle up, so 'Yes, Mom, I am wearing my seatbelt, I always do!'. Ah, finally the GPS got the directions, now...\"\n\nAs ridiculous as that sounds as a formulation for how we plan our day out and think about what to do and in what order, nonetheless it's exactly how our brains operate at a functional level. Remember, that's not multitasking, it's just fast context switching.\n\nThe reason it's difficult for us as developers to write async evented code, especially when all we have is the callback to do it, is that stream of consciousness thinking/planning is unnatural for most of us.\n\nWe think in step-by-step terms, but the tools (callbacks) available to us in code are not expressed in a step-by-step fashion once we move from synchronous to asynchronous.\n\nAnd **that** is why it's so hard to accurately author and reason about async JS code with callbacks: because it's not how our brain planning works.\n\n**Note:** The only thing worse than not knowing why some code breaks is not knowing why it worked in the first place! It's the classic \"house of cards\" mentality: \"it works, but not sure why, so nobody touch it!\" You may have heard, \"Hell is other people\" (Sartre), and the programmer meme twist, \"Hell is other people's code.\" I believe truly: \"Hell is not understanding my own code.\" And callbacks are one main culprit.\n\n### Nested/Chained Callbacks\n\nConsider:\n\n```js\nlisten( \"click\", function handler(evt){\n\tsetTimeout( function request(){\n\t\tajax( \"http://some.url.1\", function response(text){\n\t\t\tif (text == \"hello\") {\n\t\t\t\thandler();\n\t\t\t}\n\t\t\telse if (text == \"world\") {\n\t\t\t\trequest();\n\t\t\t}\n\t\t} );\n\t}, 500) ;\n} );\n```\n\nThere's a good chance code like that is recognizable to you. We've got a chain of three functions nested together, each one representing a step in an asynchronous series (task, \"process\").\n\nThis kind of code is often called \"callback hell,\" and sometimes also referred to as the \"pyramid of doom\" (for its sideways-facing triangular shape due to the nested indentation).\n\nBut \"callback hell\" actually has almost nothing to do with the nesting/indentation. It's a far deeper problem than that. We'll see how and why as we continue through the rest of this chapter.\n\nFirst, we're waiting for the \"click\" event, then we're waiting for the timer to fire, then we're waiting for the Ajax response to come back, at which point it might do it all again.\n\nAt first glance, this code may seem to map its asynchrony naturally to sequential brain planning.\n\nFirst (*now*), we:\n\n```js\nlisten( \"..\", function handler(..){\n\t// ..\n} );\n```\n\nThen *later*, we:\n\n```js\nsetTimeout( function request(..){\n\t// ..\n}, 500) ;\n```\n\nThen still *later*, we:\n\n```js\najax( \"..\", function response(..){\n\t// ..\n} );\n```\n\nAnd finally (most *later*), we:\n\n```js\nif ( .. ) {\n\t// ..\n}\nelse ..\n```\n\nBut there's several problems with reasoning about this code linearly in such a fashion.\n\nFirst, it's an accident of the example that our steps are on subsequent lines (1, 2, 3, and 4...). In real async JS programs, there's often a lot more noise cluttering things up, noise that we have to deftly maneuver past in our brains as we jump from one function to the next. Understanding the async flow in such callback-laden code is not impossible, but it's certainly not natural or easy, even with lots of practice.\n\nBut also, there's something deeper wrong, which isn't evident just in that code example. Let me make up another scenario (pseudocode-ish) to illustrate it:\n\n```js\ndoA( function(){\n\tdoB();\n\n\tdoC( function(){\n\t\tdoD();\n\t} )\n\n\tdoE();\n} );\n\ndoF();\n```\n\nWhile the experienced among you will correctly identify the true order of operations here, I'm betting it is more than a little confusing at first glance, and takes some concerted mental cycles to arrive at. The operations will happen in this order:\n\n* `doA()`\n* `doF()`\n* `doB()`\n* `doC()`\n* `doE()`\n* `doD()`\n\nDid you get that right the very first time you glanced at the code?\n\nOK, some of you are thinking I was unfair in my function naming, to intentionally lead you astray. I swear I was just naming in top-down appearance order. But let me try again:\n\n```js\ndoA( function(){\n\tdoC();\n\n\tdoD( function(){\n\t\tdoF();\n\t} )\n\n\tdoE();\n} );\n\ndoB();\n```\n\nNow, I've named them alphabetically in order of actual execution. But I still bet, even with experience now in this scenario, tracing through the `A -> B -> C -> D -> E -> F` order doesn't come natural to many if any of you readers. Certainly, your eyes do an awful lot of jumping up and down the code snippet, right?\n\nBut even if that all comes natural to you, there's still one more hazard that could wreak havoc. Can you spot what it is?\n\nWhat if `doA(..)` or `doD(..)` aren't actually async, the way we obviously assumed them to be? Uh oh, now the order is different. If they're both sync (and maybe only sometimes, depending on the conditions of the program at the time), the order is now `A -> C -> D -> F -> E -> B`.\n\nThat sound you just heard faintly in the background is the sighs of thousands of JS developers who just had a face-in-hands moment.\n\nIs nesting the problem? Is that what makes it so hard to trace the async flow? That's part of it, certainly.\n\nBut let me rewrite the previous nested event/timeout/Ajax example without using nesting:\n\n```js\nlisten( \"click\", handler );\n\nfunction handler() {\n\tsetTimeout( request, 500 );\n}\n\nfunction request(){\n\tajax( \"http://some.url.1\", response );\n}\n\nfunction response(text){\n\tif (text == \"hello\") {\n\t\thandler();\n\t}\n\telse if (text == \"world\") {\n\t\trequest();\n\t}\n}\n```\n\nThis formulation of the code is not hardly as recognizable as having the nesting/indentation woes of its previous form, and yet it's every bit as susceptible to \"callback hell.\" Why?\n\nAs we go to linearly (sequentially) reason about this code, we have to skip from one function, to the next, to the next, and bounce all around the code base to \"see\" the sequence flow. And remember, this is simplified code in sort of best-case fashion. We all know that real async JS program code bases are often fantastically more jumbled, which makes such reasoning orders of magnitude more difficult.\n\nAnother thing to notice: to get steps 2, 3, and 4 linked together so they happen in succession, the only affordance callbacks alone gives us is to hardcode step 2 into step 1, step 3 into step 2, step 4 into step 3, and so on. The hardcoding isn't necessarily a bad thing, if it really is a fixed condition that step 2 should always lead to step 3.\n\nBut the hardcoding definitely makes the code a bit more brittle, as it doesn't account for anything going wrong that might cause a deviation in the progression of steps. For example, if step 2 fails, step 3 never gets reached, nor does step 2 retry, or move to an alternate error handling flow, and so on.\n\nAll of these issues are things you *can* manually hardcode into each step, but that code is often very repetitive and not reusable in other steps or in other async flows in your program.\n\nEven though our brains might plan out a series of tasks in a sequential type of way (this, then this, then this), the evented nature of our brain operation makes recovery/retry/forking of flow control almost effortless. If you're out running errands, and you realize you left a shopping list at home, it doesn't end the day because you didn't plan that ahead of time. Your brain routes around this hiccup easily: you go home, get the list, then head right back out to the store.\n\nBut the brittle nature of manually hardcoded callbacks (even with hardcoded error handling) is often far less graceful. Once you end up specifying (aka pre-planning) all the various eventualities/paths, the code becomes so convoluted that it's hard to ever maintain or update it.\n\n**That** is what \"callback hell\" is all about! The nesting/indentation are basically a side show, a red herring.\n\nAnd as if all that's not enough, we haven't even touched what happens when two or more chains of these callback continuations are happening *simultaneously*, or when the third step branches out into \"parallel\" callbacks with gates or latches, or... OMG, my brain hurts, how about yours!?\n\nAre you catching the notion here that our sequential, blocking brain planning behaviors just don't map well onto callback-oriented async code? That's the first major deficiency to articulate about callbacks: they express asynchrony in code in ways our brains have to fight just to keep in sync with (pun intended!).\n\n## Trust Issues\n\nThe mismatch between sequential brain planning and callback-driven async JS code is only part of the problem with callbacks. There's something much deeper to be concerned about.\n\nLet's once again revisit the notion of a callback function as the continuation (aka the second half) of our program:\n\n```js\n// A\najax( \"..\", function(..){\n\t// C\n} );\n// B\n```\n\n`// A` and `// B` happen *now*, under the direct control of the main JS program. But `// C` gets deferred to happen *later*, and under the control of another party -- in this case, the `ajax(..)` function. In a basic sense, that sort of hand-off of control doesn't regularly cause lots of problems for programs.\n\nBut don't be fooled by its infrequency that this control switch isn't a big deal. In fact, it's one of the worst (and yet most subtle) problems about callback-driven design. It revolves around the idea that sometimes `ajax(..)` (i.e., the \"party\" you hand your callback continuation to) is not a function that you wrote, or that you directly control. Many times, it's a utility provided by some third party.\n\nWe call this \"inversion of control,\" when you take part of your program and give over control of its execution to another third party. There's an unspoken \"contract\" that exists between your code and the third-party utility -- a set of things you expect to be maintained.\n\n### Tale of Five Callbacks\n\nIt might not be terribly obvious why this is such a big deal. Let me construct an exaggerated scenario to illustrate the hazards of trust at play.\n\nImagine you're a developer tasked with building out an ecommerce checkout system for a site that sells expensive TVs. You already have all the various pages of the checkout system built out just fine. On the last page, when the user clicks \"confirm\" to buy the TV, you need to call a third-party function (provided say by some analytics tracking company) so that the sale can be tracked.\n\nYou notice that they've provided what looks like an async tracking utility, probably for the sake of performance best practices, which means you need to pass in a callback function. In this continuation that you pass in, you will have the final code that charges the customer's credit card and displays the thank you page.\n\nThis code might look like:\n\n```js\nanalytics.trackPurchase( purchaseData, function(){\n\tchargeCreditCard();\n\tdisplayThankyouPage();\n} );\n```\n\nEasy enough, right? You write the code, test it, everything works, and you deploy to production. Everyone's happy!\n\nSix months go by and no issues. You've almost forgotten you even wrote that code. One morning, you're at a coffee shop before work, casually enjoying your latte, when you get a panicked call from your boss insisting you drop the coffee and rush into work right away.\n\nWhen you arrive, you find out that a high-profile customer has had his credit card charged five times for the same TV, and he's understandably upset. Customer service has already issued an apology and processed a refund. But your boss demands to know how this could possibly have happened. \"Don't we have tests for stuff like this!?\"\n\nYou don't even remember the code you wrote. But you dig back in and start trying to find out what could have gone awry.\n\nAfter digging through some logs, you come to the conclusion that the only explanation is that the analytics utility somehow, for some reason, called your callback five times instead of once. Nothing in their documentation mentions anything about this.\n\nFrustrated, you contact customer support, who of course is as astonished as you are. They agree to escalate it to their developers, and promise to get back to you. The next day, you receive a lengthy email explaining what they found, which you promptly forward to your boss.\n\nApparently, the developers at the analytics company had been working on some experimental code that, under certain conditions, would retry the provided callback once per second, for five seconds, before failing with a timeout. They had never intended to push that into production, but somehow they did, and they're totally embarrassed and apologetic. They go into plenty of detail about how they've identified the breakdown and what they'll do to ensure it never happens again. Yadda, yadda.\n\nWhat's next?\n\nYou talk it over with your boss, but he's not feeling particularly comfortable with the state of things. He insists, and you reluctantly agree, that you can't trust *them* anymore (that's what bit you), and that you'll need to figure out how to protect the checkout code from such a vulnerability again.\n\nAfter some tinkering, you implement some simple ad hoc code like the following, which the team seems happy with:\n\n```js\nvar tracked = false;\n\nanalytics.trackPurchase( purchaseData, function(){\n\tif (!tracked) {\n\t\ttracked = true;\n\t\tchargeCreditCard();\n\t\tdisplayThankyouPage();\n\t}\n} );\n```\n\n**Note:** This should look familiar to you from Chapter 1, because we're essentially creating a latch to handle if there happen to be multiple concurrent invocations of our callback.\n\nBut then one of your QA engineers asks, \"what happens if they never call the callback?\" Oops. Neither of you had thought about that.\n\nYou begin to chase down the rabbit hole, and think of all the possible things that could go wrong with them calling your callback. Here's roughly the list you come up with of ways the analytics utility could misbehave:\n\n* Call the callback too early (before it's been tracked)\n* Call the callback too late (or never)\n* Call the callback too few or too many times (like the problem you encountered!)\n* Fail to pass along any necessary environment/parameters to your callback\n* Swallow any errors/exceptions that may happen\n* ...\n\nThat should feel like a troubling list, because it is. You're probably slowly starting to realize that you're going to have to invent an awful lot of ad hoc logic **in each and every single callback** that's passed to a utility you're not positive you can trust.\n\nNow you realize a bit more completely just how hellish \"callback hell\" is.\n\n### Not Just Others' Code\n\nSome of you may be skeptical at this point whether this is as big a deal as I'm making it out to be. Perhaps you don't interact with truly third-party utilities much if at all. Perhaps you use versioned APIs or self-host such libraries, so that its behavior can't be changed out from underneath you.\n\nSo, contemplate this: can you even *really* trust utilities that you do theoretically control (in your own code base)?\n\nThink of it this way: most of us agree that at least to some extent we should build our own internal functions with some defensive checks on the input parameters, to reduce/prevent unexpected issues.\n\nOverly trusting of input:\n```js\nfunction addNumbers(x,y) {\n\t// + is overloaded with coercion to also be\n\t// string concatenation, so this operation\n\t// isn't strictly safe depending on what's\n\t// passed in.\n\treturn x + y;\n}\n\naddNumbers( 21, 21 );\t// 42\naddNumbers( 21, \"21\" );\t// \"2121\"\n```\n\nDefensive against untrusted input:\n```js\nfunction addNumbers(x,y) {\n\t// ensure numerical input\n\tif (typeof x != \"number\" || typeof y != \"number\") {\n\t\tthrow Error( \"Bad parameters\" );\n\t}\n\n\t// if we get here, + will safely do numeric addition\n\treturn x + y;\n}\n\naddNumbers( 21, 21 );\t// 42\naddNumbers( 21, \"21\" );\t// Error: \"Bad parameters\"\n```\n\nOr perhaps still safe but friendlier:\n```js\nfunction addNumbers(x,y) {\n\t// ensure numerical input\n\tx = Number( x );\n\ty = Number( y );\n\n\t// + will safely do numeric addition\n\treturn x + y;\n}\n\naddNumbers( 21, 21 );\t// 42\naddNumbers( 21, \"21\" );\t// 42\n```\n\nHowever you go about it, these sorts of checks/normalizations are fairly common on function inputs, even with code we theoretically entirely trust. In a crude sort of way, it's like the programming equivalent of the geopolitical principle of \"Trust But Verify.\"\n\nSo, doesn't it stand to reason that we should do the same thing about composition of async function callbacks, not just with truly external code but even with code we know is generally \"under our own control\"? **Of course we should.**\n\nBut callbacks don't really offer anything to assist us. We have to construct all that machinery ourselves, and it often ends up being a lot of boilerplate/overhead that we repeat for every single async callback.\n\nThe most troublesome problem with callbacks is *inversion of control* leading to a complete breakdown along all those trust lines.\n\nIf you have code that uses callbacks, especially but not exclusively with third-party utilities, and you're not already applying some sort of mitigation logic for all these *inversion of control* trust issues, your code *has* bugs in it right now even though they may not have bitten you yet. Latent bugs are still bugs.\n\nHell indeed.\n\n## Trying to Save Callbacks\n\nThere are several variations of callback design that have attempted to address some (not all!) of the trust issues we've just looked at. It's a valiant, but doomed, effort to save the callback pattern from imploding on itself.\n\nFor example, regarding more graceful error handling, some API designs provide for split callbacks (one for the success notification, one for the error notification):\n\n```js\nfunction success(data) {\n\tconsole.log( data );\n}\n\nfunction failure(err) {\n\tconsole.error( err );\n}\n\najax( \"http://some.url.1\", success, failure );\n```\n\nIn APIs of this design, often the `failure()` error handler is optional, and if not provided it will be assumed you want the errors swallowed. Ugh.\n\n**Note:** This split-callback design is what the ES6 Promise API uses. We'll cover ES6 Promises in much more detail in the next chapter.\n\nAnother common callback pattern is called \"error-first style\" (sometimes called \"Node style,\" as it's also the convention used across nearly all Node.js APIs), where the first argument of a single callback is reserved for an error object (if any). If success, this argument will be empty/falsy (and any subsequent arguments will be the success data), but if an error result is being signaled, the first argument is set/truthy (and usually nothing else is passed):\n\n```js\nfunction response(err,data) {\n\t// error?\n\tif (err) {\n\t\tconsole.error( err );\n\t}\n\t// otherwise, assume success\n\telse {\n\t\tconsole.log( data );\n\t}\n}\n\najax( \"http://some.url.1\", response );\n```\n\nIn both of these cases, several things should be observed.\n\nFirst, it has not really resolved the majority of trust issues like it may appear. There's nothing about either callback that prevents or filters unwanted repeated invocations. Moreover, things are worse now, because you may get both success and error signals, or neither, and you still have to code around either of those conditions.\n\nAlso, don't miss the fact that while it's a standard pattern you can employ, it's definitely more verbose and boilerplate-ish without much reuse, so you're going to get weary of typing all that out for every single callback in your application.\n\nWhat about the trust issue of never being called? If this is a concern (and it probably should be!), you likely will need to set up a timeout that cancels the event. You could make a utility (proof-of-concept only shown) to help you with that:\n\n```js\nfunction timeoutify(fn,delay) {\n\tvar intv = setTimeout( function(){\n\t\t\tintv = null;\n\t\t\tfn( new Error( \"Timeout!\" ) );\n\t\t}, delay )\n\t;\n\n\treturn function() {\n\t\t// timeout hasn't happened yet?\n\t\tif (intv) {\n\t\t\tclearTimeout( intv );\n\t\t\tfn.apply( this, [ null ].concat( [].slice.call( arguments ) ) );\n\t\t}\n\t};\n}\n```\n\nHere's how you use it:\n\n```js\n// using \"error-first style\" callback design\nfunction foo(err,data) {\n\tif (err) {\n\t\tconsole.error( err );\n\t}\n\telse {\n\t\tconsole.log( data );\n\t}\n}\n\najax( \"http://some.url.1\", timeoutify( foo, 500 ) );\n```\n\nAnother trust issue is being called \"too early.\" In application-specific terms, this may actually involve being called before some critical task is complete. But more generally, the problem is evident in utilities that can either invoke the callback you provide *now* (synchronously), or *later* (asynchronously).\n\nThis nondeterminism around the sync-or-async behavior is almost always going to lead to very difficult to track down bugs. In some circles, the fictional insanity-inducing monster named Zalgo is used to describe the sync/async nightmares. \"Don't release Zalgo!\" is a common cry, and it leads to very sound advice: always invoke callbacks asynchronously, even if that's \"right away\" on the next turn of the event loop, so that all callbacks are predictably async.\n\n**Note:** For more information on Zalgo, see Oren Golan's \"Don't Release Zalgo!\" (https://github.com/oren/oren.github.io/blob/master/posts/zalgo.md) and Isaac Z. Schlueter's \"Designing APIs for Asynchrony\" (http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony).\n\nConsider:\n\n```js\nfunction result(data) {\n\tconsole.log( a );\n}\n\nvar a = 0;\n\najax( \"..pre-cached-url..\", result );\na++;\n```\n\nWill this code print `0` (sync callback invocation) or `1` (async callback invocation)? Depends... on the conditions.\n\nYou can see just how quickly the unpredictability of Zalgo can threaten any JS program. So the silly-sounding \"never release Zalgo\" is actually incredibly common and solid advice. Always be asyncing.\n\nWhat if you don't know whether the API in question will always execute async? You could invent a utility like this `asyncify(..)` proof-of-concept:\n\n```js\nfunction asyncify(fn) {\n\tvar orig_fn = fn,\n\t\tintv = setTimeout( function(){\n\t\t\tintv = null;\n\t\t\tif (fn) fn();\n\t\t}, 0 )\n\t;\n\n\tfn = null;\n\n\treturn function() {\n\t\t// firing too quickly, before `intv` timer has fired to\n\t\t// indicate async turn has passed?\n\t\tif (intv) {\n\t\t\tfn = orig_fn.bind.apply(\n\t\t\t\torig_fn,\n\t\t\t\t// add the wrapper's `this` to the `bind(..)`\n\t\t\t\t// call parameters, as well as currying any\n\t\t\t\t// passed in parameters\n\t\t\t\t[this].concat( [].slice.call( arguments ) )\n\t\t\t);\n\t\t}\n\t\t// already async\n\t\telse {\n\t\t\t// invoke original function\n\t\t\torig_fn.apply( this, arguments );\n\t\t}\n\t};\n}\n```\n\nYou use `asyncify(..)` like this:\n\n```js\nfunction result(data) {\n\tconsole.log( a );\n}\n\nvar a = 0;\n\najax( \"..pre-cached-url..\", asyncify( result ) );\na++;\n```\n\nWhether the Ajax request is in the cache and resolves to try to call the callback right away, or must be fetched over the wire and thus complete later asynchronously, this code will always output `1` instead of `0` -- `result(..)` cannot help but be invoked asynchronously, which means the `a++` has a chance to run before `result(..)` does.\n\nYay, another trust issued \"solved\"! But it's inefficient, and yet again more bloated boilerplate to weigh your project down.\n\nThat's just the story, over and over again, with callbacks. They can do pretty much anything you want, but you have to be willing to work hard to get it, and oftentimes this effort is much more than you can or should spend on such code reasoning.\n\nYou might find yourself wishing for built-in APIs or other language mechanics to address these issues. Finally ES6 has arrived on the scene with some great answers, so keep reading!\n\n## Review\n\nCallbacks are the fundamental unit of asynchrony in JS. But they're not enough for the evolving landscape of async programming as JS matures.\n\nFirst, our brains plan things out in sequential, blocking, single-threaded semantic ways, but callbacks express asynchronous flow in a rather nonlinear, nonsequential way, which makes reasoning properly about such code much harder. Bad to reason about code is bad code that leads to bad bugs.\n\nWe need a way to express asynchrony in a more synchronous, sequential, blocking manner, just like our brains do.\n\nSecond, and more importantly, callbacks suffer from *inversion of control* in that they implicitly give control over to another party (often a third-party utility not in your control!) to invoke the *continuation* of your program. This control transfer leads us to a troubling list of trust issues, such as whether the callback is called more times than we expect.\n\nInventing ad hoc logic to solve these trust issues is possible, but it's more difficult than it should be, and it produces clunkier and harder to maintain code, as well as code that is likely insufficiently protected from these hazards until you get visibly bitten by the bugs.\n\nWe need a generalized solution to **all of the trust issues**, one that can be reused for as many callbacks as we create without all the extra boilerplate overhead.\n\nWe need something better than callbacks. They've served us well to this point, but the *future* of JavaScript demands more sophisticated and capable async patterns. The subsequent chapters in this book will dive into those emerging evolutions.\n"
},
{
"path": "async & performance/ch3.md",
"content": "# You Don't Know JS: Async & Performance\n# Chapter 3: Promises\n\nIn Chapter 2, we identified two major categories of deficiencies with using callbacks to express program asynchrony and manage concurrency: lack of sequentiality and lack of trustability. Now that we understand the problems more intimately, it's time we turn our attention to patterns that can address them.\n\nThe issue we want to address first is the *inversion of control*, the trust that is so fragilely held and so easily lost.\n\nRecall that we wrap up the *continuation* of our program in a callback function, and hand that callback over to another party (potentially even external code) and just cross our fingers that it will do the right thing with the invocation of the callback.\n\nWe do this because we want to say, \"here's what happens *later*, after the current step finishes.\"\n\nBut what if we could uninvert that *inversion of control*? What if instead of handing the continuation of our program to another party, we could expect it to return us a capability to know when its task finishes, and then our code could decide what to do next?\n\nThis paradigm is called **Promises**.\n\nPromises are starting to take the JS world by storm, as developers and specification writers alike desperately seek to untangle the insanity of callback hell in their code/design. In fact, most new async APIs being added to JS/DOM platform are being built on Promises. So it's probably a good idea to dig in and learn them, don't you think!?\n\n**Note:** The word \"immediately\" will be used frequently in this chapter, generally to refer to some Promise resolution action. However, in essentially all cases, \"immediately\" means in terms of the Job queue behavior (see Chapter 1), not in the strictly synchronous *now* sense.\n\n## What Is a Promise?\n\nWhen developers decide to learn a new technology or pattern, usually their first step is \"Show me the code!\" It's quite natural for us to just jump in feet first and learn as we go.\n\nBut it turns out that some abstractions get lost on the APIs alone. Promises are one of those tools where it can be painfully obvious from how someone uses it whether they understand what it's for and about versus just learning and using the API.\n\nSo before I show the Promise code, I want to fully explain what a Promise really is conceptually. I hope this will then guide you better as you explore integrating Promise theory into your own async flow.\n\nWith that in mind, let's look at two different analogies for what a Promise *is*.\n\n### Future Value\n\nImagine this scenario: I walk up to the counter at a fast-food restaurant, and place an order for a cheeseburger. I hand the cashier $1.47. By placing my order and paying for it, I've made a request for a *value* back (the cheeseburger). I've started a transaction.\n\nBut often, the cheeseburger is not immediately available for me. The cashier hands me something in place of my cheeseburger: a receipt with an order number on it. This order number is an IOU (\"I owe you\") *promise* that ensures that eventually, I should receive my cheeseburger.\n\nSo I hold onto my receipt and order number. I know it represents my *future cheeseburger*, so I don't need to worry about it anymore -- aside from being hungry!\n\nWhile I wait, I can do other things, like send a text message to a friend that says, \"Hey, can you come join me for lunch? I'm going to eat a cheeseburger.\"\n\nI am reasoning about my *future cheeseburger* already, even though I don't have it in my hands yet. My brain is able to do this because it's treating the order number as a placeholder for the cheeseburger. The placeholder essentially makes the value *time independent*. It's a **future value**.\n\nEventually, I hear, \"Order 113!\" and I gleefully walk back up to the counter with receipt in hand. I hand my receipt to the cashier, and I take my cheeseburger in return.\n\nIn other words, once my *future value* was ready, I exchanged my value-promise for the value itself.\n\nBut there's another possible outcome. They call my order number, but when I go to retrieve my cheeseburger, the cashier regretfully informs me, \"I'm sorry, but we appear to be all out of cheeseburgers.\" Setting aside the customer frustration of this scenario for a moment, we can see an important characteristic of *future values*: they can either indicate a success or failure.\n\nEvery time I order a cheeseburger, I know that I'll either get a cheeseburger eventually, or I'll get the sad news of the cheeseburger shortage, and I'll have to figure out something else to eat for lunch.\n\n**Note:** In code, things are not quite as simple, because metaphorically the order number may never be called, in which case we're left indefinitely in an unresolved state. We'll come back to dealing with that case later.\n\n#### Values Now and Later\n\nThis all might sound too mentally abstract to apply to your code. So let's be more concrete.\n\nHowever, before we can introduce how Promises work in this fashion, we're going to derive in code that we already understand -- callbacks! -- how to handle these *future values*.\n\nWhen you write code to reason about a value, such as performing math on a `number`, whether you realize it or not, you've been assuming something very fundamental about that value, which is that it's a concrete *now* value already:\n\n```js\nvar x, y = 2;\n\nconsole.log( x + y ); // NaN <-- because `x` isn't set yet\n```\n\nThe `x + y` operation assumes both `x` and `y` are already set. In terms we'll expound on shortly, we assume the `x` and `y` values are already *resolved*.\n\nIt would be nonsense to expect that the `+` operator by itself would somehow be magically capable of detecting and waiting around until both `x` and `y` are resolved (aka ready), only then to do the operation. That would cause chaos in the program if different statements finished *now* and others finished *later*, right?\n\nHow could you possibly reason about the relationships between two statements if either one (or both) of them might not be finished yet? If statement 2 relies on statement 1 being finished, there are just two outcomes: either statement 1 finished right *now* and everything proceeds fine, or statement 1 didn't finish yet, and thus statement 2 is going to fail.\n\nIf this sort of thing sounds familiar from Chapter 1, good!\n\nLet's go back to our `x + y` math operation. Imagine if there was a way to say, \"Add `x` and `y`, but if either of them isn't ready yet, just wait until they are. Add them as soon as you can.\"\n\nYour brain might have just jumped to callbacks. OK, so...\n\n```js\nfunction add(getX,getY,cb) {\n\tvar x, y;\n\tgetX( function(xVal){\n\t\tx = xVal;\n\t\t// both are ready?\n\t\tif (y != undefined) {\n\t\t\tcb( x + y );\t// send along sum\n\t\t}\n\t} );\n\tgetY( function(yVal){\n\t\ty = yVal;\n\t\t// both are ready?\n\t\tif (x != undefined) {\n\t\t\tcb( x + y );\t// send along sum\n\t\t}\n\t} );\n}\n\n// `fetchX()` and `fetchY()` are sync or async\n// functions\nadd( fetchX, fetchY, function(sum){\n\tconsole.log( sum ); // that was easy, huh?\n} );\n```\n\nTake just a moment to let the beauty (or lack thereof) of that snippet sink in (whistles patiently).\n\nWhile the ugliness is undeniable, there's something very important to notice about this async pattern.\n\nIn that snippet, we treated `x` and `y` as future values, and we express an operation `add(..)` that (from the outside) does not care whether `x` or `y` or both are available right away or not. In other words, it normalizes the *now* and *later*, such that we can rely on a predictable outcome of the `add(..)` operation.\n\nBy using an `add(..)` that is temporally consistent -- it behaves the same across *now* and *later* times -- the async code is much easier to reason about.\n\nTo put it more plainly: to consistently handle both *now* and *later*, we make both of them *later*: all operations become async.\n\nOf course, this rough callbacks-based approach leaves much to be desired. It's just a first tiny step toward realizing the benefits of reasoning about *future values* without worrying about the time aspect of when it's available or not.\n\n#### Promise Value\n\nWe'll definitely go into a lot more detail about Promises later in the chapter -- so don't worry if some of this is confusing -- but let's just briefly glimpse at how we can express the `x + y` example via `Promise`s:\n\n```js\nfunction add(xPromise,yPromise) {\n\t// `Promise.all([ .. ])` takes an array of promises,\n\t// and returns a new promise that waits on them\n\t// all to finish\n\treturn Promise.all( [xPromise, yPromise] )\n\n\t// when that promise is resolved, let's take the\n\t// received `X` and `Y` values and add them together.\n\t.then( function(values){\n\t\t// `values` is an array of the messages from the\n\t\t// previously resolved promises\n\t\treturn values[0] + values[1];\n\t} );\n}\n\n// `fetchX()` and `fetchY()` return promises for\n// their respective values, which may be ready\n// *now* or *later*.\nadd( fetchX(), fetchY() )\n\n// we get a promise back for the sum of those\n// two numbers.\n// now we chain-call `then(..)` to wait for the\n// resolution of that returned promise.\n.then( function(sum){\n\tconsole.log( sum ); // that was easier!\n} );\n```\n\nThere are two layers of Promises in this snippet.\n\n`fetchX()` and `fetchY()` are called directly, and the values they return (promises!) are passed into `add(..)`. The underlying values those promises represent may be ready *now* or *later*, but each promise normalizes the behavior to be the same regardless. We reason about `X` and `Y` values in a time-independent way. They are *future values*.\n\nThe second layer is the promise that `add(..)` creates (via `Promise.all([ .. ])`) and returns, which we wait on by calling `then(..)`. When the `add(..)` operation completes, our `sum` *future value* is ready and we can print it out. We hide inside of `add(..)` the logic for waiting on the `X` and `Y` *future values*.\n\n**Note:** Inside `add(..)`, the `Promise.all([ .. ])` call creates a promise (which is waiting on `promiseX` and `promiseY` to resolve). The chained call to `.then(..)` creates another promise, which the `return values[0] + values[1]` line immediately resolves (with the result of the addition). Thus, the `then(..)` call we chain off the end of the `add(..)` call -- at the end of the snippet -- is actually operating on that second promise returned, rather than the first one created by `Promise.all([ .. ])`. Also, though we are not chaining off the end of that second `then(..)`, it too has created another promise, had we chosen to observe/use it. This Promise chaining stuff will be explained in much greater detail later in this chapter.\n\nJust like with cheeseburger orders, it's possible that the resolution of a Promise is rejection instead of fulfillment. Unlike a fulfilled Promise, where the value is always programmatic, a rejection value -- commonly called a \"rejection reason\" -- can either be set directly by the program logic, or it can result implicitly from a runtime exception.\n\nWith Promises, the `then(..)` call can actually take two functions, the first for fulfillment (as shown earlier), and the second for rejection:\n\n```js\nadd( fetchX(), fetchY() )\n.then(\n\t// fulfillment handler\n\tfunction(sum) {\n\t\tconsole.log( sum );\n\t},\n\t// rejection handler\n\tfunction(err) {\n\t\tconsole.error( err ); // bummer!\n\t}\n);\n```\n\nIf something went wrong getting `X` or `Y`, or something somehow failed during the addition, the promise that `add(..)` returns is rejected, and the second callback error handler passed to `then(..)` will receive the rejection value from the promise.\n\nBecause Promises encapsulate the time-dependent state -- waiting on the fulfillment or rejection of the underlying value -- from the outside, the Promise itself is time-independent, and thus Promises can be composed (combined) in predictable ways regardless of the timing or outcome underneath.\n\nMoreover, once a Promise is resolved, it stays that way forever -- it becomes an *immutable value* at that point -- and can then be *observed* as many times as necessary.\n\n**Note:** Because a Promise is externally immutable once resolved, it's now safe to pass that value around to any party and know that it cannot be modified accidentally or maliciously. This is especially true in relation to multiple parties observing the resolution of a Promise. It is not possible for one party to affect another party's ability to observe Promise resolution. Immutability may sound like an academic topic, but it's actually one of the most fundamental and important aspects of Promise design, and shouldn't be casually passed over.\n\nThat's one of the most powerful and important concepts to understand about Promises. With a fair amount of work, you could ad hoc create the same effects with nothing but ugly callback composition, but that's not really an effective strategy, especially because you have to do it over and over again.\n\nPromises are an easily repeatable mechanism for encapsulating and composing *future values*.\n\n### Completion Event\n\nAs we just saw, an individual Promise behaves as a *future value*. But there's another way to think of the resolution of a Promise: as a flow-control mechanism -- a temporal this-then-that -- for two or more steps in an asynchronous task.\n\nLet's imagine calling a function `foo(..)` to perform some task. We don't know about any of its details, nor do we care. It may complete the task right away, or it may take a while.\n\nWe just simply need to know when `foo(..)` finishes so that we can move on to our next task. In other words, we'd like a way to be notified of `foo(..)`'s completion so that we can *continue*.\n\nIn typical JavaScript fashion, if you need to listen for a notification, you'd likely think of that in terms of events. So we could reframe our need for notification as a need to listen for a *completion* (or *continuation*) event emitted by `foo(..)`.\n\n**Note:** Whether you call it a \"completion event\" or a \"continuation event\" depends on your perspective. Is the focus more on what happens with `foo(..)`, or what happens *after* `foo(..)` finishes? Both perspectives are accurate and useful. The event notification tells us that `foo(..)` has *completed*, but also that it's OK to *continue* with the next step. Indeed, the callback you pass to be called for the event notification is itself what we've previously called a *continuation*. Because *completion event* is a bit more focused on the `foo(..)`, which more has our attention at present, we slightly favor *completion event* for the rest of this text.\n\nWith callbacks, the \"notification\" would be our callback invoked by the task (`foo(..)`). But with Promises, we turn the relationship around, and expect that we can listen for an event from `foo(..)`, and when notified, proceed accordingly.\n\nFirst, consider some pseudocode:\n\n```js\nfoo(x) {\n\t// start doing something that could take a while\n}\n\nfoo( 42 )\n\non (foo \"completion\") {\n\t// now we can do the next step!\n}\n\non (foo \"error\") {\n\t// oops, something went wrong in `foo(..)`\n}\n```\n\nWe call `foo(..)` and then we set up two event listeners, one for `\"completion\"` and one for `\"error\"` -- the two possible *final* outcomes of the `foo(..)` call. In essence, `foo(..)` doesn't even appear to be aware that the calling code has subscribed to these events, which makes for a very nice *separation of concerns*.\n\nUnfortunately, such code would require some \"magic\" of the JS environment that doesn't exist (and would likely be a bit impractical). Here's the more natural way we could express that in JS:\n\n```js\nfunction foo(x) {\n\t// start doing something that could take a while\n\n\t// make a `listener` event notification\n\t// capability to return\n\n\treturn listener;\n}\n\nvar evt = foo( 42 );\n\nevt.on( \"completion\", function(){\n\t// now we can do the next step!\n} );\n\nevt.on( \"failure\", function(err){\n\t// oops, something went wrong in `foo(..)`\n} );\n```\n\n`foo(..)` expressly creates an event subscription capability to return back, and the calling code receives and registers the two event handlers against it.\n\nThe inversion from normal callback-oriented code should be obvious, and it's intentional. Instead of passing the callbacks to `foo(..)`, it returns an event capability we call `evt`, which receives the callbacks.\n\nBut if you recall from Chapter 2, callbacks themselves represent an *inversion of control*. So inverting the callback pattern is actually an *inversion of inversion*, or an *uninversion of control* -- restoring control back to the calling code where we wanted it to be in the first place.\n\nOne important benefit is that multiple separate parts of the code can be given the event listening capability, and they can all independently be notified of when `foo(..)` completes to perform subsequent steps after its completion:\n\n```js\nvar evt = foo( 42 );\n\n// let `bar(..)` listen to `foo(..)`'s completion\nbar( evt );\n\n// also, let `baz(..)` listen to `foo(..)`'s completion\nbaz( evt );\n```\n\n*Uninversion of control* enables a nicer *separation of concerns*, where `bar(..)` and `baz(..)` don't need to be involved in how `foo(..)` is called. Similarly, `foo(..)` doesn't need to know or care that `bar(..)` and `baz(..)` exist or are waiting to be notified when `foo(..)` completes.\n\nEssentially, this `evt` object is a neutral third-party negotiation between the separate concerns.\n\n#### Promise \"Events\"\n\nAs you may have guessed by now, the `evt` event listening capability is an analogy for a Promise.\n\nIn a Promise-based approach, the previous snippet would have `foo(..)` creating and returning a `Promise` instance, and that promise would then be passed to `bar(..)` and `baz(..)`.\n\n**Note:** The Promise resolution \"events\" we listen for aren't strictly events (though they certainly behave like events for these purposes), and they're not typically called `\"completion\"` or `\"error\"`. Instead, we use `then(..)` to register a `\"then\"` event. Or perhaps more precisely, `then(..)` registers `\"fulfillment\"` and/or `\"rejection\"` event(s), though we don't see those terms used explicitly in the code.\n\nConsider:\n\n```js\nfunction foo(x) {\n\t// start doing something that could take a while\n\n\t// construct and return a promise\n\treturn new Promise( function(resolve,reject){\n\t\t// eventually, call `resolve(..)` or `reject(..)`,\n\t\t// which are the resolution callbacks for\n\t\t// the promise.\n\t} );\n}\n\nvar p = foo( 42 );\n\nbar( p );\n\nbaz( p );\n```\n\n**Note:** The pattern shown with `new Promise( function(..){ .. } )` is generally called the [\"revealing constructor\"](http://domenic.me/2014/02/13/the-revealing-constructor-pattern/). The function passed in is executed immediately (not async deferred, as callbacks to `then(..)` are), and it's provided two parameters, which in this case we've named `resolve` and `reject`. These are the resolution functions for the promise. `resolve(..)` generally signals fulfillment, and `reject(..)` signals rejection.\n\nYou can probably guess what the internals of `bar(..)` and `baz(..)` might look like:\n\n```js\nfunction bar(fooPromise) {\n\t// listen for `foo(..)` to complete\n\tfooPromise.then(\n\t\tfunction(){\n\t\t\t// `foo(..)` has now finished, so\n\t\t\t// do `bar(..)`'s task\n\t\t},\n\t\tfunction(){\n\t\t\t// oops, something went wrong in `foo(..)`\n\t\t}\n\t);\n}\n\n// ditto for `baz(..)`\n```\n\nPromise resolution doesn't necessarily need to involve sending along a message, as it did when we were examining Promises as *future values*. It can just be a flow-control signal, as used in the previous snippet.\n\nAnother way to approach this is:\n\n```js\nfunction bar() {\n\t// `foo(..)` has definitely finished, so\n\t// do `bar(..)`'s task\n}\n\nfunction oopsBar() {\n\t// oops, something went wrong in `foo(..)`,\n\t// so `bar(..)` didn't run\n}\n\n// ditto for `baz()` and `oopsBaz()`\n\nvar p = foo( 42 );\n\np.then( bar, oopsBar );\n\np.then( baz, oopsBaz );\n```\n\n**Note:** If you've seen Promise-based coding before, you might be tempted to believe that the last two lines of that code could be written as `p.then( .. ).then( .. )`, using chaining, rather than `p.then(..); p.then(..)`. That would have an entirely different behavior, so be careful! The difference might not be clear right now, but it's actually a different async pattern than we've seen thus far: splitting/forking. Don't worry! We'll come back to this point later in this chapter.\n\nInstead of passing the `p` promise to `bar(..)` and `baz(..)`, we use the promise to control when `bar(..)` and `baz(..)` will get executed, if ever. The primary difference is in the error handling.\n\nIn the first snippet's approach, `bar(..)` is called regardless of whether `foo(..)` succeeds or fails, and it handles its own fallback logic if it's notified that `foo(..)` failed. The same is true for `baz(..)`, obviously.\n\nIn the second snippet, `bar(..)` only gets called if `foo(..)` succeeds, and otherwise `oopsBar(..)` gets called. Ditto for `baz(..)`.\n\nNeither approach is *correct* per se. There will be cases where one is preferred over the other.\n\nIn either case, the promise `p` that comes back from `foo(..)` is used to control what happens next.\n\nMoreover, the fact that both snippets end up calling `then(..)` twice against the same promise `p` illustrates the point made earlier, which is that Promises (once resolved) retain their same resolution (fulfillment or rejection) forever, and can subsequently be observed as many times as necessary.\n\nWhenever `p` is resolved, the next step will always be the same, both *now* and *later*.\n\n## Thenable Duck Typing\n\nIn Promises-land, an important detail is how to know for sure if some value is a genuine Promise or not. Or more directly, is it a value that will behave like a Promise?\n\nGiven that Promises are constructed by the `new Promise(..)` syntax, you might think that `p instanceof Promise` would be an acceptable check. But unfortunately, there are a number of reasons that's not totally sufficient.\n\nMainly, you can receive a Promise value from another browser window (iframe, etc.), which would have its own Promise different from the one in the current window/frame, and that check would fail to identify the Promise instance.\n\nMoreover, a library or framework may choose to vend its own Promises and not use the native ES6 `Promise` implementation to do so. In fact, you may very well be using Promises with libraries in older browsers that have no Promise at all.\n\nWhen we discuss Promise resolution processes later in this chapter, it will become more obvious why a non-genuine-but-Promise-like value would still be very important to be able to recognize and assimilate. But for now, just take my word for it that it's a critical piece of the puzzle.\n\nAs such, it was decided that the way to recognize a Promise (or something that behaves like a Promise) would be to define something called a \"thenable\" as any object or function which has a `then(..)` method on it. It is assumed that any such value is a Promise-conforming thenable.\n\nThe general term for \"type checks\" that make assumptions about a value's \"type\" based on its shape (what properties are present) is called \"duck typing\" -- \"If it looks like a duck, and quacks like a duck, it must be a duck\" (see the *Types & Grammar* title of this book series). So the duck typing check for a thenable would roughly be:\n\n```js\nif (\n\tp !== null &&\n\t(\n\t\ttypeof p === \"object\" ||\n\t\ttypeof p === \"function\"\n\t) &&\n\ttypeof p.then === \"function\"\n) {\n\t// assume it's a thenable!\n}\nelse {\n\t// not a thenable\n}\n```\n\nYuck! Setting aside the fact that this logic is a bit ugly to implement in various places, there's something deeper and more troubling going on.\n\nIf you try to fulfill a Promise with any object/function value that happens to have a `then(..)` function on it, but you weren't intending it to be treated as a Promise/thenable, you're out of luck, because it will automatically be recognized as thenable and treated with special rules (see later in the chapter).\n\nThis is even true if you didn't realize the value has a `then(..)` on it. For example:\n\n```js\nvar o = { then: function(){} };\n\n// make `v` be `[[Prototype]]`-linked to `o`\nvar v = Object.create( o );\n\nv.someStuff = \"cool\";\nv.otherStuff = \"not so cool\";\n\nv.hasOwnProperty( \"then\" );\t\t// false\n```\n\n`v` doesn't look like a Promise or thenable at all. It's just a plain object with some properties on it. You're probably just intending to send that value around like any other object.\n\nBut unknown to you, `v` is also `[[Prototype]]`-linked (see the *this & Object Prototypes* title of this book series) to another object `o`, which happens to have a `then(..)` on it. So the thenable duck typing checks will think and assume `v` is a thenable. Uh oh.\n\nIt doesn't even need to be something as directly intentional as that:\n\n```js\nObject.prototype.then = function(){};\nArray.prototype.then = function(){};\n\nvar v1 = { hello: \"world\" };\nvar v2 = [ \"Hello\", \"World\" ];\n```\n\nBoth `v1` and `v2` will be assumed to be thenables. You can't control or predict if any other code accidentally or maliciously adds `then(..)` to `Object.prototype`, `Array.prototype`, or any of the other native prototypes. And if what's specified is a function that doesn't call either of its parameters as callbacks, then any Promise resolved with such a value will just silently hang forever! Crazy.\n\nSound implausible or unlikely? Perhaps.\n\nBut keep in mind that there were several well-known non-Promise libraries preexisting in the community prior to ES6 that happened to already have a method on them called `then(..)`. Some of those libraries chose to rename their own methods to avoid collision (that sucks!). Others have simply been relegated to the unfortunate status of \"incompatible with Promise-based coding\" in reward for their inability to change to get out of the way.\n\nThe standards decision to hijack the previously nonreserved -- and completely general-purpose sounding -- `then` property name means that no value (or any of its delegates), either past, present, or future, can have a `then(..)` function present, either on purpose or by accident, or that value will be confused for a thenable in Promises systems, which will probably create bugs that are really hard to track down.\n\n**Warning:** I do not like how we ended up with duck typing of thenables for Promise recognition. There were other options, such as \"branding\" or even \"anti-branding\"; what we got seems like a worst-case compromise. But it's not all doom and gloom. Thenable duck typing can be helpful, as we'll see later. Just beware that thenable duck typing can be hazardous if it incorrectly identifies something as a Promise that isn't.\n\n## Promise Trust\n\nWe've now seen two strong analogies that explain different aspects of what Promises can do for our async code. But if we stop there, we've missed perhaps the single most important characteristic that the Promise pattern establishes: trust.\n\nWhereas the *future values* and *completion events* analogies play out explicitly in the code patterns we've explored, it won't be entirely obvious why or how Promises are designed to solve all of the *inversion of control* trust issues we laid out in the \"Trust Issues\" section of Chapter 2. But with a little digging, we can uncover some important guarantees that restore the confidence in async coding that Chapter 2 tore down!\n\nLet's start by reviewing the trust issues with callbacks-only coding. When you pass a callback to a utility `foo(..)`, it might:\n\n* Call the callback too early\n* Call the callback too late (or never)\n* Call the callback too few or too many times\n* Fail to pass along any necessary environment/parameters\n* Swallow any errors/exceptions that may happen\n\nThe characteristics of Promises are intentionally designed to provide useful, repeatable answers to all these concerns.\n\n### Calling Too Early\n\nPrimarily, this is a concern of whether code can introduce Zalgo-like effects (see Chapter 2), where sometimes a task finishes synchronously and sometimes asynchronously, which can lead to race conditions.\n\nPromises by definition cannot be susceptible to this concern, because even an immediately fulfilled Promise (like `new Promise(function(resolve){ resolve(42); })`) cannot be *observed* synchronously.\n\nThat is, when you call `then(..)` on a Promise, even if that Promise was already resolved, the callback you provide to `then(..)` will **always** be called asynchronously (for more on this, refer back to \"Jobs\" in Chapter 1).\n\nNo more need to insert your own `setTimeout(..,0)` hacks. Promises prevent Zalgo automatically.\n\n### Calling Too Late\n\nSimilar to the previous point, a Promise's `then(..)` registered observation callbacks are automatically scheduled when either `resolve(..)` or `reject(..)` are called by the Promise creation capability. Those scheduled callbacks will predictably be fired at the next asynchronous moment (see \"Jobs\" in Chapter 1).\n\nIt's not possible for synchronous observation, so it's not possible for a synchronous chain of tasks to run in such a way to in effect \"delay\" another callback from happening as expected. That is, when a Promise is resolved, all `then(..)` registered callbacks on it will be called, in order, immediately at the next asynchronous opportunity (again, see \"Jobs\" in Chapter 1), and nothing that happens inside of one of those callbacks can affect/delay the calling of the other callbacks.\n\nFor example:\n\n```js\np.then( function(){\n\tp.then( function(){\n\t\tconsole.log( \"C\" );\n\t} );\n\tconsole.log( \"A\" );\n} );\np.then( function(){\n\tconsole.log( \"B\" );\n} );\n// A B C\n```\n\nHere, `\"C\"` cannot interrupt and precede `\"B\"`, by virtue of how Promises are defined to operate.\n\n#### Promise Scheduling Quirks\n\nIt's important to note, though, that there are lots of nuances of scheduling where the relative ordering between callbacks chained off two separate Promises is not reliably predictable.\n\nIf two promises `p1` and `p2` are both already resolved, it should be true that `p1.then(..); p2.then(..)` would end up calling the callback(s) for `p1` before the ones for `p2`. But there are subtle cases where that might not be true, such as the following:\n\n```js\nvar p3 = new Promise( function(resolve,reject){\n\tresolve( \"B\" );\n} );\n\nvar p1 = new Promise( function(resolve,reject){\n\tresolve( p3 );\n} );\n\nvar p2 = new Promise( function(resolve,reject){\n\tresolve( \"A\" );\n} );\n\np1.then( function(v){\n\tconsole.log( v );\n} );\n\np2.then( function(v){\n\tconsole.log( v );\n} );\n\n// A B <-- not B A as you might expect\n```\n\nWe'll cover this more later, but as you can see, `p1` is resolved not with an immediate value, but with another promise `p3` which is itself resolved with the value `\"B\"`. The specified behavior is to *unwrap* `p3` into `p1`, but asynchronously, so `p1`'s callback(s) are *behind* `p2`'s callback(s) in the asynchronous Job queue (see Chapter 1).\n\nTo avoid such nuanced nightmares, you should never rely on anything about the ordering/scheduling of callbacks across Promises. In fact, a good practice is not to code in such a way where the ordering of multiple callbacks matters at all. Avoid that if you can.\n\n### Never Calling the Callback\n\nThis is a very common concern. It's addressable in several ways with Promises.\n\nFirst, nothing (not even a JS error) can prevent a Promise from notifying you of its resolution (if it's resolved). If you register both fulfillment and rejection callbacks for a Promise, and the Promise gets resolved, one of the two callbacks will always be called.\n\nOf course, if your callbacks themselves have JS errors, you may not see the outcome you expect, but the callback will in fact have been called. We'll cover later how to be notified of an error in your callback, because even those don't get swallowed.\n\nBut what if the Promise itself never gets resolved either way? Even that is a condition that Promises provide an answer for, using a higher level abstraction called a \"race\":\n\n```js\n// a utility for timing out a Promise\nfunction timeoutPromise(delay) {\n\treturn new Promise( function(resolve,reject){\n\t\tsetTimeout( function(){\n\t\t\treject( \"Timeout!\" );\n\t\t}, delay );\n\t} );\n}\n\n// setup a timeout for `foo()`\nPromise.race( [\n\tfoo(),\t\t\t\t\t// attempt `foo()`\n\ttimeoutPromise( 3000 )\t// give it 3 seconds\n] )\n.then(\n\tfunction(){\n\t\t// `foo(..)` fulfilled in time!\n\t},\n\tfunction(err){\n\t\t// either `foo()` rejected, or it just\n\t\t// didn't finish in time, so inspect\n\t\t// `err` to know which\n\t}\n);\n```\n\nThere are more details to consider with this Promise timeout pattern, but we'll come back to it later.\n\nImportantly, we can ensure a signal as to the outcome of `foo()`, to prevent it from hanging our program indefinitely.\n\n### Calling Too Few or Too Many Times\n\nBy definition, *one* is the appropriate number of times for the callback to be called. The \"too few\" case would be zero calls, which is the same as the \"never\" case we just examined.\n\nThe \"too many\" case is easy to explain. Promises are defined so that they can only be resolved once. If for some reason the Promise creation code tries to call `resolve(..)` or `reject(..)` multiple times, or tries to call both, the Promise will accept only the first resolution, and will silently ignore any subsequent attempts.\n\nBecause a Promise can only be resolved once, any `then(..)` registered callbacks will only ever be called once (each).\n\nOf course, if you register the same callback more than once, (e.g., `p.then(f); p.then(f);`), it'll be called as many times as it was registered. The guarantee that a response function is called only once does not prevent you from shooting yourself in the foot.\n\n### Failing to Pass Along Any Parameters/Environment\n\nPromises can have, at most, one resolution value (fulfillment or rejection).\n\nIf you don't explicitly resolve with a value either way, the value is `undefined`, as is typical in JS. But whatever the value, it will always be passed to all registered (and appropriate: fulfillment or rejection) callbacks, either *now* or in the future.\n\nSomething to be aware of: If you call `resolve(..)` or `reject(..)` with multiple parameters, all subsequent parameters beyond the first will be silently ignored. Although that might seem a violation of the guarantee we just described, it's not exactly, because it constitutes an invalid usage of the Promise mechanism. Other invalid usages of the API (such as calling `resolve(..)` multiple times) are similarly *protected*, so the Promise behavior here is consistent (if not a tiny bit frustrating).\n\nIf you want to pass along multiple values, you must wrap them in another single value that you pass, such as an `array` or an `object`.\n\nAs for environment, functions in JS always retain their closure of the scope in which they're defined (see the *Scope & Closures* title of this series), so they of course would continue to have access to whatever surrounding state you provide. Of course, the same is true of callbacks-only design, so this isn't a specific augmentation of benefit from Promises -- but it's a guarantee we can rely on nonetheless.\n\n### Swallowing Any Errors/Exceptions\n\nIn the base sense, this is a restatement of the previous point. If you reject a Promise with a *reason* (aka error message), that value is passed to the rejection callback(s).\n\nBut there's something much bigger at play here. If at any point in the creation of a Promise, or in the observation of its resolution, a JS exception error occurs, such as a `TypeError` or `ReferenceError`, that exception will be caught, and it will force the Promise in question to become rejected.\n\nFor example:\n\n```js\nvar p = new Promise( function(resolve,reject){\n\tfoo.bar();\t// `foo` is not defined, so error!\n\tresolve( 42 );\t// never gets here :(\n} );\n\np.then(\n\tfunction fulfilled(){\n\t\t// never gets here :(\n\t},\n\tfunction rejected(err){\n\t\t// `err` will be a `TypeError` exception object\n\t\t// from the `foo.bar()` line.\n\t}\n);\n```\n\nThe JS exception that occurs from `foo.bar()` becomes a Promise rejection that you can catch and respond to.\n\nThis is an important detail, because it effectively solves another potential Zalgo moment, which is that errors could create a synchronous reaction whereas nonerrors would be asynchronous. Promises turn even JS exceptions into asynchronous behavior, thereby reducing the race condition chances greatly.\n\nBut what happens if a Promise is fulfilled, but there's a JS exception error during the observation (in a `then(..)` registered callback)? Even those aren't lost, but you may find how they're handled a bit surprising, until you dig in a little deeper:\n\n```js\nvar p = new Promise( function(resolve,reject){\n\tresolve( 42 );\n} );\n\np.then(\n\tfunction fulfilled(msg){\n\t\tfoo.bar();\n\t\tconsole.log( msg );\t// never gets here :(\n\t},\n\tfunction rejected(err){\n\t\t// never gets here either :(\n\t}\n);\n```\n\nWait, that makes it seem like the exception from `foo.bar()` really did get swallowed. Never fear, it didn't. But something deeper is wrong, which is that we've failed to listen for it. The `p.then(..)` call itself returns another promise, and it's *that* promise that will be rejected with the `TypeError` exception.\n\nWhy couldn't it just call the error handler we have defined there? Seems like a logical behavior on the surface. But it would violate the fundamental principle that Promises are **immutable** once resolved. `p` was already fulfilled to the value `42`, so it can't later be changed to a rejection just because there's an error in observing `p`'s resolution.\n\nBesides the principle violation, such behavior could wreak havoc, if say there were multiple `then(..)` registered callbacks on the promise `p`, because some would get called and others wouldn't, and it would be very opaque as to why.\n\n### Trustable Promise?\n\nThere's one last detail to examine to establish trust based on the Promise pattern.\n\nYou've no doubt noticed that Promises don't get rid of callbacks at all. They just change where the callback is passed to. Instead of passing a callback to `foo(..)`, we get *something* (ostensibly a genuine Promise) back from `foo(..)`, and we pass the callback to that *something* instead.\n\nBut why would this be any more trustable than just callbacks alone? How can we be sure the *something* we get back is in fact a trustable Promise? Isn't it basically all just a house of cards where we can trust only because we already trusted?\n\nOne of the most important, but often overlooked, details of Promises is that they have a solution to this issue as well. Included with the native ES6 `Promise` implementation is `Promise.resolve(..)`.\n\nIf you pass an immediate, non-Promise, non-thenable value to `Promise.resolve(..)`, you get a promise that's fulfilled with that value. In other words, these two promises `p1` and `p2` will behave basically identically:\n\n```js\nvar p1 = new Promise( function(resolve,reject){\n\tresolve( 42 );\n} );\n\nvar p2 = Promise.resolve( 42 );\n```\n\nBut if you pass a genuine Promise to `Promise.resolve(..)`, you just get the same promise back:\n\n```js\nvar p1 = Promise.resolve( 42 );\n\nvar p2 = Promise.resolve( p1 );\n\np1 === p2; // true\n```\n\nEven more importantly, if you pass a non-Promise thenable value to `Promise.resolve(..)`, it will attempt to unwrap that value, and the unwrapping will keep going until a concrete final non-Promise-like value is extracted.\n\nRecall our previous discussion of thenables?\n\nConsider:\n\n```js\nvar p = {\n\tthen: function(cb) {\n\t\tcb( 42 );\n\t}\n};\n\n// this works OK, but only by good fortune\np\n.then(\n\tfunction fulfilled(val){\n\t\tconsole.log( val ); // 42\n\t},\n\tfunction rejected(err){\n\t\t// never gets here\n\t}\n);\n```\n\nThis `p` is a thenable, but it's not a genuine Promise. Luckily, it's reasonable, as most will be. But what if you got back instead something that looked like:\n\n```js\nvar p = {\n\tthen: function(cb,errcb) {\n\t\tcb( 42 );\n\t\terrcb( \"evil laugh\" );\n\t}\n};\n\np\n.then(\n\tfunction fulfilled(val){\n\t\tconsole.log( val ); // 42\n\t},\n\tfunction rejected(err){\n\t\t// oops, shouldn't have run\n\t\tconsole.log( err ); // evil laugh\n\t}\n);\n```\n\nThis `p` is a thenable but it's not so well behaved of a promise. Is it malicious? Or is it just ignorant of how Promises should work? It doesn't really matter, to be honest. In either case, it's not trustable as is.\n\nNonetheless, we can pass either of these versions of `p` to `Promise.resolve(..)`, and we'll get the normalized, safe result we'd expect:\n\n```js\nPromise.resolve( p )\n.then(\n\tfunction fulfilled(val){\n\t\tconsole.log( val ); // 42\n\t},\n\tfunction rejected(err){\n\t\t// never gets here\n\t}\n);\n```\n\n`Promise.resolve(..)` will accept any thenable, and will unwrap it to its non-thenable value. But you get back from `Promise.resolve(..)` a real, genuine Promise in its place, **one that you can trust**. If what you passed in is already a genuine Promise, you just get it right back, so there's no downside at all to filtering through `Promise.resolve(..)` to gain trust.\n\nSo let's say we're calling a `foo(..)` utility and we're not sure we can trust its return value to be a well-behaving Promise, but we know it's at least a thenable. `Promise.resolve(..)` will give us a trustable Promise wrapper to chain off of:\n\n```js\n// don't just do this:\nfoo( 42 )\n.then( function(v){\n\tconsole.log( v );\n} );\n\n// instead, do this:\nPromise.resolve( foo( 42 ) )\n.then( function(v){\n\tconsole.log( v );\n} );\n```\n\n**Note:** Another beneficial side effect of wrapping `Promise.resolve(..)` around any function's return value (thenable or not) is that it's an easy way to normalize that function call into a well-behaving async task. If `foo(42)` returns an immediate value sometimes, or a Promise other times, `Promise.resolve( foo(42) )` makes sure it's always a Promise result. And avoiding Zalgo makes for much better code.\n\n### Trust Built\n\nHopefully the previous discussion now fully \"resolves\" (pun intended) in your mind why the Promise is trustable, and more importantly, why that trust is so critical in building robust, maintainable software.\n\nCan you write async code in JS without trust? Of course you can. We JS developers have been coding async with nothing but callbacks for nearly two decades.\n\nBut once you start questioning just how much you can trust the mechanisms you build upon to actually be predictable and reliable, you start to realize callbacks have a pretty shaky trust foundation.\n\nPromises are a pattern that augments callbacks with trustable semantics, so that the behavior is more reason-able and more reliable. By uninverting the *inversion of control* of callbacks, we place the control with a trustable system (Promises) that was designed specifically to bring sanity to our async.\n\n## Chain Flow\n\nWe've hinted at this a couple of times already, but Promises are not just a mechanism for a single-step *this-then-that* sort of operation. That's the building block, of course, but it turns out we can string multiple Promises together to represent a sequence of async steps.\n\nThe key to making this work is built on two behaviors intrinsic to Promises:\n\n* Every time you call `then(..)` on a Promise, it creates and returns a new Promise, which we can *chain* with.\n* Whatever value you return from the `then(..)` call's fulfillment callback (the first parameter) is automatically set as the fulfillment of the *chained* Promise (from the first point).\n\nLet's first illustrate what that means, and *then* we'll derive how that helps us create async sequences of flow control. Consider the following:\n\n```js\nvar p = Promise.resolve( 21 );\n\nvar p2 = p.then( function(v){\n\tconsole.log( v );\t// 21\n\n\t// fulfill `p2` with value `42`\n\treturn v * 2;\n} );\n\n// chain off `p2`\np2.then( function(v){\n\tconsole.log( v );\t// 42\n} );\n```\n\nBy returning `v * 2` (i.e., `42`), we fulfill the `p2` promise that the first `then(..)` call created and returned. When `p2`'s `then(..)` call runs, it's receiving the fulfillment from the `return v * 2` statement. Of course, `p2.then(..)` creates yet another promise, which we could have stored in a `p3` variable.\n\nBut it's a little annoying to have to create an intermediate variable `p2` (or `p3`, etc.). Thankfully, we can easily just chain these together:\n\n```js\nvar p = Promise.resolve( 21 );\n\np\n.then( function(v){\n\tconsole.log( v );\t// 21\n\n\t// fulfill the chained promise with value `42`\n\treturn v * 2;\n} )\n// here's the chained promise\n.then( function(v){\n\tconsole.log( v );\t// 42\n} );\n```\n\nSo now the first `then(..)` is the first step in an async sequence, and the second `then(..)` is the second step. This could keep going for as long as you needed it to extend. Just keep chaining off a previous `then(..)` with each automatically created Promise.\n\nBut there's something missing here. What if we want step 2 to wait for step 1 to do something asynchronous? We're using an immediate `return` statement, which immediately fulfills the chained promise.\n\nThe key to making a Promise sequence truly async capable at every step is to recall how `Promise.resolve(..)` operates when what you pass to it is a Promise or thenable instead of a final value. `Promise.resolve(..)` directly returns a received genuine Promise, or it unwraps the value of a received thenable -- and keeps going recursively while it keeps unwrapping thenables.\n\nThe same sort of unwrapping happens if you `return` a thenable or Promise from the fulfillment (or rejection) handler. Consider:\n\n```js\nvar p = Promise.resolve( 21 );\n\np.then( function(v){\n\tconsole.log( v );\t// 21\n\n\t// create a promise and return it\n\treturn new Promise( function(resolve,reject){\n\t\t// fulfill with value `42`\n\t\tresolve( v * 2 );\n\t} );\n} )\n.then( function(v){\n\tconsole.log( v );\t// 42\n} );\n```\n\nEven though we wrapped `42` up in a promise that we returned, it still got unwrapped and ended up as the resolution of the chained promise, such that the second `then(..)` still received `42`. If we introduce asynchrony to that wrapping promise, everything still nicely works the same:\n\n```js\nvar p = Promise.resolve( 21 );\n\np.then( function(v){\n\tconsole.log( v );\t// 21\n\n\t// create a promise to return\n\treturn new Promise( function(resolve,reject){\n\t\t// introduce asynchrony!\n\t\tsetTimeout( function(){\n\t\t\t// fulfill with value `42`\n\t\t\tresolve( v * 2 );\n\t\t}, 100 );\n\t} );\n} )\n.then( function(v){\n\t// runs after the 100ms delay in the previous step\n\tconsole.log( v );\t// 42\n} );\n```\n\nThat's incredibly powerful! Now we can construct a sequence of however many async steps we want, and each step can delay the next step (or not!), as necessary.\n\nOf course, the value passing from step to step in these examples is optional. If you don't return an explicit value, an implicit `undefined` is assumed, and the promises still chain together the same way. Each Promise resolution is thus just a signal to proceed to the next step.\n\nTo further the chain illustration, let's generalize a delay-Promise creation (without resolution messages) into a utility we can reuse for multiple steps:\n\n```js\nfunction delay(time) {\n\treturn new Promise( function(resolve,reject){\n\t\tsetTimeout( resolve, time );\n\t} );\n}\n\ndelay( 100 ) // step 1\n.then( function STEP2(){\n\tconsole.log( \"step 2 (after 100ms)\" );\n\treturn delay( 200 );\n} )\n.then( function STEP3(){\n\tconsole.log( \"step 3 (after another 200ms)\" );\n} )\n.then( function STEP4(){\n\tconsole.log( \"step 4 (next Job)\" );\n\treturn delay( 50 );\n} )\n.then( function STEP5(){\n\tconsole.log( \"step 5 (after another 50ms)\" );\n} )\n...\n```\n\nCalling `delay(200)` creates a promise that will fulfill in 200ms, and then we return that from the first `then(..)` fulfillment callback, which causes the second `then(..)`'s promise to wait on that 200ms promise.\n\n**Note:** As described, technically there are two promises in that interchange: the 200ms-delay promise and the chained promise that the second `then(..)` chains from. But you may find it easier to mentally combine these two promises together, because the Promise mechanism automatically merges their states for you. In that respect, you could think of `return delay(200)` as creating a promise that replaces the earlier-returned chained promise.\n\nTo be honest, though, sequences of delays with no message passing isn't a terribly useful example of Promise flow control. Let's look at a scenario that's a little more practical.\n\nInstead of timers, let's consider making Ajax requests:\n\n```js\n// assume an `ajax( {url}, {callback} )` utility\n\n// Promise-aware ajax\nfunction request(url) {\n\treturn new Promise( function(resolve,reject){\n\t\t// the `ajax(..)` callback should be our\n\t\t// promise's `resolve(..)` function\n\t\tajax( url, resolve );\n\t} );\n}\n```\n\nWe first define a `request(..)` utility that constructs a promise to represent the completion of the `ajax(..)` call:\n\n```js\nrequest( \"http://some.url.1/\" )\n.then( function(response1){\n\treturn request( \"http://some.url.2/?v=\" + response1 );\n} )\n.then( function(response2){\n\tconsole.log( response2 );\n} );\n```\n\n**Note:** Developers commonly encounter situations in which they want to do Promise-aware async flow control with utilities that are not themselves Promise-enabled (like `ajax(..)` here, which expects a callback). Although the native ES6 `Promise` mechanism doesn't automatically solve this pattern for us, practically all Promise libraries *do*. They usually call this process \"lifting\" or \"promisifying\" or some variation thereof. We'll come back to this technique later.\n\nUsing the Promise-returning `request(..)`, we create the first step in our chain implicitly by calling it with the first URL, and chain off that returned promise with the first `then(..)`.\n\nOnce `response1` comes back, we use that value to construct a second URL, and make a second `request(..)` call. That second `request(..)` promise is `return`ed so that the third step in our async flow control waits for that Ajax call to complete. Finally, we print `response2` once it returns.\n\nThe Promise chain we construct is not only a flow control that expresses a multistep async sequence, but it also acts as a message channel to propagate messages from step to step.\n\nWhat if something went wrong in one of the steps of the Promise chain? An error/exception is on a per-Promise basis, which means it's possible to catch such an error at any point in the chain, and that catching acts to sort of \"reset\" the chain back to normal operation at that point:\n\n```js\n// step 1:\nrequest( \"http://some.url.1/\" )\n\n// step 2:\n.then( function(response1){\n\tfoo.bar(); // undefined, error!\n\n\t// never gets here\n\treturn request( \"http://some.url.2/?v=\" + response1 );\n} )\n\n// step 3:\n.then(\n\tfunction fulfilled(response2){\n\t\t// never gets here\n\t},\n\t// rejection handler to catch the error\n\tfunction rejected(err){\n\t\tconsole.log( err );\t// `TypeError` from `foo.bar()` error\n\t\treturn 42;\n\t}\n)\n\n// step 4:\n.then( function(msg){\n\tconsole.log( msg );\t\t// 42\n} );\n```\n\nWhen the error occurs in step 2, the rejection handler in step 3 catches it. The return value (`42` in this snippet), if any, from that rejection handler fulfills the promise for the next step (4), such that the chain is now back in a fulfillment state.\n\n**Note:** As we discussed earlier, when returning a promise from a fulfillment handler, it's unwrapped and can delay the next step. That's also true for returning promises from rejection handlers, such that if the `return 42` in step 3 instead returned a promise, that promise could delay step 4. A thrown exception inside either the fulfillment or rejection handler of a `then(..)` call causes the next (chained) promise to be immediately rejected with that exception.\n\nIf you call `then(..)` on a promise, and you only pass a fulfillment handler to it, an assumed rejection handler is substituted:\n\n```js\nvar p = new Promise( function(resolve,reject){\n\treject( \"Oops\" );\n} );\n\nvar p2 = p.then(\n\tfunction fulfilled(){\n\t\t// never gets here\n\t}\n\t// assumed rejection handler, if omitted or\n\t// any other non-function value passed\n\t// function(err) {\n\t// throw err;\n\t// }\n);\n```\n\nAs you can see, the assumed rejection handler simply rethrows the error, which ends up forcing `p2` (the chained promise) to reject with the same error reason. In essence, this allows the error to continue propagating along a Promise chain until an explicitly defined rejection handler is encountered.\n\n**Note:** We'll cover more details of error handling with Promises a little later, because there are other nuanced details to be concerned about.\n\nIf a proper valid function is not passed as the fulfillment handler parameter to `then(..)`, there's also a default handler substituted:\n\n```js\nvar p = Promise.resolve( 42 );\n\np.then(\n\t// assumed fulfillment handler, if omitted or\n\t// any other non-function value passed\n\t// function(v) {\n\t// return v;\n\t// }\n\tnull,\n\tfunction rejected(err){\n\t\t// never gets here\n\t}\n);\n```\n\nAs you can see, the default fulfillment handler simply passes whatever value it receives along to the next step (Promise).\n\n**Note:** The `then(null,function(err){ .. })` pattern -- only handling rejections (if any) but letting fulfillments pass through -- has a shortcut in the API: `catch(function(err){ .. })`. We'll cover `catch(..)` more fully in the next section.\n\nLet's review briefly the intrinsic behaviors of Promises that enable chaining flow control:\n\n* A `then(..)` call against one Promise automatically produces a new Promise to return from the call.\n* Inside the fulfillment/rejection handlers, if you return a value or an exception is thrown, the new returned (chainable) Promise is resolved accordingly.\n* If the fulfillment or rejection handler returns a Promise, it is unwrapped, so that whatever its resolution is will become the resolution of the chained Promise returned from the current `then(..)`.\n\nWhile chaining flow control is helpful, it's probably most accurate to think of it as a side benefit of how Promises compose (combine) together, rather than the main intent. As we've discussed in detail several times already, Promises normalize asynchrony and encapsulate time-dependent value state, and *that* is what lets us chain them together in this useful way.\n\nCertainly, the sequential expressiveness of the chain (this-then-this-then-this...) is a big improvement over the tangled mess of callbacks as we identified in Chapter 2. But there's still a fair amount of boilerplate (`then(..)` and `function(){ .. }`) to wade through. In the next chapter, we'll see a significantly nicer pattern for sequential flow control expressivity, with generators.\n\n### Terminology: Resolve, Fulfill, and Reject\n\nThere's some slight confusion around the terms \"resolve,\" \"fulfill,\" and \"reject\" that we need to clear up, before you get too much deeper into learning about Promises. Let's first consider the `Promise(..)` constructor:\n\n```js\nvar p = new Promise( function(X,Y){\n\t// X() for fulfillment\n\t// Y() for rejection\n} );\n```\n\nAs you can see, two callbacks (here labeled `X` and `Y`) are provided. The first is *usually* used to mark the Promise as fulfilled, and the second *always* marks the Promise as rejected. But what's the \"usually\" about, and what does that imply about accurately naming those parameters?\n\nUltimately, it's just your user code and the identifier names aren't interpreted by the engine to mean anything, so it doesn't *technically* matter; `foo(..)` and `bar(..)` are equally functional. But the words you use can affect not only how you are thinking about the code, but how other developers on your team will think about it. Thinking wrongly about carefully orchestrated async code is almost surely going to be worse than the spaghetti-callback alternatives.\n\nSo it actually does kind of matter what you call them.\n\nThe second parameter is easy to decide. Almost all literature uses `reject(..)` as its name, and because that's exactly (and only!) what it does, that's a very good choice for the name. I'd strongly recommend you always use `reject(..)`.\n\nBut there's a little more ambiguity around the first parameter, which in Promise literature is often labeled `resolve(..)`. That word is obviously related to \"resolution,\" which is what's used across the literature (including this book) to describe setting a final value/state to a Promise. We've already used \"resolve the Promise\" several times to mean either fulfilling or rejecting the Promise.\n\nBut if this parameter seems to be used to specifically fulfill the Promise, why shouldn't we call it `fulfill(..)` instead of `resolve(..)` to be more accurate? To answer that question, let's also take a look at two of the `Promise` API methods:\n\n```js\nvar fulfilledPr = Promise.resolve( 42 );\n\nvar rejectedPr = Promise.reject( \"Oops\" );\n```\n\n`Promise.resolve(..)` creates a Promise that's resolved to the value given to it. In this example, `42` is a normal, non-Promise, non-thenable value, so the fulfilled promise `fulfilledPr` is created for the value `42`. `Promise.reject(\"Oops\")` creates the rejected promise `rejectedPr` for the reason `\"Oops\"`.\n\nLet's now illustrate why the word \"resolve\" (such as in `Promise.resolve(..)`) is unambiguous and indeed more accurate, if used explicitly in a context that could result in either fulfillment or rejection:\n\n```js\nvar rejectedTh = {\n\tthen: function(resolved,rejected) {\n\t\trejected( \"Oops\" );\n\t}\n};\n\nvar rejectedPr = Promise.resolve( rejectedTh );\n```\n\nAs we discussed earlier in this chapter, `Promise.resolve(..)` will return a received genuine Promise directly, or unwrap a received thenable. If that thenable unwrapping reveals a rejected state, the Promise returned from `Promise.resolve(..)` is in fact in that same rejected state.\n\nSo `Promise.resolve(..)` is a good, accurate name for the API method, because it can actually result in either fulfillment or rejection.\n\nThe first callback parameter of the `Promise(..)` constructor will unwrap either a thenable (identically to `Promise.resolve(..)`) or a genuine Promise:\n\n```js\nvar rejectedPr = new Promise( function(resolve,reject){\n\t// resolve this promise with a rejected promise\n\tresolve( Promise.reject( \"Oops\" ) );\n} );\n\nrejectedPr.then(\n\tfunction fulfilled(){\n\t\t// never gets here\n\t},\n\tfunction rejected(err){\n\t\tconsole.log( err );\t// \"Oops\"\n\t}\n);\n```\n\nIt should be clear now that `resolve(..)` is the appropriate name for the first callback parameter of the `Promise(..)` constructor.\n\n**Warning:** The previously mentioned `reject(..)` does **not** do the unwrapping that `resolve(..)` does. If you pass a Promise/thenable value to `reject(..)`, that untouched value will be set as the rejection reason. A subsequent rejection handler would receive the actual Promise/thenable you passed to `reject(..)`, not its underlying immediate value.\n\nBut now let's turn our attention to the callbacks provided to `then(..)`. What should they be called (both in literature and in code)? I would suggest `fulfilled(..)` and `rejected(..)`:\n\n```js\nfunction fulfilled(msg) {\n\tconsole.log( msg );\n}\n\nfunction rejected(err) {\n\tconsole.error( err );\n}\n\np.then(\n\tfulfilled,\n\trejected\n);\n```\n\nIn the case of the first parameter to `then(..)`, it's unambiguously always the fulfillment case, so there's no need for the duality of \"resolve\" terminology. As a side note, the ES6 specification uses `onFulfilled(..)` and `onRejected(..)` to label these two callbacks, so they are accurate terms.\n\n## Error Handling\n\nWe've already seen several examples of how Promise rejection -- either intentional through calling `reject(..)` or accidental through JS exceptions -- allows saner error handling in asynchronous programming. Let's circle back though and be explicit about some of the details that we glossed over.\n\nThe most natural form of error handling for most developers is the synchronous `try..catch` construct. Unfortunately, it's synchronous-only, so it fails to help in async code patterns:\n\n```js\nfunction foo() {\n\tsetTimeout( function(){\n\t\tbaz.bar();\n\t}, 100 );\n}\n\ntry {\n\tfoo();\n\t// later throws global error from `baz.bar()`\n}\ncatch (err) {\n\t// never gets here\n}\n```\n\n`try..catch` would certainly be nice to have, but it doesn't work across async operations. That is, unless there's some additional environmental support, which we'll come back to with generators in Chapter 4.\n\nIn callbacks, some standards have emerged for patterned error handling, most notably the \"error-first callback\" style:\n\n```js\nfunction foo(cb) {\n\tsetTimeout( function(){\n\t\ttry {\n\t\t\tvar x = baz.bar();\n\t\t\tcb( null, x ); // success!\n\t\t}\n\t\tcatch (err) {\n\t\t\tcb( err );\n\t\t}\n\t}, 100 );\n}\n\nfoo( function(err,val){\n\tif (err) {\n\t\tconsole.error( err ); // bummer :(\n\t}\n\telse {\n\t\tconsole.log( val );\n\t}\n} );\n```\n\n**Note:** The `try..catch` here works only from the perspective that the `baz.bar()` call will either succeed or fail immediately, synchronously. If `baz.bar()` was itself its own async completing function, any async errors inside it would not be catchable.\n\nThe callback we pass to `foo(..)` expects to receive a signal of an error by the reserved first parameter `err`. If present, error is assumed. If not, success is assumed.\n\nThis sort of error handling is technically *async capable*, but it doesn't compose well at all. Multiple levels of error-first callbacks woven together with these ubiquitous `if` statement checks inevitably will lead you to the perils of callback hell (see Chapter 2).\n\nSo we come back to error handling in Promises, with the rejection handler passed to `then(..)`. Promises don't use the popular \"error-first callback\" design style, but instead use \"split callbacks\" style; there's one callback for fulfillment and one for rejection:\n\n```js\nvar p = Promise.reject( \"Oops\" );\n\np.then(\n\tfunction fulfilled(){\n\t\t// never gets here\n\t},\n\tfunction rejected(err){\n\t\tconsole.log( err ); // \"Oops\"\n\t}\n);\n```\n\nWhile this pattern of error handling makes fine sense on the surface, the nuances of Promise error handling are often a fair bit more difficult to fully grasp.\n\nConsider:\n\n```js\nvar p = Promise.resolve( 42 );\n\np.then(\n\tfunction fulfilled(msg){\n\t\t// numbers don't have string functions,\n\t\t// so will throw an error\n\t\tconsole.log( msg.toLowerCase() );\n\t},\n\tfunction rejected(err){\n\t\t// never gets here\n\t}\n);\n```\n\nIf the `msg.toLowerCase()` legitimately throws an error (it does!), why doesn't our error handler get notified? As we explained earlier, it's because *that* error handler is for the `p` promise, which has already been fulfilled with value `42`. The `p` promise is immutable, so the only promise that can be notified of the error is the one returned from `p.then(..)`, which in this case we don't capture.\n\nThat should paint a clear picture of why error handling with Promises is error-prone (pun intended). It's far too easy to have errors swallowed, as this is very rarely what you'd intend.\n\n**Warning:** If you use the Promise API in an invalid way and an error occurs that prevents proper Promise construction, the result will be an immediately thrown exception, **not a rejected Promise**. Some examples of incorrect usage that fail Promise construction: `new Promise(null)`, `Promise.all()`, `Promise.race(42)`, and so on. You can't get a rejected Promise if you don't use the Promise API validly enough to actually construct a Promise in the first place!\n\n### Pit of Despair\n\nJeff Atwood noted years ago: programming languages are often set up in such a way that by default, developers fall into the \"pit of despair\" (http://blog.codinghorror.com/falling-into-the-pit-of-success/) -- where accidents are punished -- and that you have to try harder to get it right. He implored us to instead create a \"pit of success,\" where by default you fall into expected (successful) action, and thus would have to try hard to fail.\n\nPromise error handling is unquestionably \"pit of despair\" design. By default, it assumes that you want any error to be swallowed by the Promise state, and if you forget to observe that state, the error silently languishes/dies in obscurity -- usually despair.\n\nTo avoid losing an error to the silence of a forgotten/discarded Promise, some developers have claimed that a \"best practice\" for Promise chains is to always end your chain with a final `catch(..)`, like:\n\n```js\nvar p = Promise.resolve( 42 );\n\np.then(\n\tfunction fulfilled(msg){\n\t\t// numbers don't have string functions,\n\t\t// so will throw an error\n\t\tconsole.log( msg.toLowerCase() );\n\t}\n)\n.catch( handleErrors );\n```\n\nBecause we didn't pass a rejection handler to the `then(..)`, the default handler was substituted, which simply propagates the error to the next promise in the chain. As such, both errors that come into `p`, and errors that come *after* `p` in its resolution (like the `msg.toLowerCase()` one) will filter down to the final `handleErrors(..)`.\n\nProblem solved, right? Not so fast!\n\nWhat happens if `handleErrors(..)` itself also has an error in it? Who catches that? There's still yet another unattended promise: the one `catch(..)` returns, which we don't capture and don't register a rejection handler for.\n\nYou can't just stick another `catch(..)` on the end of that chain, because it too could fail. The last step in any Promise chain, whatever it is, always has the possibility, even decreasingly so, of dangling with an uncaught error stuck inside an unobserved Promise.\n\nSound like an impossible conundrum yet?\n\n### Uncaught Handling\n\nIt's not exactly an easy problem to solve completely. There are other ways to approach it which many would say are *better*.\n\nSome Promise libraries have added methods for registering something like a \"global unhandled rejection\" handler, which would be called instead of a globally thrown error. But their solution for how to identify an error as \"uncaught\" is to have an arbitrary-length timer, say 3 seconds, running from time of rejection. If a Promise is rejected but no error handler is registered before the timer fires, then it's assumed that you won't ever be registering a handler, so it's \"uncaught.\"\n\nIn practice, this has worked well for many libraries, as most usage patterns don't typically call for significant delay between Promise rejection and observation of that rejection. But this pattern is troublesome because 3 seconds is so arbitrary (even if empirical), and also because there are indeed some cases where you want a Promise to hold on to its rejectedness for some indefinite period of time, and you don't really want to have your \"uncaught\" handler called for all those false positives (not-yet-handled \"uncaught errors\").\n\nAnother more common suggestion is that Promises should have a `done(..)` added to them, which essentially marks the Promise chain as \"done.\" `done(..)` doesn't create and return a Promise, so the callbacks passed to `done(..)` are obviously not wired up to report problems to a chained Promise that doesn't exist.\n\nSo what happens instead? It's treated as you might usually expect in uncaught error conditions: any exception inside a `done(..)` rejection handler would be thrown as a global uncaught error (in the developer console, basically):\n\n```js\nvar p = Promise.resolve( 42 );\n\np.then(\n\tfunction fulfilled(msg){\n\t\t// numbers don't have string functions,\n\t\t// so will throw an error\n\t\tconsole.log( msg.toLowerCase() );\n\t}\n)\n.done( null, handleErrors );\n\n// if `handleErrors(..)` caused its own exception, it would\n// be thrown globally here\n```\n\nThis might sound more attractive than the never-ending chain or the arbitrary timeouts. But the biggest problem is that it's not part of the ES6 standard, so no matter how good it sounds, at best it's a lot longer way off from being a reliable and ubiquitous solution.\n\nAre we just stuck, then? Not entirely.\n\nBrowsers have a unique capability that our code does not have: they can track and know for sure when any object gets thrown away and garbage collected. So, browsers can track Promise objects, and whenever they get garbage collected, if they have a rejection in them, the browser knows for sure this was a legitimate \"uncaught error,\" and can thus confidently know it should report it to the developer console.\n\n**Note:** At the time of this writing, both Chrome and Firefox have early attempts at that sort of \"uncaught rejection\" capability, though support is incomplete at best.\n\nHowever, if a Promise doesn't get garbage collected -- it's exceedingly easy for that to accidentally happen through lots of different coding patterns -- the browser's garbage collection sniffing won't help you know and diagnose that you have a silently rejected Promise laying around.\n\nIs there any other alternative? Yes.\n\n### Pit of Success\n\nThe following is just theoretical, how Promises *could* be someday changed to behave. I believe it would be far superior to what we currently have. And I think this change would be possible even post-ES6 because I don't think it would break web compatibility with ES6 Promises. Moreover, it can be polyfilled/prollyfilled in, if you're careful. Let's take a look:\n\n* Promises could default to reporting (to the developer console) any rejection, on the next Job or event loop tick, if at that exact moment no error handler has been registered for the Promise.\n* For the cases where you want a rejected Promise to hold onto its rejected state for an indefinite amount of time before observing, you could call `defer()`, which suppresses automatic error reporting on that Promise.\n\nIf a Promise is rejected, it defaults to noisily reporting that fact to the developer console (instead of defaulting to silence). You can opt out of that reporting either implicitly (by registering an error handler before rejection), or explicitly (with `defer()`). In either case, *you* control the false positives.\n\nConsider:\n\n```js\nvar p = Promise.reject( \"Oops\" ).defer();\n\n// `foo(..)` is Promise-aware\nfoo( 42 )\n.then(\n\tfunction fulfilled(){\n\t\treturn p;\n\t},\n\tfunction rejected(err){\n\t\t// handle `foo(..)` error\n\t}\n);\n...\n```\n\nWhen we create `p`, we know we're going to wait a while to use/observe its rejection, so we call `defer()` -- thus no global reporting. `defer()` simply returns the same promise, for chaining purposes.\n\nThe promise returned from `foo(..)` gets an error handler attached *right away*, so it's implicitly opted out and no global reporting for it occurs either.\n\nBut the promise returned from the `then(..)` call has no `defer()` or error handler attached, so if it rejects (from inside either resolution handler), then *it* will be reported to the developer console as an uncaught error.\n\n**This design is a pit of success.** By default, all errors are either handled or reported -- what almost all developers in almost all cases would expect. You either have to register a handler or you have to intentionally opt out, and indicate you intend to defer error handling until *later*; you're opting for the extra responsibility in just that specific case.\n\nThe only real danger in this approach is if you `defer()` a Promise but then fail to actually ever observe/handle its rejection.\n\nBut you had to intentionally call `defer()` to opt into that pit of despair -- the default was the pit of success -- so there's not much else we could do to save you from your own mistakes.\n\nI think there's still hope for Promise error handling (post-ES6). I hope the powers that be will rethink the situation and consider this alternative. In the meantime, you can implement this yourself (a challenging exercise for the reader!), or use a *smarter* Promise library that does so for you!\n\n**Note:** This exact model for error handling/reporting is implemented in my *asynquence* Promise abstraction library, which will be discussed in Appendix A of this book.\n\n## Promise Patterns\n\nWe've already implicitly seen the sequence pattern with Promise chains (this-then-this-then-that flow control) but there are lots of variations on asynchronous patterns that we can build as abstractions on top of Promises. These patterns serve to simplify the expression of async flow control -- which helps make our code more reason-able and more maintainable -- even in the most complex parts of our programs.\n\nTwo such patterns are codified directly into the native ES6 `Promise` implementation, so we get them for free, to use as building blocks for other patterns.\n\n### Promise.all([ .. ])\n\nIn an async sequence (Promise chain), only one async task is being coordinated at any given moment -- step 2 strictly follows step 1, and step 3 strictly follows step 2. But what about doing two or more steps concurrently (aka \"in parallel\")?\n\nIn classic programming terminology, a \"gate\" is a mechanism that waits on two or more parallel/concurrent tasks to complete before continuing. It doesn't matter what order they finish in, just that all of them have to complete for the gate to open and let the flow control through.\n\nIn the Promise API, we call this pattern `all([ .. ])`.\n\nSay you wanted to make two Ajax requests at the same time, and wait for both to finish, regardless of their order, before making a third Ajax request. Consider:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility,\n// like we defined earlier in the chapter\n\nvar p1 = request( \"http://some.url.1/\" );\nvar p2 = request( \"http://some.url.2/\" );\n\nPromise.all( [p1,p2] )\n.then( function(msgs){\n\t// both `p1` and `p2` fulfill and pass in\n\t// their messages here\n\treturn request(\n\t\t\"http://some.url.3/?v=\" + msgs.join(\",\")\n\t);\n} )\n.then( function(msg){\n\tconsole.log( msg );\n} );\n```\n\n`Promise.all([ .. ])` expects a single argument, an `array`, consisting generally of Promise instances. The promise returned from the `Promise.all([ .. ])` call will receive a fulfillment message (`msgs` in this snippet) that is an `array` of all the fulfillment messages from the passed in promises, in the same order as specified (regardless of fulfillment order).\n\n**Note:** Technically, the `array` of values passed into `Promise.all([ .. ])` can include Promises, thenables, or even immediate values. Each value in the list is essentially passed through `Promise.resolve(..)` to make sure it's a genuine Promise to be waited on, so an immediate value will just be normalized into a Promise for that value. If the `array` is empty, the main Promise is immediately fulfilled.\n\nThe main promise returned from `Promise.all([ .. ])` will only be fulfilled if and when all its constituent promises are fulfilled. If any one of those promises instead is rejected, the main `Promise.all([ .. ])` promise is immediately rejected, discarding all results from any other promises.\n\nRemember to always attach a rejection/error handler to every promise, even and especially the one that comes back from `Promise.all([ .. ])`.\n\n### Promise.race([ .. ])\n\nWhile `Promise.all([ .. ])` coordinates multiple Promises concurrently and assumes all are needed for fulfillment, sometimes you only want to respond to the \"first Promise to cross the finish line,\" letting the other Promises fall away.\n\nThis pattern is classically called a \"latch,\" but in Promises it's called a \"race.\"\n\n**Warning:** While the metaphor of \"only the first across the finish line wins\" fits the behavior well, unfortunately \"race\" is kind of a loaded term, because \"race conditions\" are generally taken as bugs in programs (see Chapter 1). Don't confuse `Promise.race([ .. ])` with \"race condition.\"\n\n`Promise.race([ .. ])` also expects a single `array` argument, containing one or more Promises, thenables, or immediate values. It doesn't make much practical sense to have a race with immediate values, because the first one listed will obviously win -- like a foot race where one runner starts at the finish line!\n\nSimilar to `Promise.all([ .. ])`, `Promise.race([ .. ])` will fulfill if and when any Promise resolution is a fulfillment, and it will reject if and when any Promise resolution is a rejection.\n\n**Warning:** A \"race\" requires at least one \"runner,\" so if you pass an empty `array`, instead of immediately resolving, the main `race([..])` Promise will never resolve. This is a footgun! ES6 should have specified that it either fulfills, rejects, or just throws some sort of synchronous error. Unfortunately, because of precedence in Promise libraries predating ES6 `Promise`, they had to leave this gotcha in there, so be careful never to send in an empty `array`.\n\nLet's revisit our previous concurrent Ajax example, but in the context of a race between `p1` and `p2`:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility,\n// like we defined earlier in the chapter\n\nvar p1 = request( \"http://some.url.1/\" );\nvar p2 = request( \"http://some.url.2/\" );\n\nPromise.race( [p1,p2] )\n.then( function(msg){\n\t// either `p1` or `p2` will win the race\n\treturn request(\n\t\t\"http://some.url.3/?v=\" + msg\n\t);\n} )\n.then( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nBecause only one promise wins, the fulfillment value is a single message, not an `array` as it was for `Promise.all([ .. ])`.\n\n#### Timeout Race\n\nWe saw this example earlier, illustrating how `Promise.race([ .. ])` can be used to express the \"promise timeout\" pattern:\n\n```js\n// `foo()` is a Promise-aware function\n\n// `timeoutPromise(..)`, defined ealier, returns\n// a Promise that rejects after a specified delay\n\n// setup a timeout for `foo()`\nPromise.race( [\n\tfoo(),\t\t\t\t\t// attempt `foo()`\n\ttimeoutPromise( 3000 )\t// give it 3 seconds\n] )\n.then(\n\tfunction(){\n\t\t// `foo(..)` fulfilled in time!\n\t},\n\tfunction(err){\n\t\t// either `foo()` rejected, or it just\n\t\t// didn't finish in time, so inspect\n\t\t// `err` to know which\n\t}\n);\n```\n\nThis timeout pattern works well in most cases. But there are some nuances to consider, and frankly they apply to both `Promise.race([ .. ])` and `Promise.all([ .. ])` equally.\n\n#### \"Finally\"\n\nThe key question to ask is, \"What happens to the promises that get discarded/ignored?\" We're not asking that question from the performance perspective -- they would typically end up garbage collection eligible -- but from the behavioral perspective (side effects, etc.). Promises cannot be canceled -- and shouldn't be as that would destroy the external immutability trust discussed in the \"Promise Uncancelable\" section later in this chapter -- so they can only be silently ignored.\n\nBut what if `foo()` in the previous example is reserving some sort of resource for usage, but the timeout fires first and causes that promise to be ignored? Is there anything in this pattern that proactively frees the reserved resource after the timeout, or otherwise cancels any side effects it may have had? What if all you wanted was to log the fact that `foo()` timed out?\n\nSome developers have proposed that Promises need a `finally(..)` callback registration, which is always called when a Promise resolves, and allows you to specify any cleanup that may be necessary. This doesn't exist in the specification at the moment, but it may come in ES7+. We'll have to wait and see.\n\nIt might look like:\n\n```js\nvar p = Promise.resolve( 42 );\n\np.then( something )\n.finally( cleanup )\n.then( another )\n.finally( cleanup );\n```\n\n**Note:** In various Promise libraries, `finally(..)` still creates and returns a new Promise (to keep the chain going). If the `cleanup(..)` function were to return a Promise, it would be linked into the chain, which means you could still have the unhandled rejection issues we discussed earlier.\n\nIn the meantime, we could make a static helper utility that lets us observe (without interfering) the resolution of a Promise:\n\n```js\n// polyfill-safe guard check\nif (!Promise.observe) {\n\tPromise.observe = function(pr,cb) {\n\t\t// side-observe `pr`'s resolution\n\t\tpr.then(\n\t\t\tfunction fulfilled(msg){\n\t\t\t\t// schedule callback async (as Job)\n\t\t\t\tPromise.resolve( msg ).then( cb );\n\t\t\t},\n\t\t\tfunction rejected(err){\n\t\t\t\t// schedule callback async (as Job)\n\t\t\t\tPromise.resolve( err ).then( cb );\n\t\t\t}\n\t\t);\n\n\t\t// return original promise\n\t\treturn pr;\n\t};\n}\n```\n\nHere's how we'd use it in the timeout example from before:\n\n```js\nPromise.race( [\n\tPromise.observe(\n\t\tfoo(),\t\t\t\t\t// attempt `foo()`\n\t\tfunction cleanup(msg){\n\t\t\t// clean up after `foo()`, even if it\n\t\t\t// didn't finish before the timeout\n\t\t}\n\t),\n\ttimeoutPromise( 3000 )\t// give it 3 seconds\n] )\n```\n\nThis `Promise.observe(..)` helper is just an illustration of how you could observe the completions of Promises without interfering with them. Other Promise libraries have their own solutions. Regardless of how you do it, you'll likely have places where you want to make sure your Promises aren't *just* silently ignored by accident.\n\n### Variations on all([ .. ]) and race([ .. ])\n\nWhile native ES6 Promises come with built-in `Promise.all([ .. ])` and `Promise.race([ .. ])`, there are several other commonly used patterns with variations on those semantics:\n\n* `none([ .. ])` is like `all([ .. ])`, but fulfillments and rejections are transposed. All Promises need to be rejected -- rejections become the fulfillment values and vice versa.\n* `any([ .. ])` is like `all([ .. ])`, but it ignores any rejections, so only one needs to fulfill instead of *all* of them.\n* `first([ .. ])` is like a race with `any([ .. ])`, which is that it ignores any rejections and fulfills as soon as the first Promise fulfills.\n* `last([ .. ])` is like `first([ .. ])`, but only the latest fulfillment wins.\n\nSome Promise abstraction libraries provide these, but you could also define them yourself using the mechanics of Promises, `race([ .. ])` and `all([ .. ])`.\n\nFor example, here's how we could define `first([ .. ])`:\n\n```js\n// polyfill-safe guard check\nif (!Promise.first) {\n\tPromise.first = function(prs) {\n\t\treturn new Promise( function(resolve,reject){\n\t\t\t// loop through all promises\n\t\t\tprs.forEach( function(pr){\n\t\t\t\t// normalize the value\n\t\t\t\tPromise.resolve( pr )\n\t\t\t\t// whichever one fulfills first wins, and\n\t\t\t\t// gets to resolve the main promise\n\t\t\t\t.then( resolve );\n\t\t\t} );\n\t\t} );\n\t};\n}\n```\n\n**Note:** This implementation of `first(..)` does not reject if all its promises reject; it simply hangs, much like a `Promise.race([])` does. If desired, you could add additional logic to track each promise rejection and if all reject, call `reject()` on the main promise. We'll leave that as an exercise for the reader.\n\n### Concurrent Iterations\n\nSometimes you want to iterate over a list of Promises and perform some task against all of them, much like you can do with synchronous `array`s (e.g., `forEach(..)`, `map(..)`, `some(..)`, and `every(..)`). If the task to perform against each Promise is fundamentally synchronous, these work fine, just as we used `forEach(..)` in the previous snippet.\n\nBut if the tasks are fundamentally asynchronous, or can/should otherwise be performed concurrently, you can use async versions of these utilities as provided by many libraries.\n\nFor example, let's consider an asynchronous `map(..)` utility that takes an `array` of values (could be Promises or anything else), plus a function (task) to perform against each. `map(..)` itself returns a promise whose fulfillment value is an `array` that holds (in the same mapping order) the async fulfillment value from each task:\n\n```js\nif (!Promise.map) {\n\tPromise.map = function(vals,cb) {\n\t\t// new promise that waits for all mapped promises\n\t\treturn Promise.all(\n\t\t\t// note: regular array `map(..)`, turns\n\t\t\t// the array of values into an array of\n\t\t\t// promises\n\t\t\tvals.map( function(val){\n\t\t\t\t// replace `val` with a new promise that\n\t\t\t\t// resolves after `val` is async mapped\n\t\t\t\treturn new Promise( function(resolve){\n\t\t\t\t\tcb( val, resolve );\n\t\t\t\t} );\n\t\t\t} )\n\t\t);\n\t};\n}\n```\n\n**Note:** In this implementation of `map(..)`, you can't signal async rejection, but if a synchronous exception/error occurs inside of the mapping callback (`cb(..)`), the main `Promise.map(..)` returned promise would reject.\n\nLet's illustrate using `map(..)` with a list of Promises (instead of simple values):\n\n```js\nvar p1 = Promise.resolve( 21 );\nvar p2 = Promise.resolve( 42 );\nvar p3 = Promise.reject( \"Oops\" );\n\n// double values in list even if they're in\n// Promises\nPromise.map( [p1,p2,p3], function(pr,done){\n\t// make sure the item itself is a Promise\n\tPromise.resolve( pr )\n\t.then(\n\t\t// extract value as `v`\n\t\tfunction(v){\n\t\t\t// map fulfillment `v` to new value\n\t\t\tdone( v * 2 );\n\t\t},\n\t\t// or, map to promise rejection message\n\t\tdone\n\t);\n} )\n.then( function(vals){\n\tconsole.log( vals );\t// [42,84,\"Oops\"]\n} );\n```\n\n## Promise API Recap\n\nLet's review the ES6 `Promise` API that we've already seen unfold in bits and pieces throughout this chapter.\n\n**Note:** The following API is native only as of ES6, but there are specification-compliant polyfills (not just extended Promise libraries) which can define `Promise` and all its associated behavior so that you can use native Promises even in pre-ES6 browsers. One such polyfill is \"Native Promise Only\" (http://github.com/getify/native-promise-only), which I wrote!\n\n### new Promise(..) Constructor\n\nThe *revealing constructor* `Promise(..)` must be used with `new`, and must be provided a function callback that is synchronously/immediately called. This function is passed two function callbacks that act as resolution capabilities for the promise. We commonly label these `resolve(..)` and `reject(..)`:\n\n```js\nvar p = new Promise( function(resolve,reject){\n\t// `resolve(..)` to resolve/fulfill the promise\n\t// `reject(..)` to reject the promise\n} );\n```\n\n`reject(..)` simply rejects the promise, but `resolve(..)` can either fulfill the promise or reject it, depending on what it's passed. If `resolve(..)` is passed an immediate, non-Promise, non-thenable value, then the promise is fulfilled with that value.\n\nBut if `resolve(..)` is passed a genuine Promise or thenable value, that value is unwrapped recursively, and whatever its final resolution/state is will be adopted by the promise.\n\n### Promise.resolve(..) and Promise.reject(..)\n\nA shortcut for creating an already-rejected Promise is `Promise.reject(..)`, so these two promises are equivalent:\n\n```js\nvar p1 = new Promise( function(resolve,reject){\n\treject( \"Oops\" );\n} );\n\nvar p2 = Promise.reject( \"Oops\" );\n```\n\n`Promise.resolve(..)` is usually used to create an already-fulfilled Promise in a similar way to `Promise.reject(..)`. However, `Promise.resolve(..)` also unwraps thenable values (as discussed several times already). In that case, the Promise returned adopts the final resolution of the thenable you passed in, which could either be fulfillment or rejection:\n\n```js\nvar fulfilledTh = {\n\tthen: function(cb) { cb( 42 ); }\n};\nvar rejectedTh = {\n\tthen: function(cb,errCb) {\n\t\terrCb( \"Oops\" );\n\t}\n};\n\nvar p1 = Promise.resolve( fulfilledTh );\nvar p2 = Promise.resolve( rejectedTh );\n\n// `p1` will be a fulfilled promise\n// `p2` will be a rejected promise\n```\n\nAnd remember, `Promise.resolve(..)` doesn't do anything if what you pass is already a genuine Promise; it just returns the value directly. So there's no overhead to calling `Promise.resolve(..)` on values that you don't know the nature of, if one happens to already be a genuine Promise.\n\n### then(..) and catch(..)\n\nEach Promise instance (**not** the `Promise` API namespace) has `then(..)` and `catch(..)` methods, which allow registering of fulfillment and rejection handlers for the Promise. Once the Promise is resolved, one or the other of these handlers will be called, but not both, and it will always be called asynchronously (see \"Jobs\" in Chapter 1).\n\n`then(..)` takes one or two parameters, the first for the fulfillment callback, and the second for the rejection callback. If either is omitted or is otherwise passed as a non-function value, a default callback is substituted respectively. The default fulfillment callback simply passes the message along, while the default rejection callback simply rethrows (propagates) the error reason it receives.\n\n`catch(..)` takes only the rejection callback as a parameter, and automatically substitutes the default fulfillment callback, as just discussed. In other words, it's equivalent to `then(null,..)`:\n\n```js\np.then( fulfilled );\n\np.then( fulfilled, rejected );\n\np.catch( rejected ); // or `p.then( null, rejected )`\n```\n\n`then(..)` and `catch(..)` also create and return a new promise, which can be used to express Promise chain flow control. If the fulfillment or rejection callbacks have an exception thrown, the returned promise is rejected. If either callback returns an immediate, non-Promise, non-thenable value, that value is set as the fulfillment for the returned promise. If the fulfillment handler specifically returns a promise or thenable value, that value is unwrapped and becomes the resolution of the returned promise.\n\n### Promise.all([ .. ]) and Promise.race([ .. ])\n\nThe static helpers `Promise.all([ .. ])` and `Promise.race([ .. ])` on the ES6 `Promise` API both create a Promise as their return value. The resolution of that promise is controlled entirely by the array of promises that you pass in.\n\nFor `Promise.all([ .. ])`, all the promises you pass in must fulfill for the returned promise to fulfill. If any promise is rejected, the main returned promise is immediately rejected, too (discarding the results of any of the other promises). For fulfillment, you receive an `array` of all the passed in promises' fulfillment values. For rejection, you receive just the first promise rejection reason value. This pattern is classically called a \"gate\": all must arrive before the gate opens.\n\nFor `Promise.race([ .. ])`, only the first promise to resolve (fulfillment or rejection) \"wins,\" and whatever that resolution is becomes the resolution of the returned promise. This pattern is classically called a \"latch\": first one to open the latch gets through. Consider:\n\n```js\nvar p1 = Promise.resolve( 42 );\nvar p2 = Promise.resolve( \"Hello World\" );\nvar p3 = Promise.reject( \"Oops\" );\n\nPromise.race( [p1,p2,p3] )\n.then( function(msg){\n\tconsole.log( msg );\t\t// 42\n} );\n\nPromise.all( [p1,p2,p3] )\n.catch( function(err){\n\tconsole.error( err );\t// \"Oops\"\n} );\n\nPromise.all( [p1,p2] )\n.then( function(msgs){\n\tconsole.log( msgs );\t// [42,\"Hello World\"]\n} );\n```\n\n**Warning:** Be careful! If an empty `array` is passed to `Promise.all([ .. ])`, it will fulfill immediately, but `Promise.race([ .. ])` will hang forever and never resolve.\n\nThe ES6 `Promise` API is pretty simple and straightforward. It's at least good enough to serve the most basic of async cases, and is a good place to start when rearranging your code from callback hell to something better.\n\nBut there's a whole lot of async sophistication that apps often demand which Promises themselves will be limited in addressing. In the next section, we'll dive into those limitations as motivations for the benefit of Promise libraries.\n\n## Promise Limitations\n\nMany of the details we'll discuss in this section have already been alluded to in this chapter, but we'll just make sure to review these limitations specifically.\n\n### Sequence Error Handling\n\nWe covered Promise-flavored error handling in detail earlier in this chapter. The limitations of how Promises are designed -- how they chain, specifically -- creates a very easy pitfall where an error in a Promise chain can be silently ignored accidentally.\n\nBut there's something else to consider with Promise errors. Because a Promise chain is nothing more than its constituent Promises wired together, there's no entity to refer to the entire chain as a single *thing*, which means there's no external way to observe any errors that may occur.\n\nIf you construct a Promise chain that has no error handling in it, any error anywhere in the chain will propagate indefinitely down the chain, until observed (by registering a rejection handler at some step). So, in that specific case, having a reference to the *last* promise in the chain is enough (`p` in the following snippet), because you can register a rejection handler there, and it will be notified of any propagated errors:\n\n```js\n// `foo(..)`, `STEP2(..)` and `STEP3(..)` are\n// all promise-aware utilities\n\nvar p = foo( 42 )\n.then( STEP2 )\n.then( STEP3 );\n```\n\nAlthough it may seem sneakily confusing, `p` here doesn't point to the first promise in the chain (the one from the `foo(42)` call), but instead from the last promise, the one that comes from the `then(STEP3)` call.\n\nAlso, no step in the promise chain is observably doing its own error handling. That means that you could then register a rejection error handler on `p`, and it would be notified if any errors occur anywhere in the chain:\n\n```\np.catch( handleErrors );\n```\n\nBut if any step of the chain in fact does its own error handling (perhaps hidden/abstracted away from what you can see), your `handleErrors(..)` won't be notified. This may be what you want -- it was, after all, a \"handled rejection\" -- but it also may *not* be what you want. The complete lack of ability to be notified (of \"already handled\" rejection errors) is a limitation that restricts capabilities in some use cases.\n\nIt's basically the same limitation that exists with a `try..catch` that can catch an exception and simply swallow it. So this isn't a limitation **unique to Promises**, but it *is* something we might wish to have a workaround for.\n\nUnfortunately, many times there is no reference kept for the intermediate steps in a Promise-chain sequence, so without such references, you cannot attach error handlers to reliably observe the errors.\n\n### Single Value\n\nPromises by definition only have a single fulfillment value or a single rejection reason. In simple examples, this isn't that big of a deal, but in more sophisticated scenarios, you may find this limiting.\n\nThe typical advice is to construct a values wrapper (such as an `object` or `array`) to contain these multiple messages. This solution works, but it can be quite awkward and tedious to wrap and unwrap your messages with every single step of your Promise chain.\n\n#### Splitting Values\n\nSometimes you can take this as a signal that you could/should decompose the problem into two or more Promises.\n\nImagine you have a utility `foo(..)` that produces two values (`x` and `y`) asynchronously:\n\n```js\nfunction getY(x) {\n\treturn new Promise( function(resolve,reject){\n\t\tsetTimeout( function(){\n\t\t\tresolve( (3 * x) - 1 );\n\t\t}, 100 );\n\t} );\n}\n\nfunction foo(bar,baz) {\n\tvar x = bar * baz;\n\n\treturn getY( x )\n\t.then( function(y){\n\t\t// wrap both values into container\n\t\treturn [x,y];\n\t} );\n}\n\nfoo( 10, 20 )\n.then( function(msgs){\n\tvar x = msgs[0];\n\tvar y = msgs[1];\n\n\tconsole.log( x, y );\t// 200 599\n} );\n```\n\nFirst, let's rearrange what `foo(..)` returns so that we don't have to wrap `x` and `y` into a single `array` value to transport through one Promise. Instead, we can wrap each value into its own promise:\n\n```js\nfunction foo(bar,baz) {\n\tvar x = bar * baz;\n\n\t// return both promises\n\treturn [\n\t\tPromise.resolve( x ),\n\t\tgetY( x )\n\t];\n}\n\nPromise.all(\n\tfoo( 10, 20 )\n)\n.then( function(msgs){\n\tvar x = msgs[0];\n\tvar y = msgs[1];\n\n\tconsole.log( x, y );\n} );\n```\n\nIs an `array` of promises really better than an `array` of values passed through a single promise? Syntactically, it's not much of an improvement.\n\nBut this approach more closely embraces the Promise design theory. It's now easier in the future to refactor to split the calculation of `x` and `y` into separate functions. It's cleaner and more flexible to let the calling code decide how to orchestrate the two promises -- using `Promise.all([ .. ])` here, but certainly not the only option -- rather than to abstract such details away inside of `foo(..)`.\n\n#### Unwrap/Spread Arguments\n\nThe `var x = ..` and `var y = ..` assignments are still awkward overhead. We can employ some functional trickery (hat tip to Reginald Braithwaite, @raganwald on Twitter) in a helper utility:\n\n```js\nfunction spread(fn) {\n\treturn Function.apply.bind( fn, null );\n}\n\nPromise.all(\n\tfoo( 10, 20 )\n)\n.then(\n\tspread( function(x,y){\n\t\tconsole.log( x, y );\t// 200 599\n\t} )\n)\n```\n\nThat's a bit nicer! Of course, you could inline the functional magic to avoid the extra helper:\n\n```js\nPromise.all(\n\tfoo( 10, 20 )\n)\n.then( Function.apply.bind(\n\tfunction(x,y){\n\t\tconsole.log( x, y );\t// 200 599\n\t},\n\tnull\n) );\n```\n\nThese tricks may be neat, but ES6 has an even better answer for us: destructuring. The array destructuring assignment form looks like this:\n\n```js\nPromise.all(\n\tfoo( 10, 20 )\n)\n.then( function(msgs){\n\tvar [x,y] = msgs;\n\n\tconsole.log( x, y );\t// 200 599\n} );\n```\n\nBut best of all, ES6 offers the array parameter destructuring form:\n\n```js\nPromise.all(\n\tfoo( 10, 20 )\n)\n.then( function([x,y]){\n\tconsole.log( x, y );\t// 200 599\n} );\n```\n\nWe've now embraced the one-value-per-Promise mantra, but kept our supporting boilerplate to a minimum!\n\n**Note:** For more information on ES6 destructuring forms, see the *ES6 & Beyond* title of this series.\n\n### Single Resolution\n\nOne of the most intrinsic behaviors of Promises is that a Promise can only be resolved once (fulfillment or rejection). For many async use cases, you're only retrieving a value once, so this works fine.\n\nBut there's also a lot of async cases that fit into a different model -- one that's more akin to events and/or streams of data. It's not clear on the surface how well Promises can fit into such use cases, if at all. Without a significant abstraction on top of Promises, they will completely fall short for handling multiple value resolution.\n\nImagine a scenario where you might want to fire off a sequence of async steps in response to a stimulus (like an event) that can in fact happen multiple times, like a button click.\n\nThis probably won't work the way you want:\n\n```js\n// `click(..)` binds the `\"click\"` event to a DOM element\n// `request(..)` is the previously defined Promise-aware Ajax\n\nvar p = new Promise( function(resolve,reject){\n\tclick( \"#mybtn\", resolve );\n} );\n\np.then( function(evt){\n\tvar btnID = evt.currentTarget.id;\n\treturn request( \"http://some.url.1/?id=\" + btnID );\n} )\n.then( function(text){\n\tconsole.log( text );\n} );\n```\n\nThe behavior here only works if your application calls for the button to be clicked just once. If the button is clicked a second time, the `p` promise has already been resolved, so the second `resolve(..)` call would be ignored.\n\nInstead, you'd probably need to invert the paradigm, creating a whole new Promise chain for each event firing:\n\n```js\nclick( \"#mybtn\", function(evt){\n\tvar btnID = evt.currentTarget.id;\n\n\trequest( \"http://some.url.1/?id=\" + btnID )\n\t.then( function(text){\n\t\tconsole.log( text );\n\t} );\n} );\n```\n\nThis approach will *work* in that a whole new Promise sequence will be fired off for each `\"click\"` event on the button.\n\nBut beyond just the ugliness of having to define the entire Promise chain inside the event handler, this design in some respects violates the idea of separation of concerns/capabilities (SoC). You might very well want to define your event handler in a different place in your code from where you define the *response* to the event (the Promise chain). That's pretty awkward to do in this pattern, without helper mechanisms.\n\n**Note:** Another way of articulating this limitation is that it'd be nice if we could construct some sort of \"observable\" that we can subscribe a Promise chain to. There are libraries that have created these abstractions (such as RxJS -- http://rxjs.codeplex.com/), but the abstractions can seem so heavy that you can't even see the nature of Promises anymore. Such heavy abstraction brings important questions to mind such as whether (sans Promises) these mechanisms are as *trustable* as Promises themselves have been designed to be. We'll revisit the \"Observable\" pattern in Appendix B.\n\n### Inertia\n\nOne concrete barrier to starting to use Promises in your own code is all the code that currently exists which is not already Promise-aware. If you have lots of callback-based code, it's far easier to just keep coding in that same style.\n\n\"A code base in motion (with callbacks) will remain in motion (with callbacks) unless acted upon by a smart, Promises-aware developer.\"\n\nPromises offer a different paradigm, and as such, the approach to the code can be anywhere from just a little different to, in some cases, radically different. You have to be intentional about it, because Promises will not just naturally shake out from the same ol' ways of doing code that have served you well thus far.\n\nConsider a callback-based scenario like the following:\n\n```js\nfunction foo(x,y,cb) {\n\tajax(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y,\n\t\tcb\n\t);\n}\n\nfoo( 11, 31, function(err,text) {\n\tif (err) {\n\t\tconsole.error( err );\n\t}\n\telse {\n\t\tconsole.log( text );\n\t}\n} );\n```\n\nIs it immediately obvious what the first steps are to convert this callback-based code to Promise-aware code? Depends on your experience. The more practice you have with it, the more natural it will feel. But certainly, Promises don't just advertise on the label exactly how to do it -- there's no one-size-fits-all answer -- so the responsibility is up to you.\n\nAs we've covered before, we definitely need an Ajax utility that is Promise-aware instead of callback-based, which we could call `request(..)`. You can make your own, as we have already. But the overhead of having to manually define Promise-aware wrappers for every callback-based utility makes it less likely you'll choose to refactor to Promise-aware coding at all.\n\nPromises offer no direct answer to that limitation. Most Promise libraries do offer a helper, however. But even without a library, imagine a helper like this:\n\n```js\n// polyfill-safe guard check\nif (!Promise.wrap) {\n\tPromise.wrap = function(fn) {\n\t\treturn function() {\n\t\t\tvar args = [].slice.call( arguments );\n\n\t\t\treturn new Promise( function(resolve,reject){\n\t\t\t\tfn.apply(\n\t\t\t\t\tnull,\n\t\t\t\t\targs.concat( function(err,v){\n\t\t\t\t\t\tif (err) {\n\t\t\t\t\t\t\treject( err );\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse {\n\t\t\t\t\t\t\tresolve( v );\n\t\t\t\t\t\t}\n\t\t\t\t\t} )\n\t\t\t\t);\n\t\t\t} );\n\t\t};\n\t};\n}\n```\n\nOK, that's more than just a tiny trivial utility. However, although it may look a bit intimidating, it's not as bad as you'd think. It takes a function that expects an error-first style callback as its last parameter, and returns a new one that automatically creates a Promise to return, and substitutes the callback for you, wired up to the Promise fulfillment/rejection.\n\nRather than waste too much time talking about *how* this `Promise.wrap(..)` helper works, let's just look at how we use it:\n\n```js\nvar request = Promise.wrap( ajax );\n\nrequest( \"http://some.url.1/\" )\n.then( .. )\n..\n```\n\nWow, that was pretty easy!\n\n`Promise.wrap(..)` does **not** produce a Promise. It produces a function that will produce Promises. In a sense, a Promise-producing function could be seen as a \"Promise factory.\" I propose \"promisory\" as the name for such a thing (\"Promise\" + \"factory\").\n\nThe act of wrapping a callback-expecting function to be a Promise-aware function is sometimes referred to as \"lifting\" or \"promisifying\". But there doesn't seem to be a standard term for what to call the resultant function other than a \"lifted function\", so I like \"promisory\" better as I think it's more descriptive.\n\n**Note:** Promisory isn't a made-up term. It's a real word, and its definition means to contain or convey a promise. That's exactly what these functions are doing, so it turns out to be a pretty perfect terminology match!\n\nSo, `Promise.wrap(ajax)` produces an `ajax(..)` promisory we call `request(..)`, and that promisory produces Promises for Ajax responses.\n\nIf all functions were already promisories, we wouldn't need to make them ourselves, so the extra step is a tad bit of a shame. But at least the wrapping pattern is (usually) repeatable so we can put it into a `Promise.wrap(..)` helper as shown to aid our promise coding.\n\nSo back to our earlier example, we need a promisory for both `ajax(..)` and `foo(..)`:\n\n```js\n// make a promisory for `ajax(..)`\nvar request = Promise.wrap( ajax );\n\n// refactor `foo(..)`, but keep it externally\n// callback-based for compatibility with other\n// parts of the code for now -- only use\n// `request(..)`'s promise internally.\nfunction foo(x,y,cb) {\n\trequest(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y\n\t)\n\t.then(\n\t\tfunction fulfilled(text){\n\t\t\tcb( null, text );\n\t\t},\n\t\tcb\n\t);\n}\n\n// now, for this code's purposes, make a\n// promisory for `foo(..)`\nvar betterFoo = Promise.wrap( foo );\n\n// and use the promisory\nbetterFoo( 11, 31 )\n.then(\n\tfunction fulfilled(text){\n\t\tconsole.log( text );\n\t},\n\tfunction rejected(err){\n\t\tconsole.error( err );\n\t}\n);\n```\n\nOf course, while we're refactoring `foo(..)` to use our new `request(..)` promisory, we could just make `foo(..)` a promisory itself, instead of remaining callback-based and needing to make and use the subsequent `betterFoo(..)` promisory. This decision just depends on whether `foo(..)` needs to stay callback-based compatible with other parts of the code base or not.\n\nConsider:\n\n```js\n// `foo(..)` is now also a promisory because it\n// delegates to the `request(..)` promisory\nfunction foo(x,y) {\n\treturn request(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y\n\t);\n}\n\nfoo( 11, 31 )\n.then( .. )\n..\n```\n\nWhile ES6 Promises don't natively ship with helpers for such promisory wrapping, most libraries provide them, or you can make your own. Either way, this particular limitation of Promises is addressable without too much pain (certainly compared to the pain of callback hell!).\n\n### Promise Uncancelable\n\nOnce you create a Promise and register a fulfillment and/or rejection handler for it, there's nothing external you can do to stop that progression if something else happens to make that task moot.\n\n**Note:** Many Promise abstraction libraries provide facilities to cancel Promises, but this is a terrible idea! Many developers wish Promises had natively been designed with external cancelation capability, but the problem is that it would let one consumer/observer of a Promise affect some other consumer's ability to observe that same Promise. This violates the future-value's trustability (external immutability), but moreover is the embodiment of the \"action at a distance\" anti-pattern (http://en.wikipedia.org/wiki/Action_at_a_distance_%28computer_programming%29). Regardless of how useful it seems, it will actually lead you straight back into the same nightmares as callbacks.\n\nConsider our Promise timeout scenario from earlier:\n\n```js\nvar p = foo( 42 );\n\nPromise.race( [\n\tp,\n\ttimeoutPromise( 3000 )\n] )\n.then(\n\tdoSomething,\n\thandleError\n);\n\np.then( function(){\n\t// still happens even in the timeout case :(\n} );\n```\n\nThe \"timeout\" was external to the promise `p`, so `p` itself keeps going, which we probably don't want.\n\nOne option is to invasively define your resolution callbacks:\n\n```js\nvar OK = true;\n\nvar p = foo( 42 );\n\nPromise.race( [\n\tp,\n\ttimeoutPromise( 3000 )\n\t.catch( function(err){\n\t\tOK = false;\n\t\tthrow err;\n\t} )\n] )\n.then(\n\tdoSomething,\n\thandleError\n);\n\np.then( function(){\n\tif (OK) {\n\t\t// only happens if no timeout! :)\n\t}\n} );\n```\n\nThis is ugly. It works, but it's far from ideal. Generally, you should try to avoid such scenarios.\n\nBut if you can't, the ugliness of this solution should be a clue that *cancelation* is a functionality that belongs at a higher level of abstraction on top of Promises. I'd recommend you look to Promise abstraction libraries for assistance rather than hacking it yourself.\n\n**Note:** My *asynquence* Promise abstraction library provides just such an abstraction and an `abort()` capability for the sequence, all of which will be discussed in Appendix A.\n\nA single Promise is not really a flow-control mechanism (at least not in a very meaningful sense), which is exactly what *cancelation* refers to; that's why Promise cancelation would feel awkward.\n\nBy contrast, a chain of Promises taken collectively together -- what I like to call a \"sequence\" -- *is* a flow control expression, and thus it's appropriate for cancelation to be defined at that level of abstraction.\n\nNo individual Promise should be cancelable, but it's sensible for a *sequence* to be cancelable, because you don't pass around a sequence as a single immutable value like you do with a Promise.\n\n### Promise Performance\n\nThis particular limitation is both simple and complex.\n\nComparing how many pieces are moving with a basic callback-based async task chain versus a Promise chain, it's clear Promises have a fair bit more going on, which means they are naturally at least a tiny bit slower. Think back to just the simple list of trust guarantees that Promises offer, as compared to the ad hoc solution code you'd have to layer on top of callbacks to achieve the same protections.\n\nMore work to do, more guards to protect, means that Promises *are* slower as compared to naked, untrustable callbacks. That much is obvious, and probably simple to wrap your brain around.\n\nBut how much slower? Well... that's actually proving to be an incredibly difficult question to answer absolutely, across the board.\n\nFrankly, it's kind of an apples-to-oranges comparison, so it's probably the wrong question to ask. You should actually compare whether an ad-hoc callback system with all the same protections manually layered in is faster than a Promise implementation.\n\nIf Promises have a legitimate performance limitation, it's more that they don't really offer a line-item choice as to which trustability protections you want/need or not -- you get them all, always.\n\nNevertheless, if we grant that a Promise is generally a *little bit slower* than its non-Promise, non-trustable callback equivalent -- assuming there are places where you feel you can justify the lack of trustability -- does that mean that Promises should be avoided across the board, as if your entire application is driven by nothing but must-be-utterly-the-fastest code possible?\n\nSanity check: if your code is legitimately like that, **is JavaScript even the right language for such tasks?** JavaScript can be optimized to run applications very performantly (see Chapter 5 and Chapter 6). But is obsessing over tiny performance tradeoffs with Promises, in light of all the benefits they offer, *really* appropriate?\n\nAnother subtle issue is that Promises make *everything* async, which means that some immediately (synchronously) complete steps still defer advancement of the next step to a Job (see Chapter 1). That means that it's possible that a sequence of Promise tasks could complete ever-so-slightly slower than the same sequence wired up with callbacks.\n\nOf course, the question here is this: are these potential slips in tiny fractions of performance *worth* all the other articulated benefits of Promises we've laid out across this chapter?\n\nMy take is that in virtually all cases where you might think Promise performance is slow enough to be concerned, it's actually an anti-pattern to optimize away the benefits of Promise trustability and composability by avoiding them altogether.\n\nInstead, you should default to using them across the code base, and then profile and analyze your application's hot (critical) paths. Are Promises *really* a bottleneck, or are they just a theoretical slowdown? Only *then*, armed with actual valid benchmarks (see Chapter 6) is it responsible and prudent to factor out the Promises in just those identified critical areas.\n\nPromises are a little slower, but in exchange you're getting a lot of trustability, non-Zalgo predictability, and composability built in. Maybe the limitation is not actually their performance, but your lack of perception of their benefits?\n\n## Review\n\nPromises are awesome. Use them. They solve the *inversion of control* issues that plague us with callbacks-only code.\n\nThey don't get rid of callbacks, they just redirect the orchestration of those callbacks to a trustable intermediary mechanism that sits between us and another utility.\n\nPromise chains also begin to address (though certainly not perfectly) a better way of expressing async flow in sequential fashion, which helps our brains plan and maintain async JS code better. We'll see an even better solution to *that* problem in the next chapter!\n"
},
{
"path": "async & performance/ch4.md",
"content": "# You Don't Know JS: Async & Performance\n# Chapter 4: Generators\n\nIn Chapter 2, we identified two key drawbacks to expressing async flow control with callbacks:\n\n* Callback-based async doesn't fit how our brain plans out steps of a task.\n* Callbacks aren't trustable or composable because of *inversion of control*.\n\nIn Chapter 3, we detailed how Promises uninvert the *inversion of control* of callbacks, restoring trustability/composability.\n\nNow we turn our attention to expressing async flow control in a sequential, synchronous-looking fashion. The \"magic\" that makes it possible is ES6 **generators**.\n\n## Breaking Run-to-Completion\n\nIn Chapter 1, we explained an expectation that JS developers almost universally rely on in their code: once a function starts executing, it runs until it completes, and no other code can interrupt and run in between.\n\nAs bizarre as it may seem, ES6 introduces a new type of function that does not behave with the run-to-completion behavior. This new type of function is called a \"generator.\"\n\nTo understand the implications, let's consider this example:\n\n```js\nvar x = 1;\n\nfunction foo() {\n\tx++;\n\tbar();\t\t\t\t// <-- what about this line?\n\tconsole.log( \"x:\", x );\n}\n\nfunction bar() {\n\tx++;\n}\n\nfoo();\t\t\t\t\t// x: 3\n```\n\nIn this example, we know for sure that `bar()` runs in between `x++` and `console.log(x)`. But what if `bar()` wasn't there? Obviously, the result would be `2` instead of `3`.\n\nNow let's twist your brain. What if `bar()` wasn't present, but it could still somehow run between the `x++` and `console.log(x)` statements? How would that be possible?\n\nIn **preemptive** multithreaded languages, it would essentially be possible for `bar()` to \"interrupt\" and run at exactly the right moment between those two statements. But JS is not preemptive, nor is it (currently) multithreaded. And yet, a **cooperative** form of this \"interruption\" (concurrency) is possible, if `foo()` itself could somehow indicate a \"pause\" at that part in the code.\n\n**Note:** I use the word \"cooperative\" not only because of the connection to classical concurrency terminology (see Chapter 1), but because as you'll see in the next snippet, the ES6 syntax for indicating a pause point in code is `yield` -- suggesting a politely *cooperative* yielding of control.\n\nHere's the ES6 code to accomplish such cooperative concurrency:\n\n```js\nvar x = 1;\n\nfunction *foo() {\n\tx++;\n\tyield; // pause!\n\tconsole.log( \"x:\", x );\n}\n\nfunction bar() {\n\tx++;\n}\n```\n\n**Note:** You will likely see most other JS documentation/code that will format a generator declaration as `function* foo() { .. }` instead of as I've done here with `function *foo() { .. }` -- the only difference being the stylistic positioning of the `*`. The two forms are functionally/syntactically identical, as is a third `function*foo() { .. }` (no space) form. There are arguments for both styles, but I basically prefer `function *foo..` because it then matches when I reference a generator in writing with `*foo()`. If I said only `foo()`, you wouldn't know as clearly if I was talking about a generator or a regular function. It's purely a stylistic preference.\n\nNow, how can we run the code in that previous snippet such that `bar()` executes at the point of the `yield` inside of `*foo()`?\n\n```js\n// construct an iterator `it` to control the generator\nvar it = foo();\n\n// start `foo()` here!\nit.next();\nx;\t\t\t\t\t\t// 2\nbar();\nx;\t\t\t\t\t\t// 3\nit.next();\t\t\t\t// x: 3\n```\n\nOK, there's quite a bit of new and potentially confusing stuff in those two code snippets, so we've got plenty to wade through. But before we explain the different mechanics/syntax with ES6 generators, let's walk through the behavior flow:\n\n1. The `it = foo()` operation does *not* execute the `*foo()` generator yet, but it merely constructs an *iterator* that will control its execution. More on *iterators* in a bit.\n2. The first `it.next()` starts the `*foo()` generator, and runs the `x++` on the first line of `*foo()`.\n3. `*foo()` pauses at the `yield` statement, at which point that first `it.next()` call finishes. At the moment, `*foo()` is still running and active, but it's in a paused state.\n4. We inspect the value of `x`, and it's now `2`.\n5. We call `bar()`, which increments `x` again with `x++`.\n6. We inspect the value of `x` again, and it's now `3`.\n7. The final `it.next()` call resumes the `*foo()` generator from where it was paused, and runs the `console.log(..)` statement, which uses the current value of `x` of `3`.\n\nClearly, `*foo()` started, but did *not* run-to-completion -- it paused at the `yield`. We resumed `*foo()` later, and let it finish, but that wasn't even required.\n\nSo, a generator is a special kind of function that can start and stop one or more times, and doesn't necessarily ever have to finish. While it won't be terribly obvious yet why that's so powerful, as we go throughout the rest of this chapter, that will be one of the fundamental building blocks we use to construct generators-as-async-flow-control as a pattern for our code.\n\n### Input and Output\n\nA generator function is a special function with the new processing model we just alluded to. But it's still a function, which means it still has some basic tenets that haven't changed -- namely, that it still accepts arguments (aka \"input\"), and that it can still return a value (aka \"output\"):\n\n```js\nfunction *foo(x,y) {\n\treturn x * y;\n}\n\nvar it = foo( 6, 7 );\n\nvar res = it.next();\n\nres.value;\t\t// 42\n```\n\nWe pass in the arguments `6` and `7` to `*foo(..)` as the parameters `x` and `y`, respectively. And `*foo(..)` returns the value `42` back to the calling code.\n\nWe now see a difference with how the generator is invoked compared to a normal function. `foo(6,7)` obviously looks familiar. But subtly, the `*foo(..)` generator hasn't actually run yet as it would have with a function.\n\nInstead, we're just creating an *iterator* object, which we assign to the variable `it`, to control the `*foo(..)` generator. Then we call `it.next()`, which instructs the `*foo(..)` generator to advance from its current location, stopping either at the next `yield` or end of the generator.\n\nThe result of that `next(..)` call is an object with a `value` property on it holding whatever value (if anything) was returned from `*foo(..)`. In other words, `yield` caused a value to be sent out from the generator during the middle of its execution, kind of like an intermediate `return`.\n\nAgain, it won't be obvious yet why we need this whole indirect *iterator* object to control the generator. We'll get there, I *promise*.\n\n#### Iteration Messaging\n\nIn addition to generators accepting arguments and having return values, there's even more powerful and compelling input/output messaging capability built into them, via `yield` and `next(..)`.\n\nConsider:\n\n```js\nfunction *foo(x) {\n\tvar y = x * (yield);\n\treturn y;\n}\n\nvar it = foo( 6 );\n\n// start `foo(..)`\nit.next();\n\nvar res = it.next( 7 );\n\nres.value;\t\t// 42\n```\n\nFirst, we pass in `6` as the parameter `x`. Then we call `it.next()`, and it starts up `*foo(..)`.\n\nInside `*foo(..)`, the `var y = x ..` statement starts to be processed, but then it runs across a `yield` expression. At that point, it pauses `*foo(..)` (in the middle of the assignment statement!), and essentially requests the calling code to provide a result value for the `yield` expression. Next, we call `it.next( 7 )`, which is passing the `7` value back in to *be* that result of the paused `yield` expression.\n\nSo, at this point, the assignment statement is essentially `var y = 6 * 7`. Now, `return y` returns that `42` value back as the result of the `it.next( 7 )` call.\n\nNotice something very important but also easily confusing, even to seasoned JS developers: depending on your perspective, there's a mismatch between the `yield` and the `next(..)` call. In general, you're going to have one more `next(..)` call than you have `yield` statements -- the preceding snippet has one `yield` and two `next(..)` calls.\n\nWhy the mismatch?\n\nBecause the first `next(..)` always starts a generator, and runs to the first `yield`. But it's the second `next(..)` call that fulfills the first paused `yield` expression, and the third `next(..)` would fulfill the second `yield`, and so on.\n\n##### Tale of Two Questions\n\nActually, which code you're thinking about primarily will affect whether there's a perceived mismatch or not.\n\nConsider only the generator code:\n\n```js\nvar y = x * (yield);\nreturn y;\n```\n\nThis **first** `yield` is basically *asking a question*: \"What value should I insert here?\"\n\nWho's going to answer that question? Well, the **first** `next()` has already run to get the generator up to this point, so obviously *it* can't answer the question. So, the **second** `next(..)` call must answer the question *posed* by the **first** `yield`.\n\nSee the mismatch -- second-to-first?\n\nBut let's flip our perspective. Let's look at it not from the generator's point of view, but from the iterator's point of view.\n\nTo properly illustrate this perspective, we also need to explain that messages can go in both directions -- `yield ..` as an expression can send out messages in response to `next(..)` calls, and `next(..)` can send values to a paused `yield` expression. Consider this slightly adjusted code:\n\n```js\nfunction *foo(x) {\n\tvar y = x * (yield \"Hello\");\t// <-- yield a value!\n\treturn y;\n}\n\nvar it = foo( 6 );\n\nvar res = it.next();\t// first `next()`, don't pass anything\nres.value;\t\t\t\t// \"Hello\"\n\nres = it.next( 7 );\t\t// pass `7` to waiting `yield`\nres.value;\t\t\t\t// 42\n```\n\n`yield ..` and `next(..)` pair together as a two-way message passing system **during the execution of the generator**.\n\nSo, looking only at the *iterator* code:\n\n```js\nvar res = it.next();\t// first `next()`, don't pass anything\nres.value;\t\t\t\t// \"Hello\"\n\nres = it.next( 7 );\t\t// pass `7` to waiting `yield`\nres.value;\t\t\t\t// 42\n```\n\n**Note:** We don't pass a value to the first `next()` call, and that's on purpose. Only a paused `yield` could accept such a value passed by a `next(..)`, and at the beginning of the generator when we call the first `next()`, there **is no paused `yield`** to accept such a value. The specification and all compliant browsers just silently **discard** anything passed to the first `next()`. It's still a bad idea to pass a value, as you're just creating silently \"failing\" code that's confusing. So, always start a generator with an argument-free `next()`.\n\nThe first `next()` call (with nothing passed to it) is basically *asking a question*: \"What *next* value does the `*foo(..)` generator have to give me?\" And who answers this question? The first `yield \"hello\"` expression.\n\nSee? No mismatch there.\n\nDepending on *who* you think about asking the question, there is either a mismatch between the `yield` and `next(..)` calls, or not.\n\nBut wait! There's still an extra `next()` compared to the number of `yield` statements. So, that final `it.next(7)` call is again asking the question about what *next* value the generator will produce. But there's no more `yield` statements left to answer, is there? So who answers?\n\nThe `return` statement answers the question!\n\nAnd if there **is no `return`** in your generator -- `return` is certainly not any more required in generators than in regular functions -- there's always an assumed/implicit `return;` (aka `return undefined;`), which serves the purpose of default answering the question *posed* by the final `it.next(7)` call.\n\nThese questions and answers -- the two-way message passing with `yield` and `next(..)` -- are quite powerful, but it's not obvious at all how these mechanisms are connected to async flow control. We're getting there!\n\n### Multiple Iterators\n\nIt may appear from the syntactic usage that when you use an *iterator* to control a generator, you're controlling the declared generator function itself. But there's a subtlety that's easy to miss: each time you construct an *iterator*, you are implicitly constructing an instance of the generator which that *iterator* will control.\n\nYou can have multiple instances of the same generator running at the same time, and they can even interact:\n\n```js\nfunction *foo() {\n\tvar x = yield 2;\n\tz++;\n\tvar y = yield (x * z);\n\tconsole.log( x, y, z );\n}\n\nvar z = 1;\n\nvar it1 = foo();\nvar it2 = foo();\n\nvar val1 = it1.next().value;\t\t\t// 2 <-- yield 2\nvar val2 = it2.next().value;\t\t\t// 2 <-- yield 2\n\nval1 = it1.next( val2 * 10 ).value;\t\t// 40 <-- x:20, z:2\nval2 = it2.next( val1 * 5 ).value;\t\t// 600 <-- x:200, z:3\n\nit1.next( val2 / 2 );\t\t\t\t\t// y:300\n\t\t\t\t\t\t\t\t\t\t// 20 300 3\nit2.next( val1 / 4 );\t\t\t\t\t// y:10\n\t\t\t\t\t\t\t\t\t\t// 200 10 3\n```\n\n**Warning:** The most common usage of multiple instances of the same generator running concurrently is not such interactions, but when the generator is producing its own values without input, perhaps from some independently connected resource. We'll talk more about value production in the next section.\n\nLet's briefly walk through the processing:\n\n1. Both instances of `*foo()` are started at the same time, and both `next()` calls reveal a `value` of `2` from the `yield 2` statements, respectively.\n2. `val2 * 10` is `2 * 10`, which is sent into the first generator instance `it1`, so that `x` gets value `20`. `z` is incremented from `1` to `2`, and then `20 * 2` is `yield`ed out, setting `val1` to `40`.\n3. `val1 * 5` is `40 * 5`, which is sent into the second generator instance `it2`, so that `x` gets value `200`. `z` is incremented again, from `2` to `3`, and then `200 * 3` is `yield`ed out, setting `val2` to `600`.\n4. `val2 / 2` is `600 / 2`, which is sent into the first generator instance `it1`, so that `y` gets value `300`, then printing out `20 300 3` for its `x y z` values, respectively.\n5. `val1 / 4` is `40 / 4`, which is sent into the second generator instance `it2`, so that `y` gets value `10`, then printing out `200 10 3` for its `x y z` values, respectively.\n\nThat's a \"fun\" example to run through in your mind. Did you keep it straight?\n\n#### Interleaving\n\nRecall this scenario from the \"Run-to-completion\" section of Chapter 1:\n\n```js\nvar a = 1;\nvar b = 2;\n\nfunction foo() {\n\ta++;\n\tb = b * a;\n\ta = b + 3;\n}\n\nfunction bar() {\n\tb--;\n\ta = 8 + b;\n\tb = a * 2;\n}\n```\n\nWith normal JS functions, of course either `foo()` can run completely first, or `bar()` can run completely first, but `foo()` cannot interleave its individual statements with `bar()`. So, there are only two possible outcomes to the preceding program.\n\nHowever, with generators, clearly interleaving (even in the middle of statements!) is possible:\n\n```js\nvar a = 1;\nvar b = 2;\n\nfunction *foo() {\n\ta++;\n\tyield;\n\tb = b * a;\n\ta = (yield b) + 3;\n}\n\nfunction *bar() {\n\tb--;\n\tyield;\n\ta = (yield 8) + b;\n\tb = a * (yield 2);\n}\n```\n\nDepending on what respective order the *iterators* controlling `*foo()` and `*bar()` are called, the preceding program could produce several different results. In other words, we can actually illustrate (in a sort of fake-ish way) the theoretical \"threaded race conditions\" circumstances discussed in Chapter 1, by interleaving the two generator iterations over the same shared variables.\n\nFirst, let's make a helper called `step(..)` that controls an *iterator*:\n\n```js\nfunction step(gen) {\n\tvar it = gen();\n\tvar last;\n\n\treturn function() {\n\t\t// whatever is `yield`ed out, just\n\t\t// send it right back in the next time!\n\t\tlast = it.next( last ).value;\n\t};\n}\n```\n\n`step(..)` initializes a generator to create its `it` *iterator*, then returns a function which, when called, advances the *iterator* by one step. Additionally, the previously `yield`ed out value is sent right back in at the *next* step. So, `yield 8` will just become `8` and `yield b` will just be `b` (whatever it was at the time of `yield`).\n\nNow, just for fun, let's experiment to see the effects of interleaving these different chunks of `*foo()` and `*bar()`. We'll start with the boring base case, making sure `*foo()` totally finishes before `*bar()` (just like we did in Chapter 1):\n\n```js\n// make sure to reset `a` and `b`\na = 1;\nb = 2;\n\nvar s1 = step( foo );\nvar s2 = step( bar );\n\n// run `*foo()` completely first\ns1();\ns1();\ns1();\n\n// now run `*bar()`\ns2();\ns2();\ns2();\ns2();\n\nconsole.log( a, b );\t// 11 22\n```\n\nThe end result is `11` and `22`, just as it was in the Chapter 1 version. Now let's mix up the interleaving ordering and see how it changes the final values of `a` and `b`:\n\n```js\n// make sure to reset `a` and `b`\na = 1;\nb = 2;\n\nvar s1 = step( foo );\nvar s2 = step( bar );\n\ns2();\t\t// b--;\ns2();\t\t// yield 8\ns1();\t\t// a++;\ns2();\t\t// a = 8 + b;\n\t\t\t// yield 2\ns1();\t\t// b = b * a;\n\t\t\t// yield b\ns1();\t\t// a = b + 3;\ns2();\t\t// b = a * 2;\n```\n\nBefore I tell you the results, can you figure out what `a` and `b` are after the preceding program? No cheating!\n\n```js\nconsole.log( a, b );\t// 12 18\n```\n\n**Note:** As an exercise for the reader, try to see how many other combinations of results you can get back rearranging the order of the `s1()` and `s2()` calls. Don't forget you'll always need three `s1()` calls and four `s2()` calls. Recall the discussion earlier about matching `next()` with `yield` for the reasons why.\n\nYou almost certainly won't want to intentionally create *this* level of interleaving confusion, as it creates incredibly difficult to understand code. But the exercise is interesting and instructive to understand more about how multiple generators can run concurrently in the same shared scope, because there will be places where this capability is quite useful.\n\nWe'll discuss generator concurrency in more detail at the end of this chapter.\n\n## Generator'ing Values\n\nIn the previous section, we mentioned an interesting use for generators, as a way to produce values. This is **not** the main focus in this chapter, but we'd be remiss if we didn't cover the basics, especially because this use case is essentially the origin of the name: generators.\n\nWe're going to take a slight diversion into the topic of *iterators* for a bit, but we'll circle back to how they relate to generators and using a generator to *generate* values.\n\n### Producers and Iterators\n\nImagine you're producing a series of values where each value has a definable relationship to the previous value. To do this, you're going to need a stateful producer that remembers the last value it gave out.\n\nYou can implement something like that straightforwardly using a function closure (see the *Scope & Closures* title of this series):\n\n```js\nvar gimmeSomething = (function(){\n\tvar nextVal;\n\n\treturn function(){\n\t\tif (nextVal === undefined) {\n\t\t\tnextVal = 1;\n\t\t}\n\t\telse {\n\t\t\tnextVal = (3 * nextVal) + 6;\n\t\t}\n\n\t\treturn nextVal;\n\t};\n})();\n\ngimmeSomething();\t\t// 1\ngimmeSomething();\t\t// 9\ngimmeSomething();\t\t// 33\ngimmeSomething();\t\t// 105\n```\n\n**Note:** The `nextVal` computation logic here could have been simplified, but conceptually, we don't want to calculate the *next value* (aka `nextVal`) until the *next* `gimmeSomething()` call happens, because in general that could be a resource-leaky design for producers of more persistent or resource-limited values than simple `number`s.\n\nGenerating an arbitrary number series isn't a terribly realistic example. But what if you were generating records from a data source? You could imagine much the same code.\n\nIn fact, this task is a very common design pattern, usually solved by iterators. An *iterator* is a well-defined interface for stepping through a series of values from a producer. The JS interface for iterators, as it is in most languages, is to call `next()` each time you want the next value from the producer.\n\nWe could implement the standard *iterator* interface for our number series producer:\n\n```js\nvar something = (function(){\n\tvar nextVal;\n\n\treturn {\n\t\t// needed for `for..of` loops\n\t\t[Symbol.iterator]: function(){ return this; },\n\n\t\t// standard iterator interface method\n\t\tnext: function(){\n\t\t\tif (nextVal === undefined) {\n\t\t\t\tnextVal = 1;\n\t\t\t}\n\t\t\telse {\n\t\t\t\tnextVal = (3 * nextVal) + 6;\n\t\t\t}\n\n\t\t\treturn { done:false, value:nextVal };\n\t\t}\n\t};\n})();\n\nsomething.next().value;\t\t// 1\nsomething.next().value;\t\t// 9\nsomething.next().value;\t\t// 33\nsomething.next().value;\t\t// 105\n```\n\n**Note:** We'll explain why we need the `[Symbol.iterator]: ..` part of this code snippet in the \"Iterables\" section. Syntactically though, two ES6 features are at play. First, the `[ .. ]` syntax is called a *computed property name* (see the *this & Object Prototypes* title of this series). It's a way in an object literal definition to specify an expression and use the result of that expression as the name for the property. Next, `Symbol.iterator` is one of ES6's predefined special `Symbol` values (see the *ES6 & Beyond* title of this book series).\n\nThe `next()` call returns an object with two properties: `done` is a `boolean` value signaling the *iterator's* complete status; `value` holds the iteration value.\n\nES6 also adds the `for..of` loop, which means that a standard *iterator* can automatically be consumed with native loop syntax:\n\n```js\nfor (var v of something) {\n\tconsole.log( v );\n\n\t// don't let the loop run forever!\n\tif (v > 500) {\n\t\tbreak;\n\t}\n}\n// 1 9 33 105 321 969\n```\n\n**Note:** Because our `something` *iterator* always returns `done:false`, this `for..of` loop would run forever, which is why we put the `break` conditional in. It's totally OK for iterators to be never-ending, but there are also cases where the *iterator* will run over a finite set of values and eventually return a `done:true`.\n\nThe `for..of` loop automatically calls `next()` for each iteration -- it doesn't pass any values in to the `next()` -- and it will automatically terminate on receiving a `done:true`. It's quite handy for looping over a set of data.\n\nOf course, you could manually loop over iterators, calling `next()` and checking for the `done:true` condition to know when to stop:\n\n```js\nfor (\n\tvar ret;\n\t(ret = something.next()) && !ret.done;\n) {\n\tconsole.log( ret.value );\n\n\t// don't let the loop run forever!\n\tif (ret.value > 500) {\n\t\tbreak;\n\t}\n}\n// 1 9 33 105 321 969\n```\n\n**Note:** This manual `for` approach is certainly uglier than the ES6 `for..of` loop syntax, but its advantage is that it affords you the opportunity to pass in values to the `next(..)` calls if necessary.\n\nIn addition to making your own *iterators*, many built-in data structures in JS (as of ES6), like `array`s, also have default *iterators*:\n\n```js\nvar a = [1,3,5,7,9];\n\nfor (var v of a) {\n\tconsole.log( v );\n}\n// 1 3 5 7 9\n```\n\nThe `for..of` loop asks `a` for its *iterator*, and automatically uses it to iterate over `a`'s values.\n\n**Note:** It may seem a strange omission by ES6, but regular `object`s intentionally do not come with a default *iterator* the way `array`s do. The reasons go deeper than we will cover here. If all you want is to iterate over the properties of an object (with no particular guarantee of ordering), `Object.keys(..)` returns an `array`, which can then be used like `for (var k of Object.keys(obj)) { ..`. Such a `for..of` loop over an object's keys would be similar to a `for..in` loop, except that `Object.keys(..)` does not include properties from the `[[Prototype]]` chain while `for..in` does (see the *this & Object Prototypes* title of this series).\n\n### Iterables\n\nThe `something` object in our running example is called an *iterator*, as it has the `next()` method on its interface. But a closely related term is *iterable*, which is an `object` that **contains** an *iterator* that can iterate over its values.\n\nAs of ES6, the way to retrieve an *iterator* from an *iterable* is that the *iterable* must have a function on it, with the name being the special ES6 symbol value `Symbol.iterator`. When this function is called, it returns an *iterator*. Though not required, generally each call should return a fresh new *iterator*.\n\n`a` in the previous snippet is an *iterable*. The `for..of` loop automatically calls its `Symbol.iterator` function to construct an *iterator*. But we could of course call the function manually, and use the *iterator* it returns:\n\n```js\nvar a = [1,3,5,7,9];\n\nvar it = a[Symbol.iterator]();\n\nit.next().value;\t// 1\nit.next().value;\t// 3\nit.next().value;\t// 5\n..\n```\n\nIn the previous code listing that defined `something`, you may have noticed this line:\n\n```js\n[Symbol.iterator]: function(){ return this; }\n```\n\nThat little bit of confusing code is making the `something` value -- the interface of the `something` *iterator* -- also an *iterable*; it's now both an *iterable* and an *iterator*. Then, we pass `something` to the `for..of` loop:\n\n```js\nfor (var v of something) {\n\t..\n}\n```\n\nThe `for..of` loop expects `something` to be an *iterable*, so it looks for and calls its `Symbol.iterator` function. We defined that function to simply `return this`, so it just gives itself back, and the `for..of` loop is none the wiser.\n\n### Generator Iterator\n\nLet's turn our attention back to generators, in the context of *iterators*. A generator can be treated as a producer of values that we extract one at a time through an *iterator* interface's `next()` calls.\n\nSo, a generator itself is not technically an *iterable*, though it's very similar -- when you execute the generator, you get an *iterator* back:\n\n```js\nfunction *foo(){ .. }\n\nvar it = foo();\n```\n\nWe can implement the `something` infinite number series producer from earlier with a generator, like this:\n\n```js\nfunction *something() {\n\tvar nextVal;\n\n\twhile (true) {\n\t\tif (nextVal === undefined) {\n\t\t\tnextVal = 1;\n\t\t}\n\t\telse {\n\t\t\tnextVal = (3 * nextVal) + 6;\n\t\t}\n\n\t\tyield nextVal;\n\t}\n}\n```\n\n**Note:** A `while..true` loop would normally be a very bad thing to include in a real JS program, at least if it doesn't have a `break` or `return` in it, as it would likely run forever, synchronously, and block/lock-up the browser UI. However, in a generator, such a loop is generally totally OK if it has a `yield` in it, as the generator will pause at each iteration, `yield`ing back to the main program and/or to the event loop queue. To put it glibly, \"generators put the `while..true` back in JS programming!\"\n\nThat's a fair bit cleaner and simpler, right? Because the generator pauses at each `yield`, the state (scope) of the function `*something()` is kept around, meaning there's no need for the closure boilerplate to preserve variable state across calls.\n\nNot only is it simpler code -- we don't have to make our own *iterator* interface -- it actually is more reason-able code, because it more clearly expresses the intent. For example, the `while..true` loop tells us the generator is intended to run forever -- to keep *generating* values as long as we keep asking for them.\n\nAnd now we can use our shiny new `*something()` generator with a `for..of` loop, and you'll see it works basically identically:\n\n```js\nfor (var v of something()) {\n\tconsole.log( v );\n\n\t// don't let the loop run forever!\n\tif (v > 500) {\n\t\tbreak;\n\t}\n}\n// 1 9 33 105 321 969\n```\n\nBut don't skip over `for (var v of something()) ..`! We didn't just reference `something` as a value like in earlier examples, but instead called the `*something()` generator to get its *iterator* for the `for..of` loop to use.\n\nIf you're paying close attention, two questions may arise from this interaction between the generator and the loop:\n\n* Why couldn't we say `for (var v of something) ..`? Because `something` here is a generator, which is not an *iterable*. We have to call `something()` to construct a producer for the `for..of` loop to iterate over.\n* The `something()` call produces an *iterator*, but the `for..of` loop wants an *iterable*, right? Yep. The generator's *iterator* also has a `Symbol.iterator` function on it, which basically does a `return this`, just like the `something` *iterable* we defined earlier. In other words, a generator's *iterator* is also an *iterable*!\n\n#### Stopping the Generator\n\nIn the previous example, it would appear the *iterator* instance for the `*something()` generator was basically left in a suspended state forever after the `break` in the loop was called.\n\nBut there's a hidden behavior that takes care of that for you. \"Abnormal completion\" (i.e., \"early termination\") of the `for..of` loop -- generally caused by a `break`, `return`, or an uncaught exception -- sends a signal to the generator's *iterator* for it to terminate.\n\n**Note:** Technically, the `for..of` loop also sends this signal to the *iterator* at the normal completion of the loop. For a generator, that's essentially a moot operation, as the generator's *iterator* had to complete first so the `for..of` loop completed. However, custom *iterators* might desire to receive this additional signal from `for..of` loop consumers.\n\nWhile a `for..of` loop will automatically send this signal, you may wish to send the signal manually to an *iterator*; you do this by calling `return(..)`.\n\nIf you specify a `try..finally` clause inside the generator, it will always be run even when the generator is externally completed. This is useful if you need to clean up resources (database connections, etc.):\n\n```js\nfunction *something() {\n\ttry {\n\t\tvar nextVal;\n\n\t\twhile (true) {\n\t\t\tif (nextVal === undefined) {\n\t\t\t\tnextVal = 1;\n\t\t\t}\n\t\t\telse {\n\t\t\t\tnextVal = (3 * nextVal) + 6;\n\t\t\t}\n\n\t\t\tyield nextVal;\n\t\t}\n\t}\n\t// cleanup clause\n\tfinally {\n\t\tconsole.log( \"cleaning up!\" );\n\t}\n}\n```\n\nThe earlier example with `break` in the `for..of` loop will trigger the `finally` clause. But you could instead manually terminate the generator's *iterator* instance from the outside with `return(..)`:\n\n```js\nvar it = something();\nfor (var v of it) {\n\tconsole.log( v );\n\n\t// don't let the loop run forever!\n\tif (v > 500) {\n\t\tconsole.log(\n\t\t\t// complete the generator's iterator\n\t\t\tit.return( \"Hello World\" ).value\n\t\t);\n\t\t// no `break` needed here\n\t}\n}\n// 1 9 33 105 321 969\n// cleaning up!\n// Hello World\n```\n\nWhen we call `it.return(..)`, it immediately terminates the generator, which of course runs the `finally` clause. Also, it sets the returned `value` to whatever you passed in to `return(..)`, which is how `\"Hello World\"` comes right back out. We also don't need to include a `break` now because the generator's *iterator* is set to `done:true`, so the `for..of` loop will terminate on its next iteration.\n\nGenerators owe their namesake mostly to this *consuming produced values* use. But again, that's just one of the uses for generators, and frankly not even the main one we're concerned with in the context of this book.\n\nBut now that we more fully understand some of the mechanics of how they work, we can *next* turn our attention to how generators apply to async concurrency.\n\n## Iterating Generators Asynchronously\n\nWhat do generators have to do with async coding patterns, fixing problems with callbacks, and the like? Let's get to answering that important question.\n\nWe should revisit one of our scenarios from Chapter 3. Let's recall the callback approach:\n\n```js\nfunction foo(x,y,cb) {\n\tajax(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y,\n\t\tcb\n\t);\n}\n\nfoo( 11, 31, function(err,text) {\n\tif (err) {\n\t\tconsole.error( err );\n\t}\n\telse {\n\t\tconsole.log( text );\n\t}\n} );\n```\n\nIf we wanted to express this same task flow control with a generator, we could do:\n\n```js\nfunction foo(x,y) {\n\tajax(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y,\n\t\tfunction(err,data){\n\t\t\tif (err) {\n\t\t\t\t// throw an error into `*main()`\n\t\t\t\tit.throw( err );\n\t\t\t}\n\t\t\telse {\n\t\t\t\t// resume `*main()` with received `data`\n\t\t\t\tit.next( data );\n\t\t\t}\n\t\t}\n\t);\n}\n\nfunction *main() {\n\ttry {\n\t\tvar text = yield foo( 11, 31 );\n\t\tconsole.log( text );\n\t}\n\tcatch (err) {\n\t\tconsole.error( err );\n\t}\n}\n\nvar it = main();\n\n// start it all up!\nit.next();\n```\n\nAt first glance, this snippet is longer, and perhaps a little more complex looking, than the callback snippet before it. But don't let that impression get you off track. The generator snippet is actually **much** better! But there's a lot going on for us to explain.\n\nFirst, let's look at this part of the code, which is the most important:\n\n```js\nvar text = yield foo( 11, 31 );\nconsole.log( text );\n```\n\nThink about how that code works for a moment. We're calling a normal function `foo(..)` and we're apparently able to get back the `text` from the Ajax call, even though it's asynchronous.\n\nHow is that possible? If you recall the beginning of Chapter 1, we had almost identical code:\n\n```js\nvar data = ajax( \"..url 1..\" );\nconsole.log( data );\n```\n\nAnd that code didn't work! Can you spot the difference? It's the `yield` used in a generator.\n\nThat's the magic! That's what allows us to have what appears to be blocking, synchronous code, but it doesn't actually block the whole program; it only pauses/blocks the code in the generator itself.\n\nIn `yield foo(11,31)`, first the `foo(11,31)` call is made, which returns nothing (aka `undefined`), so we're making a call to request data, but we're actually then doing `yield undefined`. That's OK, because the code is not currently relying on a `yield`ed value to do anything interesting. We'll revisit this point later in the chapter.\n\nWe're not using `yield` in a message passing sense here, only in a flow control sense to pause/block. Actually, it will have message passing, but only in one direction, after the generator is resumed.\n\nSo, the generator pauses at the `yield`, essentially asking the question, \"what value should I return to assign to the variable `text`?\" Who's going to answer that question?\n\nLook at `foo(..)`. If the Ajax request is successful, we call:\n\n```js\nit.next( data );\n```\n\nThat's resuming the generator with the response data, which means that our paused `yield` expression receives that value directly, and then as it restarts the generator code, that value gets assigned to the local variable `text`.\n\nPretty cool, huh?\n\nTake a step back and consider the implications. We have totally synchronous-looking code inside the generator (other than the `yield` keyword itself), but hidden behind the scenes, inside of `foo(..)`, the operations can complete asynchronously.\n\n**That's huge!** That's a nearly perfect solution to our previously stated problem with callbacks not being able to express asynchrony in a sequential, synchronous fashion that our brains can relate to.\n\nIn essence, we are abstracting the asynchrony away as an implementation detail, so that we can reason synchronously/sequentially about our flow control: \"Make an Ajax request, and when it finishes print out the response.\" And of course, we just expressed two steps in the flow control, but this same capability extends without bounds, to let us express however many steps we need to.\n\n**Tip:** This is such an important realization, just go back and read the last three paragraphs again to let it sink in!\n\n### Synchronous Error Handling\n\nBut the preceding generator code has even more goodness to *yield* to us. Let's turn our attention to the `try..catch` inside the generator:\n\n```js\ntry {\n\tvar text = yield foo( 11, 31 );\n\tconsole.log( text );\n}\ncatch (err) {\n\tconsole.error( err );\n}\n```\n\nHow does this work? The `foo(..)` call is asynchronously completing, and doesn't `try..catch` fail to catch asynchronous errors, as we looked at in Chapter 3?\n\nWe already saw how the `yield` lets the assignment statement pause to wait for `foo(..)` to finish, so that the completed response can be assigned to `text`. The awesome part is that this `yield` pausing *also* allows the generator to `catch` an error. We throw that error into the generator with this part of the earlier code listing:\n\n```js\nif (err) {\n\t// throw an error into `*main()`\n\tit.throw( err );\n}\n```\n\nThe `yield`-pause nature of generators means that not only do we get synchronous-looking `return` values from async function calls, but we can also synchronously `catch` errors from those async function calls!\n\nSo we've seen we can throw errors *into* a generator, but what about throwing errors *out of* a generator? Exactly as you'd expect:\n\n```js\nfunction *main() {\n\tvar x = yield \"Hello World\";\n\n\tyield x.toLowerCase();\t// cause an exception!\n}\n\nvar it = main();\n\nit.next().value;\t\t\t// Hello World\n\ntry {\n\tit.next( 42 );\n}\ncatch (err) {\n\tconsole.error( err );\t// TypeError\n}\n```\n\nOf course, we could have manually thrown an error with `throw ..` instead of causing an exception.\n\nWe can even `catch` the same error that we `throw(..)` into the generator, essentially giving the generator a chance to handle it but if it doesn't, the *iterator* code must handle it:\n\n```js\nfunction *main() {\n\tvar x = yield \"Hello World\";\n\n\t// never gets here\n\tconsole.log( x );\n}\n\nvar it = main();\n\nit.next();\n\ntry {\n\t// will `*main()` handle this error? we'll see!\n\tit.throw( \"Oops\" );\n}\ncatch (err) {\n\t// nope, didn't handle it!\n\tconsole.error( err );\t\t\t// Oops\n}\n```\n\nSynchronous-looking error handling (via `try..catch`) with async code is a huge win for readability and reason-ability.\n\n## Generators + Promises\n\nIn our previous discussion, we showed how generators can be iterated asynchronously, which is a huge step forward in sequential reason-ability over the spaghetti mess of callbacks. But we lost something very important: the trustability and composability of Promises (see Chapter 3)!\n\nDon't worry -- we can get that back. The best of all worlds in ES6 is to combine generators (synchronous-looking async code) with Promises (trustable and composable).\n\nBut how?\n\nRecall from Chapter 3 the Promise-based approach to our running Ajax example:\n\n```js\nfunction foo(x,y) {\n\treturn request(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y\n\t);\n}\n\nfoo( 11, 31 )\n.then(\n\tfunction(text){\n\t\tconsole.log( text );\n\t},\n\tfunction(err){\n\t\tconsole.error( err );\n\t}\n);\n```\n\nIn our earlier generator code for the running Ajax example, `foo(..)` returned nothing (`undefined`), and our *iterator* control code didn't care about that `yield`ed value.\n\nBut here the Promise-aware `foo(..)` returns a promise after making the Ajax call. That suggests that we could construct a promise with `foo(..)` and then `yield` it from the generator, and then the *iterator* control code would receive that promise.\n\nBut what should the *iterator* do with the promise?\n\nIt should listen for the promise to resolve (fulfillment or rejection), and then either resume the generator with the fulfillment message or throw an error into the generator with the rejection reason.\n\nLet me repeat that, because it's so important. The natural way to get the most out of Promises and generators is **to `yield` a Promise**, and wire that Promise to control the generator's *iterator*.\n\nLet's give it a try! First, we'll put the Promise-aware `foo(..)` together with the generator `*main()`:\n\n```js\nfunction foo(x,y) {\n\treturn request(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y\n\t);\n}\n\nfunction *main() {\n\ttry {\n\t\tvar text = yield foo( 11, 31 );\n\t\tconsole.log( text );\n\t}\n\tcatch (err) {\n\t\tconsole.error( err );\n\t}\n}\n```\n\nThe most powerful revelation in this refactor is that the code inside `*main()` **did not have to change at all!** Inside the generator, whatever values are `yield`ed out is just an opaque implementation detail, so we're not even aware it's happening, nor do we need to worry about it.\n\nBut how are we going to run `*main()` now? We still have some of the implementation plumbing work to do, to receive and wire up the `yield`ed promise so that it resumes the generator upon resolution. We'll start by trying that manually:\n\n```js\nvar it = main();\n\nvar p = it.next().value;\n\n// wait for the `p` promise to resolve\np.then(\n\tfunction(text){\n\t\tit.next( text );\n\t},\n\tfunction(err){\n\t\tit.throw( err );\n\t}\n);\n```\n\nActually, that wasn't so painful at all, was it?\n\nThis snippet should look very similar to what we did earlier with the manually wired generator controlled by the error-first callback. Instead of an `if (err) { it.throw..`, the promise already splits fulfillment (success) and rejection (failure) for us, but otherwise the *iterator* control is identical.\n\nNow, we've glossed over some important details.\n\nMost importantly, we took advantage of the fact that we knew that `*main()` only had one Promise-aware step in it. What if we wanted to be able to Promise-drive a generator no matter how many steps it has? We certainly don't want to manually write out the Promise chain differently for each generator! What would be much nicer is if there was a way to repeat (aka \"loop\" over) the iteration control, and each time a Promise comes out, wait on its resolution before continuing.\n\nAlso, what if the generator throws out an error (intentionally or accidentally) during the `it.next(..)` call? Should we quit, or should we `catch` it and send it right back in? Similarly, what if we `it.throw(..)` a Promise rejection into the generator, but it's not handled, and comes right back out?\n\n### Promise-Aware Generator Runner\n\nThe more you start to explore this path, the more you realize, \"wow, it'd be great if there was just some utility to do it for me.\" And you're absolutely correct. This is such an important pattern, and you don't want to get it wrong (or exhaust yourself repeating it over and over), so your best bet is to use a utility that is specifically designed to *run* Promise-`yield`ing generators in the manner we've illustrated.\n\nSeveral Promise abstraction libraries provide just such a utility, including my *asynquence* library and its `runner(..)`, which will be discussed in Appendix A of this book.\n\nBut for the sake of learning and illustration, let's just define our own standalone utility that we'll call `run(..)`:\n\n```js\n// thanks to Benjamin Gruenbaum (@benjamingr on GitHub) for\n// big improvements here!\nfunction run(gen) {\n\tvar args = [].slice.call( arguments, 1), it;\n\n\t// initialize the generator in the current context\n\tit = gen.apply( this, args );\n\n\t// return a promise for the generator completing\n\treturn Promise.resolve()\n\t\t.then( function handleNext(value){\n\t\t\t// run to the next yielded value\n\t\t\tvar next = it.next( value );\n\n\t\t\treturn (function handleResult(next){\n\t\t\t\t// generator has completed running?\n\t\t\t\tif (next.done) {\n\t\t\t\t\treturn next.value;\n\t\t\t\t}\n\t\t\t\t// otherwise keep going\n\t\t\t\telse {\n\t\t\t\t\treturn Promise.resolve( next.value )\n\t\t\t\t\t\t.then(\n\t\t\t\t\t\t\t// resume the async loop on\n\t\t\t\t\t\t\t// success, sending the resolved\n\t\t\t\t\t\t\t// value back into the generator\n\t\t\t\t\t\t\thandleNext,\n\n\t\t\t\t\t\t\t// if `value` is a rejected\n\t\t\t\t\t\t\t// promise, propagate error back\n\t\t\t\t\t\t\t// into the generator for its own\n\t\t\t\t\t\t\t// error handling\n\t\t\t\t\t\t\tfunction handleErr(err) {\n\t\t\t\t\t\t\t\treturn Promise.resolve(\n\t\t\t\t\t\t\t\t\tit.throw( err )\n\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t.then( handleResult );\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t})(next);\n\t\t} );\n}\n```\n\nAs you can see, it's a quite a bit more complex than you'd probably want to author yourself, and you especially wouldn't want to repeat this code for each generator you use. So, a utility/library helper is definitely the way to go. Nevertheless, I encourage you to spend a few minutes studying that code listing to get a better sense of how to manage the generator+Promise negotiation.\n\nHow would you use `run(..)` with `*main()` in our *running* Ajax example?\n\n```js\nfunction *main() {\n\t// ..\n}\n\nrun( main );\n```\n\nThat's it! The way we wired `run(..)`, it will automatically advance the generator you pass to it, asynchronously until completion.\n\n**Note:** The `run(..)` we defined returns a promise which is wired to resolve once the generator is complete, or receive an uncaught exception if the generator doesn't handle it. We don't show that capability here, but we'll come back to it later in the chapter.\n\n#### ES7: `async` and `await`?\n\nThe preceding pattern -- generators yielding Promises that then control the generator's *iterator* to advance it to completion -- is such a powerful and useful approach, it would be nicer if we could do it without the clutter of the library utility helper (aka `run(..)`).\n\nThere's probably good news on that front. At the time of this writing, there's early but strong support for a proposal for more syntactic addition in this realm for the post-ES6, ES7-ish timeframe. Obviously, it's too early to guarantee the details, but there's a pretty decent chance it will shake out similar to the following:\n\n```js\nfunction foo(x,y) {\n\treturn request(\n\t\t\"http://some.url.1/?x=\" + x + \"&y=\" + y\n\t);\n}\n\nasync function main() {\n\ttry {\n\t\tvar text = await foo( 11, 31 );\n\t\tconsole.log( text );\n\t}\n\tcatch (err) {\n\t\tconsole.error( err );\n\t}\n}\n\nmain();\n```\n\nAs you can see, there's no `run(..)` call (meaning no need for a library utility!) to invoke and drive `main()` -- it's just called as a normal function. Also, `main()` isn't declared as a generator function anymore; it's a new kind of function: `async function`. And finally, instead of `yield`ing a Promise, we `await` for it to resolve.\n\nThe `async function` automatically knows what to do if you `await` a Promise -- it will pause the function (just like with generators) until the Promise resolves. We didn't illustrate it in this snippet, but calling an async function like `main()` automatically returns a promise that's resolved whenever the function finishes completely.\n\n**Tip:** The `async` / `await` syntax should look very familiar to readers with experience in C#, because it's basically identical.\n\nThe proposal essentially codifies support for the pattern we've already derived, into a syntactic mechanism: combining Promises with sync-looking flow control code. That's the best of both worlds combined, to effectively address practically all of the major concerns we outlined with callbacks.\n\nThe mere fact that such a ES7-ish proposal already exists and has early support and enthusiasm is a major vote of confidence in the future importance of this async pattern.\n\n### Promise Concurrency in Generators\n\nSo far, all we've demonstrated is a single-step async flow with Promises+generators. But real-world code will often have many async steps.\n\nIf you're not careful, the sync-looking style of generators may lull you into complacency with how you structure your async concurrency, leading to suboptimal performance patterns. So we want to spend a little time exploring the options.\n\nImagine a scenario where you need to fetch data from two different sources, then combine those responses to make a third request, and finally print out the last response. We explored a similar scenario with Promises in Chapter 3, but let's reconsider it in the context of generators.\n\nYour first instinct might be something like:\n\n```js\nfunction *foo() {\n\tvar r1 = yield request( \"http://some.url.1\" );\n\tvar r2 = yield request( \"http://some.url.2\" );\n\n\tvar r3 = yield request(\n\t\t\"http://some.url.3/?v=\" + r1 + \",\" + r2\n\t);\n\n\tconsole.log( r3 );\n}\n\n// use previously defined `run(..)` utility\nrun( foo );\n```\n\nThis code will work, but in the specifics of our scenario, it's not optimal. Can you spot why?\n\nBecause the `r1` and `r2` requests can -- and for performance reasons, *should* -- run concurrently, but in this code they will run sequentially; the `\"http://some.url.2\"` URL isn't Ajax fetched until after the `\"http://some.url.1\"` request is finished. These two requests are independent, so the better performance approach would likely be to have them run at the same time.\n\nBut how exactly would you do that with a generator and `yield`? We know that `yield` is only a single pause point in the code, so you can't really do two pauses at the same time.\n\nThe most natural and effective answer is to base the async flow on Promises, specifically on their capability to manage state in a time-independent fashion (see \"Future Value\" in Chapter 3).\n\nThe simplest approach:\n\n```js\nfunction *foo() {\n\t// make both requests \"in parallel\"\n\tvar p1 = request( \"http://some.url.1\" );\n\tvar p2 = request( \"http://some.url.2\" );\n\n\t// wait until both promises resolve\n\tvar r1 = yield p1;\n\tvar r2 = yield p2;\n\n\tvar r3 = yield request(\n\t\t\"http://some.url.3/?v=\" + r1 + \",\" + r2\n\t);\n\n\tconsole.log( r3 );\n}\n\n// use previously defined `run(..)` utility\nrun( foo );\n```\n\nWhy is this different from the previous snippet? Look at where the `yield` is and is not. `p1` and `p2` are promises for Ajax requests made concurrently (aka \"in parallel\"). It doesn't matter which one finishes first, because promises will hold onto their resolved state for as long as necessary.\n\nThen we use two subsequent `yield` statements to wait for and retrieve the resolutions from the promises (into `r1` and `r2`, respectively). If `p1` resolves first, the `yield p1` resumes first then waits on the `yield p2` to resume. If `p2` resolves first, it will just patiently hold onto that resolution value until asked, but the `yield p1` will hold on first, until `p1` resolves.\n\nEither way, both `p1` and `p2` will run concurrently, and both have to finish, in either order, before the `r3 = yield request..` Ajax request will be made.\n\nIf that flow control processing model sounds familiar, it's basically the same as what we identified in Chapter 3 as the \"gate\" pattern, enabled by the `Promise.all([ .. ])` utility. So, we could also express the flow control like this:\n\n```js\nfunction *foo() {\n\t// make both requests \"in parallel,\" and\n\t// wait until both promises resolve\n\tvar results = yield Promise.all( [\n\t\trequest( \"http://some.url.1\" ),\n\t\trequest( \"http://some.url.2\" )\n\t] );\n\n\tvar r1 = results[0];\n\tvar r2 = results[1];\n\n\tvar r3 = yield request(\n\t\t\"http://some.url.3/?v=\" + r1 + \",\" + r2\n\t);\n\n\tconsole.log( r3 );\n}\n\n// use previously defined `run(..)` utility\nrun( foo );\n```\n\n**Note:** As we discussed in Chapter 3, we can even use ES6 destructuring assignment to simplify the `var r1 = .. var r2 = ..` assignments, with `var [r1,r2] = results`.\n\nIn other words, all of the concurrency capabilities of Promises are available to us in the generator+Promise approach. So in any place where you need more than sequential this-then-that async flow control steps, Promises are likely your best bet.\n\n#### Promises, Hidden\n\nAs a word of stylistic caution, be careful about how much Promise logic you include **inside your generators**. The whole point of using generators for asynchrony in the way we've described is to create simple, sequential, sync-looking code, and to hide as much of the details of asynchrony away from that code as possible.\n\nFor example, this might be a cleaner approach:\n\n```js\n// note: normal function, not generator\nfunction bar(url1,url2) {\n\treturn Promise.all( [\n\t\trequest( url1 ),\n\t\trequest( url2 )\n\t] );\n}\n\nfunction *foo() {\n\t// hide the Promise-based concurrency details\n\t// inside `bar(..)`\n\tvar results = yield bar(\n\t\t\"http://some.url.1\",\n\t\t\"http://some.url.2\"\n\t);\n\n\tvar r1 = results[0];\n\tvar r2 = results[1];\n\n\tvar r3 = yield request(\n\t\t\"http://some.url.3/?v=\" + r1 + \",\" + r2\n\t);\n\n\tconsole.log( r3 );\n}\n\n// use previously defined `run(..)` utility\nrun( foo );\n```\n\nInside `*foo()`, it's cleaner and clearer that all we're doing is just asking `bar(..)` to get us some `results`, and we'll `yield`-wait on that to happen. We don't have to care that under the covers a `Promise.all([ .. ])` Promise composition will be used to make that happen.\n\n**We treat asynchrony, and indeed Promises, as an implementation detail.**\n\nHiding your Promise logic inside a function that you merely call from your generator is especially useful if you're going to do a sophisticated series flow-control. For example:\n\n```js\nfunction bar() {\n\treturn\tPromise.all( [\n\t\t baz( .. )\n\t\t .then( .. ),\n\t\t Promise.race( [ .. ] )\n\t\t] )\n\t\t.then( .. )\n}\n```\n\nThat kind of logic is sometimes required, and if you dump it directly inside your generator(s), you've defeated most of the reason why you would want to use generators in the first place. We *should* intentionally abstract such details away from our generator code so that they don't clutter up the higher level task expression.\n\nBeyond creating code that is both functional and performant, you should also strive to make code that is as reason-able and maintainable as possible.\n\n**Note:** Abstraction is not *always* a healthy thing for programming -- many times it can increase complexity in exchange for terseness. But in this case, I believe it's much healthier for your generator+Promise async code than the alternatives. As with all such advice, though, pay attention to your specific situations and make proper decisions for you and your team.\n\n## Generator Delegation\n\nIn the previous section, we showed calling regular functions from inside a generator, and how that remains a useful technique for abstracting away implementation details (like async Promise flow). But the main drawback of using a normal function for this task is that it has to behave by the normal function rules, which means it cannot pause itself with `yield` like a generator can.\n\nIt may then occur to you that you might try to call one generator from another generator, using our `run(..)` helper, such as:\n\n```js\nfunction *foo() {\n\tvar r2 = yield request( \"http://some.url.2\" );\n\tvar r3 = yield request( \"http://some.url.3/?v=\" + r2 );\n\n\treturn r3;\n}\n\nfunction *bar() {\n\tvar r1 = yield request( \"http://some.url.1\" );\n\n\t// \"delegating\" to `*foo()` via `run(..)`\n\tvar r3 = yield run( foo );\n\n\tconsole.log( r3 );\n}\n\nrun( bar );\n```\n\nWe run `*foo()` inside of `*bar()` by using our `run(..)` utility again. We take advantage here of the fact that the `run(..)` we defined earlier returns a promise which is resolved when its generator is run to completion (or errors out), so if we `yield` out to a `run(..)` instance the promise from another `run(..)` call, it automatically pauses `*bar()` until `*foo()` finishes.\n\nBut there's an even better way to integrate calling `*foo()` into `*bar()`, and it's called `yield`-delegation. The special syntax for `yield`-delegation is: `yield * __` (notice the extra `*`). Before we see it work in our previous example, let's look at a simpler scenario:\n\n```js\nfunction *foo() {\n\tconsole.log( \"`*foo()` starting\" );\n\tyield 3;\n\tyield 4;\n\tconsole.log( \"`*foo()` finished\" );\n}\n\nfunction *bar() {\n\tyield 1;\n\tyield 2;\n\tyield *foo();\t// `yield`-delegation!\n\tyield 5;\n}\n\nvar it = bar();\n\nit.next().value;\t// 1\nit.next().value;\t// 2\nit.next().value;\t// `*foo()` starting\n\t\t\t\t\t// 3\nit.next().value;\t// 4\nit.next().value;\t// `*foo()` finished\n\t\t\t\t\t// 5\n```\n\n**Note:** Similar to a note earlier in the chapter where I explained why I prefer `function *foo() ..` instead of `function* foo() ..`, I also prefer -- differing from most other documentation on the topic -- to say `yield *foo()` instead of `yield* foo()`. The placement of the `*` is purely stylistic and up to your best judgment. But I find the consistency of styling attractive.\n\nHow does the `yield *foo()` delegation work?\n\nFirst, calling `foo()` creates an *iterator* exactly as we've already seen. Then, `yield *` delegates/transfers the *iterator* instance control (of the present `*bar()` generator) over to this other `*foo()` *iterator*.\n\nSo, the first two `it.next()` calls are controlling `*bar()`, but when we make the third `it.next()` call, now `*foo()` starts up, and now we're controlling `*foo()` instead of `*bar()`. That's why it's called delegation -- `*bar()` delegated its iteration control to `*foo()`.\n\nAs soon as the `it` *iterator* control exhausts the entire `*foo()` *iterator*, it automatically returns to controlling `*bar()`.\n\nSo now back to the previous example with the three sequential Ajax requests:\n\n```js\nfunction *foo() {\n\tvar r2 = yield request( \"http://some.url.2\" );\n\tvar r3 = yield request( \"http://some.url.3/?v=\" + r2 );\n\n\treturn r3;\n}\n\nfunction *bar() {\n\tvar r1 = yield request( \"http://some.url.1\" );\n\n\t// \"delegating\" to `*foo()` via `yield*`\n\tvar r3 = yield *foo();\n\n\tconsole.log( r3 );\n}\n\nrun( bar );\n```\n\nThe only difference between this snippet and the version used earlier is the use of `yield *foo()` instead of the previous `yield run(foo)`.\n\n**Note:** `yield *` yields iteration control, not generator control; when you invoke the `*foo()` generator, you're now `yield`-delegating to its *iterator*. But you can actually `yield`-delegate to any *iterable*; `yield *[1,2,3]` would consume the default *iterator* for the `[1,2,3]` array value.\n\n### Why Delegation?\n\nThe purpose of `yield`-delegation is mostly code organization, and in that way is symmetrical with normal function calling.\n\nImagine two modules that respectively provide methods `foo()` and `bar()`, where `bar()` calls `foo()`. The reason the two are separate is generally because the proper organization of code for the program calls for them to be in separate functions. For example, there may be cases where `foo()` is called standalone, and other places where `bar()` calls `foo()`.\n\nFor all these exact same reasons, keeping generators separate aids in program readability, maintenance, and debuggability. In that respect, `yield *` is a syntactic shortcut for manually iterating over the steps of `*foo()` while inside of `*bar()`.\n\nSuch manual approach would be especially complex if the steps in `*foo()` were asynchronous, which is why you'd probably need to use that `run(..)` utility to do it. And as we've shown, `yield *foo()` eliminates the need for a sub-instance of the `run(..)` utility (like `run(foo)`).\n\n### Delegating Messages\n\nYou may wonder how this `yield`-delegation works not just with *iterator* control but with the two-way message passing. Carefully follow the flow of messages in and out, through the `yield`-delegation:\n\n```js\nfunction *foo() {\n\tconsole.log( \"inside `*foo()`:\", yield \"B\" );\n\n\tconsole.log( \"inside `*foo()`:\", yield \"C\" );\n\n\treturn \"D\";\n}\n\nfunction *bar() {\n\tconsole.log( \"inside `*bar()`:\", yield \"A\" );\n\n\t// `yield`-delegation!\n\tconsole.log( \"inside `*bar()`:\", yield *foo() );\n\n\tconsole.log( \"inside `*bar()`:\", yield \"E\" );\n\n\treturn \"F\";\n}\n\nvar it = bar();\n\nconsole.log( \"outside:\", it.next().value );\n// outside: A\n\nconsole.log( \"outside:\", it.next( 1 ).value );\n// inside `*bar()`: 1\n// outside: B\n\nconsole.log( \"outside:\", it.next( 2 ).value );\n// inside `*foo()`: 2\n// outside: C\n\nconsole.log( \"outside:\", it.next( 3 ).value );\n// inside `*foo()`: 3\n// inside `*bar()`: D\n// outside: E\n\nconsole.log( \"outside:\", it.next( 4 ).value );\n// inside `*bar()`: 4\n// outside: F\n```\n\nPay particular attention to the processing steps after the `it.next(3)` call:\n\n1. The `3` value is passed (through the `yield`-delegation in `*bar()`) into the waiting `yield \"C\"` expression inside of `*foo()`.\n2. `*foo()` then calls `return \"D\"`, but this value doesn't get returned all the way back to the outside `it.next(3)` call.\n3. Instead, the `\"D\"` value is sent as the result of the waiting `yield *foo()` expression inside of `*bar()` -- this `yield`-delegation expression has essentially been paused while all of `*foo()` was exhausted. So `\"D\"` ends up inside of `*bar()` for it to print out.\n4. `yield \"E\"` is called inside of `*bar()`, and the `\"E\"` value is yielded to the outside as the result of the `it.next(3)` call.\n\nFrom the perspective of the external *iterator* (`it`), it doesn't appear any differently between controlling the initial generator or a delegated one.\n\nIn fact, `yield`-delegation doesn't even have to be directed to another generator; it can just be directed to a non-generator, general *iterable*. For example:\n\n```js\nfunction *bar() {\n\tconsole.log( \"inside `*bar()`:\", yield \"A\" );\n\n\t// `yield`-delegation to a non-generator!\n\tconsole.log( \"inside `*bar()`:\", yield *[ \"B\", \"C\", \"D\" ] );\n\n\tconsole.log( \"inside `*bar()`:\", yield \"E\" );\n\n\treturn \"F\";\n}\n\nvar it = bar();\n\nconsole.log( \"outside:\", it.next().value );\n// outside: A\n\nconsole.log( \"outside:\", it.next( 1 ).value );\n// inside `*bar()`: 1\n// outside: B\n\nconsole.log( \"outside:\", it.next( 2 ).value );\n// outside: C\n\nconsole.log( \"outside:\", it.next( 3 ).value );\n// outside: D\n\nconsole.log( \"outside:\", it.next( 4 ).value );\n// inside `*bar()`: undefined\n// outside: E\n\nconsole.log( \"outside:\", it.next( 5 ).value );\n// inside `*bar()`: 5\n// outside: F\n```\n\nNotice the differences in where the messages were received/reported between this example and the one previous.\n\nMost strikingly, the default `array` *iterator* doesn't care about any messages sent in via `next(..)` calls, so the values `2`, `3`, and `4` are essentially ignored. Also, because that *iterator* has no explicit `return` value (unlike the previously used `*foo()`), the `yield *` expression gets an `undefined` when it finishes.\n\n#### Exceptions Delegated, Too!\n\nIn the same way that `yield`-delegation transparently passes messages through in both directions, errors/exceptions also pass in both directions:\n\n```js\nfunction *foo() {\n\ttry {\n\t\tyield \"B\";\n\t}\n\tcatch (err) {\n\t\tconsole.log( \"error caught inside `*foo()`:\", err );\n\t}\n\n\tyield \"C\";\n\n\tthrow \"D\";\n}\n\nfunction *bar() {\n\tyield \"A\";\n\n\ttry {\n\t\tyield *foo();\n\t}\n\tcatch (err) {\n\t\tconsole.log( \"error caught inside `*bar()`:\", err );\n\t}\n\n\tyield \"E\";\n\n\tyield *baz();\n\n\t// note: can't get here!\n\tyield \"G\";\n}\n\nfunction *baz() {\n\tthrow \"F\";\n}\n\nvar it = bar();\n\nconsole.log( \"outside:\", it.next().value );\n// outside: A\n\nconsole.log( \"outside:\", it.next( 1 ).value );\n// outside: B\n\nconsole.log( \"outside:\", it.throw( 2 ).value );\n// error caught inside `*foo()`: 2\n// outside: C\n\nconsole.log( \"outside:\", it.next( 3 ).value );\n// error caught inside `*bar()`: D\n// outside: E\n\ntry {\n\tconsole.log( \"outside:\", it.next( 4 ).value );\n}\ncatch (err) {\n\tconsole.log( \"error caught outside:\", err );\n}\n// error caught outside: F\n```\n\nSome things to note from this snippet:\n\n1. When we call `it.throw(2)`, it sends the error message `2` into `*bar()`, which delegates that to `*foo()`, which then `catch`es it and handles it gracefully. Then, the `yield \"C\"` sends `\"C\"` back out as the return `value` from the `it.throw(2)` call.\n2. The `\"D\"` value that's next `throw`n from inside `*foo()` propagates out to `*bar()`, which `catch`es it and handles it gracefully. Then the `yield \"E\"` sends `\"E\"` back out as the return `value` from the `it.next(3)` call.\n3. Next, the exception `throw`n from `*baz()` isn't caught in `*bar()` -- though we did `catch` it outside -- so both `*baz()` and `*bar()` are set to a completed state. After this snippet, you would not be able to get the `\"G\"` value out with any subsequent `next(..)` call(s) -- they will just return `undefined` for `value`.\n\n### Delegating Asynchrony\n\nLet's finally get back to our earlier `yield`-delegation example with the multiple sequential Ajax requests:\n\n```js\nfunction *foo() {\n\tvar r2 = yield request( \"http://some.url.2\" );\n\tvar r3 = yield request( \"http://some.url.3/?v=\" + r2 );\n\n\treturn r3;\n}\n\nfunction *bar() {\n\tvar r1 = yield request( \"http://some.url.1\" );\n\n\tvar r3 = yield *foo();\n\n\tconsole.log( r3 );\n}\n\nrun( bar );\n```\n\nInstead of calling `yield run(foo)` inside of `*bar()`, we just call `yield *foo()`.\n\nIn the previous version of this example, the Promise mechanism (controlled by `run(..)`) was used to transport the value from `return r3` in `*foo()` to the local variable `r3` inside `*bar()`. Now, that value is just returned back directly via the `yield *` mechanics.\n\nOtherwise, the behavior is pretty much identical.\n\n### Delegating \"Recursion\"\n\nOf course, `yield`-delegation can keep following as many delegation steps as you wire up. You could even use `yield`-delegation for async-capable generator \"recursion\" -- a generator `yield`-delegating to itself:\n\n```js\nfunction *foo(val) {\n\tif (val > 1) {\n\t\t// generator recursion\n\t\tval = yield *foo( val - 1 );\n\t}\n\n\treturn yield request( \"http://some.url/?v=\" + val );\n}\n\nfunction *bar() {\n\tvar r1 = yield *foo( 3 );\n\tconsole.log( r1 );\n}\n\nrun( bar );\n```\n\n**Note:** Our `run(..)` utility could have been called with `run( foo, 3 )`, because it supports additional parameters being passed along to the initialization of the generator. However, we used a parameter-free `*bar()` here to highlight the flexibility of `yield *`.\n\nWhat processing steps follow from that code? Hang on, this is going to be quite intricate to describe in detail:\n\n1. `run(bar)` starts up the `*bar()` generator.\n2. `foo(3)` creates an *iterator* for `*foo(..)` and passes `3` as its `val` parameter.\n3. Because `3 > 1`, `foo(2)` creates another *iterator* and passes in `2` as its `val` parameter.\n4. Because `2 > 1`, `foo(1)` creates yet another *iterator* and passes in `1` as its `val` parameter.\n5. `1 > 1` is `false`, so we next call `request(..)` with the `1` value, and get a promise back for that first Ajax call.\n6. That promise is `yield`ed out, which comes back to the `*foo(2)` generator instance.\n7. The `yield *` passes that promise back out to the `*foo(3)` generator instance. Another `yield *` passes the promise out to the `*bar()` generator instance. And yet again another `yield *` passes the promise out to the `run(..)` utility, which will wait on that promise (for the first Ajax request) to proceed.\n8. When the promise resolves, its fulfillment message is sent to resume `*bar()`, which passes through the `yield *` into the `*foo(3)` instance, which then passes through the `yield *` to the `*foo(2)` generator instance, which then passes through the `yield *` to the normal `yield` that's waiting in the `*foo(3)` generator instance.\n9. That first call's Ajax response is now immediately `return`ed from the `*foo(3)` generator instance, which sends that value back as the result of the `yield *` expression in the `*foo(2)` instance, and assigned to its local `val` variable.\n10. Inside `*foo(2)`, a second Ajax request is made with `request(..)`, whose promise is `yield`ed back to the `*foo(1)` instance, and then `yield *` propagates all the way out to `run(..)` (step 7 again). When the promise resolves, the second Ajax response propagates all the way back into the `*foo(2)` generator instance, and is assigned to its local `val` variable.\n11. Finally, the third Ajax request is made with `request(..)`, its promise goes out to `run(..)`, and then its resolution value comes all the way back, which is then `return`ed so that it comes back to the waiting `yield *` expression in `*bar()`.\n\nPhew! A lot of crazy mental juggling, huh? You might want to read through that a few more times, and then go grab a snack to clear your head!\n\n## Generator Concurrency\n\nAs we discussed in both Chapter 1 and earlier in this chapter, two simultaneously running \"processes\" can cooperatively interleave their operations, and many times this can *yield* (pun intended) very powerful asynchrony expressions.\n\nFrankly, our earlier examples of concurrency interleaving of multiple generators showed how to make it really confusing. But we hinted that there's places where this capability is quite useful.\n\nRecall a scenario we looked at in Chapter 1, where two different simultaneous Ajax response handlers needed to coordinate with each other to make sure that the data communication was not a race condition. We slotted the responses into the `res` array like this:\n\n```js\nfunction response(data) {\n\tif (data.url == \"http://some.url.1\") {\n\t\tres[0] = data;\n\t}\n\telse if (data.url == \"http://some.url.2\") {\n\t\tres[1] = data;\n\t}\n}\n```\n\nBut how can we use multiple generators concurrently for this scenario?\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nvar res = [];\n\nfunction *reqData(url) {\n\tres.push(\n\t\tyield request( url )\n\t);\n}\n```\n\n**Note:** We're going to use two instances of the `*reqData(..)` generator here, but there's no difference to running a single instance of two different generators; both approaches are reasoned about identically. We'll see two different generators coordinating in just a bit.\n\nInstead of having to manually sort out `res[0]` and `res[1]` assignments, we'll use coordinated ordering so that `res.push(..)` properly slots the values in the expected and predictable order. The expressed logic thus should feel a bit cleaner.\n\nBut how will we actually orchestrate this interaction? First, let's just do it manually, with Promises:\n\n```js\nvar it1 = reqData( \"http://some.url.1\" );\nvar it2 = reqData( \"http://some.url.2\" );\n\nvar p1 = it1.next().value;\nvar p2 = it2.next().value;\n\np1\n.then( function(data){\n\tit1.next( data );\n\treturn p2;\n} )\n.then( function(data){\n\tit2.next( data );\n} );\n```\n\n`*reqData(..)`'s two instances are both started to make their Ajax requests, then paused with `yield`. Then we choose to resume the first instance when `p1` resolves, and then `p2`'s resolution will restart the second instance. In this way, we use Promise orchestration to ensure that `res[0]` will have the first response and `res[1]` will have the second response.\n\nBut frankly, this is awfully manual, and it doesn't really let the generators orchestrate themselves, which is where the true power can lie. Let's try it a different way:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nvar res = [];\n\nfunction *reqData(url) {\n\tvar data = yield request( url );\n\n\t// transfer control\n\tyield;\n\n\tres.push( data );\n}\n\nvar it1 = reqData( \"http://some.url.1\" );\nvar it2 = reqData( \"http://some.url.2\" );\n\nvar p1 = it1.next().value;\nvar p2 = it2.next().value;\n\np1.then( function(data){\n\tit1.next( data );\n} );\n\np2.then( function(data){\n\tit2.next( data );\n} );\n\nPromise.all( [p1,p2] )\n.then( function(){\n\tit1.next();\n\tit2.next();\n} );\n```\n\nOK, this is a bit better (though still manual!), because now the two instances of `*reqData(..)` run truly concurrently, and (at least for the first part) independently.\n\nIn the previous snippet, the second instance was not given its data until after the first instance was totally finished. But here, both instances receive their data as soon as their respective responses come back, and then each instance does another `yield` for control transfer purposes. We then choose what order to resume them in the `Promise.all([ .. ])` handler.\n\nWhat may not be as obvious is that this approach hints at an easier form for a reusable utility, because of the symmetry. We can do even better. Let's imagine using a utility called `runAll(..)`:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nvar res = [];\n\nrunAll(\n\tfunction*(){\n\t\tvar p1 = request( \"http://some.url.1\" );\n\n\t\t// transfer control\n\t\tyield;\n\n\t\tres.push( yield p1 );\n\t},\n\tfunction*(){\n\t\tvar p2 = request( \"http://some.url.2\" );\n\n\t\t// transfer control\n\t\tyield;\n\n\t\tres.push( yield p2 );\n\t}\n);\n```\n\n**Note:** We're not including a code listing for `runAll(..)` as it is not only long enough to bog down the text, but is an extension of the logic we've already implemented in `run(..)` earlier. So, as a good supplementary exercise for the reader, try your hand at evolving the code from `run(..)` to work like the imagined `runAll(..)`. Also, my *asynquence* library provides a previously mentioned `runner(..)` utility with this kind of capability already built in, and will be discussed in Appendix A of this book.\n\nHere's how the processing inside `runAll(..)` would operate:\n\n1. The first generator gets a promise for the first Ajax response from `\"http://some.url.1\"`, then `yield`s control back to the `runAll(..)` utility.\n2. The second generator runs and does the same for `\"http://some.url.2\"`, `yield`ing control back to the `runAll(..)` utility.\n3. The first generator resumes, and then `yield`s out its promise `p1`. The `runAll(..)` utility does the same in this case as our previous `run(..)`, in that it waits on that promise to resolve, then resumes the same generator (no control transfer!). When `p1` resolves, `runAll(..)` resumes the first generator again with that resolution value, and then `res[0]` is given its value. When the first generator then finishes, that's an implicit transfer of control.\n4. The second generator resumes, `yield`s out its promise `p2`, and waits for it to resolve. Once it does, `runAll(..)` resumes the second generator with that value, and `res[1]` is set.\n\nIn this running example, we use an outer variable called `res` to store the results of the two different Ajax responses -- that's our concurrency coordination making that possible.\n\nBut it might be quite helpful to further extend `runAll(..)` to provide an inner variable space for the multiple generator instances to *share*, such as an empty object we'll call `data` below. Also, it could take non-Promise values that are `yield`ed and hand them off to the next generator.\n\nConsider:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nrunAll(\n\tfunction*(data){\n\t\tdata.res = [];\n\n\t\t// transfer control (and message pass)\n\t\tvar url1 = yield \"http://some.url.2\";\n\n\t\tvar p1 = request( url1 ); // \"http://some.url.1\"\n\n\t\t// transfer control\n\t\tyield;\n\n\t\tdata.res.push( yield p1 );\n\t},\n\tfunction*(data){\n\t\t// transfer control (and message pass)\n\t\tvar url2 = yield \"http://some.url.1\";\n\n\t\tvar p2 = request( url2 ); // \"http://some.url.2\"\n\n\t\t// transfer control\n\t\tyield;\n\n\t\tdata.res.push( yield p2 );\n\t}\n);\n```\n\nIn this formulation, the two generators are not just coordinating control transfer, but actually communicating with each other, both through `data.res` and the `yield`ed messages that trade `url1` and `url2` values. That's incredibly powerful!\n\nSuch realization also serves as a conceptual base for a more sophisticated asynchrony technique called CSP (Communicating Sequential Processes), which we will cover in Appendix B of this book.\n\n## Thunks\n\nSo far, we've made the assumption that `yield`ing a Promise from a generator -- and having that Promise resume the generator via a helper utility like `run(..)` -- was the best possible way to manage asynchrony with generators. To be clear, it is.\n\nBut we skipped over another pattern that has some mildly widespread adoption, so in the interest of completeness we'll take a brief look at it.\n\nIn general computer science, there's an old pre-JS concept called a \"thunk.\" Without getting bogged down in the historical nature, a narrow expression of a thunk in JS is a function that -- without any parameters -- is wired to call another function.\n\nIn other words, you wrap a function definition around function call -- with any parameters it needs -- to *defer* the execution of that call, and that wrapping function is a thunk. When you later execute the thunk, you end up calling the original function.\n\nFor example:\n\n```js\nfunction foo(x,y) {\n\treturn x + y;\n}\n\nfunction fooThunk() {\n\treturn foo( 3, 4 );\n}\n\n// later\n\nconsole.log( fooThunk() );\t// 7\n```\n\nSo, a synchronous thunk is pretty straightforward. But what about an async thunk? We can essentially extend the narrow thunk definition to include it receiving a callback.\n\nConsider:\n\n```js\nfunction foo(x,y,cb) {\n\tsetTimeout( function(){\n\t\tcb( x + y );\n\t}, 1000 );\n}\n\nfunction fooThunk(cb) {\n\tfoo( 3, 4, cb );\n}\n\n// later\n\nfooThunk( function(sum){\n\tconsole.log( sum );\t\t// 7\n} );\n```\n\nAs you can see, `fooThunk(..)` only expects a `cb(..)` parameter, as it already has values `3` and `4` (for `x` and `y`, respectively) pre-specified and ready to pass to `foo(..)`. A thunk is just waiting around patiently for the last piece it needs to do its job: the callback.\n\nYou don't want to make thunks manually, though. So, let's invent a utility that does this wrapping for us.\n\nConsider:\n\n```js\nfunction thunkify(fn) {\n\tvar args = [].slice.call( arguments, 1 );\n\treturn function(cb) {\n\t\targs.push( cb );\n\t\treturn fn.apply( null, args );\n\t};\n}\n\nvar fooThunk = thunkify( foo, 3, 4 );\n\n// later\n\nfooThunk( function(sum) {\n\tconsole.log( sum );\t\t// 7\n} );\n```\n\n**Tip:** Here we assume that the original (`foo(..)`) function signature expects its callback in the last position, with any other parameters coming before it. This is a pretty ubiquitous \"standard\" for async JS function standards. You might call it \"callback-last style.\" If for some reason you had a need to handle \"callback-first style\" signatures, you would just make a utility that used `args.unshift(..)` instead of `args.push(..)`.\n\nThe preceding formulation of `thunkify(..)` takes both the `foo(..)` function reference, and any parameters it needs, and returns back the thunk itself (`fooThunk(..)`). However, that's not the typical approach you'll find to thunks in JS.\n\nInstead of `thunkify(..)` making the thunk itself, typically -- if not perplexingly -- the `thunkify(..)` utility would produce a function that produces thunks.\n\nUhhhh... yeah.\n\nConsider:\n\n```js\nfunction thunkify(fn) {\n\treturn function() {\n\t\tvar args = [].slice.call( arguments );\n\t\treturn function(cb) {\n\t\t\targs.push( cb );\n\t\t\treturn fn.apply( null, args );\n\t\t};\n\t};\n}\n```\n\nThe main difference here is the extra `return function() { .. }` layer. Here's how its usage differs:\n\n```js\nvar whatIsThis = thunkify( foo );\n\nvar fooThunk = whatIsThis( 3, 4 );\n\n// later\n\nfooThunk( function(sum) {\n\tconsole.log( sum );\t\t// 7\n} );\n```\n\nObviously, the big question this snippet implies is what is `whatIsThis` properly called? It's not the thunk, it's the thing that will produce thunks from `foo(..)` calls. It's kind of like a \"factory\" for \"thunks.\" There doesn't seem to be any kind of standard agreement for naming such a thing.\n\nSo, my proposal is \"thunkory\" (\"thunk\" + \"factory\"). So, `thunkify(..)` produces a thunkory, and a thunkory produces thunks. That reasoning is symmetric to my proposal for \"promisory\" in Chapter 3:\n\n```js\nvar fooThunkory = thunkify( foo );\n\nvar fooThunk1 = fooThunkory( 3, 4 );\nvar fooThunk2 = fooThunkory( 5, 6 );\n\n// later\n\nfooThunk1( function(sum) {\n\tconsole.log( sum );\t\t// 7\n} );\n\nfooThunk2( function(sum) {\n\tconsole.log( sum );\t\t// 11\n} );\n```\n\n**Note:** The running `foo(..)` example expects a style of callback that's not \"error-first style.\" Of course, \"error-first style\" is much more common. If `foo(..)` had some sort of legitimate error-producing expectation, we could change it to expect and use an error-first callback. None of the subsequent `thunkify(..)` machinery cares what style of callback is assumed. The only difference in usage would be `fooThunk1(function(err,sum){..`.\n\nExposing the thunkory method -- instead of how the earlier `thunkify(..)` hides this intermediary step -- may seem like unnecessary complication. But in general, it's quite useful to make thunkories at the beginning of your program to wrap existing API methods, and then be able to pass around and call those thunkories when you need thunks. The two distinct steps preserve a cleaner separation of capability.\n\nTo illustrate:\n\n```js\n// cleaner:\nvar fooThunkory = thunkify( foo );\n\nvar fooThunk1 = fooThunkory( 3, 4 );\nvar fooThunk2 = fooThunkory( 5, 6 );\n\n// instead of:\nvar fooThunk1 = thunkify( foo, 3, 4 );\nvar fooThunk2 = thunkify( foo, 5, 6 );\n```\n\nRegardless of whether you like to deal with the thunkories explicitly or not, the usage of thunks `fooThunk1(..)` and `fooThunk2(..)` remains the same.\n\n### s/promise/thunk/\n\nSo what's all this thunk stuff have to do with generators?\n\nComparing thunks to promises generally: they're not directly interchangable as they're not equivalent in behavior. Promises are vastly more capable and trustable than bare thunks.\n\nBut in another sense, they both can be seen as a request for a value, which may be async in its answering.\n\nRecall from Chapter 3 we defined a utility for promisifying a function, which we called `Promise.wrap(..)` -- we could have called it `promisify(..)`, too! This Promise-wrapping utility doesn't produce Promises; it produces promisories that in turn produce Promises. This is completely symmetric to the thunkories and thunks presently being discussed.\n\nTo illustrate the symmetry, let's first alter the running `foo(..)` example from earlier to assume an \"error-first style\" callback:\n\n```js\nfunction foo(x,y,cb) {\n\tsetTimeout( function(){\n\t\t// assume `cb(..)` as \"error-first style\"\n\t\tcb( null, x + y );\n\t}, 1000 );\n}\n```\n\nNow, we'll compare using `thunkify(..)` and `promisify(..)` (aka `Promise.wrap(..)` from Chapter 3):\n\n```js\n// symmetrical: constructing the question asker\nvar fooThunkory = thunkify( foo );\nvar fooPromisory = promisify( foo );\n\n// symmetrical: asking the question\nvar fooThunk = fooThunkory( 3, 4 );\nvar fooPromise = fooPromisory( 3, 4 );\n\n// get the thunk answer\nfooThunk( function(err,sum){\n\tif (err) {\n\t\tconsole.error( err );\n\t}\n\telse {\n\t\tconsole.log( sum );\t\t// 7\n\t}\n} );\n\n// get the promise answer\nfooPromise\n.then(\n\tfunction(sum){\n\t\tconsole.log( sum );\t\t// 7\n\t},\n\tfunction(err){\n\t\tconsole.error( err );\n\t}\n);\n```\n\nBoth the thunkory and the promisory are essentially asking a question (for a value), and respectively the thunk `fooThunk` and promise `fooPromise` represent the future answers to that question. Presented in that light, the symmetry is clear.\n\nWith that perspective in mind, we can see that generators which `yield` Promises for asynchrony could instead `yield` thunks for asynchrony. All we'd need is a smarter `run(..)` utility (like from before) that can not only look for and wire up to a `yield`ed Promise but also to provide a callback to a `yield`ed thunk.\n\nConsider:\n\n```js\nfunction *foo() {\n\tvar val = yield request( \"http://some.url.1\" );\n\tconsole.log( val );\n}\n\nrun( foo );\n```\n\nIn this example, `request(..)` could either be a promisory that returns a promise, or a thunkory that returns a thunk. From the perspective of what's going on inside the generator code logic, we don't care about that implementation detail, which is quite powerful!\n\nSo, `request(..)` could be either:\n\n```js\n// promisory `request(..)` (see Chapter 3)\nvar request = Promise.wrap( ajax );\n\n// vs.\n\n// thunkory `request(..)`\nvar request = thunkify( ajax );\n```\n\nFinally, as a thunk-aware patch to our earlier `run(..)` utility, we would need logic like this:\n\n```js\n// ..\n// did we receive a thunk back?\nelse if (typeof next.value == \"function\") {\n\treturn new Promise( function(resolve,reject){\n\t\t// call the thunk with an error-first callback\n\t\tnext.value( function(err,msg) {\n\t\t\tif (err) {\n\t\t\t\treject( err );\n\t\t\t}\n\t\t\telse {\n\t\t\t\tresolve( msg );\n\t\t\t}\n\t\t} );\n\t} )\n\t.then(\n\t\thandleNext,\n\t\tfunction handleErr(err) {\n\t\t\treturn Promise.resolve(\n\t\t\t\tit.throw( err )\n\t\t\t)\n\t\t\t.then( handleResult );\n\t\t}\n\t);\n}\n```\n\nNow, our generators can either call promisories to `yield` Promises, or call thunkories to `yield` thunks, and in either case, `run(..)` would handle that value and use it to wait for the completion to resume the generator.\n\nSymmetry wise, these two approaches look identical. However, we should point out that's true only from the perspective of Promises or thunks representing the future value continuation of a generator.\n\nFrom the larger perspective, thunks do not in and of themselves have hardly any of the trustability or composability guarantees that Promises are designed with. Using a thunk as a stand-in for a Promise in this particular generator asynchrony pattern is workable but should be seen as less than ideal when compared to all the benefits that Promises offer (see Chapter 3).\n\nIf you have the option, prefer `yield pr` rather than `yield th`. But there's nothing wrong with having a `run(..)` utility which can handle both value types.\n\n**Note:** The `runner(..)` utility in my *asynquence* library, which will be discussed in Appendix A, handles `yield`s of Promises, thunks and *asynquence* sequences.\n\n## Pre-ES6 Generators\n\nYou're hopefully convinced now that generators are a very important addition to the async programming toolbox. But it's a new syntax in ES6, which means you can't just polyfill generators like you can Promises (which are just a new API). So what can we do to bring generators to our browser JS if we don't have the luxury of ignoring pre-ES6 browsers?\n\nFor all new syntax extensions in ES6, there are tools -- the most common term for them is transpilers, for trans-compilers -- which can take your ES6 syntax and transform it into equivalent (but obviously uglier!) pre-ES6 code. So, generators can be transpiled into code that will have the same behavior but work in ES5 and below.\n\nBut how? The \"magic\" of `yield` doesn't obviously sound like code that's easy to transpile. We actually hinted at a solution in our earlier discussion of closure-based *iterators*.\n\n### Manual Transformation\n\nBefore we discuss the transpilers, let's derive how manual transpilation would work in the case of generators. This isn't just an academic exercise, because doing so will actually help further reinforce how they work.\n\nConsider:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nfunction *foo(url) {\n\ttry {\n\t\tconsole.log( \"requesting:\", url );\n\t\tvar val = yield request( url );\n\t\tconsole.log( val );\n\t}\n\tcatch (err) {\n\t\tconsole.log( \"Oops:\", err );\n\t\treturn false;\n\t}\n}\n\nvar it = foo( \"http://some.url.1\" );\n```\n\nThe first thing to observe is that we'll still need a normal `foo()` function that can be called, and it will still need to return an *iterator*. So, let's sketch out the non-generator transformation:\n\n```js\nfunction foo(url) {\n\n\t// ..\n\n\t// make and return an iterator\n\treturn {\n\t\tnext: function(v) {\n\t\t\t// ..\n\t\t},\n\t\tthrow: function(e) {\n\t\t\t// ..\n\t\t}\n\t};\n}\n\nvar it = foo( \"http://some.url.1\" );\n```\n\nThe next thing to observe is that a generator does its \"magic\" by suspending its scope/state, but we can emulate that with function closure (see the *Scope & Closures* title of this series). To understand how to write such code, we'll first annotate different parts of our generator with state values:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nfunction *foo(url) {\n\t// STATE *1*\n\n\ttry {\n\t\tconsole.log( \"requesting:\", url );\n\t\tvar TMP1 = request( url );\n\n\t\t// STATE *2*\n\t\tvar val = yield TMP1;\n\t\tconsole.log( val );\n\t}\n\tcatch (err) {\n\t\t// STATE *3*\n\t\tconsole.log( \"Oops:\", err );\n\t\treturn false;\n\t}\n}\n```\n\n**Note:** For more accurate illustration, we split up the `val = yield request..` statement into two parts, using the temporary `TMP1` variable. `request(..)` happens in state `*1*`, and the assignment of its completion value to `val` happens in state `*2*`. We'll get rid of that intermediate `TMP1` when we convert the code to its non-generator equivalent.\n\nIn other words, `*1*` is the beginning state, `*2*` is the state if the `request(..)` succeeds, and `*3*` is the state if the `request(..)` fails. You can probably imagine how any extra `yield` steps would just be encoded as extra states.\n\nBack to our transpiled generator, let's define a variable `state` in the closure we can use to keep track of the state:\n\n```js\nfunction foo(url) {\n\t// manage generator state\n\tvar state;\n\n\t// ..\n}\n```\n\nNow, let's define an inner function called `process(..)` inside the closure which handles each state, using a `switch` statement:\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nfunction foo(url) {\n\t// manage generator state\n\tvar state;\n\n\t// generator-wide variable declarations\n\tvar val;\n\n\tfunction process(v) {\n\t\tswitch (state) {\n\t\t\tcase 1:\n\t\t\t\tconsole.log( \"requesting:\", url );\n\t\t\t\treturn request( url );\n\t\t\tcase 2:\n\t\t\t\tval = v;\n\t\t\t\tconsole.log( val );\n\t\t\t\treturn;\n\t\t\tcase 3:\n\t\t\t\tvar err = v;\n\t\t\t\tconsole.log( \"Oops:\", err );\n\t\t\t\treturn false;\n\t\t}\n\t}\n\n\t// ..\n}\n```\n\nEach state in our generator is represented by its own `case` in the `switch` statement. `process(..)` will be called each time we need to process a new state. We'll come back to how that works in just a moment.\n\nFor any generator-wide variable declarations (`val`), we move those to a `var` declaration outside of `process(..)` so they can survive multiple calls to `process(..)`. But the \"block scoped\" `err` variable is only needed for the `*3*` state, so we leave it in place.\n\nIn state `*1*`, instead of `yield request(..)`, we did `return request(..)`. In terminal state `*2*`, there was no explicit `return`, so we just do a `return;` which is the same as `return undefined`. In terminal state `*3*`, there was a `return false`, so we preserve that.\n\nNow we need to define the code in the *iterator* functions so they call `process(..)` appropriately:\n\n```js\nfunction foo(url) {\n\t// manage generator state\n\tvar state;\n\n\t// generator-wide variable declarations\n\tvar val;\n\n\tfunction process(v) {\n\t\tswitch (state) {\n\t\t\tcase 1:\n\t\t\t\tconsole.log( \"requesting:\", url );\n\t\t\t\treturn request( url );\n\t\t\tcase 2:\n\t\t\t\tval = v;\n\t\t\t\tconsole.log( val );\n\t\t\t\treturn;\n\t\t\tcase 3:\n\t\t\t\tvar err = v;\n\t\t\t\tconsole.log( \"Oops:\", err );\n\t\t\t\treturn false;\n\t\t}\n\t}\n\n\t// make and return an iterator\n\treturn {\n\t\tnext: function(v) {\n\t\t\t// initial state\n\t\t\tif (!state) {\n\t\t\t\tstate = 1;\n\t\t\t\treturn {\n\t\t\t\t\tdone: false,\n\t\t\t\t\tvalue: process()\n\t\t\t\t};\n\t\t\t}\n\t\t\t// yield resumed successfully\n\t\t\telse if (state == 1) {\n\t\t\t\tstate = 2;\n\t\t\t\treturn {\n\t\t\t\t\tdone: true,\n\t\t\t\t\tvalue: process( v )\n\t\t\t\t};\n\t\t\t}\n\t\t\t// generator already completed\n\t\t\telse {\n\t\t\t\treturn {\n\t\t\t\t\tdone: true,\n\t\t\t\t\tvalue: undefined\n\t\t\t\t};\n\t\t\t}\n\t\t},\n\t\t\"throw\": function(e) {\n\t\t\t// the only explicit error handling is in\n\t\t\t// state *1*\n\t\t\tif (state == 1) {\n\t\t\t\tstate = 3;\n\t\t\t\treturn {\n\t\t\t\t\tdone: true,\n\t\t\t\t\tvalue: process( e )\n\t\t\t\t};\n\t\t\t}\n\t\t\t// otherwise, an error won't be handled,\n\t\t\t// so just throw it right back out\n\t\t\telse {\n\t\t\t\tthrow e;\n\t\t\t}\n\t\t}\n\t};\n}\n```\n\nHow does this code work?\n\n1. The first call to the *iterator*'s `next()` call would move the generator from the uninitialized state to state `1`, and then call `process()` to handle that state. The return value from `request(..)`, which is the promise for the Ajax response, is returned back as the `value` property from the `next()` call.\n2. If the Ajax request succeeds, the second call to `next(..)` should send in the Ajax response value, which moves our state to `2`. `process(..)` is again called (this time with the passed in Ajax response value), and the `value` property returned from `next(..)` will be `undefined`.\n3. However, if the Ajax request fails, `throw(..)` should be called with the error, which would move the state from `1` to `3` (instead of `2`). Again `process(..)` is called, this time with the error value. That `case` returns `false`, which is set as the `value` property returned from the `throw(..)` call.\n\nFrom the outside -- that is, interacting only with the *iterator* -- this `foo(..)` normal function works pretty much the same as the `*foo(..)` generator would have worked. So we've effectively \"transpiled\" our ES6 generator to pre-ES6 compatibility!\n\nWe could then manually instantiate our generator and control its iterator -- calling `var it = foo(\"..\")` and `it.next(..)` and such -- or better, we could pass it to our previously defined `run(..)` utility as `run(foo,\"..\")`.\n\n### Automatic Transpilation\n\nThe preceding exercise of manually deriving a transformation of our ES6 generator to pre-ES6 equivalent teaches us how generators work conceptually. But that transformation was really intricate and very non-portable to other generators in our code. It would be quite impractical to do this work by hand, and would completely obviate all the benefit of generators.\n\nBut luckily, several tools already exist that can automatically convert ES6 generators to things like what we derived in the previous section. Not only do they do the heavy lifting work for us, but they also handle several complications that we glossed over.\n\nOne such tool is regenerator (https://facebook.github.io/regenerator/), from the smart folks at Facebook.\n\nIf we use regenerator to transpile our previous generator, here's the code produced (at the time of this writing):\n\n```js\n// `request(..)` is a Promise-aware Ajax utility\n\nvar foo = regeneratorRuntime.mark(function foo(url) {\n var val;\n\n return regeneratorRuntime.wrap(function foo$(context$1$0) {\n while (1) switch (context$1$0.prev = context$1$0.next) {\n case 0:\n context$1$0.prev = 0;\n console.log( \"requesting:\", url );\n context$1$0.next = 4;\n return request( url );\n case 4:\n val = context$1$0.sent;\n console.log( val );\n context$1$0.next = 12;\n break;\n case 8:\n context$1$0.prev = 8;\n context$1$0.t0 = context$1$0.catch(0);\n console.log(\"Oops:\", context$1$0.t0);\n return context$1$0.abrupt(\"return\", false);\n case 12:\n case \"end\":\n return context$1$0.stop();\n }\n }, foo, this, [[0, 8]]);\n});\n```\n\nThere's some obvious similarities here to our manual derivation, such as the `switch` / `case` statements, and we even see `val` pulled out of the closure just as we did.\n\nOf course, one trade-off is that regenerator's transpilation requires a helper library `regeneratorRuntime` that holds all the reusable logic for managing a general generator / *iterator*. A lot of that boilerplate looks different than our version, but even then, the concepts can be seen, like with `context$1$0.next = 4` keeping track of the next state for the generator.\n\nThe main takeaway is that generators are not restricted to only being useful in ES6+ environments. Once you understand the concepts, you can employ them throughout your code, and use tools to transform the code to be compatible with older environments.\n\nThis is more work than just using a `Promise` API polyfill for pre-ES6 Promises, but the effort is totally worth it, because generators are so much better at expressing async flow control in a reason-able, sensible, synchronous-looking, sequential fashion.\n\nOnce you get hooked on generators, you'll never want to go back to the hell of async spaghetti callbacks!\n\n## Review\n\nGenerators are a new ES6 function type that does not run-to-completion like normal functions. Instead, the generator can be paused in mid-completion (entirely preserving its state), and it can later be resumed from where it left off.\n\nThis pause/resume interchange is cooperative rather than preemptive, which means that the generator has the sole capability to pause itself, using the `yield` keyword, and yet the *iterator* that controls the generator has the sole capability (via `next(..)`) to resume the generator.\n\nThe `yield` / `next(..)` duality is not just a control mechanism, it's actually a two-way message passing mechanism. A `yield ..` expression essentially pauses waiting for a value, and the next `next(..)` call passes a value (or implicit `undefined`) back to that paused `yield` expression.\n\nThe key benefit of generators related to async flow control is that the code inside a generator expresses a sequence of steps for the task in a naturally sync/sequential fashion. The trick is that we essentially hide potential asynchrony behind the `yield` keyword -- moving the asynchrony to the code where the generator's *iterator* is controlled.\n\nIn other words, generators preserve a sequential, synchronous, blocking code pattern for async code, which lets our brains reason about the code much more naturally, addressing one of the two key drawbacks of callback-based async.\n"
},
{
"path": "async & performance/ch5.md",
"content": "# You Don't Know JS: Async & Performance\n# Chapter 5: Program Performance\n\nThis book so far has been all about how to leverage asynchrony patterns more effectively. But we haven't directly addressed why asynchrony really matters to JS. The most obvious explicit reason is **performance**.\n\nFor example, if you have two Ajax requests to make, and they're independent, but you need to wait on them both to finish before doing the next task, you have two options for modeling that interaction: serial and concurrent.\n\nYou could make the first request and wait to start the second request until the first finishes. Or, as we've seen both with promises and generators, you could make both requests \"in parallel,\" and express the \"gate\" to wait on both of them before moving on.\n\nClearly, the latter is usually going to be more performant than the former. And better performance generally leads to better user experience.\n\nIt's even possible that asynchrony (interleaved concurrency) can improve just the perception of performance, even if the overall program still takes the same amount of time to complete. User perception of performance is every bit -- if not more! -- as important as actual measurable performance.\n\nWe want to now move beyond localized asynchrony patterns to talk about some bigger picture performance details at the program level.\n\n**Note:** You may be wondering about micro-performance issues like if `a++` or `++a` is faster. We'll look at those sorts of performance details in the next chapter on \"Benchmarking & Tuning.\"\n\n## Web Workers\n\nIf you have processing-intensive tasks but you don't want them to run on the main thread (which may slow down the browser/UI), you might have wished that JavaScript could operate in a multithreaded manner.\n\nIn Chapter 1, we talked in detail about how JavaScript is single threaded. And that's still true. But a single thread isn't the only way to organize the execution of your program.\n\nImagine splitting your program into two pieces, and running one of those pieces on the main UI thread, and running the other piece on an entirely separate thread.\n\nWhat kinds of concerns would such an architecture bring up?\n\nFor one, you'd want to know if running on a separate thread meant that it ran in parallel (on systems with multiple CPUs/cores) such that a long-running process on that second thread would **not** block the main program thread. Otherwise, \"virtual threading\" wouldn't be of much benefit over what we already have in JS with async concurrency.\n\nAnd you'd want to know if these two pieces of the program have access to the same shared scope/resources. If they do, then you have all the questions that multithreaded languages (Java, C++, etc.) deal with, such as needing cooperative or preemptive locking (mutexes, etc.). That's a lot of extra work, and shouldn't be undertaken lightly.\n\nAlternatively, you'd want to know how these two pieces could \"communicate\" if they couldn't share scope/resources.\n\nAll these are great questions to consider as we explore a feature added to the web platform circa HTML5 called \"Web Workers.\" This is a feature of the browser (aka host environment) and actually has almost nothing to do with the JS language itself. That is, JavaScript does not *currently* have any features that support threaded execution.\n\nBut an environment like your browser can easily provide multiple instances of the JavaScript engine, each on its own thread, and let you run a different program in each thread. Each of those separate threaded pieces of your program is called a \"(Web) Worker.\" This type of parallelism is called \"task parallelism,\" as the emphasis is on splitting up chunks of your program to run in parallel.\n\nFrom your main JS program (or another Worker), you instantiate a Worker like so:\n\n```js\nvar w1 = new Worker( \"http://some.url.1/mycoolworker.js\" );\n```\n\nThe URL should point to the location of a JS file (not an HTML page!) which is intended to be loaded into a Worker. The browser will then spin up a separate thread and let that file run as an independent program in that thread.\n\n**Note:** The kind of Worker created with such a URL is called a \"Dedicated Worker.\" But instead of providing a URL to an external file, you can also create an \"Inline Worker\" by providing a Blob URL (another HTML5 feature); essentially it's an inline file stored in a single (binary) value. However, Blobs are beyond the scope of what we'll discuss here.\n\nWorkers do not share any scope or resources with each other or the main program -- that would bring all the nightmares of threaded programming to the forefront -- but instead have a basic event messaging mechanism connecting them.\n\nThe `w1` Worker object is an event listener and trigger, which lets you subscribe to events sent by the Worker as well as send events to the Worker.\n\nHere's how to listen for events (actually, the fixed `\"message\"` event):\n\n```js\nw1.addEventListener( \"message\", function(evt){\n\t// evt.data\n} );\n```\n\nAnd you can send the `\"message\"` event to the Worker:\n\n```js\nw1.postMessage( \"something cool to say\" );\n```\n\nInside the Worker, the messaging is totally symmetrical:\n\n```js\n// \"mycoolworker.js\"\n\naddEventListener( \"message\", function(evt){\n\t// evt.data\n} );\n\npostMessage( \"a really cool reply\" );\n```\n\nNotice that a dedicated Worker is in a one-to-one relationship with the program that created it. That is, the `\"message\"` event doesn't need any disambiguation here, because we're sure that it could only have come from this one-to-one relationship -- either it came from the Worker or the main page.\n\nUsually the main page application creates the Workers, but a Worker can instantiate its own child Worker(s) -- known as subworkers -- as necessary. Sometimes this is useful to delegate such details to a sort of \"master\" Worker that spawns other Workers to process parts of a task. Unfortunately, at the time of this writing, Chrome still does not support subworkers, while Firefox does.\n\nTo kill a Worker immediately from the program that created it, call `terminate()` on the Worker object (like `w1` in the previous snippets). Abruptly terminating a Worker thread does not give it any chance to finish up its work or clean up any resources. It's akin to you closing a browser tab to kill a page.\n\nIf you have two or more pages (or multiple tabs with the same page!) in the browser that try to create a Worker from the same file URL, those will actually end up as completely separate Workers. Shortly, we'll discuss a way to \"share\" a Worker.\n\n**Note:** It may seem like a malicious or ignorant JS program could easily perform a denial-of-service attack on a system by spawning hundreds of Workers, seemingly each with their own thread. While it's true that it's somewhat of a guarantee that a Worker will end up on a separate thread, this guarantee is not unlimited. The system is free to decide how many actual threads/CPUs/cores it really wants to create. There's no way to predict or guarantee how many you'll have access to, though many people assume it's at least as many as the number of CPUs/cores available. I think the safest assumption is that there's at least one other thread besides the main UI thread, but that's about it.\n\n### Worker Environment\n\nInside the Worker, you do not have access to any of the main program's resources. That means you cannot access any of its global variables, nor can you access the page's DOM or other resources. Remember: it's a totally separate thread.\n\nYou can, however, perform network operations (Ajax, WebSockets) and set timers. Also, the Worker has access to its own copy of several important global variables/features, including `navigator`, `location`, `JSON`, and `applicationCache`.\n\nYou can also load extra JS scripts into your Worker, using `importScripts(..)`:\n\n```js\n// inside the Worker\nimportScripts( \"foo.js\", \"bar.js\" );\n```\n\nThese scripts are loaded synchronously, which means the `importScripts(..)` call will block the rest of the Worker's execution until the file(s) are finished loading and executing.\n\n**Note:** There have also been some discussions about exposing the `
![](\"cover.jpg\")
\n\n-----\n\n**[Purchase digital/print copy from O'Reilly](http://shop.oreilly.com/product/0636920033752.do)**\n\n-----\n\n[Table of Contents](toc.md)\n\n* [Foreword](foreword.md) (by [Jake Archibald](http://jakearchibald.com))\n* [Preface](../preface.md)\n* [Chapter 1: Asynchrony: Now & Later](ch1.md)\n* [Chapter 2: Callbacks](ch2.md)\n* [Chapter 3: Promises](ch3.md)\n* [Chapter 4: Generators](ch4.md)\n* [Chapter 5: Program Performance](ch5.md)\n* [Chapter 6: Benchmarking & Tuning](ch6.md)\n* [Appendix A: Library: asynquence](apA.md)\n* [Appendix B: Advanced Async Patterns](apB.md)\n* [Appendix C: Thank You's!](apC.md)\n"
},
{
"path": "async & performance/apA.md",
"content": "# You Don't Know JS: Async & Performance\n# Appendix A: *asynquence* Library\n\nChapters 1 and 2 went into quite a bit of detail about typical asynchronous programming patterns and how they're commonly solved with callbacks. But we also saw why callbacks are fatally limited in capability, which led us to Chapters 3 and 4, with Promises and generators offering a much more solid, trustable, and reason-able base to build your asynchrony on.\n\nI referenced my own asynchronous library *asynquence* (http://github.com/getify/asynquence) -- \"async\" + \"sequence\" = \"asynquence\" -- several times in this book, and I want to now briefly explain how it works and why its unique design is important and helpful.\n\nIn the next appendix, we'll explore some advanced async patterns, but you'll probably want a library to make those palatable enough to be useful. We'll use *asynquence* to express those patterns, so you'll want to spend a little time here getting to know the library first.\n\n*asynquence* is obviously not the only option for good async coding; certainly there are many great libraries in this space. But *asynquence* provides a unique perspective by combining the best of all these patterns into a single library, and moreover is built on a single basic abstraction: the (async) sequence.\n\nMy premise is that sophisticated JS programs often need bits and pieces of various different asynchronous patterns woven together, and this is usually left entirely up to each developer to figure out. Instead of having to bring in two or more different async libraries that focus on different aspects of asynchrony, *asynquence* unifies them into variated sequence steps, with just one core library to learn and deploy.\n\nI believe the value is strong enough with *asynquence* to make async flow control programming with Promise-style semantics super easy to accomplish, so that's why we'll exclusively focus on that library here.\n\nTo begin, I'll explain the design principles behind *asynquence*, and then we'll illustrate how its API works with code examples.\n\n## Sequences, Abstraction Design\n\nUnderstanding *asynquence* begins with understanding a fundamental abstraction: any series of steps for a task, whether they separately are synchronous or asynchronous, can be collectively thought of as a \"sequence\". In other words, a sequence is a container that represents a task, and is comprised of individual (potentially async) steps to complete that task.\n\nEach step in the sequence is controlled under the covers by a Promise (see Chapter 3). That is, every step you add to a sequence implicitly creates a Promise that is wired to the previous end of the sequence. Because of the semantics of Promises, every single step advancement in a sequence is asynchronous, even if you synchronously complete the step.\n\nMoreover, a sequence will always proceed linearly from step to step, meaning that step 2 always comes after step 1 finishes, and so on.\n\nOf course, a new sequence can be forked off an existing sequence, meaning the fork only occurs once the main sequence reaches that point in the flow. Sequences can also be combined in various ways, including having one sequence subsumed by another sequence at a particular point in the flow.\n\nA sequence is kind of like a Promise chain. However, with Promise chains, there is no \"handle\" to grab that references the entire chain. Whichever Promise you have a reference to only represents the current step in the chain plus any other steps hanging off it. Essentially, you cannot hold a reference to a Promise chain unless you hold a reference to the first Promise in the chain.\n\nThere are many cases where it turns out to be quite useful to have a handle that references the entire sequence collectively. The most important of those cases is with sequence abort/cancel. As we covered extensively in Chapter 3, Promises themselves should never be able to be canceled, as this violates a fundamental design imperative: external immutability.\n\nBut sequences have no such immutability design principle, mostly because sequences are not passed around as future-value containers that need immutable value semantics. So sequences are the proper level of abstraction to handle abort/cancel behavior. *asynquence* sequences can be `abort()`ed at any time, and the sequence will stop at that point and not go for any reason.\n\nThere's plenty more reasons to prefer a sequence abstraction on top of Promise chains, for flow control purposes.\n\nFirst, Promise chaining is a rather manual process -- one that can get pretty tedious once you start creating and chaining Promises across a wide swath of your programs -- and this tedium can act counterproductively to dissuade the developer from using Promises in places where they are quite appropriate.\n\nAbstractions are meant to reduce boilerplate and tedium, so the sequence abstraction is a good solution to this problem. With Promises, your focus is on the individual step, and there's little assumption that you will keep the chain going. With sequences, the opposite approach is taken, assuming the sequence will keep having more steps added indefinitely.\n\nThis abstraction complexity reduction is especially powerful when you start thinking about higher-order Promise patterns (beyond `race([..])` and `all([..])`.\n\nFor example, in the middle of a sequence, you may want to express a step that is conceptually like a `try..catch` in that the step will always result in success, either the intended main success resolution or a positive nonerror signal for the caught error. Or, you might want to express a step that is like a retry/until loop, where it keeps trying the same step over and over until success occurs.\n\nThese sorts of abstractions are quite nontrivial to express using only Promise primitives, and doing so in the middle of an existing Promise chain is not pretty. But if you abstract your thinking to a sequence, and consider a step as a wrapper around a Promise, that step wrapper can hide such details, freeing you to think about the flow control in the most sensible way without being bothered by the details.\n\nSecond, and perhaps more importantly, thinking of async flow control in terms of steps in a sequence allows you to abstract out the details of what types of asynchronicity are involved with each individual step. Under the covers, a Promise will always control the step, but above the covers, that step can look either like a continuation callback (the simple default), or like a real Promise, or as a run-to-completion generator, or ... Hopefully, you get the picture.\n\nThird, sequences can more easily be twisted to adapt to different modes of thinking, such as event-, stream-, or reactive-based coding. *asynquence* provides a pattern I call \"reactive sequences\" (which we'll cover later) as a variation on the \"reactive observable\" ideas in RxJS (\"Reactive Extensions\"), that lets a repeatable event fire off a new sequence instance each time. Promises are one-shot-only, so it's quite awkward to express repetitious asynchrony with Promises alone.\n\nAnother alternate mode of thinking inverts the resolution/control capability in a pattern I call \"iterable sequences\". Instead of each individual step internally controlling its own completion (and thus advancement of the sequence), the sequence is inverted so the advancement control is through an external iterator, and each step in the *iterable sequence* just responds to the `next(..)` *iterator* control.\n\nWe'll explore all of these different variations as we go throughout the rest of this appendix, so don't worry if we ran over those bits far too quickly just now.\n\nThe takeaway is that sequences are a more powerful and sensible abstraction for complex asynchrony than just Promises (Promise chains) or just generators, and *asynquence* is designed to express that abstraction with just the right level of sugar to make async programming more understandable and more enjoyable.\n\n## *asynquence* API\n\nTo start off, the way you create a sequence (an *asynquence* instance) is with the `ASQ(..)` function. An `ASQ()` call with no parameters creates an empty initial sequence, whereas passing one or more values or functions to `ASQ(..)` sets up the sequence with each argument representing the initial steps of the sequence.\n\n**Note:** For the purposes of all code examples here, I will use the *asynquence* top-level identifier in global browser usage: `ASQ`. If you include and use *asynquence* through a module system (browser or server), you of course can define whichever symbol you prefer, and *asynquence* won't care!\n\nMany of the API methods discussed here are built into the core of *asynquence*, but others are provided through including the optional \"contrib\" plug-ins package. See the documentation for *asynquence* for whether a method is built in or defined via plug-in: http://github.com/getify/asynquence\n\n### Steps\n\nIf a function represents a normal step in the sequence, that function is invoked with the first parameter being the continuation callback, and any subsequent parameters being any messages passed on from the previous step. The step will not complete until the continuation callback is called. Once it's called, any arguments you pass to it will be sent along as messages to the next step in the sequence.\n\nTo add an additional normal step to the sequence, call `then(..)` (which has essentially the exact same semantics as the `ASQ(..)` call):\n\n```js\nASQ(\n\t// step 1\n\tfunction(done){\n\t\tsetTimeout( function(){\n\t\t\tdone( \"Hello\" );\n\t\t}, 100 );\n\t},\n\t// step 2\n\tfunction(done,greeting) {\n\t\tsetTimeout( function(){\n\t\t\tdone( greeting + \" World\" );\n\t\t}, 100 );\n\t}\n)\n// step 3\n.then( function(done,msg){\n\tsetTimeout( function(){\n\t\tdone( msg.toUpperCase() );\n\t}, 100 );\n} )\n// step 4\n.then( function(done,msg){\n\tconsole.log( msg );\t\t\t// HELLO WORLD\n} );\n```\n\n**Note:** Though the name `then(..)` is identical to the native Promises API, this `then(..)` is different. You can pass as few or as many functions or values to `then(..)` as you'd like, and each is taken as a separate step. There's no two-callback fulfilled/rejected semantics involved.\n\nUnlike with Promises, where to chain one Promise to the next you have to create and `return` that Promise from a `then(..)` fulfillment handler, with *asynquence*, all you need to do is call the continuation callback -- I always call it `done()` but you can name it whatever suits you -- and optionally pass it completion messages as arguments.\n\nEach step defined by `then(..)` is assumed to be asynchronous. If you have a step that's synchronous, you can either just call `done(..)` right away, or you can use the simpler `val(..)` step helper:\n\n```js\n// step 1 (sync)\nASQ( function(done){\n\tdone( \"Hello\" );\t// manually synchronous\n} )\n// step 2 (sync)\n.val( function(greeting){\n\treturn greeting + \" World\";\n} )\n// step 3 (async)\n.then( function(done,msg){\n\tsetTimeout( function(){\n\t\tdone( msg.toUpperCase() );\n\t}, 100 );\n} )\n// step 4 (sync)\n.val( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nAs you can see, `val(..)`-invoked steps don't receive a continuation callback, as that part is assumed for you -- and the parameter list is less cluttered as a result! To send a message along to the next step, you simply use `return`.\n\nThink of `val(..)` as representing a synchronous \"value-only\" step, which is useful for synchronous value operations, logging, and the like.\n\n### Errors\n\nOne important difference with *asynquence* compared to Promises is with error handling.\n\nWith Promises, each individual Promise (step) in a chain can have its own independent error, and each subsequent step has the ability to handle the error or not. The main reason for this semantic comes (again) from the focus on individual Promises rather than on the chain (sequence) as a whole.\n\nI believe that most of the time, an error in one part of a sequence is generally not recoverable, so the subsequent steps in the sequence are moot and should be skipped. So, by default, an error at any step of a sequence throws the entire sequence into error mode, and the rest of the normal steps are ignored.\n\nIf you *do* need to have a step where its error is recoverable, there are several different API methods that can accommodate, such as `try(..)` -- previously mentioned as a kind of `try..catch` step -- or `until(..)` -- a retry loop that keeps attempting the step until it succeeds or you manually `break()` the loop. *asynquence* even has `pThen(..)` and `pCatch(..)` methods, which work identically to how normal Promise `then(..)` and `catch(..)` work (see Chapter 3), so you can do localized mid-sequence error handling if you so choose.\n\nThe point is, you have both options, but the more common one in my experience is the default. With Promises, to get a chain of steps to ignore all steps once an error occurs, you have to take care not to register a rejection handler at any step; otherwise, that error gets swallowed as handled, and the sequence may continue (perhaps unexpectedly). This kind of desired behavior is a bit awkward to properly and reliably handle.\n\nTo register a sequence error notification handler, *asynquence* provides an `or(..)` sequence method, which also has an alias of `onerror(..)`. You can call this method anywhere in the sequence, and you can register as many handlers as you'd like. That makes it easy for multiple different consumers to listen in on a sequence to know if it failed or not; it's kind of like an error event handler in that respect.\n\nJust like with Promises, all JS exceptions become sequence errors, or you can programmatically signal a sequence error:\n\n```js\nvar sq = ASQ( function(done){\n\tsetTimeout( function(){\n\t\t// signal an error for the sequence\n\t\tdone.fail( \"Oops\" );\n\t}, 100 );\n} )\n.then( function(done){\n\t// will never get here\n} )\n.or( function(err){\n\tconsole.log( err );\t\t\t// Oops\n} )\n.then( function(done){\n\t// won't get here either\n} );\n\n// later\n\nsq.or( function(err){\n\tconsole.log( err );\t\t\t// Oops\n} );\n```\n\nAnother really important difference with error handling in *asynquence* compared to native Promises is the default behavior of \"unhandled exceptions\". As we discussed at length in Chapter 3, a rejected Promise without a registered rejection handler will just silently hold (aka swallow) the error; you have to remember to always end a chain with a final `catch(..)`.\n\nIn *asynquence*, the assumption is reversed.\n\nIf an error occurs on a sequence, and it **at that moment** has no error handlers registered, the error is reported to the `console`. In other words, unhandled rejections are by default always reported so as not to be swallowed and missed.\n\nAs soon as you register an error handler against a sequence, it opts that sequence out of such reporting, to prevent duplicate noise.\n\nThere may, in fact, be cases where you want to create a sequence that may go into the error state before you have a chance to register the handler. This isn't common, but it can happen from time to time.\n\nIn those cases, you can also **opt a sequence instance out** of error reporting by calling `defer()` on the sequence. You should only opt out of error reporting if you are sure that you're going to eventually handle such errors:\n\n```js\nvar sq1 = ASQ( function(done){\n\tdoesnt.Exist();\t\t\t// will throw exception to console\n} );\n\nvar sq2 = ASQ( function(done){\n\tdoesnt.Exist();\t\t\t// will throw only a sequence error\n} )\n// opt-out of error reporting\n.defer();\n\nsetTimeout( function(){\n\tsq1.or( function(err){\n\t\tconsole.log( err );\t// ReferenceError\n\t} );\n\n\tsq2.or( function(err){\n\t\tconsole.log( err );\t// ReferenceError\n\t} );\n}, 100 );\n\n// ReferenceError (from sq1)\n```\n\nThis is better error handling behavior than Promises themselves have, because it's the Pit of Success, not the Pit of Failure (see Chapter 3).\n\n**Note:** If a sequence is piped into (aka subsumed by) another sequence -- see \"Combining Sequences\" for a complete description -- then the source sequence is opted out of error reporting, but now the target sequence's error reporting or lack thereof must be considered.\n\n### Parallel Steps\n\nNot all steps in your sequences will have just a single (async) task to perform; some will need to perform multiple steps \"in parallel\" (concurrently). A step in a sequence in which multiple substeps are processing concurrently is called a `gate(..)` -- there's an `all(..)` alias if you prefer -- and is directly symmetric to native `Promise.all([..])`.\n\nIf all the steps in the `gate(..)` complete successfully, all success messages will be passed to the next sequence step. If any of them generate errors, the whole sequence immediately goes into an error state.\n\nConsider:\n\n```js\nASQ( function(done){\n\tsetTimeout( done, 100 );\n} )\n.gate(\n\tfunction(done){\n\t\tsetTimeout( function(){\n\t\t\tdone( \"Hello\" );\n\t\t}, 100 );\n\t},\n\tfunction(done){\n\t\tsetTimeout( function(){\n\t\t\tdone( \"World\", \"!\" );\n\t\t}, 100 );\n\t}\n)\n.val( function(msg1,msg2){\n\tconsole.log( msg1 );\t// Hello\n\tconsole.log( msg2 );\t// [ \"World\", \"!\" ]\n} );\n```\n\nFor illustration, let's compare that example to native Promises:\n\n```js\nnew Promise( function(resolve,reject){\n\tsetTimeout( resolve, 100 );\n} )\n.then( function(){\n\treturn Promise.all( [\n\t\tnew Promise( function(resolve,reject){\n\t\t\tsetTimeout( function(){\n\t\t\t\tresolve( \"Hello\" );\n\t\t\t}, 100 );\n\t\t} ),\n\t\tnew Promise( function(resolve,reject){\n\t\t\tsetTimeout( function(){\n\t\t\t\t// note: we need a [ ] array here\n\t\t\t\tresolve( [ \"World\", \"!\" ] );\n\t\t\t}, 100 );\n\t\t} )\n\t] );\n} )\n.then( function(msgs){\n\tconsole.log( msgs[0] );\t// Hello\n\tconsole.log( msgs[1] );\t// [ \"World\", \"!\" ]\n} );\n```\n\nYuck. Promises require a lot more boilerplate overhead to express the same asynchronous flow control. That's a great illustration of why the *asynquence* API and abstraction make dealing with Promise steps a lot nicer. The improvement only goes higher the more complex your asynchrony is.\n\n#### Step Variations\n\nThere are several variations in the contrib plug-ins on *asynquence*'s `gate(..)` step type that can be quite helpful:\n\n* `any(..)` is like `gate(..)`, except just one segment has to eventually succeed to proceed on the main sequence.\n* `first(..)` is like `any(..)`, except as soon as any segment succeeds, the main sequence proceeds (ignoring subsequent results from other segments).\n* `race(..)` (symmetric with `Promise.race([..])`) is like `first(..)`, except the main sequence proceeds as soon as any segment completes (either success or failure).\n* `last(..)` is like `any(..)`, except only the latest segment to complete successfully sends its message(s) along to the main sequence.\n* `none(..)` is the inverse of `gate(..)`: the main sequence proceeds only if all the segments fail (with all segment error message(s) transposed as success message(s) and vice versa).\n\nLet's first define some helpers to make illustration cleaner:\n\n```js\nfunction success1(done) {\n\tsetTimeout( function(){\n\t\tdone( 1 );\n\t}, 100 );\n}\n\nfunction success2(done) {\n\tsetTimeout( function(){\n\t\tdone( 2 );\n\t}, 100 );\n}\n\nfunction failure3(done) {\n\tsetTimeout( function(){\n\t\tdone.fail( 3 );\n\t}, 100 );\n}\n\nfunction output(msg) {\n\tconsole.log( msg );\n}\n```\n\nNow, let's demonstrate these `gate(..)` step variations:\n\n```js\nASQ().race(\n\tfailure3,\n\tsuccess1\n)\n.or( output );\t\t// 3\n\n\nASQ().any(\n\tsuccess1,\n\tfailure3,\n\tsuccess2\n)\n.val( function(){\n\tvar args = [].slice.call( arguments );\n\tconsole.log(\n\t\targs\t\t// [ 1, undefined, 2 ]\n\t);\n} );\n\n\nASQ().first(\n\tfailure3,\n\tsuccess1,\n\tsuccess2\n)\n.val( output );\t\t// 1\n\n\nASQ().last(\n\tfailure3,\n\tsuccess1,\n\tsuccess2\n)\n.val( output );\t\t// 2\n\nASQ().none(\n\tfailure3\n)\n.val( output )\t\t// 3\n.none(\n\tfailure3\n\tsuccess1\n)\n.or( output );\t\t// 1\n```\n\nAnother step variation is `map(..)`, which lets you asynchronously map elements of an array to different values, and the step doesn't proceed until all the mappings are complete. `map(..)` is very similar to `gate(..)`, except it gets the initial values from an array instead of from separately specified functions, and also because you define a single function callback to operate on each value:\n\n```js\nfunction double(x,done) {\n\tsetTimeout( function(){\n\t\tdone( x * 2 );\n\t}, 100 );\n}\n\nASQ().map( [1,2,3], double )\n.val( output );\t\t\t\t\t// [2,4,6]\n```\n\nAlso, `map(..)` can receive either of its parameters (the array or the callback) from messages passed from the previous step:\n\n```js\nfunction plusOne(x,done) {\n\tsetTimeout( function(){\n\t\tdone( x + 1 );\n\t}, 100 );\n}\n\nASQ( [1,2,3] )\n.map( double )\t\t\t// message `[1,2,3]` comes in\n.map( plusOne )\t\t\t// message `[2,4,6]` comes in\n.val( output );\t\t\t// [3,5,7]\n```\n\nAnother variation is `waterfall(..)`, which is kind of like a mixture between `gate(..)`'s message collection behavior but `then(..)`'s sequential processing.\n\nStep 1 is first executed, then the success message from step 1 is given to step 2, and then both success messages go to step 3, and then all three success messages go to step 4, and so on, such that the messages sort of collect and cascade down the \"waterfall\".\n\nConsider:\n\n```js\nfunction double(done) {\n\tvar args = [].slice.call( arguments, 1 );\n\tconsole.log( args );\n\n\tsetTimeout( function(){\n\t\tdone( args[args.length - 1] * 2 );\n\t}, 100 );\n}\n\nASQ( 3 )\n.waterfall(\n\tdouble,\t\t\t\t\t// [ 3 ]\n\tdouble,\t\t\t\t\t// [ 6 ]\n\tdouble,\t\t\t\t\t// [ 6, 12 ]\n\tdouble\t\t\t\t\t// [ 6, 12, 24 ]\n)\n.val( function(){\n\tvar args = [].slice.call( arguments );\n\tconsole.log( args );\t// [ 6, 12, 24, 48 ]\n} );\n```\n\nIf at any point in the \"waterfall\" an error occurs, the whole sequence immediately goes into an error state.\n\n#### Error Tolerance\n\nSometimes you want to manage errors at the step level and not let them necessarily send the whole sequence into the error state. *asynquence* offers two step variations for that purpose.\n\n`try(..)` attempts a step, and if it succeeds, the sequence proceeds as normal, but if the step fails, the failure is turned into a success message formated as `{ catch: .. }` with the error message(s) filled in:\n\n```js\nASQ()\n.try( success1 )\n.val( output )\t\t\t// 1\n.try( failure3 )\n.val( output )\t\t\t// { catch: 3 }\n.or( function(err){\n\t// never gets here\n} );\n```\n\nYou could instead set up a retry loop using `until(..)`, which tries the step and if it fails, retries the step again on the next event loop tick, and so on.\n\nThis retry loop can continue indefinitely, but if you want to break out of the loop, you can call the `break()` flag on the completion trigger, which sends the main sequence into an error state:\n\n```js\nvar count = 0;\n\nASQ( 3 )\n.until( double )\n.val( output )\t\t\t\t\t// 6\n.until( function(done){\n\tcount++;\n\n\tsetTimeout( function(){\n\t\tif (count < 5) {\n\t\t\tdone.fail();\n\t\t}\n\t\telse {\n\t\t\t// break out of the `until(..)` retry loop\n\t\t\tdone.break( \"Oops\" );\n\t\t}\n\t}, 100 );\n} )\n.or( output );\t\t\t\t\t// Oops\n```\n\n#### Promise-Style Steps\n\nIf you would prefer to have, inline in your sequence, Promise-style semantics like Promises' `then(..)` and `catch(..)` (see Chapter 3), you can use the `pThen` and `pCatch` plug-ins:\n\n```js\nASQ( 21 )\n.pThen( function(msg){\n\treturn msg * 2;\n} )\n.pThen( output )\t\t\t\t// 42\n.pThen( function(){\n\t// throw an exception\n\tdoesnt.Exist();\n} )\n.pCatch( function(err){\n\t// caught the exception (rejection)\n\tconsole.log( err );\t\t\t// ReferenceError\n} )\n.val( function(){\n\t// main sequence is back in a\n\t// success state because previous\n\t// exception was caught by\n\t// `pCatch(..)`\n} );\n```\n\n`pThen(..)` and `pCatch(..)` are designed to run in the sequence, but behave as if it was a normal Promise chain. As such, you can either resolve genuine Promises or *asynquence* sequences from the \"fulfillment\" handler passed to `pThen(..)` (see Chapter 3).\n\n### Forking Sequences\n\nOne feature that can be quite useful about Promises is that you can attach multiple `then(..)` handler registrations to the same promise, effectively \"forking\" the flow-control at that promise:\n\n```js\nvar p = Promise.resolve( 21 );\n\n// fork 1 (from `p`)\np.then( function(msg){\n\treturn msg * 2;\n} )\n.then( function(msg){\n\tconsole.log( msg );\t\t// 42\n} )\n\n// fork 2 (from `p`)\np.then( function(msg){\n\tconsole.log( msg );\t\t// 21\n} );\n```\n\nThe same \"forking\" is easy in *asynquence* with `fork()`:\n\n```js\nvar sq = ASQ(..).then(..).then(..);\n\nvar sq2 = sq.fork();\n\n// fork 1\nsq.then(..)..;\n\n// fork 2\nsq2.then(..)..;\n```\n\n### Combining Sequences\n\nThe reverse of `fork()`ing, you can combine two sequences by subsuming one into another, using the `seq(..)` instance method:\n\n```js\nvar sq = ASQ( function(done){\n\tsetTimeout( function(){\n\t\tdone( \"Hello World\" );\n\t}, 200 );\n} );\n\nASQ( function(done){\n\tsetTimeout( done, 100 );\n} )\n// subsume `sq` sequence into this sequence\n.seq( sq )\n.val( function(msg){\n\tconsole.log( msg );\t\t// Hello World\n} )\n```\n\n`seq(..)` can either accept a sequence itself, as shown here, or a function. If a function, it's expected that the function when called will return a sequence, so the preceding code could have been done with:\n\n```js\n// ..\n.seq( function(){\n\treturn sq;\n} )\n// ..\n```\n\nAlso, that step could instead have been accomplished with a `pipe(..)`:\n\n```js\n// ..\n.then( function(done){\n\t// pipe `sq` into the `done` continuation callback\n\tsq.pipe( done );\n} )\n// ..\n```\n\nWhen a sequence is subsumed, both its success message stream and its error stream are piped in.\n\n**Note:** As mentioned in an earlier note, piping (manually with `pipe(..)` or automatically with `seq(..)`) opts the source sequence out of error-reporting, but doesn't affect the error reporting status of the target sequence.\n\n## Value and Error Sequences\n\nIf any step of a sequence is just a normal value, that value is just mapped to that step's completion message:\n\n```js\nvar sq = ASQ( 42 );\n\nsq.val( function(msg){\n\tconsole.log( msg );\t\t// 42\n} );\n```\n\nIf you want to make a sequence that's automatically errored:\n\n```js\nvar sq = ASQ.failed( \"Oops\" );\n\nASQ()\n.seq( sq )\n.val( function(msg){\n\t// won't get here\n} )\n.or( function(err){\n\tconsole.log( err );\t\t// Oops\n} );\n```\n\nYou also may want to automatically create a delayed-value or a delayed-error sequence. Using the `after` and `failAfter` contrib plug-ins, this is easy:\n\n```js\nvar sq1 = ASQ.after( 100, \"Hello\", \"World\" );\nvar sq2 = ASQ.failAfter( 100, \"Oops\" );\n\nsq1.val( function(msg1,msg2){\n\tconsole.log( msg1, msg2 );\t\t// Hello World\n} );\n\nsq2.or( function(err){\n\tconsole.log( err );\t\t\t\t// Oops\n} );\n```\n\nYou can also insert a delay in the middle of a sequence using `after(..)`:\n\n```js\nASQ( 42 )\n// insert a delay into the sequence\n.after( 100 )\n.val( function(msg){\n\tconsole.log( msg );\t\t// 42\n} );\n```\n\n## Promises and Callbacks\n\nI think *asynquence* sequences provide a lot of value on top of native Promises, and for the most part you'll find it more pleasant and more powerful to work at that level of abstraction. However, integrating *asynquence* with other non-*asynquence* code will be a reality.\n\nYou can easily subsume a promise (e.g., thenable -- see Chapter 3) into a sequence using the `promise(..)` instance method:\n\n```js\nvar p = Promise.resolve( 42 );\n\nASQ()\n.promise( p )\t\t\t// could also: `function(){ return p; }`\n.val( function(msg){\n\tconsole.log( msg );\t// 42\n} );\n```\n\nAnd to go the opposite direction and fork/vend a promise from a sequence at a certain step, use the `toPromise` contrib plug-in:\n\n```js\nvar sq = ASQ.after( 100, \"Hello World\" );\n\nsq.toPromise()\n// this is a standard promise chain now\n.then( function(msg){\n\treturn msg.toUpperCase();\n} )\n.then( function(msg){\n\tconsole.log( msg );\t\t// HELLO WORLD\n} );\n```\n\nTo adapt *asynquence* to systems using callbacks, there are several helper facilities. To automatically generate an \"error-first style\" callback from your sequence to wire into a callback-oriented utility, use `errfcb`:\n\n```js\nvar sq = ASQ( function(done){\n\t// note: expecting \"error-first style\" callback\n\tsomeAsyncFuncWithCB( 1, 2, done.errfcb )\n} )\n.val( function(msg){\n\t// ..\n} )\n.or( function(err){\n\t// ..\n} );\n\n// note: expecting \"error-first style\" callback\nanotherAsyncFuncWithCB( 1, 2, sq.errfcb() );\n```\n\nYou also may want to create a sequence-wrapped version of a utility -- compare to \"promisory\" in Chapter 3 and \"thunkory\" in Chapter 4 -- and *asynquence* provides `ASQ.wrap(..)` for that purpose:\n\n```js\nvar coolUtility = ASQ.wrap( someAsyncFuncWithCB );\n\ncoolUtility( 1, 2 )\n.val( function(msg){\n\t// ..\n} )\n.or( function(err){\n\t// ..\n} );\n```\n\n**Note:** For the sake of clarity (and for fun!), let's coin yet another term, for a sequence-producing function that comes from `ASQ.wrap(..)`, like `coolUtility` here. I propose \"sequory\" (\"sequence\" + \"factory\").\n\n## Iterable Sequences\n\nThe normal paradigm for a sequence is that each step is responsible for completing itself, which is what advances the sequence. Promises work the same way.\n\nThe unfortunate part is that sometimes you need external control over a Promise/step, which leads to awkward \"capability extraction\".\n\nConsider this Promises example:\n\n```js\nvar domready = new Promise( function(resolve,reject){\n\t// don't want to put this here, because\n\t// it belongs logically in another part\n\t// of the code\n\tdocument.addEventListener( \"DOMContentLoaded\", resolve );\n} );\n\n// ..\n\ndomready.then( function(){\n\t// DOM is ready!\n} );\n```\n\nThe \"capability extraction\" anti-pattern with Promises looks like this:\n\n```js\nvar ready;\n\nvar domready = new Promise( function(resolve,reject){\n\t// extract the `resolve()` capability\n\tready = resolve;\n} );\n\n// ..\n\ndomready.then( function(){\n\t// DOM is ready!\n} );\n\n// ..\n\ndocument.addEventListener( \"DOMContentLoaded\", ready );\n```\n\n**Note:** This anti-pattern is an awkward code smell, in my opinion, but some developers like it, for reasons I can't grasp.\n\n*asynquence* offers an inverted sequence type I call \"iterable sequences\", which externalizes the control capability (it's quite useful in use cases like the `domready`):\n\n```js\n// note: `domready` here is an *iterator* that\n// controls the sequence\nvar domready = ASQ.iterable();\n\n// ..\n\ndomready.val( function(){\n\t// DOM is ready\n} );\n\n// ..\n\ndocument.addEventListener( \"DOMContentLoaded\", domready.next );\n```\n\nThere's more to iterable sequences than what we see in this scenario. We'll come back to them in Appendix B.\n\n## Running Generators\n\nIn Chapter 4, we derived a utility called `run(..)` which can run generators to completion, listening for `yield`ed Promises and using them to async resume the generator. *asynquence* has just such a utility built in, called `runner(..)`.\n\nLet's first set up some helpers for illustration:\n\n```js\nfunction doublePr(x) {\n\treturn new Promise( function(resolve,reject){\n\t\tsetTimeout( function(){\n\t\t\tresolve( x * 2 );\n\t\t}, 100 );\n\t} );\n}\n\nfunction doubleSeq(x) {\n\treturn ASQ( function(done){\n\t\tsetTimeout( function(){\n\t\t\tdone( x * 2)\n\t\t}, 100 );\n\t} );\n}\n```\n\nNow, we can use `runner(..)` as a step in the middle of a sequence:\n\n```js\nASQ( 10, 11 )\n.runner( function*(token){\n\tvar x = token.messages[0] + token.messages[1];\n\n\t// yield a real promise\n\tx = yield doublePr( x );\n\n\t// yield a sequence\n\tx = yield doubleSeq( x );\n\n\treturn x;\n} )\n.val( function(msg){\n\tconsole.log( msg );\t\t\t// 84\n} );\n```\n\n### Wrapped Generators\n\nYou can also create a self-packaged generator -- that is, a normal function that runs your specified generator and returns a sequence for its completion -- by `ASQ.wrap(..)`ing it:\n\n```js\nvar foo = ASQ.wrap( function*(token){\n\tvar x = token.messages[0] + token.messages[1];\n\n\t// yield a real promise\n\tx = yield doublePr( x );\n\n\t// yield a sequence\n\tx = yield doubleSeq( x );\n\n\treturn x;\n}, { gen: true } );\n\n// ..\n\nfoo( 8, 9 )\n.val( function(msg){\n\tconsole.log( msg );\t\t\t// 68\n} );\n```\n\nThere's a lot more awesome that `runner(..)` is capable of, but we'll come back to that in Appendix B.\n\n## Review\n\n*asynquence* is a simple abstraction -- a sequence is a series of (async) steps -- on top of Promises, aimed at making working with various asynchronous patterns much easier, without any compromise in capability.\n\nThere are other goodies in the *asynquence* core API and its contrib plug-ins beyond what we saw in this appendix, but we'll leave that as an exercise for the reader to go check the rest of the capabilities out.\n\nYou've now seen the essence and spirit of *asynquence*. The key take away is that a sequence is comprised of steps, and those steps can be any of dozens of different variations on Promises, or they can be a generator-run, or... The choice is up to you, you have all the freedom to weave together whatever async flow control logic is appropriate for your tasks. No more library switching to catch different async patterns.\n\nIf these *asynquence* snippets have made sense to you, you're now pretty well up to speed on the library; it doesn't take that much to learn, actually!\n\nIf you're still a little fuzzy on how it works (or why!), you'll want to spend a little more time examining the previous examples and playing around with *asynquence* yourself, before going on to the next appendix. Appendix B will push *asynquence* into several more advanced and powerful async patterns.\n"
},
{
"path": "async & performance/apB.md",
"content": "# You Don't Know JS: Async & Performance\n# Appendix B: Advanced Async Patterns\n\nAppendix A introduced the *asynquence* library for sequence-oriented async flow control, primarily based on Promises and generators.\n\nNow we'll explore other advanced asynchronous patterns built on top of that existing understanding and functionality, and see how *asynquence* makes those sophisticated async techniques easy to mix and match in our programs without needing lots of separate libraries.\n\n## Iterable Sequences\n\nWe introduced *asynquence*'s iterable sequences in the previous appendix, but we want to revisit them in more detail.\n\nTo refresh, recall:\n\n```js\nvar domready = ASQ.iterable();\n\n// ..\n\ndomready.val( function(){\n\t// DOM is ready\n} );\n\n// ..\n\ndocument.addEventListener( \"DOMContentLoaded\", domready.next );\n```\n\nNow, let's define a sequence of multiple steps as an iterable sequence:\n\n```js\nvar steps = ASQ.iterable();\n\nsteps\n.then( function STEP1(x){\n\treturn x * 2;\n} )\n.then( function STEP2(x){\n\treturn x + 3;\n} )\n.then( function STEP3(x){\n\treturn x * 4;\n} );\n\nsteps.next( 8 ).value;\t// 16\nsteps.next( 16 ).value;\t// 19\nsteps.next( 19 ).value;\t// 76\nsteps.next().done;\t\t// true\n```\n\nAs you can see, an iterable sequence is a standard-compliant *iterator* (see Chapter 4). So, it can be iterated with an ES6 `for..of` loop, just like a generator (or any other *iterable*) can:\n\n```js\nvar steps = ASQ.iterable();\n\nsteps\n.then( function STEP1(){ return 2; } )\n.then( function STEP2(){ return 4; } )\n.then( function STEP3(){ return 6; } )\n.then( function STEP4(){ return 8; } )\n.then( function STEP5(){ return 10; } );\n\nfor (var v of steps) {\n\tconsole.log( v );\n}\n// 2 4 6 8 10\n```\n\nBeyond the event triggering example shown in the previous appendix, iterable sequences are interesting because in essence they can be seen as a stand-in for generators or Promise chains, but with even more flexibility.\n\nConsider a multiple Ajax request example -- we've seen the same scenario in Chapters 3 and 4, both as a Promise chain and as a generator, respectively -- expressed as an iterable sequence:\n\n```js\n// sequence-aware ajax\nvar request = ASQ.wrap( ajax );\n\nASQ( \"http://some.url.1\" )\n.runner(\n\tASQ.iterable()\n\n\t.then( function STEP1(token){\n\t\tvar url = token.messages[0];\n\t\treturn request( url );\n\t} )\n\n\t.then( function STEP2(resp){\n\t\treturn ASQ().gate(\n\t\t\trequest( \"http://some.url.2/?v=\" + resp ),\n\t\t\trequest( \"http://some.url.3/?v=\" + resp )\n\t\t);\n\t} )\n\n\t.then( function STEP3(r1,r2){ return r1 + r2; } )\n)\n.val( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nThe iterable sequence expresses a sequential series of (sync or async) steps that looks awfully similar to a Promise chain -- in other words, it's much cleaner looking than just plain nested callbacks, but not quite as nice as the `yield`-based sequential syntax of generators.\n\nBut we pass the iterable sequence into `ASQ#runner(..)`, which runs it to completion the same as if it was a generator. The fact that an iterable sequence behaves essentially the same as a generator is notable for a couple of reasons.\n\nFirst, iterable sequences are kind of a pre-ES6 equivalent to a certain subset of ES6 generators, which means you can either author them directly (to run anywhere), or you can author ES6 generators and transpile/convert them to iterable sequences (or Promise chains for that matter!).\n\nThinking of an async-run-to-completion generator as just syntactic sugar for a Promise chain is an important recognition of their isomorphic relationship.\n\nBefore we move on, we should note that the previous snippet could have been expressed in *asynquence* as:\n\n```js\nASQ( \"http://some.url.1\" )\n.seq( /*STEP 1*/ request )\n.seq( function STEP2(resp){\n\treturn ASQ().gate(\n\t\trequest( \"http://some.url.2/?v=\" + resp ),\n\t\trequest( \"http://some.url.3/?v=\" + resp )\n\t);\n} )\n.val( function STEP3(r1,r2){ return r1 + r2; } )\n.val( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nMoreover, step 2 could have even been expressed as:\n\n```js\n.gate(\n\tfunction STEP2a(done,resp) {\n\t\trequest( \"http://some.url.2/?v=\" + resp )\n\t\t.pipe( done );\n\t},\n\tfunction STEP2b(done,resp) {\n\t\trequest( \"http://some.url.3/?v=\" + resp )\n\t\t.pipe( done );\n\t}\n)\n```\n\nSo, why would we go to the trouble of expressing our flow control as an iterable sequence in a `ASQ#runner(..)` step, when it seems like a simpler/flatter *asyquence* chain does the job well?\n\nBecause the iterable sequence form has an important trick up its sleeve that gives us more capability. Read on.\n\n### Extending Iterable Sequences\n\nGenerators, normal *asynquence* sequences, and Promise chains, are all **eagerly evaluated** -- whatever flow control is expressed initially *is* the fixed flow that will be followed.\n\nHowever, iterable sequences are **lazily evaluated**, which means that during execution of the iterable sequence, you can extend the sequence with more steps if desired.\n\n**Note:** You can only append to the end of an iterable sequence, not inject into the middle of the sequence.\n\nLet's first look at a simpler (synchronous) example of that capability to get familiar with it:\n\n```js\nfunction double(x) {\n\tx *= 2;\n\n\t// should we keep extending?\n\tif (x < 500) {\n\t\tisq.then( double );\n\t}\n\n\treturn x;\n}\n\n// setup single-step iterable sequence\nvar isq = ASQ.iterable().then( double );\n\nfor (var v = 10, ret;\n\t(ret = isq.next( v )) && !ret.done;\n) {\n\tv = ret.value;\n\tconsole.log( v );\n}\n```\n\nThe iterable sequence starts out with only one defined step (`isq.then(double)`), but the sequence keeps extending itself under certain conditions (`x < 500`). Both *asynquence* sequences and Promise chains technically *can* do something similar, but we'll see in a little bit why their capability is insufficient.\n\nThough this example is rather trivial and could otherwise be expressed with a `while` loop in a generator, we'll consider more sophisticated cases.\n\nFor instance, you could examine the response from an Ajax request and if it indicates that more data is needed, you conditionally insert more steps into the iterable sequence to make the additional request(s). Or you could conditionally add a value-formatting step to the end of your Ajax handling.\n\nConsider:\n\n```js\nvar steps = ASQ.iterable()\n\n.then( function STEP1(token){\n\tvar url = token.messages[0].url;\n\n\t// was an additional formatting step provided?\n\tif (token.messages[0].format) {\n\t\tsteps.then( token.messages[0].format );\n\t}\n\n\treturn request( url );\n} )\n\n.then( function STEP2(resp){\n\t// add another Ajax request to the sequence?\n\tif (/x1/.test( resp )) {\n\t\tsteps.then( function STEP5(text){\n\t\t\treturn request(\n\t\t\t\t\"http://some.url.4/?v=\" + text\n\t\t\t);\n\t\t} );\n\t}\n\n\treturn ASQ().gate(\n\t\trequest( \"http://some.url.2/?v=\" + resp ),\n\t\trequest( \"http://some.url.3/?v=\" + resp )\n\t);\n} )\n\n.then( function STEP3(r1,r2){ return r1 + r2; } );\n```\n\nYou can see in two different places where we conditionally extend `steps` with `steps.then(..)`. And to run this `steps` iterable sequence, we just wire it into our main program flow with an *asynquence* sequence (called `main` here) using `ASQ#runner(..)`:\n\n```js\nvar main = ASQ( {\n\turl: \"http://some.url.1\",\n\tformat: function STEP4(text){\n\t\treturn text.toUpperCase();\n\t}\n} )\n.runner( steps )\n.val( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nCan the flexibility (conditional behavior) of the `steps` iterable sequence be expressed with a generator? Kind of, but we have to rearrange the logic in a slightly awkward way:\n\n```js\nfunction *steps(token) {\n\t// **STEP 1**\n\tvar resp = yield request( token.messages[0].url );\n\n\t// **STEP 2**\n\tvar rvals = yield ASQ().gate(\n\t\trequest( \"http://some.url.2/?v=\" + resp ),\n\t\trequest( \"http://some.url.3/?v=\" + resp )\n\t);\n\n\t// **STEP 3**\n\tvar text = rvals[0] + rvals[1];\n\n\t// **STEP 4**\n\t// was an additional formatting step provided?\n\tif (token.messages[0].format) {\n\t\ttext = yield token.messages[0].format( text );\n\t}\n\n\t// **STEP 5**\n\t// need another Ajax request added to the sequence?\n\tif (/foobar/.test( resp )) {\n\t\ttext = yield request(\n\t\t\t\"http://some.url.4/?v=\" + text\n\t\t);\n\t}\n\n\treturn text;\n}\n\n// note: `*steps()` can be run by the same `ASQ` sequence\n// as `steps` was previously\n```\n\nSetting aside the already identified benefits of the sequential, synchronous-looking syntax of generators (see Chapter 4), the `steps` logic had to be reordered in the `*steps()` generator form, to fake the dynamicism of the extendable iterable sequence `steps`.\n\nWhat about expressing the functionality with Promises or sequences, though? You *can* do something like this:\n\n```js\nvar steps = something( .. )\n.then( .. )\n.then( function(..){\n\t// ..\n\n\t// extending the chain, right?\n\tsteps = steps.then( .. );\n\n\t// ..\n})\n.then( .. );\n```\n\nThe problem is subtle but important to grasp. So, consider trying to wire up our `steps` Promise chain into our main program flow -- this time expressed with Promises instead of *asynquence*:\n\n```js\nvar main = Promise.resolve( {\n\turl: \"http://some.url.1\",\n\tformat: function STEP4(text){\n\t\treturn text.toUpperCase();\n\t}\n} )\n.then( function(..){\n\treturn steps;\t\t\t// hint!\n} )\n.val( function(msg){\n\tconsole.log( msg );\n} );\n```\n\nCan you spot the problem now? Look closely!\n\nThere's a race condition for sequence steps ordering. When you `return steps`, at that moment `steps` *might* be the originally defined promise chain, or it might now point to the extended promise chain via the `steps = steps.then(..)` call, depending on what order things happen.\n\nHere are the two possible outcomes:\n\n* If `steps` is still the original promise chain, once it's later \"extended\" by `steps = steps.then(..)`, that extended promise on the end of the chain is **not** considered by the `main` flow, as it's already tapped the `steps` chain. This is the unfortunately limiting **eager evaluation**.\n* If `steps` is already the extended promise chain, it works as we expect in that the extended promise is what `main` taps.\n\nOther than the obvious fact that a race condition is intolerable, the first case is the concern; it illustrates **eager evaluation** of the promise chain. By contrast, we easily extended the iterable sequence without such issues, because iterable sequences are **lazily evaluated**.\n\nThe more dynamic you need your flow control, the more iterable sequences will shine.\n\n**Tip:** Check out more information and examples of iterable sequences on the *asynquence* site (https://github.com/getify/asynquence/blob/master/README.md#iterable-sequences).\n\n## Event Reactive\n\nIt should be obvious from (at least!) Chapter 3 that Promises are a very powerful tool in your async toolbox. But one thing that's clearly lacking is in their capability to handle streams of events, as a Promise can only be resolved once. And frankly, this exact same weakness is true of plain *asynquence* sequences, as well.\n\nConsider a scenario where you want to fire off a series of steps every time a certain event is fired. A single Promise or sequence cannot represent all occurrences of that event. So, you have to create a whole new Promise chain (or sequence) for *each* event occurrence, such as:\n\n```js\nlistener.on( \"foobar\", function(data){\n\n\t// create a new event handling promise chain\n\tnew Promise( function(resolve,reject){\n\t\t// ..\n\t} )\n\t.then( .. )\n\t.then( .. );\n\n} );\n```\n\nThe base functionality we need is present in this approach, but it's far from a desirable way to express our intended logic. There are two separate capabilities conflated in this paradigm: the event listening, and responding to the event; separation of concerns would implore us to separate out these capabilities.\n\nThe carefully observant reader will see this problem as somewhat symmetrical to the problems we detailed with callbacks in Chapter 2; it's kind of an inversion of control problem.\n\nImagine uninverting this paradigm, like so:\n\n```js\nvar observable = listener.on( \"foobar\" );\n\n// later\nobservable\n.then( .. )\n.then( .. );\n\n// elsewhere\nobservable\n.then( .. )\n.then( .. );\n```\n\nThe `observable` value is not exactly a Promise, but you can *observe* it much like you can observe a Promise, so it's closely related. In fact, it can be observed many times, and it will send out notifications every time its event (`\"foobar\"`) occurs.\n\n**Tip:** This pattern I've just illustrated is a **massive simplification** of the concepts and motivations behind reactive programming (aka RP), which has been implemented/expounded upon by several great projects and languages. A variation on RP is functional reactive programming (FRP), which refers to applying functional programming techniques (immutability, referential integrity, etc.) to streams of data. \"Reactive\" refers to spreading this functionality out over time in response to events. The interested reader should consider studying \"Reactive Observables\" in the fantastic \"Reactive Extensions\" library (\"RxJS\" for JavaScript) by Microsoft (http://rxjs.codeplex.com/); it's much more sophisticated and powerful than I've just shown. Also, Andre Staltz has an excellent write-up (https://gist.github.com/staltz/868e7e9bc2a7b8c1f754) that pragmatically lays out RP in concrete examples.\n\n### ES7 Observables\n\nAt the time of this writing, there's an early ES7 proposal for a new data type called \"Observable\" (https://github.com/jhusain/asyncgenerator#introducing-observable), which in spirit is similar to what we've laid out here, but is definitely more sophisticated.\n\nThe notion of this kind of Observable is that the way you \"subscribe\" to the events from a stream is to pass in a generator -- actually the *iterator* is the interested party -- whose `next(..)` method will be called for each event.\n\nYou could imagine it sort of like this:\n\n```js\n// `someEventStream` is a stream of events, like from\n// mouse clicks, and the like.\n\nvar observer = new Observer( someEventStream, function*(){\n\twhile (var evt = yield) {\n\t\tconsole.log( evt );\n\t}\n} );\n```\n\nThe generator you pass in will `yield` pause the `while` loop waiting for the next event. The *iterator* attached to the generator instance will have its `next(..)` called each time `someEventStream` has a new event published, and so that event data will resume your generator/*iterator* with the `evt` data.\n\nIn the subscription to events functionality here, it's the *iterator* part that matters, not the generator. So conceptually you could pass in practically any iterable, including `ASQ.iterable()` iterable sequences.\n\nInterestingly, there are also proposed adapters to make it easy to construct Observables from certain types of streams, such as `fromEvent(..)` for DOM events. If you look at a suggested implementation of `fromEvent(..)` in the earlier linked ES7 proposal, it looks an awful lot like the `ASQ.react(..)` we'll see in the next section.\n\nOf course, these are all early proposals, so what shakes out may very well look/behave differently than shown here. But it's exciting to see the early alignments of concepts across different libraries and language proposals!\n\n### Reactive Sequences\n\nWith that crazy brief summary of Observables (and F/RP) as our inspiration and motivation, I will now illustrate an adaptation of a small subset of \"Reactive Observables,\" which I call \"Reactive Sequences.\"\n\nFirst, let's start with how to create an Observable, using an *asynquence* plug-in utility called `react(..)`:\n\n```js\nvar observable = ASQ.react( function setup(next){\n\tlistener.on( \"foobar\", next );\n} );\n```\n\nNow, let's see how to define a sequence that \"reacts\" -- in F/RP, this is typically called \"subscribing\" -- to that `observable`:\n\n```js\nobservable\n.seq( .. )\n.then( .. )\n.val( .. );\n```\n\nSo, you just define the sequence by chaining off the Observable. That's easy, huh?\n\nIn F/RP, the stream of events typically channels through a set of functional transforms, like `scan(..)`, `map(..)`, `reduce(..)`, and so on. With reactive sequences, each event channels through a new instance of the sequence. Let's look at a more concrete example:\n\n```js\nASQ.react( function setup(next){\n\tdocument.getElementById( \"mybtn\" )\n\t.addEventListener( \"click\", next, false );\n} )\n.seq( function(evt){\n\tvar btnID = evt.target.id;\n\treturn request(\n\t\t\"http://some.url.1/?id=\" + btnID\n\t);\n} )\n.val( function(text){\n\tconsole.log( text );\n} );\n```\n\nThe \"reactive\" portion of the reactive sequence comes from assigning one or more event handlers to invoke the event trigger (calling `next(..)`).\n\nThe \"sequence\" portion of the reactive sequence is exactly like the sequences we've already explored: each step can be whatever asynchronous technique makes sense, from continuation callback to Promise to generator.\n\nOnce you set up a reactive sequence, it will continue to initiate instances of the sequence as long as the events keep firing. If you want to stop a reactive sequence, you can call `stop()`.\n\nIf a reactive sequence is `stop()`'d, you likely want the event handler(s) to be unregistered as well; you can register a teardown handler for this purpose:\n\n```js\nvar sq = ASQ.react( function setup(next,registerTeardown){\n\tvar btn = document.getElementById( \"mybtn\" );\n\n\tbtn.addEventListener( \"click\", next, false );\n\n\t// will be called once `sq.stop()` is called\n\tregisterTeardown( function(){\n\t\tbtn.removeEventListener( \"click\", next, false );\n\t} );\n} )\n.seq( .. )\n.then( .. )\n.val( .. );\n\n// later\nsq.stop();\n```\n\n**Note:** The `this` binding reference inside the `setup(..)` handler is the same `sq` reactive sequence, so you can use the `this` reference to add to the reactive sequence definition, call methods like `stop()`, and so on.\n\nHere's an example from the Node.js world, using reactive sequences to handle incoming HTTP requests:\n\n```js\nvar server = http.createServer();\nserver.listen(8000);\n\n// reactive observer\nvar request = ASQ.react( function setup(next,registerTeardown){\n\tserver.addListener( \"request\", next );\n\tserver.addListener( \"close\", this.stop );\n\n\tregisterTeardown( function(){\n\t\tserver.removeListener( \"request\", next );\n\t\tserver.removeListener( \"close\", request.stop );\n\t} );\n});\n\n// respond to requests\nrequest\n.seq( pullFromDatabase )\n.val( function(data,res){\n\tres.end( data );\n} );\n\n// node teardown\nprocess.on( \"SIGINT\", request.stop );\n```\n\nThe `next(..)` trigger can also adapt to node streams easily, using `onStream(..)` and `unStream(..)`:\n\n```js\nASQ.react( function setup(next){\n\tvar fstream = fs.createReadStream( \"/some/file\" );\n\n\t// pipe the stream's \"data\" event to `next(..)`\n\tnext.onStream( fstream );\n\n\t// listen for the end of the stream\n\tfstream.on( \"end\", function(){\n\t\tnext.unStream( fstream );\n\t} );\n} )\n.seq( .. )\n.then( .. )\n.val( .. );\n```\n\nYou can also use sequence combinations to compose multiple reactive sequence streams:\n\n```js\nvar sq1 = ASQ.react( .. ).seq( .. ).then( .. );\nvar sq2 = ASQ.react( .. ).seq( .. ).then( .. );\n\nvar sq3 = ASQ.react(..)\n.gate(\n\tsq1,\n\tsq2\n)\n.then( .. );\n```\n\nThe main takeaway is that `ASQ.react(..)` is a lightweight adaptation of F/RP concepts, enabling the wiring of an event stream to a sequence, hence the term \"reactive sequence.\" Reactive sequences are generally capable enough for basic reactive uses.\n\n**Note:** Here's an example of using `ASQ.react(..)` in managing UI state (http://jsbin.com/rozipaki/6/edit?js,output), and another example of handling HTTP request/response streams with `ASQ.react(..)` (https://gist.github.com/getify/bba5ec0de9d6047b720e).\n\n## Generator Coroutine\n\nHopefully Chapter 4 helped you get pretty familiar with ES6 generators. In particular, we want to revisit the \"Generator Concurrency\" discussion, and push it even further.\n\nWe imagined a `runAll(..)` utility that could take two or more generators and run them concurrently, letting them cooperatively `yield` control from one to the next, with optional message passing.\n\nIn addition to being able to run a single generator to completion, the `ASQ#runner(..)` we discussed in Appendix A is a similar implementation of the concepts of `runAll(..)`, which can run multiple generators concurrently to completion.\n\nSo let's see how we can implement the concurrent Ajax scenario from Chapter 4:\n\n```js\nASQ(\n\t\"http://some.url.2\"\n)\n.runner(\n\tfunction*(token){\n\t\t// transfer control\n\t\tyield token;\n\n\t\tvar url1 = token.messages[0]; // \"http://some.url.1\"\n\n\t\t// clear out messages to start fresh\n\t\ttoken.messages = [];\n\n\t\tvar p1 = request( url1 );\n\n\t\t// transfer control\n\t\tyield token;\n\n\t\ttoken.messages.push( yield p1 );\n\t},\n\tfunction*(token){\n\t\tvar url2 = token.messages[0]; // \"http://some.url.2\"\n\n\t\t// message pass and transfer control\n\t\ttoken.messages[0] = \"http://some.url.1\";\n\t\tyield token;\n\n\t\tvar p2 = request( url2 );\n\n\t\t// transfer control\n\t\tyield token;\n\n\t\ttoken.messages.push( yield p2 );\n\n\t\t// pass along results to next sequence step\n\t\treturn token.messages;\n\t}\n)\n.val( function(res){\n\t// `res[0]` comes from \"http://some.url.1\"\n\t// `res[1]` comes from \"http://some.url.2\"\n} );\n```\n\nThe main differences between `ASQ#runner(..)` and `runAll(..)` are as follows:\n\n* Each generator (coroutine) is provided an argument we call `token`, which is the special value to `yield` when you want to explicitly transfer control to the next coroutine.\n* `token.messages` is an array that holds any messages passed in from the previous sequence step. It's also a data structure that you can use to share messages between coroutines.\n* `yield`ing a Promise (or sequence) value does not transfer control, but instead pauses the coroutine processing until that value is ready.\n* The last `return`ed or `yield`ed value from the coroutine processing run will be forward passed to the next step in the sequence.\n\nIt's also easy to layer helpers on top of the base `ASQ#runner(..)` functionality to suit different uses.\n\n### State Machines\n\nOne example that may be familiar to many programmers is state machines. You can, with the help of a simple cosmetic utility, create an easy-to-express state machine processor.\n\nLet's imagine such a utility. We'll call it `state(..)`, and will pass it two arguments: a state value and a generator that handles that state. `state(..)` will do the dirty work of creating and returning an adapter generator to pass to `ASQ#runner(..)`.\n\nConsider:\n\n```js\nfunction state(val,handler) {\n\t// make a coroutine handler for this state\n\treturn function*(token) {\n\t\t// state transition handler\n\t\tfunction transition(to) {\n\t\t\ttoken.messages[0] = to;\n\t\t}\n\n\t\t// set initial state (if none set yet)\n\t\tif (token.messages.length < 1) {\n\t\t\ttoken.messages[0] = val;\n\t\t}\n\n\t\t// keep going until final state (false) is reached\n\t\twhile (token.messages[0] !== false) {\n\t\t\t// current state matches this handler?\n\t\t\tif (token.messages[0] === val) {\n\t\t\t\t// delegate to state handler\n\t\t\t\tyield *handler( transition );\n\t\t\t}\n\n\t\t\t// transfer control to another state handler?\n\t\t\tif (token.messages[0] !== false) {\n\t\t\t\tyield token;\n\t\t\t}\n\t\t}\n\t};\n}\n```\n\nIf you look closely, you'll see that `state(..)` returns back a generator that accepts a `token`, and then it sets up a `while` loop that will run until the state machine reaches its final state (which we arbitrarily pick as the `false` value); that's exactly the kind of generator we want to pass to `ASQ#runner(..)`!\n\nWe also arbitrarily reserve the `token.messages[0]` slot as the place where the current state of our state machine will be tracked, which means we can even seed the initial state as the value passed in from the previous step in the sequence.\n\nHow do we use the `state(..)` helper along with `ASQ#runner(..)`?\n\n```js\nvar prevState;\n\nASQ(\n\t/* optional: initial state value */\n\t2\n)\n// run our state machine\n// transitions: 2 -> 3 -> 1 -> 3 -> false\n.runner(\n\t// state `1` handler\n\tstate( 1, function *stateOne(transition){\n\t\tconsole.log( \"in state 1\" );\n\n\t\tprevState = 1;\n\t\tyield transition( 3 );\t// goto state `3`\n\t} ),\n\n\t// state `2` handler\n\tstate( 2, function *stateTwo(transition){\n\t\tconsole.log( \"in state 2\" );\n\n\t\tprevState = 2;\n\t\tyield transition( 3 );\t// goto state `3`\n\t} ),\n\n\t// state `3` handler\n\tstate( 3, function *stateThree(transition){\n\t\tconsole.log( \"in state 3\" );\n\n\t\tif (prevState === 2) {\n\t\t\tprevState = 3;\n\t\t\tyield transition( 1 ); // goto state `1`\n\t\t}\n\t\t// all done!\n\t\telse {\n\t\t\tyield \"That's all folks!\";\n\n\t\t\tprevState = 3;\n\t\t\tyield transition( false ); // terminal state\n\t\t}\n\t} )\n)\n// state machine complete, so move on\n.val( function(msg){\n\tconsole.log( msg );\t// That's all folks!\n} );\n```\n\nIt's important to note that the `*stateOne(..)`, `*stateTwo(..)`, and `*stateThree(..)` generators themselves are reinvoked each time that state is entered, and they finish when you `transition(..)` to another value. While not shown here, of course these state generator handlers can be asynchronously paused by `yield`ing Promises/sequences/thunks.\n\nThe underneath hidden generators produced by the `state(..)` helper and actually passed to `ASQ#runner(..)` are the ones that continue to run concurrently for the length of the state machine, and each of them handles cooperatively `yield`ing control to the next, and so on.\n\n**Note:** See this \"ping pong\" example (http://jsbin.com/qutabu/1/edit?js,output) for more illustration of using cooperative concurrency with generators driven by `ASQ#runner(..)`.\n\n## Communicating Sequential Processes (CSP)\n\n\"Communicating Sequential Processes\" (CSP) was first described by C. A. R. Hoare in a 1978 academic paper (http://dl.acm.org/citation.cfm?doid=359576.359585), and later in a 1985 book (http://www.usingcsp.com/) of the same name. CSP describes a formal method for concurrent \"processes\" to interact (aka \"communicate\") during processing.\n\nYou may recall that we examined concurrent \"processes\" back in Chapter 1, so our exploration of CSP here will build upon that understanding.\n\nLike most great concepts in computer science, CSP is heavily steeped in academic formalism, expressed as a process algebra. However, I suspect symbolic algebra theorems won't make much practical difference to the reader, so we will want to find some other way of wrapping our brains around CSP.\n\nI will leave much of the formal description and proof of CSP to Hoare's writing, and to many other fantastic writings since. Instead, we will try to just briefly explain the idea of CSP in as un-academic and hopefully intuitively understandable a way as possible.\n\n### Message Passing\n\nThe core principle in CSP is that all communication/interaction between otherwise independent processes must be through formal message passing. Perhaps counter to your expectations, CSP message passing is described as a synchronous action, where the sender process and the receiver process have to mutually be ready for the message to be passed.\n\nHow could such synchronous messaging possibly be related to asynchronous programming in JavaScript?\n\nThe concreteness of relationship comes from the nature of how ES6 generators are used to produce synchronous-looking actions that under the covers can indeed either be synchronous or (more likely) asynchronous.\n\nIn other words, two or more concurrently running generators can appear to synchronously message each other while preserving the fundamental asynchrony of the system because each generator's code is paused (aka \"blocked\") waiting on resumption of an asynchronous action.\n\nHow does this work?\n\nImagine a generator (aka \"process\") called \"A\" that wants to send a message to generator \"B.\" First, \"A\" `yield`s the message (thus pausing \"A\") to be sent to \"B.\" When \"B\" is ready and takes the message, \"A\" is then resumed (unblocked).\n\nSymmetrically, imagine a generator \"A\" that wants a message **from** \"B.\" \"A\" `yield`s its request (thus pausing \"A\") for the message from \"B,\" and once \"B\" sends a message, \"A\" takes the message and is resumed.\n\nOne of the more popular expressions of this CSP message passing theory comes from ClojureScript's core.async library, and also from the *go* language. These takes on CSP embody the described communication semantics in a conduit that is opened between processes called a \"channel.\"\n\n**Note:** The term *channel* is used in part because there are modes in which more than one value can be sent at once into the \"buffer\" of the channel; this is similar to what you may think of as a stream. We won't go into depth about it here, but it can be a very powerful technique for managing streams of data.\n\nIn the simplest notion of CSP, a channel that we create between \"A\" and \"B\" would have a method called `take(..)` for blocking to receive a value, and a method called `put(..)` for blocking to send a value.\n\nThis might look like:\n\n```js\nvar ch = channel();\n\nfunction *foo() {\n\tvar msg = yield take( ch );\n\n\tconsole.log( msg );\n}\n\nfunction *bar() {\n\tyield put( ch, \"Hello World\" );\n\n\tconsole.log( \"message sent\" );\n}\n\nrun( foo );\nrun( bar );\n// Hello World\n// \"message sent\"\n```\n\nCompare this structured, synchronous(-looking) message passing interaction to the informal and unstructured message sharing that `ASQ#runner(..)` provides through the `token.messages` array and cooperative `yield`ing. In essence, `yield put(..)` is a single operation that both sends the value and pauses execution to transfer control, whereas in earlier examples we did those as separate steps.\n\nMoreover, CSP stresses that you don't really explicitly \"transfer control,\" but rather you design your concurrent routines to block expecting either a value received from the channel, or to block expecting to try to send a message on the channel. The blocking around receiving or sending messages is how you coordinate sequencing of behavior between the coroutines.\n\n**Note:** Fair warning: this pattern is very powerful but it's also a little mind twisting to get used to at first. You will want to practice this a bit to get used to this new way of thinking about coordinating your concurrency.\n\nThere are several great libraries that have implemented this flavor of CSP in JavaScript, most notably \"js-csp\" (https://github.com/ubolonton/js-csp), which James Long (http://twitter.com/jlongster) forked (https://github.com/jlongster/js-csp) and has written extensively about (http://jlongster.com/Taming-the-Asynchronous-Beast-with-CSP-in-JavaScript). Also, it cannot be stressed enough how amazing the many writings of David Nolen (http://twitter.com/swannodette) are on the topic of adapting ClojureScript's go-style core.async CSP into JS generators (http://swannodette.github.io/2013/08/24/es6-generators-and-csp).\n\n### asynquence CSP emulation\n\nBecause we've been discussing async patterns here in the context of my *asynquence* library, you might be interested to see that we can fairly easily add an emulation layer on top of `ASQ#runner(..)` generator handling as a nearly perfect porting of the CSP API and behavior. This emulation layer ships as an optional part of the \"asynquence-contrib\" package alongside *asynquence*.\n\nVery similar to the `state(..)` helper from earlier, `ASQ.csp.go(..)` takes a generator -- in go/core.async terms, it's known as a goroutine -- and adapts it to use with `ASQ#runner(..)` by returning a new generator.\n\nInstead of being passed a `token`, your goroutine receives an initially created channel (`ch` below) that all goroutines in this run will share. You can create more channels (which is often quite helpful!) with `ASQ.csp.chan(..)`.\n\nIn CSP, we model all asynchrony in terms of blocking on channel messages, rather than blocking waiting for a Promise/sequence/thunk to complete.\n\nSo, instead of `yield`ing the Promise returned from `request(..)`, `request(..)` should return a channel that you `take(..)` a value from. In other words, a single-value channel is roughly equivalent in this context/usage to a Promise/sequence.\n\nLet's first make a channel-aware version of `request(..)`:\n\n```js\nfunction request(url) {\n\tvar ch = ASQ.csp.channel();\n\tajax( url ).then( function(content){\n\t\t// `putAsync(..)` is a version of `put(..)` that\n\t\t// can be used outside of a generator. It returns\n\t\t// a promise for the operation's completion. We\n\t\t// don't use that promise here, but we could if\n\t\t// we needed to be notified when the value had\n\t\t// been `take(..)`n.\n\t\tASQ.csp.putAsync( ch, content );\n\t} );\n\treturn ch;\n}\n```\n\nFrom Chapter 3, \"promisory\" is a Promise-producing utility, \"thunkory\" from Chapter 4 is a thunk-producing utility, and finally, in Appendix A we invented \"sequory\" for a sequence-producing utility.\n\nNaturally, we need to coin a symmetric term here for a channel-producing utility. So let's unsurprisingly call it a \"chanory\" (\"channel\" + \"factory\"). As an exercise for the reader, try your hand at defining a `channelify(..)` utility similar to `Promise.wrap(..)`/`promisify(..)` (Chapter 3), `thunkify(..)` (Chapter 4), and `ASQ.wrap(..)` (Appendix A).\n\nNow consider the concurrent Ajax example using *asyquence*-flavored CSP:\n\n```js\nASQ()\n.runner(\n\tASQ.csp.go( function*(ch){\n\t\tyield ASQ.csp.put( ch, \"http://some.url.2\" );\n\n\t\tvar url1 = yield ASQ.csp.take( ch );\n\t\t// \"http://some.url.1\"\n\n\t\tvar res1 = yield ASQ.csp.take( request( url1 ) );\n\n\t\tyield ASQ.csp.put( ch, res1 );\n\t} ),\n\tASQ.csp.go( function*(ch){\n\t\tvar url2 = yield ASQ.csp.take( ch );\n\t\t// \"http://some.url.2\"\n\n\t\tyield ASQ.csp.put( ch, \"http://some.url.1\" );\n\n\t\tvar res2 = yield ASQ.csp.take( request( url2 ) );\n\t\tvar res1 = yield ASQ.csp.take( ch );\n\n\t\t// pass along results to next sequence step\n\t\tch.buffer_size = 2;\n\t\tASQ.csp.put( ch, res1 );\n\t\tASQ.csp.put( ch, res2 );\n\t} )\n)\n.val( function(res1,res2){\n\t// `res1` comes from \"http://some.url.1\"\n\t// `res2` comes from \"http://some.url.2\"\n} );\n```\n\nThe message passing that trades the URL strings between the two goroutines is pretty straightforward. The first goroutine makes an Ajax request to the first URL, and that response is put onto the `ch` channel. The second goroutine makes an Ajax request to the second URL, then gets the first response `res1` off the `ch` channel. At that point, both responses `res1` and `res2` are completed and ready.\n\nIf there are any remaining values in the `ch` channel at the end of the goroutine run, they will be passed along to the next step in the sequence. So, to pass out message(s) from the final goroutine, `put(..)` them into `ch`. As shown, to avoid the blocking of those final `put(..)`s, we switch `ch` into buffering mode by setting its `buffer_size` to `2` (default: `0`).\n\n**Note:** See many more examples of using *asynquence*-flavored CSP here (https://gist.github.com/getify/e0d04f1f5aa24b1947ae).\n\n## Review\n\nPromises and generators provide the foundational building blocks upon which we can build much more sophisticated and capable asynchrony.\n\n*asynquence* has utilities for implementing *iterable sequences*, *reactive sequences* (aka \"Observables\"), *concurrent coroutines*, and even *CSP goroutines*.\n\nThose patterns, combined with the continuation-callback and Promise capabilities, gives *asynquence* a powerful mix of different asynchronous functionalities, all integrated in one clean async flow control abstraction: the sequence.\n"
},
{
"path": "async & performance/apC.md",
"content": "# You Don't Know JS: Async & Performance\n# Appendix C: Acknowledgments\n\nI have many people to thank for making this book title and the overall series happen.\n\nFirst, I must thank my wife Christen Simpson, and my two kids Ethan and Emily, for putting up with Dad always pecking away at the computer. Even when not writing books, my obsession with JavaScript glues my eyes to the screen far more than it should. That time I borrow from my family is the reason these books can so deeply and completely explain JavaScript to you, the reader. I owe my family everything.\n\nI'd like to thank my editors at O'Reilly, namely Simon St.Laurent and Brian MacDonald, as well as the rest of the editorial and marketing staff. They are fantastic to work with, and have been especially accommodating during this experiment into \"open source\" book writing, editing, and production.\n\nThank you to the many folks who have participated in making this book series better by providing editorial suggestions and corrections, including Shelley Powers, Tim Ferro, Evan Borden, Forrest L. Norvell, Jennifer Davis, Jesse Harlin, Kris Kowal, Rick Waldron, Jordan Harband, Benjamin Gruenbaum, Vyacheslav Egorov, David Nolen, and many others. A big thank you to Jake Archibald for writing the Foreword for this title.\n\nThank you to the countless folks in the community, including members of the TC39 committee, who have shared so much knowledge with the rest of us, and especially tolerated my incessant questions and explorations with patience and detail. John-David Dalton, Juriy \"kangax\" Zaytsev, Mathias Bynens, Axel Rauschmayer, Nicholas Zakas, Angus Croll, Reginald Braithwaite, Dave Herman, Brendan Eich, Allen Wirfs-Brock, Bradley Meck, Domenic Denicola, David Walsh, Tim Disney, Peter van der Zee, Andrea Giammarchi, Kit Cambridge, Eric Elliott, and so many others, I can't even scratch the surface.\n\nThe *You Don't Know JS* book series was born on Kickstarter, so I also wish to thank all my (nearly) 500 generous backers, without whom this book series could not have happened:\n\n> Jan Szpila, nokiko, Murali Krishnamoorthy, Ryan Joy, Craig Patchett, pdqtrader, Dale Fukami, ray hatfield, R0drigo Perez [Mx], Dan Petitt, Jack Franklin, Andrew Berry, Brian Grinstead, Rob Sutherland, Sergi Meseguer, Phillip Gourley, Mark Watson, Jeff Carouth, Alfredo Sumaran, Martin Sachse, Marcio Barrios, Dan, AimelyneM, Matt Sullivan, Delnatte Pierre-Antoine, Jake Smith, Eugen Tudorancea, Iris, David Trinh, simonstl, Ray Daly, Uros Gruber, Justin Myers, Shai Zonis, Mom & Dad, Devin Clark, Dennis Palmer, Brian Panahi Johnson, Josh Marshall, Marshall, Dennis Kerr, Matt Steele, Erik Slagter, Sacah, Justin Rainbow, Christian Nilsson, Delapouite, D.Pereira, Nicolas Hoizey, George V. Reilly, Dan Reeves, Bruno Laturner, Chad Jennings, Shane King, Jeremiah Lee Cohick, od3n, Stan Yamane, Marko Vucinic, Jim B, Stephen Collins, Ægir Þorsteinsson, Eric Pederson, Owain, Nathan Smith, Jeanetteurphy, Alexandre ELISÉ, Chris Peterson, Rik Watson, Luke Matthews, Justin Lowery, Morten Nielsen, Vernon Kesner, Chetan Shenoy, Paul Tregoing, Marc Grabanski, Dion Almaer, Andrew Sullivan, Keith Elsass, Tom Burke, Brian Ashenfelter, David Stuart, Karl Swedberg, Graeme, Brandon Hays, John Christopher, Gior, manoj reddy, Chad Smith, Jared Harbour, Minoru TODA, Chris Wigley, Daniel Mee, Mike, Handyface, Alex Jahraus, Carl Furrow, Rob Foulkrod, Max Shishkin, Leigh Penny Jr., Robert Ferguson, Mike van Hoenselaar, Hasse Schougaard, rajan venkataguru, Jeff Adams, Trae Robbins, Rolf Langenhuijzen, Jorge Antunes, Alex Koloskov, Hugh Greenish, Tim Jones, Jose Ochoa, Michael Brennan-White, Naga Harish Muvva, Barkóczi Dávid, Kitt Hodsden, Paul McGraw, Sascha Goldhofer, Andrew Metcalf, Markus Krogh, Michael Mathews, Matt Jared, Juanfran, Georgie Kirschner, Kenny Lee, Ted Zhang, Amit Pahwa, Inbal Sinai, Dan Raine, Schabse Laks, Michael Tervoort, Alexandre Abreu, Alan Joseph Williams, NicolasD, Cindy Wong, Reg Braithwaite, LocalPCGuy, Jon Friskics, Chris Merriman, John Pena, Jacob Katz, Sue Lockwood, Magnus Johansson, Jeremy Crapsey, Grzegorz Pawłowski, nico nuzzaci, Christine Wilks, Hans Bergren, charles montgomery, Ariel בר-לבב Fogel, Ivan Kolev, Daniel Campos, Hugh Wood, Christian Bradford, Frédéric Harper, Ionuţ Dan Popa, Jeff Trimble, Rupert Wood, Trey Carrico, Pancho Lopez, Joël kuijten, Tom A Marra, Jeff Jewiss, Jacob Rios, Paolo Di Stefano, Soledad Penades, Chris Gerber, Andrey Dolganov, Wil Moore III, Thomas Martineau, Kareem, Ben Thouret, Udi Nir, Morgan Laupies, jory carson-burson, Nathan L Smith, Eric Damon Walters, Derry Lozano-Hoyland, Geoffrey Wiseman, mkeehner, KatieK, Scott MacFarlane, Brian LaShomb, Adrien Mas, christopher ross, Ian Littman, Dan Atkinson, Elliot Jobe, Nick Dozier, Peter Wooley, John Hoover, dan, Martin A. Jackson, Héctor Fernando Hurtado, andy ennamorato, Paul Seltmann, Melissa Gore, Dave Pollard, Jack Smith, Philip Da Silva, Guy Israeli, @megalithic, Damian Crawford, Felix Gliesche, April Carter Grant, Heidi, jim tierney, Andrea Giammarchi, Nico Vignola, Don Jones, Chris Hartjes, Alex Howes, john gibbon, David J. Groom, BBox, Yu 'Dilys' Sun, Nate Steiner, Brandon Satrom, Brian Wyant, Wesley Hales, Ian Pouncey, Timothy Kevin Oxley, George Terezakis, sanjay raj, Jordan Harband, Marko McLion, Wolfgang Kaufmann, Pascal Peuckert, Dave Nugent, Markus Liebelt, Welling Guzman, Nick Cooley, Daniel Mesquita, Robert Syvarth, Chris Coyier, Rémy Bach, Adam Dougal, Alistair Duggin, David Loidolt, Ed Richer, Brian Chenault, GoldFire Studios, Carles Andrés, Carlos Cabo, Yuya Saito, roberto ricardo, Barnett Klane, Mike Moore, Kevin Marx, Justin Love, Joe Taylor, Paul Dijou, Michael Kohler, Rob Cassie, Mike Tierney, Cody Leroy Lindley, tofuji, Shimon Schwartz, Raymond, Luc De Brouwer, David Hayes, Rhys Brett-Bowen, Dmitry, Aziz Khoury, Dean, Scott Tolinski - Level Up, Clement Boirie, Djordje Lukic, Anton Kotenko, Rafael Corral, Philip Hurwitz, Jonathan Pidgeon, Jason Campbell, Joseph C., SwiftOne, Jan Hohner, Derick Bailey, getify, Daniel Cousineau, Chris Charlton, Eric Turner, David Turner, Joël Galeran, Dharma Vagabond, adam, Dirk van Bergen, dave ♥♫★ furf, Vedran Zakanj, Ryan McAllen, Natalie Patrice Tucker, Eric J. Bivona, Adam Spooner, Aaron Cavano, Kelly Packer, Eric J, Martin Drenovac, Emilis, Michael Pelikan, Scott F. Walter, Josh Freeman, Brandon Hudgeons, vijay chennupati, Bill Glennon, Robin R., Troy Forster, otaku_coder, Brad, Scott, Frederick Ostrander, Adam Brill, Seb Flippence, Michael Anderson, Jacob, Adam Randlett, Standard, Joshua Clanton, Sebastian Kouba, Chris Deck, SwordFire, Hannes Papenberg, Richard Woeber, hnzz, Rob Crowther, Jedidiah Broadbent, Sergey Chernyshev, Jay-Ar Jamon, Ben Combee, luciano bonachela, Mark Tomlinson, Kit Cambridge, Michael Melgares, Jacob Adams, Adrian Bruinhout, Bev Wieber, Scott Puleo, Thomas Herzog, April Leone, Daniel Mizieliński, Kees van Ginkel, Jon Abrams, Erwin Heiser, Avi Laviad, David newell, Jean-Francois Turcot, Niko Roberts, Erik Dana, Charles Neill, Aaron Holmes, Grzegorz Ziółkowski, Nathan Youngman, Timothy, Jacob Mather, Michael Allan, Mohit Seth, Ryan Ewing, Benjamin Van Treese, Marcelo Santos, Denis Wolf, Phil Keys, Chris Yung, Timo Tijhof, Martin Lekvall, Agendine, Greg Whitworth, Helen Humphrey, Dougal Campbell, Johannes Harth, Bruno Girin, Brian Hough, Darren Newton, Craig McPheat, Olivier Tille, Dennis Roethig, Mathias Bynens, Brendan Stromberger, sundeep, John Meyer, Ron Male, John F Croston III, gigante, Carl Bergenhem, B.J. May, Rebekah Tyler, Ted Foxberry, Jordan Reese, Terry Suitor, afeliz, Tom Kiefer, Darragh Duffy, Kevin Vanderbeken, Andy Pearson, Simon Mac Donald, Abid Din, Chris Joel, Tomas Theunissen, David Dick, Paul Grock, Brandon Wood, John Weis, dgrebb, Nick Jenkins, Chuck Lane, Johnny Megahan, marzsman, Tatu Tamminen, Geoffrey Knauth, Alexander Tarmolov, Jeremy Tymes, Chad Auld, Sean Parmelee, Rob Staenke, Dan Bender, Yannick derwa, Joshua Jones, Geert Plaisier, Tom LeZotte, Christen Simpson, Stefan Bruvik, Justin Falcone, Carlos Santana, Michael Weiss, Pablo Villoslada, Peter deHaan, Dimitris Iliopoulos, seyDoggy, Adam Jordens, Noah Kantrowitz, Amol M, Matthew Winnard, Dirk Ginader, Phinam Bui, David Rapson, Andrew Baxter, Florian Bougel, Michael George, Alban Escalier, Daniel Sellers, Sasha Rudan, John Green, Robert Kowalski, David I. Teixeira (@ditma, Charles Carpenter, Justin Yost, Sam S, Denis Ciccale, Kevin Sheurs, Yannick Croissant, Pau Fracés, Stephen McGowan, Shawn Searcy, Chris Ruppel, Kevin Lamping, Jessica Campbell, Christopher Schmitt, Sablons, Jonathan Reisdorf, Bunni Gek, Teddy Huff, Michael Mullany, Michael Fürstenberg, Carl Henderson, Rick Yoesting, Scott Nichols, Hernán Ciudad, Andrew Maier, Mike Stapp, Jesse Shawl, Sérgio Lopes, jsulak, Shawn Price, Joel Clermont, Chris Ridmann, Sean Timm, Jason Finch, Aiden Montgomery, Elijah Manor, Derek Gathright, Jesse Harlin, Dillon Curry, Courtney Myers, Diego Cadenas, Arne de Bree, João Paulo Dubas, James Taylor, Philipp Kraeutli, Mihai Păun, Sam Gharegozlou, joshjs, Matt Murchison, Eric Windham, Timo Behrmann, Andrew Hall, joshua price, Théophile Villard\n\nThis book series is being produced in an open source fashion, including editing and production. We owe GitHub a debt of gratitude for making that sort of thing possible for the community!\n\nThank you again to all the countless folks I didn't name but who I nonetheless owe thanks. May this book series be \"owned\" by all of us and serve to contribute to increasing awareness and understanding of the JavaScript language, to the benefit of all current and future community contributors.\n"
},
{
"path": "async & performance/ch1.md",
"content": "# You Don't Know JS: Async & Performance\n# Chapter 1: Asynchrony: Now & Later\n\nOne of the most important and yet often misunderstood parts of programming in a language like JavaScript is how to express and manipulate program behavior spread out over a period of time.\n\nThis is not just about what happens from the beginning of a `for` loop to the end of a `for` loop, which of course takes *some time* (microseconds to milliseconds) to complete. It's about what happens when part of your program runs *now*, and another part of your program runs *later* -- there's a gap between *now* and *later* where your program isn't actively executing.\n\nPractically all nontrivial programs ever written (especially in JS) have in some way or another had to manage this gap, whether that be in waiting for user input, requesting data from a database or file system, sending data across the network and waiting for a response, or performing a repeated task at a fixed interval of time (like animation). In all these various ways, your program has to manage state across the gap in time. As they famously say in London (of the chasm between the subway door and the platform): \"mind the gap.\"\n\nIn fact, the relationship between the *now* and *later* parts of your program is at the heart of asynchronous programming.\n\nAsynchronous programming has been around since the beginning of JS, for sure. But most JS developers have never really carefully considered exactly how and why it crops up in their programs, or explored various *other* ways to handle it. The *good enough* approach has always been the humble callback function. Many to this day will insist that callbacks are more than sufficient.\n\nBut as JS continues to grow in both scope and complexity, to meet the ever-widening demands of a first-class programming language that runs in browsers and servers and every conceivable device in between, the pains by which we manage asynchrony are becoming increasingly crippling, and they cry out for approaches that are both more capable and more reason-able.\n\nWhile this all may seem rather abstract right now, I assure you we'll tackle it more completely and concretely as we go on through this book. We'll explore a variety of emerging techniques for async JavaScript programming over the next several chapters.\n\nBut before we can get there, we're going to have to understand much more deeply what asynchrony is and how it operates in JS.\n\n## A Program in Chunks\n\nYou may write your JS program in one *.js* file, but your program is almost certainly comprised of several chunks, only one of which is going to execute *now*, and the rest of which will execute *later*. The most common unit of *chunk* is the `function`.\n\nThe problem most developers new to JS seem to have is that *later* doesn't happen strictly and immediately after *now*. In other words, tasks that cannot complete *now* are, by definition, going to complete asynchronously, and thus we will not have blocking behavior as you might intuitively expect or want.\n\nConsider:\n\n```js\n// ajax(..) is some arbitrary Ajax function given by a library\nvar data = ajax( \"http://some.url.1\" );\n\nconsole.log( data );\n// Oops! `data` generally won't have the Ajax results\n```\n\nYou're probably aware that standard Ajax requests don't complete synchronously, which means the `ajax(..)` function does not yet have any value to return back to be assigned to `data` variable. If `ajax(..)` *could* block until the response came back, then the `data = ..` assignment would work fine.\n\nBut that's not how we do Ajax. We make an asynchronous Ajax request *now*, and we won't get the results back until *later*.\n\nThe simplest (but definitely not only, or necessarily even best!) way of \"waiting\" from *now* until *later* is to use a function, commonly called a callback function:\n\n```js\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", function myCallbackFunction(data){\n\n\tconsole.log( data ); // Yay, I gots me some `data`!\n\n} );\n```\n\n**Warning:** You may have heard that it's possible to make synchronous Ajax requests. While that's technically true, you should never, ever do it, under any circumstances, because it locks the browser UI (buttons, menus, scrolling, etc.) and prevents any user interaction whatsoever. This is a terrible idea, and should always be avoided.\n\nBefore you protest in disagreement, no, your desire to avoid the mess of callbacks is *not* justification for blocking, synchronous Ajax.\n\nFor example, consider this code:\n\n```js\nfunction now() {\n\treturn 21;\n}\n\nfunction later() {\n\tanswer = answer * 2;\n\tconsole.log( \"Meaning of life:\", answer );\n}\n\nvar answer = now();\n\nsetTimeout( later, 1000 ); // Meaning of life: 42\n```\n\nThere are two chunks to this program: the stuff that will run *now*, and the stuff that will run *later*. It should be fairly obvious what those two chunks are, but let's be super explicit:\n\nNow:\n```js\nfunction now() {\n\treturn 21;\n}\n\nfunction later() { .. }\n\nvar answer = now();\n\nsetTimeout( later, 1000 );\n```\n\nLater:\n```js\nanswer = answer * 2;\nconsole.log( \"Meaning of life:\", answer );\n```\n\nThe *now* chunk runs right away, as soon as you execute your program. But `setTimeout(..)` also sets up an event (a timeout) to happen *later*, so the contents of the `later()` function will be executed at a later time (1,000 milliseconds from now).\n\nAny time you wrap a portion of code into a `function` and specify that it should be executed in response to some event (timer, mouse click, Ajax response, etc.), you are creating a *later* chunk of your code, and thus introducing asynchrony to your program.\n\n### Async Console\n\nThere is no specification or set of requirements around how the `console.*` methods work -- they are not officially part of JavaScript, but are instead added to JS by the *hosting environment* (see the *Types & Grammar* title of this book series).\n\nSo, different browsers and JS environments do as they please, which can sometimes lead to confusing behavior.\n\nIn particular, there are some browsers and some conditions that `console.log(..)` does not actually immediately output what it's given. The main reason this may happen is because I/O is a very slow and blocking part of many programs (not just JS). So, it may perform better (from the page/UI perspective) for a browser to handle `console` I/O asynchronously in the background, without you perhaps even knowing that occurred.\n\nA not terribly common, but possible, scenario where this could be *observable* (not from code itself but from the outside):\n\n```js\nvar a = {\n\tindex: 1\n};\n\n// later\nconsole.log( a ); // ??\n\n// even later\na.index++;\n```\n\nWe'd normally expect to see the `a` object be snapshotted at the exact moment of the `console.log(..)` statement, printing something like `{ index: 1 }`, such that in the next statement when `a.index++` happens, it's modifying something different than, or just strictly after, the output of `a`.\n\nMost of the time, the preceding code will probably produce an object representation in your developer tools' console that's what you'd expect. But it's possible this same code could run in a situation where the browser felt it needed to defer the console I/O to the background, in which case it's *possible* that by the time the object is represented in the browser console, the `a.index++` has already happened, and it shows `{ index: 2 }`.\n\nIt's a moving target under what conditions exactly `console` I/O will be deferred, or even whether it will be observable. Just be aware of this possible asynchronicity in I/O in case you ever run into issues in debugging where objects have been modified *after* a `console.log(..)` statement and yet you see the unexpected modifications show up.\n\n**Note:** If you run into this rare scenario, the best option is to use breakpoints in your JS debugger instead of relying on `console` output. The next best option would be to force a \"snapshot\" of the object in question by serializing it to a `string`, like with `JSON.stringify(..)`.\n\n## Event Loop\n\nLet's make a (perhaps shocking) claim: despite clearly allowing asynchronous JS code (like the timeout we just looked at), up until recently (ES6), JavaScript itself has actually never had any direct notion of asynchrony built into it.\n\n**What!?** That seems like a crazy claim, right? In fact, it's quite true. The JS engine itself has never done anything more than execute a single chunk of your program at any given moment, when asked to.\n\n\"Asked to.\" By whom? That's the important part!\n\nThe JS engine doesn't run in isolation. It runs inside a *hosting environment*, which is for most developers the typical web browser. Over the last several years (but by no means exclusively), JS has expanded beyond the browser into other environments, such as servers, via things like Node.js. In fact, JavaScript gets embedded into all kinds of devices these days, from robots to lightbulbs.\n\nBut the one common \"thread\" (that's a not-so-subtle asynchronous joke, for what it's worth) of all these environments is that they have a mechanism in them that handles executing multiple chunks of your program *over time*, at each moment invoking the JS engine, called the \"event loop.\"\n\nIn other words, the JS engine has had no innate sense of *time*, but has instead been an on-demand execution environment for any arbitrary snippet of JS. It's the surrounding environment that has always *scheduled* \"events\" (JS code executions).\n\nSo, for example, when your JS program makes an Ajax request to fetch some data from a server, you set up the \"response\" code in a function (commonly called a \"callback\"), and the JS engine tells the hosting environment, \"Hey, I'm going to suspend execution for now, but whenever you finish with that network request, and you have some data, please *call* this function *back*.\"\n\nThe browser is then set up to listen for the response from the network, and when it has something to give you, it schedules the callback function to be executed by inserting it into the *event loop*.\n\nSo what is the *event loop*?\n\nLet's conceptualize it first through some fake-ish code:\n\n```js\n// `eventLoop` is an array that acts as a queue (first-in, first-out)\nvar eventLoop = [ ];\nvar event;\n\n// keep going \"forever\"\nwhile (true) {\n\t// perform a \"tick\"\n\tif (eventLoop.length > 0) {\n\t\t// get the next event in the queue\n\t\tevent = eventLoop.shift();\n\n\t\t// now, execute the next event\n\t\ttry {\n\t\t\tevent();\n\t\t}\n\t\tcatch (err) {\n\t\t\treportError(err);\n\t\t}\n\t}\n}\n```\n\nThis is, of course, vastly simplified pseudocode to illustrate the concepts. But it should be enough to help get a better understanding.\n\nAs you can see, there's a continuously running loop represented by the `while` loop, and each iteration of this loop is called a \"tick.\" For each tick, if an event is waiting on the queue, it's taken off and executed. These events are your function callbacks.\n\nIt's important to note that `setTimeout(..)` doesn't put your callback on the event loop queue. What it does is set up a timer; when the timer expires, the environment places your callback into the event loop, such that some future tick will pick it up and execute it.\n\nWhat if there are already 20 items in the event loop at that moment? Your callback waits. It gets in line behind the others -- there's not normally a path for preempting the queue and skipping ahead in line. This explains why `setTimeout(..)` timers may not fire with perfect temporal accuracy. You're guaranteed (roughly speaking) that your callback won't fire *before* the time interval you specify, but it can happen at or after that time, depending on the state of the event queue.\n\nSo, in other words, your program is generally broken up into lots of small chunks, which happen one after the other in the event loop queue. And technically, other events not related directly to your program can be interleaved within the queue as well.\n\n**Note:** We mentioned \"up until recently\" in relation to ES6 changing the nature of where the event loop queue is managed. It's mostly a formal technicality, but ES6 now specifies how the event loop works, which means technically it's within the purview of the JS engine, rather than just the *hosting environment*. One main reason for this change is the introduction of ES6 Promises, which we'll discuss in Chapter 3, because they require the ability to have direct, fine-grained control over scheduling operations on the event loop queue (see the discussion of `setTimeout(..0)` in the \"Cooperation\" section).\n\n## Parallel Threading\n\nIt's very common to conflate the terms \"async\" and \"parallel,\" but they are actually quite different. Remember, async is about the gap between *now* and *later*. But parallel is about things being able to occur simultaneously.\n\nThe most common tools for parallel computing are processes and threads. Processes and threads execute independently and may execute simultaneously: on separate processors, or even separate computers, but multiple threads can share the memory of a single process.\n\nAn event loop, by contrast, breaks its work into tasks and executes them in serial, disallowing parallel access and changes to shared memory. Parallelism and \"serialism\" can coexist in the form of cooperating event loops in separate threads.\n\nThe interleaving of parallel threads of execution and the interleaving of asynchronous events occur at very different levels of granularity.\n\nFor example:\n\n```js\nfunction later() {\n\tanswer = answer * 2;\n\tconsole.log( \"Meaning of life:\", answer );\n}\n```\n\nWhile the entire contents of `later()` would be regarded as a single event loop queue entry, when thinking about a thread this code would run on, there's actually perhaps a dozen different low-level operations. For example, `answer = answer * 2` requires first loading the current value of `answer`, then putting `2` somewhere, then performing the multiplication, then taking the result and storing it back into `answer`.\n\nIn a single-threaded environment, it really doesn't matter that the items in the thread queue are low-level operations, because nothing can interrupt the thread. But if you have a parallel system, where two different threads are operating in the same program, you could very likely have unpredictable behavior.\n\nConsider:\n\n```js\nvar a = 20;\n\nfunction foo() {\n\ta = a + 1;\n}\n\nfunction bar() {\n\ta = a * 2;\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nIn JavaScript's single-threaded behavior, if `foo()` runs before `bar()`, the result is that `a` has `42`, but if `bar()` runs before `foo()` the result in `a` will be `41`.\n\nIf JS events sharing the same data executed in parallel, though, the problems would be much more subtle. Consider these two lists of pseudocode tasks as the threads that could respectively run the code in `foo()` and `bar()`, and consider what happens if they are running at exactly the same time:\n\nThread 1 (`X` and `Y` are temporary memory locations):\n```\nfoo():\n a. load value of `a` in `X`\n b. store `1` in `Y`\n c. add `X` and `Y`, store result in `X`\n d. store value of `X` in `a`\n```\n\nThread 2 (`X` and `Y` are temporary memory locations):\n```\nbar():\n a. load value of `a` in `X`\n b. store `2` in `Y`\n c. multiply `X` and `Y`, store result in `X`\n d. store value of `X` in `a`\n```\n\nNow, let's say that the two threads are running truly in parallel. You can probably spot the problem, right? They use shared memory locations `X` and `Y` for their temporary steps.\n\nWhat's the end result in `a` if the steps happen like this?\n\n```\n1a (load value of `a` in `X` ==> `20`)\n2a (load value of `a` in `X` ==> `20`)\n1b (store `1` in `Y` ==> `1`)\n2b (store `2` in `Y` ==> `2`)\n1c (add `X` and `Y`, store result in `X` ==> `22`)\n1d (store value of `X` in `a` ==> `22`)\n2c (multiply `X` and `Y`, store result in `X` ==> `44`)\n2d (store value of `X` in `a` ==> `44`)\n```\n\nThe result in `a` will be `44`. But what about this ordering?\n\n```\n1a (load value of `a` in `X` ==> `20`)\n2a (load value of `a` in `X` ==> `20`)\n2b (store `2` in `Y` ==> `2`)\n1b (store `1` in `Y` ==> `1`)\n2c (multiply `X` and `Y`, store result in `X` ==> `20`)\n1c (add `X` and `Y`, store result in `X` ==> `21`)\n1d (store value of `X` in `a` ==> `21`)\n2d (store value of `X` in `a` ==> `21`)\n```\n\nThe result in `a` will be `21`.\n\nSo, threaded programming is very tricky, because if you don't take special steps to prevent this kind of interruption/interleaving from happening, you can get very surprising, nondeterministic behavior that frequently leads to headaches.\n\nJavaScript never shares data across threads, which means *that* level of nondeterminism isn't a concern. But that doesn't mean JS is always deterministic. Remember earlier, where the relative ordering of `foo()` and `bar()` produces two different results (`41` or `42`)?\n\n**Note:** It may not be obvious yet, but not all nondeterminism is bad. Sometimes it's irrelevant, and sometimes it's intentional. We'll see more examples of that throughout this and the next few chapters.\n\n### Run-to-Completion\n\nBecause of JavaScript's single-threading, the code inside of `foo()` (and `bar()`) is atomic, which means that once `foo()` starts running, the entirety of its code will finish before any of the code in `bar()` can run, or vice versa. This is called \"run-to-completion\" behavior.\n\nIn fact, the run-to-completion semantics are more obvious when `foo()` and `bar()` have more code in them, such as:\n\n```js\nvar a = 1;\nvar b = 2;\n\nfunction foo() {\n\ta++;\n\tb = b * a;\n\ta = b + 3;\n}\n\nfunction bar() {\n\tb--;\n\ta = 8 + b;\n\tb = a * 2;\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\nBecause `foo()` can't be interrupted by `bar()`, and `bar()` can't be interrupted by `foo()`, this program only has two possible outcomes depending on which starts running first -- if threading were present, and the individual statements in `foo()` and `bar()` could be interleaved, the number of possible outcomes would be greatly increased!\n\nChunk 1 is synchronous (happens *now*), but chunks 2 and 3 are asynchronous (happen *later*), which means their execution will be separated by a gap of time.\n\nChunk 1:\n```js\nvar a = 1;\nvar b = 2;\n```\n\nChunk 2 (`foo()`):\n```js\na++;\nb = b * a;\na = b + 3;\n```\n\nChunk 3 (`bar()`):\n```js\nb--;\na = 8 + b;\nb = a * 2;\n```\n\nChunks 2 and 3 may happen in either-first order, so there are two possible outcomes for this program, as illustrated here:\n\nOutcome 1:\n```js\nvar a = 1;\nvar b = 2;\n\n// foo()\na++;\nb = b * a;\na = b + 3;\n\n// bar()\nb--;\na = 8 + b;\nb = a * 2;\n\na; // 11\nb; // 22\n```\n\nOutcome 2:\n```js\nvar a = 1;\nvar b = 2;\n\n// bar()\nb--;\na = 8 + b;\nb = a * 2;\n\n// foo()\na++;\nb = b * a;\na = b + 3;\n\na; // 183\nb; // 180\n```\n\nTwo outcomes from the same code means we still have nondeterminism! But it's at the function (event) ordering level, rather than at the statement ordering level (or, in fact, the expression operation ordering level) as it is with threads. In other words, it's *more deterministic* than threads would have been.\n\nAs applied to JavaScript's behavior, this function-ordering nondeterminism is the common term \"race condition,\" as `foo()` and `bar()` are racing against each other to see which runs first. Specifically, it's a \"race condition\" because you cannot predict reliably how `a` and `b` will turn out.\n\n**Note:** If there was a function in JS that somehow did not have run-to-completion behavior, we could have many more possible outcomes, right? It turns out ES6 introduces just such a thing (see Chapter 4 \"Generators\"), but don't worry right now, we'll come back to that!\n\n## Concurrency\n\nLet's imagine a site that displays a list of status updates (like a social network news feed) that progressively loads as the user scrolls down the list. To make such a feature work correctly, (at least) two separate \"processes\" will need to be executing *simultaneously* (i.e., during the same window of time, but not necessarily at the same instant).\n\n**Note:** We're using \"process\" in quotes here because they aren't true operating system–level processes in the computer science sense. They're virtual processes, or tasks, that represent a logically connected, sequential series of operations. We'll simply prefer \"process\" over \"task\" because terminology-wise, it will match the definitions of the concepts we're exploring.\n\nThe first \"process\" will respond to `onscroll` events (making Ajax requests for new content) as they fire when the user has scrolled the page further down. The second \"process\" will receive Ajax responses back (to render content onto the page).\n\nObviously, if a user scrolls fast enough, you may see two or more `onscroll` events fired during the time it takes to get the first response back and process, and thus you're going to have `onscroll` events and Ajax response events firing rapidly, interleaved with each other.\n\nConcurrency is when two or more \"processes\" are executing simultaneously over the same period, regardless of whether their individual constituent operations happen *in parallel* (at the same instant on separate processors or cores) or not. You can think of concurrency then as \"process\"-level (or task-level) parallelism, as opposed to operation-level parallelism (separate-processor threads).\n\n**Note:** Concurrency also introduces an optional notion of these \"processes\" interacting with each other. We'll come back to that later.\n\nFor a given window of time (a few seconds worth of a user scrolling), let's visualize each independent \"process\" as a series of events/operations:\n\n\"Process\" 1 (`onscroll` events):\n```\nonscroll, request 1\nonscroll, request 2\nonscroll, request 3\nonscroll, request 4\nonscroll, request 5\nonscroll, request 6\nonscroll, request 7\n```\n\n\"Process\" 2 (Ajax response events):\n```\nresponse 1\nresponse 2\nresponse 3\nresponse 4\nresponse 5\nresponse 6\nresponse 7\n```\n\nIt's quite possible that an `onscroll` event and an Ajax response event could be ready to be processed at exactly the same *moment*. For example, let's visualize these events in a timeline:\n\n```\nonscroll, request 1\nonscroll, request 2 response 1\nonscroll, request 3 response 2\nresponse 3\nonscroll, request 4\nonscroll, request 5\nonscroll, request 6 response 4\nonscroll, request 7\nresponse 6\nresponse 5\nresponse 7\n```\n\nBut, going back to our notion of the event loop from earlier in the chapter, JS is only going to be able to handle one event at a time, so either `onscroll, request 2` is going to happen first or `response 1` is going to happen first, but they cannot happen at literally the same moment. Just like kids at a school cafeteria, no matter what crowd they form outside the doors, they'll have to merge into a single line to get their lunch!\n\nLet's visualize the interleaving of all these events onto the event loop queue.\n\nEvent Loop Queue:\n```\nonscroll, request 1 <--- Process 1 starts\nonscroll, request 2\nresponse 1 <--- Process 2 starts\nonscroll, request 3\nresponse 2\nresponse 3\nonscroll, request 4\nonscroll, request 5\nonscroll, request 6\nresponse 4\nonscroll, request 7 <--- Process 1 finishes\nresponse 6\nresponse 5\nresponse 7 <--- Process 2 finishes\n```\n\n\"Process 1\" and \"Process 2\" run concurrently (task-level parallel), but their individual events run sequentially on the event loop queue.\n\nBy the way, notice how `response 6` and `response 5` came back out of expected order?\n\nThe single-threaded event loop is one expression of concurrency (there are certainly others, which we'll come back to later).\n\n### Noninteracting\n\nAs two or more \"processes\" are interleaving their steps/events concurrently within the same program, they don't necessarily need to interact with each other if the tasks are unrelated. **If they don't interact, nondeterminism is perfectly acceptable.**\n\nFor example:\n\n```js\nvar res = {};\n\nfunction foo(results) {\n\tres.foo = results;\n}\n\nfunction bar(results) {\n\tres.bar = results;\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", foo );\najax( \"http://some.url.2\", bar );\n```\n\n`foo()` and `bar()` are two concurrent \"processes,\" and it's nondeterminate which order they will be fired in. But we've constructed the program so it doesn't matter what order they fire in, because they act independently and as such don't need to interact.\n\nThis is not a \"race condition\" bug, as the code will always work correctly, regardless of the ordering.\n\n### Interaction\n\nMore commonly, concurrent \"processes\" will by necessity interact, indirectly through scope and/or the DOM. When such interaction will occur, you need to coordinate these interactions to prevent \"race conditions,\" as described earlier.\n\nHere's a simple example of two concurrent \"processes\" that interact because of implied ordering, which is only *sometimes broken*:\n\n```js\nvar res = [];\n\nfunction response(data) {\n\tres.push( data );\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", response );\najax( \"http://some.url.2\", response );\n```\n\nThe concurrent \"processes\" are the two `response()` calls that will be made to handle the Ajax responses. They can happen in either-first order.\n\nLet's assume the expected behavior is that `res[0]` has the results of the `\"http://some.url.1\"` call, and `res[1]` has the results of the `\"http://some.url.2\"` call. Sometimes that will be the case, but sometimes they'll be flipped, depending on which call finishes first. There's a pretty good likelihood that this nondeterminism is a \"race condition\" bug.\n\n**Note:** Be extremely wary of assumptions you might tend to make in these situations. For example, it's not uncommon for a developer to observe that `\"http://some.url.2\"` is \"always\" much slower to respond than `\"http://some.url.1\"`, perhaps by virtue of what tasks they're doing (e.g., one performing a database task and the other just fetching a static file), so the observed ordering seems to always be as expected. Even if both requests go to the same server, and *it* intentionally responds in a certain order, there's no *real* guarantee of what order the responses will arrive back in the browser.\n\nSo, to address such a race condition, you can coordinate ordering interaction:\n\n```js\nvar res = [];\n\nfunction response(data) {\n\tif (data.url == \"http://some.url.1\") {\n\t\tres[0] = data;\n\t}\n\telse if (data.url == \"http://some.url.2\") {\n\t\tres[1] = data;\n\t}\n}\n\n// ajax(..) is some arbitrary Ajax function given by a library\najax( \"http://some.url.1\", response );\najax( \"http://some.url.2\", response );\n```\n\nRegardless of which Ajax response comes back first, we inspect the `data.url` (assuming one is returned from the server, of course!) to figure out which position the response data should occupy in the `res` array. `res[0]` will always hold the `\"http://some.url.1\"` results and `res[1]` will always hold the `\"http://some.url.2\"` results. Through simple coordination, we eliminated the \"race condition\" nondeterminism.\n\nThe same reasoning from this scenario would apply if multiple concurrent function calls were interacting with each other through the shared DOM, like one updating the contents of a `