0
# Collection Operations
1

2
Advanced matching operations for working with arrays and performing logical operations across multiple patterns. These functions provide boolean logic and set operations for pattern matching.
3

4
## Capabilities
5

6
### Some Operation
7

8
Test if some elements in a collection match any of the given patterns.
9

10
```javascript { .api }
11
/**
12
 * Test if some elements match any patterns (short-circuit evaluation)
13
 * @param {String|Array} list - String or array of strings to test
14
 * @param {String|Array} patterns - One or more patterns to match against
15
 * @param {Object} options - Optional configuration object
16
 * @returns {Boolean} True if any elements match any patterns
17
 */
18
nanomatch.some(list, patterns, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const nanomatch = require('nanomatch');
25

26
// Test array elements
27
console.log(nanomatch.some(['foo.js', 'bar.txt'], '*.js'));
28
//=> true (foo.js matches)
29

30
console.log(nanomatch.some(['foo.txt', 'bar.md'], '*.js'));
31
//=> false (no matches)
32

33
// Multiple patterns
34
console.log(nanomatch.some(['foo.css', 'bar.js'], ['*.js', '*.ts']));
35
//=> true (bar.js matches *.js)
36

37
// With negation patterns
38
console.log(nanomatch.some(['foo.js', 'bar.js'], ['*.js', '!foo.js']));
39
//=> true (bar.js matches the combined pattern)
40

41
console.log(nanomatch.some(['foo.js'], ['*.js', '!foo.js']));
42
//=> false (foo.js is excluded by negation)
43

44
// Single string input
45
console.log(nanomatch.some('test.js', '*.js'));
46
//=> true
47
```
48

49
### Every Operation
50

51
Test if every element in a collection matches at least one of the given patterns.
52

53
```javascript { .api }
54
/**
55
 * Test if every element matches at least one pattern
56
 * @param {String|Array} list - String or array of strings to test
57
 * @param {String|Array} patterns - One or more patterns to match against
58
 * @param {Object} options - Optional configuration object
59
 * @returns {Boolean} True if all elements match at least one pattern
60
 */
61
nanomatch.every(list, patterns, options);
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
const nanomatch = require('nanomatch');
68

69
// All elements must match
70
console.log(nanomatch.every(['foo.js', 'bar.js'], '*.js'));
71
//=> true (both match)
72

73
console.log(nanomatch.every(['foo.js', 'bar.txt'], '*.js'));
74
//=> false (bar.txt doesn't match)
75

76
// Multiple patterns - each element needs one match
77
console.log(nanomatch.every(['foo.js', 'bar.css'], ['*.js', '*.css']));
78
//=> true (foo.js matches *.js, bar.css matches *.css)
79

80
// With negation
81
console.log(nanomatch.every(['bar.js', 'baz.js'], ['*.js', '!foo.js']));
82
//=> true (both match *.js and neither is foo.js)
83

84
console.log(nanomatch.every(['foo.js', 'bar.js'], ['*.js', '!foo.js']));
85
//=> false (foo.js is excluded by negation)
86

87
// Single string input
88
console.log(nanomatch.every('test.js', '*.js'));
89
//=> true
90
```
91

92
### Any Pattern Matching
93

94
Test if any of the given patterns match a single string.
95

96
```javascript { .api }
97
/**
98
 * Test if any patterns match the given string
99
 * @param {String} str - String to test against patterns
100
 * @param {String|Array} patterns - One or more patterns to test
101
 * @param {Object} options - Optional configuration object
102
 * @returns {Boolean} True if any patterns match the string
103
 */
104
nanomatch.any(str, patterns, options);
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
const nanomatch = require('nanomatch');
111

112
// Multiple patterns, any can match
113
console.log(nanomatch.any('foo.js', ['*.txt', '*.js']));
114
//=> true (matches *.js)
115

116
console.log(nanomatch.any('foo.css', ['*.txt', '*.js']));
117
//=> false (no patterns match)
118

119
// Single pattern (equivalent to isMatch)
120
console.log(nanomatch.any('test.js', '*.js'));
121
//=> true
122

123
// Complex patterns
124
console.log(nanomatch.any('src/utils.js', ['lib/**', 'src/**']));
125
//=> true (matches src/**)
126

127
// Empty patterns
128
console.log(nanomatch.any('test.js', []));
129
//=> false
130

131
console.log(nanomatch.any('test.js', ''));
132
//=> false
133
```
134

135
### All Pattern Matching
136

137
Test if all of the given patterns match a single string.
138

