| 1 | fast-async
|
| 2 | ==========
|
| 3 |
|
| 4 | 'fast-async' is a _Babel v6.x.x_ plugin that implements the ES7 keywords `async` and `await` using syntax transformation
|
| 5 | at compile-time rather than generators.
|
| 6 |
|
| 7 | The main reason for using 'fast-async' as opposed to Babel's default implementation of async/await is
|
| 8 | performance (https://github.com/MatAtBread/nodent#performance) - it's 3-4 times faster in a browser/node, and
|
| 9 | as much as 10 times faster on a mobile browsers, mainly due to avoiding generators (and therefore regenerator).
|
| 10 |
|
| 11 | There's a simple test (that just makes sure the plugin works and generates code that runs). More complete
|
| 12 | test coverage is included with nodent.
|
| 13 |
|
| 14 | Because Babel parses the code, the ES7 extensions possible with nodent (`await` anywhere, `async return` and `async throw`) are not supported, however full implementation of `async function` containing `await` expressions is implemented.
|
| 15 |
|
| 16 | For _Babel v5.x.x_ install fast-async@1.0.3
|
| 17 |
|
| 18 | Install
|
| 19 | -------
|
| 20 |
|
| 21 | npm install fast-async
|
| 22 |
|
| 23 |
|
| 24 | Usage
|
| 25 | -----
|
| 26 |
|
| 27 | Just include the plugin to the babel options. Minimal `.babelrc` example:
|
| 28 |
|
| 29 | {
|
| 30 | "plugins": ["fast-async"]
|
| 31 | }
|
| 32 |
|
| 33 | That's all. Neither `babel-plugin-transform-runtime` nor `babel-polyfill` required.
|
| 34 |
|
| 35 | With options:
|
| 36 |
|
| 37 | {
|
| 38 | "plugins": [
|
| 39 | ["fast-async", {
|
| 40 | "env": {
|
| 41 | "augmentObject": false,
|
| 42 | "dontMapStackTraces": false,
|
| 43 | "asyncStackTrace": false,
|
| 44 | "dontInstallRequireHook": false
|
| 45 | },
|
| 46 | "compiler": {
|
| 47 | "promises": true,
|
| 48 | "generators": false
|
| 49 | },
|
| 50 | "runtimePattern":null
|
| 51 | }]
|
| 52 | ]
|
| 53 | }
|
| 54 |
|
| 55 |
|
| 56 | Test
|
| 57 | ----
|
| 58 | From the installation directory (e.g. node_modules/fast-async):
|
| 59 |
|
| 60 | npm test
|
| 61 |
|
| 62 | Options
|
| 63 | -------
|
| 64 | The plugin accepts the following options object, which itself is optional, as are all members. These are based on the options in nodent,
|
| 65 | but since much of the parsing is done by Babel some are unused.
|
| 66 |
|
| 67 | env:{
|
| 68 | log:function(string), // Supplied routine to emit transformation warnings. Default: console.log
|
| 69 | augmentObject:false, // Add the nodent utilities asyncify() and isThenable() to Object.prototype
|
| 70 | dontMapStackTraces:false, // Don't install the stack trace hook that maps line numbers
|
| 71 | asyncStackTrace:false, // Provide async stack traces
|
| 72 | dontInstallRequireHook:false // Don't transform all JS files as they are loaded into node
|
| 73 | },
|
| 74 | compiler:{
|
| 75 | promises:true, // Use nodent's "Promises" mode. Set to false if your execution environment does not support Promises.
|
| 76 | generators:false // Transform into 'Generators'.
|
| 77 | },
|
| 78 | runtimePattern:null // See below
|
| 79 |
|
| 80 | For more information on the compiler options, see [ES7 and Promises](https://github.com/matatbread/nodent#es7-and-promises) in the nodent documentation.
|
| 81 |
|
| 82 | __runtimePattern__
|
| 83 | By default, fast-async will put the nodent runtime into every file it compiles. If your project is made up of more than one file, the constant
|
| 84 | redefinition of the runtime is a waste of time and space. You can specify that you want the runtime in particular file(s) by setting the 'runtimePattern' to a regular expression (in quotes). Only files that match the regular expression will have the runtime defined (which is global, so you only need it once). For example:
|
| 85 |
|
| 86 | "babel": {
|
| 87 | "plugins": [
|
| 88 | "syntax-async-functions",
|
| 89 | ["fast-async",{
|
| 90 | "runtimePattern":"test-input\\.js"
|
| 91 | }]
|
| 92 | ]
|
| 93 | }
|
| 94 |
|
| 95 | Alternatively, if you set runtimePattern to `"directive"`, the statement `"use runtime-nodent";` will be replaced with the runtime during compilation.
|
| 96 |
|
| 97 |
|
| 98 | Useful Links
|
| 99 | ------------
|
| 100 |
|
| 101 | * [nodent](https://github.com/MatAtBread/nodent)
|
| 102 | * [Babel plugins](http://babeljs.io/docs/advanced/plugins/)
|
| 103 |
|
| 104 | Online performance checkers:
|
| 105 |
|
| 106 | * [nodent](http://nodent.mailed.me.uk/#function%20pause%28%29%20{%0A%20%20%20%20return%20new%20Promise%28function%20%28%24return%2C%20%24error%29%20{%0A%20%20%20%20%20%20%20%20setTimeout%28function%20%28%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20%24return%280%29%3B%0A%20%20%20%20%20%20%20%20}%2C%200%29%3B%0A%20%20%20%20}%29%3B%0A}%0A%0Aasync%20function%20doNothing%28%29%20{%0A%20%20%20%20return%3B%0A}%0A%0Aasync%20function%20test%28%29%20{%0A%20%20%20%20var%20t%20%3D%20Date.now%28%29%3B%0A%20%20%20%20for%20%28var%20j%20%3D%200%3B%20j%20%3C%2050%3B%20j%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20for%20%28var%20i%20%3D%200%3B%20i%20%3C%201000%3B%20i%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20await%20doNothing%28%29%3B%0A%20%20%20%20%20%20%20%20}%0A%20%20%20%20%20%20%20%20await%20pause%28%29%3B%0A%20%20%20%20}%0A%20%20%20%20return%20Date.now%28%29%20-%20t%3B%0A}%0A%0Atest%28%29.then%28alert%29%3B%0A) 632ms (and shave off another 100ms by selecting 'Pure ES5' mode)
|
| 107 | * [babel](https://babeljs.io/repl/#?experimental=true&evaluate=true&loose=false&spec=false&code=function%20pause%28%29%20{%0A%20%20%20%20return%20new%20Promise%28function%20%28%24return%2C%20%24error%29%20{%0A%20%20%20%20%20%20%20%20setTimeout%28function%20%28%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20%24return%280%29%3B%0A%20%20%20%20%20%20%20%20}%2C%200%29%3B%0A%20%20%20%20}%29%3B%0A}%0A%0Aasync%20function%20doNothing%28%29%20{%0A%20%20%20%20return%3B%0A}%0A%0Aasync%20function%20test%28%29%20{%0A%20%20%20%20var%20t%20%3D%20Date.now%28%29%3B%0A%20%20%20%20for%20%28var%20j%20%3D%200%3B%20j%20%3C%2050%3B%20j%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20for%20%28var%20i%20%3D%200%3B%20i%20%3C%201000%3B%20i%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20await%20doNothing%28%29%3B%0A%20%20%20%20%20%20%20%20}%0A%20%20%20%20%20%20%20%20await%20pause%28%29%3B%0A%20%20%20%20}%0A%20%20%20%20return%20Date.now%28%29%20-%20t%3B%0A}%0A%0Atest%28%29.then%28alert%2Calert%29%3B%0A) 1877ms - 3x slower
|
| 108 | * [traceur](https://google.github.io/traceur-compiler/demo/repl.html#%2F%2F%20Options%3A%20--annotations%20--array-comprehension%20--async-functions%20--async-generators%20--exponentiation%20--export-from-extended%20--for-on%20--generator-comprehension%20--member-variables%20--proper-tail-calls%20--require%20--symbols%20--types%20%0Afunction%20pause%28%29%20{%0A%20%20%20%20return%20new%20Promise%28function%20%28%24return%2C%20%24error%29%20{%0A%20%20%20%20%20%20%20%20setTimeout%28function%20%28%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20return%20%24return%280%29%3B%0A%20%20%20%20%20%20%20%20}%2C%200%29%3B%0A%20%20%20%20}%29%3B%0A}%0A%0Aasync%20function%20doNothing%28%29%20{%0A%20%20%20%20return%3B%0A}%0A%0Aasync%20function%20test%28%29%20{%0A%20%20%20%20var%20t%20%3D%20Date.now%28%29%3B%0A%20%20%20%20for%20%28var%20j%20%3D%200%3B%20j%20%3C%2050%3B%20j%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20for%20%28var%20i%20%3D%200%3B%20i%20%3C%201000%3B%20i%2B%2B%29%20{%0A%20%20%20%20%20%20%20%20%20%20%20%20await%20doNothing%28%29%3B%0A%20%20%20%20%20%20%20%20}%0A%20%20%20%20%20%20%20%20await%20pause%28%29%3B%0A%20%20%20%20}%0A%20%20%20%20return%20Date.now%28%29%20-%20t%3B%0A}%0A%0Atest%28%29.then%28alert%2Calert%29%3B%20%0A) 2488ms - 4x slower
|