minimatch-fast

Drop-in replacement for minimatch.
6-25x faster. Zero vulnerabilities.

npm install minimatch-fast

Get Started GitHub

MIT License

Why minimatch-fast?

The performance and security upgrade your glob matching needs

Lightning Fast

6-25x faster than minimatch. Powered by picomatch engine with LRU caching and optimized fast paths for common patterns.

Secure

Not vulnerable to CVE-2022-3517 (ReDoS). Built-in protection against catastrophic backtracking and DoS attacks.

Stable

Never freezes on patterns like {1..1000}. Limits on brace expansion prevent hanging or memory issues.

100% Compatible

Drop-in replacement with identical API. 355 tests ensure full compatibility with minimatch v10.x behavior.

TypeScript Ready

Full TypeScript support with complete type definitions included. No need to install separate @types packages.

Dual Module Support

Works with both ESM and CommonJS. Use import or require() - we support both module systems out of the box.

Performance Benchmarks

Real measurements comparing minimatch-fast vs minimatch v10.x

Pattern	minimatch	minimatch-fast
`Simple star (*.js)`	Baseline	6.5x faster
`Globstar (*/.js)`	Baseline	5.9x faster
`Brace patterns ({a,b})`	Baseline	15.1x faster
`Complex braces`	Baseline	26.6x faster
`Character class ([0-9])`	Baseline	7.3x faster
`Negation patterns (!*.min.js)`	Baseline	6.5x faster
`Pre-compiled class`	Baseline	1.5x faster

Security Comparison

Feature	minimatch	minimatch-fast
CVE-2022-3517 (ReDoS)	Vulnerable	Not affected
Pattern {1..1000}	Freezes	Instant
Brace expansion limit	None	10,000 max

Benchmarks run on Node.js with 10,000 iterations per pattern. Results may vary based on hardware and pattern complexity.

Installation

Two ways to upgrade from minimatch

Option 1: Update imports

Install the package and update your import statements:

Terminal

npm uninstall minimatch
npm install minimatch-fast

Then update your imports:

- const minimatch = require('minimatch');
+ const minimatch = require('minimatch-fast');

- import minimatch from 'minimatch';
+ import minimatch from 'minimatch-fast';

Option 2: npm aliasing

Zero code changes required. Use npm's package aliasing:

Terminal

npm install minimatch@npm:minimatch-fast

This installs minimatch-fast as minimatch, so all your existing imports continue to work without any changes.

Note: This also updates minimatch for all your dependencies that use it.

Usage Examples

Common patterns and use cases

Basic Matching

import minimatch from 'minimatch-fast';

// Basic matching
minimatch('foo.js', '*.js');    // true
minimatch('bar.txt', '*.js');   // false

// Globstar (recursive)
minimatch('src/utils/helpers.js', '**/*.js');  // true
minimatch('test/foo/bar.spec.ts', '**/*.ts');  // true

Match Array

import { minimatch } from 'minimatch-fast';

const files = ['foo.js', 'bar.js', 'baz.txt', 'qux.md'];

// Match array of files
minimatch.match(files, '*.js');
// => ['foo.js', 'bar.js']

minimatch.match(files, '*.{js,md}');
// => ['foo.js', 'bar.js', 'qux.md']

Filter Function

import { minimatch } from 'minimatch-fast';

const files = ['src/index.js', 'src/utils.js', 'test/foo.spec.js'];

// Create a filter function
const isSource = minimatch.filter('src/**/*.js');

files.filter(isSource);
// => ['src/index.js', 'src/utils.js']

Minimatch Class

import { Minimatch } from 'minimatch-fast';

// Pre-compile pattern for repeated matching
const mm = new Minimatch('**/*.js', { dot: true });

// Match multiple files efficiently
mm.match('src/index.js');     // true
mm.match('.eslintrc.js');     // true (dot: true)
mm.match('README.md');        // false

// Access the compiled regex
console.log(mm.regexp);       // /^(?:(?!...)...$/

Brace Expansion

import { minimatch } from 'minimatch-fast';

// Brace expansion
minimatch.braceExpand('{a,b,c}');
// => ['a', 'b', 'c']

