@babel/plugin-proposal-object-rest-spread

@babel/plugin-proposal-object-rest-spread is a Babel plugin that transforms ECMAScript object rest and spread syntax into ES5-compatible code. It enables developers to use modern object destructuring and spreading features (like {a, ...rest} = obj and {...obj, b}) while maintaining compatibility with older JavaScript environments.

Package Information

• Package Name: @babel/plugin-proposal-object-rest-spread
• Package Type: npm (Babel plugin)
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-proposal-object-rest-spread

Core Imports

The plugin can be imported directly or used through Babel configuration:

// Direct import (TypeScript/ES modules)
import objectRestSpreadPlugin from "@babel/plugin-proposal-object-rest-spread";

// CommonJS import
const objectRestSpreadPlugin = require("@babel/plugin-proposal-object-rest-spread");

Babel Configuration Usage:

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

With options:

// babel.config.js
module.exports = {
  plugins: [
    ["@babel/plugin-proposal-object-rest-spread", {
      useBuiltIns: true,
      loose: false
    }]
  ]
};

Basic Usage

This plugin automatically transforms object rest and spread syntax when included in your Babel configuration:

Input (ES2018):

// Object rest in destructuring
const { a, ...rest } = obj;

// Object spread in expressions
const newObj = { ...obj, b: 2 };

// In function parameters
function fn({ a, ...rest }) {
  console.log(rest);
}

Output (ES5):

// Object rest becomes helper calls
const { a } = obj;
const rest = _objectWithoutProperties(obj, ["a"]);

// Object spread becomes Object.assign or helpers
const newObj = _objectSpread({}, obj, { b: 2 });

// Function parameters are transformed
function fn(_ref) {
  const { a } = _ref;
  const rest = _objectWithoutProperties(_ref, ["a"]);
  console.log(rest);
}

Capabilities

Plugin Factory Function

Creates a Babel plugin that transforms object rest and spread syntax.

/**
 * Main plugin factory function that creates the Babel plugin
 * @param api - Babel API object providing compilation context and utilities
 * @param opts - Plugin configuration options (optional)
 * @returns Babel plugin object with name, inheritance, and visitor methods
 */
function objectRestSpreadPlugin(api: BabelAPI, opts?: Options): BabelPlugin;

// Default export (the actual exported function)
export default objectRestSpreadPlugin;

Plugin Interfaces

Complete type definitions for the plugin API:

interface BabelPlugin {
  name: string;
  inherits: any;
  visitor: {
    Function(path: NodePath<t.Function>): void;
    VariableDeclarator(path: NodePath<t.VariableDeclarator>, file: PluginPass): void;
    ExportNamedDeclaration(path: NodePath<t.ExportNamedDeclaration>): void;
    CatchClause(path: NodePath<t.CatchClause>): void;
    AssignmentExpression(path: NodePath<t.AssignmentExpression>, file: PluginPass): void;
    ForXStatement(path: NodePath<t.ForXStatement>): void;
    ArrayPattern(path: NodePath<t.ArrayPattern>): void;
    ObjectExpression(path: NodePath<t.ObjectExpression>, file: PluginPass): void;
  };
}

interface BabelAPI {
  assertVersion(version: number): void;
  targets(): any;
  assumption(name: string): boolean | undefined;
}

Configuration Options

Plugin options interface for customizing transformation behavior.

interface Options {
  /**
   * Whether to use built-in Object.assign instead of Babel helpers
   * @default Determined by compilation targets (true if Object.assign is supported)
   */
  useBuiltIns?: boolean;
  
  /**
   * Whether to use loose transformations for better performance
   * @default false
   */
  loose?: boolean;
}

Transformation Patterns

The plugin handles these specific object rest and spread patterns:

Object Rest Patterns

• Variable declarations: const { a, ...rest } = obj
• Function parameters: function fn({ a, ...rest }) {}
• Assignment expressions: ({ a, ...rest } = obj)
• For-loop variables: for (const { a, ...rest } of items) {}
• Catch clause parameters: catch ({ message, ...error }) {}
• Nested patterns: const [{ a, ...rest }] = array

Object Spread Patterns

• Object expressions: { ...obj, b: 2 }
• Multiple spreads: { ...obj1, ...obj2, c: 3 }
• Mixed with properties: { a: 1, ...obj, b: 2 }

Plugin Behavior

Visitor Methods

The plugin implements these AST visitor methods for transformation:

• Function: Transforms function parameters with object rest patterns
• VariableDeclarator: Handles variable declarations with object rest (const { a, ...rest } = obj)
• ExportNamedDeclaration: Processes exported variable declarations with object rest
• CatchClause: Transforms catch clause parameters with object rest patterns
• AssignmentExpression: Handles assignment expressions with object rest (({ a, ...rest } = obj))
• ForXStatement: Transforms for-in/for-of loop variables with object rest
• ArrayPattern: Processes array patterns containing object rest elements
• ObjectExpression: Transforms object expressions with spread syntax ({ ...obj })

Compilation Assumptions

The plugin respects Babel's assumption system:

• ignoreFunctionLength: Affects parameter transformation behavior (default: loose value)
• objectRestNoSymbols: Uses loose object rest helpers without symbol support (default: loose value)
• pureGetters: Assumes object property getters are pure (default: loose value)
• setSpreadProperties: Uses Object.assign-style property setting for spreads (default: loose value)

Helper Functions

The plugin generates calls to various Babel helper functions based on the source code analysis:

• extends: Core helper for object extension (or Object.assign when useBuiltIns=true)
• objectWithoutProperties: Standard object rest helper
• objectWithoutPropertiesLoose: Loose mode object rest helper (when objectRestNoSymbols assumption is true)
• objectSpread2: Modern object spread helper (preferred)
• objectSpread: Legacy object spread helper (fallback)
• objectDestructuringEmpty: For empty object destructuring patterns
• toPropertyKey: For computed property key normalization

Error Handling

The plugin validates configuration options:

// Throws error if loose option is not boolean
if (typeof loose !== "boolean") {
  throw new Error(".loose must be a boolean, or undefined");
}

Dependencies

The plugin requires these Babel packages (from actual package.json):

• @babel/helper-plugin-utils: Plugin creation utilities
• @babel/plugin-syntax-object-rest-spread: Syntax parsing support (^7.8.3)
• @babel/plugin-transform-parameters: Parameter transformation utilities
• @babel/helper-compilation-targets: Target environment compatibility
• @babel/compat-data: Browser/environment compatibility data

Peer Dependencies:

• @babel/core: ^7.0.0-0

Dev Dependencies:

• @babel/helper-plugin-test-runner: For plugin testing
• @babel/parser: AST parsing utilities