api.d.ts

/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */
/**
 * @module
 * @description
 * Entry point for all public APIs of the language service package.
 */
import type ts from 'typescript';
export interface PluginConfig {
    /**
     * If true, return only Angular results. Otherwise, return Angular + TypeScript
     * results.
     */
    angularOnly: boolean;
    /**
     * If true, enable `strictTemplates` in Angular compiler options regardless
     * of its value in tsconfig.json.
     */
    forceStrictTemplates?: true;
    /**
     * If false, disables parsing control flow blocks in the compiler. Should be used only when older
     * versions of Angular that do not support blocks (pre-v17) used with the language service.
     */
    enableBlockSyntax?: false;
    /**
     * Version of `@angular/core` that was detected in the user's workspace.
     */
    angularCoreVersion?: string;
    /**
     * If false, disables parsing of `@let` declarations in the compiler.
     */
    enableLetSyntax?: false;
    /**
     * Whether selectorless is enabled.
     */
    enableSelectorless?: true;
    /**
     * A list of diagnostic codes that should be supressed in the language service.
     */
    suppressAngularDiagnosticCodes?: number[];
}
export type GetTcbResponse = {
    /**
     * The filename of the SourceFile this typecheck block belongs to.
     * The filename is entirely opaque and unstable, useful only for debugging
     * purposes.
     */
    fileName: string;
    /** The content of the SourceFile this typecheck block belongs to. */
    content: string;
    /**
     * Spans over node(s) in the typecheck block corresponding to the
     * TS code generated for template node under the current cursor position.
     *
     * When the cursor position is over a source for which there is no generated
     * code, `selections` is empty.
     */
    selections: ts.TextSpan[];
};
export type GetComponentLocationsForTemplateResponse = ts.DocumentSpan[];
export type GetTemplateLocationForComponentResponse = ts.DocumentSpan | undefined;
/**
 * Function that can be invoked to show progress when computing
 * refactoring edits.
 *
 * Useful for refactorings which take a long time to compute edits for.
 */
export type ApplyRefactoringProgressFn = (percentage: number, updateMessage: string) => void;
/** Interface describing the result for computing edits of a refactoring. */
export interface ApplyRefactoringResult extends Omit<ts.RefactorEditInfo, 'notApplicableReason'> {
    errorMessage?: string;
    warningMessage?: string;
}
/**
 * Angular-specific LSP SymbolKind values for template symbols.
 * These are used for symbols that don't have a direct TypeScript ScriptElementKind mapping.
 * Values match LSP SymbolKind enum: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#symbolKind
 */
export declare enum AngularSymbolKind {
    Namespace = 3,
    Class = 5,
    Array = 18,
    Object = 19,
    Struct = 23,
    Event = 24
}
/**
 * A document symbol representing an Angular template element.
 * This uses TypeScript's NavigationTree structure so it can be merged with TS symbols.
 */
export interface TemplateDocumentSymbol {
    /** Display name for the symbol */
    text: string;
    /** Kind of symbol (using TypeScript's ScriptElementKind for compatibility) */
    kind: ts.ScriptElementKind;
    /**
     * Optional LSP SymbolKind override for Angular-specific symbol types.
     * When set, this takes precedence over the default ScriptElementKind mapping.
     */
    lspKind?: AngularSymbolKind;
    /** Span covering the entire symbol */
    spans: ts.TextSpan[];
    /** Span for just the name (used for selection) */
    nameSpan?: ts.TextSpan;
    /** Child symbols */
    childItems?: TemplateDocumentSymbol[];
    /**
     * The name of the class this template belongs to.
     * Only set for root-level symbols in TypeScript files with inline templates.
     * Used to merge template symbols into the correct component class when
     * multiple components exist in the same file.
     */
    className?: string;
}
/**
 * Options for customizing document symbols behavior.
 */
export interface DocumentSymbolsOptions {
    /**
     * Show all implicit @for loop variables ($index, $count, $first, $last, $even, $odd).
     * When false (default), only explicitly aliased variables like `let i = $index` are shown.
     */
    showImplicitForVariables?: boolean;
}
/**
 * Result for linked editing ranges containing the ranges and optional word pattern.
 */
export interface LinkedEditingRanges {
    /** The ranges that should be edited together. */
    ranges: ts.TextSpan[];
    /** An optional word pattern to describe valid tag names. */
    wordPattern?: string;
}
/**
 * A display part for interactive inlay hints.
 * When clicked, can navigate to the definition of the type/parameter.
 */
export interface InlayHintDisplayPart {
    /** The text to display */
    text: string;
    /** Optional navigation target span */
    span?: {
        /** Start offset in the target file */
        start: number;
        /** Length of the span */
        length: number;
    };
    /** Optional target file path for navigation */
    file?: string;
}
/**
 * Represents an Angular-specific inlay hint to be displayed in the editor.
 */
