@microsoft/api-extractor

  • Version 7.18.4
  • Published
  • 1.71 MB
  • 12 dependencies
  • MIT license

Install

npm i @microsoft/api-extractor
yarn add @microsoft/api-extractor
pnpm add @microsoft/api-extractor

Overview

API Extractor helps with validation, documentation, and reviewing of the exported API for a TypeScript library. The @microsoft/api-extractor package provides the command-line tool. It also exposes a developer API that you can use to invoke API Extractor programmatically.

Index

Classes

Interfaces

Enums

Classes

class CompilerState

class CompilerState {}
  • This class represents the TypeScript compiler state. This allows an optimization where multiple invocations of API Extractor can reuse the same TypeScript compiler analysis.

    Modifiers

    • @public

property program

readonly program: {};
  • The TypeScript compiler's Program object, which represents a complete scope of analysis.

method create

static create: (
extractorConfig: ExtractorConfig,
options?: ICompilerStateCreateOptions
) => CompilerState;
  • Create a compiler state for use with the specified IExtractorInvokeOptions.

class Extractor

class Extractor {}
  • The starting point for invoking the API Extractor tool.

    Modifiers

    • @public

property packageName

static readonly packageName: string;
  • Returns the package name of the API Extractor NPM package.

property version

static readonly version: string;
  • Returns the version number of the API Extractor NPM package.

method invoke

static invoke: (
extractorConfig: ExtractorConfig,
options?: IExtractorInvokeOptions
) => ExtractorResult;
  • Invoke API Extractor using an already prepared ExtractorConfig object.

method loadConfigAndInvoke

static loadConfigAndInvoke: (
configFilePath: string,
options?: IExtractorInvokeOptions
) => ExtractorResult;
  • Load the api-extractor.json config file from the specified path, and then invoke API Extractor.

class ExtractorConfig

class ExtractorConfig {}
  • The ExtractorConfig class loads, validates, interprets, and represents the api-extractor.json config file.

    Modifiers

    • @public

property apiJsonFilePath

readonly apiJsonFilePath: string;

property apiReportEnabled

readonly apiReportEnabled: boolean;

property betaTrimmedFilePath

readonly betaTrimmedFilePath: string;

property bundledPackages

readonly bundledPackages: string[];

property docModelEnabled

readonly docModelEnabled: boolean;

property FILENAME

static readonly FILENAME: string;
  • The config file name "api-extractor.json".

property jsonSchema

static readonly jsonSchema: any;
  • The JSON Schema for API Extractor config file (api-extractor.schema.json).

property mainEntryPointFilePath

readonly mainEntryPointFilePath: string;

property messages

readonly messages: IExtractorMessagesConfig;

property newlineKind

readonly newlineKind: any;
  • Specifies what type of newlines API Extractor should use when writing output files. By default, the output files will be written with Windows-style newlines.

property omitTrimmingComments

readonly omitTrimmingComments: boolean;

property overrideTsconfig

readonly overrideTsconfig: {};

property packageFolder

readonly packageFolder: string;
  • The absolute path of the folder containing the package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

property packageJson

readonly packageJson: any;
  • The parsed package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

property projectFolder

readonly projectFolder: string;

property publicTrimmedFilePath

readonly publicTrimmedFilePath: string;

property reportFilePath

readonly reportFilePath: string;
  • The reportFolder path combined with the reportFileName.

property reportTempFilePath

readonly reportTempFilePath: string;
  • The reportTempFolder path combined with the reportFileName.

property rollupEnabled

readonly rollupEnabled: boolean;

property skipLibCheck

readonly skipLibCheck: boolean;

property testMode

readonly testMode: boolean;

property tsconfigFilePath

readonly tsconfigFilePath: string;

property tsdocConfigFile

readonly tsdocConfigFile: any;
  • The tsdoc.json configuration that will be used when parsing doc comments.

property tsdocConfiguration

readonly tsdocConfiguration: any;

property tsdocMetadataEnabled

readonly tsdocMetadataEnabled: boolean;

property tsdocMetadataFilePath

