Babel Helper: Hoist Variables

A Babel helper function that hoists variable declarations in JavaScript AST transformations. This utility traverses AST paths to find variable declarations and converts them into separate declaration and assignment statements, effectively hoisting the variable declarations to their containing scope while maintaining proper JavaScript semantics.

Package Information

• Package Name: babel-helper-hoist-variables
• Package Type: npm
• Language: JavaScript (ES6+ with Flow types)
• Installation: npm install babel-helper-hoist-variables

Core Imports

ESM:

import hoistVariables from "babel-helper-hoist-variables";

CommonJS:

const hoistVariables = require("babel-helper-hoist-variables");

Basic Usage

import hoistVariables from "babel-helper-hoist-variables";
import { parse } from "babel-parser";
import traverse from "babel-traverse";

// Parse some code
const ast = parse(`
function example() {
  var a = 1, b = 2;
  let c = 3;
}
`);

// Use in a Babel transformation
traverse(ast, {
  FunctionDeclaration(path) {
    const hoistedVars = [];
    
    // Hoist 'var' declarations
    hoistVariables(path, (identifier, name) => {
      hoistedVars.push(identifier);
    }, "var");
    
    console.log("Hoisted variables:", hoistedVars);
  }
});

Capabilities

Variable Hoisting Function

The main export hoists variable declarations from a given AST path by converting them into separate declaration and assignment statements.

/**
 * Hoists variable declarations from an AST path
 * @param {NodePath} path - The Babel AST path to traverse for variable hoisting (from babel-traverse)
 * @param {Function} emit - Callback function that receives hoisted identifiers
 * @param {("var"|"let")} kind - The kind of variable declarations to hoist (default: "var")
 * @returns {undefined} - This function performs side effects and doesn't return a value
 */
function hoistVariables(path, emit, kind = "var");

Parameters

• path (Required): The Babel AST NodePath object to traverse for variable hoisting (from babel-traverse)
• emit (Required): Callback function that receives each hoisted identifier
  • Signature: emit(identifier, name)
  • identifier: Babel identifier node for the hoisted variable
  • name: String name of the variable
• kind (Optional): String literal specifying which variable declaration types to hoist
  • Accepts: "var" or "let"
  • Default: "var"

Behavior

The function traverses the provided AST path using a visitor pattern that:

1. Respects Scope Boundaries: Skips nested function declarations to prevent hoisting variables across function scopes
2. Handles Declaration Kinds: Only processes variable declarations matching the specified kind parameter
3. Converts Declarations: Transforms variable declarations into:
   • Separate variable declarations (hoisted via emit callback)
   • Assignment expressions for initialization values
4. Special For-Loop Handling: Properly handles variable declarations in for-loop contexts
5. Maintains Semantics: Preserves JavaScript variable scoping and initialization semantics

Usage Patterns

Collecting Hoisted Variables:

const hoistedVars = [];
hoistVariables(path, (identifier, name) => {
  hoistedVars.push(identifier);
});

Adding to Scope:

hoistVariables(path, (identifier, name) => {
  scope.push({ id: identifier });
});

Filtering by Declaration Kind:

// Only hoist 'let' declarations
hoistVariables(path, emitFunction, "let");

Types

// From babel-traverse
interface NodePath {
  // Babel AST path with traversal and manipulation methods
}

// From babel-types  
interface Identifier {
  // Babel identifier AST node
}

Dependencies

This package depends on:

• babel-types: For AST node creation and manipulation
• babel-runtime: For Babel runtime helpers

When using this package, you'll typically also need:

• babel-traverse: Provides the NodePath type used by the main function

Implementation Notes

• Uses Babel's visitor pattern for AST traversal
• Skips function boundaries to maintain proper variable scoping
• Handles for-loop variable declarations as a special case
• Supports both 'var' and 'let' declaration hoisting
• Preserves original variable initialization through assignment expressions