Article: async functions #3617

jakearchibald · 2016-10-06T16:24:12Z

I haven't proof-read this myself, and I don't really have an ending yet, but here it is.

addyosmani · 2016-10-06T16:32:49Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+
+{% include "web/_shared/contributors/jakearchibald.html" %}
+
+Async functions are enabled by default in Chrome 55 and they're quite frankly marvelous. They allow you to write promise-based code as if it were synchronous, but without blocking the main thread.


Async functions link to spec or MDN page?

I'm unsure about this one. The spec is kinda scary and there's no MDN page yet. Even then, would we want to link to an explaining article this early on in our explaining article?

addyosmani · 2016-10-06T16:43:10Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+### Workaround - regenerator
+
+If you're targeting older browsers, Babel can also transpile generators, allowing you to use async functions all the way down to IE8.
+


Thanks for calling out the path to older browser support here too. Link to Babel docs for transpiling generators here?

Oh yeah good point

addyosmani · 2016-10-06T16:45:04Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+## Example: Streaming a response
+
+Note: If you're unfamiliar with streaming, [check out my guide](https://jakearchibald.com/2016/streams-ftw/#streams-the-fetch-api){: .external}.
+


You just had to mention streams :P

Keep on streamin'

philipwalton · 2016-10-06T16:47:41Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+    }
+
+If you use the `async` keyword before a function definition, you can then use `await` within the function. When you `await` a promise, the function is paused until the promise settles. If the promise fulfills, you get the value back. If the promise rejects, the rejected value is thrown.


This is a nit, but do you want to say "resolves" instead of "fulfills"?

+1 resolves

The opposite of reject is "fulfill". A promise can resolve to a rejected promise, eg Promise.resolve(Promise.reject(new Error("foo"))) resolves to a rejected promise.

Turns out I wrote about it https://jakearchibald.com/2014/resolve-not-opposite-of-reject/

Interetesting. TIL.

For anyone else seeing this, I also found this helpful:
https://github.com/domenic/promises-unwrapping/blob/master/docs/states-and-fates.md

philipwalton · 2016-10-06T16:52:37Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+
+Note: The phrase "logging out the chunks" made me sick in my mouth.
+
+## Example: Avoid going too linear


I didn't know what you meant by "too linear" when first reading this heading. It took me reading the examples to figure it out.

I wonder if sequential is a better word.

Yeah, much better

ebidel · 2016-10-06T16:44:57Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+
+Async functions look like this:
+
+    async function myFirstAsyncFucntion() {


Fucntion -> Function

lol - I am rubbing off on Jake. I said this to him yesterday that I can write function properly.

Hah, yep. Good catch.

ebidel · 2016-10-06T16:46:30Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+      catch (rejectedValue) {
+        // …
+      }


so because async functions always return a promise, you don't explicitly need a return val? Might want to mention that.

Welllllll you need to return what you want the promise to resolve to, else it resolves to void the same way functions return void if you don't have an explicit return.

ebidel · 2016-10-06T16:47:53Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      return 'world';
+    }
+
+…calling `hello()` returns a promise that *fulfills* with `"world"`.


would be good to show the examples of the calls for each of these.

ebidel · 2016-10-06T16:51:58Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+        this.cachePromise = caches.open('avatars');
+      }
+
+      async getAvatar(name) {


show an example usage of getAvatar()

ebidel · 2016-10-06T16:55:58Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+In this example, the URLs are fetched and read as text in parallel, but the "smart" `reduce` bit is replaced with a standard, readable, for-loop.
+
+## Browser support & workarounds
+


What do you think about using a framebox here to embed the chromestatus info:
https://www.chromestatus.com/feature/5643236399906816?embed

Isn't this a bit huge for an embed?

jakearchibald · 2016-10-06T18:47:56Z

Oh, I need to wrap all the lines too. Oops.

jeffposnick · 2016-10-06T18:56:39Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+    }
+
+If you use the `async` keyword before a function definition, you can then use `await` within the function. When you `await` a promise, the function is paused until the promise settles. If the promise fulfills, you get the value back. If the promise rejects, the rejected value is thrown.


