1 | /**
|
2 | * @license
|
3 | * Copyright Google LLC All Rights Reserved.
|
4 | *
|
5 | * Use of this source code is governed by an MIT-style license that can be
|
6 | * found in the LICENSE file at https://angular.io/license
|
7 | */
|
8 | /// <amd-module name="@angular/compiler-cli/src/ngtsc/typecheck/api/api" />
|
9 | import { AbsoluteSourceSpan, BoundTarget, DirectiveMeta, ParseSourceSpan, SchemaMetadata } from '@angular/compiler';
|
10 | import ts from 'typescript';
|
11 | import { ErrorCode } from '../../diagnostics';
|
12 | import { Reference } from '../../imports';
|
13 | import { ClassPropertyMapping, DirectiveTypeCheckMeta } from '../../metadata';
|
14 | import { ClassDeclaration } from '../../reflection';
|
15 | /**
|
16 | * Extension of `DirectiveMeta` that includes additional information required to type-check the
|
17 | * usage of a particular directive.
|
18 | */
|
19 | export interface TypeCheckableDirectiveMeta extends DirectiveMeta, DirectiveTypeCheckMeta {
|
20 | ref: Reference<ClassDeclaration>;
|
21 | queries: string[];
|
22 | inputs: ClassPropertyMapping;
|
23 | outputs: ClassPropertyMapping;
|
24 | isStandalone: boolean;
|
25 | }
|
26 | export declare type TemplateId = string & {
|
27 | __brand: 'TemplateId';
|
28 | };
|
29 | /**
|
30 | * A `ts.Diagnostic` with additional information about the diagnostic related to template
|
31 | * type-checking.
|
32 | */
|
33 | export interface TemplateDiagnostic extends ts.Diagnostic {
|
34 | /**
|
35 | * The component with the template that resulted in this diagnostic.
|
36 | */
|
37 | componentFile: ts.SourceFile;
|
38 | /**
|
39 | * The template id of the component that resulted in this diagnostic.
|
40 | */
|
41 | templateId: TemplateId;
|
42 | }
|
43 | /**
|
44 | * A `TemplateDiagnostic` with a specific error code.
|
45 | */
|
46 | export declare type NgTemplateDiagnostic<T extends ErrorCode> = TemplateDiagnostic & {
|
47 | __ngCode: T;
|
48 | };
|
49 | /**
|
50 | * Metadata required in addition to a component class in order to generate a type check block (TCB)
|
51 | * for that component.
|
52 | */
|
53 | export interface TypeCheckBlockMetadata {
|
54 | /**
|
55 | * A unique identifier for the class which gave rise to this TCB.
|
56 | *
|
57 | * This can be used to map errors back to the `ts.ClassDeclaration` for the component.
|
58 | */
|
59 | id: TemplateId;
|
60 | /**
|
61 | * Semantic information about the template of the component.
|
62 | */
|
63 | boundTarget: BoundTarget<TypeCheckableDirectiveMeta>;
|
64 | pipes: Map<string, Reference<ClassDeclaration<ts.ClassDeclaration>>>;
|
65 | /**
|
66 | * Schemas that apply to this template.
|
67 | */
|
68 | schemas: SchemaMetadata[];
|
69 | isStandalone: boolean;
|
70 | }
|
71 | export interface TypeCtorMetadata {
|
72 | /**
|
73 | * The name of the requested type constructor function.
|
74 | */
|
75 | fnName: string;
|
76 | /**
|
77 | * Whether to generate a body for the function or not.
|
78 | */
|
79 | body: boolean;
|
80 | /**
|
81 | * Input, output, and query field names in the type which should be included as constructor input.
|
82 | */
|
83 | fields: {
|
84 | inputs: string[];
|
85 | outputs: string[];
|
86 | queries: string[];
|
87 | };
|
88 | /**
|
89 | * `Set` of field names which have type coercion enabled.
|
90 | */
|
91 | coercedInputFields: Set<string>;
|
92 | }
|
93 | export interface TypeCheckingConfig {
|
94 | /**
|
95 | * Whether to check the left-hand side type of binding operations.
|
96 | *
|
97 | * For example, if this is `false` then the expression `[input]="expr"` will have `expr` type-
|
98 | * checked, but not the assignment of the resulting type to the `input` property of whichever
|
99 | * directive or component is receiving the binding. If set to `true`, both sides of the assignment
|
100 | * are checked.
|
101 | *
|
102 | * This flag only affects bindings to components/directives. Bindings to the DOM are checked if
|
103 | * `checkTypeOfDomBindings` is set.
|
104 | */
|
105 | checkTypeOfInputBindings: boolean;
|
106 | /**
|
107 | * Whether to honor the access modifiers on input bindings for the component/directive.
|
108 | *
|
109 | * If a template binding attempts to assign to an input that is private/protected/readonly,
|
110 | * this will produce errors when enabled but will not when disabled.
|
111 | */
|
112 | honorAccessModifiersForInputBindings: boolean;
|
113 | /**
|
114 | * Whether to use strict null types for input bindings for directives.
|
115 | *
|
116 | * If this is `true`, applications that are compiled with TypeScript's `strictNullChecks` enabled
|
117 | * will produce type errors for bindings which can evaluate to `undefined` or `null` where the
|
118 | * inputs's type does not include `undefined` or `null` in its type. If set to `false`, all
|
119 | * binding expressions are wrapped in a non-null assertion operator to effectively disable strict
|
120 | * null checks. This may be particularly useful when the directive is from a library that is not
|
121 | * compiled with `strictNullChecks` enabled.
|
122 | *
|
123 | * If `checkTypeOfInputBindings` is set to `false`, this flag has no effect.
|
124 | */
|
125 | strictNullInputBindings: boolean;
|
126 | /**
|
127 | * Whether to check text attributes that happen to be consumed by a directive or component.
|
128 | *
|
129 | * For example, in a template containing `<input matInput disabled>` the `disabled` attribute ends
|
130 | * up being consumed as an input with type `boolean` by the `matInput` directive. At runtime, the
|
131 | * input will be set to the attribute's string value, which is an empty string for attributes
|
132 | * without a value, so with this flag set to `true`, an error would be reported. If set to
|
133 | * `false`, text attributes will never report an error.
|
134 | *
|
135 | * Note that if `checkTypeOfInputBindings` is set to `false`, this flag has no effect.
|
136 | */
|
137 | checkTypeOfAttributes: boolean;
|
138 | /**
|
139 | * Whether to check the left-hand side type of binding operations to DOM properties.
|
140 | *
|
141 | * As `checkTypeOfBindings`, but only applies to bindings to DOM properties.
|
142 | *
|
143 | * This does not affect the use of the `DomSchemaChecker` to validate the template against the DOM
|
144 | * schema. Rather, this flag is an experimental, not yet complete feature which uses the
|
145 | * lib.dom.d.ts DOM typings in TypeScript to validate that DOM bindings are of the correct type
|
146 | * for assignability to the underlying DOM element properties.
|
147 | */
|
148 | checkTypeOfDomBindings: boolean;
|
149 | /**
|
150 | * Whether to infer the type of the `$event` variable in event bindings for directive outputs or
|
151 | * animation events.
|
152 | *
|
153 | * If this is `true`, the type of `$event` will be inferred based on the generic type of
|
154 | * `EventEmitter`/`Subject` of the output. If set to `false`, the `$event` variable will be of
|
155 | * type `any`.
|
156 | */
|
157 | checkTypeOfOutputEvents: boolean;
|
158 | /**
|
159 | * Whether to infer the type of the `$event` variable in event bindings for animations.
|
160 | *
|
161 | * If this is `true`, the type of `$event` will be `AnimationEvent` from `@angular/animations`.
|
162 | * If set to `false`, the `$event` variable will be of type `any`.
|
163 | */
|
164 | checkTypeOfAnimationEvents: boolean;
|
165 | /**
|
166 | * Whether to infer the type of the `$event` variable in event bindings to DOM events.
|
167 | *
|
168 | * If this is `true`, the type of `$event` will be inferred based on TypeScript's
|
169 | * `HTMLElementEventMap`, with a fallback to the native `Event` type. If set to `false`, the
|
170 | * `$event` variable will be of type `any`.
|
171 | */
|
172 | checkTypeOfDomEvents: boolean;
|
173 | /**
|
174 | * Whether to infer the type of local references to DOM elements.
|
175 | *
|
176 | * If this is `true`, the type of a `#ref` variable on a DOM node in the template will be
|
177 | * determined by the type of `document.createElement` for the given DOM node type. If set to
|
178 | * `false`, the type of `ref` for DOM nodes will be `any`.
|
179 | */
|
180 | checkTypeOfDomReferences: boolean;
|
181 | /**
|
182 | * Whether to infer the type of local references.
|
183 | *
|
184 | * If this is `true`, the type of a `#ref` variable that points to a directive or `TemplateRef` in
|
185 | * the template will be inferred correctly. If set to `false`, the type of `ref` for will be
|
186 | * `any`.
|
187 | */
|
188 | checkTypeOfNonDomReferences: boolean;
|
189 | /**
|
190 | * Whether to adjust the output of the TCB to ensure compatibility with the `TemplateTypeChecker`.
|
191 | *
|
192 | * The statements generated in the TCB are optimized for performance and producing diagnostics.
|
193 | * These optimizations can result in generating a TCB that does not have all the information
|
194 | * needed by the `TemplateTypeChecker` for retrieving `Symbol`s. For example, as an optimization,
|
195 | * the TCB will not generate variable declaration statements for directives that have no
|
196 | * references, inputs, or outputs. However, the `TemplateTypeChecker` always needs these
|
197 | * statements to be present in order to provide `ts.Symbol`s and `ts.Type`s for the directives.
|
198 | *
|
199 | * When set to `false`, enables TCB optimizations for template diagnostics.
|
200 | * When set to `true`, ensures all information required by `TemplateTypeChecker` to
|
201 | * retrieve symbols for template nodes is available in the TCB.
|
202 | */
|
203 | enableTemplateTypeChecker: boolean;
|
204 | /**
|
205 | * Whether to include type information from pipes in the type-checking operation.
|
206 | *
|
207 | * If this is `true`, then the pipe's type signature for `transform()` will be used to check the
|
208 | * usage of the pipe. If this is `false`, then the result of applying a pipe will be `any`, and
|
209 | * the types of the pipe's value and arguments will not be matched against the `transform()`
|
210 | * method.
|
211 | */
|
212 | checkTypeOfPipes: boolean;
|
213 | /**
|
214 | * Whether to narrow the types of template contexts.
|
215 | */
|
216 | applyTemplateContextGuards: boolean;
|
217 | /**
|
218 | * Whether to use a strict type for null-safe navigation operations.
|
219 | *
|
220 | * If this is `false`, then the return type of `a?.b` or `a?()` will be `any`. If set to `true`,
|
221 | * then the return type of `a?.b` for example will be the same as the type of the ternary
|
222 | * expression `a != null ? a.b : a`.
|
223 | */
|
224 | strictSafeNavigationTypes: boolean;
|
225 | /**
|
226 | * Whether to descend into template bodies and check any bindings there.
|
227 | */
|
228 | checkTemplateBodies: boolean;
|
229 | /**
|
230 | * Whether to always apply DOM schema checks in template bodies, independently of the
|
231 | * `checkTemplateBodies` setting.
|
232 | */
|
233 | alwaysCheckSchemaInTemplateBodies: boolean;
|
234 | /**
|
235 | * Whether to check resolvable queries.
|
236 | *
|
237 | * This is currently an unsupported feature.
|
238 | */
|
239 | checkQueries: false;
|
240 | /**
|
241 | * Whether to use any generic types of the context component.
|
242 | *
|
243 | * If this is `true`, then if the context component has generic types, those will be mirrored in
|
244 | * the template type-checking context. If `false`, any generic type parameters of the context
|
245 | * component will be set to `any` during type-checking.
|
246 | */
|
247 | useContextGenericType: boolean;
|
248 | /**
|
249 | * Whether or not to infer types for object and array literals in the template.
|
250 | *
|
251 | * If this is `true`, then the type of an object or an array literal in the template will be the
|
252 | * same type that TypeScript would infer if the literal appeared in code. If `false`, then such
|
253 | * literals are cast to `any` when declared.
|
254 | */
|
255 | strictLiteralTypes: boolean;
|
256 | /**
|
257 | * Whether to use inline type constructors.
|
258 | *
|
259 | * If this is `true`, create inline type constructors when required. For example, if a type
|
260 | * constructor's parameters has private types, it cannot be created normally, so we inline it in
|
261 | * the directives definition file.
|
262 | *
|
263 | * If false, do not create inline type constructors. Fall back to using `any` type for
|
264 | * constructors that normally require inlining.
|
265 | *
|
266 | * This option requires the environment to support inlining. If the environment does not support
|
267 | * inlining, this must be set to `false`.
|
268 | */
|
269 | useInlineTypeConstructors: boolean;
|
270 | /**
|
271 | * Whether or not to produce diagnostic suggestions in cases where the compiler could have
|
272 | * inferred a better type for a construct, but was prevented from doing so by the current type
|
273 | * checking configuration.
|
274 | *
|
275 | * For example, if the compiler could have used a template context guard to infer a better type
|
276 | * for a structural directive's context and `let-` variables, but the user is in
|
277 | * `fullTemplateTypeCheck` mode and such guards are therefore disabled.
|
278 | *
|
279 | * This mode is useful for clients like the Language Service which want to inform users of
|
280 | * opportunities to improve their own developer experience.
|
281 | */
|
282 | suggestionsForSuboptimalTypeInference: boolean;
|
283 | }
|
284 | export declare type TemplateSourceMapping = DirectTemplateSourceMapping | IndirectTemplateSourceMapping | ExternalTemplateSourceMapping;
|
285 | /**
|
286 | * A mapping to an inline template in a TS file.
|
287 | *
|
288 | * `ParseSourceSpan`s for this template should be accurate for direct reporting in a TS error
|
289 | * message.
|
290 | */
|
291 | export interface DirectTemplateSourceMapping {
|
292 | type: 'direct';
|
293 | node: ts.StringLiteral | ts.NoSubstitutionTemplateLiteral;
|
294 | }
|
295 | /**
|
296 | * A mapping to a template which is still in a TS file, but where the node positions in any
|
297 | * `ParseSourceSpan`s are not accurate for one reason or another.
|
298 | *
|
299 | * This can occur if the template expression was interpolated in a way where the compiler could not
|
300 | * construct a contiguous mapping for the template string. The `node` refers to the `template`
|
301 | * expression.
|
302 | */
|
303 | export interface IndirectTemplateSourceMapping {
|
304 | type: 'indirect';
|
305 | componentClass: ClassDeclaration;
|
306 | node: ts.Expression;
|
307 | template: string;
|
308 | }
|
309 | /**
|
310 | * A mapping to a template declared in an external HTML file, where node positions in
|
311 | * `ParseSourceSpan`s represent accurate offsets into the external file.
|
312 | *
|
313 | * In this case, the given `node` refers to the `templateUrl` expression.
|
314 | */
|
315 | export interface ExternalTemplateSourceMapping {
|
316 | type: 'external';
|
317 | componentClass: ClassDeclaration;
|
318 | node: ts.Expression;
|
319 | template: string;
|
320 | templateUrl: string;
|
321 | }
|
322 | /**
|
323 | * A mapping of a TCB template id to a span in the corresponding template source.
|
324 | */
|
325 | export interface SourceLocation {
|
326 | id: TemplateId;
|
327 | span: AbsoluteSourceSpan;
|
328 | }
|
329 | /**
|
330 | * A representation of all a node's template mapping information we know. Useful for producing
|
331 | * diagnostics based on a TCB node or generally mapping from a TCB node back to a template location.
|
332 | */
|
333 | export interface FullTemplateMapping {
|
334 | sourceLocation: SourceLocation;
|
335 | templateSourceMapping: TemplateSourceMapping;
|
336 | span: ParseSourceSpan;
|
337 | }
|