ActionHero V18: Async/Await

Today we’ve released ActionHero v18.0.0!

Version 18.0.0 of ActionHero marks the conclusion of months of work by the community to upgrade every part of ActionHero to use async/await Javascript Syntax. This will not only make developing with ActionHero easier, but also less error-prone, easier to read, and more stable. We can write less code to get more done, have simpler error handling, and more! With the newer versions of node, we also get access to real class methods, which make extending and sharing code much easier.

If you are not familiar with async/await in javascript, there are a number of excellent guides out there, but this is my favorite:

There are no more callbacks and no more promise chains. You use try/catch to deal with errors. You can use normal for and while loops to work on async methods. The world is so much more pleasant! Code is more readable, and bugs are far easier to find and test.

For example, here’s how an action testing api.cache changed from ActionHero v17 to v18:

This is going to be so much better!

Community Support and Breaking Changes

Because this release had so many breaking changes, we needed to handle this release differently than we have in the past.

The ActionHero Core Team had to make a hard decision with this release. This marks the first version we’ve released that does not work with all active LTS versions of node.JS. Until now, this had been our policy. However, We felt the gains in legibility, productivity, and debugging were so important that leaving ‘legacy’ users behind was the correct tradeoff.

However, to continue to support ActionHero users on v17, we will break with our other policy of only supporting the "master" branch. We’ve cut a v17 branch, and will continue to accept patches and updates to it until March of 2018. We will also port any security fixes from master back to v17. Greg has also offered to create inline documentation for v17 as well (more on this later).

We know that upgrading to v18 (and perhaps a new version of Node.js) will be the most difficult ActionHero migration to date, but I assure you it will be worth it!

I’ve also discussed these thoughts on the first Always bet on Node podcast with Dan Shaw and Mikeal.

What’s New

The full Release Notes for ActionHero v18 can be found on GitHub, and as usual, we’ve published our Upgrade Guide from the previous version.

The new features I’m most proud of are:

Full Support for **async/await** programming in ActionHero.

Really. This is a big deal. Our test suite saved hundreds of lines of code. There is no more ‘callback hell’, and in general, everything is so much easier to understand. We don’t need any more flow control tools.

We’ve also significantly increased our test coverage to include plugins and the CLI commands… parts of ActionHero which, in the old callback style, were *very* hard to test.

Full documentation of all public classes and APIs.

I had not heard of JSdoc before this upgrade… But, just like when I learned about standard.js, I now can’t imagine creating publicly-consumable projects without it. JSdoc allows you to comment your code (automatically in many cases) such that you can generate human-readable documentation from your source files. This means that as you write a new method or class, you can use the handy plugin for your code editor to automagically generate documentation.

We’ve set up ActionHero to automatically build our new documentation site, docs.actionherojs.com at the conclusion of every successful test run. This ensures that our documentation will aways be up-to-date now!

A bonus feature of this work is that now you will always have the ability to generate the documentation for your local version of ActionHero. cd ./node_modules/actionhero && npm run docs. In the coming weeks, we’ll add support for multiple versions of ActionHero the documentation website, but having an offline version will ensure that you can get work done with ActionHero.

Requiring the **api** object.

We were able to simplify much of the ActionHero developer experience by stopping our convention of passing the api object into every run, start, and stop method. We’ve taken advantage of Node.js’ module require cache to simply allow you to const {api} = require('actionhero') wherever you need it. This now allows you to have access to the ActionHero api in any file in your project, not just actions and tasks.

Try out ActionHero v18 today!

npm install actionhero && npx actionhero generate