@babel/plugin-transform-dotall-regex

@babel/plugin-transform-dotall-regex is a Babel plugin that transforms JavaScript regular expressions using the dotAll flag (s flag) to make them compatible with ES5 environments. The dotAll flag allows the dot metacharacter (.) in regular expressions to match newline characters, which is not supported in older JavaScript engines.

Package Information

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

Core Imports

This is a Babel plugin, so it's typically used in Babel configuration rather than directly imported:

{
  "plugins": ["@babel/plugin-transform-dotall-regex"]
}

For programmatic usage with Babel:

import plugin from "@babel/plugin-transform-dotall-regex";
import { declare } from "@babel/helper-plugin-utils";
import { createRegExpFeaturePlugin } from "@babel/helper-create-regexp-features-plugin";

CommonJS:

const plugin = require("@babel/plugin-transform-dotall-regex");
const { declare } = require("@babel/helper-plugin-utils");
const { createRegExpFeaturePlugin } = require("@babel/helper-create-regexp-features-plugin");

Basic Usage

Babel Configuration

Add the plugin to your .babelrc or babel.config.js:

{
  "plugins": ["@babel/plugin-transform-dotall-regex"]
}

Transformation Example

Input (ES2018 with dotAll flag):

var a = /./;    // Matches any character except newlines
var b = /./s;   // Matches any character including newlines (dotAll)

Output (ES5 compatible):

var a = /./;    // Unchanged - no dotAll flag
var b = /[^]/;  // Transformed - [^] matches any character including newlines

Programmatic Usage

import { transform } from "@babel/core";
import plugin from "@babel/plugin-transform-dotall-regex";

const code = `
const regex = /pattern./s;
const multiFlag = /test./gisu;
`;

const result = transform(code, {
  plugins: [plugin]
});

console.log(result.code);
// Output: 
// const regex = /pattern[^]/;
// const multiFlag = /test[^]/giu;

Capabilities

Babel Plugin Factory

The main export is a Babel plugin factory function that creates a plugin instance configured for dotAll regex transformation.

/**
 * Creates a Babel plugin for transforming dotAll regex patterns
 * @param api - Babel API object with assertVersion method and other utilities
 * @returns Babel plugin object configured for dotAll transformation
 */
export default declare(api => {
  api.assertVersion(REQUIRED_VERSION(7));
  return createRegExpFeaturePlugin({
    name: "transform-dotall-regex",
    feature: "dotAllFlag",
  });
});

// Dependencies - imported from helper packages
function createRegExpFeaturePlugin(options: RegExpFeatureOptions): PluginObject;
function declare(factory: (api: BabelAPI) => PluginObject): BabelPlugin;
function REQUIRED_VERSION(version: number): number | string;

interface BabelAPI {
  assertVersion(version: number | string): void;
  types: typeof t;
  template: typeof template;
  traverse: typeof traverse;
}

interface RegExpFeatureOptions {
  name: string;
  feature: string;
}

interface PluginObject {
  name: string;
  visitor: Visitor;
}

type BabelPlugin = (api: BabelAPI) => PluginObject;
type Visitor = Record<string, Function>;

The plugin:

• Uses createRegExpFeaturePlugin from @babel/helper-create-regexp-features-plugin
• Uses declare from @babel/helper-plugin-utils to create the plugin factory
• Configured with name "transform-dotall-regex" and feature "dotAllFlag"
• Requires Babel version 7 or higher via REQUIRED_VERSION(7) assertion
• Automatically detects and transforms regex literals with the s flag
• Returns a standard Babel plugin object with visitor pattern for AST transformation

Transformation Behavior

The plugin performs the following transformations:

1. Detects dotAll flag: Identifies regular expressions with the s flag (e.g., /pattern/s)
2. Preserves other flags: Maintains other regex flags like g, i, m, u
3. Transforms dot metacharacter: Converts . to [^] when dotAll flag is present
4. Removes dotAll flag: Removes the s flag from the transformed regex
5. ES5 compatibility: Ensures the output works in pre-ES2018 environments

Types

// Core plugin types
type BabelPlugin = (api: BabelAPI) => PluginObject;

// Babel API provided to plugin factory
interface BabelAPI {
  assertVersion(version: number | string): void;
  types: typeof t; // @babel/types
  template: typeof template; // @babel/template  
  traverse: typeof traverse; // @babel/traverse
  targets(): Targets; // Browser/Node targets
}

// Plugin configuration options for createRegExpFeaturePlugin
interface RegExpFeatureOptions {
  name: string; // Plugin identification name
  feature: string; // RegExp feature to transform ("dotAllFlag")
}

// Standard Babel plugin object structure
interface PluginObject {
  name: string;
  visitor: Visitor; // AST visitor pattern
}

// Version assertion function (global in Babel build)
function REQUIRED_VERSION(version: number): number | string;
function REQUIRED_VERSION(version: string): string;

Dependencies

Runtime Dependencies

• @babel/helper-create-regexp-features-plugin: Core regex transformation functionality
• @babel/helper-plugin-utils: Babel plugin utilities

Peer Dependencies

• @babel/core: ^7.0.0-0 (Required Babel version)

Error Handling

The plugin leverages Babel's built-in error handling and the regexp features plugin infrastructure. Common scenarios:

• Invalid regex syntax: Babel will report syntax errors during parsing
• Unsupported Babel version: Plugin asserts Babel 7+ requirement via REQUIRED_VERSION(7) - throws error if version < 7
• Transform failures: Handled by the underlying regexp features plugin
• Missing dependencies: Runtime errors if @babel/helper-create-regexp-features-plugin or @babel/helper-plugin-utils are not available

Browser Compatibility

This plugin enables dotAll regex functionality in:

• ES5 environments: Internet Explorer 9+, older Node.js versions
• Pre-ES2018 browsers: Chrome < 62, Firefox < 78, Safari < 11.1
• Modern environments: No transformation needed, but plugin is safe to use

The transformed output ([^] character class) is supported in all JavaScript engines that support regular expressions.