@babel/plugin-transform-object-super

@babel/plugin-transform-object-super is a Babel plugin that transforms ES2015 object super references to ES5-compatible code. It handles super property access and method calls within object methods by replacing them with equivalent expressions that work in ES5 environments.

Package Information

• Package Name: @babel/plugin-transform-object-super
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-transform-object-super

Core Imports

// CommonJS
const plugin = require("@babel/plugin-transform-object-super");

// ESM (module type)
import plugin from "@babel/plugin-transform-object-super";

Basic Usage

Babel Configuration

Add the plugin to your Babel configuration:

// babel.config.js
module.exports = {
  plugins: [
    "@babel/plugin-transform-object-super"
  ]
};

// .babelrc
{
  "plugins": ["@babel/plugin-transform-object-super"]
}

Input/Output Examples

Example 1: Super Property Access

Input (ES2015 with object super):

var o = {
  m() {
    return super.x;
  }
};

Output (ES5 compatible):

var _obj;
var o = _obj = {
  m: function () {
    return babelHelpers.superPropGet(_obj, "x", this);
  }
};

Example 2: Super Method Call

Input:

var parent = {
  getName() {
    return "Parent";
  }
};

var child = {
  getName() {
    return super.getName() + " Child";
  }
};

Object.setPrototypeOf(child, parent);

Output:

var _obj;
var parent = {
  getName: function getName() {
    return "Parent";
  }
};

var child = _obj = {
  getName: function getName() {
    return babelHelpers.superPropGet(_obj, "getName", this).call(this) + " Child";
  }
};

Object.setPrototypeOf(child, parent);

Example 3: Loop Handling with Let Declarations

Input:

const objects = [];
for (const proto of [{x: 0}, {x: 1}]) {
  if(true) {
    objects.push({
      __proto__: proto,
      foo() {
        return super.x
      }
    });
  }
}

Output:

const objects = [];
for (const proto of [{
  x: 0
}, {
  x: 1
}]) {
  let _obj;
  if (true) {
    objects.push(_obj = {
      __proto__: proto,
      foo: function () {
        return babelHelpers.superPropGet(_obj, "x", this);
      }
    });
  }
}

Architecture

The plugin uses the Babel plugin factory pattern and consists of several key components:

• Plugin Declaration: Uses @babel/helper-plugin-utils declare() function to create the plugin
• Super Replacement: Leverages @babel/helper-replace-supers for the actual transformation logic
• Visitor Pattern: Implements ObjectExpression and Loop visitors for AST transformation
• Scoping System: Handles variable scoping for object references, using let declarations in loops and var elsewhere

The plugin processes object expressions containing methods with super references, generates unique identifiers for object references, and delegates the actual super transformation to the ReplaceSupers helper.

Capabilities

Plugin Factory Function

The main export is a Babel plugin created using the declare helper from @babel/helper-plugin-utils.

import { declare } from "@babel/helper-plugin-utils";

declare(api => {
  api.assertVersion(REQUIRED_VERSION(7));
  return {
    name: "transform-object-super",
    visitor: {
      Loop: LoopVisitor,
      ObjectExpression: ObjectExpressionVisitor
    }
  };
});

function REQUIRED_VERSION(version: number): string | number;

Plugin Return Object

The plugin factory returns a configuration object with visitor methods for AST transformation.

interface BabelPlugin {
  /** Plugin identifier name */
  name: "transform-object-super";
  /** AST visitor object containing transformation methods */
  visitor: {
    Loop: {
      exit(path: NodePath): void;
    };
    ObjectExpression(path: NodePath<t.ObjectExpression>, state: PluginPass): void;
  };
}

Internal Helper Function

The plugin includes an internal helper function for replacing super references in object methods.

function replacePropertySuper(
  path: NodePath<t.ObjectMethod>,
  getObjectRef: () => t.Identifier,
  file: File
): void;

Loop Visitor

Handles variable scoping for object references in loops, using let declarations for proper block scoping.

