Fast Brake

Fast braking match detection! Fast brake enables a plugins and extension based schema to detect matches using JavaScript very fast. This is useful for detecting ECMAscript api features, Telemetry or other spec pattern matches you'd like to spec with a focus on speed.

Installation

bun install fast-brake

Quick Start

import { fastBrakeSync, fastBrake, check } from "fast-brake";

// Fastest: sync check compatibility (no async overhead)
const fbSync = fastBrakeSync();
const isES5Compatible = fbSync.check("const x = () => {}", { target: "es5" });
console.log(isES5Compatible); // false - arrow functions are ES6+

// Async check (when you need async workflow)
const isCompatible = await check("const x = () => {}", { target: "es5" });

// Detect features (returns array of detected features)
const features = await fastBrake("const x = () => {}");
console.log(features);
// [{ name: 'arrow_functions', version: 'es2015' }]

// Factory pattern with plugins and extensions
import { es2015Plugin } from "fast-brake/plugins/es2015";
import { locExtension } from "fast-brake/extensions/loc";

// Sync version (fastest for repeated operations)
const fbSync = fastBrakeSync({
  plugins: [es2015Plugin],
  extensions: [locExtension]
});
const syncIsCompatible = fbSync.check("const x = () => {}", { target: "es5" });
const syncFeatures = fbSync.detect("const x = () => {}");

// Async version (when async is needed)
const fb = await fastBrake({
  plugins: [es2015Plugin],
  extensions: [locExtension]
});
const asyncIsCompatible = await fb.check("const x = () => {}", { target: "es5" });
const asyncFeatures = await fb.detect("const x = () => {}");

Why Fast Brake?

Other tools, like the parsers that inspired this utility provide a full AST to process files. They're incredibe! Fast Brake is optimized to a different pattern. To detect or find patterns based on matches very fast. Fast Brake is built with auto ES version detection, automatically determining the minimum required ES version for your code.

This is nice for:

• Build tools - Validate code compatibility before bundling
• Linters - Check ES version or Telemetry compliance in CI/CD
• Transpilers - Determine which features need polyfilling
• Code analysis - Understand your codebase's ES requirements

Features

• Fast - Process files faster for match a spec faster than full AST parsing (in JavaScript at lest)
• Zero Runtime Dependencies - Lightweight and secure
• Pattern Matching - Optimized string, regex-based detection
• ES5 to ES2025 - Comprehensive feature coverage (40+ features)
• Programmatic API - Simple, intuitive interface
• Performance First - Optimized for speed
• Plugin enabled - Mix and match plugins with a basic api
• Simple interface - Clean and straightforward API

Why this was made?

Pre-2025, detecting issues that can cause es issues fast in bundles, dependencies is a necessity for CI/CD. In 2025, with Telemetry, Privacy Policies, and AI, it's important to know what you have going on in your files. This is why fast-brake was built!

Initially, I was inspired by acorn.js, then meriyah (amazing tools). I submitted a pull request so I could implement plugins using meriyah. name provided inside into another direction which led me to making fast-brake—which is built on a very simple api to enable an architecture based on failing fast.

Pattern-Based Detection

fast-brake uses optimized pattern matching for maximum speed:

• String matching where possible - match strings before pattern matching
• High-performance regex patterns - patterns for each item, such as an ES feature; with string detection before to detect if the pattern matching is even required
• Single-pass scanning - Processes code once for all features
• Early exit optimization - Stops on first incompatible feature when configured
• Minimal overhead - No AST or tokenization

// Detect all ES features in code
const features = detect(code);

// Stop on first incompatible feature (fastest)
fastBrake(code, { target: "es5", throwOnFirst: true });

API Reference

fastBrake(code) or fastBrake(options)

Can be used in two ways:

1. Direct detection: Pass code string to detect features using default settings
2. Factory pattern: Pass options to create an instance with custom plugins/extensions

import { fastBrake } from "fast-brake";

// Direct detection (async)
const features = await fastBrake("const x = () => {}");
// [{ name: 'arrow_functions', version: 'es2015' }]

