0
# multimatch
1

2
multimatch extends minimatch.match() with support for multiple patterns, enabling pattern matching against multiple glob patterns simultaneously. It processes arrays of file paths and patterns, supporting both positive matches (inclusion) and negative matches (exclusion with '!' prefix), making it ideal for file filtering operations in build tools, CLI utilities, and file processing applications.
3

4
## Package Information
5

6
- **Package Name**: multimatch
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install multimatch`
10

11
## Core Imports
12

13
```javascript
14
import multimatch from 'multimatch';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const multimatch = require('multimatch');
21
```
22

23
TypeScript with type imports:
24

25
```typescript
26
import multimatch, { type Options } from 'multimatch';
27
```
28

29
## Basic Usage
30

31
```javascript
32
import multimatch from 'multimatch';
33

34
// Basic pattern matching
35
multimatch(['unicorn', 'cake', 'rainbows'], '*');
36
//=> ['unicorn', 'cake', 'rainbows']
37

38
// Multiple patterns with negation
39
multimatch(['unicorn', 'cake', 'rainbows'], ['*', '!cake']);
40
//=> ['unicorn', 'rainbows']
41

42
// Single pattern as string
43
multimatch(['foo', 'bar', 'baz'], 'f*');
44
//=> ['foo']
45

46
// File path matching
47
multimatch(['vendor/js/foo.js', 'vendor/js/bar.js'], '**/*.js');
48
//=> ['vendor/js/foo.js', 'vendor/js/bar.js']
49
```
50

51
## Capabilities
52

53
### Pattern Matching
54

55
The main function that matches paths against multiple glob patterns with support for inclusion and exclusion patterns.
56

57
```javascript { .api }
58
/**
59
 * Extends minimatch.match() with support for multiple patterns
60
 * @param paths - The paths to match against (string or array of strings)
61
 * @param patterns - Globbing patterns to use (string or array of strings)
62
 * @param options - Optional minimatch options
63
 * @returns Array of matching paths in the order of input paths
64
 */
65
function multimatch(
66
  paths: string | readonly string[],
67
  patterns: string | readonly string[],
68
  options?: Options
69
): string[];
70
```
71

72
**Pattern Behavior:**
73
- **Positive patterns** (e.g., `*`, `foo`) add matches to results
74
- **Negative patterns** (e.g., `!foo`) subtract matches from results
75
- **Pattern order matters** - patterns are applied sequentially
76
- **Lone negations** (e.g., `['!foo']`) never match anything - use `['*', '!foo']` instead
77

78
**Usage Examples:**
79

80
```javascript
81
// Multiple positive patterns
82
multimatch(['foo', 'bar', 'baz'], ['foo', 'bar']);
83
//=> ['foo', 'bar']
84

85
// Combining positive and negative patterns
86
multimatch(['foo', 'bar', 'baz'], ['*', '!bar']);
87
//=> ['foo', 'baz']
88

89
// Pattern order affects results
90
multimatch(['foo', 'bar', 'baz'], ['!*a*', '*r', 'f*']);
91
//=> ['foo', 'bar']
92

93
// Complex glob patterns
94
multimatch(['vendor/js/foo.js', 'vendor/css/bar.css'], ['**/*.js', '!**/foo.*']);
95
//=> []
96
```
97

98
**Edge Cases:**
99
- Empty inputs return empty array: `multimatch([], ['*'])` → `[]`
100
- No patterns return empty array: `multimatch(['foo'], [])` → `[]`
101
- Results maintain original input order
102
- Accepts both string and array inputs for paths and patterns
103

104
## Types
105

106
```typescript { .api }
107
import { type MinimatchOptions } from 'minimatch';
108

109
/**
110
 * Configuration options extending minimatch options
111
 */
112
type Options = Readonly<MinimatchOptions>;
113
```
114

115
The `Options` type extends all minimatch options including:
116
- `dot` - Allow patterns to match filenames starting with a period
117
- `noglobstar` - Disable ** globstar matching
118
- `nocase` - Perform case-insensitive matching
119
- `debug` - Enable debug output
120
- And all other [minimatch options](https://github.com/isaacs/minimatch#options)
121

122
## Pattern Syntax
123

124
multimatch supports all minimatch glob patterns:
125

126
- `*` - Matches any number of characters, but not `/`
127
- `?` - Matches a single character, but not `/`
128
- `**` - Matches any number of characters, including `/`, as long as it's the only thing in a path part
129
- `{}` - Allows for a comma-separated list of "or" expressions
130
- `!` - At the beginning of a pattern negates the match
131
- `[...]` - Character class matching
132
- `+(pattern)` - One or more occurrences
133
- `*(pattern)` - Zero or more occurrences
134
- `?(pattern)` - Zero or one occurrence
135
- `@(pattern)` - Exactly one occurrence