0
# Nanomatch
1

2
Nanomatch is a fast and minimal glob matcher for Node.js that provides complete Bash 4.3 wildcard support. It offers efficient pattern matching for file paths and strings using standard glob patterns like `*`, `**`, `?`, and `[...]`, with optimized performance and comprehensive caching.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES modules:
18

19
```javascript
20
import nanomatch from 'nanomatch';
21
```
22

23
## Basic Usage
24

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

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

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

37
// Filter with multiple patterns including negation
38
console.log(nanomatch(files, ['*.js', '!a.js']));
39
//=> ['c.js']
40

41
// Match with glob stars for directory traversal
42
const paths = ['src/index.js', 'lib/utils.js', 'test/spec.js'];
43
console.log(nanomatch(paths, 'src/**'));
44
//=> ['src/index.js']
45
```
46

47
## Architecture
48

49
Nanomatch is built around several key components:
50

51
- **Parser/Compiler Pipeline**: Uses snapdragon for parsing glob patterns into AST and compiling to optimized regex
52
- **Caching System**: Aggressive memoization of compiled patterns for performance
53
- **Bash Compatibility**: Full support for Bash 4.3 wildcard semantics with cross-platform normalization  
54
- **Negation Support**: Built-in support for negation patterns using `!` prefix
55
- **Options System**: Comprehensive configuration for behavior customization
56

57
## Capabilities
58

59
### Core Pattern Matching
60

61
Primary glob pattern matching functionality for filtering arrays of strings against one or more patterns.
62

63
```javascript { .api }
64
/**
65
 * Match array of strings against glob patterns
66
 * @param {Array} list - Array of strings to match
67
 * @param {String|Array} patterns - One or more glob patterns
68
 * @param {Object} options - Optional matching configuration
69
 * @returns {Array} Array of matching strings
70
 */
71
function nanomatch(list, patterns, options);
72

73
/**
74
 * Match array against single pattern
75
 * @param {Array} list - Array of strings to match  
76
 * @param {String} pattern - Single glob pattern
77
 * @param {Object} options - Optional matching configuration
78
 * @returns {Array} Array of matching strings
79
 */
80
nanomatch.match(list, pattern, options);
81

82
/**
83
 * Test if string matches pattern
84
 * @param {String} string - String to test
85
 * @param {String} pattern - Glob pattern to test against
86
 * @param {Object} options - Optional matching configuration  
87
 * @returns {Boolean} True if string matches pattern
88
 */
89
nanomatch.isMatch(string, pattern, options);
90
```
91

92
[Core Pattern Matching](./core-matching.md)
93

94
### Collection Operations
95

96
Advanced matching operations for working with arrays and performing logical operations across multiple patterns.
97

98
```javascript { .api }
99
/**
100
 * Test if some items match any patterns
101
 * @param {String|Array} list - String or array to test
102
 * @param {String|Array} patterns - Patterns to match against
103
 * @param {Object} options - Optional matching configuration
104
 * @returns {Boolean} True if any items match any patterns  
105
 */
106
nanomatch.some(list, patterns, options);
107

108
/**
109
 * Test if every item matches at least one pattern
110
 * @param {String|Array} list - String or array to test
111
 * @param {String|Array} patterns - Patterns to match against
112
 * @param {Object} options - Optional matching configuration
113
 * @returns {Boolean} True if all items match at least one pattern
114
 */
115
nanomatch.every(list, patterns, options);
116

117
/**
118
 * Test if any patterns match the string
119
 * @param {String} str - String to test
120
 * @param {String|Array} patterns - Patterns to test against
121
 * @param {Object} options - Optional matching configuration
122
 * @returns {Boolean} True if any patterns match
123
 */
124
nanomatch.any(str, patterns, options);
125

126
/**
127
 * Test if all patterns match the string  
128
 * @param {String} str - String to test
129
 * @param {String|Array} patterns - Patterns to test against
130
 * @param {Object} options - Optional matching configuration
131
 * @returns {Boolean} True if all patterns match
132
 */
133
nanomatch.all(str, patterns, options);
134

135
/**
136
 * Return strings that do not match any patterns
137
 * @param {Array} list - Array of strings to filter
138
 * @param {String|Array} patterns - Patterns to match against
139
 * @param {Object} options - Optional matching configuration
140
 * @returns {Array} Array of non-matching strings
141
 */
142
nanomatch.not(list, patterns, options);
143
```
144

145
[Collection Operations](./collection-operations.md)
146

147
### Content and Object Matching
148

149
String containment matching and object key filtering capabilities.
150

151
```javascript { .api }
152
/**
153
 * Test if pattern matches any part of string
154
 * @param {String} str - String to search within
155
 * @param {String|Array} patterns - Patterns to search for
156
 * @param {Object} options - Optional matching configuration
157
 * @returns {Boolean} True if patterns match any part of string
158
 */
159
nanomatch.contains(str, patterns, options);
160

161
/**
162
 * Filter object keys using glob patterns
163
 * @param {Object} object - Object with keys to filter
164
 * @param {String|Array} patterns - Patterns to match keys against
165
 * @param {Object} options - Optional matching configuration
166
 * @returns {Object} New object with only matching keys
167
 */
168
nanomatch.matchKeys(object, patterns, options);
169
```
170

171
[Content and Object Matching](./content-matching.md)
172

173
### Matcher Creation and Capture
174

175
Factory functions for creating reusable matchers and extracting pattern captures.
176

177
```javascript { .api }
178
/**
179
 * Create reusable matcher function from pattern
180
 * @param {String} pattern - Glob pattern to create matcher for
181
 * @param {Object} options - Optional matching configuration
182
 * @returns {Function} Matcher function that takes string and returns boolean
183
 */