// Factory pattern (async)
const fb = await fastBrake({
  plugins: [es2015Plugin],
  extensions: [locExtension]
});
const features = await fb.detect("const x = () => {}");
const isCompatible = await fb.check("const x = () => {}", { target: "es5" });

Parameters:

• When called with code (string): Code to analyze
• When called with options (FastBrakeOptions):
  • plugins (Plugin[]): Array of plugins to use
  • extensions (Extension[]): Array of extensions to use

Returns:

• With code: Promise<DetectedFeature[]>
• With options: Promise<FastBrakeAPI> with detect() and check() methods

detect(code, options?)

Returns an array of detected features. This is an async function.

import { detect } from "fast-brake";

const features = await detect(`
  const arrow = () => {};
  const template = \`Hello \${name}\`;
`);

console.log(features);
// [{ name: 'arrow_functions', version: 'es2015' }]

// With plugins
const features = await detect(code, {
  plugins: [esAll, telemetryPlugin],
});

Parameters:

• code (string): Code to analyze
• options (optional):
  • plugins (Plugin[]): Array of plugins to use for detection

Returns: Promise<DetectedFeature[]>

interface DetectedFeature {
  name: string; // Feature name (e.g., 'arrow_functions')
  version: string; // Required ES version (e.g., 'es2015')
  line?: number; // Line number where feature was found
  column?: number; // Column number where feature was found
  snippet?: string; // Code snippet containing the feature
}

check(code, options)

Returns a boolean indicating if code is compatible with the target version. This is an async function.

import { check } from "fast-brake";

const isES5Compatible = await check("var x = 10;", { target: "es5" });
console.log(isES5Compatible); // true

const hasES6Features = await check("const x = () => {};", { target: "es5" });
console.log(hasES6Features); // false

// With custom plugins
const isCompatible = await check(code, {
  target: "es5",
  plugins: [myPlugin],
});

Parameters:

• code (string): Code to analyze
• options (DetectionOptions):
  • target (string): Target ES version
  • plugins? (Plugin[]): Array of plugins to use
  • throwOnFirst? (boolean): Stop on first incompatible feature
  • ignorePatterns? (string[]): Patterns to ignore
  • preprocessors? (Array<(code: string) => string>): Code preprocessors

Returns: Promise<boolean>

fastBrakeSync(options)

Synchronous factory function for creating a fast-brake instance without async/await.

import { fastBrakeSync } from "fast-brake";
import { es2015Plugin } from "fast-brake/plugins/es2015";
import { locExtension } from "fast-brake/extensions/loc";

// Create sync instance with plugins and extensions
const fbSync = fastBrakeSync({
  plugins: [es2015Plugin],
  extensions: [locExtension]
});

// Use synchronously (no await needed)
const features = fbSync.detect("const x = () => {}");
const isCompatible = fbSync.check("const x = () => {}", { target: "es5" });

Parameters:

• options (FastBrakeOptions):
  • plugins (Plugin[]): Array of plugins to use
  • extensions (Extension[]): Array of extensions to use

Returns: FastBrakeSyncAPI with synchronous detect() and check() methods

Additional Exports

Fast Brake also exports these classes and utilities:

import { Detector, Scanner, FastBrakeCache } from "fast-brake";

// Create a detector instance with custom plugins
const detector = new Detector();
await detector.initialize([myPlugin1, myPlugin2]);

// Scanner for file system operations
const scanner = new Scanner();

// Cache for performance optimization
const cache = new FastBrakeCache();

Plugin System

Fast Brake uses a plugin-based architecture for feature detection. Plugins define patterns and rules for detecting specific JavaScript features or telemetry.

Plugin Schema

Each plugin follows the types defined in the Plugin Schema:

interface Plugin {
  name: string; // Unique plugin identifier
  description: string; // Plugin description
  spec: PluginSpec; // Plugin specification
}

interface PluginSpec {
  orderedRules: string[]; // Ordered list of rules (e.g., ES versions)
  matches: Record<string, PluginMatch>; // Detection patterns mapped by feature name
}

