0
# CustomConsole
1

2
CustomConsole is a console implementation that outputs to custom streams with optional formatting, providing formatted console output with custom styling and message processing capabilities.
3

4
## Capabilities
5

6
### CustomConsole Class
7

8
Console implementation that extends Node.js Console to output to custom streams with optional message formatting.
9

10
```typescript { .api }
11
/**
12
 * Function type for formatting console output messages
13
 * @param type - The type of log message
14
 * @param message - The message to format
15
 * @returns Formatted message string
16
 */
17
type Formatter = (type: LogType, message: LogMessage) => string;
18

19
/**
20
 * Console implementation that outputs to custom streams with optional formatting
21
 * Extends Node.js Console with custom stream and formatting capabilities
22
 */
23
class CustomConsole extends Console {
24
  /**
25
   * Creates a new CustomConsole instance
26
   * @param stdout - WriteStream for standard output
27
   * @param stderr - WriteStream for error output
28
   * @param formatBuffer - Optional formatter function for message processing
29
   */
30
  constructor(
31
    stdout: WriteStream,
32
    stderr: WriteStream,
33
    formatBuffer?: Formatter
34
  );
35
  
36
  /** Reference to the Node.js Console constructor */
37
  Console: typeof Console;
38
  
39
  /** Always returns undefined (no buffering in CustomConsole) */
40
  getBuffer(): undefined;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { CustomConsole } from "@jest/console";
48
import type { WriteStream } from "tty";
49

50
// Basic usage with process streams
51
const console = new CustomConsole(process.stdout, process.stderr);
52
console.log("This goes to stdout");
53
console.error("This goes to stderr");
54

55
// With custom formatter
56
const formattedConsole = new CustomConsole(
57
  process.stdout,
58
  process.stderr,
59
  (type, message) => `[${type.toUpperCase()}] ${new Date().toISOString()}: ${message}`
60
);
61

62
formattedConsole.log("Hello, World!");
63
// Output: [LOG] 2023-01-01T12:00:00.000Z: Hello, World!
64

65
// With custom streams
66
import { Writable } from "stream";
67

68
let output = "";
69
const customStream = new Writable({
70
  write(chunk, encoding, callback) {
71
    output += chunk.toString();
72
    callback();
73
  }
74
}) as WriteStream;
75

76
const streamConsole = new CustomConsole(customStream, customStream);
77
streamConsole.log("Captured output");
78
console.log(output); // "Captured output\n"
79
```
80

81
### Console Methods
82

83
All standard console methods are supported, with output directed to the appropriate streams.
84

85
#### Logging Methods
86

87
```typescript { .api }
88
/**
89
 * Log a message to stdout
90
 * @param firstArg - Primary message or data to log
91
 * @param args - Additional arguments to format and log
92
 */
93
log(firstArg: unknown, ...args: Array<unknown>): void;
94

95
/**
96
 * Log an informational message to stdout
97
 * @param firstArg - Primary message or data to log
98
 * @param args - Additional arguments to format and log
99
 */
100
info(firstArg: unknown, ...args: Array<unknown>): void;
101

102
/**
103
 * Log a debug message to stdout
104
 * @param firstArg - Primary message or data to log
105
 * @param args - Additional arguments to format and log
106
 */
107
debug(firstArg: unknown, ...args: Array<unknown>): void;
108

109
/**
110
 * Log a warning message to stderr
111
 * @param firstArg - Primary message or data to log
112
 * @param args - Additional arguments to format and log
113
 */
114
warn(firstArg: unknown, ...args: Array<unknown>): void;
115

116
/**
117
 * Log an error message to stderr
118
 * @param firstArg - Primary message or data to log
119
 * @param args - Additional arguments to format and log
120
 */
121
error(firstArg: unknown, ...args: Array<unknown>): void;
122
```
123

124
#### Assertion Method
125

126
```typescript { .api }
127
/**
128
 * Assert that a value is truthy, logging assertion failures to stderr
129
 * @param value - Value to test for truthiness
130
 * @param message - Optional message or Error object for assertion failure
131
 */
132
assert(value: unknown, message?: string | Error): asserts value;
133
```
134

135
#### Object Inspection Methods
136

137
```typescript { .api }
138
/**
139
 * Log an object inspection to stdout
140
 * @param firstArg - Object to inspect
141
 * @param options - Optional inspection options from Node.js util.inspect
142
 */
143
dir(firstArg: unknown, options?: InspectOptions): void;
144

145
/**
146
 * Log XML-style object representation to stdout
147
 * @param firstArg - Primary object to log
148
 * @param args - Additional arguments to format and log
149
 */
150
dirxml(firstArg: unknown, ...args: Array<unknown>): void;
151
```
152

153
#### Grouping Methods
154

155
```typescript { .api }
156
/**
157
 * Start a new console group with optional title, increasing indentation depth
158
 * @param title - Optional group title
159
 * @param args - Additional arguments to format in the title
160
 */
161
group(title?: string, ...args: Array<unknown>): void;
162

163
/**
164
 * Start a new collapsed console group with optional title
165
 * @param title - Optional group title
166
 * @param args - Additional arguments to format in the title
167
 */
168
groupCollapsed(title?: string, ...args: Array<unknown>): void;
169

170
/**
171
 * End the current console group, decreasing indentation depth
172
 */
173
groupEnd(): void;
174
```
175

176
#### Counting Methods
177

178
```typescript { .api }
179
/**
180
 * Increment and log a counter for the given label to stdout
181
 * @param label - Counter label, defaults to 'default'
182
 */
183
count(label?: string): void;
184

185
/**
186
 * Reset a counter for the given label to zero
187
 * @param label - Counter label to reset, defaults to 'default'
188
 */
189
countReset(label?: string): void;
190
```
191

192
#### Timing Methods
193

194
```typescript { .api }
195
/**
196
 * Start a timer with the given label
197
 * @param label - Timer label, defaults to 'default'
198
 */
199
time(label?: string): void;
200

201
/**
202
 * End a timer and log the elapsed time to stdout
203
 * @param label - Timer label to end, defaults to 'default'
204
 */
205
timeEnd(label?: string): void;
206

207
/**
208
 * Log the current elapsed time for a running timer to stdout
209
 * @param label - Timer label to check, defaults to 'default'
210
 * @param data - Additional data to log with the time
211
 */
212
timeLog(label?: string, ...data: Array<unknown>): void;
213
```