1 | /**
|
2 | * @license
|
3 | * Copyright Google Inc. 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 | /**
|
9 | * @fileoverview Externs creates Closure Compiler #externs definitions from the
|
10 | * ambient declarations in a TypeScript file.
|
11 | *
|
12 | * (Note that we cannot write the "@" form of the externs tag, even in comments,
|
13 | * because the compiler greps for it in source files(!). So we write #externs
|
14 | * instead.)
|
15 | *
|
16 | * For example, a
|
17 | * declare interface Foo { bar: string; }
|
18 | *
|
19 | * Would generate a
|
20 | * /.. #externs ./
|
21 | * /.. @record ./
|
22 | * var Foo = function() {};
|
23 | * /.. @type {string} ./
|
24 | * Foo.prototype.bar;
|
25 | *
|
26 | * The generated externs indicate to Closure Compiler that symbols are external
|
27 | * to the optimization process, i.e. they are provided by outside code. That
|
28 | * most importantly means they must not be renamed or removed.
|
29 | *
|
30 | * A major difficulty here is that TypeScript supports module-scoped external
|
31 | * symbols; `.d.ts` files can contain `export`s and `import` other files.
|
32 | * Closure Compiler does not have such a concept, so tsickle must emulate the
|
33 | * behaviour. It does so by following this scheme:
|
34 | *
|
35 | * 1. non-module .d.ts produces global symbols
|
36 | * 2. module .d.ts produce symbols namespaced to the module, by creating a
|
37 | * mangled name matching the current file's path. tsickle expects outside
|
38 | * code (e.g. build system integration or manually written code) to contain a
|
39 | * goog.module/provide that references the mangled path.
|
40 | * 3. declarations in `.ts` files produce types that can be separately emitted
|
41 | * in e.g. an `externs.js`, using `getGeneratedExterns` below.
|
42 | * 1. non-exported symbols produce global types, because that's what users
|
43 | * expect and it matches TypeScripts emit, which just references `Foo` for
|
44 | * a locally declared symbol `Foo` in a module. Arguably these should be
|
45 | * wrapped in `declare global { ... }`.
|
46 | * 2. exported symbols are scoped to the `.ts` file by prefixing them with a
|
47 | * mangled name. Exported types are re-exported from the JavaScript
|
48 | * `goog.module`, allowing downstream code to reference them. This has the
|
49 | * same problem regarding ambient values as above, it is unclear where the
|
50 | * value symbol would be defined, so for the time being this is
|
51 | * unsupported.
|
52 | *
|
53 | * The effect of this is that:
|
54 | * - symbols in a module (i.e. not globals) are generally scoped to the local
|
55 | * module using a mangled name, preventing symbol collisions on the Closure
|
56 | * side.
|
57 | * - importing code can unconditionally refer to and import any symbol defined
|
58 | * in a module `X` as `path.to.module.X`, regardless of whether the defining
|
59 | * location is a `.d.ts` file or a `.ts` file, and regardless whether the
|
60 | * symbol is ambient (assuming there's an appropriate shim).
|
61 | * - if there is a shim present, tsickle avoids emitting the Closure namespace
|
62 | * itself, expecting the shim to provide the namespace and initialize it to a
|
63 | * symbol that provides the right value at runtime (i.e. the implementation of
|
64 | * whatever third party library the .d.ts describes).
|
65 | */
|
66 | import * as ts from 'typescript';
|
67 | import { AnnotatorHost } from './annotator_host';
|
68 | /**
|
69 | * Concatenate all generated externs definitions together into a string,
|
70 | * including a file comment header.
|
71 | *
|
72 | * @param rootDir Project root. Emitted comments will reference paths relative
|
73 | * to this root.
|
74 | */
|
75 | export declare function getGeneratedExterns(externs: {
|
76 | [fileName: string]: string;
|
77 | }, rootDir: string): string;
|
78 | /**
|
79 | * generateExterns generates extern definitions for all ambient declarations in the given source
|
80 | * file. It returns a string representation of the Closure JavaScript, not including the initial
|
81 | * comment with \@fileoverview and #externs (see above for that).
|
82 | */
|
83 | export declare function generateExterns(typeChecker: ts.TypeChecker, sourceFile: ts.SourceFile, host: AnnotatorHost, moduleResolutionHost: ts.ModuleResolutionHost, options: ts.CompilerOptions): {
|
84 | output: string;
|
85 | diagnostics: ts.Diagnostic[];
|
86 | };
|