0
# Picomatch
1
2
Picomatch is a blazing fast and accurate glob matcher written in JavaScript with no dependencies and full support for standard and extended Bash glob features, including braces, extglobs, POSIX brackets, and regular expressions.
3
4
## Package Information
5
6
- **Package Name**: picomatch
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install picomatch`
10
11
## Core Imports
12
13
```javascript
14
const picomatch = require('picomatch');
15
```
16
17
ES Modules:
18
19
```javascript
20
import picomatch from 'picomatch';
21
```
22
23
For POSIX-only usage:
24
25
```javascript
26
const picomatch = require('picomatch/posix');
27
```
28
29
## Basic Usage
30
31
```javascript
32
const picomatch = require('picomatch');
33
34
// Create a matcher function
35
const isMatch = picomatch('*.js');
36
37
console.log(isMatch('file.js')); // => true
38
console.log(isMatch('file.txt')); // => false
39
40
// Multiple patterns
41
const isMatchAny = picomatch(['*.js', '*.ts']);
42
console.log(isMatchAny('app.ts')); // => true
43
44
// With options
45
const matcher = picomatch('**/*.js', { ignore: '**/node_modules/**' });
46
console.log(matcher('src/utils.js')); // => true
47
console.log(matcher('node_modules/lib.js')); // => false
48
```
49
50
## Architecture
51
52
Picomatch is built around several key components:
53
54
- **Main Function**: Primary export that creates matcher functions from glob patterns
55
- **Static Methods**: Collection of utility methods for parsing, compiling, and testing patterns
56
- **Pattern Engine**: High-performance glob pattern parsing and regex compilation
57
- **Cross-Platform Support**: Windows and POSIX path handling with automatic detection
58
- **Zero Dependencies**: Self-contained implementation for minimal overhead
59
60
## Capabilities
61
62
### Core Matching
63
64
Primary matcher function creation and pattern matching capabilities. The main entry point for creating efficient matcher functions from glob patterns.
65
66
```javascript { .api }
67
/**
68
* Creates a matcher function from one or more glob patterns
69
* @param {string|string[]} glob - Glob pattern(s) to compile
70
* @param {object} options - Configuration options
71
* @param {boolean} returnState - Whether to return state information
72
* @returns {function} Matcher function that tests strings
73
*/
74
function picomatch(glob, options, returnState = false);
75
```
76
77
[Core Matching](./core-matching.md)
78
79
### Pattern Testing and Validation
80
81
Direct pattern testing without creating persistent matcher functions. Useful for one-off matching operations.
82
83
```javascript { .api }
84
/**
85
* Test input with the given regex
86
* @param {string} input - String to test
87
* @param {RegExp} regex - Regular expression to test against
88
* @param {object} options - Configuration options
89
* @param {object} context - Additional context (glob, posix)
90
* @returns {object} Object with matching info
91
*/
92
picomatch.test(input, regex, options, { glob, posix });
93
94
/**
95
* Returns true if any of the given patterns match the string
96
* @param {string} str - String to test
97
* @param {string|string[]} patterns - Glob pattern(s) to test
98
* @param {object} options - Configuration options
99
* @returns {boolean} True if any patterns match
100
*/
101
picomatch.isMatch(str, patterns, options);
102
```
103
104
[Pattern Testing](./pattern-testing.md)
105
106
### Pattern Parsing and Compilation
107
108
Low-level pattern parsing and regex compilation utilities for advanced use cases and custom implementations.
109
110
```javascript { .api }
111
/**
112
* Parse a glob pattern to create source string for regex
113
* @param {string|string[]} pattern - Glob pattern(s) to parse
114
* @param {object} options - Configuration options
115
* @returns {object|object[]} Parsed pattern object(s)
116
*/
117
picomatch.parse(pattern, options);
118
119
/**
120
* Create a regular expression from glob pattern
121
* @param {string} input - Glob pattern
122
* @param {object} options - Configuration options
123
* @param {boolean} returnOutput - Return output instead of regex
124
* @param {boolean} returnState - Include state in result
125
* @returns {RegExp} Compiled regular expression
126
*/
127
picomatch.makeRe(input, options, returnOutput, returnState);
128
```
129
130
[Pattern Parsing](./pattern-parsing.md)
131
132
### Constants and Utilities
133
134
Access to internal constants and utility functions for advanced use cases.
135
136
```javascript { .api }
137
/**
138
* Internal constants used by picomatch
139
*/
140
picomatch.constants: {
141
/** Maximum length for glob patterns */
142
MAX_LENGTH: 65536;
143
144
/** POSIX bracket expressions */
145
POSIX_REGEX_SOURCE: {
146
alnum: string;
147
alpha: string;
148
ascii: string;
149
blank: string;
150
cntrl: string;
151
digit: string;
152
graph: string;
153
lower: string;
154
print: string;
155
punct: string;
156
space: string;
157
upper: string;
158
word: string;
159
xdigit: string;
160
};
161
162
/** Regular expressions for parsing */
163
REGEX_BACKSLASH: RegExp;
164
REGEX_NON_SPECIAL_CHARS: RegExp;
165
REGEX_SPECIAL_CHARS: RegExp;
166
REGEX_SPECIAL_CHARS_BACKREF: RegExp;
167
REGEX_SPECIAL_CHARS_GLOBAL: RegExp;
168
REGEX_REMOVE_BACKSLASH: RegExp;
169
170
/** Pattern replacements for optimization */
171
REPLACEMENTS: {
172
'***': '*';
173
'**/**': '**';
174
'**/**/**': '**';
175
};
176
177
/** Character code constants */
178
CHAR_0: 48;
179
CHAR_9: 57;
180
CHAR_UPPERCASE_A: 65;
181
CHAR_LOWERCASE_A: 97;
182
CHAR_UPPERCASE_Z: 90;
183
CHAR_LOWERCASE_Z: 122;
184
CHAR_LEFT_PARENTHESES: 40;
185
CHAR_RIGHT_PARENTHESES: 41;
186
CHAR_ASTERISK: 42;
187
CHAR_AMPERSAND: 38;
188
CHAR_AT: 64;
189
CHAR_BACKWARD_SLASH: 92;
190
CHAR_CARRIAGE_RETURN: 13;
191
CHAR_CIRCUMFLEX_ACCENT: 94;
192
CHAR_COLON: 58;
193
CHAR_COMMA: 44;
194
CHAR_DOT: 46;
195
CHAR_DOUBLE_QUOTE: 34;
196
CHAR_EQUAL: 61;
197
CHAR_EXCLAMATION_MARK: 33;
198
CHAR_FORM_FEED: 12;
199
CHAR_FORWARD_SLASH: 47;
200
CHAR_GRAVE_ACCENT: 96;
201
CHAR_HASH: 35;
202
CHAR_HYPHEN_MINUS: 45;
203
CHAR_LEFT_ANGLE_BRACKET: 60;
204
CHAR_LEFT_CURLY_BRACE: 123;
205
CHAR_LEFT_SQUARE_BRACKET: 91;
206
CHAR_LINE_FEED: 10;
207
CHAR_NO_BREAK_SPACE: 160;
208
CHAR_PERCENT: 37;
209
CHAR_PLUS: 43;
210
CHAR_QUESTION_MARK: 63;
211
CHAR_RIGHT_ANGLE_BRACKET: 62;
212
CHAR_RIGHT_CURLY_BRACE: 125;
213
CHAR_RIGHT_SQUARE_BRACKET: 93;
214
CHAR_SEMICOLON: 59;
215
CHAR_SINGLE_QUOTE: 39;
216
CHAR_SPACE: 32;
217
CHAR_TAB: 9;
218
CHAR_UNDERSCORE: 95;
219
CHAR_VERTICAL_LINE: 124;
220
CHAR_ZERO_WIDTH_NOBREAK_SPACE: 65279;
221
222
/** Create extglob character definitions */
223
extglobChars: (chars: object) => {
224
'!': { type: 'negate'; open: string; close: string };
225
'?': { type: 'qmark'; open: string; close: string };
226
'+': { type: 'plus'; open: string; close: string };
227
'*': { type: 'star'; open: string; close: string };
228
'@': { type: 'at'; open: string; close: string };
229
};
230
231
/** Create glob character definitions for platform */
232
globChars: (win32: boolean) => {
233
DOT_LITERAL: string;
234
PLUS_LITERAL: string;
235
QMARK_LITERAL: string;
236
SLASH_LITERAL: string;
237
ONE_CHAR: string;
238
QMARK: string;
239
END_ANCHOR: string;
240
DOTS_SLASH: string;
241
NO_DOT: string;
242
NO_DOTS: string;
243
NO_DOT_SLASH: string;
244
NO_DOTS_SLASH: string;
245
QMARK_NO_DOT: string;
246
STAR: string;
247
START_ANCHOR: string;
248
SEP: string;
249
};
250
}
251
```
252
253
## Options
254
255
```javascript { .api }
256
interface PicomatchOptions {
257
/** Force Windows-style path handling */
258
windows?: boolean;
259
/** Patterns to ignore */
260
ignore?: string | string[];
261
/** Callback for match events */
262
onMatch?: (result: MatchResult) => void;
263
/** Callback for all results */
264
onResult?: (result: MatchResult) => void;
265
/** Callback for ignored matches */
266
onIgnore?: (result: MatchResult) => void;
267
/** Enable/disable fast path optimizations */
268
fastpaths?: boolean;
269
/** Custom path format function */
270
format?: (path: string) => string;
271
/** Enable capture groups */
272
capture?: boolean;
273
/** Match anywhere in string (not anchored) */
274
contains?: boolean;
275
/** Match only basename (equivalent to basename) */
276
basename?: boolean;
277
/** Match only basename */
278
matchBase?: boolean;
279
/** Case insensitive matching */
280
nocase?: boolean;
281
/** Enable debug mode */
282
debug?: boolean;
283
/** Custom regex flags */
284
flags?: string;
285
/** Disable globstars (**) */
286
noglobstar?: boolean;
287
/** Disable extglobs (+(a|b)) */
288
noextglob?: boolean;
289
/** Disable braces ({a,b}) */
290
nobrace?: boolean;
291
/** Disable brackets ([abc]) */
292
nobracket?: boolean;
293
/** Custom expand range function for brackets */
294
expandRange?: (left: string, right: string, options: object) => string;
295
/** Strict slash handling */
296
strictSlashes?: boolean;
297
/** Unescape regex characters */
298
unescape?: boolean;
299
/** Maximum regex length */
300
maxLength?: number;
301
/** POSIX character classes */
302
posix?: boolean;
303
/** Dot handling in patterns */
304
dot?: boolean;
305
/** Custom star replacement */
306
star?: string;
307
/** Bash compatibility mode */
308
bash?: boolean;
309
}
310
311
interface MatchResult {
312
/** Original glob pattern */
313
glob: string;
314
/** Parsed state object */
315
state: {
316
input: string;
317
tokens: Token[];
318
output: string;
319
negated: boolean;
320
fastpaths: boolean;
321
};
322
/** Compiled regular expression */
323
regex: RegExp;
324
/** Whether POSIX mode is enabled */
325
posix: boolean;
326
/** Input string being tested */
327
input: string;
328
/** Formatted output string */
329
output: string;
330
/** Regex match result */
331
match: RegExpExecArray | null;
332
/** Whether the pattern matched */
333
isMatch: boolean;
334
}
335
336
interface Token {
337
/** Token type (star, text, globstar, etc.) */
338
type: string;
339
/** Token value */
340
value: string;
341
/** Compiled output for token */
342
output?: string;
343
/** Whether token is escaped */
344
escaped?: boolean;
345
/** Whether token is negated */
346
negated?: boolean;
347
}
348
```
349
350
## Error Handling
351
352
Picomatch throws specific errors for invalid inputs and provides error handling options:
353
354
```javascript { .api }
355
/** Exception thrown for invalid patterns */
356
class TypeError extends Error {
357
constructor(message: string);
358
}
359
```
360
361
**Common Error Conditions:**
362
363
- `TypeError: Expected pattern to be a non-empty string` - when pattern is empty, null, or not a string
364
- `TypeError: Expected input to be a string` - when input to test methods is not a string
365
- Invalid regex patterns return fallback regex `/$^/` (matches nothing) when debug is false
366
- Invalid regex patterns throw errors when debug is true
367
368
**Usage Examples:**
369
370
```javascript
371
// Pattern validation
372
try {
373
const matcher = picomatch(''); // Throws TypeError
374
} catch (error) {
375
console.log(error.message); // => 'Expected pattern to be a non-empty string'
376
}
377
378
try {
379
const matcher = picomatch(null); // Throws TypeError
380
} catch (error) {
381
console.log(error.message); // => 'Expected pattern to be a non-empty string'
382
}
383
384
// Input validation
385
try {
386
picomatch.test(123, /test/); // Throws TypeError
387
} catch (error) {
388
console.log(error.message); // => 'Expected input to be a string'
389
}
390
391
// Regex error handling
392
const validRegex = picomatch.toRegex('*.js'); // Works fine
393
const invalidRegex = picomatch.toRegex('[invalid'); // Returns /$^/ (matches nothing)
394
395
// With debug mode
396
try {
397
const debugRegex = picomatch.toRegex('[invalid', { debug: true }); // Throws
398
} catch (error) {
399
console.log('Invalid regex pattern detected');
400
}
401
```