You could use this space to explicitly call out that top-level await isn't supported, and that the only time you can use await is inside an async function.

That's something that I found non-obvious.

jakearchibald · 2016-10-07T11:33:01Z

Thanks for all the feedback everyone.

I'm pretty happy with this now. @addyosmani anyone else need to review this?

ithinkihaveacat

Perhaps add a section on async/await gotchas? Also, are there any situations in which raw promises are preferable or easier to understand?

ithinkihaveacat · 2016-10-07T13:33:53Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+    }
+
+If you use the `async` keyword before a function definition, you can then use


Maybe not for this article, but why is async even necessary? (Why is await appearing in the body not sufficient?) Is this a convenience to the JS engine?

I guess the reasons are similar to why function()* is necessary for generators, but I'm not 100% sure.

FWIW I've been caught out by generators in Python in the past. It wasn't clear to me that a function would behave very differently because it has a yield hidden away in it somewhere.

There are a few reasons:

When you have such drastically different modes, it's a benefit to readability to have it called out when the function starts (as Jake says above).

You can have an async function which doesn't contain any await; the semantics will be kinda sorta like if return foo was return Promise.resolve(foo)

await is a new keyword, but we can't "just" add keywords. They might already be used as variables. Scoping the keyword-ness to async functions is one technique that await uses. (async uses other techniques, e.g., that if it's followed by function, it would've been a syntax error.)

ithinkihaveacat · 2016-10-07T13:36:28Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+    }
+
+    async function hello() {
+      await wait(500);


Might be worth explaining why adding an additional await wait(500) will result in this function taking 1s to run, and why something like

const p1 = wait(500); const p2 = wait(500); const v1 = await p1; const v2 = await p2;

(which seems more or less equivalent) takes 0.5s.

Ohh, this is a good example. Let me see if I can work it in.

Added this at the start of the series vs parallel bit. Cheers!

You might like this post 😇

jakearchibald · 2016-10-07T13:57:05Z

@ithinkihaveacat

Perhaps add a section on async/await gotchas? Also, are there any situations in which raw promises are preferable or easier to understand?

The biggest gotcha is forgetting that you're async, or making thinks too sequential, which I cover.

Generally it's ok to use async functions for everything you'd previously use promises for.

beaufortfrancois

Great article ;) See my 2 cents!

beaufortfrancois · 2016-10-10T12:04:42Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+    const storage = new Storage();
+    storage.getAvatar('jaffathecake').then(…);
+
+Note: Class constructors cannot be async.


get and set as well. However it looks like static works fine.
Shall we be exhaustive there @jakearchibald?

Yeahhhh why not

beaufortfrancois · 2016-10-10T12:08:18Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+ages to figure out what it's doing, like one of those magic-eye pictures from
+the 90's.
+
+Let's try that again with async functions:


Shall we also add the catch to show how to handle errors?

beaufortfrancois · 2016-10-10T12:10:16Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      return "done!";
+    }
+
+…the above takes 500ms to complete, because both waits happen at the same time.


We may want to call out observables are different than promises as they always start no matter what when you call them unlike observables.

Not sure why observables would be mentioned here.

littledan

Great article, seems to get at all the right points. I think the beginning could be changed a little bit to lead with examples, rather than an explanation of obscure error handling.

littledan · 2016-10-18T09:22:32Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+      catch (rejectedValue) {
+        // …
+      }


I see a lot of code samples like this, with the try/catch. I worry that presenting async functions like this may make people think they always need a try/catch block inside their async function body, which definitely isn't true. Maybe the initial example should be a chain of awaiting multiple things, or even a loop, and then explain the exceptions/rejection duality later.

I'll try and pick up on this elsewhere in the article. I kinda like opening with how fulfill/reject values map in async functions.

littledan · 2016-10-18T09:25:44Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      }
+    }
+
+If you use the `async` keyword before a function definition, you can then use


There are a few reasons:

When you have such drastically different modes, it's a benefit to readability to have it called out when the function starts (as Jake says above).

You can have an async function which doesn't contain any await; the semantics will be kinda sorta like if return foo was return Promise.resolve(foo)

await is a new keyword, but we can't "just" add keywords. They might already be used as variables. Scoping the keyword-ness to async functions is one technique that await uses. (async uses other techniques, e.g., that if it's followed by function, it would've been a syntax error.)

littledan · 2016-10-18T09:26:48Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+If you use the `async` keyword before a function definition, you can then use
+`await` within the function. When you `await` a promise, the function is paused
+until the promise settles. If the promise fulfills, you get the value back. If
+the promise rejects, the rejected value is thrown.


Is this the right paragraph to lead with? Maybe the article should open with an explanation and examples of, "you can await a bunch of stuff in a row!" and then get into the nitty gritty of exception handling later.

This doesn't really feel nitty gritty to me, it's kinda "the basics". I'm going to move the stuff about return values to after the first example, so readers will get to the first example quicker.

littledan · 2016-10-18T09:27:37Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+
+    // wait ms milliseconds
+    function wait(ms) {
+      return new Promise(r => setTimeout(r, ms));


Generally, I like this example because it shows a simple async/await usage without exceptions. However, could we open with something that uses platform-provided Promises, rather than the Promise constructor (whose usage, long-term, should be minimal)?

Yeah, moving this to after the first example

littledan · 2016-10-18T09:29:05Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      catch (err) {
+        console.log('fetch failed', err);
+      }
+    }


Awesome example, much cleaner and gives a good use case for exception handling/rejection. Maybe you should move that opening try/catch example to just above this.

littledan · 2016-10-18T09:30:14Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+    const jsonPromises = urls.map(async url => {
+      const response = await fetch(url);
+      return response.json();
+    });


Another cool thing you can do here is Promise.all(foo.map(async elt => fn(elt))).