interface PluginMatch {
  rule: string; // Rule this match belongs to (e.g., "es2015")
  strings?: string[]; // Fast string patterns to check first
  patterns?: PluginPattern[]; // Regex patterns for detailed matching
}

interface PluginPattern {
  pattern: string; // Regex pattern string
  identifier?: string; // Optional identifier for the pattern
}

Using Plugins

Plugins can be passed to any of the main functions:

import { fastBrake, detect, check } from "fast-brake";
import { es2020 } from "fast-brake/src/plugins/esversion";
import { telemetryPlugin } from "fast-brake/src/plugins/telemetry";

// Pass single plugin
const features = await fastBrake(code, { plugins: [es2020] });

// Pass multiple plugins
const results = await detect(code, {
  plugins: [es2020, telemetryPlugin],
});

// Use with check function
const isCompatible = await check(code, {
  target: "es2020",
  plugins: [es2020, telemetryPlugin],
});

Creating Custom Plugins

const myPlugin = {
  name: "my-custom-plugin",
  description: "Detects custom patterns",
  spec: {
    orderedRules: ["rule1", "rule2"],
    matches: {
      feature_name: {
        rule: "rule1",
        strings: ["console.log"],
        patterns: [
          {
            pattern: "console\\.(log|warn|error)",
            identifier: "console_methods",
          },
        ],
      },
    },
  },
};

Built-in Plugins

Fast Brake includes several built-in plugins for different detection needs:

1. ES Version Plugin

Detects ECMAScript features from ES5 through ES2025.

import { es5, es2015, es2020, esAll } from "fast-brake/src/plugins/esversion";

// Use specific version checks
const plugin = es2015; // Checks for features newer than ES2015

// Or use the complete plugin
const allFeatures = esAll; // Detects all ES features

2. Telemetry Plugin

Identifies analytics and tracking code patterns.

import {
  telemetryPlugin,
  strictTelemetryPlugin,
} from "fast-brake/src/plugins/telemetry";

// Standard telemetry detection
const plugin = telemetryPlugin;

// Strict mode treats all telemetry as errors
const strict = strictTelemetryPlugin;

3. Browserlist Plugin

Checks compatibility with specific browser versions.

import browserlistPlugin from "fast-brake/src/plugins/browserlist";

// Use the browserlist plugin
const plugin = browserlistPlugin;

4. Detect Plugin

Auto-detects the minimum required ES version.

import detectPlugin from "fast-brake/src/plugins/detect";

// Automatically determine minimum ES version
const plugin = detectPlugin;

Extensions

Fast Brake supports extensions that provide metadata and examples for enhanced detection capabilities.

Extension Schema

Each extension follows the types defined in the Extension Schema:

interface Extension {
  name: string; // Extension name
  description: string; // Extension description
  spec: {
    // Extension specification
    code: string; // Example code
    result: {
      // Example result
      name: string;
      match: string;
      spec: object; // Additional metadata
      rule: string;
      index?: number;
    };
  };
}

Using Extensions

Extensions can be passed to enhance detection with additional metadata:

import { Detector } from "fast-brake";
import { locExtension } from "fast-brake/src/extensions/loc";
import { throwExtension } from "fast-brake/src/extensions/throw";

// Use single extension
const detector = new Detector({ extensions: [locExtension] });
await detector.initialize();
const results = await detector.detect(code);

// Use multiple extensions
const enhancedDetector = new Detector({
  extensions: [locExtension, throwExtension],
});
await enhancedDetector.initialize();
const detailedResults = await enhancedDetector.detect(code);

Built-in Extensions

1. throw Extension

Provides metadata for error throwing patterns:

import { throwExtension } from "fast-brake/src/extensions/throw";

console.log(throwExtension);
// {
//   name: "throw",
//   description: "Throws an error when specific patterns...",
//   spec: {
//     code: "throw new Error('Invalid operation');",
//     result: {
//       name: "throw-statement",
//       match: "throw new Error",
//       spec: { type: "error-throw", errorType: "Error", message: "Invalid operation" },
//       rule: "throw-statement-pattern",
//       index: 0
//     }
//   }
// }

2. loc Extension

Provides metadata for location enrichment:

import { locExtension } from "fast-brake/src/extensions/loc";

console.log(locExtension);
// {
//   name: "loc",
//   description: "Enriches detected features with location information...",
//   spec: {
//     code: "const arrow = () => { return 42; }",
//     result: {
//       name: "arrow-function",
//       match: "() =>",
//       spec: {
//         loc: {
//           start: { line: 1, column: 14 },
//           end: { line: 1, column: 19 },
//           offset: 14,
//           length: 5
//         }
//       },
//       rule: "arrow-function-pattern",
//       index: 14
//     }
//   }
// }

ES Version Features

EsVersion (default plugin)

ES2015 (ES6) Features

ES2016 Features

ES2017 Features

ES2018 Features

ES2019 Features

ES2020 Features

ES2021 Features

ES2022 Features

ES2023 Features

ES2024 Features

ES2025 Features

Performance Benchmarks

ES5 (Legacy)

File size: 0.4 KB

ES2015 (Modern)

File size: 0.7 KB

ES2022 (Latest)

File size: 1.2 KB

Large File (100x)

File size: 69.4 KB

Performance Highlights

Based on the latest benchmarks:

• ~600,000 operations per second for standard ES2015/ES2022 code
• 33x faster than @babel/parser for ES feature detection
• 12x faster than meriyah (the fastest full parser)
• Optimized for real-world use - even faster on large files (665k ops/sec)
• Native performance - leverages V8/JSC optimized string operations
• Zero overhead - no AST generation or unnecessary allocations

When to use Quick vs Full mode

Quick Mode ({ quick: true }):

• Up to 7x faster than full mode
• Perfect for build tools and hot reloading
• Pattern-based detection without tokenizer validation
• Use when speed is critical

Full Mode (default):

• High accuracy with tokenizer validation
• Still faster than AST parsers
• Recommended for most use cases
• Use for linting, CI/CD, and production builds

Browser Support

Fast-brake supports detection of all ES versions from ES5 through ES2025+:

Use Cases

Build Tool Integration

import { check } from "fast-brake";

// Validate code before bundling
if (!check(sourceCode, { target: "es2015" })) {
  console.warn("Code requires transpilation for ES2015 compatibility");
}

Linting Integration

import { detect } from "fast-brake";

// Check for features not allowed in your project
const features = detect(code);
const modernFeatures = features.filter((f) =>
  ["es2020", "es2021", "es2022"].includes(f.version),
);

if (modernFeatures.length > 0) {
  console.error("Modern ES features detected:", modernFeatures);
}

CI/CD Pipeline

import { fastBrake } from "fast-brake";
import { readFileSync } from "fs";

// Validate all source files
const files = ["src/index.js", "src/utils.js"];
for (const file of files) {
  const code = readFileSync(file, "utf-8");
  try {
    fastBrake(code, { target: "es2018" });
    console.log(`${file} is ES2018 compatible`);
  } catch (error) {
    console.error(`${file}: ${error.message}`);
    process.exit(1);
  }
}

Dynamic Feature Detection

import { getMinimumESVersion } from "fast-brake";

// Determine polyfill requirements
const userCode = getUserSubmittedCode();
const requiredVersion = getMinimumESVersion(userCode);

if (requiredVersion === "es5") {
  // No polyfills needed
} else if (requiredVersion === "es2015") {
  loadES2015Polyfills();
} else {
  loadModernPolyfills();
}

TypeScript Support

fast-brake includes full TypeScript definitions:

import {
  fastBrake,
  detect,
  check,
  getMinimumESVersion,
  DetectedFeature,
  DetectionOptions,
} from "fast-brake";

const options: DetectionOptions = {
  target: "es2015",
  quick: false,
  throwOnFirst: true,
};

const features: DetectedFeature[] = detect(code, options);

Development

Remote Caching (Vercel)

Speed up builds with Vercel remote caching:

# Create .env.local with your Vercel token
echo "TURBO_TOKEN=your-vercel-token" > .env.local
echo "TURBO_TEAM=your-team-id" >> .env.local

# Get token from: https://vercel.com/account/tokens

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © @yowainwright, Jeff Wainwright