0
# Micromatch
1

2
Micromatch is a high-performance glob matching library for JavaScript/Node.js that serves as a faster, feature-rich alternative to minimatch and multimatch. It provides comprehensive pattern matching capabilities including extended globbing (extglobs), brace expansion, POSIX bracket expressions, and regex character classes.
3

4
## Package Information
5

6
- **Package Name**: micromatch
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install micromatch`
10

11
## Core Imports
12

13
```javascript
14
const micromatch = require('micromatch');
15
```
16

17
For specific functions:
18

19
```javascript
20
const { isMatch, matcher, not, contains } = require('micromatch');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const micromatch = require('micromatch');
27

28
// Filter files using glob patterns
29
const files = ['a.js', 'b.txt', 'c.js', 'd.md'];
30
console.log(micromatch(files, '*.js')); 
31
//=> ['a.js', 'c.js']
32

33
// Test if a string matches patterns
34
console.log(micromatch.isMatch('foo.js', '*.js')); 
35
//=> true
36

37
// Use negation patterns
38
console.log(micromatch(files, ['*', '!*.txt'])); 
39
//=> ['a.js', 'c.js', 'd.md']
40
```
41

42
## Architecture
43

44
Micromatch is built around several key components:
45

46
- **Main Matching Engine**: Primary `micromatch()` function for filtering arrays of strings
47
- **Test Functions**: Boolean matching functions (`isMatch`, `contains`, `some`, `every`, `all`)
48
- **Pattern Processing**: Advanced pattern manipulation (`parse`, `scan`, `makeRe`)
49
- **Brace Expansion**: Comprehensive brace pattern support (`braces`, `braceExpand`)
50
- **Utility Functions**: Helper methods for specific use cases (`not`, `matchKeys`, `capture`)
51

52
## Capabilities
53

54
### Main Matching
55

56
Core functionality for filtering arrays of strings against glob patterns with support for negation, options, and advanced pattern features.
57

58
```javascript { .api }
59
/**
60
 * Returns an array of strings that match one or more glob patterns
61
 * @param {string|string[]} list - List of strings to match
62
 * @param {string|string[]} patterns - One or more glob patterns
63
 * @param {object} options - See available options
64
 * @returns {string[]} Array of matches
65
 */
66
function micromatch(list, patterns, options);
67
```
68

69
[Main Matching](./main-matching.md)
70

71
### Boolean Testing
72

73
Functions that return true/false for pattern matching tests, including single string tests and collection-based tests.
74

75
```javascript { .api }
76
/**
77
 * Returns true if any of the given glob patterns match the specified string
78
 * @param {string} str - The string to test
79
 * @param {string|string[]} patterns - One or more glob patterns
80
 * @param {object} options - See available options
81
 * @returns {boolean} Returns true if any patterns match str
82
 */
83
function isMatch(str, patterns, options);
84

85
/**
86
 * Returns a matcher function from the given glob pattern
87
 * @param {string} pattern - Glob pattern
88
 * @param {object} options - See available options
89
 * @returns {function} Returns a matcher function
90
 */
91
function matcher(pattern, options);
92
```
93

94
[Boolean Testing](./boolean-testing.md)
95

96
### Pattern Processing
97

98
Advanced pattern manipulation functions for creating regular expressions, parsing patterns, and analyzing pattern structure.
99

100
```javascript { .api }
101
/**
102
 * Create a regular expression from the given glob pattern
103
 * @param {string} pattern - A glob pattern to convert to regex
104
 * @param {object} options - See available options
105
 * @returns {RegExp} Returns a regex created from the given pattern
106
 */
107
function makeRe(pattern, options);
108

109
/**
110
 * Parse a glob pattern to create the source string for a regular expression
111
 * @param {string|string[]} patterns - Glob patterns to parse
112
 * @param {object} options - See available options
113
 * @returns {object[]} Returns array of parsed pattern objects
114
 */
115
function parse(patterns, options);
116
```
117

118
[Pattern Processing](./pattern-processing.md)
119

120
### Brace Expansion
121

122
Comprehensive brace pattern processing for expanding and manipulating brace expressions like `{a,b,c}` and `{1..10}`.
123

124
```javascript { .api }
125
/**
126
 * Process the given brace pattern
127
 * @param {string} pattern - String with brace pattern to process
128
 * @param {object} options - Any options to change how expansion is performed
129
 * @returns {string[]} Array of processed patterns
130
 */