interface LoopVisitor {
  exit(path: NodePath): void;
}

The loop visitor:

1. Checks for object references that need let declarations
2. Pushes let bindings to the appropriate scope
3. Requeues the path for processing after scope changes

ObjectExpression Visitor

Transforms object expressions containing methods with super references.

interface ObjectExpressionVisitor {
  (path: NodePath<t.ObjectExpression>, state: PluginPass): void;
}

The ObjectExpression visitor:

1. Generates unique object reference identifiers
2. Processes each object method property
3. Delegates super transformation to replacePropertySuper
4. Creates assignment expressions for object references
5. Handles scoping based on loop context (let vs var)

ReplaceSupers Integration

The plugin uses the @babel/helper-replace-supers helper for the actual super transformation.

import ReplaceSupers from "@babel/helper-replace-supers";

// Usage within the plugin
const replaceSupers = new ReplaceSupers({
  getObjectRef: () => t.Identifier,
  methodPath: NodePath<t.ObjectMethod>,
  file: File
});

replaceSupers.replace();

Dependencies

The plugin requires these packages:

// Core dependencies
"@babel/helper-plugin-utils": "workspace:^"
"@babel/helper-replace-supers": "workspace:^"

// Peer dependency
"@babel/core": "^7.0.0-0"

// Imported types and utilities
import { types as t } from "@babel/core";
import type { File, NodePath, PluginPass } from "@babel/core";

Version Requirements

// Node.js compatibility
engines: {
  node: ">=6.9.0"
}

// Babel version requirement
api.assertVersion(REQUIRED_VERSION(7))

Types

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

// Core Babel AST types used
type ObjectExpression = t.ObjectExpression;
type ObjectMethod = t.ObjectMethod;
type Identifier = t.Identifier;
type AssignmentExpression = t.AssignmentExpression;

interface NodePath<T = t.Node> {
  node: T;
  scope: Scope;
  get(key: string): NodePath | NodePath[];
  isMethod(): boolean;
  findParent(predicate: (path: NodePath) => boolean): NodePath | null;
  replaceWith(replacement: t.Node): void;
  requeue(): void;
  isFunction(): boolean;
  isProgram(): boolean;
  isLoop(): boolean;
}

interface Scope {
  generateUidIdentifier(name: string): t.Identifier;
  push(binding: { id: t.Identifier; kind: "var" | "let" }): void;
  crawl(): void;
}

interface PluginPass {
  file: File;
  opts: any;
}

Transformation Behavior

The plugin performs the following transformations:

1. Super Property Access: Transforms super.property to babelHelpers.superPropGet(obj, "property", this)
2. Super Method Calls: Transforms super.method() to babelHelpers.superPropGet(obj, "method", this).call(this)
3. Object Reference Creation: Generates unique identifiers (_obj, _obj2, etc.) for each object containing super references
4. Assignment Expression: Wraps object literals in assignment expressions to capture the object reference
5. Loop Scoping: Uses let declarations for object references within loops, var declarations elsewhere
6. Scope Management: Properly handles variable scoping and avoids identifier conflicts

Error Handling

The plugin handles various edge cases:

• Version Compatibility: Validates Babel version at startup using api.assertVersion()
• Non-Method Properties: Gracefully skips object properties that are not methods
• AST Integrity: Maintains proper AST structure during transformations using t.cloneNode()
• Scope Conflicts: Generates unique identifiers to avoid variable name conflicts
• Loop Context: Properly detects loop contexts for appropriate variable declaration types

Use Cases

This plugin is essential for:

• Legacy Browser Support: Enabling modern super syntax in environments that don't support ES2015
• Babel Compilation Pipelines: Part of comprehensive ES2015+ to ES5 transformation
• Object-Oriented Patterns: Supporting inheritance patterns in object literals using Object.setPrototypeOf
• Library Development: Ensuring wide browser compatibility for published packages
• Prototype Chain Access: Enabling access to prototype methods in object literal inheritance patterns