0
# Wildcard Match
1

2
Wildcard Match is a tiny and extremely fast JavaScript library for compiling and matching basic glob patterns. It takes one or more glob patterns, compiles them into a RegExp, and returns a function for matching strings against it. The library supports `?`, `*`, and `**` wildcards with customizable separators.
3

4
## Package Information
5

6
- **Package Name**: wildcard-match
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install wildcard-match`
10

11
## Core Imports
12

13
```typescript
14
import wcmatch from "wildcard-match";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const wcmatch = require("wildcard-match");
21
```
22

23
When loaded via CDN, wildcard-match is available as the global function `wcmatch`.
24

25
## Basic Usage
26

27
```typescript
28
import wcmatch from "wildcard-match";
29

30
// Create a matcher
31
const isMatch = wcmatch("src/**/*.?s");
32

33
// Test strings
34
isMatch("src/components/header/index.js"); // => true
35
isMatch("src/README.md"); // => false
36

37
// Access matcher properties
38
isMatch.pattern; // => 'src/**/*.?s'
39
isMatch.options; // => { separator: true }
40
isMatch.regexp; // => /^src[/\\]+?(?:[^/\\]*?[/\\]+?)*?[^/\\]*?\.[^/\\]s[/\\]*?$/
41

42
// Immediate matching (single use)
43
wcmatch("*.example.com", ".")("foo.example.com"); // => true
44

45
// Multiple patterns
46
const multiMatch = wcmatch(["src/*", "test/*"]);
47
multiMatch("src/index.js"); // => true
48
multiMatch("test/spec.js"); // => true
49
```
50

51
## Architecture
52

53
Wildcard Match is built around several key components that work together to provide fast pattern matching:
54

55
- **Pattern Transformation Engine**: Converts glob patterns into optimized regular expressions using a custom transform algorithm
56
- **Separator Handling System**: Flexible separator detection and matching that supports cross-platform paths, custom delimiters, and segment-based matching
57
- **RegExp Compilation**: Optimized regular expression generation with support for custom flags and multi-pattern OR logic
58
- **Matcher Function Factory**: Returns bound functions with embedded RegExp and metadata for optimal performance during repeated matching
59
- **Input Validation Layer**: Comprehensive type checking and error handling for patterns, options, and sample strings
60

61
The compilation process transforms glob wildcards (`?`, `*`, `**`) into RegExp patterns while respecting separator boundaries and escape sequences. The resulting matcher functions provide direct access to the compiled RegExp and original configuration for debugging and introspection.
62

63
## Capabilities
64

65
### Pattern Compilation
66

67
Compiles one or more glob patterns into a RegExp and returns a matching function.
68

69
```typescript { .api }
70
/**
71
 * Compiles one or more glob patterns into a RegExp and returns an isMatch function.
72
 * The isMatch function takes a sample string as its only argument and returns true
73
 * if the string matches the pattern(s).
74
 */
75
function wcmatch(
76
  pattern: string | string[],
77
  options?: string | boolean | WildcardMatchOptions
78
): isMatch;
79
```
80

81
**Parameters:**
82
- `pattern`: Single pattern string or array of patterns to compile
83
- `options`: Options object, or shorthand for separator setting
84

85
**Usage Examples:**
86

87
```typescript
88
// Single pattern
89
const matcher = wcmatch("src/*.js");
90

91
// Multiple patterns
92
const multiMatcher = wcmatch(["*.js", "*.ts"]);
93

94
// With separator option (shorthand)
95
const domainMatcher = wcmatch("*.example.com", ".");
96

97
// With full options
98
const caseInsensitive = wcmatch("*.TXT", { flags: "i" });
99
```
100

101
### String Matching
102

103
Tests if a sample string matches the compiled pattern(s).
104

105
```typescript { .api }
106
/**
107
 * Tests if a sample string matches the pattern(s) that were used to compile
108
 * the regular expression and create this function.
109
 */
110
interface isMatch {
111
  (sample: string): boolean;
112
  /** Compiled regular expression */
113
  regexp: RegExp;
114
  /** Original pattern or array of patterns that was used to compile the RegExp */
115
  pattern: string | string[];
116
  /** Options that were used to compile the RegExp */
117
  options: WildcardMatchOptions;
118
}
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
const isMatch = wcmatch("src/**/*.js");
125

126
// Test various strings
127
isMatch("src/index.js"); // => true
128
isMatch("src/components/Button.js"); // => true
129
isMatch("test/spec.js"); // => false
130

131
// Access properties
132
console.log(isMatch.pattern); // => "src/**/*.js"
133
console.log(isMatch.regexp); // => RegExp object
134
```
135

136
### Array Operations
137

138
The returned function works seamlessly with native array methods.
139

140
**Usage Examples:**
141

142
```typescript
143
const isMatch = wcmatch("src/*.js");
144
const paths = ["readme.md", "src/index.js", "src/components/body.js"];
145