export interface AngularInlayHint {
    /** Offset position where the hint should appear */
    position: number;
    /**
     * The text to display.
     * For non-interactive hints, this contains the full hint text.
     * For interactive hints, this may be empty and displayParts is used instead.
     */
    text: string;
    /** Kind of hint: 'Type' for type annotations, 'Parameter' for parameter names */
    kind: 'Type' | 'Parameter';
    /** Whether to add padding before the hint */
    paddingLeft?: boolean;
    /** Whether to add padding after the hint */
    paddingRight?: boolean;
    /** Optional tooltip documentation */
    tooltip?: string;
    /**
     * Display parts for interactive hints.
     * When present, these parts can be clicked to navigate to type/parameter definitions.
     * Used when interactiveInlayHints is enabled.
     */
    displayParts?: InlayHintDisplayPart[];
}
/**
 * Configuration for which Angular inlay hints to show.
 * These options are designed to align with TypeScript's inlay hints configuration
 * where applicable to Angular templates.
 */
export interface InlayHintsConfig {
    /** Show type hints for @for loop variables: `@for (item: Item of items)` */
    forLoopVariableTypes?: boolean;
    /**
     * Show type hints for @if alias variables: `@if (data; as result: Data)`
     *
     * Can be a boolean to enable/disable all @if alias hints, or an object for fine-grained control:
     * - `simpleExpressions`: Show hints for simple variable references like `@if (data; as result)`
     * - `complexExpressions`: Show hints for complex expressions like `@if (data == 2; as b)` or `@if (data.prop; as p)`
     *
     * When set to true, shows hints for all @if aliases.
     * When set to 'complex', only shows hints for complex expressions (property access, comparisons, calls, etc.)
     */
    ifAliasTypes?: boolean | 'complex' | {
        /** Show hints for simple variable references: @if (data; as result). Default: true */
        simpleExpressions?: boolean;
        /** Show hints for complex expressions: @if (data.prop; as p), @if (a == b; as c). Default: true */
        complexExpressions?: boolean;
    };
    /** Show type hints for @let declarations: `@let count: number = items.length` */
    letDeclarationTypes?: boolean;
    /** Show type hints for template reference variables: `#ref: HTMLInputElement` */
    referenceVariableTypes?: boolean;
    /**
     * Suppress hints when variable name matches the type name (case-insensitive).
     * Equivalent to TypeScript's `includeInlayVariableTypeHintsWhenTypeMatchesName`.
     * When false, skips hints like `@let user: User = getUser()` where name matches type.
     * @default true
     */
    variableTypeHintsWhenTypeMatchesName?: boolean;
    /**
     * Show type hints for arrow function parameters in templates.
     * Equivalent to TypeScript's `includeInlayFunctionParameterTypeHints`.
     *
     * When enabled, shows: `(a: number, b: string) => a + b` where types are inferred.
     * @default true
     */
    arrowFunctionParameterTypes?: boolean;
    /**
     * Show return type hints for arrow functions in templates.
     * Equivalent to TypeScript's `includeInlayFunctionLikeReturnTypeHints`.
     *
     * When enabled, shows: `(a, b): number => a + b` where return type is inferred.
     * @default true
     */
    arrowFunctionReturnTypes?: boolean;
    /**
     * Show parameter name hints for function/method arguments in expressions.
     * Equivalent to TypeScript's `includeInlayParameterNameHints`.
     *
     * When enabled, shows: `handleClick(event: $event)` where 'event' is the parameter name.
     * Options:
     * - 'none': No parameter name hints
     * - 'literals': Only for literal arguments (strings, numbers, booleans)
     * - 'all': For all arguments
     * @default 'all'
     */
    parameterNameHints?: 'none' | 'literals' | 'all';
    /**
     * Show parameter hints even when argument name matches parameter name.
     * Equivalent to TypeScript's `includeInlayParameterNameHintsWhenArgumentMatchesName`.
     * When false, skips hints like `onClick(event)` where arg name matches param name.
     * @default false
     */
    parameterNameHintsWhenArgumentMatchesName?: boolean;
    /**
     * Show type hints for event binding $event parameter.
     * Works with @Output() EventEmitter<T>, output() OutputEmitterRef<T>, and model() changes.
     * Example: `(click: MouseEvent)`, `(valueChange: string)`
     *
     * Can be a boolean to enable/disable all event hints, or an object for fine-grained control:
     * - `nativeEvents`: Show hints for native HTML events (click, input, etc.)
     * - `componentEvents`: Show hints for custom component/directive events
     * - `animationEvents`: Show hints for animation events (@trigger.done)
     */
    eventParameterTypes?: boolean | {
        /** Show hints for native HTML events (click, input, keydown, etc.). Default: true */
        nativeEvents?: boolean;
        /** Show hints for custom component/directive output events. Default: true */
        componentEvents?: boolean;
        /** Show hints for animation events (@trigger.start, @trigger.done). Default: true */
        animationEvents?: boolean;
    };
    /** Show type hints for pipe output types: `{{ value | async: Observable<T> }}` */
    pipeOutputTypes?: boolean;
    /**
     * Show type hints for property/input binding types.
     * Works with @Input(), input(), input.required(), and model() inputs.
     * Example: `[disabled: boolean]="isDisabled"`
     *
     * Can be a boolean to enable/disable all property hints, or an object for fine-grained control:
     * - `nativeProperties`: Show hints for native DOM properties ([disabled], [hidden], etc.)
     * - `componentInputs`: Show hints for component/directive @Input() and input() bindings
     */
    propertyBindingTypes?: boolean | {
        /** Show hints for native DOM properties. Default: true */
        nativeProperties?: boolean;
        /** Show hints for component/directive inputs. Default: true */
        componentInputs?: boolean;
    };
    /**
     * Show WritableSignal<T> type for two-way bindings with model() signals.
     * When true: `[(checked: WritableSignal<boolean>)]="checkboxSignal"`
     * When false: `[(checked: boolean)]="checkboxSignal"`
     * @default true
     */
    twoWayBindingSignalTypes?: boolean;
    /**
     * Add visual indicator for input.required() bindings.
     * Options:
     * - 'none': No special indicator
     * - 'asterisk': Add asterisk suffix `[user*: User]`
     * - 'exclamation': Add exclamation suffix `[user: User!]`
     * @default 'none'
     */
    requiredInputIndicator?: 'none' | 'asterisk' | 'exclamation';
    /**
     * Enable clickable hints that navigate to type/parameter definitions.
     * Equivalent to TypeScript's `interactiveInlayHints`.
     * @default false
     */
    interactiveInlayHints?: boolean;
    /**
     * Show type hints for @HostListener argument expressions.
     * Example: `@HostListener('click', ['$event.target: EventTarget | null', '$event.clientX: number'])`
     *
     * When enabled, shows the inferred type for each expression passed in the decorator arguments.
     * @default true
     */
    hostListenerArgumentTypes?: boolean;
    /**
     * Show type hints for @switch block expressions.
     * Example: `@switch (status: Status) { @case (Status.Active) { ... } }`
     *
     * When enabled, shows the inferred type of the switch expression value.
     * @default true
     */
    switchExpressionTypes?: boolean;
    /**
     * Show type hints for @defer block trigger expressions.
     * Example: `@defer (when isVisible: boolean) { ... }`
     *
     * When enabled, shows the inferred type for 'when' trigger conditions.
     * @default true
     */
    deferTriggerTypes?: boolean;
}
/**
 * `NgLanguageService` describes an instance of an Angular language service,
 * whose API surface is a strict superset of TypeScript's language service.
 */
