0
# Parcel TypeScript Types Transformer
1

2
A Parcel transformer plugin that processes TypeScript files to generate optimized TypeScript declaration files (.d.ts). The transformer uses the TypeScript compiler API to build module dependency graphs, perform tree-shaking on type definitions, and generate minimal declaration files with only necessary type information.
3

4
## Package Information
5

6
- **Package Name**: @parcel/transformer-typescript-types
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow type annotations
9
- **Installation**: `npm install @parcel/transformer-typescript-types`
10
- **Node.js**: >= 16.0.0
11
- **Peer Dependencies**: TypeScript >= 3.0.0
12

13
## Core Imports
14

15
```javascript
16
// This is a Parcel plugin - import and usage is handled by Parcel's plugin system
17
// Direct usage typically occurs through Parcel configuration or programmatic API
18
const TSTypesTransformer = require("@parcel/transformer-typescript-types");
19
```
20

21
For TypeScript:
22

23
```typescript
24
import TSTypesTransformer from "@parcel/transformer-typescript-types";
25
```
26

27
## Basic Usage
28

29
This transformer is designed to be used within the Parcel build system as a plugin. It cannot be used standalone and requires integration with Parcel's plugin architecture.
30

31
```javascript
32
// Parcel automatically loads and uses this transformer for TypeScript files
33
// when configured in .parcelrc or package.json
34

35
// Example .parcelrc configuration for declaration generation
36
{
37
  "extends": "@parcel/config-default",
38
  "transformers": {
39
    "*.ts": ["@parcel/transformer-typescript-types"],
40
    "*.tsx": ["@parcel/transformer-typescript-types"]
41
  }
42
}
43

44
// Alternative package.json configuration
45
{
46
  "name": "my-package",
47
  "@parcel/transformer-typescript-types": {
48
    "validateTS": true,
49
    "isolatedModules": false
50
  },
51
  "targets": {
52
    "types": {
53
      "source": "src/index.ts",
54
      "distDir": "dist",
55
      "includeNodeModules": false
56
    }
57
  }
58
}
59

60
// Programmatic usage with Parcel API
61
import { Parcel } from '@parcel/core';
62

63
const bundler = new Parcel({
64
  entries: 'src/index.ts',
65
  defaultConfig: '@parcel/config-default',
66
  targets: {
67
    types: {
68
      distDir: 'types',
69
      includeNodeModules: false
70
    }
71
  }
72
});
73

74
const { bundleGraph } = await bundler.run();
75
```
76

77
## Architecture
78

79
The transformer operates through a two-phase TypeScript compiler transformation process:
80

81
- **Collection Phase**: Builds a complete module dependency graph from TypeScript source files, tracking imports, exports, and local bindings
82
- **Tree-shaking Phase**: Removes unused type definitions and renames symbols to avoid conflicts while preserving necessary type information
83
- **Module Graph System**: Manages dependencies between TypeScript modules for optimal type resolution
84
- **TypeScript Integration**: Uses TypeScript compiler API with custom transforms for advanced AST manipulation
85
- **Source Map Support**: Generates source maps for debugging declaration files
86

87
## Capabilities
88

89
### TypeScript Transformer
90

91
Main transformer that processes TypeScript source files to generate optimized declaration files with tree-shaking and module graph optimization.
92

93
```javascript { .api }
94
/**
95
 * Main Parcel transformer instance for processing TypeScript files
96
 */
97
const TSTypesTransformer: {
98
  loadConfig(config: any, options: any): Promise<any>;
99
  transform(asset: any, config: any, options: any, logger: any): Promise<any[]>;
100
};
101
```
102

103
[TypeScript Transformer](./transformer.md)
104

105
### Module Graph Management
106

107
System for tracking and managing dependencies between TypeScript modules, enabling efficient tree-shaking and symbol resolution.
108

109
```javascript { .api }
110
/**
111
 * Manages dependency graph between TypeScript modules
112
 */
113
class TSModuleGraph {
114
  constructor(mainModuleName: string);
115
  addModule(name: string, module: TSModule): void;
116
  getModule(name: string): TSModule | null;
117
  markUsed(module: TSModule, name: string, context: any): void;
118
  propagate(context: any): Map<string, TSModule>;
119
}
120

121
/**
122
 * Represents a single TypeScript module with imports, exports, and bindings
123
 */
124
class TSModule {
125
  constructor();
126
  addImport(local: string, specifier: string, imported: string): void;
127
  addExport(name: string, imported: string, specifier?: string): void;
128
  addLocal(name: string, node: any): void;
129
  getName(name: string): string;
130
  hasBinding(name: string): boolean;
131
}
132
```
133

