0
# Type Translation
1

2
The type translation system converts TypeScript type annotations into Closure Compiler-compatible JSDoc type expressions, enabling full type information preservation through the compilation process.
3

4
## Capabilities
5

6
### TypeTranslator Class
7

8
Core class responsible for translating TypeScript types to Closure Compiler format.
9

10
```typescript { .api }
11
/**
12
 * Translates TypeScript types to Closure Compiler types
13
 */
14
class TypeTranslator {
15
  /** Whether translation is for externs */
16
  readonly isForExterns: boolean;
17
  
18
  constructor(
19
    host: AnnotatorHost, 
20
    typeChecker: ts.TypeChecker,
21
    node: ts.Node, 
22
    pathUnknownSymbolsSet: Set<string>,
23
    symbolsToAliasedNames: Map<ts.Symbol, string>,
24
    symbolToNameCache: Map<ts.Symbol, string>,
25
    ensureSymbolDeclared?: (sym: ts.Symbol) => void
26
  );
27
  
28
  /** Converts symbol to string representation */
29
  symbolToString(sym: ts.Symbol): string | undefined;
30
  /** Translates type to Closure format */
31
  translate(type: ts.Type): string;
32
  /** Checks if symbol is always unknown */
33
  isAlwaysUnknownSymbol(symbol: ts.Symbol): boolean;
34
  /** Marks type parameter as unknown */
35
  markTypeParameterAsUnknown(symbol: ts.Symbol): void;
36
}
37
```
38

39
**Usage Example:**
40

41
```typescript
42
import { TypeTranslator } from "tsickle";
43

44
const translator = new TypeTranslator(host, typeChecker, node);
45
const closureType = translator.translate(tsType);
46
// Result: "!Array<string>" for TypeScript "string[]"
47
```
48

49
### Module Type Translator
50

51
Specialized translator for handling types within module scope, managing import aliases and dependencies.
52

53
```typescript { .api }
54
/**
55
 * Translates types within module scope for JSDoc generation
56
 */
57
class ModuleTypeTranslator {
58
  readonly symbolsToAliasedNames: Map<ts.Symbol, string>;
59
  readonly sourceFile: ts.SourceFile;
60
  readonly typeChecker: ts.TypeChecker;
61
  
62
  constructor(
63
    sourceFile: ts.SourceFile,
64
    typeChecker: ts.TypeChecker,
65
    host: AnnotatorHost,
66
    diagnostics: ts.Diagnostic[],
67
    isForExterns: boolean
68
  );
69
  
70
  /** Converts type to Closure format */
71
  typeToClosure(context: ts.Node, type?: ts.Type): string;
72
  /** Creates new type translator */
73
  newTypeTranslator(context: ts.Node): TypeTranslator;
74
  /** Checks if symbol is unknown */
75
  isAlwaysUnknownSymbol(symbol: ts.Symbol): boolean;
76
  /** Requires and translates type */
77
  requireType(context: ts.Node, type: ts.Type): string;
78
}
79
```
80

81
### Type Validation Functions
82

83
Utility functions for validating and checking type properties.
84

85
```typescript { .api }
86
/**
87
 * Validates Closure property names
88
 */
89
function isValidClosurePropertyName(name: string): boolean;
90

91
/**
92
 * Checks if symbol is declared in builtin lib.d.ts
93
 */
94
function isDeclaredInBuiltinLibDTS(node: ts.Node): boolean;
95

96
/**
97
 * Checks if type/value conflict is handled
98
 */
99
function typeValueConflictHandled(sym: ts.Symbol): boolean;
100

101
/**
102
 * Checks if symbol is always unknown
103
 */
104
function isAlwaysUnknownSymbol(pathSet: Set<string>, symbol: ts.Symbol): boolean;
105

106
/**
107
 * Extracts rest parameter type
108
 */
109
function restParameterType(typeChecker: ts.TypeChecker, type: ts.Type): ts.Type | undefined;
110
```
111