readonly tsdocMetadataFilePath: string;

property untrimmedFilePath

readonly untrimmedFilePath: string;

method getDiagnosticDump

getDiagnosticDump: () => string;
  • Returns a JSON-like string representing the ExtractorConfig state, which can be printed to a console for diagnostic purposes.

    Remarks

    This is used by the "--diagnostics" command-line option. The string is not intended to be deserialized; its format may be changed at any time.

method hasDtsFileExtension

static hasDtsFileExtension: (filePath: string) => boolean;
  • Returns true if the specified file path has the ".d.ts" file extension.

method loadFile

static loadFile: (jsonFilePath: string) => IConfigFile;
  • Performs only the first half of ExtractorConfig.loadFileAndPrepare, providing an opportunity to modify the object before it is passed to ExtractorConfig.prepare.

    Remarks

    Loads the api-extractor.json config file from the specified file path. If the "extends" field is present, the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.

method loadFileAndPrepare

static loadFileAndPrepare: (configJsonFilePath: string) => ExtractorConfig;
  • Loads the api-extractor.json config file from the specified file path, and prepares an ExtractorConfig object.

    Remarks

    Loads the api-extractor.json config file from the specified file path. If the "extends" field is present, the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.

    The result is prepared using ExtractorConfig.prepare().

method prepare

static prepare: (options: IExtractorConfigPrepareOptions) => ExtractorConfig;
  • Prepares an ExtractorConfig object using a configuration that is provided as a runtime object, rather than reading it from disk. This allows configurations to be constructed programmatically, loaded from an alternate source, and/or customized after loading.

method tryLoadForFolder

static tryLoadForFolder: (
options: IExtractorConfigLoadForFolderOptions
) => IExtractorConfigPrepareOptions | undefined;
  • Searches for the api-extractor.json config file associated with the specified starting folder, and loads the file if found. This lookup supports rig packages.

    Returns

    An options object that can be passed to ExtractorConfig.prepare, or undefined if not api-extractor.json file was found.

    Remarks

    The search will first look for a package.json file in a parent folder of the starting folder; if found, that will be used as the base folder instead of the starting folder. If the config file is not found in <baseFolder>/api-extractor.json or <baseFolder>/config/api-extractor.json, then <baseFolder/config/rig.json will be checked to see whether a rig package is referenced; if so then the rig's api-extractor.json file will be used instead. If a config file is found, it will be loaded and returned with the IExtractorConfigPrepareOptions object. Otherwise, undefined is returned to indicate that API Extractor does not appear to be configured for the specified folder.

class ExtractorMessage

class ExtractorMessage {}
  • This object is used to report an error or warning that occurred during API Extractor's analysis.

    Modifiers

    • @public

property category

readonly category: ExtractorMessageCategory;
  • The category of issue.

property handled

handled: boolean;
  • If the IExtractorInvokeOptions.messageCallback sets this property to true, it will prevent the message from being displayed by API Extractor.

    Remarks

    If the messageCallback routes the message to a custom handler (e.g. a toolchain logger), it should assign handled = true to prevent API Extractor from displaying it. Assigning handled = true for all messages would effectively disable all console output from the Extractor API.

    If handled is set to true, the message will still be included in the count of errors/warnings; to discard a message entirely, instead assign logLevel = none.

property logLevel

logLevel: ExtractorLogLevel;
  • Specifies how the message should be reported.

    Remarks

    If the IExtractorInvokeOptions.messageCallback handles the message (i.e. sets handled = true), it can use the logLevel to determine how to display the message.

    Alternatively, if API Extractor is handling the message, the messageCallback could assign logLevel to change how it will be processed. However, in general the recommended practice is to configure message routing using the messages section in api-extractor.json.

    To discard a message entirely, assign logLevel = none.

property messageId

readonly messageId: any;
  • A text string that uniquely identifies the issue type. This identifier can be used to suppress or configure the reporting of issues, and also to search for help about an issue.

property properties

readonly properties: IExtractorMessageProperties;
  • Additional contextual information about the message that may be useful when reporting errors. All properties are optional.

