-
Notifications
You must be signed in to change notification settings - Fork 24.8k
/
api.ts
492 lines (430 loc) Β· 19.3 KB
/
api.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
/**
* @license
* Copyright Google Inc. 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.io/license
*/
import {GeneratedFile, ParseSourceSpan, Position} from '@angular/compiler';
import * as ts from 'typescript';
export const DEFAULT_ERROR_CODE = 100;
export const UNKNOWN_ERROR_CODE = 500;
export const SOURCE = 'angular' as 'angular';
export interface DiagnosticMessageChain {
messageText: string;
position?: Position;
next?: DiagnosticMessageChain[];
}
export interface Diagnostic {
messageText: string;
span?: ParseSourceSpan;
position?: Position;
chain?: DiagnosticMessageChain;
category: ts.DiagnosticCategory;
code: number;
source: 'angular';
}
export function isTsDiagnostic(diagnostic: any): diagnostic is ts.Diagnostic {
return diagnostic != null && diagnostic.source !== 'angular';
}
export function isNgDiagnostic(diagnostic: any): diagnostic is Diagnostic {
return diagnostic != null && diagnostic.source === 'angular';
}
export interface CompilerOptions extends ts.CompilerOptions {
// NOTE: These comments and aio/content/guides/aot-compiler.md should be kept in sync.
// Write statistics about compilation (e.g. total time, ...)
// Note: this is the --diagnostics command line option from TS (which is @internal
// on ts.CompilerOptions interface).
diagnostics?: boolean;
// Absolute path to a directory where generated file structure is written.
// If unspecified, generated files will be written alongside sources.
// @deprecated - no effect
genDir?: string;
// Path to the directory containing the tsconfig.json file.
basePath?: string;
// Don't produce .metadata.json files (they don't work for bundled emit with --out)
skipMetadataEmit?: boolean;
// Produce an error if the metadata written for a class would produce an error if used.
strictMetadataEmit?: boolean;
// Don't produce .ngfactory.js or .ngstyle.js files
skipTemplateCodegen?: boolean;
// Always report errors when the type of a parameter supplied whose injection type cannot
// be determined. When this value option is not provided or is `false`, constructor
// parameters of classes marked with `@Injectable` whose type cannot be resolved will
// produce a warning. With this option `true`, they produce an error. When this option is
// not provided is treated as if it were `false`.
strictInjectionParameters?: boolean;
// Whether to generate a flat module index of the given name and the corresponding
// flat module metadata. This option is intended to be used when creating flat
// modules similar to how `@angular/core` and `@angular/common` are packaged.
// When this option is used the `package.json` for the library should referred to the
// generated flat module index instead of the library index file. When using this
// option only one .metadata.json file is produced that contains all the metadata
// necessary for symbols exported from the library index.
// In the generated .ngfactory.ts files flat module index is used to import symbols
// includes both the public API from the library index as well as shrowded internal
// symbols.
// By default the .ts file supplied in the `files` files field is assumed to be
// library index. If more than one is specified, uses `libraryIndex` to select the
// file to use. If more than on .ts file is supplied and no `libraryIndex` is supplied
// an error is produced.
// A flat module index .d.ts and .js will be created with the given `flatModuleOutFile`
// name in the same location as the library index .d.ts file is emitted.
// For example, if a library uses `public_api.ts` file as the library index of the
// module the `tsconfig.json` `files` field would be `["public_api.ts"]`. The
// `flatModuleOutFile` options could then be set to, for example `"index.js"`, which
// produces `index.d.ts` and `index.metadata.json` files. The library's
// `package.json`'s `module` field would be `"index.js"` and the `typings` field would
// be `"index.d.ts"`.
flatModuleOutFile?: string;
// Preferred module id to use for importing flat module. References generated by `ngc`
// will use this module name when importing symbols from the flat module. This is only
// meaningful when `flatModuleOutFile` is also supplied. It is otherwise ignored.
flatModuleId?: string;
// A prefix to insert in generated private symbols, e.g. for "my_prefix_" we
// would generate private symbols named like `Ι΅my_prefix_a`.
flatModulePrivateSymbolPrefix?: string;
// Whether to generate code for library code.
// If true, produce .ngfactory.ts and .ngstyle.ts files for .d.ts inputs.
// Default is true.
generateCodeForLibraries?: boolean;
// Whether to enable all type checks for templates.
// This will be true be default in Angular 6.
fullTemplateTypeCheck?: boolean;
// Whether to use the CompilerHost's fileNameToModuleName utility (if available) to generate
// import module specifiers. This is false by default, and exists to support running ngtsc
// within Google. This option is internal and is used by the ng_module.bzl rule to switch
// behavior between Bazel and Blaze.
_useHostForImportGeneration?: boolean;
// Insert JSDoc type annotations needed by Closure Compiler
annotateForClosureCompiler?: boolean;
// Modify how angular annotations are emitted to improve tree-shaking.
// Default is static fields.
// decorators: Leave the Decorators in-place. This makes compilation faster.
// TypeScript will emit calls to the __decorate helper.
// `--emitDecoratorMetadata` can be used for runtime reflection.
// However, the resulting code will not properly tree-shake.
// static fields: Replace decorators with a static field in the class.
// Allows advanced tree-shakers like Closure Compiler to remove
// unused classes.
annotationsAs?: 'decorators'|'static fields';
// Print extra information while running the compiler
trace?: boolean;
// Whether to enable lowering expressions lambdas and expressions in a reference value
// position.
disableExpressionLowering?: boolean;
// Disable TypeScript Version Check.
disableTypeScriptVersionCheck?: boolean;
// Locale of the application
i18nOutLocale?: string;
// Export format (xlf, xlf2 or xmb)
i18nOutFormat?: string;
// Path to the extracted message file
i18nOutFile?: string;
// Import format if different from `i18nFormat`
i18nInFormat?: string;
// Locale of the imported translations
i18nInLocale?: string;
// Path to the translation file
i18nInFile?: string;
// How to handle missing messages
i18nInMissingTranslations?: 'error'|'warning'|'ignore';
// Whether translation variable name should contain external message id
// (used by Closure Compiler's output of `goog.getMsg` for transition period)
i18nUseExternalIds?: boolean;
/**
* Render `$localize` message ids with the legacy format (xlf, xlf2 or xmb) specified in
* `i18nInFormat`.
*
* This is only active if we are building with `enableIvy: true` and a valid
* `i18nInFormat` has been provided. The default value for now is `true`.
*
* Use this option when use are using the `$localize` based localization messages but
* have not migrated the translation files to use the new `$localize` message id format.
*/
enableI18nLegacyMessageIdFormat?: boolean;
// Whether to remove blank text nodes from compiled templates. It is `false` by default starting
// from Angular 6.
preserveWhitespaces?: boolean;
/** generate all possible generated files */
allowEmptyCodegenFiles?: boolean;
/**
* Whether to generate .ngsummary.ts files that allow to use AOTed artifacts
* in JIT mode. This is off by default.
*/
enableSummariesForJit?: boolean;
/**
* Whether to replace the `templateUrl` and `styleUrls` property in all
* @Component decorators with inlined contents in `template` and `styles`
* properties.
* When enabled, the .js output of ngc will have no lazy-loaded `templateUrl`
* or `styleUrl`s. Note that this requires that resources be available to
* load statically at compile-time.
*/
enableResourceInlining?: boolean;
/**
* Controls whether ngtsc will emit `.ngfactory.js` shims for each compiled `.ts` file.
*
* These shims support legacy imports from `ngfactory` files, by exporting a factory shim
* for each component or NgModule in the original `.ts` file.
*/
generateNgFactoryShims?: boolean;
/**
* Controls whether ngtsc will emit `.ngsummary.js` shims for each compiled `.ts` file.
*
* These shims support legacy imports from `ngsummary` files, by exporting an empty object
* for each NgModule in the original `.ts` file. The only purpose of summaries is to feed them to
* `TestBed`, which is a no-op in Ivy.
*/
generateNgSummaryShims?: boolean;
/**
* Tells the compiler to generate definitions using the Render3 style code generation.
* This option defaults to `true`.
*
* Acceptable values are as follows:
*
* `false` - run ngc normally
* `true` - run the ngtsc compiler instead of the normal ngc compiler
* `ngtsc` - alias for `true`
*
* @publicApi
*/
enableIvy?: boolean|'ngtsc';
/** @internal */
collectAllErrors?: boolean;
/** An option to enable ngtsc's internal performance tracing.
*
* This should be a path to a JSON file where trace information will be written. An optional 'ts:'
* prefix will cause the trace to be written via the TS host instead of directly to the filesystem
* (not all hosts support this mode of operation).
*
* This is currently not exposed to users as the trace format is still unstable.
*
* @internal */
tracePerformance?: string;
/**
* Whether NGC should generate re-exports for external symbols which are referenced
* in Angular metadata (e.g. @Component, @Inject, @ViewChild). This can be enabled in
* order to avoid dynamically generated module dependencies which can break strict
* dependency enforcements. This is not enabled by default.
* Read more about this here: https://github.com/angular/angular/issues/25644.
*/
createExternalSymbolFactoryReexports?: boolean;
/**
* Turn on template type-checking in the Ivy compiler.
*
* This is an internal flag being used to roll out template type-checking in ngtsc. Turning it on
* by default before it's ready might break other users attempting to test the new compiler's
* behavior.
*
* @internal
*/
ivyTemplateTypeCheck?: boolean;
/**
* Enables the generation of alias re-exports of directives/pipes that are visible from an
* NgModule from that NgModule's file.
*
* This option should be disabled for application builds or for Angular Package Format libraries
* (where NgModules along with their directives/pipes are exported via a single entrypoint).
*
* For other library compilations which are intended to be path-mapped into an application build
* (or another library), enabling this option enables the resulting deep imports to work
* correctly.
*
* A consumer of such a path-mapped library will write an import like:
*
* ```typescript
* import {LibModule} from 'lib/deep/path/to/module';
* ```
*
* The compiler will attempt to generate imports of directives/pipes from that same module
* specifier (the compiler does not rewrite the user's given import path, unlike View Engine).
*
* ```typescript
* import {LibDir, LibCmp, LibPipe} from 'lib/deep/path/to/module';
* ```
*
* It would be burdensome for users to have to re-export all directives/pipes alongside each
* NgModule to support this import model. Enabling this option tells the compiler to generate
* private re-exports alongside the NgModule of all the directives/pipes it makes available, to
* support these future imports.
*/
generateDeepReexports?: boolean;
}
export interface CompilerHost extends ts.CompilerHost {
/**
* Converts a module name that is used in an `import` to a file path.
* I.e. `path/to/containingFile.ts` containing `import {...} from 'module-name'`.
*/
moduleNameToFileName?(moduleName: string, containingFile: string): string|null;
/**
* Converts a file path to a module name that can be used as an `import ...`
* I.e. `path/to/importedFile.ts` should be imported by `path/to/containingFile.ts`.
*/
fileNameToModuleName?(importedFilePath: string, containingFilePath: string): string;
/**
* Converts a file path for a resource that is used in a source file or another resource
* into a filepath.
*/
resourceNameToFileName?(resourceName: string, containingFilePath: string): string|null;
/**
* Converts a file name into a representation that should be stored in a summary file.
* This has to include changing the suffix as well.
* E.g.
* `some_file.ts` -> `some_file.d.ts`
*
* @param referringSrcFileName the soure file that refers to fileName
*/
toSummaryFileName?(fileName: string, referringSrcFileName: string): string;
/**
* Converts a fileName that was processed by `toSummaryFileName` back into a real fileName
* given the fileName of the library that is referrig to it.
*/
fromSummaryFileName?(fileName: string, referringLibFileName: string): string;
/**
* Load a referenced resource either statically or asynchronously. If the host returns a
* `Promise<string>` it is assumed the user of the corresponding `Program` will call
* `loadNgStructureAsync()`. Returning `Promise<string>` outside `loadNgStructureAsync()` will
* cause a diagnostics diagnostic error or an exception to be thrown.
*/
readResource?(fileName: string): Promise<string>|string;
/**
* Produce an AMD module name for the source file. Used in Bazel.
*
* An AMD module can have an arbitrary name, so that it is require'd by name
* rather than by path. See http://requirejs.org/docs/whyamd.html#namedmodules
*/
amdModuleName?(sf: ts.SourceFile): string|undefined;
/**
* Get the absolute paths to the changed files that triggered the current compilation
* or `undefined` if this is not an incremental build.
*/
getModifiedResourceFiles?(): Set<string>|undefined;
}
export enum EmitFlags {
DTS = 1 << 0,
JS = 1 << 1,
Metadata = 1 << 2,
I18nBundle = 1 << 3,
Codegen = 1 << 4,
Default = DTS | JS | Codegen,
All = DTS | JS | Metadata | I18nBundle | Codegen,
}
export interface CustomTransformers {
beforeTs?: ts.TransformerFactory<ts.SourceFile>[];
afterTs?: ts.TransformerFactory<ts.SourceFile>[];
}
export interface TsEmitArguments {
program: ts.Program;
host: CompilerHost;
options: CompilerOptions;
targetSourceFile?: ts.SourceFile;
writeFile?: ts.WriteFileCallback;
cancellationToken?: ts.CancellationToken;
emitOnlyDtsFiles?: boolean;
customTransformers?: ts.CustomTransformers;
}
export interface TsEmitCallback { (args: TsEmitArguments): ts.EmitResult; }
export interface TsMergeEmitResultsCallback { (results: ts.EmitResult[]): ts.EmitResult; }
export interface LibrarySummary {
fileName: string;
text: string;
sourceFile?: ts.SourceFile;
}
export interface LazyRoute {
route: string;
module: {name: string, filePath: string};
referencedModule: {name: string, filePath: string};
}
export interface Program {
/**
* Retrieve the TypeScript program used to produce semantic diagnostics and emit the sources.
*
* Angular structural information is required to produce the program.
*/
getTsProgram(): ts.Program;
/**
* Retrieve options diagnostics for the TypeScript options used to create the program. This is
* faster than calling `getTsProgram().getOptionsDiagnostics()` since it does not need to
* collect Angular structural information to produce the errors.
*/
getTsOptionDiagnostics(cancellationToken?: ts.CancellationToken): ReadonlyArray<ts.Diagnostic>;
/**
* Retrieve options diagnostics for the Angular options used to create the program.
*/
getNgOptionDiagnostics(cancellationToken?: ts.CancellationToken):
ReadonlyArray<ts.Diagnostic|Diagnostic>;
/**
* Retrieve the syntax diagnostics from TypeScript. This is faster than calling
* `getTsProgram().getSyntacticDiagnostics()` since it does not need to collect Angular structural
* information to produce the errors.
*/
getTsSyntacticDiagnostics(sourceFile?: ts.SourceFile, cancellationToken?: ts.CancellationToken):
ReadonlyArray<ts.Diagnostic>;
/**
* Retrieve the diagnostics for the structure of an Angular application is correctly formed.
* This includes validating Angular annotations and the syntax of referenced and imbedded HTML
* and CSS.
*
* Note it is important to displaying TypeScript semantic diagnostics along with Angular
* structural diagnostics as an error in the program structure might cause errors detected in
* semantic analysis and a semantic error might cause errors in specifying the program structure.
*
* Angular structural information is required to produce these diagnostics.
*/
getNgStructuralDiagnostics(cancellationToken?: ts.CancellationToken): ReadonlyArray<Diagnostic>;
/**
* Retrieve the semantic diagnostics from TypeScript. This is equivalent to calling
* `getTsProgram().getSemanticDiagnostics()` directly and is included for completeness.
*/
getTsSemanticDiagnostics(sourceFile?: ts.SourceFile, cancellationToken?: ts.CancellationToken):
ReadonlyArray<ts.Diagnostic>;
/**
* Retrieve the Angular semantic diagnostics.
*
* Angular structural information is required to produce these diagnostics.
*/
getNgSemanticDiagnostics(fileName?: string, cancellationToken?: ts.CancellationToken):
ReadonlyArray<ts.Diagnostic|Diagnostic>;
/**
* Load Angular structural information asynchronously. If this method is not called then the
* Angular structural information, including referenced HTML and CSS files, are loaded
* synchronously. If the supplied Angular compiler host returns a promise from `loadResource()`
* will produce a diagnostic error message or, `getTsProgram()` or `emit` to throw.
*/
loadNgStructureAsync(): Promise<void>;
/**
* Returns the lazy routes in the program.
* @param entryRoute A reference to an NgModule like `someModule#name`. If given,
* will recursively analyze routes starting from this symbol only.
* Otherwise will list all routes for all NgModules in the program/
*/
listLazyRoutes(entryRoute?: string): LazyRoute[];
/**
* Emit the files requested by emitFlags implied by the program.
*
* Angular structural information is required to emit files.
*/
emit({emitFlags, cancellationToken, customTransformers, emitCallback,
mergeEmitResultsCallback}?: {
emitFlags?: EmitFlags,
cancellationToken?: ts.CancellationToken,
customTransformers?: CustomTransformers,
emitCallback?: TsEmitCallback,
mergeEmitResultsCallback?: TsMergeEmitResultsCallback
}): ts.EmitResult;
/**
* Returns the .d.ts / .ngsummary.json / .ngfactory.d.ts files of libraries that have been emitted
* in this program or previous programs with paths that emulate the fact that these libraries
* have been compiled before with no outDir.
*/
getLibrarySummaries(): Map<string, LibrarySummary>;
/**
* @internal
*/
getEmittedGeneratedFiles(): Map<string, GeneratedFile>;
/**
* @internal
*/
getEmittedSourceFiles(): Map<string, ts.SourceFile>;
}