112
### Debug Utilities
113

114
Functions for debugging type translation issues.
115

116
```typescript { .api }
117
/**
118
 * Converts type to debug string
119
 */
120
function typeToDebugString(type: ts.Type): string;
121

122
/**
123
 * Converts symbol to debug string
124
 */
125
function symbolToDebugString(sym: ts.Symbol): string;
126
```
127

128
## Type Mapping Examples
129

130
### Primitive Types
131

132
```typescript
133
// TypeScript -> Closure
134
string        -> string
135
number        -> number  
136
boolean       -> boolean
137
void          -> void
138
null          -> null
139
undefined     -> undefined
140
any           -> ?
141
unknown       -> ?
142
```
143

144
### Complex Types
145

146
```typescript
147
// Arrays
148
string[]           -> !Array<string>
149
Array<number>      -> !Array<number>
150
ReadonlyArray<T>   -> !Array<T>
151

152
// Objects
153
{x: number}        -> {x: number}
154
Record<string, T>  -> !Object<string, T>
155

156
// Functions
157
(x: string) => number     -> function(string): number
158
(...args: string[]) => T  -> function(...string): T
159

160
// Unions
161
string | number    -> (string|number)
162
T | null          -> ?T
163
T | undefined     -> (T|undefined)
164

165
// Generics
166
Promise<T>        -> !Promise<T>
167
Map<K, V>         -> !Map<K, V>
168
```
169

170
### Special Cases
171

172
```typescript
173
// Optional parameters
174
(x?: string) => void     -> function(string=): void
175

176
// Rest parameters
177
(...items: T[]) => void  -> function(...T): void
178

179
// Type assertions preserved in specific contexts
180
value as Type            -> /** @type {Type} */ (value)
181
```
182

183
## Configuration
184

185
The type translator behavior can be configured through the AnnotatorHost:
186

187
```typescript { .api }
188
interface AnnotatorHost {
189
  /** Whether to generate untyped output */
190
  untyped?: boolean;
191
  /** Paths to exclude from type transformation */
192
  typeBlackListPaths?: Set<string>;
193
  /** Paths with unknown types */
194
  unknownTypesPaths?: Set<string>;
195
  /** Enable automatic property quoting */
196
  enableAutoQuoting?: boolean;
197
}
198
```
199

200
**Configuration Example:**
201

202
```typescript
203
const host: AnnotatorHost = {
204
  pathToModuleName: (context, importPath) => importPath,
205
  untyped: false, // Generate full type annotations
206
  typeBlackListPaths: new Set(['/node_modules/']), // Skip type checking for node_modules
207
  unknownTypesPaths: new Set(['/legacy/']), // Treat legacy code as unknown types
208
  enableAutoQuoting: true // Automatically quote invalid property names
209
};
210
```
211

212
## JSDoc Integration
213

214
### Mutable JSDoc
215

216
Helper class for managing JSDoc comments during type translation.
217

218
```typescript { .api }
219
/**
220
 * Encapsulates mutable JSDoc comment
221
 */
222
class MutableJSDoc {
223
  constructor(node: ts.Node, sourceComment: ts.SynthesizedComment | null, tags: Tag[]);
224
  /** Updates comment, optionally escaping extra tags */
225
  updateComment(escapeExtraTags?: Set<string>): void;
226
}
227
```
228

229
Type translation integrates directly with JSDoc generation, automatically inserting proper type annotations:
230

231
```typescript
232
// Before transformation (TypeScript)
233
function processUser(user: User): Promise<ProcessedUser> {
234
  return Promise.resolve(transformUser(user));
235
}
236

237
// After transformation (with JSDoc)
238
/**
239
 * @param {!User} user
240
 * @return {!Promise<!ProcessedUser>}
241
 */
242
function processUser(user) {
243
  return Promise.resolve(transformUser(user));
244
}
245
```