async-compiler

1.0.20 verified Fri May 01 auth: no javascript maintenance

A JavaScript compiler that transforms functions annotated with @async JSDoc tag into code using Promises for sequential asynchronous execution. Version 1.0.20 is the current stable release, with no recent updates indicating ongoing maintenance. It provides a simpler alternative to nested callbacks or promise chains by allowing developers to write asynchronous code in a synchronous style. Unlike native async/await (ES2017), it requires a compile step and a runtime library (async-compiler-runtime), and does not support advanced features like error handling or parallel execution patterns.

Common errors

error Error: Cannot find module 'async-compiler-runtime' ↓

cause The runtime package is not installed or not required in the compiled output.

fix

Install async-compiler-runtime: npm install async-compiler-runtime (or include as dependency). Then add var AsyncTool = require('async-compiler-runtime'); at the top of your source file before using @async functions.

error SyntaxError: Unexpected token function ↓

cause Node.js version does not support destructuring or arrow functions used in compiled output without --harmony flag.

fix

Run with --harmony flag: node --harmony compiled.js

error Error: @async function must return a Promise ↓

cause The function body does not contain an async operation returning a Promise, or the return value is not a Promise.

fix

Ensure that inside @async functions, all asynchronous calls return Promises (e.g., using the provided add/mul functions). The final return value of the @async function must be a Promise (typically the result of the outermost async call).

Warnings

breaking Requires Node.js with --harmony flag for destructuring support (e.g., Node 6+). ↓

fix Use node --harmony or update Node.js to version 6+ where destructuring is enabled by default (though --harmony still recommended).

deprecated Native async/await (ES2017) is widely supported in Node 7.6+ and modern browsers, making this compiler unnecessary for most projects. ↓

fix Migrate to native async/await syntax and remove the compile step.

gotcha The function must be annotated with exactly `/** @async **/` (with two asterisks on opening). Single-line comment /* */ will be ignored. ↓

fix Ensure JSDoc comment starts with /** and ends with */, with @async inside.

Install

npm install async-compiler

yarn add async-compiler

pnpm add async-compiler

Imports

AsyncTool

wrong

import AsyncTool from 'async-compiler-runtime';

correct

var AsyncTool = require('async-compiler-runtime');

The runtime library is CommonJS-only, no ESM exports.

Quickstart

Shows a complete example: two async functions, a function with @async tag that composes them, and the compile/run commands.

// async-example.js
var AsyncTool = require('async-compiler-runtime');

function add(x, y) {
  return Promise.resolve(x + y);
}
function mul(x, y) {
  return Promise.resolve(x * y);
}

/** @async **/
function foo() {
  return mul(add(3, 4), add(5, 6));
}

foo().then(function(v) {
  console.log('Result:', v);
});

// Command to compile:
// node --harmony node_modules/async-compiler/compile.js --input async-example.js --output async-compiled.js
// node --harmony async-compiled.js