184
nanomatch.matcher(pattern, options);
185

186
/**
187
 * Extract captures from pattern match
188
 * @param {String} pattern - Glob pattern with capture groups
189
 * @param {String} string - String to match and extract from
190
 * @param {Object} options - Optional matching configuration
191
 * @returns {Array|null} Array of captured groups or null if no match
192
 */
193
nanomatch.capture(pattern, string, options);
194
```
195

196
[Matcher Creation and Capture](./matcher-creation.md)
197

198
### Regex and Compilation
199

200
Low-level pattern parsing, compilation, and regex generation for advanced use cases.
201

202
```javascript { .api }
203
/**
204
 * Create regular expression from glob pattern
205
 * @param {String} pattern - Glob pattern to convert
206
 * @param {Object} options - Optional compilation configuration
207
 * @returns {RegExp} Compiled regular expression
208
 */
209
nanomatch.makeRe(pattern, options);
210

211
/**
212
 * Parse and compile pattern with full AST and metadata
213
 * @param {String} pattern - Glob pattern to parse and compile
214
 * @param {Object} options - Optional parsing/compilation configuration
215
 * @returns {Object} Object with compiled output, AST, and source map
216
 */
217
nanomatch.create(pattern, options);
218

219
/**
220
 * Parse pattern string into AST
221
 * @param {String} pattern - Glob pattern to parse
222
 * @param {Object} options - Optional parsing configuration
223
 * @returns {Object} Abstract syntax tree representation
224
 */
225
nanomatch.parse(pattern, options);
226

227
/**
228
 * Compile AST or pattern string to output
229
 * @param {Object|String} ast - AST object or pattern string to compile
230
 * @param {Object} options - Optional compilation configuration
231
 * @returns {Object} Object with compiled output and metadata
232
 */
233
nanomatch.compile(ast, options);
234
```
235

236
[Regex and Compilation](./regex-compilation.md)
237

238
### Cache Management
239

240
Control over internal pattern caching for performance optimization.
241

242
```javascript { .api }
243
/**
244
 * Clear internal pattern cache
245
 * @returns {void}
246
 */
247
nanomatch.clearCache();
248
```
249

250
### Utility Functions
251

252
Helper functions for advanced pattern analysis and option determination.
253

254
```javascript { .api }
255
/**
256
 * Determine if matchBase option should be enabled for pattern
257
 * @param {String} pattern - Glob pattern to analyze
258
 * @param {Object} options - Options object to check
259
 * @returns {Boolean} True if matchBase should be enabled
260
 */
261
nanomatch.matchBase(pattern, options);
262
```
263

264
### Exposed Internal Components
265

266
Access to nanomatch's internal parsing and compilation components for advanced customization.
267

268
```javascript { .api }
269
/**
270
 * Exposed compiler functions for advanced pattern compilation
271
 * @type {Object}
272
 */
273
nanomatch.compilers;
274

275
/**
276
 * Exposed parser functions for advanced pattern parsing
277
 * @type {Object}
278
 */
279
nanomatch.parsers;
280

281
/**
282
 * Exposed cache instance for direct cache manipulation
283
 * @type {Object}
284
 */
285
nanomatch.cache;
286
```
287

288
## Common Options
289

290
```javascript { .api }
291
interface NanomatchOptions {
292
  /** Match basenames only, ignoring directory paths */
293
  basename?: boolean;
294
  /** Alias for basename */  
295
  matchBase?: boolean;
296
  /** Enable bash-like bracket behavior (default: true) */
297
  bash?: boolean;
298
  /** Disable regex and function memoization */
299
  cache?: boolean;
300
  /** Match dotfiles (files starting with .) */
301
  dot?: boolean;
302
  /** Throw error when no matches found */
303
  failglob?: boolean;
304
  /** Patterns to ignore during matching */
305
  ignore?: string | string[];
306
  /** Case-insensitive matching */
307
  nocase?: boolean;
308
  /** Remove duplicate results (default: true) */
309
  nodupes?: boolean;
310
  /** Disable globstar (**) matching */
311
  noglobstar?: boolean;
312
  /** Disable negation (!) patterns */
313
  nonegate?: boolean;
314
  /** Return pattern if no matches found */
315
  nonull?: boolean;
316
  /** Alias for nonull */
317
  nullglob?: boolean;
318
  /** Custom slash character(s) for path separators */
319
  slash?: string | Function;
320
  /** Custom star character pattern */
321
  star?: string | Function;
322
  /** Custom snapdragon instance */
323
  snapdragon?: Object;
324
  /** Generate source maps during compilation */
325
  sourcemap?: boolean;
326
  /** Remove backslashes from returned matches */
327
  unescape?: boolean;
328
  /** Convert paths to POSIX format (default: true) */
329
  unixify?: boolean;
330
}
331
```
332

333
## Types
334

335
```javascript { .api }
336
/** Function signature for matcher functions returned by nanomatch.matcher */
337
type MatcherFunction = (str: string) => boolean;
338

339
/** Compilation result from nanomatch.create */
340
interface CompilationResult {
341
  /** Compiled regex pattern string */
342
  output: string;
343
  /** Parsed abstract syntax tree */
344
  ast: Object;
345
  /** Source map (if sourcemap option enabled) */
346
  map?: Object;
347
  /** Parser options used */
348
  options: Object;
349
  /** Parser state information */  
350
  state: Object;
351
  /** Available compilers */
352
  compilers: Object;
353
}
354

355
/** Parse result from nanomatch.parse */
356
interface ParseResult {
357
  /** AST node type */
358
  type: string;
359
  /** Input pattern string */
360
  input: string;
361
  /** Child nodes */
362
  nodes: Object[];
363
  /** Parsing errors */
364
  errors: any[];
365
}
366
```