CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-babel--helper-builder-binary-assignment-operator-visitor

Helper function to build binary assignment operator visitors for Babel AST transformations

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Babel Helper: Binary Assignment Operator Visitor

A Babel helper that provides a factory function for creating AST visitors that transform binary assignment operators (like +=, -=, *=, /=, etc.) into their explicit binary operation equivalents. It handles complex assignment expressions by safely exploding assignable expressions to avoid side effects during transformation.

Package Information

  • Package Name: @babel/helper-builder-binary-assignment-operator-visitor
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babel/helper-builder-binary-assignment-operator-visitor

Core Imports

import builderVisitor from "@babel/helper-builder-binary-assignment-operator-visitor";

For CommonJS:

const builderVisitor = require("@babel/helper-builder-binary-assignment-operator-visitor");

Basic Usage

import * as t from "@babel/types";
import { Visitor } from "@babel/traverse";
import builderVisitor from "@babel/helper-builder-binary-assignment-operator-visitor";

// Create a visitor for transforming += operators
const visitor: Visitor = builderVisitor({
  operator: "+",
  build(left: t.Expression, right: t.Expression): t.Expression {
    return t.binaryExpression("+", left, right);
  }
});

// Use in a Babel plugin
export default function myPlugin() {
  return {
    visitor
  };
}

Architecture

The helper handles binary assignment operator transformation through several key components:

  • Visitor Factory: The main exported function creates customized visitors for specific operators
  • Safe Expression Handling: Uses expression explosion to avoid side effects when evaluating the left-hand side multiple times
  • AST Transformation: Converts assignment expressions (x += y) into sequence expressions with proper evaluation order
  • Binary Expression Handling: Also transforms standalone binary expressions using the provided build function

Capabilities

Visitor Builder Function

Creates a Babel visitor that transforms binary assignment operators and binary expressions for a specific operator.

/**
 * Creates a Babel visitor for transforming binary assignment operators
 * @param opts - Configuration options
 * @returns Visitor object with AssignmentExpression and BinaryExpression handlers
 */
export default function (opts: {
  /** Function that defines how to build the transformed expression from operands */
  build: (
    left: t.Expression | t.PrivateName | t.Super,
    right: t.Expression,
  ) => t.Expression;
  /** The binary operator to transform (e.g., "+", "-", "*", "/") */
  operator: t.BinaryExpression["operator"];
}): Visitor;

interface BuilderOptions {
  build: (
    left: t.Expression | t.PrivateName | t.Super,
    right: t.Expression,
  ) => t.Expression;
  operator: t.BinaryExpression["operator"];
}

Parameters:

  • opts.build: A function that takes the left and right operands and returns the transformed expression. This defines the specific transformation logic for the binary operation.
  • opts.operator: The binary operator string to transform (e.g., "+", "-", "*", "/", "%", "**", etc.)

Returns: A Babel Visitor object that can be used in Babel plugins to transform assignment expressions and binary expressions.

Usage Example:

import * as t from "@babel/types";
import builderVisitor from "@babel/helper-builder-binary-assignment-operator-visitor";

// Example: Transform *= operators for exponentiation
const visitor = builderVisitor({
  operator: "*",
  build(left, right) {
    // Custom logic for multiplication
    return t.callExpression(
      t.memberExpression(t.identifier("Math"), t.identifier("pow")),
      [left, right]
    );
  }
});

// This visitor will transform:
// x *= y  →  x = Math.pow(x, y)
// a * b   →  Math.pow(a, b)

Visitor Behavior

The returned visitor handles two types of AST nodes:

AssignmentExpression Handling:

  • Detects assignment expressions with the specified compound operator (e.g., +=, -=)
  • Safely explodes the left-hand side to avoid side effects
  • Replaces the assignment with a sequence expression containing the safe evaluation

BinaryExpression Handling:

  • Detects binary expressions with the specified operator
  • Applies the build function transformation directly

Types

// Core types imported from @babel/types and @babel/traverse
import type { Visitor } from "@babel/traverse";
import type * as t from "@babel/types";

// Binary operators supported
type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "**" | "&" | "|" | ">>" | ">>>" | "<<" | "^" | "==" | "===" | "!=" | "!==" | "<" | "<=" | ">" | ">=" | "in" | "instanceof";

// Expression types that can be used as left-hand side of assignments
type AssignableExpression = t.Expression | t.PrivateName | t.Super;

// Node types handled by the visitor
type AssignmentExpression = t.AssignmentExpression;
type BinaryExpression = t.BinaryExpression;
type MemberExpression = t.MemberExpression;
type Identifier = t.Identifier;

Error Handling

The helper includes built-in error handling for edge cases:

  • Private Name Properties: Throws an error if attempting to process private class members, suggesting to install @babel/plugin-transform-class-properties
  • Unsupported Node Types: Throws descriptive errors for node types that cannot be safely exploded

Advanced Usage

Complex Assignment Transformations

// Transform ??= (nullish coalescing assignment)
const nullishVisitor = builderVisitor({
  operator: "??",
  build(left, right) {
    return t.logicalExpression("??", left, right);
  }
});

// Transform |= (bitwise OR assignment)
const bitwiseOrVisitor = builderVisitor({
  operator: "|",
  build(left, right) {
    return t.binaryExpression("|", left, right);
  }
});

Side Effect Safety

The helper automatically handles complex left-hand side expressions:

// Input: obj.prop[computedKey()] += value
// Without safety: obj.prop[computedKey()] = obj.prop[computedKey()] + value
// With safety: (_temp = obj.prop, _temp2 = computedKey(), _temp[_temp2] = _temp[_temp2] + value)

This ensures that computedKey() is only called once, preventing potential side effects or performance issues.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babel/helper-builder-binary-assignment-operator-visitor@7.25.x
Publish Source
CLI
Badge
tessl/npm-babel--helper-builder-binary-assignment-operator-visitor badge