dets/dist/index.d.ts

A TypeScript declaration file bundler.

import * as Typescript from 'typescript';

declare module "dets" {
  export function setupVisitorContext(name: string, root: string, files: Array<string>, imports: Array<string>, log: Logger, flags: DeclVisitorFlags): DeclVisitorContext;

  export function fillExportsFromApi(context: DeclVisitorContext, apiPath: string, apiName: string): void;

  export function fillExportsFromReferences(context: DeclVisitorContext, typingsPath: string): void;

  export function fillExportsFromTypes(context: DeclVisitorContext, typingsPath: string): void;

  export function addAvailableImports(context: DeclVisitorContext, imports: Array<string>): void;

  export function addAmbientModules(context: DeclVisitorContext, imports: Array<string>): void;

  export function processVisitorContext(context: DeclVisitorContext, plugins: Array<DetsPlugin>): Promise<void>;

  export interface DetsOptions {
    /**
     * The root directory to use. If in doubt just use `process.cwd()`.
     * All other paths (e.g., files) are relative to this directory.
     */
    root?: string;
    /**
     * An optional list of plugins to run.
     */
    plugins?: Array<DetsPlugin>;
    /**
     * Determines if the `@ignore` rule should not be handled by
     * removing the found property.
     */
    noIgnore?: boolean;
    /**
     * Defines imported dependencies which should be excluded from bundling.
     */
    imports?: Array<string>;
    /**
     * Overrides the logger + loglevel combination.
     */
    log?: Logger;
    /**
     * Provides the logger instance for logging.
     */
    logger?: Logger;
    /**
     * Defines the log level to use with the logger.
     */
    logLevel?: LogLevel;
    /**
     * If given does not wrap the declaration in a "declare module" statement.
     */
    noModuleDeclaration?: boolean;
  }

  export interface DeclOptions extends DetsOptions {
    /**
     * The name of the declaration module.
     */
    name: string;
    /**
     * The additional files to consider for typing inspection.
     */
    files?: Array<string>;
    /**
     * The additional type modules to consider for API generation.
     */
    types?: Array<string>;
    /**
     * The APIs to build.
     */
    apis?: Array<{
      /**
       * The root module where the API can be gathered.
       */
      file: string;
      /**
       * The name of the API interface object in the module.
       */
      name: string;
    }>;
  }

  /**
   * Generates a new declaration using the provided options.
   * @param options The options for declaration generation.
   * @returns The content of the declaration.
   */
  export function generateDeclaration(options: DeclOptions): Promise<string>;

  export interface TypingOptions extends DetsOptions {
    /**
     * The additional files to consider for typing inspection.
     */
    files?: Array<string>;
    /**
     * The type modules to inspect for retrieving the typings.
     */
    types: Array<string>;
  }

  /**
   * Retrieves the typings using the given typing options.
   * @param options The options for the typing generation.
   * @returns The retrieved typings module.
   */
  export function retrieveTypings(options: TypingOptions): Promise<TypeRefs>;

  export interface DetsClassicPlugin {
    /**
     * Type of the plugin.
     */
    type: "before-init" | "before-process" | "after-process" | "before-stringify";
    /**
     * The name of the plugin (emitted in case of problems).
     */
    name: string;
    /**
     * Callback to run when invoking the plugin.
     * @param context The context to perform the work on.
     */
    run(context: DeclVisitorContext): void | Promise<void>;
  }

  export interface DetsModernPlugin {
    /**
     * The name of the plugin (emitted in case of problems).
     */
    name: string;
    /**
     * Callback to run when invoking the plugin.
     * @param context The context to perform the work on.
     */
    "before-init"?(context: DeclVisitorContext): void | Promise<void>;
    /**
     * Callback to run when invoking the plugin.
     * @param context The context to perform the work on.
     */
    "before-process"?(context: DeclVisitorContext): void | Promise<void>;
    /**
     * Callback to run when invoking the plugin.
     * @param context The context to perform the work on.
     */
    "before-stringify"?(context: DeclVisitorContext): void | Promise<void>;
    /**
     * Callback to run when invoking the plugin.
     * @param context The context to perform the work on.
     */
    "after-process"?(context: DeclVisitorContext): void | Promise<void>;
  }

  export type DetsPlugin = DetsClassicPlugin | DetsModernPlugin;

  export function createExcludePlugin(moduleNames: Array<string>): DetsPlugin;

  export function createDiffPlugin(originalFile: string): DetsPlugin;

  export interface Logger {
    error(message: string): void;
    warn(message: string): void;
    info(message: string): void;
    verbose(message: string): void;
  }

  export interface DeclVisitorFlags {
    noIgnore: boolean;
    noModuleDeclaration: boolean;
  }

  export interface DeclVisitorContext {
    modules: Record<string, TypeRefs>;
    moduleNames: Record<string, NamesMap>;
    checker: Typescript.TypeChecker;
    program: Typescript.Program;
    exports: Array<Typescript.Node>;
    imports: Array<string>;
    usedImports: Array<string>;
    availableImports: ImportRefs;
    log: Logger;
    name: string;
    flags: DeclVisitorFlags;
    root: string;
    forEachResolvedModule(cb: ResolvedModuleCallback, file: Typescript.SourceFile): void;
  }

