0
# File Writing
1

2
File writing infrastructure in Istanbul Lib Report provides comprehensive file and console output management with support for directory-based organization, content writing abstractions, and output capturing for testing.
3

4
## Capabilities
5

6
### FileWriter Class
7

8
The main file writing utility that manages output directories and creates content writers for files or console output.
9

10
```javascript { .api }
11
/**
12
 * Utility for writing files under a specific directory
13
 */
14
class FileWriter {
15
  /**
16
   * Create a new FileWriter instance
17
   * @param {string} baseDir - The base directory under which files should be written
18
   * @throws {Error} If baseDir is not specified
19
   */
20
  constructor(baseDir);
21

22
  /**
23
   * Returns a FileWriter that is rooted at the supplied subdirectory
24
   * @param {string} subdir - The subdirectory under which to root the returned FileWriter
25
   * @returns {FileWriter} New FileWriter instance for the subdirectory
26
   * @throws {Error} If subdir is an absolute path
27
   */
28
  writerForDir(subdir);
29

30
  /**
31
   * Copies a file from a source directory to a destination name
32
   * @param {string} source - Path to source file
33
   * @param {string} dest - Relative path to destination file
34
   * @param {string} [header] - Optional text to prepend to destination
35
   * @throws {Error} If dest is an absolute path
36
   */
37
  copyFile(source, dest, header);
38

39
  /**
40
   * Returns a content writer for writing content to the supplied file
41
   * @param {string|null} file - Relative path to file, or "-"/null for console
42
   * @returns {ContentWriter} Content writer instance
43
   * @throws {Error} If file is an absolute path
44
   */
45
  writeFile(file);
46
}
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
const { FileWriter } = require('istanbul-lib-report/lib/file-writer');
53

54
// Create file writer for reports directory
55
const writer = new FileWriter('coverage-reports');
56

57
// Create content writer for a file
58
const fileWriter = writer.writeFile('summary.txt');
59
fileWriter.println('Coverage Summary');
60
fileWriter.close();
61

62
// Write to console
63
const consoleWriter = writer.writeFile(null); // or "-"
64
consoleWriter.println('Writing to console');
65

66
// Create subdirectory writer
67
const htmlWriter = writer.writerForDir('html');
68
const indexWriter = htmlWriter.writeFile('index.html');
69

70
// Copy file with header
71
writer.copyFile('/templates/style.css', 'css/style.css', '/* Auto-generated */\\n');
72
```
73

74
### Static Capture Methods
75

76
Static methods for capturing stdout output, particularly useful for testing report generation.
77

78
```javascript { .api }
79
/**
80
 * Start capturing stdout report output (useful for tests)
81
 */
82
static startCapture();
83

84
/**
85
 * Stop capturing stdout report output
86
 */
87
static stopCapture();
88

89
/**
90
 * Get captured stdout output
91
 * @returns {string} Captured output
92
 */
93
static getOutput();
94

95
/**
96
 * Reset captured output buffer
97
 */
98
static resetOutput();
99
```
100

101
**Usage Examples:**
102

103
```javascript
104
const { FileWriter } = require('istanbul-lib-report/lib/file-writer');
105

106
// Basic capture for testing
107
FileWriter.startCapture();
108

109
const writer = new FileWriter('test-dir');
110
const consoleWriter = writer.writeFile(null);
111
consoleWriter.println('Test output');
112

113
const captured = FileWriter.getOutput(); // "Test output\\n"
114
FileWriter.stopCapture();
115
FileWriter.resetOutput();
116

117
// Advanced: Capture during report generation for testing
118
function testReportGeneration() {
119
  FileWriter.startCapture();
120
  
121
  try {
122
    // Generate report that writes to console
123
    const context = libReport.createContext({ 
124
      dir: 'coverage',
125
      coverageMap 
126
    });
127
    
128
    // Your report generation code here
129
    const consoleWriter = context.getWriter().writeFile(null);
130
    consoleWriter.println('Coverage Summary:');
131
    consoleWriter.println('Lines: 85%');
132
    
133
    // Verify output in tests
134
    const output = FileWriter.getOutput();
135
    console.assert(output.includes('Coverage Summary:'));
136
    console.assert(output.includes('Lines: 85%'));
137
    
138
    return output;
139
  } finally {
140
    FileWriter.stopCapture();
141
    FileWriter.resetOutput();
142
  }
143
}
144

145
// Integration testing pattern
146
function captureReportOutput(reportGenerator) {
147
  FileWriter.startCapture();
148
  
149
  try {
150
    reportGenerator();
151
    return FileWriter.getOutput();
152
  } finally {
153
    FileWriter.stopCapture();
154
    FileWriter.resetOutput();
155
  }
156
}
157
```
158

