DEV Community

Refactoring node.js (Part 1)

Paula Santamaría on November 09, 2019

This is the first part of a series of articles where I'll share tips to write cleaner and more effective node.js code. 1. Use async/awai...

Read full post

Avalander • Nov 10 '19 • Edited

Async/await allows us to build asynchronous non-blocking code with a cleaner and more readable syntax than promises

I wish people would stop saying that. async/await is a nice abstraction if you want to write asynchronous imperative code, but promises end up in nicer and more readable code if you use function composition and higher order functions.

To make a fair comparision, your example could be rewritten like this:

myFunction()
    .then(doStuff)
    .catch(handle)

Which is not only shorter than the async/await example, but avoids an unnecessary intermediate variable* polluting the local scope.

* I'm not saying that locally scoped variables are a bad thing, but each variable in the scope is one more thing you need to keep in mind when reasoning about that piece of code, because it can be accessed and modified elsewhere in that scope. Long functions using async/await tend to result in lots of intermediate variables that is unclear at a first glance whether they are only passed as argument to the next function or are used further below.

Paula Santamaría • Nov 10 '19 • Edited

I actually did a little research before writing that sentence, because I thought "maybe I'm just more comfortable with async/await because of my C# background", and I wanted to be objective. Here's what I found with links to the sources (so you don't have to take my word for it):

First I went straight to the source, ECMA-262, 8th edition, were I found async functions to be defined as follows:

Async functions improve the asynchronous programming experience by providing syntax for promise-returning functions.

But I wanted some benchmarks and in-depth analysis, so I kept going. And that's when I found this article Faster async functions and promises, by the V8 team, that definitely convinced me. Here are the key points made in the article:

With async functions, the code becomes more succinct, and the control and data flow are a lot easier to follow, despite the fact that the execution is still asynchronous.

Async functions are intended to make asynchronous code look like synchronous code, hiding some of the complexity of the asynchronous processing from the developer.

async/await outperforms hand-written promise code now. The key takeaway here is that we significantly reduced the overhead of async functions — not just in V8, but across all JavaScript engines, by patching the spec.

So, after this research I felt comfortable enough to recommend async/await over promises. But still, I understand devs that are used to promises and new to async/await may not find this syntax more readable.

Avalander • Nov 10 '19 • Edited

We could discuss all day long the merits of the second article you linked. For instance, I find it interesting that they conclude that async/await outperforms hand-written code promise when the graph right above that sentence shows that async/await runs faster only in one of the two benchmarks, or how relevant it is for real applications that some arbitrary code runs about 5ms faster than some other arbitrary code.

However, I'm not interested in discussing performance because it's not the point you made in the article, it's not the point I was debating, and promises vs async/await is rarely where the performance bottleneck will be in any real world project.

Going back to the topic of readability, I think we should acknowledge that it is a somewhat subjective matter, and some decisions are going to be more a matter of personal style than one option being clearly superior to the other. I think async/await vs promises is one of those instances.

I've written a lot of asynchronous code in many different styles and contexts. Among others, I've written Javascript code with callbacks, promises and async/await; Python both with its async/await and before that was added to the language; and Java 1.7 with its blocking thread execution until asynchronous operations finish. And I don't see Javascript's async/await being a substantial improvement over promises in the same way that promises and async/await are an improvement over callbacks.

As I said, promises fit the declarative functional paradigm quite good. If your mental model is a pipe of transformations through which the data flows from a given input to the desired output, a promise chain matches that model quite well, and you'll find easier to reason about code written in that style.

On the other hand, async/await is better if you are writing imperative code. If your mental model is a series of steps that need to be performed, then it will be easier to reason about steps that need to be awaited than functions that will be executed at an arbitrary point in the future.

Thus, I think async/await is a horizontal evolution over promises that fills an entirely different niche, for which Javascript didn't have any good solution yet.

Paula Santamaría • Nov 10 '19 • Edited

I agree, we would discuss all day. If you won't even consider an article written by the people behind the javascript engine inside node.js, I don't think I can come up with a better/more reliable resource.

It's true that readability is subjective, and that's why I try to ignore my own biases and follow recommendations from the leaders of the industry that I also take into account when writing my articles.