export interface NgLanguageService extends ts.LanguageService {
    /**
     * Triggers the Angular compiler's analysis pipeline without performing
     * per-file type checking. This is a lighter alternative to calling
     * `getSemanticDiagnostics()` when the goal is only to ensure that the
     * Angular project has been analyzed (e.g. during project initialization).
     */
    ensureProjectAnalyzed(): void;
    getTcb(fileName: string, position: number): GetTcbResponse | undefined;
    /**
     * Gets linked editing ranges for synchronized editing of HTML tag pairs.
     *
     * When the cursor is on an element tag name, returns both the opening and closing
     * tag name spans so they can be edited simultaneously. This overrides TypeScript's
     * built-in method which only works for JSX/TSX.
     *
     * @param fileName The file to check
     * @param position The cursor position in the file
     * @returns LinkedEditingRanges if on a tag name, undefined otherwise
     */
    getLinkedEditingRangeAtPosition(fileName: string, position: number): LinkedEditingRanges | undefined;
    getComponentLocationsForTemplate(fileName: string): GetComponentLocationsForTemplateResponse;
    getTemplateLocationForComponent(fileName: string, position: number): GetTemplateLocationForComponentResponse;
    getTypescriptLanguageService(): ts.LanguageService;
    /**
     * Provide Angular-specific inlay hints for templates.
     *
     * Returns hints for:
     * - @for loop variable types: `@for (user: User of users)`
     * - @if alias types: `@if (data; as result: ApiResult)`
     * - Event parameter types: `(click)="onClick($event: MouseEvent)"`
     * - Pipe output types
     * - @let declaration types
     *
     * @param fileName The file to get inlay hints for
     * @param span The text span to get hints within
     * @param config Optional configuration for which hints to show
     */
    getAngularInlayHints(fileName: string, span: ts.TextSpan, config?: InlayHintsConfig): AngularInlayHint[];
    /**
     * Gets document symbols for Angular templates, including control flow blocks,
     * elements, components, template references, and @let declarations.
     * Returns symbols in NavigationTree format for compatibility with TypeScript.
     *
     * @param fileName The file path to get template symbols for
     * @param options Optional configuration for document symbols behavior
     */
    getTemplateDocumentSymbols(fileName: string, options?: DocumentSymbolsOptions): TemplateDocumentSymbol[];
    applyRefactoring(fileName: string, positionOrRange: number | ts.TextRange, refactorName: string, reportProgress: ApplyRefactoringProgressFn): Promise<ApplyRefactoringResult | undefined>;
    hasCodeFixesForErrorCode(errorCode: number): boolean;
    getTokenTypeFromClassification(classification: number): number | undefined;
    getTokenModifierFromClassification(classification: number): number;
}
export declare function isNgLanguageService(ls: ts.LanguageService | NgLanguageService): ls is NgLanguageService;