@babel/plugin-transform-private-property-in-object

@babel/plugin-transform-private-property-in-object is a Babel plugin that transforms checks for private properties in objects (#property in obj syntax) into runtime-safe equivalents. It generates WeakSet-based brand checking mechanisms to detect private fields and methods, enabling modern JavaScript private field syntax across different JavaScript engines and versions.

Package Information

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

Core Imports

The plugin is used in Babel configuration, not imported directly in application code:

// babel.config.js
module.exports = {
  plugins: [
    ["@babel/plugin-transform-private-property-in-object", { loose: false }]
  ]
};

Or in package.json with babel preset:

{
  "babel": {
    "plugins": [
      ["@babel/plugin-transform-private-property-in-object", { "loose": true }]
    ]
  }
}

Basic Usage

The plugin automatically transforms private property in object checks during the Babel compilation process:

Input JavaScript:

class MyClass {
  #privateField = 42;
  #privateMethod() { return "secret"; }

  checkInstance(obj) {
    // These expressions get transformed by the plugin
    return #privateField in obj && #privateMethod in obj;
  }
}

Transformed Output (loose: false):

var _privateField = new WeakSet();
var _privateMethod = new WeakSet();

class MyClass {
  constructor() {
    _privateField.add(this);
    _privateMethod.add(this);
  }

  checkInstance(obj) {
    return _privateField.has(obj) && _privateMethod.has(obj);
  }
}

Capabilities

Plugin Factory Function

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

/**
 * Default export: Babel plugin factory function
 * Created using declare() helper for transforming private property in object checks
 * @param api - Babel plugin API with types, template, and version utilities
 * @param options - Plugin configuration options with loose mode setting
 * @returns Babel plugin configuration object with visitor pattern
 */
const plugin: (
  api: PluginAPI,
  options: Options
) => PluginObject;

export default plugin;

Plugin Configuration Options

Configuration interface for customizing plugin behavior.

/**
 * Configuration options for the private property in object transform plugin
 */
interface Options {
  /**
   * Enable loose mode for better performance but different semantics
   * - loose: true - Uses simple property checks (faster, less spec-compliant)
   * - loose: false - Uses WeakSet-based brand checking (slower, spec-compliant)
   * @default false
   */
  loose?: boolean;
}

Plugin Configuration Object

The plugin returns a standard Babel plugin configuration object with visitor pattern.

interface PluginObject {
  /** Plugin identifier name */
  name: "transform-private-property-in-object";
  
  /** Optional parser manipulation - adds "privateIn" plugin for legacy environments (disabled in Babel 8) */
  manipulateOptions?: (opts: any, parser: ParserOptions) => void;
  
  /** Pre-processing hook to enable features using helper-create-class-features-plugin */
  pre(): void;
  
  /** AST visitor configuration for transforming BinaryExpression nodes */
  visitor: {
    BinaryExpression(path: NodePath<BinaryExpression>, state: PluginPass): void;
  };
}

Types

Core Plugin Types

The plugin uses standard Babel plugin interfaces from @babel/core:

import type { PluginAPI, PluginObject, NodePath, PluginPass } from "@babel/core";

interface PluginAPI {
  /** Babel core type definitions */
  types: typeof t;
  /** Template string utilities for generating AST nodes */
  template: Template;
  /** Assert minimum Babel version compatibility */
  assertVersion(version: number | string): void;
}

interface PluginPass {
  /** Current file being processed */
  file: File;
}

interface ParserOptions {
  /** Parser plugins to enable */
  plugins: string[];
}

Helper Function Types

The plugin imports helper functions from @babel/helper-create-class-features-plugin:

/** Enable feature flag for privateIn transformation */
function enableFeature(file: File, feature: number, loose: boolean): void;

/** FEATURES constant from helper plugin */
const FEATURES: {
  privateIn: number;
};

/** Build check for right-hand side of 'in' expressions */
function buildCheckInRHS(node: Expression, file: File): Expression;

/** Version requirement helper for assertVersion() */
function REQUIRED_VERSION(major: number): number | string;

Transformation Behavior

Private Field Transformations

The plugin handles different types of private property checks:

1. Instance Private Fields: Transformed to WeakSet-based brand checking

   // Input: #field in obj
   // Output: _field_brandCheck.has(obj)

2. Static Private Methods: Transformed to class identity checking

   // Input: #staticMethod in obj  
   // Output: MyClass === obj

3. Instance Private Methods: Transformed to WeakSet-based brand checking

   // Input: #method in obj
   // Output: _class_brandCheck.has(obj)

Scope and Injection

The plugin automatically:

• Generates unique WeakSet identifiers to avoid naming conflicts
• Injects WeakSet declarations before the class definition
• Adds initialization code to constructors or field initializers
• Handles nested classes and complex scoping scenarios

Loose Mode Differences

• Strict mode (loose: false): Uses WeakSet-based brand checking for full spec compliance
• Loose mode (loose: true): May use simpler checks for better performance but different semantics

Runtime Requirements

• Node.js: >=6.9.0
• Babel Core: ^7.0.0-0 (peer dependency)
• Module Type: ES Module

Dependencies

• @babel/helper-plugin-utils: Provides declare() function for creating Babel plugins
• @babel/helper-create-class-features-plugin: Provides enableFeature(), FEATURES, buildCheckInRHS(), and injectInitialization() helpers
• @babel/helper-annotate-as-pure: Provides annotateAsPure() for marking expressions as pure for optimization

Error Handling

The plugin handles various edge cases during transformation:

• Nested classes with conflicting private property names
• Complex scoping scenarios with variable shadowing
• Pattern-based class expressions that need wrapping
• Half-constructed objects during private field initialization