0
# Utility Functions
1

2
Specialized utility functions for specific matching scenarios including negation filtering, object key matching, and advanced collection operations.
3

4
## Capabilities
5

6
### Negation Filtering
7

8
Returns strings that do NOT match any of the given patterns - the inverse of the main micromatch function.
9

10
```javascript { .api }
11
/**
12
 * Returns a list of strings that do not match any of the given patterns
13
 * @param {string[]} list - Array of strings to match
14
 * @param {string|string[]} patterns - One or more glob pattern to use for matching
15
 * @param {object} options - See available options for changing how matches are performed
16
 * @returns {string[]} Returns an array of strings that do not match the given patterns
17
 */
18
function not(list, patterns, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const { not } = require('micromatch');
25

26
// Basic negation filtering
27
console.log(not(['a.a', 'b.b', 'c.c'], '*.a'));
28
//=> ['b.b', 'c.c']
29

30
// Multiple patterns
31
const files = ['app.js', 'test.js', 'readme.md', 'config.json'];
32
console.log(not(files, ['*.js', '*.md']));
33
//=> ['config.json']
34

35
// With complex patterns
36
console.log(not(['foo.js', 'bar.txt', 'baz.js'], '**/*.js'));
37
//=> ['bar.txt']
38
```
39

40
### Object Key Filtering
41

42
Filters the keys of an object using glob patterns, returning a new object with only matching keys.
43

44
```javascript { .api }
45
/**
46
 * Filter the keys of the given object with the given glob pattern and options
47
 * @param {object} object - The object with keys to filter
48
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
49
 * @param {object} options - See available options for changing how matches are performed  
50
 * @returns {object} Returns an object with only keys that match the given patterns
51
 */
52
function matchKeys(object, patterns, options);
53
```
54

55
**Usage Examples:**
56

57
```javascript
58
const { matchKeys } = require('micromatch');
59

60
// Basic key matching
61
const obj = { aa: 'a', ab: 'b', ac: 'c', ba: 'd' };
62
console.log(matchKeys(obj, '*b'));
63
//=> { ab: 'b' }
64

65
// Multiple patterns
66
console.log(matchKeys(obj, ['a*', 'ba']));
67
//=> { aa: 'a', ab: 'b', ac: 'c', ba: 'd' }
68

69
// API endpoint filtering example
70
const routes = {
71
  'GET /users': 'getUsers',
72
  'POST /users': 'createUser', 
73
  'GET /posts': 'getPosts',
74
  'DELETE /users': 'deleteUser'
75
};
76
console.log(matchKeys(routes, 'GET *'));
77
//=> { 'GET /users': 'getUsers', 'GET /posts': 'getPosts' }
78
```
79

80
## Advanced Collection Operations
81

82
These utilities build on the core matching functionality to provide specialized collection handling:
83

84
### Negation Logic
85

86
The `not()` function implements inverse matching logic:
87

88
1. Runs the main micromatch function to find all matches
89
2. Returns all items from the original list that were NOT in the matches
90
3. Preserves original order of non-matching items
91
4. Supports all the same options as the main micromatch function
92

93
### Object Key Processing
94

95
The `matchKeys()` function applies glob matching to object keys:
96

97
1. Extracts all keys from the input object using `Object.keys()`
98
2. Filters keys using the main micromatch function
99
3. Constructs a new object with only the matching keys and their values
100
4. Throws `TypeError` if the first argument is not an object
101

102
## Error Handling
103

104
### Not Function
105

106
- Handles empty input lists gracefully (returns empty array)
107
- Processes all the same pattern types as main micromatch function
108
- Supports negation patterns within the patterns parameter
109
- Preserves array order of non-matching items
110

111
### MatchKeys Function
112

113
- Throws `TypeError` if first argument is not an object
114
- Handles objects with no enumerable keys (returns empty object)
115
- Processes all key types that can be converted to strings
116
- Returns new object instance (does not modify original)
117

118
## Use Cases
119

120
### File System Operations
121

122
```javascript
123
const files = ['src/app.js', 'src/app.test.js', 'dist/app.js', 'README.md'];
124

125
// Get non-source files
126
const nonSource = not(files, 'src/**');
127
//=> ['dist/app.js', 'README.md']
128

129
// Get non-test files  
130
const nonTest = not(files, '**/*.test.*');
131
//=> ['src/app.js', 'dist/app.js', 'README.md']
132
```
133

134
### Configuration Management
135

136
```javascript
137
const config = {
138
  'app.port': 3000,
139
  'app.host': 'localhost', 
140
  'db.host': 'localhost',
141
  'db.port': 5432,
142
  'cache.enabled': true
143
};
144

145
// Get all app settings
146
const appConfig = matchKeys(config, 'app.*');
147
//=> { 'app.port': 3000, 'app.host': 'localhost' }
148

149
// Get all port settings
150
const portConfig = matchKeys(config, '*.port');
151
//=> { 'app.port': 3000, 'db.port': 5432 }
152
```
153

154
### API Route Processing
155

156
```javascript  
157
const routes = {
158
  'GET /api/users': 'listUsers',
159
  'POST /api/users': 'createUser',
160
  'GET /api/posts': 'listPosts', 
161
  'DELETE /api/users/:id': 'deleteUser'
162
};
163

164
// Get all GET routes
165
const getRoutes = matchKeys(routes, 'GET *');
166

167
// Exclude DELETE routes
168
const safeRoutes = matchKeys(routes, ['*', '!DELETE *']);
169
```