146
paths.filter(isMatch); // => ["src/index.js"]
147
paths.some(isMatch); // => true
148
paths.every(isMatch); // => false
149
paths.find(isMatch); // => "src/index.js"
150
paths.findIndex(isMatch); // => 1
151
```
152

153
## Wildcard Syntax
154

155
Wildcard-match supports the following glob syntax:
156

157
- `?` - matches exactly one arbitrary character excluding separators
158
- `*` - matches zero or more arbitrary characters excluding separators  
159
- `**` - matches any number of segments when used as a whole segment in a separated pattern
160
- `\` - escapes the following character making it be treated literally
161

162
**Examples:**
163

164
```typescript
165
// Single character wildcard
166
wcmatch("src/?ar")("src/bar"); // => true
167
wcmatch("src/?ar")("src/car"); // => true
168

169
// Multi-character wildcard
170
wcmatch("src/*.js")("src/index.js"); // => true
171
wcmatch("src/*.js")("src/component.js"); // => true
172

173
// Multi-segment wildcard
174
wcmatch("src/**/index.js")("src/components/header/index.js"); // => true
175

176
// Escaped wildcards
177
wcmatch("literal\\*")("literal*"); // => true
178
```
179

180
## Separator Handling
181

182
Wildcard-match can work with custom separators for different use cases beyond file paths.
183

184
**Default Behavior (separator: true):**
185
- `/` in patterns matches both `/` and `\` in samples
186
- Enables cross-platform path matching
187

188
**Custom Separators:**
189

190
```typescript
191
// Domain matching with dot separator
192
const matchDomain = wcmatch("*.example.com", { separator: "." });
193
matchDomain("subdomain.example.com"); // => true
194

195
// Comma-separated values
196
const matchCSV = wcmatch("one,**,four", ",");
197
matchCSV("one,two,three,four"); // => true
198

199
// No segmentation (separator: false)
200
const matchAnything = wcmatch("foo?ba*", false);
201
matchAnything("foo/bar/qux"); // => true
202
```
203

204
**Separator Rules:**
205
- Single separator in pattern matches one or more separators in sample
206
- Trailing separator in pattern requires trailing separator(s) in sample
207
- No trailing separator in pattern allows optional trailing separators in sample
208

209
## Configuration Options
210

211
**Option Details:**
212

213
- **separator**: 
214
  - `true` (default): `/` matches both `/` and `\`
215
  - `false`: No segmentation, wildcards match across entire string
216
  - `string`: Custom separator character(s)
217
- **flags**: Standard RegExp flags (`"i"` for case-insensitive, `"g"` for global, etc.)
218

219
**Usage Examples:**
220

221
```typescript
222
// Case-insensitive matching
223
const caseInsensitive = wcmatch("*.TXT", { flags: "i" });
224
caseInsensitive("readme.txt"); // => true
225

226
// Multi-character separator
227
const pathMatcher = wcmatch("home**user", { separator: "::" });
228
pathMatcher("home::documents::user"); // => true
229
```
230

231
## Error Handling
232

233
The library throws specific errors for invalid inputs:
234

235
- **TypeError**: When pattern is not a string or array
236
- **TypeError**: When options parameter has wrong type
237
- **TypeError**: When sample passed to isMatch is not a string
238
- **Error**: When backslash `\` is used as separator (reserved for escaping)
239

240
**Examples:**
241

242
```typescript
243
// Invalid pattern type
244
wcmatch(123); // TypeError: The first argument must be a single pattern string or an array of patterns
245

246
// Invalid options type
247
wcmatch("pattern", 123); // TypeError: The second argument must be an options object or a string/boolean separator
248

249
// Invalid sample type
250
const matcher = wcmatch("*.js");
251
matcher(123); // TypeError: Sample must be a string, but number given
252

253
// Invalid separator
254
wcmatch("pattern", { separator: "\\" }); // Error: \ is not a valid separator because it is used for escaping
255
```
256

257
## Types
258

259
```typescript { .api }
260
interface WildcardMatchOptions {
261
  /** Separator to be used to split patterns and samples into segments */
262
  separator?: string | boolean;
263
  /** Flags to pass to the RegExp */
264
  flags?: string;
265
}
266

267
interface isMatch {
268
  /**
269
   * Tests if a sample string matches the pattern(s)
270
   */
271
  (sample: string): boolean;
272
  /** Compiled regular expression */
273
  regexp: RegExp;
274
  /** Original pattern or array of patterns that was used to compile the RegExp */
275
  pattern: string | string[];
276
  /** Options that were used to compile the RegExp */
277
  options: WildcardMatchOptions;
278
}
279

280
/**
281
 * Compiles one or more glob patterns into a RegExp and returns an isMatch function.
282
 */
283
declare function wcmatch(
284
  pattern: string | string[],
285
  options?: string | boolean | WildcardMatchOptions
286
): isMatch;
287

288
export default wcmatch;
289
```