0
# Brace Expansion
1

2
Comprehensive brace pattern processing for expanding and manipulating brace expressions like `{a,b,c}` and `{1..10}`, powered by the braces library.
3

4
## Capabilities
5

6
### Brace Processing
7

8
Processes brace patterns with options to control expansion behavior.
9

10
```javascript { .api }
11
/**
12
 * Process the given brace pattern
13
 * @param {string} pattern - String with brace pattern to process
14
 * @param {object} options - Any options to change how expansion is performed
15
 * @returns {string[]} Array of processed patterns
16
 */
17
function braces(pattern, options);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const { braces } = require('micromatch');
24

25
// Basic alternation - returns regex pattern by default
26
console.log(braces('foo/{a,b,c}/bar'));
27
//=> ['foo/(a|b|c)/bar']
28

29
// Numeric range
30
console.log(braces('file{1..3}.txt'));
31
//=> ['file(1|2|3).txt']
32

33
// Character range  
34
console.log(braces('test{a..c}.js'));
35
//=> ['test(a|b|c).js']
36
```
37

38
### Brace Expansion
39

40
Expands brace patterns into individual strings (sets `expand: true` option automatically).
41

42
```javascript { .api }
43
/**
44
 * Expand braces with expand option enabled
45
 * @param {string} pattern - String with brace pattern to expand
46
 * @param {object} options - Any options to change how expansion is performed
47
 * @returns {string[]} Array of expanded patterns
48
 */
49
function braceExpand(pattern, options);
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const { braceExpand } = require('micromatch');
56

57
// Expanded alternation
58
console.log(braceExpand('foo/{a,b,c}/bar'));
59
//=> ['foo/a/bar', 'foo/b/bar', 'foo/c/bar']
60

61
// Expanded numeric range
62
console.log(braceExpand('file{1..3}.txt'));
63
//=> ['file1.txt', 'file2.txt', 'file3.txt']
64

65
// Expanded character range
66
console.log(braceExpand('test{a..c}.js'));
67
//=> ['testa.js', 'testb.js', 'testc.js']
68

69
// Complex nested patterns
70
console.log(braceExpand('src/{app,lib}/{*.js,*.ts}'));
71
//=> ['src/app/*.js', 'src/app/*.ts', 'src/lib/*.js', 'src/lib/*.ts']
72
```
73

74
### Brace Detection Utility
75

76
Helper function to detect if a string contains brace patterns (exposed for testing purposes).
77

78
```javascript { .api }
79
/**
80
 * Helper function to detect brace patterns in strings
81
 * @param {string} str - String to test for braces
82
 * @returns {boolean} Returns true if string contains brace patterns
83
 */
84
function hasBraces(str);
85
```
86

87
**Usage Examples:**
88

89
```javascript
90
const { hasBraces } = require('micromatch');
91

92
console.log(hasBraces('foo/{a,b,c}/bar')); //=> true
93
console.log(hasBraces('foo/bar')); //=> false
94
console.log(hasBraces('file{1..10}.txt')); //=> true
95
```
96

97
## Brace Pattern Types
98

99
### Alternation Patterns
100

101
Comma-separated alternatives within braces:
102

103
```javascript
104
// Basic alternation
105
'{a,b,c}' → ['a', 'b', 'c']
106

107
// With surrounding text
108
'file.{js,ts,json}' → ['file.js', 'file.ts', 'file.json']
109

110
// Nested alternation
111
'{src,test}/{*.js,*.ts}' → ['src/*.js', 'src/*.ts', 'test/*.js', 'test/*.ts']
112
```
113

114
### Numeric Ranges
115

116
Sequential numeric expansion:
117

118
```javascript
119
// Basic numeric range
120
'{1..5}' → ['1', '2', '3', '4', '5']
121

122
// With zero padding
123
'{01..05}' → ['01', '02', '03', '04', '05']
124

125
// With step increment
126
'{1..10..2}' → ['1', '3', '5', '7', '9']
127

128
// Negative numbers
129
'{-2..2}' → ['-2', '-1', '0', '1', '2']
130
```
131

132
### Character Ranges
133

134
Sequential character expansion:
135

136
```javascript
137
// Basic character range
138
'{a..e}' → ['a', 'b', 'c', 'd', 'e']
139

140
// Uppercase range
141
'{A..E}' → ['A', 'B', 'C', 'D', 'E']
142

143
// Mixed case (preserves case of endpoints)
144
'{a..E}' → ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E']
145
```
146

147
### Complex Nested Patterns
148

149
Multiple brace patterns can be combined:
150

151
```javascript
152
// Multiple brace sets
153
'{a,b}{1,2}' → ['a1', 'a2', 'b1', 'b2']
154

155
// Mixed pattern types
156
'{src,test}/file{1..3}.{js,ts}' → [
157
  'src/file1.js', 'src/file1.ts', 'src/file2.js', 'src/file2.ts',
158
  'src/file3.js', 'src/file3.ts', 'test/file1.js', 'test/file1.ts',
159
  'test/file2.js', 'test/file2.ts', 'test/file3.js', 'test/file3.ts'
160
]
161
```
162

163
## Options
164

165
### Expansion Control
166

167
- `expand: true` - Return array of expanded strings instead of regex pattern
168
- `nobrace: true` - Disable brace expansion (treat braces as literals)
169

170
### Range Options
171

172
- `expandRange: function` - Custom function for expanding ranges
173
- `rangeLimit: number` - Limit the number of range expansions (default: 65536)
174

175
### Format Options
176

177
- `nodupes: false` - Allow duplicate values in results
178
- `unescape: true` - Remove escaping from brace characters
179

180
## Error Handling
181

182
- Invalid brace patterns are treated as literal strings
183
- Empty brace patterns `{}` are treated as literal braces
184
- Malformed ranges fall back to literal interpretation
185
- Very large ranges are limited by `rangeLimit` option (default: 65536)
186

187
## Integration Notes
188

189
- The `braces()` and `braceExpand()` functions delegate to the `braces` npm package
190
- These functions are used internally by other micromatch functions during pattern processing
191
- Brace expansion happens before glob pattern matching in the main micromatch pipeline