littledan · 2016-10-18T09:31:59Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      let result;
+      let total = 0;
+
+      while ((result = await reader.read()) && !result.done) {


I like how this uses a loop, and how it uses a bunch of await calls, and seems really practical. However, maybe it would be easier to read if you didn't use the pattern of assignment && another expression, instead breaking it out into another line (otherwise it still may have the smell of "wielder of something").

Yeahhhhh fair enough. Means having reader.read twice in the code, but I guess that's why async iterables are needed.

littledan · 2016-10-18T09:32:31Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+replaced with a trusty, boring, while-loop. Much better. In future, we'll get
+[async iterators](https://github.com/tc39/proposal-async-iteration){:
+.external}, which would [replace the above `while`
+loop](https://gist.github.com/jakearchibald/0b37865637daf884943cf88c2cba1376){:


You could write inline, "would replace the while loop with a for-of loop".

littledan · 2016-10-18T09:33:03Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      return "done!";
+    }
+
+…the above takes 500ms to complete, because both waits happen at the same time.


Not sure why observables would be mentioned here.

littledan · 2016-10-18T09:34:39Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+      // log them in sequence
+      for (const textPromise of textPromises) {
+        console.log(await textPromise);
+      }


Great example

jakearchibald · 2016-10-19T11:44:14Z

I've reordered the article a little so readers get to the examples quicker, and made some minor updates based on feedback. I'm happy for this to be merged btw.

petele

A few minor comments only to provide feedback for future articles.

petele · 2016-10-19T15:26:34Z

src/content/en/fundamentals/getting-started/_toc.yaml

@@ -25,6 +25,8 @@ toc:
      path: /web/fundamentals/getting-started/primers/service-workers
    - title: "JavaScript Promises: an Introduction"
      path: /web/fundamentals/getting-started/primers/promises
+    - title: "JavaScript Async Functions"


You only need to quote if you're using a 'fun' character like :

petele · 2016-10-19T15:27:53Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+
+All the "smart" is gone. The asynchronous loop that made me feel so smug is
+replaced with a trusty, boring, while-loop. Much better. In future, we'll get
+[async iterators](https://github.com/tc39/proposal-async-iteration){:


don't break {: something } attributes, the parser isn't smart enough to handle this. :( keep them all on one line.

Damnit, that's what my auto-wrapping plugin does. Will watch out for this, cheers!

petele · 2016-10-19T15:28:24Z

src/content/en/fundamentals/getting-started/primers/async-functions.md

+been fully read, and so on. This is much slower than the promises example that
+performs the fetches in parallel. Thankfully there's an ideal middle-ground:
+
+<span class="compare-better">Recommended</span> - nice and parallel


👍 nice use

petele · 2016-10-19T15:29:39Z

Closing this and replacing with #3716 to more easily merge into master.

async article - replaces #3617

jakearchibald added the DO NOT MERGE label Oct 6, 2016

googlebot added the cla: yes label Oct 6, 2016

addyosmani reviewed Oct 6, 2016

View reviewed changes

philipwalton reviewed Oct 6, 2016

View reviewed changes

ebidel reviewed Oct 6, 2016

View reviewed changes

jeffposnick reviewed Oct 6, 2016

View reviewed changes

jakearchibald changed the title ~~(WIP) Article async functions~~ Article: async functions Oct 7, 2016

ithinkihaveacat reviewed Oct 7, 2016

View reviewed changes

beaufortfrancois reviewed Oct 10, 2016

View reviewed changes

littledan reviewed Oct 18, 2016

View reviewed changes

jakearchibald added 8 commits October 19, 2016 11:39

First draft

878ed9a

Second draft

9384180

Adding description. Wrapping text.

9afd3a0

Adding an ending

ea4d368

Adding simple example of series vs parallel

5640577

Updating date

ac53224

Feedback edits

8941d40

Reordering based on feedback

e89f6f9

jakearchibald force-pushed the article-async-functions branch from 2955a16 to e89f6f9 Compare October 19, 2016 10:58

jakearchibald assigned petele Oct 19, 2016

petele added a commit that referenced this pull request Oct 19, 2016

Replaces #3617 - Jake's async article

501860d

petele reviewed Oct 19, 2016

View reviewed changes

petele closed this Oct 19, 2016

petele added a commit that referenced this pull request Oct 19, 2016

Merge pull request #3716 from google/article-async-functions-2

58dd6a6

async article - replaces #3617

petele deleted the article-async-functions branch October 19, 2016 15:59


		{% include "web/_shared/contributors/jakearchibald.html" %}

		Async functions are enabled by default in Chrome 55 and they're quite frankly marvelous. They allow you to write promise-based code as if it were synchronous, but without blocking the main thread.

		### Workaround - regenerator

		If you're targeting older browsers, Babel can also transpile generators, allowing you to use async functions all the way down to IE8.

		## Example: Streaming a response

		Note: If you're unfamiliar with streaming, [check out my guide](https://jakearchibald.com/2016/streams-ftw/#streams-the-fetch-api){: .external}.


		Note: The phrase "logging out the chunks" made me sick in my mouth.

		## Example: Avoid going too linear


		Async functions look like this:

		async function myFirstAsyncFucntion() {

		In this example, the URLs are fetched and read as text in parallel, but the "smart" `reduce` bit is replaced with a standard, readable, for-loop.

		## Browser support & workarounds

Article: async functions #3617

Article: async functions #3617

Conversation

jakearchibald commented Oct 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addyosmani Oct 6, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ebidel Oct 6, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakearchibald commented Oct 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakearchibald commented Oct 7, 2016 • edited Loading

ithinkihaveacat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakearchibald commented Oct 7, 2016

beaufortfrancois left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

littledan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jakearchibald commented Oct 19, 2016 • edited Loading

petele left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petele commented Oct 19, 2016

addyosmani Oct 6, 2016 •

edited

Loading

ebidel Oct 6, 2016 •

edited

Loading

jakearchibald commented Oct 7, 2016 •

edited

Loading

jakearchibald commented Oct 19, 2016 •

edited

Loading