  export type LogLevel = 0 | 1 | 2 | 3 | 4 | 5;

  export type TypeRefs = Array<TypeModelExport>;

  export type NamesMap = Map<Typescript.Node, string>;

  export type ImportRefs = Record<string, ImportDefs>;

  export type ResolvedModuleCallback = (value: ResolvedModuleArg, key: string) => void;

  export type TypeModelExport = TypeModelDefault | TypeModelVariable | TypeModelInterface | TypeModelClass | TypeModelFunction | TypeModelEnumLiteral | TypeModelAlias;

  export type ImportDefs = Record<string, Typescript.Node>;

  export interface ResolvedModuleArg {
    resolvedFileName?: string;
    resolvedModule: {
      resolvedFileName: string | undefined;
      originalPath: string | undefined;
      extension: string;
      isExternalLibraryImport: boolean;
      packageId: string | undefined;
      resolvedUsingTsExtension: boolean;
    };
    failedLookupLocations: string | undefined;
    affectingLocations: string | undefined;
    resolutionDiagnostics: string | undefined;
    node10Result: string | undefined;
  }

  export interface TypeModelDefault extends WithTypeComments {
    readonly kind: "default";
    readonly name: string;
    readonly value: TypeModelRef | TypeModelClass;
  }

  export interface TypeModelVariable extends WithTypeComments {
    readonly kind: "const";
    readonly name: string;
    readonly value: TypeModel;
  }

  export interface TypeModelInterface extends WithTypeArgs, WithTypeComments, WithTypeExtends, WithTypeProps {
    readonly kind: "interface";
    readonly name: string;
    readonly mapped?: TypeModelMapped;
  }

  export interface TypeModelClass extends WithTypeComments, WithTypeArgs, WithTypeExtends, WithTypeImplements, WithTypeProps {
    readonly kind: "class";
    readonly name: string;
  }

  export interface TypeModelFunction extends WithTypeArgs {
    readonly kind: "function";
    readonly name: string;
    readonly comment?: string;
    readonly parameters: Array<TypeModelFunctionParameter>;
    readonly returnType: TypeModel;
  }

  export interface TypeModelEnumLiteral extends WithTypeComments {
    readonly kind: "enumLiteral";
    readonly name: string;
    readonly const: boolean;
    readonly values: Array<TypeMemberModel>;
  }

  export interface TypeModelAlias extends WithTypeArgs, WithTypeComments {
    readonly kind: "alias";
    readonly name: string;
    readonly child: TypeModel;
  }

  export interface WithTypeComments {
    readonly comment?: string;
  }

  export interface TypeModelRef extends WithTypeArgs {
    readonly kind: "ref";
    readonly refName: string;
  }

  export type TypeModel = TypeModelExport | TypeModelString | TypeMemberModel | TypeModelProp | TypeModelBoolean | TypeModelNumber | TypeModelUnidentified | TypeModelAny | TypeModelUnknown | TypeModelBigInt | TypeModelLiteral | TypeModelBigIntLiteral | TypeModelESSymbol | TypeModelUniqueESSymbol | TypeModelVoid | TypeModelUndefined | TypeModelNull | TypeModelNever | TypeModelTypeParameter | TypeModelFunctionParameter | TypeModelUnion | TypeModelIntersection | TypeModelIndex | TypeModelAccess | TypeModelIndexedAccess | TypeModelConditional | TypeModelSubstitution | TypeModelNonPrimitive | TypeModelTupleProp | TypeModelTuple | TypeModelConstructor | TypeModelRef | TypeModelPrefix | TypeModelImport | TypeModelPredicate | TypeModelMapped | TypeModelInfer | TypeModelNew | TypeModelGetAccessor | TypeModelSetAccessor | TypeModelParenthesis | TypeModelRest | TypeModelTemplate;

  export interface WithTypeArgs {
    readonly types: Array<TypeModel>;
  }

  export interface WithTypeExtends {
    readonly extends: Array<TypeModel>;
  }

  export interface WithTypeProps {
    readonly props: Array<TypeModel>;
  }

  export interface TypeModelMapped {
    readonly kind: "mapped";
    readonly name: string;
    readonly constraint: TypeModel;
    readonly optional: boolean;
    readonly value: TypeModel;
  }

  export interface WithTypeImplements {
    readonly implements: Array<TypeModel>;
  }

  export interface TypeModelFunctionParameter {
    readonly kind: "parameter";
    readonly param: string;
    readonly value: TypeModel;
    readonly optional: boolean;
    readonly modifiers: string;
    readonly spread: boolean;
  }

  export interface TypeMemberModel extends WithTypeComments {
    readonly kind: "member";
    readonly name: string | TypeModel;
    readonly value: TypeModel;
  }

  export interface TypeModelString {
    readonly kind: "string";
  }

