0
# Error Handling
1

2
Comprehensive error handling system in tsify for TypeScript compilation diagnostics and runtime errors.
3

4
## Capabilities
5

6
### CompileError Class
7

8
Specialized error class for TypeScript compilation errors with detailed diagnostic information.
9

10
```javascript { .api }
11
/**
12
 * TypeScript compilation error with detailed diagnostics
13
 * Extends SyntaxError to provide TypeScript-specific error information
14
 */
15
class CompileError extends SyntaxError {
16
  /** File name where the error occurred */
17
  fileName?: string;
18
  
19
  /** Line number where the error occurred (1-based) */
20
  line?: number;
21
  
22
  /** Column number where the error occurred (1-based) */
23
  column?: number;
24
  
25
  /** Error name - always "TypeScript error" */
26
  name: string;
27
  
28
  /** Formatted error message with location and details */
29
  message: string;
30
}
31
```
32

33
**Error Message Format:**
34
```
35
filename.ts(line,column): category TS#### error message
36
```
37

38
### Error Categories
39

40
TypeScript diagnostic errors are categorized by severity:
41

42
```javascript { .api }
43
/** TypeScript diagnostic categories */
44
enum DiagnosticCategory {
45
  Warning = 0,
46
  Error = 1,
47
  Suggestion = 2,
48
  Message = 3
49
}
50
```
51

52
### Error Types
53

54
**Syntax Errors:**
55
- TypeScript parsing and syntax validation errors
56
- Emitted during initial compilation phase
57
- Always fatal - prevent code generation
58

59
**Semantic Errors:**
60
- Type checking and semantic analysis errors
61
- Emitted after syntax validation passes
62
- May be non-fatal depending on `noEmitOnError` setting
63

64
**Emit Errors:**
65
- Code generation and output errors
66
- Occur during JavaScript output phase
67

68
### Error Handling Patterns
69

70
**Basic Error Handling:**
71
```javascript
72
const browserify = require('browserify');
73
const tsify = require('tsify');
74

75
browserify()
76
  .add('main.ts')
77
  .plugin(tsify, { strict: true })
78
  .bundle()
79
  .on('error', function(error) {
80
    console.error('Compilation failed:', error.message);
81
    
82
    // Check if it's a TypeScript compilation error
83
    if (error.fileName) {
84
      console.error(`File: ${error.fileName}`);
85
      console.error(`Location: ${error.line}:${error.column}`);
86
    }
87
  })
88
  .pipe(process.stdout);
89
```
90

91
**Detailed Error Information:**
92
```javascript
93
browserify()
94
  .add('main.ts')
95
  .plugin(tsify)
96
  .bundle()
97
  .on('error', function(error) {
98
    if (error instanceof Error) {
99
      console.error('Error Name:', error.name);
100
      console.error('Error Message:', error.message);
101
      
102
      // TypeScript-specific properties
103
      if (error.fileName) {
104
        console.error('File:', error.fileName);
105
        console.error('Line:', error.line);
106
        console.error('Column:', error.column);
107
      }
108
      
109
      // Stack trace for debugging
110
      console.error('Stack:', error.stack);
111
    }
112
  });
113
```
114

115
**Graceful Error Recovery:**
116
```javascript
117
function buildWithErrorRecovery() {
118
  return new Promise((resolve, reject) => {
119
    let hasErrors = false;
120
    
121
    const bundle = browserify()
122
      .add('src/main.ts')
123
      .plugin(tsify, { 
124
        noEmitOnError: false  // Continue bundling despite type errors
125
      })
126
      .bundle();
127
    
128
    bundle.on('error', function(error) {
129
      hasErrors = true;
130
      console.warn('TypeScript error (continuing):', error.message);
131
    });
132
    
133
    let output = '';
134
    bundle.on('data', chunk => output += chunk);
135
    bundle.on('end', () => {
136
      if (hasErrors) {
137
        console.warn('Bundle completed with TypeScript errors');
138
      }
139
      resolve(output);
140
    });
141
  });
142
}
143
```
144

145
### Error Configuration
146

147
**Stop on Error (Default):**
148
```javascript
149
browserify()
150
  .add('main.ts')
151
  .plugin(tsify, {
152
    noEmitOnError: true  // Stop compilation on any error
153
  })
154
  .bundle();
155
```
156

