README
async-to-gen
Turn your JavaScript with async functions into ES6 generators so they can be used in modern browsers or in node.js (v0.12 or newer).
Async functions are an exciting new proposed addition to JavaScript. The v8 team is hard at work getting it right, which means it could appear in future versions of node.js. However if you're impatient like me, then you probably just can't wait to get rid of your promise triangles and callback hell.
You can use Babel to accomplish this, but async-to-gen
is a faster, simpler, zero-configuration alternative with minimal dependencies
for super-fast npm install
and transform time.
Also, async-to-gen
provides support for async generators
which return Async Iterators, a great syntax and primitive for producing and
operating on streams of data.
Get Started!
Use the command line:
npm install --global async-to-gen
async-to-gen --help
async-to-gen input.js > output.js
# source maps!
async-to-gen input.js --sourcemaps inline > output.js
Or the JavaScript API:
npm install async-to-gen
var asyncToGen = require('async-to-gen');
var fs = require('fs');
var input = fs.readFileSync('input.js', 'utf8');
var output = asyncToGen(input).toString();
fs.writeFileSync('output.js', output);
// source maps!
var map = asyncToGen(input).generateMap();
fs.writeFileSync('output.js.map', JSON.stringify(output));
async-node
Use Wherever you use node
you can substitute async-node
and have a super fast
async functions aware evaluator or REPL.
$ async-node
> async function answer() {
... return await 42
... }
undefined
> promise = answer()
Promise { <pending> }
> promise.then(console.log)
Promise { <pending> }
42
Use the require hook
Using the require hook allows you to automatically compile files on the fly when requiring in node, useful during development:
require('async-to-gen/register')
require('./some-module-with-async-functions')
You can also provide options to the require hook:
// Disable inline source maps for use with development tools.
require('async-to-gen/register')({ sourceMaps: false })
Use options to define exactly which files to includes
or excludes
with regular
expressions. All files are included by default except those found in the
node_modules
folder, which is excluded by default. Pass excludes: null
to not
exclude any files.
require('async-to-gen/register')({ includes: /\/custom_path\// })
The require hook also offers the ability to set options and revert the require hook:
const asyncHook = require('async-to-gen/register')
// Similar to example above.
asyncHook.setOptions({ includes: /\/custom_path\// })
// Reverts the require hook.
asyncHook.revert()
Don't use the require hook in packages distributed on NPM
As always, don't forget to use
async-to-gen
to compile files before distributing your code on npm, as using the require hook affects the whole runtime and not just your module and may hurt the runtime performance of code that includes it.
Use in Build Systems:
Rollup: rollup-plugin-async
Common Usage
Async I/O
Async functions are great for writing asynchronous code that looks synchronous, and that's perfect for writing code that needs to perform async I/O operations.
One of the original motivations for Node.js was non-blocking I/O, perfect! However its core libraries do not yet support Promises, nor do many popular libraries written for Node ðŸ˜.
Do not fret, we can fix this with promisify-node!
const promisify = require('promisify-node');
const fs = promisify('fs');
async function emojify(filePath) {
const contents = await fs.readFile(filePath, 'utf8')
const edited = contents.replace(/:\)/g, '😉')
await fs.writeFile(filePath, edited, 'utf8')
}
Mocha
Writing tests in mocha? Async functions are super handy for testing any code using promises and already work out of the box! To enable async functions in mocha include the require hook when you run your tests:
mocha --require async-to-gen/register test.js
Then in your tests, use async functions in your it
clauses:
describe('My Promising Module', () => {
it('promises to give a value', async () => {
expect(await myFunction('input')).to.equal('output')
})
})
Testing your express app? Try supertest and async functions:
const express = require('express')
const request = require('supertest')
const app = express()
app.get('/foo', (req, res) => res.send('bar'))
describe('My express app', () => {
it('loads foo', async () => {
const response = await request(app).get('/foo')
expect(response.body).to.equal('bar')
})
})
Jest
Writing tests in Jest? Use the scriptPreprocessor entry in your jest configuration in package.json:
{
"name": "my-project",
"jest": {
"transform": {
"^.+\\.js