0
# Filename Plugin
1

2
The filename plugin provides interactive filename-based test filtering with typeahead functionality. Users can type partial filenames to filter which test files run during Jest watch mode.
3

4
## Capabilities
5

6
### FileNamePlugin Class
7

8
Main plugin class implementing Jest's WatchPlugin interface for filename-based filtering.
9

10
```typescript { .api }
11
/**
12
 * Jest watch plugin for filtering test files by filename patterns
13
 */
14
export default class FileNamePlugin implements WatchPlugin {
15
  constructor(options: {
16
    stdin: NodeJS.ReadStream;
17
    stdout: NodeJS.WriteStream;
18
    config?: PluginConfig;
19
  });
20
  
21
  /** Hook into Jest lifecycle events to receive project updates */
22
  apply(jestHooks: JestHookSubscriber): void;
23
  
24
  /** Handle keypress events from user input */
25
  onKey(key: string): void;
26
  
27
  /** Execute plugin functionality and update Jest configuration */
28
  run(
29
    globalConfig: Config.GlobalConfig,
30
    updateConfigAndRun: UpdateConfigCallback
31
  ): Promise<void>;
32
  
33
  /** Return plugin usage information for Jest's help display */
34
  getUsageInfo(): UsageData;
35
}
36
```
37

38
**Usage Example:**
39

40
```typescript
41
import FileNamePlugin from "jest-watch-typeahead/filename";
42

43
// Plugin is typically instantiated by Jest
44
const plugin = new FileNamePlugin({
45
  stdin: process.stdin,
46
  stdout: process.stdout,
47
  config: {
48
    key: 'f',
49
    prompt: 'filter by filename'
50
  }
51
});
52
```
53

54
### FileNamePatternPrompt Class
55

56
Interactive prompt class for filename pattern input and typeahead display.
57

58
```typescript { .api }
59
/**
60
 * Pattern prompt for filename-based filtering with typeahead functionality
61
 */
62
export default class FileNamePatternPrompt extends PatternPrompt {
63
  constructor(pipe: NodeJS.WriteStream, prompt: Prompt);
64
  
65
  /** Update available search sources (project configurations and test paths) */
66
  updateSearchSources(sources: SearchSources): void;
67
  
68
  /** Handle pattern changes and update display */
69
  protected _onChange(pattern: string, options: ScrollOptions): void;
70
  
71
  /** Display typeahead results for current pattern */
72
  protected _printTypeahead(pattern: string, options: ScrollOptions): void;
73
  
74
  /** Get test files matching the current pattern */
75
  protected _getMatchedTests(pattern: string): Array<any>;
76
}
77
```
78

79
### Pattern Matching System
80

81
The filename plugin uses regex-based pattern matching to filter test files:
82

83
- **Case-insensitive matching**: Patterns match filenames regardless of case
84
- **Partial matching**: Type partial filenames to see matching files
85
- **Real-time filtering**: Results update as you type
86
- **Highlighting**: Matching portions of filenames are highlighted in terminal output
87

88
**Pattern Examples:**
89

90
```bash
91
# Match all files containing "user"
92
user
93

94
# Match files ending with ".test.js"
95
\.test\.js$
96

97
# Match files in specific directory
98
components/.*\.test
99

100
# Match multiple patterns with OR
101
(user|auth).*test
102
```
103

104
## Integration with Jest
105

106
### Plugin Registration
107

108
```javascript
109
// jest.config.js
110
module.exports = {
111
  watchPlugins: [
112
    'jest-watch-typeahead/filename'
113
  ]
114
};
115
```
116

117
### Runtime Behavior
118

119
1. **Activation**: Press the configured key (default: 'p') in Jest watch mode
120
2. **Pattern Input**: Type partial filename patterns to filter files
121
3. **Visual Feedback**: See matching files highlighted in real-time
122
4. **Selection**: Press Enter to apply filter and run matching tests
123
5. **Exit**: Press Escape to cancel and return to main watch menu
124

125
### Hook Integration
126

127
The plugin integrates with Jest's hook system:
128

129
```typescript { .api }
130
interface JestHookSubscriber {
131
  /** Called when file changes are detected */
132
  onFileChange(callback: (data: { projects: SearchSources }) => void): void;
133
}
134
```
135

136
The filename plugin subscribes to `onFileChange` to update available test files when the project structure changes.
137

138
## Utility Functions
139

140
### Path Formatting
141

142
```typescript { .api }
143
/**
144
 * Format and trim file paths for terminal display
145
 * @param pad - Padding amount for alignment
146
 * @param config - Jest project configuration
147
 * @param testPath - Test file path to format
148
 * @param columns - Terminal column width
149
 * @returns Formatted path string with highlighting
150
 */
151
function trimAndFormatPath(
152
  pad: number,
153
  config: Config.ProjectConfig,
154
  testPath: string,
155
  columns: number
156
): string;
157
```
158

159
### Pattern Highlighting
160

161
```typescript { .api }
162
/**
163
 * Highlight matching portions of file paths
164
 * @param rawPath - Raw file path string
165
 * @param filePath - Processed file path for display
166
 * @param pattern - Search pattern to highlight
167
 * @returns Path string with ANSI highlighting
168
 */
169
function highlight(
170
  rawPath: string,
171
  filePath: string,
172
  pattern: string
173
): string;
174
```
175

176
### Terminal Width Detection
177

178
```typescript { .api }
179
/**
180
 * Get current terminal width for display formatting
181
 * @param pipe - Output stream (defaults to process.stdout)
182
 * @returns Terminal width in columns
183
 */
184
function getTerminalWidth(pipe?: NodeJS.WriteStream): number;
185
```
186

187
### Display Item Helpers
188

189
```typescript { .api }
190
/**
191
 * Print individual typeahead item to terminal
192
 * @param item - Item text to display
193
 * @param pipe - Output stream for writing
194
 */
195
function printTypeaheadItem(
196
  item: string,
197
  pipe: NodeJS.WritableStream
198
): void;
199
```
200

201
### Typeahead Selection Formatting
202

203
```typescript { .api }
204
/**
205
 * Format typeahead selection items with highlighting for active selection
206
 * @param item - Item text to format
207
 * @param index - Current item index
208
 * @param activeIndex - Index of currently active selection
209
 * @param prompt - Jest prompt instance for selection tracking
210
 * @returns Formatted item string with selection highlighting
211
 */
212
function formatTypeaheadSelection(
213
  item: string,
214
  index: number,
215
  activeIndex: number,
216
  prompt: Prompt
217
): string;
218
```
219

220
## Types
221

222
```typescript { .api }
223
type SearchSources = Array<{
224
  config: Config.ProjectConfig;
225
  testPaths: Array<string>;
226
}>;
227

228
interface UsageData {
229
  key: string;
230
  prompt: string;
231
}
232

233
interface UpdateConfigCallback {
234
  (config: {
235
    mode: 'watch';
236
    testPathPatterns: Array<string>;
237
  }): void;
238
}
239
```