@microsoft/api-extractor/lib/extractor/Extractor.d.ts

Validate, document, and review the exported API for a TypeScript library

import * as ts from 'typescript';
import { JsonSchema } from '@microsoft/node-core-library';
import { IExtractorConfig, IExtractorProjectConfig } from './IExtractorConfig';
import { ILogger } from './ILogger';
/**
 * Options for {@link Extractor.processProject}.
 * @public
 */
export interface IAnalyzeProjectOptions {
    /**
     * If omitted, then the {@link IExtractorConfig.project} config will be used by default.
     */
    projectConfig?: IExtractorProjectConfig;
}
/**
 * Runtime options for Extractor.
 *
 * @public
 */
export interface IExtractorOptions {
    /**
     * If IExtractorConfig.project.configType = 'runtime', then the TypeScript compiler state
     * must be provided via this option.
     */
    compilerProgram?: ts.Program;
    /**
     * Allows the caller to handle API Extractor errors; otherwise, they will be logged
     * to the console.
     */
    customLogger?: Partial<ILogger>;
    /**
     * Indicates that API Extractor is running as part of a local build, e.g. on developer's
     * machine. This disables certain validation that would normally be performed
     * for a ship/production build. For example, the *.api.ts review file is
     * automatically local in a debug build.
     *
     * The default value is false.
     */
    localBuild?: boolean;
    /**
     * By default API Extractor uses its own TypeScript compiler version to analyze your project.
     * This can often cause compiler errors due to incompatibilities between different TS versions.
     * Use this option to specify the folder path for your compiler version.
     *
     * @remarks
     * This option only applies when compiler.config.configType is set to "tsconfig"
     *
     * @beta
     */
    typescriptCompilerFolder?: string;
    /**
     * This option causes the typechecker to be invoked with the --skipLibCheck option. 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. If this option is used, it is strongly recommended that broken
     * dependencies be fixed or upgraded.
     *
     * @remarks
     * This option only applies when compiler.config.configType is set to "tsconfig"
     */
    skipLibCheck?: boolean;
}
/**
 * Used to invoke the API Extractor tool.
 * @public
 */
export declare class Extractor {
    /**
     * The JSON Schema for API Extractor config file (api-extractor-config.schema.json).
     */
    static jsonSchema: JsonSchema;
    private static _defaultConfig;
    private static _declarationFileExtensionRegExp;
    private static _defaultLogger;
    private readonly _actualConfig;
    private readonly _program;
    private readonly _localBuild;
    private readonly _monitoredLogger;
    private readonly _absoluteRootFolder;
    /**
     * Given a list of absolute file paths, return a list containing only the declaration
     * files.  Duplicates are also eliminated.
     *
     * @remarks
     * The tsconfig.json settings specify the compiler's input (a set of *.ts source files,
     * plus some *.d.ts declaration files used for legacy typings).  However API Extractor
     * analyzes the compiler's output (a set of *.d.ts entry point files, plus any legacy
     * typings).  This requires API Extractor to generate a special file list when it invokes
     * the compiler.
     *
     * For configType=tsconfig this happens automatically, but for configType=runtime it is
     * the responsibility of the custom tooling.  The generateFilePathsForAnalysis() function
     * is provided to facilitate that.  Duplicates are removed so that entry points can be
     * appended without worrying whether they may already appear in the tsconfig.json file list.
     */
    static generateFilePathsForAnalysis(inputFilePaths: string[]): string[];
    private static _applyConfigDefaults(config);
    constructor(config: IExtractorConfig, options?: IExtractorOptions);
    /**
     * Returns the normalized configuration object after defaults have been applied.
     *
     * @remarks
     * This is a read-only object.  The caller should NOT modify any member of this object.
     * It is provided for diagnostic purposes.  For example, a build script could write
     * this object to a JSON file to report the final configuration options used by API Extractor.
     */
    readonly actualConfig: IExtractorConfig;
    /**
     * Invokes the API Extractor engine, using the configuration that was passed to the constructor.
     * @deprecated Use {@link Extractor.processProject} instead.
     */
    analyzeProject(options?: IAnalyzeProjectOptions): void;
    /**
     * Invokes the API Extractor engine, using the configuration that was passed to the constructor.
     * @param options - provides additional runtime state that is NOT part of the API Extractor
     *     config file.
     * @returns true for a successful build, or false if the tool chain should fail the build
     *
     * @remarks
     *
     * This function returns false to indicate that the build failed, i.e. the command-line tool
     * would return a nonzero exit code.  Normally the build fails if there are any errors or
     * warnings; however, if options.localBuild=true then warnings are ignored.
     */
    processProject(options?: IAnalyzeProjectOptions): boolean;
    private _generateRollupDtsFiles(context);
    private _generateRollupDtsFile(dtsRollupGenerator, mainDtsRollupFullPath, dtsKind);
    private _getShortFilePath(absolutePath);
    /**
     * Update the parsed command line to use paths from the specified TS compiler folder, if
     * a TS compiler folder is specified.
     */
    private _updateCommandLineForTypescriptPackage(commandLine, options);
}