minimatch.braceExpand('{1..5}');
// => ['1', '2', '3', '4', '5']

minimatch.braceExpand('file{A,B}.{js,ts}');
// => ['fileA.js', 'fileA.ts', 'fileB.js', 'fileB.ts']

Escape / Unescape

import { minimatch } from 'minimatch-fast';

// Escape special characters
minimatch.escape('[foo].js');
// => '\\[foo\\].js'

// Unescape
minimatch.unescape('\\[foo\\].js');
// => '[foo].js'

Glob Pattern Reference

Complete guide to glob pattern syntax

Pattern	Description	Example
`*`	Match any characters except path separators	`*.js matches foo.js, bar.js`
`**`	Match any characters including path separators (globstar)	`*/.js matches src/foo.js, a/b/c.js`
`?`	Match exactly one character (except path separator)	`?.js matches a.js, b.js`
`[abc]`	Match any character in the set	`[abc].js matches a.js, b.js, c.js`
`[a-z]`	Match any character in the range	`[a-z].js matches a.js through z.js`
`[!abc]`	Match any character NOT in the set	`[!a].js matches b.js, c.js (not a.js)`
`{a,b,c}`	Match any of the comma-separated patterns	`{foo,bar}.js matches foo.js, bar.js`
`{1..5}`	Match numeric range	`file{1..3}.js matches file1.js, file2.js, file3.js`
`{a..c}`	Match alphabetic range	`{a..c}.js matches a.js, b.js, c.js`
`!pattern`	Negate the match	`!*.min.js excludes minified files`
`?(a\|b)`	Match zero or one of the patterns	`?(foo).js matches .js, foo.js`
`*(a\|b)`	Match zero or more of the patterns	`*(a\|b).js matches .js, a.js, ab.js, aab.js`
`+(a\|b)`	Match one or more of the patterns	`+(a\|b).js matches a.js, ab.js, aab.js`
`@(a\|b)`	Match exactly one of the patterns	`@(foo\|bar).js matches foo.js, bar.js`

POSIX Character Classes

Full support for POSIX bracket expressions

Class	Description	Example
`[[:alpha:]]`	Alphabetic characters (a-z, A-Z)	`[[:alpha:]]*.txt matches file.txt`
`[[:digit:]]`	Numeric digits (0-9)	`file[[:digit:]].js matches file1.js`
`[[:alnum:]]`	Alphanumeric (letters and digits)	`[[:alnum:]] matches a, Z, 5`
`[[:space:]]`	Whitespace characters	`[[:space:]] matches space, tab`
`[[:upper:]]`	Uppercase letters	`[[:upper:]] matches A but not a`
`[[:lower:]]`	Lowercase letters	`[[:lower:]] matches a but not A`
`[[:xdigit:]]`	Hexadecimal digits (0-9, a-f, A-F)	`[[:xdigit:]] matches 0, a, F`

Unicode Support

Full Unicode and emoji support in patterns and filenames

Pattern	Description	Matches
`*.txt`	Full Unicode support in filenames	`café.txt, 文件.txt, ファイル.txt`
`文件夹/*.js`	Unicode in patterns	`文件夹/test.js matches`
`{🎉,🎊}.txt`	Emoji support	`🎉.txt, 🎊.txt`

API Reference

Complete API documentation

minimatch(path, pattern, [options])

Test a path against a pattern. Returns true if the path matches.

Parameters

path string The path to test
pattern string The glob pattern
options MinimatchOptions Optional configuration

Returns

boolean

Example

 minimatch('foo.js', '*.js'); // true
minimatch('foo/bar.js', '**/*.js'); // true  

minimatch.match(list, pattern, [options])

Filter an array of paths, returning those that match the pattern.

Parameters

list string[] Array of paths to filter
pattern string The glob pattern
options MinimatchOptions Optional configuration

Returns

string[]

Example

 const files = ['a.js', 'b.ts', 'c.js'];
minimatch.match(files, '*.js');
// => ['a.js', 'c.js']  

minimatch.filter(pattern, [options])

Create a filter function for use with Array.filter().

Parameters

pattern string The glob pattern
options MinimatchOptions Optional configuration

Returns

(path: string) => boolean

Example

 const isJS = minimatch.filter('*.js');
