0
# TypeScript Version Compatibility
1

2
Cross-version compatibility wrappers for TypeScript compiler API functions, ensuring consistent behavior across different TypeScript versions (3.0+).
3

4
## Capabilities
5

6
### Import Declaration Creation
7

8
Version-compatible wrappers for creating import-related AST nodes that work across different TypeScript compiler versions.
9

10
```javascript { .api }
11
/**
12
 * Creates an import clause with version compatibility
13
 * @param factory - TypeScript node factory (or ts for older versions)
14
 * @param isTypeOnly - Whether this is a type-only import
15
 * @param name - Default import identifier (optional)
16
 * @param namedBindings - Named import bindings (optional)
17
 * @returns ImportClause AST node
18
 */
19
function createImportClause(
20
  factory: any,
21
  isTypeOnly: boolean,
22
  name: any,
23
  namedBindings: any
24
): any;
25

26
/**
27
 * Creates an import declaration with version compatibility
28
 * @param factory - TypeScript node factory (or ts for older versions)
29
 * @param modifiers - Declaration modifiers (optional)
30
 * @param importClause - Import clause (optional)
31
 * @param moduleSpecifier - Module path expression
32
 * @param assertClause - Import assertion clause (optional)
33
 * @returns ImportDeclaration AST node
34
 */
35
function createImportDeclaration(
36
  factory: any,
37
  modifiers: any,
38
  importClause: any,
39
  moduleSpecifier: any,
40
  assertClause: any
41
): any;
42

43
/**
44
 * Creates an import specifier with version compatibility
45
 * @param factory - TypeScript node factory (or ts for older versions)
46
 * @param isTypeOnly - Whether this is a type-only import specifier
47
 * @param propertyName - Original name in source module (optional)
48
 * @param name - Local binding name
49
 * @returns ImportSpecifier AST node
50
 */
51
function createImportSpecifier(
52
  factory: any,
53
  isTypeOnly: boolean,
54
  propertyName: any,
55
  name: any
56
): any;
57
```
58

59
### Export Declaration Updates
60

61
Version-compatible wrapper for updating export declarations across TypeScript versions.
62

63
```javascript { .api }
64
/**
65
 * Updates an export declaration with version compatibility
66
 * @param factory - TypeScript node factory (or ts for older versions)
67
 * @param node - Original export declaration to update
68
 * @param modifiers - Declaration modifiers (optional)
69
 * @param isTypeOnly - Whether this is a type-only export
70
 * @param exportClause - Named export bindings (optional)
71
 * @param moduleSpecifier - Re-export module path (optional)
72
 * @param assertClause - Export assertion clause (optional)
73
 * @returns Updated ExportDeclaration AST node
74
 */
75
function updateExportDeclaration(
76
  factory: any,
77
  node: any,
78
  modifiers: any,
79
  isTypeOnly: boolean,
80
  exportClause: any,
81
  moduleSpecifier: any,
82
  assertClause: any
83
): any;
84
```
85

86
## TypeScript Version Support
87

88
### Version Detection
89

90
The compatibility system detects TypeScript version at runtime:
91

92
```javascript
93
const [majorVersion, minorVersion] = ts.versionMajorMinor
94
  .split('.')
95
  .map(num => parseInt(num, 10));
96
```
97

98
### Supported Version Ranges
99

100
Each wrapper function supports specific TypeScript version ranges:
101

102
#### createImportClause Support
103

104
- **TypeScript 4.0+**: `factory.createImportClause(isTypeOnly, name, namedBindings)`
105
- **TypeScript 3.8+**: `factory.createImportClause(name, namedBindings, isTypeOnly)`
106
- **TypeScript 3.0+**: `factory.createImportClause(name, namedBindings)` (no type-only support)
107

108
#### createImportDeclaration Support
109

110
- **TypeScript 4.8+**: `factory.createImportDeclaration(modifiers, importClause, moduleSpecifier, assertClause)`
111
- **TypeScript 4.5+**: `factory.createImportDeclaration(undefined, modifiers, importClause, moduleSpecifier, assertClause)`
112
- **TypeScript 3.0+**: `factory.createImportDeclaration(undefined, modifiers, importClause, moduleSpecifier)`
113

114
#### createImportSpecifier Support
115

116
- **TypeScript 4.5+**: `factory.createImportSpecifier(isTypeOnly, propertyName, name)`
117
- **TypeScript 3.0+**: `factory.createImportSpecifier(propertyName, name)` (no type-only support)
118

119
#### updateExportDeclaration Support
120

121
- **TypeScript 4.8+**: Full support for all parameters including assertion clauses
122
- **TypeScript 4.5+**: Support without assertion clauses but with decorators parameter
123
- **TypeScript 4.0+**: Support with type-only exports
124
- **TypeScript 3.8+**: Basic support with different parameter order
125
- **TypeScript 3.0+**: Basic support without type-only exports
126

127
## Usage Examples
128

129
### Generating Import Statements
130

131
```javascript
132
import { 
133
  createImportClause, 
134
  createImportDeclaration, 
135
  createImportSpecifier 
136
} from '@parcel/transformer-typescript-types';
137

138
// Create named import: import { Button, Dialog } from 'components'
139
const importSpecifiers = [
140
  createImportSpecifier(factory, false, undefined, factory.createIdentifier('Button')),
141
  createImportSpecifier(factory, false, undefined, factory.createIdentifier('Dialog'))
142
];
143

144
const importClause = createImportClause(
145
  factory,
146
  false, // not type-only
147
  undefined, // no default import
148
  factory.createNamedImports(importSpecifiers)
149
);
150

151
const importDeclaration = createImportDeclaration(
152
  factory,
153
  undefined, // no modifiers
154
  importClause,
155
  factory.createStringLiteral('components'),
156
  undefined // no assertions
157
);
158
```
159

160
### Updating Export Statements
161

162
```javascript
163
import { updateExportDeclaration } from '@parcel/transformer-typescript-types';
164

165
// Update export to remove unused exports
166
const updatedExport = updateExportDeclaration(
167
  factory,
168
  originalExportNode,
169
  undefined, // modifiers
170
  false, // not type-only
171
  factory.createNamedExports(filteredExports), // only keep used exports
172
  undefined, // no module specifier
173
  undefined // no assertions
174
);
175
```
176

177
## Implementation Details
178

179
### Backward Compatibility Strategy
180

181
The wrappers use a cascade approach to handle version differences:
182

183
1. **Feature Detection**: Check TypeScript version for feature availability
184
2. **Parameter Mapping**: Map new parameter patterns to older API signatures
185
3. **Graceful Degradation**: Fall back to simpler APIs when advanced features aren't available
186
4. **Error Handling**: Throw assertion errors for unsupported versions
187

188
### Factory vs Global API
189

190
The system handles both the modern factory-based API (TypeScript 4.0+) and the older global `ts` API:
191

192
```javascript
193
// Modern factory API (preferred)
194
const node = factory.createImportClause(isTypeOnly, name, namedBindings);
195

196
// Legacy global API (fallback)
197
const node = ts.createImportClause(name, namedBindings);
198
```
199

200
### Type-Only Import Evolution
201

202
The handling of type-only imports evolved across TypeScript versions:
203

204
- **TypeScript 3.8+**: Introduced type-only imports with `import type` syntax
205
- **TypeScript 4.5+**: Added type-only import specifiers
206
- **Earlier versions**: No type-only support, parameters ignored
207

208
This ensures the transformer can generate appropriate import statements regardless of the TypeScript version in use.