159
### ContentWriter Base Class
160

161
Abstract base class for writing content with colorization support.
162

163
```javascript { .api }
164
/**
165
 * Base class for writing content
166
 */
167
class ContentWriter {
168
  /**
169
   * Returns the colorized version of a string
170
   * @param {string} str - The string to colorize
171
   * @param {string} clazz - One of "high", "medium", or "low"
172
   * @returns {string} The colorized form of the string
173
   */
174
  colorize(str, clazz);
175

176
  /**
177
   * Writes a string appended with a newline to the destination
178
   * @param {string} str - The string to write
179
   */
180
  println(str);
181

182
  /**
183
   * Writes a string to the destination (abstract method)
184
   * @param {string} str - The string to write
185
   */
186
  write(str);
187

188
  /**
189
   * Closes this content writer
190
   */
191
  close();
192
}
193
```
194

195
### FileContentWriter Class
196

197
Content writer implementation for file output.
198

199
```javascript { .api }
200
/**
201
 * A content writer that writes to a file
202
 */
203
class FileContentWriter extends ContentWriter {
204
  /**
205
   * Create a file content writer
206
   * @param {number} fd - The file descriptor
207
   */
208
  constructor(fd);
209

210
  /**
211
   * Write string to file
212
   * @param {string} str - String to write
213
   */
214
  write(str);
215

216
  /**
217
   * Close the file descriptor
218
   */
219
  close();
220
}
221
```
222

223
### ConsoleWriter Class
224

225
Content writer implementation for console output with color support.
226

227
```javascript { .api }
228
/**
229
 * A content writer that writes to the console
230
 */
231
class ConsoleWriter extends ContentWriter {
232
  /**
233
   * Write string to console
234
   * @param {string} str - String to write
235
   */
236
  write(str);
237

238
  /**
239
   * Colorize string for console output
240
   * @param {string} str - String to colorize
241
   * @param {string} clazz - Color class: "high" (green), "medium" (yellow), "low" (red)
242
   * @returns {string} Colorized string with ANSI escape codes if supported
243
   */
244
  colorize(str, clazz);
245
}
246
```
247

248
**Usage Examples:**
249

250
```javascript
251
// Using content writers directly
252
const contentWriter = writer.writeFile('report.txt');
253

254
// Basic writing
255
contentWriter.write('Coverage: ');
256
contentWriter.println('85%');
257

258
// Colorized output (useful for console)
259
const consoleWriter = writer.writeFile(null);
260
const colorized = consoleWriter.colorize('85%', 'high'); // Green if terminal supports color
261
consoleWriter.println(`Coverage: ${colorized}`);
262

263
// Always close when done
264
contentWriter.close();
265
```
266

267
## Types
268

269
```javascript { .api }
270
type ColorClass = 'high' | 'medium' | 'low';
271

272
interface ContentWriter {
273
  write(str: string): void;
274
  println(str: string): void;
275
  colorize(str: string, clazz: ColorClass): string;
276
  close(): void;
277
}
278

279
interface FileWriter {
280
  baseDir: string;
281
  writerForDir(subdir: string): FileWriter;
282
  copyFile(source: string, dest: string, header?: string): void;
283
  writeFile(file: string | null): ContentWriter;
284
}
285
```