['a.js', 'b.ts'].filter(isJS);
// => ['a.js']  

minimatch.makeRe(pattern, [options])

Create a regular expression from the pattern.

Parameters

pattern string The glob pattern
options MinimatchOptions Optional configuration

Returns

RegExp | false

Example

 minimatch.makeRe('*.js');
// => /^(?:(?!\.)...)\.js$/  

minimatch.braceExpand(pattern, [options])

Expand brace patterns into an array of patterns.

Parameters

pattern string Pattern with braces
options MinimatchOptions Optional configuration

Returns

string[]

Example

 minimatch.braceExpand('{a,b}{1,2}');
// => ['a1', 'a2', 'b1', 'b2']  

minimatch.escape(str, [options])

Escape special glob characters in a string.

Parameters

str string String to escape
options { windowsPathsNoEscape?: boolean } Optional configuration

Returns

string

Example

 minimatch.escape('[foo].js');
// => '\\[foo\\].js'  

minimatch.unescape(str, [options])

Remove escape characters from a string.

Parameters

str string String to unescape
options { windowsPathsNoEscape?: boolean } Optional configuration

Returns

string

Example

 minimatch.unescape('\\[foo\\].js');
// => '[foo].js'  

minimatch.defaults(options)

Create a new minimatch function with default options.

Parameters

options MinimatchOptions Default options to apply

Returns

typeof minimatch

Example

 const mm = minimatch.defaults({ nocase: true });
mm('FOO.js', '*.js'); // true  

new Minimatch(pattern, [options])

Create a reusable matcher for a pattern. More efficient when matching the same pattern against multiple paths.

Parameters

pattern string The glob pattern
options MinimatchOptions Optional configuration

Returns

Minimatch

Example

 const mm = new Minimatch('**/*.js');
mm.match('src/foo.js'); // true
mm.match('test/bar.js'); // true  

Options

Configuration options for fine-tuning pattern matching

