@babel/helper-remap-async-to-generator

@babel/helper-remap-async-to-generator is a Babel helper function that transforms async functions into generator functions by converting AST nodes. It's designed for build-time transformations where async/await syntax needs to be converted into generator-based patterns for compatibility with older JavaScript environments or specific runtime requirements.

Package Information

• Package Name: @babel/helper-remap-async-to-generator
• Package Type: npm
• Language: TypeScript
• Installation: npm install @babel/helper-remap-async-to-generator

Core Imports

import remapAsyncToGenerator from "@babel/helper-remap-async-to-generator";

For CommonJS:

const remapAsyncToGenerator = require("@babel/helper-remap-async-to-generator");

Basic Usage

import remapAsyncToGenerator from "@babel/helper-remap-async-to-generator";
import { types as t } from "@babel/core";

// Within a Babel plugin visitor
export default function myPlugin() {
  return {
    visitor: {
      Function(path) {
        if (path.node.async) {
          remapAsyncToGenerator(path, {
            wrapAsync: t.identifier("_asyncToGenerator"),
            wrapAwait: t.identifier("_awaitAsyncGenerator")
          });
        }
      }
    }
  };
}

Architecture

The helper is built around several key components:

• AST Transformation: Core function that modifies Babel AST nodes to convert async functions to generators
• Await Visitor: Internal visitor that traverses the AST to transform await expressions into yield expressions
• Function Wrapping: Integration with @babel/helper-wrap-function to properly wrap the transformed function
• Purity Annotation: Automatic marking of functions as pure using @babel/helper-annotate-as-pure where appropriate
• IIFE Detection: Smart detection of Immediately Invoked Function Expression patterns

Capabilities

Async to Generator Transformation

The main transformation function that remaps async functions to generators by modifying AST nodes and transforming await expressions.

/**
 * Transforms an async function into a generator function by converting AST nodes
 * @param path - Babel AST node path representing the function to transform
 * @param helpers - Object containing helper expressions for wrapping
 * @param noNewArrows - Optional flag to control arrow function handling
 * @param ignoreFunctionLength - Optional flag to control function length preservation
 */
export default function remapAsyncToGenerator(
  path: NodePath<t.Function>,
  helpers: {
    wrapAsync: t.Expression;
    wrapAwait?: t.Expression;
  },
  noNewArrows?: boolean,
  ignoreFunctionLength?: boolean,
): void;

Parameters:

• path: NodePath<t.Function> - Babel AST node path representing the function to transform. This should be an async function node.
• helpers: object - Object containing helper expressions:
  • wrapAsync: t.Expression - Required expression used to wrap the transformed generator function (e.g., _asyncToGenerator)
  • wrapAwait: t.Expression (optional) - Expression used to wrap await expressions when transformed to yields (e.g., _awaitAsyncGenerator)
• noNewArrows: boolean (optional) - Flag to control how arrow functions are handled during transformation
• ignoreFunctionLength: boolean (optional) - Flag to control whether function length is preserved during transformation

Behavior:

1. Traverses the function body to find all await expressions
2. Transforms await expressions into yield expressions
3. Optionally wraps yielded values with the provided wrapAwait helper
4. Sets the function's async property to false and generator property to true
5. Wraps the entire function using @babel/helper-wrap-function with the wrapAsync helper
6. Applies purity annotations where appropriate (non-property, non-IIFE expressions)

Usage Examples:

import remapAsyncToGenerator from "@babel/helper-remap-async-to-generator";
import { types as t } from "@babel/core";

// Basic transformation with required wrapAsync helper
remapAsyncToGenerator(functionPath, {
  wrapAsync: t.identifier("_asyncToGenerator")
});

// With optional wrapAwait helper for additional await wrapping
remapAsyncToGenerator(functionPath, {
  wrapAsync: t.identifier("_asyncToGenerator"),
  wrapAwait: t.identifier("_awaitAsyncGenerator")
});

// With additional options for arrow function and length handling
remapAsyncToGenerator(functionPath, {
  wrapAsync: t.identifier("_asyncToGenerator")
}, true, true);

Types

import type { NodePath } from "@babel/core";
import { types as t } from "@babel/core";

// Main function signature
type RemapAsyncToGeneratorFunction = (
  path: NodePath<t.Function>,
  helpers: {
    wrapAsync: t.Expression;
    wrapAwait?: t.Expression;
  },
  noNewArrows?: boolean,
  ignoreFunctionLength?: boolean,
) => void;

// Helper types from @babel/core
type NodePath<T> = import("@babel/core").NodePath<T>;
type Expression = import("@babel/core").types.Expression;
type Function = import("@babel/core").types.Function;

Error Handling

The function operates on AST nodes and assumes valid Babel AST structures. Common issues:

• Invalid NodePath: Ensure the path parameter is a valid Babel NodePath pointing to a Function node
• Missing wrapAsync: The wrapAsync helper expression is required and must be a valid AST Expression node
• Invalid AST State: The function modifies AST nodes in place; ensure the AST is in a valid state before transformation

Integration

This helper is designed to be used within Babel plugins and transformations:

// Example Babel plugin using the helper
export default function myAsyncToGeneratorPlugin() {
  return {
    visitor: {
      Function(path, state) {
        if (path.node.async && !path.node.generator) {
          remapAsyncToGenerator(path, {
            wrapAsync: state.addHelper("asyncToGenerator"),
            wrapAwait: state.addHelper("awaitAsyncGenerator")
          });
        }
      }
    }
  };
}