property sourceFileColumn

readonly sourceFileColumn: number;
  • The column number where the issue occurred in the input source file. This is not used if sourceFilePath is undefined. The first column number is 1.

property sourceFileLine

readonly sourceFileLine: number;
  • The line number where the issue occurred in the input source file. This is not used if sourceFilePath is undefined. The first line number is 1.

property sourceFilePath

readonly sourceFilePath: string;
  • The absolute path to the affected input source file, if there is one.

property text

readonly text: string;
  • The text description of this issue.

method formatMessageWithLocation

formatMessageWithLocation: (
workingPackageFolderPath: string | undefined
) => string;
  • Returns the message formatted with its identifier and file position.

    Remarks

    Example:

    src/folder/File.ts:123:4 - (ae-extra-release-tag) The doc comment should not contain more than one release tag.

method formatMessageWithoutLocation

formatMessageWithoutLocation: () => string;

    class ExtractorResult

    class ExtractorResult {}
    • This object represents the outcome of an invocation of API Extractor.

      Modifiers

      • @public

    property apiReportChanged

    readonly apiReportChanged: boolean;
    • Returns true if the API report was found to have changed.

    property compilerState

    readonly compilerState: CompilerState;
    • The TypeScript compiler state that was used.

    property errorCount

    readonly errorCount: number;
    • Reports the number of errors encountered during analysis.

      Remarks

      This does not count exceptions, where unexpected issues prematurely abort the operation.

    property extractorConfig

    readonly extractorConfig: ExtractorConfig;
    • The API Extractor configuration that was used.

    property succeeded

    readonly succeeded: boolean;
    • Whether the invocation of API Extractor was successful. For example, if succeeded is false, then the build task would normally return a nonzero process exit code, indicating that the operation failed.

      Remarks

      Normally the operation "succeeds" if errorCount and warningCount are both zero. However if IExtractorInvokeOptions.localBuild is true, then the operation "succeeds" if errorCount is zero (i.e. warnings are ignored).

    property warningCount

    readonly warningCount: number;
    • Reports the number of warnings encountered during analysis.

      Remarks

      This does not count warnings that are emitted in the API report file.

    Interfaces

    interface ICompilerStateCreateOptions

    interface ICompilerStateCreateOptions {}

    property additionalEntryPoints

    additionalEntryPoints?: string[];
    • Additional .d.ts files to include in the analysis.

    property typescriptCompilerFolder

    typescriptCompilerFolder?: string;

    interface IConfigApiReport

    interface IConfigApiReport {}
    • Configures how the API report files (*.api.md) will be generated.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property enabled

    enabled: boolean;
    • Whether to generate an API report.

    property reportFileName

    reportFileName?: string;
    • The filename for the API report files. It will be combined with reportFolder or reportTempFolder to produce a full output filename.

      Remarks

      The file extension should be ".api.md", and the string should not contain a path separator such as \ or /.

    property reportFolder

    reportFolder?: string;
    • Specifies the folder where the API report file is written. The file name portion is determined by the reportFileName setting.

      Remarks

      The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy, e.g. for an API review.

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    property reportTempFolder

    reportTempFolder?: string;
    • Specifies the folder where the temporary report file is written. The file name portion is determined by the reportFileName setting.

      Remarks

      After the temporary file is written to disk, it is compared with the file in the reportFolder. If they are different, a production build will fail.

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    interface IConfigCompiler

    interface IConfigCompiler {}
    • Determines how the TypeScript compiler engine will be invoked by API Extractor.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property overrideTsconfig

    overrideTsconfig?: {};
    • Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.

      Remarks

      The value must conform to the TypeScript tsconfig schema:

      http://json.schemastore.org/tsconfig

      If omitted, then the tsconfig.json file will instead be read from the projectFolder.

    property skipLibCheck

    skipLibCheck?: boolean;
    • This option causes the compiler to be invoked with the --skipLibCheck option.

      Remarks

      This option is not recommended and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.

    property tsconfigFilePath

    tsconfigFilePath?: string;
    • Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.

      Remarks

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

      Note: This setting will be ignored if overrideTsconfig is used.

    interface IConfigDocModel

    interface IConfigDocModel {}
    • Configures how the doc model file (*.api.json) will be generated.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property apiJsonFilePath

    apiJsonFilePath?: string;
    • The output path for the doc model file. The file extension should be ".api.json".

      Remarks

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    property enabled

    enabled: boolean;
    • Whether to generate a doc model file.

    interface IConfigDtsRollup

    interface IConfigDtsRollup {}
    • Configures how the .d.ts rollup file will be generated.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property betaTrimmedFilePath

    betaTrimmedFilePath?: string;
    • Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.

      Remarks

      This file will include only declarations that are marked as @public or @beta.

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    property enabled

    enabled: boolean;
    • Whether to generate the .d.ts rollup file.

    property omitTrimmingComments

    omitTrimmingComments?: boolean;
    • When a declaration is trimmed, by default it will be replaced by a code comment such as "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the declaration completely.

    property publicTrimmedFilePath

    publicTrimmedFilePath?: string;
    • Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.

      Remarks

      This file will include only declarations that are marked as @public.

      If the path is an empty string, then this file will not be written.

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    property untrimmedFilePath

    untrimmedFilePath?: string;
    • Specifies the output path for a .d.ts rollup file to be generated without any trimming.

      Remarks

      This file will include all declarations that are exported by the main entry point.

      If the path is an empty string, then this file will not be written.

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

    interface IConfigFile

    interface IConfigFile {}
    • Configuration options for the API Extractor tool. These options can be constructed programmatically or loaded from the api-extractor.json config file using the ExtractorConfig class.

      Modifiers

      • @public

    property apiReport

    apiReport?: IConfigApiReport;

    property bundledPackages

    bundledPackages?: string[];
    • A list of NPM package names whose exports should be treated as part of this package.

      Remarks

      For example, suppose that Webpack is used to generate a distributed bundle for the project library1, and another NPM package library2 is embedded in this bundle. Some types from library2 may become part of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly imports library2. To avoid this, we can specify:

      "bundledPackages": [ "library2" ],

      This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been local files for library1.

    property compiler

    compiler?: IConfigCompiler;

    property docModel

    docModel?: IConfigDocModel;

    property dtsRollup

    dtsRollup?: IConfigDtsRollup;

    property extends

    extends?: string;
    • Optionally specifies another JSON config file that this file extends from. This provides a way for standard settings to be shared across multiple projects.

      Remarks

      If the path starts with ./ or ../, the path is resolved relative to the folder of the file that contains the extends field. Otherwise, the first path segment is interpreted as an NPM package name, and will be resolved using NodeJS require().

    property mainEntryPointFilePath

    mainEntryPointFilePath: string;
    • Specifies the .d.ts file to be used as the starting point for analysis. API Extractor analyzes the symbols exported by this module.

      Remarks

      The file extension must be ".d.ts" and not ".ts". The path is resolved relative to the "projectFolder" location.

    property messages

    messages?: IExtractorMessagesConfig;

    property newlineKind

    newlineKind?: 'crlf' | 'lf' | 'os';
    • Specifies what type of newlines API Extractor should use when writing output files.

      Remarks

      By default, the output files will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead. To use the OS's default newline kind, specify "os".

    property projectFolder

    projectFolder?: string;
    • Determines the <projectFolder> token that can be used with other config file settings. The project folder typically contains the tsconfig.json and package.json config files, but the path is user-defined.

      Remarks

      The path is resolved relative to the folder of the config file that contains the setting.

      The default value for projectFolder is the token <lookup>, which means the folder is determined using the following heuristics:

      If the config/rig.json system is used (as defined by @rushstack/rig-package), then the <lookup> value will be the package folder that referenced the rig.

      Otherwise, the <lookup> value is determined by traversing parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error will be reported.

    property testMode

    testMode?: boolean;
    • Set to true when invoking API Extractor's test harness.

      Remarks

      When testMode is true, the toolVersion field in the .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.

    property tsdocMetadata

    tsdocMetadata?: IConfigTsdocMetadata;

    interface IConfigMessageReportingRule

    interface IConfigMessageReportingRule {}
    • Configures reporting for a given message identifier.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property addToApiReportFile

    addToApiReportFile?: boolean;
    • When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md), then the message will be written inside that file; otherwise, the message is instead logged according to the logLevel option.

    property logLevel

    logLevel: ExtractorLogLevel;
    • Specifies whether the message should be written to the the tool's output log.

      Remarks

      Note that the addToApiReportFile property may supersede this option.

    interface IConfigMessageReportingTable

    interface IConfigMessageReportingTable {}
    • Specifies a table of reporting rules for different message identifiers, and also the default rule used for identifiers that do not appear in the table.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    index signature

    [messageId: string]: IConfigMessageReportingRule;
    • The key is a message identifier for the associated type of message, or "default" to specify the default policy. For example, the key might be TS2551 (a compiler message), tsdoc-link-tag-unescaped-text (a TSDOc message), or ae-extra-release-tag (a message related to the API Extractor analysis).

    interface IConfigTsdocMetadata

    interface IConfigTsdocMetadata {}
    • Configures how the tsdoc-metadata.json file will be generated.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property enabled

    enabled: boolean;
    • Whether to generate the tsdoc-metadata.json file.

    property tsdocMetadataFilePath

    tsdocMetadataFilePath?: string;
    • Specifies where the TSDoc metadata file should be written.

      Remarks

      The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

      The default value is <lookup>, which causes the path to be automatically inferred from the tsdocMetadata, typings or main fields of the project's package.json. If none of these fields are set, the lookup falls back to tsdoc-metadata.json in the package folder.

    interface IExtractorConfigLoadForFolderOptions

    interface IExtractorConfigLoadForFolderOptions {}

    property packageJsonLookup

    packageJsonLookup?: PackageJsonLookup;
    • An already constructed PackageJsonLookup cache object to use. If omitted, a temporary one will be constructed.

    property rigConfig

    rigConfig?: RigConfig;
    • An already constructed RigConfig object. If omitted, then a new RigConfig object will be constructed.

    property startingFolder

    startingFolder: string;
    • The folder path to start from when searching for api-extractor.json.

    interface IExtractorConfigPrepareOptions

    interface IExtractorConfigPrepareOptions {}

    property configObject

    configObject: IConfigFile;

    property configObjectFullPath

    configObjectFullPath: string | undefined;
    • The absolute path of the file that the configObject object was loaded from. This is used for error messages and when probing for tsconfig.json.

      Remarks

      If configObjectFullPath and projectFolderLookupToken are both unspecified, then the api-extractor.json config file must explicitly specify a projectFolder setting rather than relying on the <lookup> token.

    property packageJson

    packageJson?: INodePackageJson | undefined;
    • The parsed package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

      Remarks

      If omitted, then the <unscopedPackageName> and <packageName> tokens will have default values.

    property packageJsonFullPath

    packageJsonFullPath: string | undefined;
    • The absolute path of the file that the packageJson object was loaded from, or undefined if API Extractor was invoked without a package.json file.

      Remarks

      This is used for error messages and when resolving paths found in package.json.

      If packageJsonFullPath is specified but packageJson is omitted, the file will be loaded automatically.

    property projectFolderLookupToken

    projectFolderLookupToken?: string;
    • The default value for the projectFolder setting is the <lookup> token, which uses a heuristic to guess an appropriate project folder. Use projectFolderLookupValue to manually specify the <lookup> token value instead.

      Remarks

      If the projectFolder setting is explicitly specified in api-extractor.json file, it should take precedence over a value specified via the API. Thus the projectFolderLookupToken option provides a way to override the default value for projectFolder setting while still honoring a manually specified value.

    property tsdocConfigFile

    tsdocConfigFile?: TSDocConfigFile;
    • Allow customization of the tsdoc.json config file. If omitted, this file will be loaded from its default location. If the file does not exist, then the standard definitions will be used from @microsoft/api-extractor/extends/tsdoc-base.json.

    interface IExtractorInvokeOptions

    interface IExtractorInvokeOptions {}
    • Runtime options for Extractor.

      Modifiers

      • @public

    property compilerState

    compilerState?: CompilerState;
    • An optional TypeScript compiler state. This allows an optimization where multiple invocations of API Extractor can reuse the same TypeScript compiler analysis.

    property localBuild

    localBuild?: boolean;
    • Indicates that API Extractor is running as part of a local build, e.g. on developer's machine.

      Remarks

      This disables certain validation that would normally be performed for a ship/production build. For example, the *.api.md report file is automatically updated in a local build.

      The default value is false.

    property messageCallback

    messageCallback?: (message: ExtractorMessage) => void;
    • An optional callback function that will be called for each ExtractorMessage before it is displayed by API Extractor. The callback can customize the message, handle it, or discard it.

      Remarks

      If a messageCallback is not provided, then by default API Extractor will print the messages to the STDERR/STDOUT console.

    property showDiagnostics

    showDiagnostics?: boolean;
    • If true, API Extractor will print diagnostic information used for troubleshooting problems. These messages will be included as ExtractorLogLevel.Verbose output.

      Remarks

      Setting showDiagnostics=true forces showVerboseMessages=true.

    property showVerboseMessages

    showVerboseMessages?: boolean;

    property typescriptCompilerFolder

    typescriptCompilerFolder?: string;
    • Specifies an alternate folder path to be used when loading the TypeScript system typings.

      Remarks

      API Extractor uses its own TypeScript compiler engine to analyze your project. If your project is built with a significantly different TypeScript version, sometimes API Extractor may report compilation errors due to differences in the system typings (e.g. lib.dom.d.ts). You can use the "--typescriptCompilerFolder" option to specify the folder path where you installed the TypeScript package, and API Extractor's compiler will use those system typings instead.

    interface IExtractorMessageProperties

    interface IExtractorMessageProperties {}

    property exportName

    readonly exportName?: string;
    • A declaration can have multiple names if it is exported more than once. If an ExtractorMessage applies to a specific export name, this property can indicate that.

      Remarks

      Used by ExtractorMessageId.InternalMissingUnderscore.

    interface IExtractorMessagesConfig

    interface IExtractorMessagesConfig {}
    • Configures how API Extractor reports error and warning messages produced during analysis.

      Remarks

      This is part of the IConfigFile structure.

      Modifiers

      • @public

    property compilerMessageReporting

    compilerMessageReporting?: IConfigMessageReportingTable;
    • Configures handling of diagnostic messages generating the TypeScript compiler while analyzing the input .d.ts files.

    property extractorMessageReporting

    extractorMessageReporting?: IConfigMessageReportingTable;
    • Configures handling of messages reported by API Extractor during its analysis.

    property tsdocMessageReporting

    tsdocMessageReporting?: IConfigMessageReportingTable;
    • Configures handling of messages reported by the TSDoc parser when analyzing code comments.

    Enums

    enum ConsoleMessageId

    const enum ConsoleMessageId {
    Preamble = 'console-preamble',
    CompilerVersionNotice = 'console-compiler-version-notice',
    UsingCustomTSDocConfig = 'console-using-custom-tsdoc-config',
    FoundTSDocMetadata = 'console-found-tsdoc-metadata',
    WritingDocModelFile = 'console-writing-doc-model-file',
    WritingDtsRollup = 'console-writing-dts-rollup',
    ApiReportNotCopied = 'console-api-report-not-copied',
    ApiReportCopied = 'console-api-report-copied',
    ApiReportUnchanged = 'console-api-report-unchanged',
    ApiReportCreated = 'console-api-report-created',
    ApiReportFolderMissing = 'console-api-report-folder-missing',
    Diagnostics = 'console-diagnostics',
    }

    member ApiReportCopied

    ApiReportCopied = 'console-api-report-copied'
    • "You have changed the public API signature for this project. Updating ___"

    member ApiReportCreated

    ApiReportCreated = 'console-api-report-created'
    • "The API report file was missing, so a new file was created. Please add this file to Git: ___"

    member ApiReportFolderMissing

    ApiReportFolderMissing = 'console-api-report-folder-missing'
    • "Unable to create the API report file. Please make sure the target folder exists: ___"

    member ApiReportNotCopied

    ApiReportNotCopied = 'console-api-report-not-copied'
    • "You have changed the public API signature for this project. Please copy the file ___ to ___, or perform a local build (which does this automatically). See the Git repo documentation for more info."

      OR

      "The API report file is missing. Please copy the file ___ to ___, or perform a local build (which does this automatically). See the Git repo documentation for more info."

    member ApiReportUnchanged

    ApiReportUnchanged = 'console-api-report-unchanged'
    • "The API report is up to date: ___"

    member CompilerVersionNotice

    CompilerVersionNotice = 'console-compiler-version-notice'
    • "The target project appears to use TypeScript ___ which is newer than the bundled compiler engine; consider upgrading API Extractor."

    member Diagnostics

    Diagnostics = 'console-diagnostics'
    • Used for the information printed when the "--diagnostics" flag is enabled.

    member FoundTSDocMetadata

    FoundTSDocMetadata = 'console-found-tsdoc-metadata'
    • "Found metadata in ___"

    member Preamble

    Preamble = 'console-preamble'
    • "Analysis will use the bundled TypeScript version ___"

    member UsingCustomTSDocConfig

    UsingCustomTSDocConfig = 'console-using-custom-tsdoc-config'
    • "Using custom TSDoc config from ___"

    member WritingDocModelFile

    WritingDocModelFile = 'console-writing-doc-model-file'
    • "Writing: ___"

    member WritingDtsRollup

    WritingDtsRollup = 'console-writing-dts-rollup'
    • "Writing package typings: ___"

    enum ExtractorLogLevel

    const enum ExtractorLogLevel {
    Error = 'error',
    Warning = 'warning',
    Info = 'info',
    Verbose = 'verbose',
    None = 'none',
    }

    member Error

    Error = 'error'
    • The message will be displayed as an error.

      Remarks

      Errors typically cause the build to fail and return a nonzero exit code.

    member Info

    Info = 'info'
    • The message will be displayed as an informational message.

      Remarks

      Informational messages may contain newlines to ensure nice formatting of the output, however word-wrapping is the responsibility of the message handler.

    member None

    None = 'none'
    • The message will be discarded entirely.

    member Verbose

    Verbose = 'verbose'
    • The message will be displayed only when "verbose" output is requested, e.g. using the --verbose command line option.

    member Warning

    Warning = 'warning'
    • The message will be displayed as an warning.

      Remarks

      Warnings typically cause a production build fail and return a nonzero exit code. For a non-production build (e.g. using the --local option with api-extractor run), the warning is displayed but the build will not fail.

    enum ExtractorMessageCategory

    const enum ExtractorMessageCategory {
    Compiler = 'Compiler',
    TSDoc = 'TSDoc',
    Extractor = 'Extractor',
    Console = 'console',
    }

    member Compiler

    Compiler = 'Compiler'
    • Messages originating from the TypeScript compiler.

      Remarks

      These strings begin with the prefix "TS" and have a numeric error code. Example: TS2551

    member Console

    Console = 'console'
    • Console messages communicate the progress of the overall operation. They may include newlines to ensure nice formatting. They are output in real time, and cannot be routed to the API Report file.

      Remarks

      These strings begin with the prefix "console-". Example: console-writing-typings-file

    member Extractor

    Extractor = 'Extractor'
    • Messages related to API Extractor's analysis.

      Remarks

      These strings begin with the prefix "ae-". Example: ae-extra-release-tag

    member TSDoc

    TSDoc = 'TSDoc'
    • Messages related to parsing of TSDoc comments.

      Remarks

      These strings begin with the prefix "tsdoc-". Example: tsdoc-link-tag-unescaped-text

    enum ExtractorMessageId

    const enum ExtractorMessageId {
    ExtraReleaseTag = 'ae-extra-release-tag',
    DifferentReleaseTags = 'ae-different-release-tags',
    IncompatibleReleaseTags = 'ae-incompatible-release-tags',
    MissingReleaseTag = 'ae-missing-release-tag',
    MisplacedPackageTag = 'ae-misplaced-package-tag',
    ForgottenExport = 'ae-forgotten-export',
    InternalMissingUnderscore = 'ae-internal-missing-underscore',
    InternalMixedReleaseTag = 'ae-internal-mixed-release-tag',
    PreapprovedUnsupportedType = 'ae-preapproved-unsupported-type',
    PreapprovedBadReleaseTag = 'ae-preapproved-bad-release-tag',
    UnresolvedInheritDocReference = 'ae-unresolved-inheritdoc-reference',
    UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base',
    CyclicInheritDoc = 'ae-cyclic-inherit-doc',
    UnresolvedLink = 'ae-unresolved-link',
    SetterWithDocs = 'ae-setter-with-docs',
    MissingGetter = 'ae-missing-getter',
    }

    member CyclicInheritDoc

    CyclicInheritDoc = 'ae-cyclic-inherit-doc'
    • "The @inheritDoc tag for ___ refers to its own declaration."

    member DifferentReleaseTags

    DifferentReleaseTags = 'ae-different-release-tags'
    • "This symbol has another declaration with a different release tag."

    member ExtraReleaseTag

    ExtraReleaseTag = 'ae-extra-release-tag'
    • "The doc comment should not contain more than one release tag."

    member ForgottenExport

    ForgottenExport = 'ae-forgotten-export'
    • "The symbol ___ needs to be exported by the entry point ___."

    member IncompatibleReleaseTags

    IncompatibleReleaseTags = 'ae-incompatible-release-tags'
    • "The symbol ___ is marked as ___, but its signature references ___ which is marked as ___."

    member InternalMissingUnderscore

    InternalMissingUnderscore = 'ae-internal-missing-underscore'
    • "The name ___ should be prefixed with an underscore because the declaration is marked as @internal."

    member InternalMixedReleaseTag

    InternalMixedReleaseTag = 'ae-internal-mixed-release-tag'
    • "Mixed release tags are not allowed for ___ because one of its declarations is marked as @internal."

    member MisplacedPackageTag

    MisplacedPackageTag = 'ae-misplaced-package-tag'
    • "The @packageDocumentation comment must appear at the top of entry point *.d.ts file."

    member MissingGetter

    MissingGetter = 'ae-missing-getter'
    • "The property ___ has a setter but no getter."

    member MissingReleaseTag

    MissingReleaseTag = 'ae-missing-release-tag'
    • "___ is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)."

    member PreapprovedBadReleaseTag

    PreapprovedBadReleaseTag = 'ae-preapproved-bad-release-tag'
    • "The @preapproved tag cannot be applied to ___ without an @internal release tag."

    member PreapprovedUnsupportedType

    PreapprovedUnsupportedType = 'ae-preapproved-unsupported-type'
    • "The @preapproved tag cannot be applied to ___ because it is not a supported declaration type."

    member SetterWithDocs

    SetterWithDocs = 'ae-setter-with-docs'
    • "The doc comment for the property ___ must appear on the getter, not the setter."

    member UnresolvedInheritDocBase

    UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base'
    • "The @inheritDoc tag needs a TSDoc declaration reference; signature matching is not supported yet."

    member UnresolvedInheritDocReference

    UnresolvedInheritDocReference = 'ae-unresolved-inheritdoc-reference'
    • "The @inheritDoc reference could not be resolved."

    UnresolvedLink = 'ae-unresolved-link'
    • "The @link reference could not be resolved."

    Package Files (1)

    Dependencies (12)

    Dev Dependencies (8)

    Peer Dependencies (0)

    No peer dependencies.

    Badge

    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@microsoft/api-extractor.

    • Markdown
      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@microsoft/api-extractor)
    • HTML
      <a href="https://www.jsdocs.io/package/@microsoft/api-extractor"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>