The idea behind this article is merely to provide the readers with tips and tools that worked for me to write clean and efficient node.js code, and that are based on official documentation and reliable resources.

Like I said, it's perfectly ok if you still prefer promises.

SavagePixie • Nov 11 '19 • Edited

If you won't even consider an article written by the people behind the javascript engine inside node.js, I don't think I can come up with a better/more reliable resource.

You do realise that Avalander has considered said article, right? They are saying two things about it: 1) its conclusions are dubious and 2) it doesn't really address your point or their objection to it. If this doesn't show that they've considered it, I don't know what does.

The point Avalander is contesting is this claim:

Isn't it cleaner and easier to read with async/await?

To which I am afraid I must side with Avalander and say that neither you nor your sources have provided good support for it. async/await reads differently than promises. But that's just it. Not cleaner, nor better, just different.

And I am going to discuss the second source you mention. Particularly the sentence you quoted:

With async functions, the code becomes more succinct, and the control and data flow are a lot easier to follow, despite the fact that the execution is still asynchronous.

I can't help but notice that they write that just below an example where they've rewritten promise syntax to async/await using two fewer lines of code (one of which is merely a )};) and making two other lines twice as long. Specifically, while the promise syntax uses 168 characters, the async/await syntax uses 181. That's 13 extra characters for the supposedly more succint code of async/await. Even if it were 5 characters less, that'd be dubious evidence on which to ground the claim that async/await is more succinct, simply because it's only one example with too small a difference to draw any conclusions.

By the way, I'm not saying that promise syntax is better than async/await. All I'm saying is that I find the claim that async/await is better or clearer wanting.

Paula Santamaría • Nov 11 '19

We concluded earlier than readability is subjective, so I don't think it makes any sense to keep arguing about what you find best.

My point is simply this: We can all have our opinions and preferences but, in the interest of objectiveness, I believe the best we can do is follow reliable sources. Unless you have the time to explore the matter in depth and write your own article with your own conclusions.

Both links I've shared on this thread I consider to be reliable and present async/await as an improvement to writing asynchronous code in javascript. And there are many other sources that explore this statement in depth and conclude the same thing. This article was not meant to list the pros and cons of async/await but merely to share tools that worked for me and that are supported by documentation written by people far more experienced than me in the subject.

Here's another article from this very platform that explores the subject more in depth.

Jonas Winzen • Nov 12 '19

I agree. I'm experiencing async/await as an invite to handle side effects and pure functionality intermixed in one big spaghetti function.

Hugo Di Francesco • Nov 10 '19

Node 10+ has a promisified version of fs under fs.promises.

const fs = require ('fs').promises

Paula Santamaría • Nov 11 '19

That's awesome, thanks! I'll probably include this in the next article.

Jakub Sarnowski • Nov 10 '19

const readFilePromise = util.promisify(fs.readFile);

const readFile = async (path) => {
    return await readFilePromise(path);
}

Here, the readFilePromise is exactly the same as readFile. You could just do: const readFile = util.promisify(fs.readFile);

Paula Santamaría • Nov 10 '19

Thanks for the suggestion! I was actually aware of that, but I decided to wrap readFilePromise in a function anyway to illustrate how, after using promisify, we can await the "promisified" function within an async function. I couldn't come up with a better example, but I'll try to think of one to avoid any confusion.

Jakub Sarnowski • Nov 10 '19

I was thinking that this might be the case, but I've decided to comment it out, just in case 😄 Great article!

Paula Santamaría • Nov 10 '19

It's 5am, I couldn't sleep and I came up with a better example that made more sense 😂. I just replaced the old one.

Evaldas Buinauskas • Nov 10 '19

The overall idea to throw exceptions for control flow isn't that great. You could achieve the same with proper method return type which would let higher layers know that a product might not exist. 🙂

Paula Santamaría • Nov 10 '19

I agree. I try to follow the rule of "using exceptions for exceptional circumstances". However, a situation that may be consider exceptional in some use-case, may be regular in another.

My example wasn't really written with any particular use-case in mind. It's just an example of how we can give more information to other layers about what went wrong. For the sake of the example, we could define that calling the getById method with a non-existent id is an exceptional circumstance.

