Skip to content

Commit c349a4c

Browse files
octogonzoctogonz
committed
New API design for a callback that routes ExtractorMessage objects
1 parent ac161c4 commit c349a4c

3 files changed

Lines changed: 60 additions & 5 deletions

File tree

‎apps/api-extractor/src/api/Extractor.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ import { PackageMetadataManager } from '../analyzer/PackageMetadataManager';
2222
import { ValidationEnhancer } from '../enhancers/ValidationEnhancer';
2323
import { DocCommentEnhancer } from '../enhancers/DocCommentEnhancer';
2424
import { CompilerState } from './CompilerState';
25+
import { ExtractorMessage } from './ExtractorMessage';
2526

2627
/**
2728
* Runtime options for Extractor.
@@ -57,6 +58,16 @@ export interface IExtractorInvokeOptions {
5758
* Use this option to specify the folder path for your compiler version.
5859
*/
5960
typescriptCompilerFolder?: string;
61+
62+
/**
63+
* An optional callback function that will be called for each `ExtractorMessage` before it is displayed by
64+
* API Extractor. The callback can customize the message, handle it, or discard it.
65+
*
66+
* @remarks
67+
* If a `messageCallback` is not provided, then by default API Extractor will print the messages to
68+
* the STDERR/STDOUT console.
69+
*/
70+
messageCallback?: (message: ExtractorMessage) => void;
6071
}
6172

6273
/**

‎apps/api-extractor/src/api/ExtractorMessage.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,35 @@ export class ExtractorMessage {
8787
*/
8888
public readonly messageId: tsdoc.TSDocMessageId | ExtractorMessageId | string;
8989

90+
/**
91+
* If the {@link IExtractorInvokeOptions.messageCallback} sets this property to true, it will prevent the message
92+
* from being displayed by API Extractor.
93+
*
94+
* @remarks
95+
* If the `messageCallback` routes the message to a custom handler (e.g. a toolchain logger), it should
96+
* assign `handled = true` to prevent API Extractor from displaying it. Assigning `handled = true` for all messages
97+
* would effectively disable all console output from the `Extractor` API.
98+
*
99+
* If `handled` is set to true, the message will still be included in the count of errors/warnings;
100+
* to discard a message entirely, instead assign `logLevel = none`.
101+
*/
102+
public handled: boolean;
103+
104+
/**
105+
* Specifies how the message should be reported.
106+
*
107+
* @remarks
108+
* If the {@link IExtractorInvokeOptions.messageCallback} handles the message (i.e. sets `handled = true`),
109+
* it can use the `logLevel` to determine how to display the message.
110+
*
111+
* Alternatively, if API Extractor is handling the message, the `messageCallback` could assign `logLevel` to change
112+
* how it will be processed. However, in general the recommended practice is to configure message routing
113+
* using the `messages` section in api-extractor.json.
114+
*
115+
* To discard a message entirely, assign `logLevel = none`.
116+
*/
117+
public logLevel: ExtractorMessageLogLevel;
118+
90119
/**
91120
* The text description of this issue.
92121
*/

‎apps/api-extractor/src/api/IConfigFile.ts‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -208,24 +208,39 @@ export interface IConfigTsdocMetadata {
208208
*/
209209
export const enum ExtractorMessageLogLevel {
210210
/**
211-
* The message will be written to the output log as an error.
211+
* The message will be displayed as an error.
212212
*
213213
* @remarks
214-
* Errors cause the build to fail and return a nonzero exit code.
214+
* Errors typically cause the build to fail and return a nonzero exit code.
215215
*/
216216
Error = 'error',
217217

218218
/**
219-
* The message will be written to the build output as an warning.
219+
* The message will be displayed as an warning.
220220
*
221221
* @remarks
222-
* Warnings cause a production build fail and return a nonzero exit code. For a non-production build
222+
* Warnings typically cause a production build fail and return a nonzero exit code. For a non-production build
223223
* (e.g. using the `--local` option with `api-extractor run`), the warning is displayed but the build will not fail.
224224
*/
225225
Warning = 'warning',
226226

227227
/**
228-
* The message will not be reported to the output log.
228+
* The message will be displayed as an informational message.
229+
*
230+
* @remarks
231+
* Informational messages may contain newlines to ensure nice formatting of the output,
232+
* however word-wrapping is the responsibility of the message handler.
233+
*/
234+
Info = 'info',
235+
236+
/**
237+
* The message will be displayed only when "verbose" output is requested, e.g. using the `--verbose`
238+
* command line option.
239+
*/
240+
Verbose = 'verbose',
241+
242+
/**
243+
* The message will be discarded entirely.
229244
*/
230245
None = 'none'
231246
}

0 commit comments

Comments
 (0)