You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: GLOSSARY.md
+68-46
Original file line number
Diff line number
Diff line change
@@ -1,58 +1,58 @@
1
1
### Terminology from inside the codebase
2
2
3
-
***Core TypeScript Compiler**
3
+
-**Core TypeScript Compiler**
4
4
5
-
***Parser:** Starting from a set of sources, and following the productions of the language grammar, to generate an Abstract Syntax Tree (AST). Also: [see Parser](https://basarat.gitbooks.io/typescript/docs/compiler/parser.html),
5
+
-**Parser:** Starting from a set of sources, and following the productions of the language grammar, to generate an Abstract Syntax Tree (AST). Also: [see Parser](https://basarat.gitbooks.io/typescript/docs/compiler/parser.html),
6
6
7
-
***Binder:** Linking declarations contributing to the same structure using a Symbol (e.g. different declarations of the same interface or module, or a function and a module with the same name). This allows the type system to reason about these named declarations. [See Binder](https://basarat.gitbooks.io/typescript/docs/compiler/binder.html)
8
-
***Type resolver/ Checker:** Resolving types of each construct, checking semantic operations and generate diagnostics as appropriate. [See Checker](https://basarat.gitbooks.io/typescript/docs/compiler/checker.html)
7
+
-**Binder:** Linking declarations contributing to the same structure using a Symbol (e.g. different declarations of the same interface or module, or a function and a module with the same name). This allows the type system to reason about these named declarations. [See Binder](https://basarat.gitbooks.io/typescript/docs/compiler/binder.html)
8
+
-**Type resolver/ Checker:** Resolving types of each construct, checking semantic operations and generate diagnostics as appropriate. [See Checker](https://basarat.gitbooks.io/typescript/docs/compiler/checker.html)
9
9
10
-
***Emitter:** Output generated from a set of inputs (.ts and .d.ts) files can be one of: JavaScript (.js), definitions (.d.ts), or source maps (.js.map)
10
+
-**Emitter:** Output generated from a set of inputs (.ts and .d.ts) files can be one of: JavaScript (.js), definitions (.d.ts), or source maps (.js.map)
11
11
12
-
***Pre-processor:** The "Compilation Context" refers to all files involved in a "program". The context is created by inspecting all files passed in to the compiler on the command line, in order, and then adding any files they may reference directly or indirectly through `import` statements and `/// <reference path=... />` tags.
13
-
The result of walking the reference graph is an ordered list of source files, that constitute the program.
14
-
When resolving imports, preference is given to ".ts" files over ".d.ts" files to ensure the most up-to-date files are processed.
15
-
The compiler does a node-like process to resolve imports by walking up the directory chain to find a source file with a .ts or .d.ts extension matching the requested import.
16
-
Failed import resolution does not result in an error, as an ambient module could be already declared.
12
+
-**Pre-processor:** The "Compilation Context" refers to all files involved in a "program". The context is created by inspecting all files passed in to the compiler on the command line, in order, and then adding any files they may reference directly or indirectly through `import` statements and `/// <reference path=... />` tags.
13
+
The result of walking the reference graph is an ordered list of source files, that constitute the program.
14
+
When resolving imports, preference is given to ".ts" files over ".d.ts" files to ensure the most up-to-date files are processed.
15
+
The compiler does a node-like process to resolve imports by walking up the directory chain to find a source file with a .ts or .d.ts extension matching the requested import.
16
+
Failed import resolution does not result in an error, as an ambient module could be already declared.
17
17
18
-
***Standalone compiler (tsc):** The batch compilation CLI. Mainly handle reading and writing files for different supported engines (e.g. Node.js)
18
+
-**Standalone compiler (tsc):** The batch compilation CLI. Mainly handle reading and writing files for different supported engines (e.g. Node.js)
19
19
20
-
***Language Service:** The "Language Service" exposes an additional layer around the core compiler pipeline that are best suiting editor-like applications.
21
-
The language service supports the common set of a typical editor operations like statement completions, signature help, code formatting and outlining, colorization, etc... Basic re-factoring like rename, Debugging interface helpers like validating breakpoints as well as TypeScript-specific features like support of incremental compilation (--watch equivalent on the command-line). The language service is designed to efficiently handle scenarios with files changing over time within a long-lived compilation context; in that sense, the language service provides a slightly different perspective about working with programs and source files from that of the other compiler interfaces.
22
-
> Please refer to the [[Using the Language Service API]] page for more details.
20
+
-**Language Service:** The "Language Service" exposes an additional layer around the core compiler pipeline that are best suiting editor-like applications.
21
+
The language service supports the common set of a typical editor operations like statement completions, signature help, code formatting and outlining, colorization, etc... Basic re-factoring like rename, Debugging interface helpers like validating breakpoints as well as TypeScript-specific features like support of incremental compilation (--watch equivalent on the command-line). The language service is designed to efficiently handle scenarios with files changing over time within a long-lived compilation context; in that sense, the language service provides a slightly different perspective about working with programs and source files from that of the other compiler interfaces.
23
22
24
-
***Standalone Server (tsserver):** The `tsserver` wraps the compiler and services layer, and exposes them through a JSON protocol.
25
-
> Please refer to the [[Standalone Server (tsserver)]] for more details.
23
+
> Please refer to the [[Using the Language Service API]] page for more details.
24
+
25
+
-**Standalone Server (tsserver):** The `tsserver` wraps the compiler and services layer, and exposes them through a JSON protocol.
26
+
> Please refer to the [[Standalone Server (tsserver)]] for more details.
26
27
27
28
### Type stuff which can be see outside the compilers
28
29
29
-
* Node: The basic building block of the Abstract Syntax Tree (AST). In general node represent non-terminals in the language grammar; some terminals are kept in the tree such as identifiers and literals.
30
+
- Node: The basic building block of the Abstract Syntax Tree (AST). In general node represent non-terminals in the language grammar; some terminals are kept in the tree such as identifiers and literals.
30
31
31
-
* SourceFile: The AST of a given source file. A SourceFile is itself a Node; it provides an additional set of interfaces to access the raw text of the file, references in the file, the list of identifiers in the file, and mapping from a position in the file to a line and character numbers.
32
+
- SourceFile: The AST of a given source file. A SourceFile is itself a Node; it provides an additional set of interfaces to access the raw text of the file, references in the file, the list of identifiers in the file, and mapping from a position in the file to a line and character numbers.
32
33
33
-
* Program: A collection of SourceFiles and a set of compilation options that represent a compilation unit. The program is the main entry point to the type system and code generation.
34
+
- Program: A collection of SourceFiles and a set of compilation options that represent a compilation unit. The program is the main entry point to the type system and code generation.
34
35
35
-
* Symbol: A named declaration. Symbols are created as a result of binding. Symbols connect declaration nodes in the tree to other declarations contributing to the same entity. Symbols are the basic building block of the semantic system.
36
+
- Symbol: A named declaration. Symbols are created as a result of binding. Symbols connect declaration nodes in the tree to other declarations contributing to the same entity. Symbols are the basic building block of the semantic system.
36
37
37
-
*`Type`: Types are the other part of the semantic system. Types can be named (e.g. classes and interfaces), or anonymous (e.g. object types).
38
+
-`Type`: Types are the other part of the semantic system. Types can be named (e.g. classes and interfaces), or anonymous (e.g. object types).
38
39
39
-
* Signature``: There are three types of signatures in the language: call, construct and index signatures.
40
+
- Signature``: There are three types of signatures in the language: call, construct and index signatures.
40
41
41
-
-`Transient Symbol` - A symbol created in the checker, as opposed to in the binder
42
-
-`Freshness` - When a literal type is first created and not expanded by hitting a mutable location, see [Widening
42
+
*`Transient Symbol` - A symbol created in the checker, as opposed to in the binder
43
+
*`Freshness` - When a literal type is first created and not expanded by hitting a mutable location, see [Widening
43
44
and Narrowing in TypeScript][wnn].
44
45
45
-
-`Expando` - This is [the term](https://developer.mozilla.org/en-US/docs/Glossary/Expando) used to describe taking a JS object and adding new things to it which expands the type's shape
46
+
*`Expando` - This is [the term](https://developer.mozilla.org/en-US/docs/Glossary/Expando) used to describe taking a JS object and adding new things to it which expands the type's shape
46
47
47
48
```js
48
49
functiondoSomething() {}
49
-
doSomething.doSomethingElse= () => {}
50
+
doSomething.doSomethingElse= () => {};
50
51
```
51
-
52
-
In TS, this is only allowed for adding properties to functions. In JS, this is a normal pattern in old school code for all kinds of objects. TypeScript will augment the types for `doSomething` to add `doSomethingElse` in the type system in both.
53
52
53
+
In TS, this is only allowed for adding properties to functions. In JS, this is a normal pattern in old school code for all kinds of objects. TypeScript will augment the types for `doSomething` to add `doSomethingElse` in the type system in both.
54
54
55
-
-`Structural Type System` - A school of types system where the way types are compared is via the structure of
55
+
*`Structural Type System` - A school of types system where the way types are compared is via the structure of
56
56
their properties.
57
57
58
58
For example:
@@ -72,7 +72,20 @@ The language service supports the common set of a typical editor operations like
72
72
These two are the exact same inside TypeScript. The basic rule for TypeScript’s structural type system is that
73
73
`x` is compatible with `y` if `y` has at least the same members as `x`.
74
74
75
-
*`Literal` - A literal type is a type that only has a single value, e.g. `true`, `1`, `"abc"`, `undefined`.
75
+
*`Laziness` To support language services that respond interactively, the compiler is lazy: it does not calculate any information until it is required.
76
+
This allows it to respond quickly when the language service requests the type of a variable or its members.
77
+
Unfortunately, laziness also makes the compiler code more complicated.
78
+
79
+
As an overview, after parsing is complete, the binder does nothing but identify symbols.
80
+
The checker then waits until a particular symbol is requested to calculate type information, etc.
81
+
82
+
*`Immutability` - Each phase of the compiler (parser, binder, etc -- see below for details) treats data structures from the previous phases as immutable.
83
+
In addition, data structures created within each phase are not usually modified after their creation.
84
+
This requires a look-aside table in some cases.
85
+
For example, because the binder only looks at one file at a time, the checker needs a merged-symbols table to track merged declarations.
86
+
It checks whether a symbol has an entry in the merged-symbols table each time before it uses a symbol.
87
+
88
+
-`Literal` - A literal type is a type that only has a single value, e.g. `true`, `1`, `"abc"`, `undefined`.
76
89
77
90
For immutable objects, TypeScript creates a literal type which is the value. For mutable objects TypeScript
78
91
uses the general type that the literal matches. See [#10676](https://github.com/Microsoft/TypeScript/pull/10676)
@@ -96,21 +109,22 @@ The language service supports the common set of a typical editor operations like
96
109
97
110
Literal types are sometimes called unit types, because they have only one ("unit") value.
98
111
99
-
-`Control Flow Analysis` - using the natural branching and execution path of code to change the types at
112
+
*`Control Flow Analysis` - using the natural branching and execution path of code to change the types at
100
113
different locations in your source code by static analysis.
101
114
102
115
```ts
103
-
typeBird= { color:string, flaps:true };
104
-
typeTiger= { color:string, stripes:true };
105
-
declareanimal: Bird|Tiger
116
+
typeBird= { color:string; flaps:true };
117
+
typeTiger= { color:string; stripes:true };
118
+
declare;
119
+
animal: Bird|Tiger;
106
120
107
121
if ("stripes"inanimal) {
108
122
// Inside here animal is only a tiger, because TS could figure out that
109
123
// the only way you could get here is when animal is a tiger and not a bird
110
124
}
111
125
```
112
126
113
-
-`Generics` - A way to have variables inside a type system.
127
+
*`Generics` - A way to have variables inside a type system.
114
128
115
129
```ts
116
130
function first(array:any[]):any {
@@ -147,7 +161,7 @@ The language service supports the common set of a typical editor operations like
147
161
first<string>(["a", "b", "c"]);
148
162
```
149
163
150
-
*`Outer type parameter` - A type parameter declared in a parent generic construct:
164
+
-`Outer type parameter` - A type parameter declared in a parent generic construct:
151
165
152
166
```ts
153
167
classParent<T> {
@@ -158,7 +172,7 @@ The language service supports the common set of a typical editor operations like
158
172
}
159
173
```
160
174
161
-
*`Narrowing` - Taking a union of types and reducing it to fewer options.
175
+
-`Narrowing` - Taking a union of types and reducing it to fewer options.
162
176
163
177
A great case is when using `--strictNullCheck` when using control flow analysis
164
178
@@ -174,7 +188,7 @@ The language service supports the common set of a typical editor operations like
174
188
}
175
189
```
176
190
177
-
-`Expanding` - The opposite of narrowing, taking a type and converting it to have more potential values.
191
+
*`Expanding` - The opposite of narrowing, taking a type and converting it to have more potential values.
0 commit comments