Troubleshooting & FAQ

Common issues, debugging tips, and frequently asked questions for fast-brake

Understanding fast-brake

What is fast-brake?

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.

How does fast-brake work?

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

This approach makes it ideal for build tools, linters, and CI/CD pipelines where performance is critical.

Issues

1. False Positives in Strings/Comments

Problem: Features detected in strings or comments.

const code = '"const arrow = () => {}"'; // String contains arrow function

Solution: fast-brake’s patterns are designed to minimize false positives, but some edge cases may occur. For critical production use, consider validating results.

2. Performance Not Meeting Expectations

Problem: Detection is slower than expected.

Solution: Use targeted plugins for maximum performance:

// Standard detection
const features = await detect(code);

// Using Detector class for more control
import { Detector } from 'fast-brake';
const detector = new Detector();
await detector.initialize();
const result = detector.detectFast(code);

3. Missing Feature Detection

Problem: A specific ES feature isn’t being detected.

Solution: Check if the feature is supported:

// Check if a feature is being detected
const features = await detect(code);
console.log('Detected features:', features.map(f => f.name));

// For unsupported features, consider contributing!

4. Incorrect Version Mapping

Problem: Feature is detected but mapped to wrong ES version.

Solution: Verify the version mapping:

// Verify version mapping
const features = await detect('const x = obj?.prop');
console.log(features); // Should show version: 'es2020'

Debugging Techniques

1. Verbose Output

Enable detailed detection information:

const features = await detect(code);

features.forEach(feature => {
  console.log(`Feature: ${feature.name}`);
  console.log(`Version: ${feature.version}`);
});

// For more detailed debugging
import { Detector } from 'fast-brake';
const detector = new Detector();
await detector.initialize();
const result = detector.detectFast(code);
console.log('Detection result:', result);

2. Pattern Testing

Test individual patterns:

// Test if specific patterns are matching
const testCode = 'const arrow = () => {}';
const features = await detect(testCode);

if (features.some(f => f.name === 'arrow_functions')) {
  console.log('Arrow function pattern matched');
}

3. Plugin Debugging

Debug specific plugins:

import { Detector } from 'fast-brake';

// Debug with specific plugin
const detector = new Detector();
await detector.initialize(); // Can pass plugins array here

const result = detector.detectFast(code);
console.log('Detection result:', result);

Performance Optimization

1. Use Targeted Plugins

// Standard detection
const features = await detect(code);

// Using Detector for batch processing
const detector = new Detector();
await detector.initialize();

// Process multiple files
const results = files.map(file => detector.detectFast(file.content));

2. Batch Processing

// Create and reuse detector instance
const detector = new Detector();
await detector.initialize();

const results = files.map(file => ({
  path: file.path,
  result: detector.detectFast(file.content)
}));

3. Early Exit Strategy

// Check compatibility with early exit
const isCompatible = await check(code, { 
  target: 'es5',
  throwOnFirst: true // Exit on first incompatible feature
});

if (!isCompatible) {
  const features = await detect(code);
  console.error('Incompatible features:', features);
}

Error Messages

Pattern/Rule Incompatibility

This means your code contains patterns from a rule newer than your target.

// Code uses const (ES2015 pattern)
const code = 'const fn = () => {};';

// But target is ES5
const isCompatible = await check(code, { target: 'es5' });
console.log(isCompatible); // false

const patterns = await detect(code);
console.log(patterns); // [{ name: 'let_const', version: 'es2015' }]
// 'version' contains the rule name 'es2015'

Solutions:

Update your target version
Transpile the code before checking
Use a polyfill for the feature

”Unknown plugin”

This error occurs when requesting a non-existent plugin.

// Check available ES versions
const validTargets = ['es5', 'es2015', 'es2016', 'es2017', 'es2018', 'es2019', 'es2020', 'es2021', 'es2022'];

Solution: Check available plugins:

es5, es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, es2023, es2024, es2025
all, browser, telemetry, detect

Integration Issues

Build Tool Integration

Webpack:

module.exports = {
  module: {
    rules: [{
      test: /\.js$/,
      enforce: 'pre',
      loader: 'fast-brake-loader',
      options: {
        target: 'es2015',
        plugins: ['es2015'] // Optimize performance
      }
    }]
  }
};

Rollup:

import { check } from 'fast-brake';

export default {
  plugins: [{
    name: 'fast-brake',
    async transform(code) {
      const isCompatible = await check(code, { target: 'es2015' });
      if (!isCompatible) {
        this.error('Code is not ES2015 compatible');
      }
      return null;
    }
  }]
};

CI/CD Integration

GitHub Actions:

- name: Check ES Compatibility
  run: |
    npx fast-brake src/**/*.js --target es2015 --plugins es2015

Pre-commit Hook:

{
  "husky": {
    "hooks": {
      "pre-commit": "fast-brake --target es2018"
    }
  }
}

Getting Help

Resources

GitHub Issues: Report bugs or request features
Documentation: Full API Reference
Examples: Code examples and recipes

Debug Checklist

When reporting issues, please include:

Community Support

Discord: Join our community for real-time help
Stack Overflow: Tag questions with fast-brake
Twitter: Follow @yowainwright for updates

FAQ

Q: Why is fast-brake faster than AST parsers? A: fast-brake uses optimized pattern matching instead of building a full AST, focusing only on feature detection.

Q: Can fast-brake replace ESLint? A: No, fast-brake is specifically for ES feature detection, not general linting.

Q: Does fast-brake support TypeScript? A: fast-brake focuses on JavaScript. For TypeScript, strip types first using a tool like esbuild.

Q: How accurate is pattern matching? A: Very accurate for real-world code. Edge cases exist but are rare in production code.

Q: Can I add custom feature detection? A: Yes! Create custom plugins or extend the detector class. See Advanced Features.