134
[Module Graph](./module-graph.md)
135

136
### AST Processing
137

138
TypeScript compiler transforms for collecting module information and performing tree-shaking operations.
139

140
```javascript { .api }
141
/**
142
 * Collects module graph information from TypeScript AST
143
 */
144
function collect(
145
  moduleGraph: TSModuleGraph,
146
  context: any,
147
  sourceFile: any
148
): any;
149

150
/**
151
 * Performs tree-shaking and symbol renaming on TypeScript AST
152
 */
153
function shake(
154
  moduleGraph: TSModuleGraph,
155
  context: any,
156
  sourceFile: any
157
): any;
158
```
159

160
[AST Processing](./ast-processing.md)
161

162
### TypeScript Version Compatibility
163

164
Cross-version compatibility wrappers for TypeScript compiler API functions, ensuring consistent behavior across different TypeScript versions.
165

166
```javascript { .api }
167
/**
168
 * Cross-version wrapper for creating import clauses
169
 */
170
function createImportClause(
171
  factory: any,
172
  isTypeOnly: boolean,
173
  name: any,
174
  namedBindings: any
175
): any;
176

177
/**
178
 * Cross-version wrapper for creating import declarations
179
 */
180
function createImportDeclaration(
181
  factory: any,
182
  modifiers: any,
183
  importClause: any,
184
  moduleSpecifier: any,
185
  assertClause: any
186
): any;
187
```
188

189
[TypeScript Compatibility](./ts-compatibility.md)
190

191
## Types
192

193
```javascript { .api }
194
/**
195
 * Represents an import statement in a TypeScript module
196
 */
197
type Import = {
198
  specifier: string;  // Module path (e.g., './components', 'react')
199
  imported: string;   // Imported symbol name ('default', '*', or named export)
200
};
201

202
/**
203
 * Represents an export statement in a TypeScript module
204
 * Either a named export (possibly re-exported) or a wildcard export
205
 */
206
type Export = 
207
  | { 
208
      name: string;           // Export name in current module
209
      imported: string;       // Symbol name being exported
210
      specifier?: string;     // Re-export source module (optional)
211
    }
212
  | { 
213
      specifier: string;      // Wildcard export source (export * from 'module')
214
    };
215

216
/**
217
 * TypeScript transform context provided by the compiler
218
 * Contains factory methods and compilation state
219
 */
220
interface TransformContext {
221
  factory?: any;                              // TypeScript node factory (TS 4.0+)
222
  suspendLexicalEnvironment?(): void;         // Suspend lexical tracking
223
  resumeLexicalEnvironment?(): void;          // Resume lexical tracking
224
  getCompilerOptions(): any;                  // Get compiler configuration
225
  [key: string]: any;                         // Additional context properties
226
}
227

228
/**
229
 * TypeScript AST node types commonly used by the transformer
230
 */
231
interface TypeScriptASTNodes {
232
  SourceFile: any;                           // Root AST node for a TypeScript file
233
  ImportDeclaration: any;                    // import statement
234
  ExportDeclaration: any;                    // export statement
235
  ImportClause: any;                         // import clause with bindings
236
  ImportSpecifier: any;                      // named import specifier
237
  ModuleDeclaration: any;                    // module or namespace declaration
238
  FunctionDeclaration: any;                  // function declaration
239
  ClassDeclaration: any;                     // class declaration
240
  InterfaceDeclaration: any;                 // interface declaration
241
  TypeAliasDeclaration: any;                 // type alias declaration
242
  EnumDeclaration: any;                      // enum declaration
243
  VariableStatement: any;                    // variable statement (const, let, var)
244
  ImportTypeNode: any;                       // import() type node
245
  QualifiedName: any;                        // qualified name (namespace.Type)
246
  Identifier: any;                           // identifier node
247
}
248

249
/**
250
 * Diagnostic information for TypeScript compilation errors
251
 */
252
interface TypeScriptDiagnostic {
253
  messageText: string | any;                 // Error message or message chain
254
  file?: any;                                // Source file with error
255
  start?: number;                            // Error start position
256
  length?: number;                           // Error length
257
  source?: string;                           // Source code text
258
}
259
```