157
**Continue on Error:**
158
```javascript
159
browserify()
160
  .add('main.ts')
161
  .plugin(tsify, {
162
    noEmitOnError: false  // Generate output despite errors
163
  })
164
  .bundle();
165
```
166

167
### Common Error Scenarios
168

169
**Missing Type Definitions:**
170
```javascript
171
// Error: Cannot find module 'some-library' or its corresponding type declarations
172
browserify()
173
  .add('main.ts')
174
  .plugin(tsify, {
175
    skipLibCheck: true  // Skip type checking for .d.ts files
176
  })
177
  .bundle();
178
```
179

180
**Module Resolution Errors:**
181
```javascript
182
// Error: Cannot resolve module 'src/utils'
183
browserify()
184
  .add('main.ts')
185
  .plugin(tsify, {
186
    baseUrl: './src',
187
    paths: {
188
      '@utils/*': ['utils/*']
189
    }
190
  })
191
  .bundle();
192
```
193

194
**Strict Mode Errors:**
195
```javascript
196
// Error: Parameter 'x' implicitly has an 'any' type
197
browserify()
198
  .add('main.ts')
199
  .plugin(tsify, {
200
    noImplicitAny: false,  // Allow implicit any
201
    strict: false          // Disable all strict checks
202
  })
203
  .bundle();
204
```
205

206
### Error Event Handling
207

208
tsify emits errors through Browserify's standard error system:
209

210
```javascript { .api }
211
/**
212
 * Error events emitted by tsify:
213
 * 
214
 * 'error' - Compilation errors (syntax, semantic, emit)
215
 * - Includes CompileError instances with diagnostic information
216
 * - Emitted for each error encountered during compilation
217
 * 
218
 * Error handling occurs at multiple levels:
219
 * 1. Tsifier level - Internal compilation errors
220
 * 2. Plugin level - Integration errors with Browserify
221
 * 3. Bundle level - Stream and bundling errors
222
 */
223
```
224

225
### Watchify Error Handling
226

227
When using with watchify for incremental compilation:
228

229
```javascript
230
const watchify = require('watchify');
231

232
const b = browserify({
233
  entries: ['src/main.ts'],
234
  cache: {},
235
  packageCache: {},
236
  plugin: [watchify]
237
});
238

239
b.plugin(tsify);
240

241
b.on('update', bundle);
242
b.on('log', console.log);
243

244
function bundle() {
245
  const stream = b.bundle();
246
  
247
  stream.on('error', function(error) {
248
    // Handle compilation errors without stopping watch
249
    console.error('TypeScript Error:', error.message);
250
    
251
    // Emit end event to continue watching
252
    stream.emit('end');
253
  });
254
  
255
  return stream.pipe(process.stdout);
256
}
257

258
bundle();
259
```
260

261
### Debug Information
262

263
Enable debug logging for detailed error context:
264

265
```bash
266
# Enable tsify debug logging
267
DEBUG=tsify* browserify main.ts -p tsify > bundle.js
268

269
# Enable tsify trace logging
270
DEBUG=tsify*,tsify-trace* browserify main.ts -p tsify > bundle.js
271
```
272

273
## Types
274

275
```typescript { .api }
276
interface ErrorContext {
277
  /** TypeScript diagnostic object */
278
  diagnostic: any;
279
  /** File where error occurred */
280
  fileName?: string;
281
  /** Error location */
282
  location?: {
283
    line: number;
284
    column: number;
285
  };
286
  /** Error category */
287
  category: 'Warning' | 'Error' | 'Suggestion' | 'Message';
288
  /** TypeScript error code */
289
  code: number;
290
  /** Error message text */
291
  messageText: string;
292
}
293

294
interface ErrorHandlingOptions {
295
  /** Stop compilation on first error */
296
  noEmitOnError?: boolean;
297
  /** Skip type checking of .d.ts files */
298
  skipLibCheck?: boolean;
299
  /** Allow implicit any types */
300
  noImplicitAny?: boolean;
301
  /** Enable all strict type checking options */
302
  strict?: boolean;
303
}
304
```