babel-plugin-transform-es3-property-literals

A Babel plugin that transforms object property keys using reserved words or invalid identifiers into quoted string literals, ensuring ES3 compatibility for legacy JavaScript environments like Internet Explorer 8 and below.

Package Information

• Package Name: babel-plugin-transform-es3-property-literals
• Package Type: npm
• Language: JavaScript (ES6/ES2015)
• Installation: npm install --save-dev babel-plugin-transform-es3-property-literals

Core Imports

The plugin is imported as a standard Babel plugin - there are no direct imports in user code since Babel handles the plugin loading.

Plugin Export Structure:

// ESM (source)
export default function ({ types: t }) { /* ... */ }

// CommonJS (built)
module.exports = function ({ types: t }) { /* ... */ }
module.exports.default = module.exports;

Babel automatically handles the plugin loading when configured in .babelrc or via API.

Basic Usage

Via .babelrc (Recommended)

{
  "plugins": ["transform-es3-property-literals"]
}

Via CLI

babel --plugins transform-es3-property-literals script.js

Via Node API

require("babel-core").transform("code", {
  plugins: ["transform-es3-property-literals"]
});

Transformation Examples

Reserved Words Transformation

Input:

var obj = {
  catch: function () {},
  default: "value",
  class: "MyClass",
  try: "reserved",
  finally: "keyword",
  switch: "statement",
  validIdentifier: "unchanged"
};

Output:

var obj = {
  "catch": function () {},
  "default": "value",
  "class": "MyClass",
  "try": "reserved",
  "finally": "keyword",
  "switch": "statement",
  validIdentifier: "unchanged"
};

What Gets Transformed vs. What Doesn't

Properties that ARE transformed:

• ES3 reserved words: catch, default, class, try, finally, switch, case, return, function, var, new, this, with, typeof, instanceof, in, void, delete, throw, debugger, etc.
• Any unquoted identifier that fails t.isValidIdentifier() check

Properties that are NOT transformed:

• Already quoted properties: "catch": value → remains unchanged
• Computed properties: [key]: value → remains unchanged
• Valid identifiers: validName: value → remains unchanged
• Numeric literals as keys: 42: value → remains unchanged

Architecture

This plugin operates within Babel's transformation pipeline using the visitor pattern:

• Plugin Phase: Runs during Babel's transform phase after parsing but before code generation
• AST Traversal: Uses Babel's visitor pattern to traverse ObjectProperty nodes
• Transformation Strategy: Applies transformations only during the "exit" phase to ensure all child nodes are processed first
• Validation Logic: Uses Babel's t.isValidIdentifier() utility to determine if property keys need quoting
• Safety: Only transforms unquoted identifiers, preserving already-quoted properties and computed properties

Integration with Babel Ecosystem:

• Compatible with all Babel 6.x versions
• Works alongside other ES3 compatibility plugins (babel-plugin-transform-es3-member-expression-literals)
• Part of Babel's ES3 preset for legacy browser support
• No runtime dependencies beyond babel-runtime

Capabilities

Plugin Factory Function

The main export that creates the Babel plugin instance.

/**
 * Babel plugin factory function that returns a plugin object
 * @param {Object} params - Babel plugin parameters
 * @param {Object} params.types - Babel types utilities (destructured as 't')
 * @returns {Object} Babel plugin object with visitor pattern
 */
export default function ({ types: t }) {
  return {
    visitor: {
      ObjectProperty: {
        exit({ node }) {
          // Plugin transformation logic
        }
      }
    }
  };
}

Plugin Structure:

• Returns a Babel plugin object with a visitor property
• Uses the visitor pattern to traverse and transform AST nodes
• Targets ObjectProperty nodes specifically
• Transforms invalid identifiers to string literals

ObjectProperty Visitor

The visitor method that processes object property nodes in the Abstract Syntax Tree (AST).

/**
 * ObjectProperty visitor that transforms invalid identifiers to string literals
 * @param {Object} path - Babel path object containing the AST node
 * @param {Object} path.node - The ObjectProperty AST node being visited
 */
ObjectProperty: {
  exit({ node }) {
    const key = node.key;
    if (!node.computed && t.isIdentifier(key) && !t.isValidIdentifier(key.name)) {
      // Transform: default: "bar" -> "default": "bar"
      node.key = t.stringLiteral(key.name);
    }
  }
}

Transformation Logic:

• Checks if the property key is an uncomputed identifier (!node.computed && t.isIdentifier(key))
• Validates if the identifier name is valid in ES3 using t.isValidIdentifier(key.name)
• Converts invalid identifiers to string literals using t.stringLiteral(key.name)
• Preserves already-quoted properties and computed properties unchanged

Types

Babel Plugin Object

interface BabelPlugin {
  visitor: {
    [NodeType: string]: {
      enter?: (path: BabelPath) => void;
      exit?: (path: BabelPath) => void;
    } | ((path: BabelPath) => void);
  };
}

interface BabelPath {
  node: ASTNode;
  // Additional Babel path properties...
}

AST Node Types

interface ObjectProperty {
  type: "ObjectProperty";
  key: Identifier | StringLiteral | Expression;
  value: Expression;
  computed: boolean;
  // Additional properties...
}

interface Identifier {
  type: "Identifier";
  name: string;
}

interface StringLiteral {
  type: "StringLiteral";
  value: string;
}

ES3 Compatibility Details

This plugin ensures JavaScript code runs in ES3 environments by addressing these issues:

• Reserved Words: Keywords like class, default, catch, try, etc. cannot be used as unquoted property names in ES3
• Invalid Identifiers: Property names starting with numbers (33rd) or containing special characters (!@#$) must be quoted
• Browser Compatibility: Enables code to run in Internet Explorer 8 and other legacy JavaScript engines

The transformation is safe and backward-compatible - quoted property names work in all JavaScript environments, while unquoted invalid identifiers only work in ES5+ environments.

Error Handling

The plugin operates during the Babel compilation phase and does not throw runtime errors. Any AST manipulation errors would be caught by Babel's internal error handling system during the build process.