139
```javascript { .api }
140
/**
141
 * Test if all patterns match the given string
142
 * @param {String} str - String to test against patterns
143
 * @param {String|Array} patterns - One or more patterns that must all match
144
 * @param {Object} options - Optional configuration object
145
 * @returns {Boolean} True if all patterns match the string
146
 */
147
nanomatch.all(str, patterns, options);
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
const nanomatch = require('nanomatch');
154

155
// All patterns must match
156
console.log(nanomatch.all('foo.js', ['foo*', '*.js']));
157
//=> true (matches both patterns)
158

159
console.log(nanomatch.all('bar.js', ['foo*', '*.js']));
160
//=> false (doesn't match foo*)
161

162
// Single pattern
163
console.log(nanomatch.all('test.js', '*.js'));
164
//=> true
165

166
// Complex patterns
167
console.log(nanomatch.all('src/utils.js', ['src/**', '**/utils.js']));
168
//=> true (matches both)
169

170
// With negation (all patterns including negation must match)
171
console.log(nanomatch.all('bar.js', ['*.js', '!foo.js']));
172
//=> true (matches *.js and is not foo.js)
173

174
console.log(nanomatch.all('foo.js', ['*.js', '!foo.js']));
175
//=> false (matches *.js but fails !foo.js)
176
```
177

178
### Negation Filtering
179

180
Return elements that do not match any of the given patterns.
181

182
```javascript { .api }
183
/**
184
 * Return strings that do not match any patterns
185
 * @param {Array} list - Array of strings to filter
186
 * @param {String|Array} patterns - Patterns to filter out
187
 * @param {Object} options - Optional configuration object
188
 * @returns {Array} Array of strings that don't match any patterns
189
 */
190
nanomatch.not(list, patterns, options);
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
const nanomatch = require('nanomatch');
197

198
// Basic negation filtering
199
const files = ['foo.js', 'bar.txt', 'baz.js', 'qux.md'];
200
console.log(nanomatch.not(files, '*.js'));
201
//=> ['bar.txt', 'qux.md']
202

203
// Multiple patterns
204
console.log(nanomatch.not(files, ['*.js', '*.md']));
205
//=> ['bar.txt']
206

207
// Complex patterns
208
const paths = ['src/app.js', 'lib/utils.js', 'test/spec.js', 'docs/readme.md'];
209
console.log(nanomatch.not(paths, '**/*.js'));
210
//=> ['docs/readme.md']
211

212
// With ignore option (double negation)
213
console.log(nanomatch.not(files, '*.js', { ignore: '*.txt' }));
214
//=> ['qux.md'] (excludes *.js, then ignores *.txt from remaining)
215

216
// Empty array for universal patterns
217
console.log(nanomatch.not(files, '**'));
218
//=> []
219

220
console.log(nanomatch.not(files, '*'));
221
//=> [] (all files match *)
222
```
223

224
## Logical Relationships
225

226
```javascript
227
const files = ['a.js', 'b.txt', 'c.js'];
228
const jsPattern = '*.js';
229

230
// These relationships hold:
231
console.log(nanomatch.some(files, jsPattern));   //=> true
232
console.log(nanomatch.every(files, jsPattern));  //=> false
233
console.log(nanomatch.not(files, jsPattern));    //=> ['b.txt']
234

235
// any() and all() work on single strings vs multiple patterns
236
const str = 'test.js';
237
const patterns = ['test*', '*.js'];
238

239
console.log(nanomatch.any(str, patterns));  //=> true (matches at least one)
240
console.log(nanomatch.all(str, patterns));  //=> true (matches all)
241
```
242

243
## Performance Considerations
244

245
- `some()` uses short-circuit evaluation - stops at first match
246
- `every()` stops at first non-match
247
- `any()` stops at first matching pattern
248
- `all()` must test every pattern
249
- All functions benefit from nanomatch's internal caching
250

251
## Error Handling
252

253
```javascript
254
// TypeError for invalid string inputs
255
try {
256
  nanomatch.any(123, '*.js');
257
} catch (error) {
258
  console.log(error.message);
259
  //=> 'expected a string: "123"'
260
}
261

262
try {
263
  nanomatch.all(null, '*.js');
264
} catch (error) {
265
  console.log(error.message);
266
  //=> 'expected a string: "null"'
267
}
268

269
// Empty string handling
270
console.log(nanomatch.some('', ''));     //=> false
271
console.log(nanomatch.any('', ''));      //=> false
272
console.log(nanomatch.all('', ''));      //=> false
273
```