  export interface TypeModelProp extends WithTypeComments {
    readonly name: string | TypeModel;
    readonly modifiers: string;
    readonly optional: boolean;
    readonly kind: "prop";
    readonly valueType: TypeModel;
  }

  export interface TypeModelBoolean {
    readonly kind: "boolean";
  }

  export interface TypeModelNumber {
    readonly kind: "number";
  }

  export interface TypeModelUnidentified {
    readonly kind: "unidentified";
  }

  export interface TypeModelAny {
    readonly kind: "any";
  }

  export interface TypeModelUnknown {
    readonly kind: "unknown";
  }

  export interface TypeModelBigInt {
    readonly kind: "bigint";
  }

  export interface TypeModelLiteral {
    readonly kind: "literal";
    readonly value: boolean | string | number;
  }

  export interface TypeModelBigIntLiteral {
    readonly kind: "bigintLiteral";
    readonly value: string;
  }

  export interface TypeModelESSymbol {
    readonly kind: "esSymbol";
  }

  export interface TypeModelUniqueESSymbol {
    readonly kind: "uniqueEsSymbol";
  }

  export interface TypeModelVoid {
    readonly kind: "void";
  }

  export interface TypeModelUndefined {
    readonly kind: "undefined";
  }

  export interface TypeModelNull {
    readonly kind: "null";
  }

  export interface TypeModelNever {
    readonly kind: "never";
  }

  export interface TypeModelTypeParameter {
    readonly kind: "typeParameter";
    readonly parameter: TypeModel;
    readonly constraint?: TypeModel;
    readonly default?: TypeModel;
  }

  export interface TypeModelUnion extends WithTypeArgs {
    readonly kind: "union";
  }

  export interface TypeModelIntersection extends WithTypeArgs {
    readonly kind: "intersection";
  }

  export interface TypeModelIndex {
    readonly kind: "index";
    readonly parameters: Array<TypeModelFunctionParameter>;
    readonly valueType: TypeModel;
    readonly optional: boolean;
  }

  export interface TypeModelAccess {
    readonly kind: "access";
    readonly name: TypeModel;
    readonly object: TypeModel;
  }

  export interface TypeModelIndexedAccess {
    readonly kind: "indexedAccess";
    readonly index: TypeModel;
    readonly object: TypeModel;
  }

  export interface TypeModelConditional {
    readonly kind: "conditional";
    readonly check: TypeModel;
    readonly extends: TypeModel;
    readonly primary: TypeModel;
    readonly alternate: TypeModel;
  }

  export interface TypeModelSubstitution {
    readonly kind: "substitution";
    readonly variable: TypeModel;
  }

  export interface TypeModelNonPrimitive {
    readonly kind: "nonPrimitive";
    readonly name?: string;
  }

  export interface TypeModelTupleProp extends WithTypeComments {
    readonly name: string | TypeModel;
    readonly optional: boolean;
    readonly kind: "tuple-prop";
    readonly valueType: TypeModel;
  }

  export interface TypeModelTuple extends WithTypeArgs {
    readonly kind: "tuple";
  }

  export interface TypeModelConstructor {
    readonly kind: "constructor";
    readonly comment?: string;
    readonly modifiers: string;
    readonly parameters: Array<TypeModelFunctionParameter>;
  }

  export type TypeModelPrefix = TypeModelPrefixKeyof | TypeModelPrefixReadonly | TypeModelPrefixUnique;

  export interface TypeModelImport {
    readonly kind: "import";
    readonly value: TypeModel;
    readonly qualifier?: string;
  }

  export interface TypeModelPredicate {
    readonly kind: "predicate";
    readonly name: string;
    readonly value: TypeModel;
  }

  export interface TypeModelInfer {
    readonly kind: "infer";
    readonly parameter: TypeModel;
  }

  export interface TypeModelNew extends WithTypeArgs {
    readonly kind: "new";
    readonly comment?: string;
    readonly parameters: Array<TypeModelFunctionParameter>;
    readonly returnType: TypeModel;
  }

  export interface TypeModelGetAccessor extends WithTypeComments {
    readonly kind: "get";
    readonly name: string | TypeModel;
    readonly type: TypeModel;
    readonly modifiers: string;
  }

  export interface TypeModelSetAccessor extends WithTypeComments {
    readonly kind: "set";
    readonly name: string | TypeModel;
    readonly parameters: Array<TypeModelFunctionParameter>;
    readonly modifiers: string;
  }

  export interface TypeModelParenthesis {
    readonly kind: "parenthesis";
    readonly value: TypeModel;
  }

  export interface TypeModelRest {
    readonly kind: "rest";
    readonly value: TypeModel;
  }

  export interface TypeModelTemplate {
    readonly kind: "template";
    readonly parts: Array<string | TypeModel>;
  }

  export interface TypeModelPrefixKeyof {
    readonly kind: "keyof";
    readonly value: TypeModel;
  }

  export interface TypeModelPrefixReadonly {
    readonly kind: "readonly";
    readonly value: TypeModel;
  }

  export interface TypeModelPrefixUnique {
    readonly kind: "unique";
    readonly value: TypeModel;
  }
}