Option	Type	Default	Description
`dot`	`boolean`	`false`	Match dotfiles (files starting with .). By default, * and ? do not match leading dots.
`nocase`	`boolean`	`false`	Perform case-insensitive matching.
`nonegate`	`boolean`	`false`	Suppress negation behavior with leading !.
`nobrace`	`boolean`	`false`	Do not expand brace patterns like {a,b,c}.
`noext`	`boolean`	`false`	Disable extglob patterns like ?(a\|b), *(a\|b), etc.
`noglobstar`	`boolean`	`false`	Disable ** matching across directory boundaries.
`nocomment`	`boolean`	`false`	Suppress treating # as a comment character.
`matchBase`	`boolean`	`false`	If pattern has no slashes, match basename of the path. foo matches bar/baz/foo.
`partial`	`boolean`	`false`	Partial match: pattern can match a portion of the path.
`flipNegate`	`boolean`	`false`	Returns true for negated patterns that do not match.
`preserveMultipleSlashes`	`boolean`	`false`	Do not collapse multiple slashes (a//b stays as a//b).
`optimizationLevel`	`number`	`1`	Regex optimization level: 0 = none, 1 = safe (default), 2 = aggressive.
`platform`	`string`	`process.platform`	Platform for path handling: "win32", "darwin", "linux", etc.
`windowsPathsNoEscape`	`boolean`	`false`	On Windows, treat \ as path separator, not escape character.
`allowWindowsEscape`	`boolean`	`platform !== "win32"`	Allow \ as escape character on Windows.
`nocaseMagicOnly`	`boolean`	`false`	Only apply nocase to magic portions of the pattern.
`magicalBraces`	`boolean`	`false`	Treat brace expansion as magic (affects hasMagic()).
`debug`	`boolean`	`false`	Enable debug output.

Security

Built-in protection against common vulnerabilities

CVE-2022-3517 Protection

The original minimatch is vulnerable to Regular Expression Denial of Service (ReDoS) via CVE-2022-3517. Malicious patterns can cause catastrophic backtracking, freezing your application.

minimatch-fast uses picomatch internally, which is specifically designed to avoid backtracking issues and is not vulnerable to this CVE.

// CVE-2022-3517 - Vulnerable pattern in minimatch
// This causes catastrophic backtracking (ReDoS)
const pattern = '[!' + 'a'.repeat(50000) + ']';

// In minimatch: hangs for minutes or crashes
minimatch('test', pattern);

// In minimatch-fast: instant, no vulnerability
minimatch('test', pattern); // false, returns immediately

Brace Expansion Limits

Unconstrained brace expansion can be exploited to create denial of service attacks. A pattern like {1..1000000} would generate a million patterns, consuming all available memory.

minimatch-fast limits brace expansion to 10,000 patterns maximum and range expansion to 1,000 items, preventing DoS attacks.

// Dangerous brace expansion in minimatch
// This creates 1,000,000 patterns and freezes

const pattern = '{1..1000000}';
minimatch.braceExpand(pattern); // Hangs

// In minimatch-fast: limited to 10,000 max
// Returns original pattern if limit exceeded

Security Features

Not affected by CVE-2022-3517 (ReDoS)
Maximum 10,000 patterns from brace expansion
Maximum 1,000 items in range expansion ({1..N})
No catastrophic backtracking in regex
Graceful fallback for oversized patterns

TypeScript Support

Full type definitions included

minimatch-fast ships with complete TypeScript definitions. All types are exported and ready to use without installing separate @types packages.

import minimatch, {
  Minimatch,
  MinimatchOptions,
  MMRegExp
} from 'minimatch-fast';

// Options with full type support
const options: MinimatchOptions = {
  dot: true,
  nocase: true,
  noglobstar: false
};

// Basic matching
const matches: boolean = minimatch('foo.js', '*.js', options);

// Minimatch class
const mm: Minimatch = new Minimatch('**/*.ts', options);
const isMatch: boolean = mm.match('src/index.ts');

// Get the compiled regex
const regex: MMRegExp | false = mm.makeRe();

// Filter function
const filter: (p: string) => boolean = minimatch.filter('*.js');

// Match array
const files: string[] = minimatch.match(['a.js', 'b.ts'], '*.js');

// Brace expansion
const expanded: string[] = minimatch.braceExpand('{a,b,c}');

Exported Types

minimatch - The main function
Minimatch - The Minimatch class
MinimatchOptions - Configuration options interface
MMRegExp - Extended RegExp with index info
ParseReturn - Type for parsed pattern segments
AST - Type for the abstract syntax tree

Testing & Compatibility

Comprehensive test suite ensures reliability

Unit Tests

Core functionality tests

196

Compatibility Tests

Behavior parity with minimatch

Edge Case Tests

Windows paths, dotfiles, negation

Security Tests

CVE-2022-3517 regression tests

Verification Tests

POSIX classes, Unicode, regex edge cases

355 Tests Total

Every release is verified against the original minimatch test suite plus additional tests for edge cases, Windows paths, and security vulnerabilities.

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run compatibility tests only
npm run test:compat

Reporting Issues

Found a compatibility issue? Please open an issue on GitHub with:

The pattern and path that produces different results
Expected behavior (what minimatch returns)
Actual behavior (what minimatch-fast returns)
Any relevant options used

Open an issue on GitHub

Changelog

Project evolution and version history

v0.2.0 Current

29/12/2025

9.4x faster average

LRU pattern cache (500 entries)Fast paths for simple patternsBrace expansion cache (200 entries)Cache utility functions

Added Pattern cache for compiled Minimatch instances
Added Fast paths for *, *.js, ???, .* patterns
Added Brace expansion cache
Added clearCache() and getCacheSize() utilities
Changed Pre-computed regex flags in Minimatch class
Changed Optimized basename extraction
Changed Smarter Windows path normalization

v0.1.0 Initial Release

10/11/2025

7-29x faster

100% API compatible with minimatchPowered by picomatch engineFull TypeScript supportDual ESM/CJS exports

Added Initial release of minimatch-fast
Added 100% API compatibility with minimatch v10.x
Added Full TypeScript support with type definitions
Added Dual ESM and CommonJS module exports
Added Comprehensive test suite (302 tests)
Added GitHub Actions CI/CD pipeline
Security Not affected by CVE-2022-3517 (ReDoS)
Security Limits on brace expansion to prevent DoS