131
function braces(pattern, options);
132

133
/**
134
 * Expand braces with expand option enabled
135
 * @param {string} pattern - String with brace pattern to expand
136
 * @param {object} options - Any options to change how expansion is performed
137
 * @returns {string[]} Array of expanded patterns
138
 */
139
function braceExpand(pattern, options);
140
```
141

142
[Brace Expansion](./brace-expansion.md)
143

144
### Utility Functions
145

146
Specialized utility functions for specific matching scenarios including negation filtering, object key matching, and capture groups.
147

148
```javascript { .api }
149
/**
150
 * Returns a list of strings that do not match any of the given patterns
151
 * @param {string[]} list - Array of strings to match
152
 * @param {string|string[]} patterns - One or more glob patterns
153
 * @param {object} options - See available options
154
 * @returns {string[]} Returns array of strings that do not match
155
 */
156
function not(list, patterns, options);
157

158
/**
159
 * Filter the keys of the given object with the given glob pattern
160
 * @param {object} object - The object with keys to filter
161
 * @param {string|string[]} patterns - One or more glob patterns
162
 * @param {object} options - See available options
163
 * @returns {object} Returns object with only keys that match patterns
164
 */
165
function matchKeys(object, patterns, options);
166
```
167

168
[Utility Functions](./utility-functions.md)
169

170
## Core Options
171

172
Micromatch provides extensive configuration options to control matching behavior:
173

174
```javascript { .api }
175
interface MicromatchOptions {
176
  // Matching Behavior
177
  /** Match against basename only */
178
  basename?: boolean;
179
  /** Alias for basename */
180
  matchBase?: boolean;
181
  /** Follow bash matching rules more strictly */
182
  bash?: boolean;
183
  /** Match dotfiles */
184
  dot?: boolean;
185
  /** Case-insensitive matching */
186
  nocase?: boolean;
187
  /** Allow partial string matching */
188
  contains?: boolean;
189
  
190
  // Pattern Processing
191
  /** Disable brace matching */
192
  nobrace?: boolean;
193
  /** Disable extglob support (+(a|b)) */
194
  noextglob?: boolean;
195
  /** Alias for noextglob */
196
  noext?: boolean;
197
  /** Disable globstar (**) support */
198
  noglobstar?: boolean;
199
  /** Disable negation (!) support */
200
  nonegate?: boolean;
201
  /** Disable regex brackets */
202
  nobracket?: boolean;
203
  /** Disable regex quantifiers */
204
  noquantifiers?: boolean;
205
  
206
  // Path Handling
207
  /** Convert slashes to forward slashes */
208
  posixSlashes?: boolean;
209
  /** Alias for posixSlashes */
210
  unixify?: boolean;
211
  /** Strict slash matching */
212
  strictSlashes?: boolean;
213
  /** Strict bracket/brace/paren matching */
214
  strictBrackets?: boolean;
215
  
216
  // Advanced Options
217
  /** One or more glob patterns to ignore */
218
  ignore?: string | string[];
219
  /** Throw error when no matches found */
220
  failglob?: boolean;
221
  /** Return null patterns when no matches (like Bash nullglob) */
222
  nullglob?: boolean;
223
  /** Return original patterns when no matches found */
224
  nonull?: boolean;
225
  /** Return regex matches in supporting methods */
226
  capture?: boolean;
227
  /** Enable fast-path optimization */
228
  fastpaths?: boolean;
229
  /** Support POSIX character classes */
230
  posix?: boolean;
231
  /** Remove escaping backslashes */
232
  unescape?: boolean;
233
  /** Regex flags to use */
234
  flags?: string;
235
  /** Maximum input string length */
236
  maxLength?: number;
237
  
238
  // Callback Functions
239
  /** Function called on all items */
240
  onResult?: (state: any) => void;
241
  /** Function called on matched items */
242
  onMatch?: (state: any) => void;
243
  /** Function called on ignored items */
244
  onIgnore?: (state: any) => void;
245
  
246
  // Custom Functions
247
  /** Custom function for expanding ranges */
248
  expandRange?: (a: string, b: string) => string;
249
  /** Custom function for formatting output */
250
  format?: (str: string) => string;
251
}
252
```