Evaldas Buinauskas • Nov 10 '19

Yep. The overall idea to throw a more specific exception is good, perhaps the use case isn't as it might confuse more junior developers.

I tend to think that exceptional is something that can happen without end user's interference, e.g. you can expect user to supply an incorrect parameter to an API :)

Paula Santamaría • Nov 10 '19 • Edited

And that's why use cases matter. I won't expect a user to supply an incorrect id. In most use-cases they won't be writing the id themselves manually, that should be solved by the front-end. And that's why, in this particular case, I find an exception appropriate.

Paula Santamaría • Nov 10 '19

I've been meaning to learn more about good practices related to error handling, but I can't seem to find any in-depth book or resources. If you could recommend a book or any trustable resource, I'll appreciate it :)

Evaldas Buinauskas • Nov 10 '19

I can't recommend a specific book but I love functional programming as it helps to solve these problems by using appropriate type definitions. e.g. Maybe<Product> which indicates that there might be a product in this wrapper, there might be none, or Result<HttpError, Product> which represents response of a HTTP call to retrieve a product.

Check github.com/rametta/pratica out. A very small lib that has it all :)

Paula Santamaría • Nov 10 '19

Thanks! I really want to get more into functional programming, I'll definitely check that out.

Jared • Nov 10 '19

wow, i didn't even know about the different instances of Error. Thank you for sharing!

Paula Santamaría • Nov 10 '19

Thank you, Jared :)
I'm a huge fan of error handling! I'll probably share more stuff about that in this series.

Adithya Sreyaj • Nov 10 '19

Really looking forward to this...as I'm pretty bad at handling errors...🙃

Paula Santamaría • Nov 17 '19 • Edited

In case you haven't had a chance to see it yet, I wrote more about error handling in the second part of this series: Refactoring Node.js (part 2).

Jacqueline Binya • Nov 10 '19

Great article as always Paula, im a huge fan. From this one I learnt a lot of stuff im hoping to implement in my code, looking forward to the next article in the series.

Paula Santamaría • Nov 10 '19

Thank you so much 🙏 I'll try to keep it interesting!

Manuel Romero • Nov 11 '19

Great post, Paula (as usually)
Just a couple of things I would like to highlight:

1) When working with callbacks first argument must be the error(AKA Error first pattern):

//If error
return callbak(error);
//Else
return callback(null, data);

2) If you are using an express like framework you can manage 404 errors in another function just calling next(); or 500 errors with next(error); so that you don't have to replicate the error logic in each controller.

Evan Plaice • Nov 10 '19

Awesome article 👍

Can you write more content on async + promisify? I feel like these are both super valuable topics that are also not talked about nearly enough.

Paula Santamaría • Nov 10 '19

Thank you Evan! I've only use promisify with the fs module, but I'll try to find more examples so we can understand it in depth together.

Evan Plaice • Nov 10 '19

Of course. I'm always excited to see someone dig deep into some more advanced topics.

Maybe this'll help

Here's promisify(exec):
github.com/vanillawc/fpm/blob/mast...

And w/ some other file operations:
github.com/vanillawc/fpm/blob/mast...

Paula Santamaría • Nov 10 '19

Awesome, thanks!

petrosvoivontas • Nov 18 '19

I think there's a mistake in this piece of code:

const firstOperation = myAsyncFunction();
const secondOperation = myAsyncFunction2('test');
const thirdOperation = myAsyncFunction3(5);

await Promise.all([ firstOperation, secondOperation, thirdOperation ]);

The variables firstOperation, secondOperation, and thirdOperation include the results of each function NOT the functions themselves. So the array you pass to Promise.all does not have functions as its elements, but the results of those functions.

Paula Santamaría • Nov 18 '19

Hi there! In that example, all functions (myAsyncFunction, myAsyncFunction2 and myAsyncFunction3), are async, which means that they return promises. So what const firtsOperation is storing is the promise returned by myAsyncFunction.

Finally, by awaiting Promise.all we're waiting for all promises to resolve.

If I wanted firstOperation to contain myAsyncFunction final result I should have wrote const firstOperation = await myAsyncFunction();
But the idea of that example was to illustrate how we can execute many async functions in parallel.

More info: MDN - Promise.all()